workbench user guide - actiandownloads.actian.com/online/docs/openroad/openroad2006/or_u… · iv...

Ingres OpenROAD® 2006

OR-2006-UG-02

Workbench User Guide

This documentation and related computer software program (hereinafter referred to as the "Documentation") is for the end user's informational purposes only and is subject to change or withdrawal by Ingres Corporation ("Ingres") at any time.

This Documentation may not be copied, transferred, reproduced, disclosed or duplicated, in whole or in part, without the prior written consent of Ingres. This Documentation is proprietary information of Ingres and protected by the copyright laws of the United States and international treaties.

Notwithstanding the foregoing, licensed users may print a reasonable number of copies of this Documentation for their own internal use, provided that all Ingres copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the confidentiality provisions of the license for the software are permitted to have access to such copies.

This right to print copies is limited to the period during which the license for the product remains in full force and effect. The user consents to Ingres obtaining injunctive relief precluding any unauthorized use of the Documentation. Should the license terminate for any reason, it shall be the user's responsibility to return to Ingres the reproduced copies or to certify to Ingres that same have been destroyed.

To the extent permitted by applicable law, INGRES PROVIDES THIS DOCUMENTATION "AS IS" WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. IN NO EVENT WILL INGRES BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USER OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF INGRES IS EXPRESSLY ADVISED OF SUCH LOSS OR DAMAGE.

The use of any product referenced in this Documentation and this Documentation is governed by the end user's applicable license agreement.

The manufacturer of this Documentation is Ingres Corporation.

For government users, the Documentation is delivered with "Restricted Rights" as set forth in 48 C.F.R. Section 12.212, 48 C.F.R. Sections 52.227-19(c)(1) and (2) or DFARS Section 252.227-7013 or applicable successor provisions.

Copyright © 2008 Ingres Corporation. All Rights Reserved.

Ingres, OpenROAD, and EDBC are registered trademarks of Ingres Corporation. All other trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

Contents iii

Contents

Chapter 1: Introduction 17 In This Guide...................................................................................................................... 17 Installing OpenROAD ........................................................................................................... 18 Intended Audience .............................................................................................................. 18 Documentation ................................................................................................................... 18

Chapter 2: Structuring an Application 21 Basic Application Components ............................................................................................... 21

The Basics of Frames and Forms ...................................................................................... 22 Scripts, Events, and Event Blocks..................................................................................... 23 Objects ........................................................................................................................ 24

Frames .............................................................................................................................. 24 Ghost Frames................................................................................................................ 25

4GL Statements for Running Frames Concurrently.................................................................... 25 How an Application Moves Between Frames............................................................................. 26 Procedures ......................................................................................................................... 26

4GL Procedures ............................................................................................................. 27 3GL Procedures ............................................................................................................. 27 Database Procedures...................................................................................................... 27

How You Can Share Information Between Frames .................................................................... 27 Global Variables............................................................................................................. 28 Global Constants............................................................................................................ 28 User and Database Events............................................................................................... 28

Scope of Frames, Procedures, Variables, and Constants ............................................................ 29 External Code: Database, 3GL Procedures, and External Class Objects .................................. 29 4GL Procedures ............................................................................................................. 29

How You Can Change Global Constants at Runtime .................................................................. 30 Controlling the Flow of Frames......................................................................................... 31 Choosing a Concurrency Style.......................................................................................... 32 How the Application's Starting Frame Is Opened................................................................. 32 Selecting a Control Frame Style ....................................................................................... 33 How You Can Manage Database Interactions...................................................................... 35 Selecting an Operation Style............................................................................................ 35

How You Can Share Frames Among Applications ...................................................................... 37 Included Applications Feature .......................................................................................... 37 How You Can Customize Included Frames.......................................................................... 37

iv Workbench User Guide

How You Can Enforce Consistency Throughout Your Environment ............................................... 38 Frame Templates ........................................................................................................... 38 Style Sheets.................................................................................................................. 38 Field Templates ............................................................................................................. 39

How You Can Create Non-interactive Applications..................................................................... 39

Chapter 3: Getting Started with OpenROAD Workbench 41 OpenROAD Workbench Overview ........................................................................................... 42

Connect Tab.................................................................................................................. 47 Develop Tab.................................................................................................................. 49 Debug Tab .................................................................................................................... 51 Monitor Tab .................................................................................................................. 52 Query Tab .................................................................................................................... 54 Build Tab ...................................................................................................................... 55 Deploy Tab ................................................................................................................... 56 Manage Tab .................................................................................................................. 58 Editors ......................................................................................................................... 59

How You Can Start OpenROAD Workbench.............................................................................. 61 Start OpenROAD Workbench from the Desktop................................................................... 62 How You Can Start Ingres ............................................................................................... 63 Start OpenROAD Workbench from the Windows Command Prompt........................................ 63 Start OpenROAD Workbench with the RunImage Utility ....................................................... 64 Define a Database Connection Profile................................................................................ 67 Connect to a Database Through a Connection Profile ........................................................... 70 Modify a Database Connection Profile................................................................................ 70 Delete a Database Connection Profile................................................................................ 71

How You Can Customize OpenROAD Workbench ...................................................................... 71 Customize the Workbench Window Display ........................................................................ 71 Applications Portlet ........................................................................................................ 72 Components Portlet........................................................................................................ 75

Chapter 4: Creating Applications 81 Create an Application........................................................................................................... 81

Application Properties ..................................................................................................... 82 Specify or Modify Application Properties ............................................................................ 84 How You Can Customize a Session for an Application .......................................................... 85

Included Applications ........................................................................................................... 87 How Applications Are Included ......................................................................................... 87 Default Included Application ............................................................................................ 88 Additional OpenROAD Applications.................................................................................... 88 Specify Included Applications........................................................................................... 89

Contents v

Application Component Development ..................................................................................... 90 Create a Component ...................................................................................................... 90 Component Types .......................................................................................................... 91

How You Can Work with Applications and Components.............................................................. 95 How You Can Edit an Application or Component.................................................................. 96 Find an Application or Component .................................................................................... 99 Rename Applications and Components ............................................................................ 101 Delete Applications and Components .............................................................................. 102

Run Applications ............................................................................................................... 103 Run a Single Application ............................................................................................... 103 Run Multiple Applications .............................................................................................. 104

Chapter 5: Creating Basic Frames 105 How You Can Create Basic Frames ....................................................................................... 105

Create an Empty Frame ................................................................................................ 107 Create a Dialog............................................................................................................ 108 Create a Menu Frame ................................................................................................... 108

Frame Editor..................................................................................................................... 109 Open an Existing Frame................................................................................................ 111 Field Palette ................................................................................................................ 111 Display the Form Grid................................................................................................... 133 Property Inspector ....................................................................................................... 135 Field Tree ................................................................................................................... 141

Alternative Methods for Creating Frames............................................................................... 142 Create Your Own Frame Templates................................................................................. 142 How You Can Set Frame Template Properties ................................................................... 144 Create a Frame Based on Your Own Frame Template ........................................................ 144 Edit Frame Templates................................................................................................... 146

How You Can View and Modify Frames.................................................................................. 146 How You Can Test Frames .................................................................................................. 146

Compile a Frame ......................................................................................................... 147 Simulate a Runtime Form.............................................................................................. 148 Run a Frame ............................................................................................................... 148

Delete a Frame ................................................................................................................. 149

Chapter 6: Creating and Using Basic Fields 151 Types of Fields.................................................................................................................. 151

Shape Fields, Illustrated ............................................................................................... 152 Scalar Fields, Illustrated ............................................................................................... 152 Composite Fields, Illustrated.......................................................................................... 153

vi Workbench User Guide

How You Can Add Fields to a Frame ..................................................................................... 154 Position Fields ............................................................................................................. 155 Create Multiple Fields ................................................................................................... 156 How You Can Select Fields ............................................................................................ 157 How You Can Work with Overlapping Fields ..................................................................... 160 How You Can Work with the Shape Layer ........................................................................ 160 Move and Resize Fields ................................................................................................. 161 Copy and Paste a Field.................................................................................................. 162 Align Fields ................................................................................................................. 162 Delete a Field .............................................................................................................. 163 How Rearranging Composite Fields Works ....................................................................... 164 Field Colors................................................................................................................. 164 Convert a Field to a Different Type ................................................................................. 167

Shape Fields..................................................................................................................... 167 Create a Rectangle Shape ............................................................................................. 168 Create an Ellipse Shape ................................................................................................ 169 Create a Line Segment ................................................................................................. 169

Scalar Fields ..................................................................................................................... 170 Field Naming............................................................................................................... 171 Trim Fields.................................................................................................................. 171 Create a Box Trim........................................................................................................ 171 Create a Free Trim ....................................................................................................... 173 Image Trim................................................................................................................. 175 Bar Fields ................................................................................................................... 177 Create a Button Field.................................................................................................... 179 Image Fields ............................................................................................................... 180 Control Buttons ........................................................................................................... 181 Create a Pop-up Button ................................................................................................ 184 List Fields ................................................................................................................... 186 Single-line Entry Fields ................................................................................................. 189 Multiline Entry Fields .................................................................................................... 194 Option Fields ............................................................................................................... 198 Create a Palette Field ................................................................................................... 200 Create a Radio Field ..................................................................................................... 201 Create Scroll Bars ........................................................................................................ 203 Create Sliders ............................................................................................................. 205 Toggles (Check Boxes) ................................................................................................. 205 List Views ................................................................................................................... 207 Tree Views.................................................................................................................. 212

Composite Fields ............................................................................................................... 215 Create a Composite Field .............................................................................................. 216 Create a Flexible Form.................................................................................................. 216 Matrix Fields ............................................................................................................... 217

Contents vii

Stack Fields ................................................................................................................ 220 Create a Subform ........................................................................................................ 222 Table Fields................................................................................................................. 223 Viewports ................................................................................................................... 231 Create a Tab Folder...................................................................................................... 232

Common Field Properties.................................................................................................... 239 Property Descriptions ................................................................................................... 240 Field Variables............................................................................................................. 254 Fields and System Classes............................................................................................. 255 Events and Scripts ....................................................................................................... 255 Gravity....................................................................................................................... 255 Field Biases................................................................................................................. 257 How You Can Set the Focus Behavior .............................................................................. 260 How You Can Define an Alt Speed Key ............................................................................ 261 Set Multiple Selections for List Fields and Table Fields ....................................................... 264 Tab Sequencing........................................................................................................... 266 Use a Custom Cursor.................................................................................................... 268 How You Can Create or Edit a Field Script........................................................................ 270

Chapter 7: Alternative Methods for Creating Fields 271 Create a Field from a Field Template .................................................................................... 271 Field Templates................................................................................................................. 273

Create a Field Template ................................................................................................ 273 Create Fields from a Database Table .................................................................................... 275 Create Fields from a User Class ........................................................................................... 277 Create Fields from an External Class .................................................................................... 279

Chapter 8: Generating Frames from Predefined Templates 281 Include Predefined Template Packages in Your Application....................................................... 283 Frame Templates .............................................................................................................. 284 The about_box Template .................................................................................................... 285

Create an About Box Frame........................................................................................... 285 How You Can Call an About Box Frame............................................................................ 287 Test an About Box........................................................................................................ 287

The Calculator Template..................................................................................................... 287 Create a Calculator Frame............................................................................................. 288 Call a Calculator Frame................................................................................................. 289 How a Calculator Works ................................................................................................ 289

viii Workbench User Guide

The find_dialog Template ................................................................................................... 290 Create a Find Dialog Frame ........................................................................................... 291 How You Can Call a Find Dialog Frame ............................................................................ 292 How a Find Dialog Frame Is Used ................................................................................... 293

The font_dialog Template ................................................................................................... 294 Create a Font Dialog Frame ........................................................................................... 295 How You Can Call a Font Dialog Frame............................................................................ 295 How a Font Dialog Frame Is Used................................................................................... 297

The splash_screen Template ............................................................................................... 297 Create a Splash Screen Frame ....................................................................................... 298 How You Can Call a Splash Screen Frame........................................................................ 299

The text_editor Template ................................................................................................... 299 Creat a Text Editor Frame ............................................................................................. 299 How You Can Customize a Text Editor Frame ................................................................... 300 How a Text Editor Is Used ............................................................................................. 300

The financial_calculator Template ........................................................................................ 302 Create a Financial Calculator Frame................................................................................ 302 How a Financial Calculator Is Used ................................................................................. 303

The mastdetl Templates ..................................................................................................... 305 How You Can Create a Frame from a mastdetl Template.................................................... 305 The simple_field Template............................................................................................. 317 The table_field Template............................................................................................... 321 The master_detail Template .......................................................................................... 325 The detail Template...................................................................................................... 328 The explosion Template ................................................................................................ 331 Add Additional Tables to a Generated Frame .................................................................... 332

The toolbar_window Template............................................................................................. 338 Create a Toolbar Frame ................................................................................................ 339

The mclient_frame Template............................................................................................... 339

Chapter 9: Generating Fields from Predefined Templates 341 Predefined Field Templates ................................................................................................. 341 How You Can Add a Generated Field to a Frame..................................................................... 342

The analog_clock Field Template .................................................................................... 343 The bar_graph Field Template........................................................................................ 345 The calculator_control Field Template ............................................................................. 350 The calendar Field Template .......................................................................................... 351 The countdown_timer Field Template.............................................................................. 352 The date_field Field Template ........................................................................................ 353 The digital_clock Field Template..................................................................................... 354 The elapsed_timer Field Template .................................................................................. 357 The float_field Field Template ........................................................................................ 358

Contents ix

The gauge Field Template ............................................................................................. 358 The integer_field Field Template..................................................................................... 361 The line_graph Field Template ....................................................................................... 361 The meter Field Template.............................................................................................. 362 The money_field Field Template ..................................................................................... 365 The smallint_field Field Template ................................................................................... 365 The spin_control Field Template ..................................................................................... 366 The stopwatch_control Field Template............................................................................. 370 The timezone_control Field Template .............................................................................. 371 The edit_control Field Template ..................................................................................... 371 The query_bar Field Template........................................................................................ 373 The tabbed_dialog Field Template .................................................................................. 376

Chapter 10: Creating and Modifying Menus 379 Start the Menu Editor......................................................................................................... 380

Menu Editor Workspace ................................................................................................ 380 Types of Menu Items ......................................................................................................... 381

Menu Editor Tool Palette ............................................................................................... 382 How Select Mode Works................................................................................................ 383

Create a Menu .................................................................................................................. 383 How You Can Edit and Convert Menu Items ..................................................................... 384 Create Scripts for Menu Items ....................................................................................... 384 How Menu Items and Variables Work .............................................................................. 384

How You Can Create Menu Items......................................................................................... 385 Pull-down and Slide-off Menus ....................................................................................... 385 Create Menu Buttons.................................................................................................... 389 Create a Menu Toggle................................................................................................... 390 Create a Menu List ....................................................................................................... 392 Create a Menu Separator .............................................................................................. 393

Common Menu Properties................................................................................................... 393 Properties ................................................................................................................... 394 How You Can Set Menu Item Biases................................................................................ 395 How You Can Assign Speed Keys.................................................................................... 396 How You Can Set Focus Behavior ................................................................................... 396

Chapter 11: Creating Toolbars 399 Start the Toolbar Editor...................................................................................................... 399

Toolbar Editor Workspace.............................................................................................. 400 Types of Toolbar Items ...................................................................................................... 400

Insert Menu ................................................................................................................ 401 Using Select Mode........................................................................................................ 401

x Workbench User Guide

Create a Toolbar ............................................................................................................... 402 Scripts for Toolbar Items............................................................................................... 402 How You Can Edit Toolbar Items .................................................................................... 403 Toolbar Items and Variables .......................................................................................... 403

How You Can Create Toolbar Items ...................................................................................... 403 Create a Toolbar .......................................................................................................... 403 Create Toolbar Buttons ................................................................................................. 404 Use the Icon Gallery..................................................................................................... 405 Create an Option Field .................................................................................................. 407 Create a Toolbar Palette Field ........................................................................................ 408 Create a Toggle Field.................................................................................................... 409

Chapter 12: Working With Classes 411 System Classes................................................................................................................. 411

The Inheritance Hierarchy ............................................................................................. 411 User Classes..................................................................................................................... 412 External Classes................................................................................................................ 413 How You Can Create User Classes........................................................................................ 414

Create a User Class...................................................................................................... 414 Create Attributes for a User Class................................................................................... 415 Create Methods for a User Class..................................................................................... 421 Edit or View a User Class .............................................................................................. 426 Deleting a User Class.................................................................................................... 426 How You Can Use Attributes and Methods........................................................................ 427

Create and Register External Class Libraries .......................................................................... 428 Register an External Class Library Component.................................................................. 429 Edit or View an External Class Library ............................................................................. 431 Delete an External Class ............................................................................................... 431

Class Browser ................................................................................................................... 432 Open the Class Browser ................................................................................................ 432 Default Viewing Mode ................................................................................................... 432 System Classes Viewing Mode ....................................................................................... 433

Chapter 13: Writing Scripts and Procedures 435 How You Can Use Scripts.................................................................................................... 435 Script Types ..................................................................................................................... 436

Scripts for User Class Methods....................................................................................... 436 How You Can Write Frame Scripts........................................................................................ 436 How Field and Menu Scripts Work ........................................................................................ 437 How You Can Write User Class Scripts .................................................................................. 438 How You Can Write Include Scripts ...................................................................................... 438

Contents xi

Script Editor ..................................................................................................................... 438 Call the Script Editor .................................................................................................... 439 How You Can Edit Text with the Script Editor ................................................................... 439 How You Can Save or Cancel Your Script Changes ............................................................ 441 How You Can Navigate the Script Editor .......................................................................... 441

How You Can Use Your System Editor................................................................................... 442 How You Can Use Templates for II_WINDOWEDIT and II_WINDOWVIEW .................................. 443

For Windows ............................................................................................................... 444 For UNIX .................................................................................................................... 444

How Editing Multiple Scripts Works ..................................................................................... 445

Chapter 14: Adding Other Components to Your Application 447 Variable Types .................................................................................................................. 447

Ways to Create Variables .............................................................................................. 448 Create a Global Variable ..................................................................................................... 449

Global Variable Properties ............................................................................................. 450 Edit or View a Global Variable ........................................................................................ 450 Delete a Global Variable................................................................................................ 451

Macro Variables ................................................................................................................ 451 Create a Macro Variable ................................................................................................ 452 Delete Macro Variables ................................................................................................. 453

Global Constants ............................................................................................................... 454 Create a Global Constant .............................................................................................. 454 Edit or View a Global Constant ....................................................................................... 455 Delete a Global Constant............................................................................................... 455

Procedures ....................................................................................................................... 456 Create a 4GL Procedure ................................................................................................ 456 View or Edit 4GL Procedures.......................................................................................... 459 Delete a 4GL Procedure ................................................................................................ 460 How You Can Use Local 4GL Procedures .......................................................................... 461 Create and Register 3GL Procedures and Database Procedures ........................................... 461

Ghost Frames ................................................................................................................... 465 Create a Ghost Frame................................................................................................... 465 Ghost Frame Properties ................................................................................................ 466 Delete a Ghost Frame................................................................................................... 467

3GL Sample Application...................................................................................................... 467 How the 3GL Sample Application Works on Windows ......................................................... 467 How the 3GL Sample Application Works on UNIX or Linux .................................................. 469 Run the Sample Application........................................................................................... 472

xii Workbench User Guide

Chapter 15: Creating Reports in OpenROAD 473 Start OpenROAD Reporter .................................................................................................. 474 OpenROAD Reporter Window .............................................................................................. 475

OpenROAD Reporter Main Menus.................................................................................... 475 OpenROAD Reporter Toolbars ........................................................................................ 476

Report Design Techniques .................................................................................................. 478 Design Considerations .................................................................................................. 478 How You Can Format a Report Document ........................................................................ 479 Set Report Document Properties .................................................................................... 480 Create a Form Report ................................................................................................... 483 Create a Page Layout Template...................................................................................... 484 Create Tabular Reports ................................................................................................. 485

Setup/Cleanup.................................................................................................................. 493 Use Setup/Cleanup ...................................................................................................... 494

Save the Report Query and Document.................................................................................. 494 How You Can Design Report Documents ............................................................................... 496

Report Sections ........................................................................................................... 496 How You Can Select and Position Fields........................................................................... 499 Edit Menu Commands for Manipulating Fields ................................................................... 499 How You Can Create Data Fields .................................................................................... 500 How You Can Group Fields ............................................................................................ 509 Static Text Fields ......................................................................................................... 514 Edit Open API Code...................................................................................................... 515 How You Can Use Shapes & Images Fields....................................................................... 516 Special Fields .............................................................................................................. 521 Create Fields from a Page Layout Template ..................................................................... 522 Lock or Unlock Fields.................................................................................................... 523 Repeat Creation........................................................................................................... 523

Set Page Breaks................................................................................................................ 523 How You Can Enhance Report Design ................................................................................... 524

Character Formatting ................................................................................................... 524 Align Fields ................................................................................................................. 525 Align Text ................................................................................................................... 525 Adjust Height and Width ............................................................................................... 526 How You Can Format Text Displays................................................................................. 526 How You Can Add Field Borders ..................................................................................... 526 Change Font and Font Size............................................................................................ 527 Set the Default Font ..................................................................................................... 528 Change Report Field Colors ........................................................................................... 529 Set Gravity ................................................................................................................. 530 Propagate to Children................................................................................................... 530 Synchronize Properties ................................................................................................. 531

Contents xiii

Change Grid Spacing .................................................................................................... 531 Duplicate Spacing ........................................................................................................ 532 How You Can Add Graphics ........................................................................................... 532

Preview and Print Report Documents.................................................................................... 532 Export a Report................................................................................................................. 534 Delete a Report................................................................................................................. 534 RWConv Utility (Report Converer)........................................................................................ 534

Convert a Report Using the RWConv Utility ...................................................................... 535

Chapter 16: Managing and Deploying Applications 537 How You Can Access the OpenROAD Utilities ......................................................................... 537 How You Can Create Application Versions Using the VersionApp Utility ...................................... 538

Create Numbered Application Versions Using the VersionApp Utility..................................... 539 Parameters for the VersionApp Utility.............................................................................. 540

How You Can Delete Application Versions.............................................................................. 542 Delete an Application Using the DestroyApp Utility............................................................ 542 How You Can Delete All Versions of a Component ............................................................. 544

How You Can Import and Export Applications and Components ................................................ 546 Import an Individual Component .................................................................................... 547 Import an Application ................................................................................................... 547 Export an Individual Component .................................................................................... 552 Export Applications and Components .............................................................................. 552

How You Can Generate Reports for Applications and Components............................................. 555 Document an Individual Component ............................................................................... 555 Document Applications and Components Using the DocumentApp Utility .............................. 556 Document Imaged Applications Using the QueryImage Utility ............................................. 559

How You Can Apply Template Changes to Frames and Fields.................................................... 561 Apply Alternate Templates to Frames or Fields Using the ApplyTemplate Utility ..................... 561 Command Line Method for Upgrading Templates .............................................................. 565

How You Can Compile Applications and Components .............................................................. 565 Compile a Component .................................................................................................. 566 Compile an Application ................................................................................................. 566 Command Line Method for Compiling Applications............................................................. 568

How You Can Create an Application Image ............................................................................ 569 Use the MakeImage Utility ............................................................................................ 569 Command Line Method for Creating an Application Image.................................................. 571

How You Can Image Included Applications ............................................................................ 575 Root Application .......................................................................................................... 575 How Referencing Images Works ..................................................................................... 575 How You Can Override Included Application References ..................................................... 576

xiv Workbench User Guide

Running an Application....................................................................................................... 577 Run an Application from the Database Using the RunDBApp Utility ...................................... 577 Run an Application from an Image Using the RunImage Utility............................................ 580 Command Line Method to Run an Application from an Image ............................................. 582 How You Can Set Metaflags for the RunDBApp and RunImage Utilities ................................. 583

Set Defaults ..................................................................................................................... 584 How You Can Deploy Applications with 3GL Procedures ........................................................... 585

How You Can Use 3GL DLLs or Shared Libraries................................................................ 585 How You Can Use Commands from a File .............................................................................. 586 How You Can Deploy a Web-based OpenROAD Application with the OpenROAD eClient Packaging Tool...................................................................................................................................... 587

How the eClient Runtime Is Installed on Client Workstations .............................................. 587 oraxp.cab—eClient Cabinet File ...................................................................................... 588 How eClient Applications and Library Cabinet Files Are Deployed......................................... 588 How You Can Set Up Your Web Server ............................................................................ 588 Guidelines for Preparing OpenROAD Applications .............................................................. 589 How You Can Use a Digital Signature .............................................................................. 589 OpenROAD Web Publisher ............................................................................................. 590 OpenROAD Web Publisher Interface................................................................................ 595 Use the Web Deployment Assistant to Create a Web Deployment Package............................ 610

mClient Deployment .......................................................................................................... 611 How You Can Install mClient.......................................................................................... 611 Launch mClient............................................................................................................ 612 Differences Between Desktop and Pocket PC .................................................................... 612

How You Can Create and Distribute Help Files........................................................................ 613 Create Help Files.......................................................................................................... 614

Appendix A: Environment Variables 617 How You Can Set Environment Variables............................................................................... 617

How You Can Use the symbol.tbl File ............................................................................. 618 Environment Variables for All Platforms ................................................................................ 619 Environment Variables for Windows ..................................................................................... 626 Environment Variables for Ingres Installations ....................................................................... 627

How You Can Set Page Locks......................................................................................... 627 How You Can Use International Characters............................................................................ 628 How You Can Specify Color Tables ....................................................................................... 629

Contents xv

Appendix B: Speed Key Mapping 631 Keyboard Map Files............................................................................................................ 631

How You Can Specify a Keyboard Map File ....................................................................... 631 How You Can Format Keyboard Map Files ........................................................................ 632

Keyboard Mapping............................................................................................................. 633 Keyboard File Map Example........................................................................................... 634

Appendix C: Data Format Templates 637 Format Templates ............................................................................................................. 637

Format Templates for Field Types................................................................................... 637 How You Can Set the Format Template at Runtime ........................................................... 638

Input Masking and Data Validation....................................................................................... 638 Numeric Templates............................................................................................................ 638

Define a Numeric Template ........................................................................................... 639 Numeric Template Syntax ............................................................................................. 640 Input Masking and Numeric Templates............................................................................ 643

Date Format Templates ...................................................................................................... 643 Define a Date Template ................................................................................................ 643 Absolute Date and Time Format Templates ...................................................................... 644 Time Interval Format Templates..................................................................................... 647 Input Masking and Date Templates................................................................................. 649

Varchar Templates ............................................................................................................ 650 Define a Varchar Template ............................................................................................ 650 How You Can Create a Custom Varchar Template ............................................................. 651 How You Can Force Mandatory Entry .............................................................................. 657 Examples of User-defined Character Sets ........................................................................ 657 Examples of Varchar Templates ..................................................................................... 658

Glossary 659

Index 679

Introduction 17

Chapter 1: Introduction This section contains the following topics:

In This Guide (see page 17) Installing OpenROAD (see page 18) Intended Audience (see page 18) Documentation (see page 18) Your Support Options (see page 19)

OpenROAD® Workbench is a database-centric, object-oriented, 4GL application development tool that lets you develop and deploy mission-critical, n-tier business applications in a variety of environments. Applications can be delivered seamlessly to a desktop web browser or mobile device, displaying rich graphical user interface (GUI) content usually seen only in desktop applications.

Note: In this guide, the term Windows refers to the Microsoft Windows operating system, including Windows NT, Windows 98, Windows 2000, and Windows XP. Unless specifically indicated, Windows refers to any available Microsoft Windows operating system supported by OpenROAD. For more information on supported versions, see the readme.

In This Guide The User Guide is your procedural handbook to OpenROAD Workbench, providing what you need to know for everything you need to do with the Workbench user interface.

This guide covers the following topics in detail:

Structuring an application

Starting and customizing OpenROAD

Creating an application and a basic frame

Creating and using basic fields and alternative methods for creating fields

Generating frames and fields from predefined templates

Creating and modifying menus and toolbars

Working with classes

Writing scripts and procedures

Adding other components to your application

Installing OpenROAD

18 Workbench User Guide

Creating reports in OpenROAD

Managing and deploying applications

The appendixes in this guide provide information about environment variables, speed key mapping, and data format templates.

Descriptions of dialog fields and all menu commands are available in online help. (To open help, click Help, Help Contents.)

Note: For more information on new and changed features, see the Release Summary. For more information on monitoring and debugging your applications, see the Programming Guide.

Installing OpenROAD OpenROAD installation instructions are detailed in the Installation and Configuration Guide. For further installation considerations, check the latest readme.

Intended Audience

Because OpenROAD is intended for developers who want to create applications and database-aware applications, this guide assumes you know:

Basic programming concepts, including the principles of object-oriented programming (OOP)

Basic relational database management system (RDBMS) concepts, such as databases, tables, and cursors

In addition, you must be familiar with your window manager and toolkit, including terminology, navigational techniques, and how to work with standard items such as menus and dialogs. If you are not familiar with these things, see your window manager documentation before using OpenROAD.

Important! This guide also assumes that you have read through and understand the concepts contained in the Getting Started guide.

Documentation

The OpenROAD documentation set is described in the Getting Started guide. For a list of file names and how to access the latest documentation online, see the readme.

Documentation

Introduction 19

Your Support Options

Enterprise customers with active maintenance and support contracts have full access to Ingres Support, including telephone support and online use of our call tracking system and knowledge base, Service Desk. For Customer Support contact details, see http://ingres.com/support/contact.php.

If you have an active support contract and want to register for access to Service Desk (https://servicedesk.ingres.com), use the enrollment form at http://www.ingres.com/users/register.php. (Your six-digit Account Number/Site ID is required.)

If you do not have a support agreement for Ingres Corporation products and are interested in purchasing support, contact us at [email protected].

For more information about support options, visit http://ingres.com/support.php.

Free support is available from the Ingres Open Source Community. Community members may obtain assistance for Ingres Corporation products by registering with the Ingres Community Site and using the available tools. To register, go to http://community.ingres.com/forums/home.php and click Register in the upper right corner of the page.

The Community Forums also provide Ingres Open Source Community members the opportunity to ask questions and interact with other community members and Ingres Corporation technical staff. For more information, visit http://community.ingres.com/forums/index.php.

Structuring an Application 21

Chapter 2: Structuring an Application This section contains the following topics:

Basic Application Components (see page 21) Frames (see page 24) 4GL Statements for Running Frames Concurrently (see page 25) How an Application Moves Between Frames (see page 26) Procedures (see page 26) How You Can Share Information Between Frames (see page 27) Scope of Frames, Procedures, Variables, and Constants (see page 29) How You Can Change Global Constants at Runtime (see page 30) How You Can Share Frames Among Applications (see page 37) How You Can Enforce Consistency Throughout Your Environment (see page 38) How You Can Create Non-interactive Applications (see page 39)

This chapter describes the structure of an application. You will learn how to effectively use and manage application components. Understanding how components work is essential to designing your application.

Basic Application Components Before discussing application structures, you must first understand some OpenROAD concepts and terms. OpenROAD applications are window-based applications built on the following basic elements:

Frames and forms

Scripts, events, and event blocks

Objects

OpenROAD provides many ways to design and write applications. If your application will use the OpenROAD Server, it must be a partitioned application. We recommend that the application's business logic be hidden in user-defined classes and procedures. Then only a thin layer of “glue code” needs to reside in the actual frame scripts.

For more information on the OpenROAD Server, see the Getting Started guide and the Server Reference Summary.

Basic Application Components


The Basics of Frames and Forms

A frame is a window that consists of a form, with or without a menu, used to display and input data. A form is a two-foot by two-foot “canvas” that lies beneath a frame's window. It is the portion of the frame where the user displays or modifies data, views illustrations, reads instructions, and selects options.

Note: An “inch” in OpenROAD may not be the physical equivalent of one-twelfth of a foot. Consequently, the actual canvas size varies according to your terminal and operating system characteristics.

Some basic elements of a frame are:

Title bar

Resides across the top of the window, displays the title, and enables the user to manage the window

Menu bar

Provides menu operations that let the user access application functionality

Basic Application Components


Frame border

Defines the outer edge or boundary of the frame. When you create a frame, you can specify that the end user be able to change its size, in which case resizing cursors appear when the mouse is over the frame's edge.

Toolbar

Typically provides iconized shortcuts for frequently used menu commands, such as File, Exit, as well as easy access to other features or windows

The window frame provides a visual boundary around the form. Although the size of the form is fixed, you control which portion of the form is actually displayed to the end user. Furthermore, you can add scroll bars to the window so that the end user can scroll to a part of the form that is not visible.

More information:

Frames (see page 24)

Scripts, Events, and Event Blocks

Associated with each frame is a 4GL script that defines how the frame operates in response to events. An event may be user-initiated, such as clicking a ButtonField, or it may be program-initiated, such as one frame sending a specific user event to another frame.

A frame script can have three parts:

An optional initialize block used to declare parameters, local variables, and procedures for the frame

Event blocks, which are blocks of 4GL code that OpenROAD executes when the user or a program initiates a specified action or event

Optional local procedures that make code easier to read and eliminate code duplication

Note: Individual fields on a form and a frame's menu items can also have their own scripts.

More information:

Writing Scripts and Procedures (see page 435).

Frames


Objects

An object in object-oriented programming (OOP) is a data structure that holds values that you can manipulate. Each OpenROAD component—such as a frame, form, or menu item—is an object.

You also can plug external objects into your OpenROAD application. External objects are external controls such as charts, grid controls, HTML controls, and web browsers from independent software vendors.

For more information about objects and object-oriented programming, see the Programming Guide.

Frames

Frames are the main building blocks of most applications. They make up the interface through which end users interact with an application and also contain the code that makes their controls operational. Other application components, such as classes and global variables, are accessed and manipulated in the scripts of an application's frame components; therefore, frames are really the “glue” that holds the application together.

You use the Frame Editor to:

Create frames, or design the user interface

Explain, in terms of one or more 4GL scripts, what the frame is capable of doing and how it responds in various situations

Typically, frames are interactive, letting the end user enter, change, or delete data.

More information:

Creating Basic Frames (see page 105)

4GL Statements for Running Frames Concurrently


Ghost Frames

In addition to interactive frames, applications can also contain ghost frames. Ghost frames are used to manage and coordinate applications without user interaction. Ghost frames differ from other OpenROAD user frames in that they do not contain forms (thus making them invisible to the user).

More information:

How You Can Create Non-interactive Applications (see page 39)

4GL Statements for Running Frames Concurrently

When you create an OpenROAD application, you create its frames and associated objects, and then write the scripts for the frames. Your applications can run any number of frames concurrently. Frames can open or call other frames.

Three 4GL statements run frames:

callframe statement

Inactivates (blocks) the calling frame and transfers control to the called frame

openframe statement

Lets the user work in either the called frame or the calling frame

gotoframe statement

Closes the calling frame and transfers control to the called frame

How you use these three statements in your scripts determines how many windows are open at any given time and how the user can interact with the application.

For more information on these statements, see the chapter "Programming Frames" in the Programming Guide.

More information:

How an Application Moves Between Frames (see page 26) Calling Frame and the Called Frame (see page 33)

How an Application Moves Between Frames


How an Application Moves Between Frames

You control the basic structure of your application by specifying the order in which frames can be opened and by controlling which frames run concurrently with others.

Unlike a terminal-based environment in which the end user can work with only one frame at a time, a window-based environment lets the end user work with any number of active frames. An active frame is a frame that has the input focus and that end users can work in. Users can click the mouse in the frame, select menu or button operations, or enter data. They can also reposition the frame on the screen. For more information about making a frame the active frame, see the FrameExec class topic in the Language Reference Guide.

As you design an application, you should consider how the end user will proceed when moving sequentially from one frame to another when the user can work with more than one frame at a time. For a description of common structures for an OpenROAD application, see Controlling the Flow of Frames (see page 31).

Procedures

Another important factor to consider when designing your application is when to use a procedure. OpenROAD lets you create three types of procedures:

4GL procedures (see page 27)

3GL procedures (see page 27)

Database procedures (see page 27)

All these entities enable you to centralize code that you want to use in more than one script.

For more information about procedures, see Writing Scripts and Procedures (see page 435) in this guide and the Programming Guide.

How You Can Share Information Between Frames


4GL Procedures

There are two types of 4GL procedures:

Global 4GL procedures

Centralize OpenROAD code that you want to use in more than one script

Local 4GL procedures

Modularize code for a single frame, field, or procedure

When you call a procedure in a 4GL script, OpenROAD executes the procedure as if the procedure code was inserted directly into the script. You can call 3GL procedures from 4GL scripts.

3GL Procedures

A 3GL procedure is a set of 3GL statements that you can call by name in an application. 3GL procedures let you access code written in third-generation languages, such as C or C++. By calling a 3GL procedure from a 4GL script, you can access the 3GL features you need to supplement the OpenROAD 4GL programming language.

Database Procedures

A database procedure is a set of SQL statements that you can call by name in an application. Database procedures let you call data-oriented procedures that are stored and executed within the database server.


When planning your application, you should consider using the following elements:

Global variables (see page 28)

Global constants (see page 28)

User events (see page 28)

Database events (see page 28)

Each of these elements provides a simple, effective way to share information between frames and procedures.



Global Variables

A global variable is a variable that you can use in any script or procedure in an application. It contains data that any script or procedure in the application can access. After you declare a global variable, it is available for reading and writing by any script or 4GL procedure in the application. If you change the value of the global variable in one frame, the new value is immediately available to all other frames and 4GL procedures in the application.

You declare global variables using the Global Variable Editor.

More information:

Create a Global Variable (see page 449)

Global Constants

A global constant is a literal value to which you assign a name. Like a global variable, you can access the value of the global constant from any script or 4GL procedure in the application. You set the value for the global constant when you declare it. Constant values can be changed only in the Constant Editor, not in a script.

Using global constants helps you standardize the use of literal values throughout your application. Constants make your code more readable and consistent, ensuring a reliable standard. Many global constants are built into OpenROAD (such as TRUE, FALSE, and CC_RED). For more information, see the Programming Guide.

More information:

Create a Global Constant (see page 454)

User and Database Events

You can also define user and database events. User events provide a simple, effective way for actions in one frame to trigger actions in another frame. Database events provide communication between two applications that are connected to the same database.

User and database events are events that you name and define by providing the event code that executes when the frame receives the event. User events are sent using the SendUserEvent method, and database events are generated by Structured Query Language (SQL) statements and sent by the DBMS.

For more information about these events, see the Programming Guide.

Scope of Frames, Procedures, Variables, and Constants


Scope of Frames, Procedures, Variables, and Constants

Any frame created in a given application is accessible to all other frames and procedures in that application. Likewise, all components in an application are available to other applications that include it.

For more information about the included applications feature, see How You Can Share Frames Among Applications (see page 37).

External Code: Database, 3GL Procedures, and External Class Objects

Database, 3GL procedures, and external class objects are written outside the application but must be registered with the application for 4GL code to access it. After being registered, they are global to the application, available to all the frames and procedures accessible to the application. Similarly, all components in an application are available to the applications that include it.

More information:

Create and Register 3GL Procedures and Database Procedures (see page 461) Create and Register External Class Libraries (see page 428)

4GL Procedures

The scope of 4GL procedures and variables depends on how and where they are created. 4GL procedures and variables created in OpenROAD are globally accessible to other application components. Likewise, all components in an application are available to other applications that include it.

However, 4GL procedures and variables declared and defined in a 4GL script are local in scope. Field variables, declared automatically when you create a field on a form, are also local to the frame.

Local variables are declared in the DECLARE section of the initialize block of a frame, field, or 4GL procedure, as are forward references to local procedures. Variables declared within the parentheses of a frame's or procedure's initialize block are parameters, visible outside the current frame or procedure. Local procedures are defined at the end of a script, after all event blocks or method definitions.

For more information about the syntax for variable and procedure declaration, see the Programming Guide.

How You Can Change Global Constants at Runtime


The following table describes the scope and lifetime of local variables and procedures:

Where Declared Scope Lifetime (of Variables)

Frame script Entire frame script and all associated field scripts, including all initialize blocks, event blocks, and local procedures

Life of frame

Field script for scalar field Entire field script, including its initialize block, event blocks, and local procedures

Life of frame

Field script for composite field

All field scripts for the composite field and for all fields contained within it, including all initialize blocks, event blocks, and local procedures in these field scripts

Life of frame

Event block (variables only)

Event block Life of event block

Local procedure (variables only)

Local procedure Life of local procedure

Global 4GL procedure script Entire 4GL procedure script, including all of its local procedures

Life of global 4GL procedure

User class method (variables only)

Method Life of method


You can create and initialize global constants in the visual development environment using the Constant Editor. If, however, you want to change the values of global constants for the duration of an application session, you can invoke files at runtime that store different sets of initial values. This feature is particularly useful if you want to change an application's language for a session.

More information:

How You Can Customize a Session for an Application (see page 85)



Controlling the Flow of Frames

OpenROAD frames are not limited to a predefined set of control types. The following are examples of three different types of frame control implementations:

Control frames (see page 31)

Sequential frames (see page 31)

Multiple use frames (see page 31)

Control Frames

Applications that give the user a choice of tasks use a control frame structure. The control frame application type displays a single frame that provides access to other frames and lets the user quit the application. The control frame may remain open for the entire session.

Sequential Frames

Sequential frames force the user to follow a set of sequential steps by closing the control frame as the detail frame opens. A separate frame is used for each individual section of the task.

How Multiple Use Frames Work

The multiple use frame structure uses a single frame to step the user through related tasks. Wizards are examples of multiple use frames. For example, if you have dozens of fields for user input and they all pertain to the same data, instead of cluttering a single frame with many fields or stepping the user through a series of frames, you can dynamically change a single frame to display many fields.

To display many fields, you can employ the following techniques:

Make use of the full size of an OpenROAD form, incorporating the entire form into a viewport field.

If a table field is wider than the frame window, a viewport provides access to all of the table field data using a horizontal scroll bar. As end users complete the last field in one part of the form, they can scroll to the next.

Put all fields in the same segment of the form, but make one group of fields invisible while others are visible.

As the end user completes the last of the visible fields, the mode of the frame changes, switching the field visibility. You can also allow end users to page back and forth among the displays.



For more information about viewports and other fields, see Creating and Using Basic Fields (see page 151).

Note: You may incorporate all of these structures in more sophisticated applications. For example, one of the frames selected from the control frame may step the user through a series of sequential frames; a sequential frame application might present the user with a frame that provides access to several other frames.

Choosing a Concurrency Style

An OpenROAD control frame application can have any number of frames open at the same time. The open frames can be in one of two states: active or inactive. You should choose a style to use and use it consistently throughout your application.

Active Frames

An active frame is a frame that has the input focus and that end users can work in. Users can click the mouse in the frame, select menu or button operations, or enter data. They can also reposition the frame on the screen.

Inactive Frames

An inactive frame is one in which the end user cannot execute an operation. A frame can become inactive in one of two ways:

The frame executes a callframe statement

The frame is temporarily blocked (even though it was opened with an openframe statement) because another frame is busy

If one frame is executing an event block that takes a long time, for example, all other frames are blocked.

In both cases an hourglass appears when the user moves the cursor over the inactive frame.

How the Application's Starting Frame Is Opened

To enable the end user to start interacting with an application, the application must display a frame. Therefore, OpenROAD automatically opens the application's starting frame when the user starts the application. (If you specify a starting procedure for the application instead of a starting frame, you must use an OpenROAD statement in the starting procedure that opens the first frame.)



After the first frame is open and you want to open a second frame, you can use any of the following statements:

openframe statement

Leaves the first frame active after opening the second frame. This creates two active frames, both of which the end user can interact with.

callframe statement

Makes the first frame inactive after opening the second frame. This creates one inactive frame and one active frame, with the active frame blocking access to the inactive frame. End users cannot use the inactive frame until they close the active frame.

gotoframe statement

Closes the first frame when it opens the second frame

For more information about these statements, see the chapter “Programming Frames” in the Programming Guide.

Calling Frame and the Called Frame

When one of these statements or a procedure appears in a frame script, the frame that contains the statement is referred to as the calling frame, and the frame to which control is passed is the called frame.

All these statements transfer control from the current frame to a second frame while executing the second frame. The control frame structure uses either the callframe or openframe statement. The sequential frame structure uses the gotoframe statement to force the user to step through the application. You can achieve a similar result by using the dynamic features of OpenROAD for a sequential frame application. This is significantly faster than using gotoframe.

For more information about how to use these dynamic features, see the Programming Guide.

Selecting a Control Frame Style

After opening the control frame, you must decide whether to open more active frames. There are many styles of control frame applications. A few common ones are described in the following sections.

Detail Frame Application

A detail frame application is the easiest application to develop. The control frame uses the callframe statement to open each of the detail frames. No communication between the frames is necessary because only one frame is active at a time. The control, or parent, frame is blocked by the detail, or child, frames.



You can use the callframe statement parameters to get information from the child frames back to the parent. To return to the control frame and select another task, the user must close the detail frame.

For more information on child-parent frame interaction, see the Programming Guide.

Read-only Application with Concurrent Frames

Another simple model is the read-only application. A read-only application is one that opens several concurrent read-only frames from the control frame. This lets end users have several concurrent frames for display purposes.

To open each of the read-only frames, use the openframe statement from the control frame. Because end users are not changing information about the child frames, you need not worry about communicating with the parent frame. However, you may want the parent frame to track when each child frame is opened to ensure that end users do not open the same frame more than once.

Read/Write Application with Concurrent Frames

A more complex type of control frame application, the read/write application provides concurrent frames that let end users enter data in some frames and select data in other frames. For this type of application, you use the openframe statement to open each of the concurrent frames from the parent frame.

An application of this type is more difficult to develop because you must ensure that any changes in the child frames are reflected in the parent frame. One way to do this is to use the SendUserEvent method and a UserEvent event block to communicate between the frames.

For more information about communicating between frames, see the Programming Guide.

Data-driven Application

A data-driven application lets you provide different operational choices to different users from a single frame that can be used throughout several applications. The choices that appear on the menu are stored in a database table or a runtime array and are displayed selectively at runtime based on such information as the end user's login or group ID.

One menu frame can serve all applications, standardizing user interaction throughout an organization. In addition to facilitating standardization, this style minimizes the user frustration that arises from being presented with operations for which privileges are lacking.



How You Can Manage Database Interactions

Developing an application with multiple concurrent frames raises issues about transaction management. If a single control frame lets the user open several concurrent child frames, a single lock is held for the entire session. If a commit or rollback statement is issued in any of the open frames, all database transactions are affected.

If you develop an application with unrelated open frames, you may want to open a different database session for each frame. However, if your frames are related, a single transaction may be more appropriate.

In a sequential frame application, you may want to commit database transactions as the user closes each frame. In a multiple-use frame, you may want to keep a single transaction open for the life of the frame.

If your application uses a single database session, only one database transaction is in effect for all the active frames, possibly causing locking conflicts for other users. If the application uses multiple sessions, you must consider concurrency issues, not only between different users but also between different transactions initiated by the same user.

For more information about these issues, see the Programming Guide.

Selecting an Operation Style

Whether you structure your application around a control frame, sequential frames, or a multiple-use frame, you have many choices for providing operations to the user. Some of these options include:

Menu bar with commands and speed keys

Toolbars

Buttons such as push buttons and control buttons

Enumerated fields (such as list fields or palette fields) or table fields

Drag-and-drop actions

External class objects (ActiveX controls)

Tree views

List views



A single control frame may offer several kinds of interactions, such as a table field for selecting tasks and buttons or a menu bar for standard operations such as Close and Help. Moreover, the same frame may have more than one method for invoking operations to enable end users to interact with an application in the manner most comfortable for them.

For example, a menu bar with speed keys can repeat operations offered in the table field, enabling the user to invoke the same operation either from the keyboard or the mouse.

How You Can Provide Multiple Invocation Styles

Providing multiple invocation styles does not require multiple blocks of code. For example, the following event block provides both a Close button and a Close menu operation (that can have an associated speed key):

on click close_button, on click menu.file.close_menu = { return; }

Note: You must refer to menu operations by their complete names. The syntax is:

MenuBar.MenuStack.MenuItem

MenuBar

Specifies the name of the menu bar. Menu bars are named “menu” by default when you create them in the Menu Editor, although you can rename a dynamically created menu bar whatever you want.

MenuStack

Refers to the operation name that appears on the menu bar, such as File or Options. Each operation that appears on the menu bar can have a stack of operations associated with it that appears when the user clicks the operation name. The operation that appears on the bar for the example stack is probably called File, as its variable name is "file."

MenuItem

Specifies the associated operation for this particular menu item—for example, the Open, Close, and Exit items on the File menu. The operation on the example stack affected by this event is the "close_menu" operation.

How You Can Share Frames Among Applications


How You Can Share Frames Among Applications

Sharing frames among applications lets you increase productivity and enforce standards.

For example, you might have a PartInfo frame that manipulates information about parts you purchase. You can make this frame available to your sales order staff, shipping staff, and stockroom staff, in three different applications—Purchasing, Shipping, and Inventory Control. By sharing the PartInfo frame among multiple applications, you can ensure that everyone in your organization interacts with the same frame. This way, if changes are made to the PartInfo frame in one application, these same changes are reflected in all three applications.

Included Applications Feature

When planning the structure of your application, consider sharing components such as frames and frame templates across your organization. You could put these components into a generic Standards application, for example, that you include in all of your other applications. In OpenROAD, an application that is shared in this way is referred to as an included application. In fact, OpenROAD itself takes advantage of this feature by including the core application library, which provides system-defined application components including frame and field templates.

More information:

Included Applications (see page 87)

How You Can Customize Included Frames

If you want, you can customize the included frames for each application that uses them. For example, you can pass parameters to the included frame, or you can use some of the dynamic features that OpenROAD provides.

For more information about dynamic features, see the Programming Guide.

How You Can Enforce Consistency Throughout Your Environment


How You Can Enforce Consistency Throughout Your Environment

OpenROAD empowers you to develop consistency and uniformity within your applications, primarily through the use of frame and field templates and style sheets.

These methods let you define the behavior and style of your fields and frames in a template, and then build your application frames based on these templates. This method provides a quick and efficient way to achieve consistency among developers and even across applications.

Frame Templates

Every OpenROAD frame is based on a frame template. Frame templates specify the appearance of a type of frame and many of its behaviors. OpenROAD provides templates for basic frame types such as a calculator or dialog box. You can also create your own templates.

You can use frame templates to specify the same menu operations for all frames of a particular type, or you can include your logo or other graphic elements on your frames.

More information:

Creating Basic Frames (see page 105) Create a Frame Based on Your Own Frame Template (see page 144)

Style Sheets

Associated with each frame and frame template is a style sheet. A style sheet defines the appearance of each type of field that can appear on any frame using that template. A style sheet lets you specify certain style attributes for each type of field that you can create for that frame or frame template.

For example, you can specify that buttons always be the same color or that entry fields always have the same outline width.

More information:

Creating Basic Frames (see page 105)

How You Can Create Non-interactive Applications


Field Templates

You can create field templates that define the appearance and behavior of a field to be used for a specific purpose. You then can use this template as the basis for creating similar fields throughout your applications.

For example, you can create a template for a Save button that lets end users save changes they have made to the data on a frame. You then can use this template with any frame without having to redesign the button or rewrite its 4GL code.

More information:

Create a Field Template (see page 273)


Because ghost frames and 4GL procedures do not require the window manager to be running, you can write OpenROAD applications that run entirely without user interaction. To execute these applications without running the window manager, use the -nowindows flag when invoking the RunImage utility.

When you run an OpenROAD application without the window manager, information that would ordinarily display as a pop-up frame on the executing window is redirected to the Trace window and the w4gl.log file.

This redirection of information includes the following items:

Informational pop-up messages provided by OpenROAD such as those containing error messages

4GL statements that do not require user response such as the message statement and the InfoPopup method

4GL statements that require user response such as the prompt statement and the ReplyPopup method

Note: Because statements that require user response block the application until answered, you should not include such statements in frames or procedures that are to be run non-interactively. Moreover, because end users may not notice informational statements directed to the error log file or Trace window, you also may want to avoid informational statements that require user response.



Other coding restrictions for running applications without the window manager include attempting to call, open, or go to frames that contain forms. These actions result in error messages.

For more information about running applications and the RunImage utility, see Managing and Deploying Applications (see page 537).

Getting Started with OpenROAD Workbench 41

Chapter 3: Getting Started with OpenROAD Workbench

This section contains the following topics:

OpenROAD Workbench Overview (see page 42) How You Can Start OpenROAD Workbench (see page 61) How You Can Customize OpenROAD Workbench (see page 71)

The first step to application development is to start the OpenROAD development environment session that provides access to Workbench and its tools for creating applications.

Note: For information on installing OpenROAD in your computing environment, see the readme and the Installation and Configuration Guide.

OpenROAD Workbench Overview



The primary interface for OpenROAD Workbench is a window consisting of a menu bar, toolbar, function tabs, and a status bar. Descriptions of each of these elements follow the illustration.



The Workbench window consists of the following controls and components:

Title bar

Displays "OpenROAD Workbench" with the name of the active connection profile

Menu bar

Displays menus applicable to the currently selected tab and portlet. Some menus, such as View, Options, and Run, are specific to to particular Workbench tabs while others, such as File and Help, are available no matter where you are in the OpenROAD development environment. Top-level Workbench menus include the following options:

File

Lets you create new items (for example, database connection profiles, applications, components, and so on), open and view items, save and rename items, import and export items, and exit Workbench

Edit

Lets you cut, copy, paste, and duplicate selected items; edit item details; and find items

View

Lets you refresh the display of applications and components or display all application versions defined in the current database. You can also customize the appearance of Workbench by hiding the status bar or changing the display format.

Project

Lets you compile applications and create image files and packages, issue queries, document projects; and create and purge versions

Run

Lets you run and debug applications, set breakpoints for debugging, and perform log file operations

Note: For more information about how to use the debugger, see the chapter “Debugging Your Application” in the Programming Guide.)

Tools

Lets you apply templates to application components, generate service call procedures and SCP metadata, and set general Workbench options

Help

Lets you display online help for OpenROAD Workbench, display the Language Reference Guide in online help format, visit the Ingres Web site, or display information about the current version of Workbench



Toolbar

Displays icons that are shortcuts for menu selections. The icons displayed as active depend on the currently selected tab and portlet. The following illustration shows all of the toolbar icons, labeled:

The toolbar icons correspond to the following menu selections:

Toolbar Icon Menu Selection

Connect to server File, Connect

New File, New, ...

Open File, Open

View File, View

Save File, Save

Save and close File, Save and close

Close File, Close

Save as File, Save as

Delete Edit, Delete

Save all File, Save all

Refresh View, Refresh

Import File, Import



Toolbar Icon Menu Selection

Export File, Export

Cut Edit, Cut

Copy Edit, Copy

Paste Edit, Paste

Duplicate Edit, Duplicate

Find Edit, Find

Find next Edit, Find next

Compile Project, Compile

Run Run, Run

Debug Run, Debug

Stop Run, Stop

Help Help, Help Contents



Tabs

Displays the following tabs, which follow the process from application development to deployment:

Connect (see page 47)

Develop (see page 49)

Debug (see page 51)

Monitor (see page 52)

Query (see page 54)

Build (see page 55)

Deploy (see page 56)

Manage (see page 58)

Most tabs are subdivided into portlets, defined areas for particular functions. Selecting a portlet often changes the available menu items and toolbar buttons.

Status bar

Displays status information in the following areas:

Left side

Displays informational messages about the development environment

Center

Displays the user name of the connected user (either your user name or the user name of the user that you used to connect to the database [-u])

Right side

Displays the name of the database that you are connected to



Connect Tab

The Connect tab is the default tab of OpenROAD Workbench, displayed every time you start Workbench. It lists all the database connection profiles you have defined, with the default profile displayed in the Default Profile portlet. A database connection profile is a collection of settings used to establish a connection with a local or remote database. To use any of the other tabs, you first must be connected to a database.

On the Connect tab, you can do the following:

Define new connection profiles (see Define a Database Connection Profile (see page 67) in the User Guide)

Modify existing connection profiles (see Modify a Database Connection Profile (see page 70) in the User Guide)

Delete connection profiles (see Delete a Database Connection Profile (see page 71) in the User Guide)

After you select a profile from the list and click any of the other tabs, Workbench establishes the database connection. For more information, see Connect to a Database Through a Connection Profile (see page 70) in the User Guide.



The Connect tab contains the following portlets:

Default Profile

Displays the connection profile you have set as the default profile. Unless you click on another profile name in the Connection Profiles portlet, you will be connected to the default profile when you click any of the other Workbench tabs.

Recent Profiles

Displays the previous connection profiles you have used to connect to a database, up to seven, in reverse chronological order from left to right

Connection Profiles

Lists all the database connection profiles you have created. When you select a profile in the list, its details are displayed in the Connection Details portlet.

Connection Details

Displays the details of the connection profile currently selected in the Connection Profiles portlet. When you select a profile in the Connection Profiles list and click File, Open, this portlet changes to the Edit Connection Profile, allowing you to make changes to the connection details.

More information:

Connect to a Database Through a Connection Profile (see page 70) in the User Guide Modify a Database Connection Profile (see page 70) in the User Guide Delete a Database Connection Profile (see page 71) in the User Guide



Develop Tab

This tab is where developers write code, and create and debug software components used to build applications.

The Develop tab contains the following portlets:

Applications

Displays all the applications stored in the repository. When you select an application, its components are displayed in the Components portlet.

For more information, see Applications Portlet (see page 72) in the User Guide.

Component Filter

Lets you filter the Components display to certain component types, for example, only user frames and 4GL procedures.

For more information, see Specify Component Types (see page 78) in the User Guide.



Components

Displays the components of the application selected in the Applications portlet.

For more information, see Components Portlet (see page 75) in the User Guide.

Application Properties

Lets you view and edit the properties of the application selected in the Applications portlet.

For more information, see Application Properties (see page 82) in the User Guide.

Included Applications

Displays applications that are included in the application selected in the Applications portlet. This portlet also lets you add and delete included applications.

For more information, see Included Applications (see page 87) in the User Guide.

Class Browser

The Class Browser provides a comprehensive look at all the classes defined to or used by your application. It also lets you browse the methods and properties of external class objects, as well as those of system and user class objects.

For more information, see Class Browser (see page 432) in the User Guide.

Component Details

Displays properties for the component selected in the Components portlet

Cross References

Displays relationships to other components for the component selected in the Components portlet.

For more information, see Display Component Relationships (see page 78) in the User Guide.



Debug Tab

This tab is where you test and debug the applications you have created on the Develop tab. The Debug tab provides an easy way to set a variety of breakpoints so that you can step through code you have written, line by line.

The Debug tab contains the following portlets:

Source Components

Displays all the source components for the application selected in the Applications portlet of the Develop tab. When you select a component, its source and breakpoints information is displayed in the Breakpoints portlets on the right side of the screen.

For more information, see the chapter "Debugging Your Application" in the Programming Guide.

Activations

Displays the breakpoints that are set in your source and lets you activate or deactivate them without removing them from your source.

Breakpoints: Source

Displays the compiled script for the component selected in the Source Components portlet. This portlet lets you set breakpoints on any executable line of code.



Breakpoints: Calls

Displays a list of user frames and procedures in the application selected in the Source Components portlet. This portlet lets you set breakpoints on specific frames and procedures.

Breakpoints: Methods

Displays a list of user and system classes and their methods for the application selected in the Source Components portlet. This portlet lets you set breakpoints on specific methods.

Breakpoints: Other

Lets you set breakpoints on a variety of events, errors, and threads

For more information about the Debug tab, see the chapter "Debugging Your Application" in the Programming Guide.

Monitor Tab

This tab lets you observe an application as it runs. It displays a schematic of the components in your application while it is running, enabling you to test and improve your application.



The Monitor tab contains the following portlets:

Call Stack

Displays all calls to procedures, frames, and user class methods. Each thread in an application has a separate call stack.

Thread Map

Displays a dynamic graphical view of the current state of the application, including a tree diagram of the parentage of the various threads in a multi-threaded application

Trace Log

Displays the log file for the running application or component

Trace Configuration

Lets you control what information is logged to the file and redirect the output to an external file

For more information about the Monitor tab, see the chapter "Debugging Your Application" in the Programming Guide.



Query Tab

This tab lets you run SQL statements against a target database to examine data in it.

The Query tab contains the following portlets.

Database Connections

Displays connections for running applications, database connection profiles, and databases in a hierarchical tree structure. This portlet also lets you create new database connections and stop currently running connections.

Connection Details

Displays details for the item currently selected in the Database Connections portlet.

For more information, see Modify a Database Connection Profile (see page 70) in the User Guide.



Database Query

Lets you specify query statements to run against the currently connected database

Query Results

Displays the results of the query entered in the Database Query portlet

For more information about the Query tab, see the Getting Started guide and the chapter "Debugging Your Application" in the Programming Guide.

Build Tab

After creating, testing, and correcting an application, you use this tab to build it into an executable image file. An image file is a compiled, executable version of an OpenROAD application. File names end with the extension .img.

You use the Build tab to create profiles for the MakeImage utility and other OpenROAD utilities. For more information on these utilities, see How You Can Access the OpenROAD Utilities (see page 537) in the User Guide.



The Build tab contains the following portlets.

Build Commands/Scripts

Displays build commands and scripts you have created with the OpenROAD Build Assistant (wizard). A build command is a saved settings profile for use with an OpenROAD utility (for example, MakeImage). A build script is an ordered collection of build commands.

Script or Command (Utility Name)

Displays the settings for the build command or script selected in the Build Commands/Scripts portlet. This portlet lets you modify the commands or scripts.

Log

Displays the contents of the trace output file for the build command or script selected in the Build Commands/Scripts portlet

For more information about using the Build tab, see the Getting Started guide.

Deploy Tab

This tab lets you package a built application and deploy it to the Web as an OpenROAD eClient application by doing the following:

Generate and publish a CAB file containing your OpenROAD application

Generate and publish a default web page containing the basic formatting (OBJECT tags) required to start the application from a web browser



You build web deployment packages (.CAB files) with the Web Deployment Assistant (wizard). For more information, see Use the Web Deployment Assistant to Create a Web Deployment Package (see page 610) in the User Guide.

Note: The Deploy tab is unavailable in the UNIX and Linux versions of OpenROAD Workbench.

The Deploy tab contains the following portlets:

Web Deployment Packages

Displays the web deployment packages you have created

Package

Lets you enter basic control information used by the OpenROAD eClient runtime to run the application. The contents are placed in the installation file that is part of your CAB file.

Content

Lets you define the 4GL image and data files held in the CAB file



Environment

Lets you define session-level environment variables that are defined to the operating system before the eClient application is run

Install File

Displays the contents of the Install4GL.txt file that is packaged with your CAB file and used by the OpenROAD eClient runtime to control the properties of the running application

Manage Tab

This tab lets you manage the OpenROAD Server using the same functionality as the former Visual OpenROAD Server Administrator application (Visual OSA). This tab lets you build and deploy OpenROAD 4GL business logic to the OpenROAD Server so that it can be accessed by a thin client.

Note: The Manage tab is available only if you have installed the OpenROAD Server.



The Manage tab contains the following portlets:

Server Manager

Displays a Microsoft Explorer tree-style interface with two panes:

Left pane (tree view)

Displays a hierarchy of nodes represented with icons. Each node has a right-click context menu.

Right pane (details)

Displays the contents of the currently highlighted node. The right pane may contain a tab folder, and each page within the folder may contain additional tab folders.

For more information about the Manage tab, see the chapter "Debugging Your Application" in the Programming Guide and "Managing and Monitoring the OpenROAD Server" in the Server Reference Guide.

Editors

Workbench toolbars and menu items provide quick access to the following OpenROAD component editors:

Frame Editor

Frame Template Editor

Field Template Editor

Class Editor

External Class Library Editor

4GL Procedure Editor

3GL Procedure Editor

Database Procedure Editor

Global Variable Editor

Constant Editor

Include Script Editor

Script Editor



Some are visual editors, like the Frame and Frame Template Editors, which have their own tool palettes and menu bars. These editors also display an accompanying Property Inspector that lets you quickly and easily specify the properties for each component and each field or control in the component. (For more information on the Property Inspector, see the User Guide.) You can optionally display a field tree that visually depicts the entire field hierarchy for a component.

The following illustration is an example of the Frame Editor with its accompanying Property Inspector, Field Palette, and menu bar:

In addition to the visual editors, OpenROAD provides editors specifically tailored to deal with different aspects of your application. These range from simple dialogs for declaring global variables and constants to a Script Editor for writing your code.

How You Can Start OpenROAD Workbench


The following illustration is an example of the Script Editor:

How You Can Start OpenROAD Workbench You can use OpenROAD Workbench to develop applications that interact with databases. During the development phase, it is common for applications to be stored in the same database, or repository, as the tables against which they operate. (That is, by default, the database is assumed to store both the application and the data that the application accesses.) Therefore, to begin a development session, you must start Workbench and then define a database connection.

After OpenROAD is installed, you can start the Workbench development system directly from the desktop, from the command line, or from an image file. For instructions, see the appropriate procedure, following.



Start OpenROAD Workbench from the Desktop

You can start OpenROAD Workbench from the icon installed on your desktop, or from the Windows Start menu.

To start OpenROAD directly from the desktop

Double-click the OpenROAD Workbench icon.

The OpenROAD Connection Profiles dialog appears (see page 67).

Note: If Ingres is not running, you will be prompted to start it. For more information, see How You Can Start Ingres (see page 63).

To start OpenROAD from the Windows Start menu

Click Start, All Programs, your_Ingres/OpenROAD_instance, OpenROAD Workbench 2006.

your_Ingres/OpenROAD_instance

Specifies the name of the Ingres instance you installed for OpenROAD


Note: If Ingres is not running, you will be prompted to start it. For more information, see How You Can Start Ingres (see page 63).

More information:

How You Can Start Ingres (see page 63) Define a Database Connection Profile (see page 67)



How You Can Start Ingres

Before you can start OpenROAD Workbench, Ingres must be running. When you start Workbench, if Ingres is not running, the following dialog box will appear:

To start Ingres

Select one of the options on the Start Ingres dialog and click OK.

Note: If you select the Ingres Service Manager (winstart) option, click Start on the Ingres Service Manager window.

Ingres is started, and then Workbench starts.

Start OpenROAD Workbench from the Windows Command Prompt

You can start OpenROAD Workbench from the command prompt or the Windows Run dialog.

Note: For a description of command line parameters, see RunImage Utility Parameters (see page 64).

To start OpenROAD from the command prompt

Enter the following command:

w4gldev runimage workbnch.img -realfields


More information:

Define a Database Connection Profile (see page 67)



Start OpenROAD Workbench with the RunImage Utility

You can use the RunImage utility to start OpenROAD Workbench using a specific database, component, and other parameters.

Note: For information about OpenROAD's other utilities, including additional information about RunImage, see Managing and Deploying Applications (see page 537).

RunImage Utility Parameters

The RunImage utility can use the following parameters to start an OpenROAD Workbench session. You enter values for these parameters in the RunImage dialog (see Start OpenROAD Workbench with the RunImage Utility (see page 64)).

-database

Specifies the name and location (host machine) of the database that contains the data to be used in the application. This database need not be the same database that was specified when the application was created.

Note: The syntax for this parameter may differ on different servers (for example, it may be vnode::dbname/ingres on Ingres and vnode::dbname/oracle if you are using Enterprise Access for Oracle).

-component

Specifies a component (frame or procedure) to use as the starting point for the application. By default, the application starts with the frame or procedure specified in the Property Inspector.

-username

Lets you use Workbench as if you were another user, whose user name you enter. Note that you, not the specified user name, own all files created by OpenROAD.

Note: This parameter may be available exclusively to users with certain privileges (or it may be mandatory regardless of your privileges), depending on the database. For example, on Ingres, only the database administrator, the Ingres system administrator, or a superuser can use this parameter. This parameter may also include a password (-uusername /password).

-m

Specifies the name of a different environment variable to contain your list of DLLs or shared libraries to be searched when resolving 3GL procedure calls. If this variable is present, the -m parameter overrides any existing specification of II_LIBU3GL.

For more information, see How You Can Use 3GL DLLs or Shared Libraries (see page 585).



-included app override file

Specifies a file containing overrides for the version and location of any included applications.

For more information about specifying an override file, see How You Can Image Included Applications (see page 575).

-global const file

Specifies a file containing initial values for the global variables and constants in the application. These values remain in effect for the duration of the current OpenROAD session.

-A(ppend to log)

Causes the trace output of the current command to be appended to the bottom of the existing error log file. Otherwise, this log file is replaced.

-realfields

Instructs Workbench to create a separate window system control for each field on a form. By default, Workbench multiplexes a single control for many fields as an optimization.

-bidi

Specifies that the frame displays from left to right

-T(race)

Controls the display of the Trace window by entering one of the following values:

yes

Specifies that the Trace window appears but suppresses all informational messages output by the system

no

Specifies that the Trace window does not appear and a log file is not created

yes,min

Specifies that the Trace window appears minimized as an icon



Start OpenROAD Workbench Using RunImage

You can start OpenROAD Workbench with parameters using the RunImage utility. For an explanation of these parameters, see RunImage Utility Parameters (see page 64).

To start the RunImage utility

1. Enter the following command at the command prompt:

w4glrunu

The RunImage dialog appears:

2. Select workbnch.img from the File drop down.

3. Specify any optional parameters.

These parameters are described in RunImage Utility Parameters (see page 64).

4. Click OK.

Workbench starts using the parameters you specified.

More information:

RunImage Utility Parameters (see page 64)



Define a Database Connection Profile

To use any of the Workbench tabs other than the Connect tab, you first must connect to a database through a database connection profile. Therefore, you must create at least one connection profile before you can connect to a database. You can create connection profiles to connect to existing databases or you can create a new database for the connection. You create database connection profiles on the Connect tab using the OpenROAD Startup Assistant.

Note: For information on fields and parameters used in the OpenROAD Startup Assistant, see OpenROAD Startup Assistant Properties (see page 68).

To create a database connection profile to connect to an existing database

1. Click the Connect tab.

2. Click File, New Profile.

The Connection Profile Assistant opens.

Click Next.

3. Select Existing Database and click Next.

4. Select whether the database is a local or remote connection.

A vnode is a virtual node, which provides all connection data to connect to an Ingres installation on a remote system. For more information, see the Ingres Network Management Utility (netutil) or Network Utility (ingnet) in the Ingres Connectivity Guide.

5. Select the database.

6. Specify connection options.

For more information on connection options, see the SQL command in the Ingres Command Reference Guide.

7. Name the profile and optionally provide a description.

The profile name must be unique.

To create a database connection profile to create a new database

1. Click the Connect tab.

2. Click File, New Profile.

The Connection Profile Assistant opens.

3. Select Create Database and click Next.



4. Select whether the database will be created on a local or remote machine.

A vnode is a virtual node, which provides all connection data to connect to an Ingres installation on a remote system. For more information, see the Ingres Network Management Utility (netutil) or Network Utility (ingnet) in the Ingres Connectivity Guide. For more information on flags that can be used with the connection command, see CREATEDB in the Ingres Command Reference Guide.

5. Select the database.

6. Specify connection options.

For more information on connection options, see the SQL command in the Ingres Command Reference Guide.

7. Name the profile and optionally provide a description.

The profile name must be unique.

OpenROAD Startup Assistant and Connection Details Properties

You can specify the following properties using the Create Connection Profile dialog. These and additional properties are available in the Connection Details portlet of the Connect tab for a selected connection profile.

Name

Specifies a unique name for the database connection profile

Description

Specifies an optional description for the connection profile

DBMS

Specifies one of the following database management systems:

Ingres

Oracle

Microsoft SQL Server

IBM DB2 UDB

Type

Specifies the type of database connection:

Local

VNode

Dynamic



Node

If you specified VNode as the Type, identifies the name of the remote virtual node, as defined by your network administrator, where the desired database is installed. It provides all connection data to connect to an Ingres installation on a remote system.

For more information, see the Ingres Network Management Utility (netutil) or Network Utility (ingnet) in the Ingres Connectivity Guide.

Database

Specifies the name of the database you are creating

Username and Connect As (-u)

Specifies a different user name. Lets you use this account to connect to the database as if you were another user. Note that you own all files created by OpenROAD, not the user whose user name you enter.

Group

Specifies the group identifier for the session, allowing the group's database directory and file permissions to be applied to the session.

If you omit this flag and there is a default group identifier specified for you, the default group identifier is assigned to the session.

Note: To specify a group, you must be a member of the specified group identifier's user list, an Ingres system administrator, the database administrator (DBA) of the specified database, or a user that has the db_admin privilege.

Role

Specifies the role identifier for an application image, and associates the role identifier's permissions to the session.

If the role identifier requires a password, you are prompted for the password. If you specify the -R flag but omit the identifier and the password, you are prompted for both. If no password is defined for the specified role identifier, press Enter when prompted for the password.

Note: Neither role identifier nor password is validated if you are an Ingres system administrator, the DBA of the specified database, or a user that has the db_admin privilege.

Other flags

(Optional.) Enter other Ingres session flags to be included with the connect statement.

For more information on flags that can be used with the connection command, see CREATEDB in the Ingres Command Reference Guide.



Profile Icon

Specifies the graphic image that represents a connection profile on the Connect tab. You can use the default connection icon, shown in the following illustration, or you can specify another image file containing a custom icon.

-x(exception)

Indicates the level of error messages you want the compiler to generate:

warning

Generates error messages and warning messages

fatal

Generates messages only for compiler errors

Connect to a Database Through a Connection Profile

To use any of the tabs other than the Connect tab, you first must connect to a database through a connection profile. For more information on creating a connection profile, see Define a Database Connection Profile (see page 67).

To connect to a database

1. Start OpenROAD Workbench.

The Connect tab is displayed by default.

2. Click the connection profile you want to use for your database connection in the Connection Profiles portlet.

3. Click any of the other tabs, depending on what you want to do.

OpenROAD connects to the database using the information in the connection profile.

Modify a Database Connection Profile

You can modify existing connection profiles on the Connect tab.

To modify a database connection profile

1. Click an existing connection profile in the Recent Profiles or Connection Profiles portlet of the Connect tab.

The profile parameters are displayed in the Connection Details portlet.

2. Click the header bar of the Connection Details portlet to activate the portlet.

How You Can Customize OpenROAD Workbench


3. Click File, Open.

The fields in the Edit Connection Details portlet become editable.

4. Modify any of the fields in the Edit Connection Details portlet.

5. Click File, Save or File, Save and Close to save your changes to the connection profile.

Delete a Database Connection Profile

You can delete existing connection profiles on the Connect tab.

To delete a database connection profile

1. Click the connection profile you want to delete in the Recent Profiles or Connection Profiles portlet of the Connect tab.

2. Click Edit, Delete.

A confirmation dialog appears.

3. Click OK to delete the profile.


You can specify how OpenROAD Workbench displays applications and components in its list view—as icons only, simple lists, detailed lists, or lists with properties.

Customize the Workbench Window Display

You can customize the appearance of the Workbench window by hiding its toolbar or status bar, or by changing the display format of certain portlets.

To hide the toolbar

Click View, Toolbar, Display to clear the option.

The toolbar is removed from the Workbench window.

To hide the status bar

Click View, Status Bar to clear the option.



To change the display format of a portlet's list view

Use the following View menu commands to change the display format of a portlet (for example, the Connection Profiles portlet on the Connect tab):

Icon

List

Details

For example, to display your connection profiles as a detailed list instead of icons, click the header bar of the Connection Profiles portlet, and then click View, Details.

Applications Portlet

The Applications portlet of the Develop tab displays all of the applications stored in the currently connected database. Database repositories contain applications:

When you select an application in the Applications portlet of the Develop tab, its components are displayed in the Components portlet. When the Applications portlet is active, you can perform the following tasks on existing applications:

Export to a text file

Rename

Delete

Compile without making an image

Create an image file

Query an image file

Document in report form

Create numbered versions

Purge all versions not included in application versions



Run the application

Debug the application

Additionally, when the Applications portlet is active, the toolbar on the Develop tab (see page 49) provides shortcut buttons to commonly used menu commands.

Refresh the Application List

In the Applications portlet of the Develop tab, you can refresh the display of applications in the list view or refresh the contents of the current application. To use the following commands, the Applications portlet must be active (click on its header bar to make it active).

To refresh the application list

Click View, Refresh Application List.

To refresh the current application

Click View, Refresh Current Application.

Display Application Versions

In the Applications portlet of the Develop tab, you can display all application versions defined in the database to which you are connected currently. To use the following commands, the Applications portlet must be active (click on its header bar to make it active).

To display application versions

Click View, Show Application Versions.

OpenROAD updates the list view accordingly and displays another column, Version, which reflects the status of each application version.

Note: For details about creating numbered versions of an application, see How You Can Create Application Versions Using the VersionApp Utility (see page 538).



Hide or Display the Status Bar

You can customize the appearance of OpenROAD Workbench by hiding or redisplaying the status bar.

To hide or display the status bar

Click View, Status Bar.

The status bar is hidden. To show the status bar again, repeat the action.

Change the Workbench Display of Applications

In the Applications portlet of the Develop tab, you can customize the display format of Workbench. For instructions, see the appropriate procedure, following. To use the following commands, the Applications portlet must be active (click on its header bar to make it active).

To display applications with a list of their properties

Click View, Properties.

The Applications portlet display changes to a list view with properties.

To display applications as a simple list

Click View, List.

The Applications portlet display changes to the List format, a simple list view with no detailed information.

To display applications as icons

Click View, Icon.

The applications are displayed as icons.

To display application details

1. Click View, Details.

Workbench returns to its default display format. This display format includes columns and column headings for the application names and developers' remarks.

2. To add additional details to this display, click View, Columns.

The Select Application Columns dialog appears.



3. Select additional details to be displayed (for example, Created By and Database Name).

Note: The choices you make here affect the list of available search options displayed in the Find Application Property dialog. For more information, see Find an Application or Component (see page 99).

4. Click OK.

Additional columns appear in the Applications portlet.

Note: Each column header is also a button. Click a column header to sort the list based on that column's contents; click again to switch between ascending and descending order.

Components Portlet

OpenROAD applications are made up of components:

The following different component types are available:

User frames

Ghost frames

User classes

External class libraries

4GL procedures

3GL procedures

Database procedures

Global variables

Global constants

Include scripts

Frame templates

Field templates



You can use these components to structure your applications however you want.

The Components portlet on the Develop tab displays components of the application selected in the Applications portlet (see page 72).

Display Application Components

You can display the components of an application in the Components portlet of the Develop tab.

To display application components

In the Applications portlet, select the application whose components you want to display.

The Components portlet displays a list of all the components in the application.

Refresh the Components List

You can refresh the display of components for a selected application on the Develop tab.

To refresh the component list

Activate the Components portlet and click View, Refresh Current Application.

Display Component Versions

You can display all component versions defined in the selected application on the Develop tab.

To display component versions

Activate the Components portlet and click View, Show Component Versions.

The list view is updated accordingly.

Note: For details about creating numbered versions of an application and its components, see How You Can Create Application Versions Using the VersionApp Utility (see page 538).



Change the Display of Components

You can customize the appearance of Components portlet on the Develop tab using the View menu.

The default display format includes a basic list of component names. You can add additional details, such as developers' remarks, component status, creation statistics, or variable information.

To add additional columns to this display

1. Activate the Components portlet and click View, Columns.

The Select Component Columns dialog appears.

2. Select additional details to be displayed (for example, Creation Date and Type).

Note: The choices you make here affect the list of available search options displayed in the Find Component Property dialog. For more information, see Find an Application or Component (see page 99).

3. Click OK.

Additional columns appear in the Components portlet.

Note: Each column header is also a button. Click a column header to sort the list based on that column's contents; click again to switch between ascending and descending order.

You can change the display format to a list view with properties, a simple list view, or icons only.

To display components with a list of their properties

Activate the Components portlet and click View, Properties.

The components display changes to the Properties format.

To display components as icons

Activate the Components portlet and click View, Icon.

All of the application's components are displayed as icons.



Specify Component Types

You can restrict the types of components displayed in the Components portlet of the Develop tab.

To restrict the types of components displayed

1. Click the Filter portlet tab on the left side of the Develop tab.

The Component Filter portlet is displayed.

Note: By default, all component types are selected.

2. Click Clear All.

All components are cleared.

3. Select the component type or types you want to display. For example, select only the UserFrame option.

4. Click OK.

The Components portlet now displays only the component types you selected.

Display Component Relationships

You can display component relationships in the Components portlet of the Develop tab using the View menu. You can select the following types of component cross-reference options:

References

Displays all the components on which the specified component depends. For example, if the selected component is a class, its superclasses are displayed and all other components to which it refers—user frames, global variables, constants, and so on.

Referenced By

Displays all components that refer to the specified component. For example, if the selected component is a global variable, all components that refer to it are displayed.

Generated From

Indicates whether the specified frame, or one of its fields, was generated from a frame or field template

Default: References

Note: Cross-reference information is available only for compiled applications in the database repository, not for application images.



Being able to cross-reference components in large applications is important because it lets you know at a glance whether a particular component depends on any other. For example, if you are considering changing the data type of a global variable, you can easily find the components that depend on it and make any necessary code adjustments.

To view the cross-references

1. Click a user frame component in the Components portlet.

2. Click View, Cross Reference.

The References window appears:

3. Click the + icon to the left of the top level component.

4. The root component expands in a tree structure:

If the user frame contains other components, + icons appear next to them, indicating that these branches in the tree can also be expanded.



5. Select one of the components in the hierarchy and then do one of the following:

Click View, Referenced By

The References window changes, showing which component calls that user frame.

Click View, Generated From

The References window shows all components that use the selected component.

6. Click File, Close.

The References dialog closes.

Creating Applications 81

Chapter 4: Creating Applications This section contains the following topics:

Create an Application (see page 81) Included Applications (see page 87) Application Component Development (see page 90) How You Can Work with Applications and Components (see page 95) Run Applications (see page 103)

This chapter shows you how you can develop an application in OpenROAD Workbench, which includes visual editors that enable you to design the frames, menus, and other user interface components using standard point-and-click, drag-and-drop techniques.

You can use the various editors to work on a single application or component, or several applications and components simultaneously. Because you save the components of an application individually, you need not save the application itself unless you want to freeze it at a certain point by creating a numbered version.

You can run the application or any of its components at any point during the creation process to test them. After running the application or component in its current state, you can return to editing mode and make adjustments.

Create an Application

When OpenROAD Workbench is open, you can create a new application and store it in the database to which you are connected currently.

To create an application and set its basic properties

1. Click the Develop tab.

2. Click File, New Application.

The Create Application dialog appears.

Note: For a description of the fields on this dialog, see Application Properties (see page 82).

3. Enter the application name (for example, My_Application).

4. Select a database option from the Database drop-down.

5. Enter a comment about the application in the Remark entry field, if desired.

6. Enter any parameters in the Parameters field.



7. Enter the name of a globals initialization file, if desired.

Note: Click the button at the right end of the field to browse the location of a file.

For more information on using an initialization file, see Specify Initial Values for Global Variables and Constants (see page 85).

8. Enter any database flags in the Ingres Flags field, if desired.

9. Accept the Default application icon, or clear the check box and browse for an alternative icon file.

Note: This option specifies the icon that is displayed when the application's frames are minimized.

10. Click Create.

Your application appears in the Workbench's detailed list view.

Note: You can modify any of these properties subsequently using the Application Properties dialog.

More information:

Application Properties (see page 82) Specify or Modify Application Properties (see page 84) Specify Initial Values for Global Variables and Constants (see page 85)

Application Properties

You can set the following properties using the Create Application dialog or modify them later using the Application Properties dialog.

Name

Specifies a valid OpenROAD name for the application.

Important! In OpenROAD, the following objects can be named: applications, classes, components, databases, database tables and columns, parameters, procedures, user events, and variables. The rules for these names, or alphanumeric identifiers, are as follows:

Names can contain up to 32 characters.

Names must begin with an alphabetic character or an underscore (_).

In addition to letters and numerals, a name may contain these characters: #, @, and $.

Names are not case sensitive.

A name may not be a reserved word (see the 4GL Keywords section in the “System Constants and Keywords” appendix of the Language Reference Guide).



Starting Component

Indicates the frame or procedure in the current application (but not from an included application) that is used as the entry point for the application.

Because this field is initially empty for a new application, you set this property after creating the rest of your application's components. For instructions, see Specify or Modify Application Properties (see page 84).

Note: This property is not available on the Create Application dialog.

Database

Specifies the database whose data the application will access when it executes. You can select one of the following values:

Current

Uses the repository database to which you are currently connected

None

Specifies no database. In this case, the application must explicitly open a database connection using the Connect method on the DBSessionObject.

For more information on the Connect method and the DBSessionObject, see the Programming Guide, the Language Reference Guide, and the System Reference Summary.

Named

Lets you enter the name of a database other than the one to which the application is currently connected

Default: Current

Remark

Specifies an optional comment or description about the application

Parameters

Specifies any optional command line parameters for running the application during the current development session.

Note: For details about specifying runtime parameters for a session, see Specify or Modify Application Properties (see page 84).

Globals Initialization File

Specifies an optional text file containing the initial values for the application's global variables and constants during the current development session.

Note: For details about creating a file of initial values, see Specify or Modify Application Properties (see page 84) and Specify Initial Values for Global Variables and Constants (see page 85).



Ingres Flags

Specifies any optional Ingres flags to be included with the CONNECT statement.

Note: For information about using the RunImage utility to override the DBMS flags specified for an application upon creation, see Managing and Deploying Applications (see page 537). For more information on flags that can be used with the CONNECT command, see CREATEDB in the Ingres Command Reference Guide.

Icon

Specifies the graphic image that is displayed when a running application's frames are minimized. If a frame is explicitly provided with an icon, that icon is displayed when the frame is minimized. If a frame has no icon, the icon associated with the application is displayed instead.

You can specify an image file containing a custom icon or use the default OpenROAD icon, shown in the following illustration:

Note: Although bitmap (.bmp) files may work in some cases, icon (.ico) files are recommended.

More information:

Create an Application (see page 81) Specify or Modify Application Properties (see page 84)

Specify or Modify Application Properties

After creating an application, you may want to modify some of its properties, such as specifying a starting frame after you have actually created several components or replacing the default icon with a custom graphic.

To specify or modify an application's properties


2. Select the application in the Applications portlet.

3. Click the Application Properties portlet tab.


The application properties are opened for editing.



5. Click the control button to the right of the Starting Component entry field to specify a starting component, or entry point, for the application, if desired.

The Select Starting Component dialog appears. This dialog lists all executable components defined to an application, including frames, frame templates, and procedures. (Other types of components, such as user classes and global variables, are not executable and, therefore, cannot be starting components.) For new applications, this dialog is initially empty.

Note: If you do not specify a starting component for an application, the Select Starting Component dialog will prompt you for one when you run the application in Workbench.

6. Select the component and click OK.

The Select Starting Component dialog closes.

7. Set any remaining properties.

Note: For more information on application properties, see Application Properties (see page 82).

8. Click File, Save and Close to save and close the application properties.

How You Can Customize a Session for an Application

You can customize your current development session for an application by setting the following values for the duration of the development session:

Initial values for the global variables and constants in the application

You can create files to store different sets of initial values. This feature is useful if, for example, you want to change the application's language for a session.

Command line parameters for running the application

You can specify parameters that determine how to run the application during the current development session.

Specify Initial Values for Global Variables and Constants

You can change the initial values of global variables and constants in an application by performing the following procedures:

Create an initialization file to store the global values.

Specify which initialization file to use for the current session.



To create an initialization file

Use an external text editor to create a text file containing the names of variables, constants, and their initial values. For each variable or constant to be initialized, the file should have one line with the following format:

global name=value

name

Specifies the name of the global variable or global constant

value

Specifies the initial value to assign to the global or constant

You can create any number of files. For example, you might have one file for each foreign language used in your organization.

To specify an initialization file for the current OpenROAD session


2. Select your application in the Applications portlet.




5. Click the control button to the right of the Globals Initialization File field.

OpenROAD displays a standard File Selection dialog.

6. Select the text file containing the global values you want to use for your application, and then click Open.

Alternatively, enter the name of the file.


Notes:

An alternative way to specify the file name is to use the -g parameter when you run the application with the RunImage utility. For more information about using the RunImage utility, see Run an Application from an Image Using the RunImage Utility (see page 580) and RunImage Utility Parameters (see page 64).

For more information about defining global variables, see Create a Global Variable (see page 449).



Specify Runtime Parameters for a Session

You can also specify command line parameters to customize how an application runs during a development session. These parameters may be either positional or keyword parameters, and they take effect when you run the application with the Run command or with the RunImage utility.

To specify runtime parameters for an application






5. Enter the desired parameters for running the application in the Parameters field.

For more information about the fields on the Application Properties portlet, see Application Properties (see page 82).


Note: For details about running an application using the Run command see the chapter “Debugging Your Application” in the Programming Guide. For more information about the RunImage utility, see Run an Application from an Image Using the RunImage Utility (see page 580).


OpenROAD lets you include other applications in your new application so that you can draw from them as if they were libraries.

How Applications Are Included

When you are developing an application, OpenROAD Workbench lets you use frames and other components that are part of other applications. To refer to these components, you include in your current application the applications that contain the components you want to use. If the included application is in an image file, OpenROAD opens a file descriptor only once for each instance of an included application, regardless of the number of times the included application is referenced within an application.

These included applications serve as libraries in which you can store components that are shared among various applications. An included application can be stored in the database or as an image file.



Default Included Application

OpenROAD Workbench provides one included system application for each application that you create—the core application library. This default included application contains frame templates that you can use as the starting point for the frames you create.

Even though the core application is not listed in the Included Applications portlet (Develop tab), its components are available to all applications. For example, when you create a new user frame, the core application library provides dialog_box, empty_frame, and menu templates as starting points. For a list of core templates, see Frame Templates (see page 284).

The core application library also contains many predefined, general-purpose frame and field templates, and specialized functions. The templates are reusable application components encapsulating user classes, 4GL scripts, and menus that enable the developer to concentrate on assembling code, rather than coding application “building blocks.”

Additional OpenROAD Applications

In addition to the core included application, OpenROAD Workbench provides a set of predefined application libraries that developers can use in their applications, including the following:

finance

Contains specialized components for use with financial applications

mastdetl

Contains templates for use in sophisticated database-oriented applications

stat

Contains statistical functions

misc

Contains various templates requiring some level of 4GL programming to create self-contained fields

Subsequent chapters provide more information about the frames and fields that you can create using the templates in the core included application as well as the supplementary application libraries.

Note: For more information about the functions provided in these libraries, see the Language Reference Guide.



Specify Included Applications

After you specify an included application, you can use any of its components in the current application. When OpenROAD calls a component in a running application and cannot find that component in the application itself, it looks through the included applications in the order in which you have listed them.

Note: If you add a component to an application that is in an included application that is being edited, you cannot reference the component in the first application until you close and reopen the second application.

To include an application in your application



3. Click the Included Applications portlet tab.

Note: Even though the default core application library is not displayed in this window, its components are available to all applications.

4. Beneath the Included Applications portlet header, click the Insert Application icon:

Note: If one or more applications are already included, the Insert Application Above and Insert Application Below icons are displayed. Select an included application and then click the appropriate icon.

The Add Included Application dialog appears. This dialog lets you add an application from the current database or an image (.img or .pkg) file.

5. Select the Include from Image File option.

The Add Included Application dialog changes slightly.

6. Click Browse.

A standard File Selection dialog appears.

7. Select each library that you want to include (for example, misc.pkg).

Note: To specify any of the OpenROAD predefined application libraries, the image file name used is the application name with an extension of .pkg.

8. Click Open.

The name of the file you selected is displayed in the Image File field.

Application Component Development


9. Click OK.

The Included Applications portlet now displays the selected application library as an included application.

10. Repeat Steps 4–9 to include any other applications.

The Include Applications window now displays all of the specified application libraries as included applications.


OpenROAD applications are made up of components. There are many different component types available for you to use when structuring your applications. For more information, see Components Portlet (see page 75).

Each type of component can contain different kinds of information. For example, a user frame is typically a complex component that has both 4GL code and visual elements, such as fields and menus, associated with it. A constant or global variable, on the other hand, is simpler and has only declaration information, such as a data type, associated with it.

Some components can be generated automatically while others must be hand-coded. A third group, including frames, can be produced using both methods.

Each of the primary editors is geared toward managing its particular component type. The editor is as simple or complex as it needs to be to provide all the functionality you need to create, edit, and maintain the component.

Create a Component

Using the Components portlet of the Develop tab, you can create components in your applications.

To create a component

Do one of the following:

Click an icon on the Component portlet's toolbar.

Activate the Components portlet, click File, New, and then select the desired component from the slide-off menu.



The appropriate Create Component dialog appears.

Each dialog lets you do the following:

Specify a valid OpenROAD name for the component

Add a descriptive remark

Select an application or library and a template, where applicable

Access the appropriate editor

More information:

Component Types (see page 91)

Component Types

Descriptions and associated icons for each application component type follow. The corresponding editor appears when you click its icon on the Component portlet's toolbar (Develop tab):

User Frames

A user frame consists of a form that you design, a script whose code you write, and, sometimes, a menu that you create. The following is the icon to open the Create User Frame dialog:

Note: For more information about user frames, see Creating Basic Frames (see page 105).



Ghost Frames

A ghost frame is a frame that has no form, but otherwise functions like a regular frame. A ghost frame can be called from other frames and procedures and receive user, database, and terminate events. The end user does not interact directly with a ghost frame. Ghost frames are most useful for handling operations that run continuously without user intervention.

The following is the icon to open the Create Ghost Frame dialog:

Note: For more information ghost frames, see Ghost Frames (see page 465).

User Classes

A user class is a set of developer-defined attributes (characteristics) and methods (behaviors) that you can use to refer to multiple data items as a single entity. The following is the icon to open the Create User Class dialog:

Note: For more information about user classes, see Working With Classes (see page 411).

External Class Libraries

An external class defines the class properties, methods, and events for one or more external objects. The following is the icon to open the Create External Class Library dialog:

Note: For more information about external classes, see Create and Register External Class Libraries (see page 428).



4GL Procedures

A 4GL procedure is a set of 4GL statements that you can call by name in an application. 4GL procedures are written in fourth-generation languages such as Java. The following is the icon to open the Create Procedure dialog:

Note: For more information about 4GL procedures, see Procedures (see page 456).

3GL Procedures

A 3GL procedure is a set of 3GL statements that you can call by name in an application. 3GL procedures let you access code written in third-generation languages, such as C or C++. The following is the icon to open the Create 3GL Procedure dialog:

Note: For more information about 3GL procedures, see Procedures (see page 456).

Database Procedures

A database procedure is a set of SQL statements that you can call by name in an application. Database procedures let you call data-oriented procedures that are stored and executed within the database server. The following is the icon to open the Create Database Procedure dialog:

Note: For more information about database procedures, see Procedures (see page 456).



Global Variables

A global variable is a variable that you can use in any script or procedure in an application. It contains data that any script or procedure in the application can access. The following is the icon to open the Create Global Variable dialog:

Note: For more information about global variables, see Adding Other Components to Your Application (see page 447).

Global Constants

A global constant is a value to which you give a name. You can then use this name to represent the value any place in an application. The following is the icon to open the Create Global Constant dialog:

Note: For more information about global constants, see Global Constants (see page 454).

Include Scripts

An include script is a segment of 4GL code that you can include in any script or procedure in an application. The following is the icon to open the Create Include Script dialog:

Note: For more information about include scripts, see Writing Scripts and Procedures (see page 435).

How You Can Work with Applications and Components


Frame Templates

A frame template is a frame that you use as a model for creating similar frames. Every frame that you create is based on a frame template that determines many of the visual and behavioral characteristics of the frame.

The following is the icon to open the Create Frame Template dialog:

Note: For more information about frame templates, see Creating Basic Frames (see page 105) and Generating Frames from Predefined Templates (see page 281).

Field Templates

Field templates are prototypes from which you can generate individual fields on a form. The following is the icon to open the Create Field Template dialog:

Note: For more information about field templates, see How You Can Add Fields to a Frame (see page 154) and Generating Frames from Predefined Templates (see page 281).


The Develop tab's toolbar buttons and menu commands let you perform the following basic operations with applications and components:

Edit

Save

Find

Rename

Delete



How You Can Edit an Application or Component

To edit an existing application in OpenROAD Workbench, use either of the following methods:

Double-click the application or component using the primary mouse button.

Select the application or component name, and then click File, Open.

You can edit several components at the same time, even if these components belong to different applications. When you open a component using either of the preceding methods, Workbench starts the appropriate editor for the component type. (For more information about what icons open which editors, see Component Types (see page 91).)

Working Copies

When you open an application, OpenROAD Workbench creates working copies of its components for you to modify using the appropriate editors. The working copy of a component can be one of the following:

Current version

Specifies a component that has been saved to the database and is available to all developers

Private version

Specifies a component that only you can work with

The OpenROAD version control feature lets any number of developers work on an application simultaneously. However, only one developer at a time can modify an individual component.

Each time you open a component to edit it, Workbench checks the component out of the database under your user name and locks it so that other developers cannot change it. Correspondingly, if the component is currently being edited by another developer, you can only view the component as it was before the current user began editing it. After the current user saves the component and closes the editor, then you may see the changes and make your own edits.



Component Status

The Components portlet of the Develop tab displays the status of a selected application. For example, the Status column displays “Saved” for the listed application components:

Possible statuses include the following:

Saved

Indicates that the current version is saved to the database. If you open the component for viewing or editing, the status subsequently changes to “Viewing” or “Editing,” respectively. Other users will see the status “Checked Out” until you close the editor.

Private

Indicates that you have created a private version of the component, which is usually different from the current version. All of the operations you perform will use the private version. For example, if you open the component for viewing or editing, you will see the private version. Likewise, if you run the application or make an image of the application, OpenROAD uses your private version. As long as you have a private version of a component, you do not have access to the current version.

Making a private version of a component lets you make changes and test them without affecting other developers. Others have no access to your private version; if another developer runs the application, OpenROAD uses the current version of the component.

Checked Out

Indicates that another developer has created a private version of the component. Therefore, you may view, but not edit, the current version.



Editing

Indicates that you have opened the component for editing. If you have a private version of the component, you will be editing the private version.

Viewing

Indicates that you have opened the component for viewing. If you have a private version of the component, you will see the private version.

Note: Except for your own actions, the displayed status reflects the status of the components of an application at the time the component list is first displayed. For example, if during your session, another developer creates a private version of a component, that component's status is still displayed as “Saved.” To update the component list, activate the Components portlet, and then click View, Refresh. (If you have any components open, this option is not available.)

Options for Saving Components

After creating or editing a component, you must save it. Each OpenROAD editor or portlet provides several commands on its File menu for saving working copies of your components:

Save

Stores the working copy of the component in the database and makes it the current version. If you are editing a private version of a component, the private version disappears. The editor or portlet remains open.

Save and Close

Replaces the previously saved version, which becomes immediately available to the rest of the development team as the “official” version. If you made a private copy, the private copy no longer exists.

Save Private

Specifies that the working version of the component becomes the private version. The current version is not affected.

Revert to Last Saved

Replaces the working copy. If you are editing the current version, the working copy is replaced with the current version. If you are editing a private version, you are prompted to revert either to the private version or to the current version of the component.

Save As

Saves the working copy as a new component with a name that you specify; the original component is unaffected. The editor remains open, and if you make further changes and save them, the changes will apply to the new component.



Save As New Template

Saves the working copy as a frame template if you are editing a user frame; the original component is unaffected. The editor remains open, and if you make further changes and save them, the changes will apply to the new component.

Save As New Version

Creates a new version of the component and leaves the original component unaffected. (For more information about creating and viewing component versions, see Managing and Deploying Applications (see page 537).)

Close

Opens the Close dialog when you select this command or you click the system Close button (X) in the upper right corner of an editor.

The Close dialog lets you discard any changes made during the current session, cancel the Close command, or save the changes using one of two options: Save or Save Private.

Find an Application or Component

You can locate applications or components in the currently connected database using the Find Property dialog. For instructions, see the appropriate procedure, following.

To locate an application in the database

1. Click the Develop tab and then click in the Applications portlet.

2. Click Edit, Find.

The Find Application Property dialog appears.

This dialog lists the default column settings, Name and Remark, as search options. However, if you customized the Develop tab by adding additional columns to its list view (Applications portlet), then this dialog changes accordingly to provide additional options that correspond to the specified columns.



For example, if you selected the Created By and Database Name columns previously using the Select Application Columns dialog, the Find Application Property dialog displays these columns as additional search options:

Note: For more information about the Select Application Columns dialog, see Change the Workbench Display of Applications (see page 74).

3. Select one of the options as the basis for your search.

4. Enter the application name (or applicable search string) in the Value field.

5. Set the search criteria using one of the Match options and optionally select the Options check box to ignore case.

6. Click Find.

The specified application—if found—is highlighted in the Applications portlet.

To find the next occurrence, if applicable, click Edit, Find Next.

More information:

Change the Workbench Display of Applications (see page 74)



To locate a component in a specified application

1. Select the application in the Applications portlet of the Develop tab.

2. Click in the Components portlet to activate it.

3. Click Edit, Find.

The Find Component Property dialog appears.

This dialog lists the default column settings, Name, Remark, and Status, as search options. However, if you customized the Develop tab by adding additional columns to its list view (Components portlet), then this dialog changes accordingly to provide additional options that correspond to the specified columns.

Note: For more information about the Select Component Columns dialog, see Change the Workbench Display of Components (see page 77).

4. Select one of the options as the basis for your search (for example, Remark).

5. Enter the component name (or applicable search string) in the entry field.

6. Set the search criteria using one of the Match options and optionally select the Options check box to ignore case.

7. Click Find.

The specified component—if found—is highlighted in the Components portlet.

To find the next occurrence, if applicable, click Edit, Find Next.

More information:

Change the Workbench Display of Components (see page 77)

Rename Applications and Components

You can rename an application or component using the Rename dialog. For instructions, see the appropriate procedure, following.

To rename an application


2. Click File, Rename.

The Rename Application dialog appears.

3. Enter the new name for the selected application.

4. Click OK.

The application is renamed.



To rename a component in the current application

1. Select the component in the Components portlet of the Develop tab.

2. Click File, Rename.

The Rename Component dialog appears.

3. Enter the new name for the selected component.

4. Click OK.

The application is renamed.

Delete Applications and Components

You can delete an application or component. For instructions, see the appropriate procedure, following.

Notes:

You can also use the DestroyApp and PurgeApp utilities to delete applications and components, respectively.

When you delete a component or application that is referenced in other components or applications, you are asked to confirm the deletion. But OpenROAD does not track dependencies; therefore, if you run referenced applications, you will likely receive compile errors.

To delete an application



A standard confirmation dialog appears.

3. Click OK to confirm the deletion, or click Cancel to abort the Delete command.

The application is deleted.

Run Applications


To delete a component in the current application

1. Select the component in the Components portlet of the Develop tab.



3. Click OK to confirm the deletion, or click Cancel to abort the Delete command.

The component is deleted.

More information:

Delete an Application Using the DestroyApp Utility (see page 542) Delete all Numbered Versions of a Component Using the PurgeApp Utility (see page 544)

Run Applications

Without leaving OpenROAD Workbench, you can run your application as the end user sees it. This is a convenient way to test an application as you develop it. You can run an application at any point during the development process.

You can run a single application or multiple applications. For instructions, see the appropriate section, following.

Run a Single Application

When you run an application, OpenROAD Workbench always uses the working version, if it exists, which includes any changes you have made to any application components, even if they have not been saved. Any components that are not compiled are automatically compiled first. If there are compilation errors, Workbench will not run the application.

To run an application

1. Select the desired application you want to run in the Applications portlet of the Develop tab.

2. Click Run, Run.

Note: The Run command always runs the current application. If the Applications portlet is active, the current application is the selected application. If the Components portlet is active, the current application is the application whose components are displayed.

If a starting frame or component was not specified when the application was created, the Select Starting Component dialog appears.

Run Applications


3. Select an executable component.

4. Click OK.

Workbench runs the application.

Run Multiple Applications

You can run several applications concurrently in OpenROAD Workbench. After you start the first application, select another application and click Run, Run. You can run any number of different applications, but no more than one instance of the same application at the same time.

Clicking the Stop toolbar button (or clicking Run, Stop) stops only the current application. If you want to stop another application, make it the current application and then click the Stop toolbar button.

How You Can Use an Image File

After you have developed and tested an application, you can create an image, which is a version of an application that is stored in an operating system file outside of the database of the application. Then users can run the application from the image file.

More information:

Start OpenROAD Using RunImage (see page 66) Run an Application from an Image Using the RunImage Utility (see page 580)

Creating Basic Frames 105

Chapter 5: Creating Basic Frames This section contains the following topics:

How You Can Create Basic Frames (see page 105) Frame Editor (see page 109) Alternative Methods for Creating Frames (see page 142) How You Can View and Modify Frames (see page 146) How You Can Test Frames (see page 146) Delete a Frame (see page 149)

OpenROAD Workbench lets you create new frames based on predefined templates. Templates enable you to provide consistency in appearance and behavior among the frames you create. This chapter describes how to create simple, basic frames using the empty_frame, dialog_box, and menu frame templates.

Later, you will learn how to use more complex frame templates that are paired with assistants in order to create automatically generated frames. You will also learn how to create ghost frames.

This chapter describes in detail how to use the Frame Editor, the primary editor for user frames and probably the most important visual editor in the Workbench development environment.

How You Can Create Basic Frames

You can create a basic frame, a frame based on a template that does not use an assistant, in OpenROAD Workbench by performing the following basic steps.

1. Create an empty frame in your desired application, basing it on a frame template.

2. Set properties for the new frame in the Frame Editor using the Property Inspector.

Note: Frame properties include various options you can set to determine how the frame should look and behave. For more information, see Set Frame Properties (see page 113).



3. Use the Frame Editor to add content to the form.

A form is a two-foot by two-foot “canvas” that lies beneath a frame's window. It is the portion of the frame where the user displays or modifies data, views illustrations, reads instructions, and selects options. If you use one of the predefined frame templates, default content is created, complete with fields and controls. You can also specify one of your own templates from the current application or any included applications instead.

As the application developer, you control the content and the format of the form. You lay out and specify the fields of a form with the Frame Editor. The Frame Editor provides a palette of fields that you can add to your form and the tools for manipulating the fields.

4. Create a menu bar, if needed.

A menu bar contains a set of pull-down menus available on the frame. Although you control the content of the menu bar (the menu titles and individual menu items), the format of the menu bar itself is determined by your window toolkit. For more information about creating menus, see Creating and Modifying Menus (see page 379).

5. Create a toolbar, if needed.

A toolbar consists of a set of iconized items from which the user makes a selection by clicking the mouse pointer on it. Toolbar items typically consist of buttons that provide shortcuts for frequently used menu commands or for easy access to other features or frames. For more information about creating toolbars, see Creating Toolbars (see page 399).

6. Write the frame script.

You use the 4GL programming language to write scripts for your frame. You can write your scripts with the Script Editor—the OpenROAD text editing facility—or with your system editor. For more information about writing scripts, see the chapter “Writing Scripts and Procedures” in the Programming Guide.

7. Test the frame.

You can test the frame at any point during development to see how your frame looks and acts when the application is running. For more information, see How You Can Test Frames (see page 146).

After you create the frame (Step 1), you can complete the other tasks in any order. In fact, you can open several Frame Editor windows simultaneously to work on more than one frame at the same time. And you can test the frame as many times as you want while you are developing it.



Create an Empty Frame

You can create an empty frame on the Develop tab.

To create an empty frame

1. Select your application in the Applications portlet of the Develop tab.

The application's components, if any, are displayed in the Components portlet.

2. Click in the Components portlet to make it active.

3. Click File, New, User Frame.

The Create User Frame dialog appears.

4. Enter a valid OpenROAD name for the component in the Name entry field (for example, My_Main_Frame).

5. (Optional) Enter a comment for the component in the Remark field.

6. Accept the default application library, Core, in the Application list field.

The Core library contains many frame templates, three of which are simple, basic frame templates:

dialog_box template

Creates a standard dialog with no window control facilities, no menu bar, and no scroll bars

empty_frame template

Creates a window with no predefined buttons or menu

menu template

Creates an independent window with a menu bar and optional scroll bars and window control facilities

Note: You can specify one of your own templates from the current application or any included applications instead.

7. Accept the default template, standard.

8. Click Create.

OpenROAD opens the Frame Editor, containing the default frame based on the template you specified. By default, this frame has a form that is completely empty—no menu bar and no default toolbar.

If you switch back to the Workbench window, you will see that the empty frame has been added to the Components portlet.

Note: You continue to develop this form interactively by setting frame properties, adding fields, and specifying field properties as you follow along in this and other chapters.



Create a Dialog

To create a standard dialog box, you follow the same basic steps as creating a frame.

To create a standard dialog






4. Enter the component name in the Name field (for example, My_Dialog).


6. Accept the default application library, Core, in the Application field, and then select the dialog_box template in the Template field.

7. Click Create.

OpenROAD opens the Frame Editor, displaying the frame based on the template you specified. By default, this frame has a form that is empty except for two standard buttons, OK and Cancel.

OpenROAD also adds the dialog to the Components portlet as a user frame component.

Create a Menu Frame

A menu frame is an otherwise empty frame except that it contains a menu bar.

To create a menu frame






4. Enter the component name in the Name field (for example, My_Menu_Frame).


Frame Editor


6. Accept the default application library, Core, in the Application field, and then select the menu template in the Template field.

7. Click Create.

OpenROAD opens the Frame Editor, displaying the frame based on the menu frame template. By default, this frame has a form that is empty except for the menu bar with a single menu item, File.

The menu frame is also added to the Components portlet as a user frame component. You can continue to develop this form, setting frame properties, adding fields, and specifying field properties in this and other chapters.

Frame Editor The Frame Editor is the primary editor in the OpenROAD development environment for creating, viewing, and modifying frames. The following is the Components portlet icon to open the Create User Frame dialog:

The Frame Editor consists of the following components:

A floating menu bar

The Property Inspector

Field, font, and color palettes

Frame Editor


These components appear by default with the frame being edited, as shown in the following illustrations:

Note: Of the three palettes, only the field palette appears initially by default. You must manually open the others from the View menu to display them.

Frame Editor


In the Frame Editor, you can do the following:

Edit frames

Add and modify fields

Specify properties for frames and fields

Save a copy of an existing frame either as a new version, a new frame with a different name, or a frame template

Access other editors including the Menu Editor, Toolbar Editor, and Script Editor

Open an Existing Frame

You open existing frames in an application from the Components portlet of the Develop tab.

To open an existing frame

1. Click the application containing the frame you want to open in the Applications portlet of the Develop tab.

Application components are displayed in the Components portlet.

2. Select the frame in the Components portlet.


The frame is opened in the Frame Editor.

Field Palette

The Frame Editor provides a palette of icons that you can use to add fields to your form. It also contains the necessary tools for manipulating these fields:

An icon for each type of simple field that you can create

The Select Mode icon to select fields on the form

The Free Trim and Box Trim icons to enter and edit text, such as titles and field labels

Frame Editor


The Frame Editor's field palette contains the following icons:

Note: The palette does not include composite fields, such as table fields and subforms. You create these fields with the Group menu commands. The various field types and procedures for adding fields to a form are detailed in How You Can Add Fields to a Frame (see page 154).

Frame Editor


Hide or Display the Field Palette

By default, OpenROAD always displays the field palette with the Frame Editor. You can hide the palette by clearing the Field Palette option on the View menu.

When the palette is not displayed, you can use the Insert, Field submenu to add new fields to your form:

Set Frame Properties

After creating a new frame, you can use the Property Inspector to set its properties. These settings affect how the frame looks and behaves and also impacts how fields look and behave when placed on the frame.

Frame properties include things such as the frame's title, return value, associated icon, and whether the frame is resizable. The following procedure describes the basic steps to set frame properties. The sections following describe the properties that you can set for a frame—the more complex properties are then discussed in greater detail.

To set the properties of a frame

1. Open the frame in the Frame Editor (see Open an Existing Frame (see page 111)).

The Property Inspector for the frame appears.

2. Scroll through the Property Inspector's list of properties to locate the property you want to change.

Frame Editor


3. Set the value of the property.

For complete descriptions of each frame property, see Available Properties (see page 114).

4. Click File, Save on the Frame Editor's floating menu bar to save the frame when you are finished setting properties.

Available Properties

The following properties are common to the Frame Editor and the Frame Template Editor, which is discussed in Alternative Methods for Creating Frames (see page 142). For more information on property prefixes, see Property Setting Prefixes (see page 138).

BgBitmap

Specifies the graphic image to be used for the form's background, if set to Bitmap

Default: No Bitmap

For more information, see How You Can Set the Background of a Form (see page 124) and Use a Bitmap for the Background (see page 125).

BgColor

Specifies a color from a color palette for the form's background

Default: CC_PALE_GRAY

For more information, see How You Can Set the Background of a Form (see page 124) and Set Background Color (see page 126).

BgPattern

Specifies a background pattern for the form. Valid options include:

FP_BITMAP FP_CLEAR FP_CROSSHATCH FP_DARKSHADE FP_HORIZONTAL FP_LIGHTSHADE FP_SHADE FP_SOLID FP_VERTICAL FP_DEFAULT

Default: FP_DEFAULT

For more information, see How You Can Set the Background of a Form (see page 124) and Specify Background Pattern (see page 125).

Frame Editor


CurMode

Specifies a frame mode for the current frame. Valid options include:

FM_UPDATE FM_QUERY FM_READ FM_USER1 FM_USER2 FM_USER3

Default: FM_UPDATE

For definitions of each of these options, see Frame Modes (see page 123).

DataType

Specifies the data type for the value returned to any frame that calls this frame

Default: the data type specified when the frame was created

For more information, see Set a Return Value (see page 120).

HasScrollbars

Specifies whether the running frame is displayed with scroll bars. Possible values are:

TRUE

Displays scroll bars

FALSE

Does not display scroll bars

Default: FALSE

HasStatusBar

Specifies whether the running frame displays an informational status bar at the bottom of the window. Possible values are:

TRUE

Displays the status bar

FALSE

Does not display the status bar

Default: FALSE

Frame Editor


IsAutoSized

Specifies whether the initial size of the running frame is just large enough to display all the fields on the form. Possible values are:

TRUE

Auto-sizes the frame

Note: If IsAutoSized is set to TRUE, OpenROAD ignores any values specified for WindowWidth and WindowHeight.

FALSE

Does not auto-size the frame

Default: FALSE

IsBordered

Specifies whether the running frame is displayed with a thick border. Possible values are:

TRUE

Displays the running frame with a thick border

FALSE

Does not display the running frame with a border

Default: TRUE

Note: The IsBordered, IsClosable, IsMaximizable, IsMinimizable, IsPopup, IsResizeable, IsTitled, and IsToolWindow properties are somewhat interdependent; however, not all combinations are possible. For more information, see the Language Reference Guide.

IsClosable

Specifies whether the running frame can be closed using a standard Close button in the upper right corner of the frame. Possible values are:

TRUE

Specifies that the standard Close button is used

FALSE

Specifies that the Close button is not used

Default: TRUE

Frame Editor


IsMaximizable

Specifies whether the running frame can be maximized to full-screen size using a standard Maximize button in the upper right corner of the frame. Possible values are:

TRUE

Specifies that the Maximize button is used

FALSE

Specifies that the Maximize button is not used

Default: TRUE

IsMinimizable

Specifies whether the running frame can be minimized to an icon using a standard Minimize button in the upper right corner of the frame. Possible values are:

TRUE

Specifies that the Minimize button is used

FALSE

Specifies that the Minimize button is not used

Default: TRUE

IsNullable

Specifies that the return value can have a null value

Default: FALSE

IsPopup

Specifies whether the frame is treated as a pop-up frame when called. Pop-up frames are frames that remain on top of the calling frame as long as the pop-up is active. Whether the pop-up frame physically blocks the calling frame depends on the window placement setting you specify.

Note: Pop-up frames do not provide a way to minimize or maximize their windows.

Possible values are:

TRUE

Specifies that the frame is a pop-up

FALSE

Specifies that the frame is not a pop-up

Default: FALSE

Frame Editor


IsResizeable

Specifies whether the user can resize the frame by dragging one of its borders. Possible values are:

TRUE

Specifies that the user can resize the frame

FALSE

Specifies that the user cannot resize the frame

Default: FALSE

IsTitled

Specifies whether the frame has a title bar. Possible values are:

TRUE

Specifies that the frame has a title bar

FALSE

Specifies that the frame has no title bar

Default: TRUE

IsToolWindow

Indicates whether the title bar has the tool window style. The height of the title bar is slightly shorter than a normal title bar. Only a standard Close button—no Minimize and Maximize buttons—are displayed in the title bar when a frame has this style. Valid options include the following:

TRUE

Specifies that the title bar follows the tool window style

FALSE

Specifies that the title bar does not follow the tool window style

Default: FALSE

Note: This property has effect only if the IsTitled property is set to TRUE.

IsTopMost

Specifies whether the frame is to remain on top of all other running frames. Possible values are:

TRUE

Specifies that the frame remains on top

FALSE

Specifies that the frame need not remain on top

Default: FALSE

Frame Editor


StatusText

Defines the text that appears in the frame's status bar

TemplateName

Specifies the name of the frame template specified earlier when creating the user frame (or frame template)

VersShortRemarks

Specifies a comment about the frame. The comment appears in the Components portlet. If you specified a remark earlier when creating the frame, it is already displayed. You can edit the comment here.

WindowHeight

Indicates the height of the initial window for the running frame, measured in 1000ths of an inch

WindowIcon

Specifies the graphic image that is displayed when the frame is minimized, if set to Bitmap. You can use the default OpenROAD icon or specify an image file containing a custom icon.

Default: No Bitmap

Note: Although bitmap (.bmp) files may work in some cases, we recommend icon (.ico) files.

WindowPlacement

Indicates where to place the window when the frame is first displayed. Valid options include:

WP_FLOATING WP_PARENTCENTERED WP_PARENTRELATIVE WP_SCREENCENTERED (see WindowXLeft and WindowYTop properties) WP_SCREENRELATIVE

Default: WP_PARENTCENTERED

For definitions of each of these options, see Frame Positioning Settings (see page 124).

WindowTitle

Defines the text that appears in the title bar of the running frame's window

WindowWidth

Indicates the width of the initial window for the running frame, measured in 1000ths of an inch

Frame Editor


WindowXLeft

Specifies the frame's x coordinate relative to the upper left corner of the screen only if the WindowPlacement property is set to WP_SCREENCENTERED

Default: 0

WindowYTop

Specifies the frame's y coordinate relative to the top of the screen only if the WindowPlacement property is set to WP_SCREENCENTERED

Default: 0

Set a Return Value

A frame's DataType attribute, or property, is the data type of its return value. You can set a return value in the Property Inspector.

To set a return value for a frame

1. Open the frame in the Frame Editor (see Open an Existing Frame (see page 111)).

2. Click the DataType property in the Property Inspector.

The Data Type dialog appears.

3. Specify the data type for the value returned to any frame that calls this frame:

None

Simple

– Varchar

– Smallint

– Integer

– Decimal

– Float

– Money

– Date

– Nvarchar

Array

Reference

Frame Editor


4. For a Simple type: Select a base data type from the option field and specify its corresponding length, if applicable, in the Length entry field:

5. For a Reference or Array type: The Data Type dialog changes slightly:

Frame Editor


Enter an OpenROAD system class or user class in the empty field in one of the following ways:

Type in the class name and skip to Step 6.

Click the List Classes button.

The Select a Class dialog appears.

a. Select an application in the Application list.

The Class list displays system or user classes.

b. Select a class from the list.

Note: You can jump to a place in the list by typing one or more beginning characters in the empty field.

c. (Optional) Select Qualify Userclass Name if you want to qualify a selected user class with its application name as a prefix, for example, My_Application!My_User_Class.

d. Click OK.

The Select a Class dialog closes, and the class name field on the Data Type dialog is populated with the class you selected.

6. (Optional) Specify whether the return value can have a null value by selecting the Nullable option.

Frame Editor


7. Click OK.

You are returned to the Property Inspector.

8. Save the frame using one of the options on the File menu.

Frame Modes

OpenROAD provides the following frame modes for you to customize for your application:

Update (default)

Query

Read

User1

User2

User3

You can customize the biases for these frame modes to define six different frame behavior modes. For more information about each of these modes, see the Programming Guide.

When the application sets the frame to a specific mode, OpenROAD automatically sets the initial biases for each field and menu item associated with the frame to the ones specified for that mode. A field's bias determines whether the field is visible and how the user can interact with it.

This is important in a multipurpose application that uses a single frame for more than one task. For example, some users may update customer or sales information in a financial application, while others may be allowed only to examine customer and sales data. In such cases, you can use frame modes to change the bias for several or all fields simultaneously.

Whenever you create a frame, Workbench uses the Update mode as the default mode.

For more information about the frame modes, the CurMode attribute of the FrameExec class used to change the frame mode at runtime, or using frame modes and field biases in your 4GL code, see the Programming Guide.

Frame Editor


Frame Positioning Settings

The WindowPlacement property determines where a frame appears on the screen when it is called.

The available placement options are described as follows:

WP_FLOATING

Specifies that the system selects a position for the window that is out of the way of the calling frame's window

WP_PARENTCENTERED

Specifies that the window is centered in the calling frame's window

WP_PARENTRELATIVE

Specifies that the window is positioned according to the settings you specify for the WindowXLeft and WindowYTop properties; the position is measured from the upper left corner of the window of the calling frame, in 1000ths of an inch.

WP_SCREENCENTERED

Specifies that the window is centered in the middle of the screen

WP_SCREENRELATIVE

Specifies that the window is positioned according to the settings you specify for the WindowXLeft and WindowYTop properties; the position is measured from the upper left corner of the screen, in 1000ths of an inch.

Default: WP_PARENTCENTERED

More information:

Available Properties (see page 114) Property Setting Prefixes (see page 138)

Set the Background of a Form

For each frame you create, you can specify the background pattern—solid, cross-hatch, horizontal lines, bitmap, and so on—as well as the background color for the entire form.

Note: To make this task easier, use the Property Inspector's Appearance filter. For more information, see How You Can Use Property Filters (see page 137).

Frame Editor


Specify Background Pattern

You can set the background pattern for a user frame using the BgPattern property.

To specify a background pattern

1. Click the BgPattern property in the Property Inspector.

The property's corresponding option field becomes accessible.

2. Select a pattern option from the property drop-down menu.

If you selected FP_CROSSHATCH, your frame would look something like this:

3. Save your frame.

Use a Bitmap for the Background

You can apply a background graphic to a frame using the BgBitmap and BgPattern properties.

To use a bitmap for the background of your frame

1. Select the BgBitmap property in the Property Inspector.

A Browse dialog appears.

2. Click its Browse button.


3. Locate and select a graphic file.

The graphic is displayed in the Browse dialog.

Frame Editor


4. Click OK.

The value cell for BgBitmap now displays a value of <Bitmap>, but the user frame is unchanged.

5. Click the BgPattern property and replace FP_DEFAULT with FP_BITMAP.

Your user frame changes its background display to the selected bitmap.

Set Background Color

You can modify the background color of a user frame using the BgColor property.

To set the background color of a user frame

1. Select the BgColor property in the Property Inspector.

A miniature version of the Frame Editor's color palette appears.

Alternatively, click View, Color Palette to access the Frame Editor's primary color palette.

Note: Depending on your operating system and monitor, you can actually select from four color palettes: OpenROAD, System, User, or RGB (Red, Green, Blue). For more information, see OpenROAD Color Palettes (see page 126).

2. Select a color from one of the palettes.

The background color of the user frame changes accordingly.

3. Save the frame.

OpenROAD Color Palettes

Depending on your window system and monitor, you can select from four different palettes when you set the colors for a form or a field:

User

Lets you select the pale, light, or “true” version of 10 different colors plus black and white

System

Lets you apply colors specified by system-defined color constants that represent various screen elements

Frame Editor


OpenROAD

Lets you apply the OpenROAD default color mappings defined in a color table for various form elements.

For more information about using color table files, see How You Can Specify Color Tables (see page 629).

RGB

Lets you set RGB values for the color attribute, which makes it possible to define a full spectrum of custom colors

Style Sheets

Every OpenROAD frame and frame template has a style sheet. A style sheet defines the appearance of each type of field that can appear on any frame using that template. A style sheet lets you specify certain style attributes for each type of field that you can create for that frame or frame template. These style attributes include visual characteristics such as background color, font, and outline width, as well as bias settings for the field.

A style sheet contains at least one style, or model, for each type of field, and may contain up to eight styles for a field type. The first model of each field, Field Style 1, is used as a default field style. When you create a field on a form, it assumes the visual characteristics of its field style.

When you create a frame, you must specify a frame template on which the frame is based. A frame based on a frame template initially obtains its style sheet from the template. Like frame templates discussed in this chapter, style sheets enable you to develop consistent frame styles and behaviors in your application.

Create or Modify a Style

You can use the Style Editor to create a field style or modify a style sheet. The Style Editor is accessible from the Frame Editor or the Frame Template Editor.

For example, you could specify that every button on My_Main_Frame be pale gray, with red text in 8-point bold System font. This example will be used in the following procedure.

To modify a style

1. Open your frame in the Frame Editor (see Open an Existing Frame (see page 111)).

2. Select the button on the frame.

Frame Editor


3. Click Tools, Style Sheet on the Frame Editor menu bar.

The Style Editor appears, displaying the style sheet associated with the current frame.

The Style Editor has its own menu bar, as well as horizontal and vertical scroll bars so that you can access all of the model fields on the style sheet. It also has an Apply Changes button.

4. Click the model for the type of field you want to modify (for example, ButtonField).

5. Click View, Font Palette.

The default settings are System, Bold, and 8 points.

6. Change the font settings to what you want.

7. Click View, Color Palette.

A color palette appears, similar to that of the Frame Editor. By default, the Background button is selected.

8. Change the color of the element's background to what you want.

Frame Editor


9. Click Foreground and then change the foreground (text) color to what you want.

Your selection is reflected in the sample box.

10. Click Apply.

11. Click Close to close the color palette.

Your changes are reflected in the Style Editor.

Create Multiple Styles for a Field Type

If you need more than one style for a field type, you can create additional field styles on the style sheet. You can then base fields of the same type on different styles without having to modify the fields individually.

To define a second style for a field type

1. Select the field type in the Style Editor for which you want to add a new style.

2. Click Edit, Create New Field Style.

The style sheet changes slightly. For example:

3. Click the new model to define a unique field style for it.

4. Click View, Fonts Palette, and set the font characteristics you want.

5. Set any color options by clicking View, Color Palette.

6. Set any other options on the Appearance menu.

7. Set any bias modes using the Bias menu options.

Frame Editor


8. Click Apply Changes.

When you apply the changes you have made, all your field style selections are reflected in the Style Editor. For example:

Note: When you modify a field style, the changes are automatically applied to all fields on the form that are based on that field style. However, you can override the style sheet to apply a different style to an individual field; for more information, see Creating and Using Basic Fields (see page 151).

9. Save the user frame.

Note: A style sheet is part of a specific frame, rather than being an application component. However, you can use a particular frame's style sheet with other frames. For more information, see Use a Frame Style with Other Frames (see page 130).

Use a Frame Style with Other Frames

Each OpenROAD frame or frame template is associated with its own style sheet. However, you can share style sheets between frames in two ways:

Save a frame's style sheet as a frame template or file

After saving it as a template or file, you can apply it to other frames.

Apply a frame template style sheet to shared frames

For instructions, see the appropriate procedure, following.

To save a style sheet as a frame template

1. Open the frame containing the style sheet you want to share in the Frame Editor.

2. Make any necessary modifications to the style sheet.

Frame Editor


3. Click File, Save As New Template in the Frame Editor.

The Save As New Template dialog appears.

4. Specify a name for the frame template (for example, My_Main_Frame_Template).

The name of the frame defaults to the New Name field, but you must give the template a different name because two components cannot have the same name.

5. Click Save.

OpenROAD saves the frame as a frame template and displays it in the Frame Template Editor. The frame template can be blank, containing only the frame style sheet, or it can include individual fields or 4GL code as part of the template.

6. Click Close to exit the Frame Template Editor.

For more information about creating frame templates, see Create Your Own Frame Templates (see page 142).

To save the current style sheet to a file

In the Style Editor, you can save the current style sheet to a file.

1. Click File, Write Style to File.


2. Specify the name, file extension, and directory for the file.

3. Click OK.

4. Click Close to exit the Style Editor.

You are returned to the Frame Editor.

To apply a frame template's style sheet to a frame

1. Open the desired frame in the Frame Editor.

2. Click the frame's TemplateName property in the Property Inspector.

The Select a Frame Template dialog appears.

Frame Editor


3. Select an application and a template from the Application and Template list fields, respectively (for example, My_Application and my_main_frame_template):

4. Click OK.

OpenROAD does the following:

Overwrites the current style sheet (including any field styles you may have created) with the frame template style sheet

In the Style Editor, displays the style sheet from the template in place of the frame's original style sheet

Modifies all fields on the form to conform to the field styles on the new style sheet

To read a style sheet from an external file

1. Open the Style Editor.

2. Click File, Read Style from File.


3. Locate and select the file to be loaded into the Style Editor.

4. Click Open.

The style sheet is associated with the current frame.

Frame Editor


Delete Field Styles

You can delete field styles in the Style Editor.

To delete one or more field styles

1. Open the Style Editor by clicking Tools, Style Sheet on the Frame Editor's floating menu bar

2. Select the field style to be deleted in the Style Editor.

3. Click Edit, Delete Field Style.

4. Repeat the previous steps to delete other styles.

Note: You must leave at least one field style or model for each field type, which will become the default style for the field type.

5. Click File, Close to exit the Style Editor.


Display the Form Grid

The Frame Editor lets you place fields anywhere on the form, but you can also align them to an underlying grid.

To display the grid

Click View, Grid on the User Frame menu bar.

The grid is displayed on the open form.

To remove the grid

Click View, Grid on the User Frame menu bar to clear the option.

Frame Editor


Snap to Grid

Using the grid makes it easier to align fields accurately. When Snap to Grid is enabled, all fields are automatically aligned with the grid points as you add them to the form.

To enable Snap to Grid

Click Layout, Snap to Grid on the User Frame menu bar.

To disable Snap to Grid

Click Layout, Snap to Grid on the User Frame menu bar to clear the option.

More information:

Resize the Grid (see page 134)

Resize the Grid

The Workbench Frame Editor's default grid has grid points every quarter of an inch. However, you can change the size of the cells in the grid. This sizing applies whether or not the grid lines are displayed. You can also change the color of the grid lines.

To resize the grid

1. Click Layout, Grid Properties on the User Frame menu bar.

OpenROAD displays the Grid Properties dialog.

2. Specify the size of the cells in the grid in any of the following ways:

Enter values (in 1000ths of an inch) in the Width and Height fields.

Use the scroll bars for the Width and Height fields.

Click the upper left cell of the model grid, and then use the resize handle to adjust the size of the cell.

3. Click OK.

OpenROAD changes all the grid cells to the specified size.

To change the color of the grid lines

1. In the Grid Properties dialog, click Change color.

The color palette appears.

2. Select a tab for a color system and click a color.

The color is applied.

3. Click OK to close the Grid Properties dialog.

Frame Editor


Property Inspector

When you start the Frame Editor, the Property Inspector appears automatically. This floating window lets you set properties for the current frame and each field on a form.

The left column of the Property Inspector lists all properties that can be specified for the current frame or selected field, and the right column contains the corresponding value cells where you select or specify a value. The Property Inspector also includes a Select Named Field drop-down menu, a Currently Selected Field entry, and a Select Attributes to Display drop-down menu.

Frame Editor


Select a Field

The Select Named Field drop-down menu at the top of the Property Inspector's window lets you switch to any field already defined on the frame.

To select a field

Click the down arrow to the right of this menu, and then select any field from the list of fields displayed.

The name of the selected field is displayed in the Currently Selected Field entry field, and the Property Inspector displays the properties applicable to the selected field.

Frame Editor


How You Can Use Property Filters

The Property Inspector features property filters that restrict the display of properties to certain types. For example, you may want to use a property filter to limit the list of available properties to those concerning only the frame's appearance. To do so, click the down arrow to the right of the Select Attributes to Display drop-down menu, and then select Appearance from the list of filter options:

The Property Inspector displays only those properties related to a frame's appearance, such as background pattern and color or the presence of scroll bars.

How Multiple Field Selection Works

If several fields on a form are selected, the Property Inspector displays only properties that are common to the selected fields. (To select multiple fields, hold down the Shift key and click the desired fields in succession.)

For example, because all fields except line segments have the BgColor property, the Property Inspector almost always displays BgColor. However, not all fields have the LineColor and OutlineColor properties. Shape fields have LineColor, whereas active fields have OutlineColor.

The Currently Selected Field drop-down menu at the top of the Property Inspector indicates that multiple fields are selected. When multiple fields are selected, the Property Inspector shows the value of a common property only if the value is the same for all of the selected fields.

Note: For details about the types of fields in OpenROAD and information about selecting individual and multiple fields, see Types of Fields (see page 151) and Select Fields (see page 157), respectively.

Frame Editor


Miscellaneous Features

Other Property Inspector features that you should keep in mind while creating frames and adding fields to their corresponding forms include the following:

The Property Inspector is used for frames, frame menus, and option menus.

The Property Inspector is automatically displayed when you open a frame.

After it is opened, the Property Inspector remains open until you close the last open frame.

To close the Property Inspector, use the standard Close button (X) in the upper right corner of its title bar.

The Property Inspector cannot be maximized.

The Property Inspector is vertically resizable.

The Property Inspector does not appear in the task bar.

Note: For a complete list of system classes and their properties, see the OpenROAD Workbench online help.

Property Setting Prefixes

All OpenROAD system classes and their properties are listed in the OpenROAD Workbench online help. Many properties begin with a prefix followed by an underscore. For example, the DisplayPolicy property's settings begin with the prefix DP_, such as DP_CLIP_IMAGE. The following table lists the prefixes used and their meanings.

For more information on these properties, see the appendix "System Constants and Keywords" in the Language Reference Guide.

Prefix Property Setting Category

ALIGN_ alignment

AP_ anchor point

BDB_ bitmap display behavior

BF_ bitmap file format

BS_ button style

CC_ color settings for standard palette

CC_DEFAULT_ color settings for OpenROAD default palette

CC_SYS_ color settings for system default palette

CL_ choice list

COR_ corner shape for tab folders

Frame Editor


CP_ collapse policy

CS_ cursor state

DC_ display capabilities

DP_ display policy

DS_ DBMS server types

DV_ default value

EH_ DataEntryErrorHandler return codes

EP_ DBMSMessagePrinting and DBMSErrorPrinting settings

ER_ error codes

FA_ field alignment

FB_ field bias

FC_ force case

FM_ frame mode

FO_ field orientation

FP_ field pattern

FT_ focus behavior

GF_ grow from

HV_ help commands

JU_ justification

LS_ line style

LVFS_ list view field style

LW_ line width

MB_ menu bias

MT_ message type

OF_ option field style

OP_ operation

OS_ outline style

POS_ position

PU_ pop-up reply codes

QS_ query states

QY_ query modes

RC_ reason code

RS_ row state

Frame Editor


SEL_ selection type

SK_ speed key

SM_ separator move

SP_ system-defined cursor settings

SY_ operating system settings

TAB_ tab settings

TF_ type face

TN_ tree nodes

UE_ message error codes

VK_ virtual key

WI_ window system settings

WP_ window placement

WV_ window visibility

Frame Editor


Field Tree

The OpenROAD Field Tree lets you view all of the fields defined to a frame and provides you with an alternative method of locating and selecting a field on the frame currently being edited. By expanding the branches of the tree, you can easily locate a field that is obscured by another field on the form. After you locate it and select it in the Field Tree, the specified field is selected in the Frame Editor.

Use the Field Tree

To access the Field Tree window, a user frame must be open.

To use the Field Tree

1. Click View, Field Tree on the Frame Editor's floating menu bar.

The Field Tree window appears, presenting all fields, including hidden fields, defined to a frame in an expandable tree view.

2. Click the + buttons to expand the contents of any components.

The Field Tree window, like the Component Cross Reference window discussed previously, uses Expand and Collapse (+/-) buttons for its branches.

3. Find and select the component you want to work with.

The component is selected in the Frame Editor.

Alternative Methods for Creating Frames



You can create a frame from an existing frame in your application or one that is included in your application. One way to do this is to edit the frame you want to copy and then save it with a new name by clicking File, Save As in the Frame Editor. Then you can begin working on your new frame.

Another method is to first create a generic frame template that you can base subsequent frames on. Then, when you create any new frame components, you can simply select this frame template for your template. Your new frame component is created based on this generic frame template.

Generally, the latter method is preferable for developing consistent frame styles and behaviors within your application. New frames have the visual characteristics, properties, and associated 4GL code as defined in the template.

You also can create frames by using templates that are already paired with assistants to create automatically generated frames, as described in Generating Frames from Predefined Templates (see page 281).

The templates you create can work with or without the Assistant Technology (as discussed in the Programming Guide). The next section provides information on creating your own frame templates.

Create Your Own Frame Templates

Every OpenROAD frame that you create is based on a frame template that determines many of the visual and behavioral characteristics of the frame. OpenROAD provides templates for the basic frame types as well as more complex templates as seen in Generating Frames from Predefined Templates (see page 281).

You also can create your own frame templates in the following ways:

Save the working copy of a frame as a frame template by clicking File, Save As New Template on the Frame Editor's floating menu bar

Create a frame template as an application component in Workbench

The following is the Develop tab, Components portlet toolbar icon to open the Create Frame Template dialog:



To create a frame template as an application component

1. Click in the Components portlet of the Develop tab.

2. Click File, New, Frame Template.

The Create Frame Template dialog appears, letting you specify the basic properties for a new frame template. This dialog is similar to the Create User Frame dialog (see page 109), except it includes an Assistant field where you can enter the name of an assistant, if available.

Note: For more information about frame template properties, see How You Can Set Frame Template Properties (see page 144).

3. Enter the frame template name in the Name field (for example, My_Frame_Template).


5. Select an application and template from the Application and Template fields, respectively.

For example, if you want to create a frame template for a standard Confirmation dialog, accept the default Core application library and then select the dialog_box template.

6. Click Create.

The Frame Template Editor opens, containing the default frame template you specified.

Note: Most of the features of the Frame Editor (see page 109) described previously also apply to the Frame Template Editor.

7. Design the form, set its properties, and write the script for the frame template as you would for any frame.

For example, you could add a free trim field with the following standard text: Are you sure you want to delete this item? You also could include a title for this form by entering Confirmation in the value cell for its WindowTitle property.

Note: For information about the various types of fields and how to create them and place them on your form, see Creating and Using Basic Fields (see page 151).

8. Click File, Save and Close.

The frame template is added to the Components portlet.



How You Can Set Frame Template Properties

When you start the Frame Template Editor, the Property Inspector also opens. The Property Inspector lets you set properties for each field on a form and for the frame template itself. The frame template properties are identical to the frame properties discussed in Available Properties (see page 114). However, frame templates have one additional property:

AssistantProc

Indicates the 4GL procedure name for a frame template assistant

Note: For more information about how to create a frame template assistant, see the chapter “Writing a Template Assistant” in the Programming Guide.

Create a Frame Based on Your Own Frame Template

In addition to the frame template being added to the Develop tab's Components portlet, it is added to the template options for the specified application and becomes available the next time you create a user frame in that application. The frame template becomes available to other applications if that application is specified as an included application.

To create a frame based on this template

1. Select the desired application in the Applications portlet, click in the Components portlet to activate it, and then click File, New, User Frame.




2. Select the application that contains your frame template from the Application list field (for example, My_Application).

The Template list field displays all frame templates defined in the specified application. For example:

Note: If the desired application is not listed in the Application list, click View, Included Applications. Add the application using the Included Application window's File, New menu and the Add Included Application dialog. For more information, see Specify Included Applications (see page 89).

3. Select the frame template, and then continue creating the frame following the basic steps defined throughout this chapter.

How You Can View and Modify Frames


Edit Frame Templates

To edit a frame template, you open it from the Develop tab's Components portlet and edit it as you would any frame.

More information:

For more information about how to apply frame template changes to previously generated frames, see How You Can Apply Template Changes to Frames and Fields (see page 561).

For technical information about how to create a frame template assistant that is compatible with the ApplyTemplate utility, see “Writing an Assistant for a Template” in the Programming Guide.

For more information about applying the OpenROAD predefined frame templates and using their associated assistants, see Generating Frames from Predefined Templates (see page 281).

How You Can View and Modify Frames

To select an existing frame to edit or view in the Frame Editor, open the Frame Editor from the Develop tab's Components portlet by using any of the following methods:

Select the frame component and click File, Open or File, View

Double-click the frame icon

A working copy of the frame is opened in the Frame Editor if the frame is available for editing. If the desired frame is not available for editing (that is, it is checked out by another developer), it will be opened for viewing only.

How You Can Test Frames

You can test a frame in any of the following ways:

In the Frame Editor, run the current frame by clicking Debug, Go on the Frame Editor's floating menu bar.

OpenROAD Workbench runs the current frame and any frames or procedures that this frame calls.

Run the current application from the Develop tab's Applications portlet by clicking Run, Run, and test all of its frames.

This method helps ensure that the current frame receives any parameters it needs from the frame that calls it.

To stop running the current application at any point, click the Stop toolbar icon or click Run, Stop.



Compile the frame in the Frame Editor without running the application.

To compile the frame, click Tools, Compile.

Debug the frame.

OpenROAD provides a Debugger for a closer inspection of your frame execution process. For more information about how to use the Debugger, see the chapter “Debugging Your Application” in the Programming Guide.

Simulate a runtime form.

In the Frame Editor, click Tools, Simulate to view a form without executing any scripts.

For more information about three of these frame testing methods, see Compile a Frame (see page 147).

Compile a Frame

If a component has a script, the relevant OpenROAD Workbench editor lets you compile the script.

To compile a frame

Click Tools, Compile on the Frame Editor's floating menu bar.

The frame is compiled. If any compilation errors are found, the Compilation Errors window is displayed.

How You Can View Compilation Errors

Whenever an error occurs while you are compiling an application or component, OpenROAD Workbench displays a status message at the bottom of the editor window. After the compilation completes, Workbench opens the Compilation Errors window, which displays the compiled code with the compilation error messages and warning messages intermixed.



The Find menu provides the following operations for viewing and editing your errors:

Next Error

Displays the next error message

Next Warning

Displays the next warning message

Edit Script with Error/Warning

Opens the Script Editor for the script at the line containing the currently selected error

You need not close the Compilation Errors window to correct errors in the frame script.

Simulate a Runtime Form

OpenROAD lets you test a form without actually running its frame.

To simulate a runtime form

Click Tools, Simulate in the Frame Editor.

The form appears as it does to users without actually executing any scripts.

Note: You must compile or run the form to actually test its functionality. For more information see, Compile a Frame (see page 147).

Run a Frame

You can run a user frame from the Develop tab's Components portlet using the Run toolbar button.

To run a frame

Select the user frame in the Components portlet and then click Run.

The frame is displayed with the default window icon, the title bar, and optional scroll bars, depending on the size of the frame.

Delete a Frame


Delete a Frame

You can delete a frame or any other component on the Develop tab.

To delete a frame

1. Select the desired frame in the Components portlet.

2. Click File, Delete.


3. Click OK to confirm the deletion.

Creating and Using Basic Fields 151

Chapter 6: Creating and Using Basic Fields This section contains the following topics:

Types of Fields (see page 151) How You Can Add Fields to a Frame (see page 154) Shape Fields (see page 167) Scalar Fields (see page 170) Composite Fields (see page 215) Common Field Properties (see page 239)

After you create a basic frame, you can place fields on its form. The types of fields you include on the form determine how your frame functions and how users interact with it. This chapter describes how to create and use basic fields using the Frame Editor's field palette and menu commands. It shows you how to position and size fields, set their properties, and create field scripts.

The chapter Alternative Methods for Creating Fields (see page 271) discusses methods for creating fields using field templates, database tables, user classes, and external classes. In the chapter Generating Fields from Predefined Templates (see page 341), you will learn how to use more complex field templates that are paired with assistants. These assistant-based field templates let you create automatically generated fields, from bar graphs and other desk accessories to editing controls and powerful database-related fields.

Types of Fields

OpenROAD fields enable an application to display information to end users and provide them with the means to give instructions to the application.

There are several types of basic fields:

Shape Fields

Correspond to certain geometric shapes.

For a depiction of these types of fields, see Shape Fields, Illustrated (see page 152). For more information on each field type, see Shape Fields (see page 167).

Types of Fields


Active Fields

Specify two classes of fields:

Scalar Fields

Used for interacting with the end user.

For a depiction of these types of fields, see Scalar Fields, Illustrated (see page 152). For more information on each field type, see Scalar Fields (see page 170).

Composite Fields

May contain other fields.

For a depiction of these types of fields, see Composite Fields, Illustrated (see page 153). For more information on each field type, see Composite Fields (see page 215).

Note: A simple field is an individual field that is not a composite field.

Shape Fields, Illustrated

A shape field is a graphic element, a geometric figure, that provides a background for other fields on a form. Users cannot interact with shape fields.

The following example shows OpenROAD shape fields:

Scalar Fields, Illustrated

A scalar field is a field that lets the application accept data from users or display data to users. For example, an entry field lets the user enter a text string, and a toggle lets the user choose between alternative options.

Types of Fields


The following illustrates OpenROAD scalar fields:

Composite Fields, Illustrated

A composite field is a field that may contain other fields. Most composite fields can contain fields of any type, even other composite fields. Composite fields serve a number of purposes. In addition to providing convenient ways of presenting data to the end user, they are often useful for organizing fields on a frame.

For example, a typical table field consists of scalar fields arranged in rows and columns, a vertical scroll bar, and a control button field. A tab folder, however, consists of two other composite fields: tab bars and tab pages.

How You Can Add Fields to a Frame


The following illustrates OpenROAD composite fields:


There are several ways to create the various types of fields for a form. The Frame Editor's tools—the field palette and the Insert Field and Group menu commands—are described here. Field templates and several other methods are discussed in Alternative Methods for Creating Fields (see page 271).



You can use the tools provided in the Frame Editor to create fields for your frame following these basic steps.

1. Select the type of field to be created in the Frame Editor.

For active or shape fields, click one of the field palette icons or select a field type from the Insert Field submenu. For composite fields, you select a field type from the Group menu.

2. Position and size the field on the form.

Depending on the field type you have chosen, the field is created when you drag the cursor—creating a field boundary—or click at the starting point for the field. This is discussed in detail in Position Fields (see page 155).

Note: You cannot change the size of some fields, such as control buttons. The size of other fields is determined by the text they contain and cannot be changed.

3. Set the properties for the new field using the Property Inspector.

Field properties include various options you can set to determine how the field should look and behave. See the appropriate section for setting a specific field's properties, such as Button Field Properties (see page 179) or List Field Properties (see page 186). Because fields share many properties, also see Common Field Properties (see page 239).

4. For certain field types, write the field script (or section of the frame script) that defines the events for the field.

You use the 4GL programming language to write the scripts for your fields. You can write your scripts using the Script Editor—the OpenROAD script editing facility—or with your system editor. For more information about writing scripts, see Writing Scripts and Procedures (see page 435).

5. Test the field.

You can test your new field at any point while you are developing the frame to see how the field looks and acts when the application is running. See How You Can Test Frames (see page 146).

Position Fields

After you select a field type from the Frame Editor's field palette, how the field is positioned on your form depends on the field's type. The pointer that appears after you select the field type tells you how to position the field:

Crosshair pointer

Indicates that you must draw a rectangular boundary to contain the field:



Drop object

Indicates that you must select a starting point for the field:

To draw a boundary for a field with the crosshair cursor

1. Place the crosshair at one of the boundary corners.

2. Holding down the mouse button, drag the pointer in a diagonal line to create a rectangle.

3. Release the mouse button when the boundary is the correct size.

Workbench positions the field in the rectangular boundary.

To position a field with the drop object

1. Select a starting point for the field on the form.

2. Click the mouse.

Workbench aligns the upper left corner of the field with the nearest pixel (if you are not using a grid) or grid point (if you are using a grid). For information about the grid feature, see Snap to Grid (see page 134).

Note: To position composite fields, follow the steps in the section for the specific field type.

Create Multiple Fields

You can create several fields of the same type using the Repeat Insertion option in the Frame Editor.

To create several fields of the same type

1. Click Insert, Field, Repeat Insertion on the floating menu bar to enable the option.

2. Select the type of field you want to create.

3. Create fields of the selected type by clicking the mouse cursor on the frame for as many fields as you want to create.

Note: When creating a field that is positioned using a crosshair cursor, you must draw the boundary for each field before creating a new one.

4. Repeat Steps 2 and 3 to create multiple fields of a different type.

5. To leave repeat insertion mode, Click Insert, Field, Repeat Insertion to clear the option.



How You Can Select Fields

The following sections describe how to select individual and composite fields. Also described are the visual selection cues that indicate what commands are allowed for a particular field.

Select an Individual Field

There are several methods for selecting a simple field or a single component of a composite field:

Point and click

Field Tree

Property Inspector

For instructions, see the appropriate procedure, following.

Select an individual field using the point and click method

Position the cursor on the desired field and click the primary mouse button

The field is selected.

Note: If you cannot select a field because it is underneath another field, click Layout, Bring to Front to move the field to the top layer or click the field on top and click Layout, Send to Back to move it to the back. For more information, see How You Can Work with Overlapping Fields (see page 160).

Select an individual field using the Field Tree method

Locate the field in the Field Tree window and click it.

The selected field is highlighted in the Frame Editor.

This feature is a handy tool for selecting a field that is obscured by another field. For more information, see Use the Field Tree (see page 141).

Select an individual field using the Property Inspector method

At the top of every Property Inspector there is a Field List drop-down menu that contains the full name of every named field on the current frame. Use this menu to change the current field selection.

For more information, see Format Templates for Field Types (see page 637).



Select a Composite Field

There are several methods for selecting a composite field, depending on whether it has a visible boundary. For instructions, see the appropriate procedure, following.

To select an entire composite field with a visible boundary

1. Position the mouse cursor on the boundary or the background of the composite field.

2. Click the mouse.

You can also select an entire composite field by selecting one of its component simple fields.

To select a composite field by selecting one of its simple fields

1. Position the mouse cursor on the simple field.

2. Click the mouse.

3. Hold down the Ctrl key and then click the mouse to select the parent (composite) field that contains the selected simple field.

Alternatively, click Edit, Select, Parent.

To see the outlines of composite fields that have no boundaries

Click View, Composite Outlines.

OpenROAD highlights the composite field.

Note: These outlines do not appear on the running frame; they only serve as a guide while you are working in the Frame Editor.

If the composite field you selected is included in another composite field, repeat this procedure.

Select a Group of Fields

You can select a group of fields the following ways:

Create a selection group by selecting one field at a time.

Lasso a group of adjacent fields with a selection box.

Note: If the fields to be selected are all within a composite field, drag a selection box around them by holding down both the Shift and Ctrl keys, then pressing the mouse button. (If you simply press the mouse button when the cursor is within a composite field, the composite field is selected.)



Click Edit, Select, All from the shortcut menu that appears to select all the fields on the form.

Click Edit, Select, Children from the shortcut menu that appears to select all the children of a selected composite field.

The selection group and selection box methods are described in more detail in the following procedures.

To create a selection group

1. Select the first field in the group.

2. Add the second field as follows:

a. Hold down the Shift key.

b. Position the cursor on the next field you want to select, and click the primary mouse button.

Two fields are now selected.

3. Repeat Step 2 for each field to be added to the group.

To use a selection box

1. Position the mouse cursor outside the group of fields you want to select.

2. Press and hold down the mouse button.

3. Drag the mouse to draw a selection box around the desired fields.

The group will include only the fields that are completely enclosed by the selection box. If any part of a field is outside the box, that field will not be selected.

Note: If a composite field is entirely inside the selection box, the composite field is selected but not its children.

Note: You can exclude any of the selected fields by positioning the cursor on it and pressing the Shift key and clicking the primary mouse button.

Visual Selection Cues

After you have selected a particular field, OpenROAD Workbench visually indicates what commands can be performed on it:

Eight handles indicate that you can move or resize the field.

Three handles indicate that you can resize the field horizontally only but not move it.

An outline on the field, but no handles, indicates that you can move it but not resize it.



How You Can Work with Overlapping Fields

OpenROAD lets you lay any number of fields on top of each other. You can select any of the overlapping fields so long as you can click on some portion of it with the mouse.

However, when one field completely overlaps another, you cannot select the bottom field by clicking on it. The Frame Editor's Layout menu includes two commands for reordering overlapping fields:

Bring to Front

Moves the selected field to the top of the field stack

Send to Back

Moves the selected field to the bottom of the field stack

For more information on using these commands with shapes, see How You Can Work with the Shape Layer (see page 160).

How You Can Work with the Shape Layer

When a form includes shapes—such as lines, ellipses, or rectangles—OpenROAD Workbench separates the fields into two layers:

Bottom layer

Contains the shapes, which always stay underneath the other fields

Top layer

Contains the active fields and the trim fields, which always stay above the shapes

The Bring to Front and Send to Back commands on the Layout menu work only within a layer. Therefore, you cannot use these commands to move a scalar field or trim field underneath a shape. If you cannot select a shape because it is completely covered by a scalar or trim field, you must drag the field off the shape.

Note: You can also use the Frame Editor's Field Tree feature. Locate the field in the Field Tree window and click it. The selected field is then highlighted in the Frame Editor. For more information, see Use the Field Tree (see page 141).



Move and Resize Fields

After you have created a field on the form, you can move the field (if move handles are displayed) or resize it (if resize handles are displayed).

Note: You can save your changes at any time using the File, Save menu command. If you try to close a frame without having saved your changes, the Frame Editor prompts you to do so.

To move an individual field

1. Position the mouse cursor inside the field.

2. Click and hold the mouse button.

3. Drag the field to its new position.

4. Release the mouse button.

To move a group of fields

1. Hold down the Shift key and select several fields in succession.

Alternatively, enclose the group in a selection box.

2. Drag the group to its new position.


To resize an individual field

1. Position the mouse cursor on one of the field's sizing handles.

Note: The corner handles let you change both dimensions with the same operation.

2. Click and hold the mouse button.

3. Drag the handle to increase or decrease the size of the field.


To move and resize an individual field using the Property Inspector

1. Select the field on the form.

The Property Inspector displays the properties of the field.

2. Use the Property Inspector's Position and Size filter to restrict the display to relevant properties.

3. Use the Height and Width properties to specify, in 1000ths of an inch, the height and width of the field.

4. Use the XLeft, XRight, YBottom, and YTop properties to specify the location of the field relative to a containing composite field, if any.



5. Use the AbsXLeft, AbsXRight, AbsYBottom, and AbsYTop properties to specify the location of the field relative to the form.

6. (Optional) Set the field's AnchorPoint property to a predetermined point such as AP_TOPLEFT, AP_CENTER, or AP_BOTTOMRIGHT.

Notes:

For more information about these size and location properties, see Common Field Properties (see page 239).

You can also resize all selected fields to be the same size as the smallest or largest selected field using Layout, Resize to Smallest or Layout, Resize to Largest command, respectively.

Copy and Paste a Field

You can copy and paste fields using Edit, Copy or Edit, Duplicate, and Edit, Paste menu commands.

Copy

Places a copy of the field or fields in the Clipboard (you then can use the Paste command to paste the copy onto the form)

Duplicate

Places the copy directly onto the form; you can then move the field as desired

Paste

Places what has been copied to the Clipboard onto the form

To copy a field or group of fields

1. Select the field or group of fields.

2. Click Edit, Copy or Edit, Duplicate.

To paste a copy of a field or fields that were copied to the Clipboard

1. Click Edit, Paste.

2. Click the mouse button at the starting point for the field.

The copy is placed on the form.

Align Fields

You can use commands on the Layout menu to align the fields on your form. To use any of these commands, you first must select the fields to reposition (see Select Fields (see page 157)), and then select the appropriate command.



The following commands are used to align two or more fields with each other in different ways:

Align to Left

Center Horizontally

Align to Right

Align to Top

Center Vertically

Align to Bottom

Center

To use any of the alignment commands

1. Select two or more fields, as described in Select Fields (see page 157).

2. Select one of the previously mentioned commands from the Layout menu.

The fields are repositioned accordingly.

Note: You can use the Frame Editor's grid as an aid in aligning fields. For more information, see Display the Form Grid (see page 133).

Delete a Field

You can delete simple fields from a form using the Edit, Cut or Edit, Delete menu commands. Deleting a composite field deletes all the individual components that it contains.

Cut

Removes the field from the form and places it in the Clipboard

Delete

Removes the field from the form only

To remove a field or group of fields from a form

1. Select the field or group of fields.

2. Click Edit, Cut or Edit, Delete.

To remove a composite field but leave its individual components intact

1. Select the entire composite field.

2. Click Group, Ungroup.

For more information, see Select a Group of Fields (see page 158).



How Rearranging Composite Fields Works

After grouping several individual fields into a composite field, you can rearrange the individual components of that composite field. Depending on the field type, OpenROAD makes the necessary adjustments to keep the basic structure of the field intact. For example, if you move one of the fields in a stack, Workbench automatically realigns the rest of the components with it.

Field Colors

You can change the color of the following field features:

Foreground (for example, text in an entry field or a button label)

Background

Line

Outline

Note: Before changing the colors of an entry field, you may simulate the running frame by clicking Tools, Simulate on the Frame Editor's floating menu bar. When you change field colors, you can see the relationship between the background and foreground. For more information about viewing a running frame, see Simulate a Runtime Form (see page 148).

You can change color properties of fields by using:

The Property Inspector (see page 164)

The Frame Editor's color palette (see page 165)

A style sheet (see page 164)

Change Field Colors Using the Property Inspector

You can change the color of a field's background or foreground using the Property Inspector.

Note: You can use the Property Inspector's Appearance filter to restrict the properties displayed to only relevant properties. For more information about using the Property Inspector's features, see Property Inspector (see page 135).



To change the color of a field's background or foreground

1. Select the field.

2. Select the FgColor property in the Property Inspector.

The miniature version of the Frame Editor's color palette appears in the Property Inspector.

Note: All of the Property Inspector's pop-up frames, such as the color palette and the Data Type and Browse dialogs, are designed to close if you click anywhere but in the pop-up frame. If you accidentally close one, click the relevant property again in the Property Inspector and the pop-up frame will reappear.

3. Select a color from one of the following palettes: OpenROAD, System, or User.

Note: For a description of each of these palettes, see OpenROAD Color Palettes (see page 126).

4. (Optional) Repeat Steps 2 and 3 for the BgColor, LineColor, or OutlineColor property, if desired.

Change Field Colors Using the Color Palette

You can change a field's background or foreground color using the Frame Editor's color palette. This method has several advantages over using the Property Inspector: color settings can be applied to children of selected fields and you can set all of the color attributes with a single operation.

To change a field's background or foreground color


2. Click View, Color Palette on the Frame Editor's floating menu bar.

The Frame Editor's primary color palette appears.

3. Select or clear the Background, Foreground, Outline, or Line button appropriately.

This option's choices change, depending on what is selected:

If the form itself is selected, only Background appears.

For most scalar fields, the radio field displays Background, Foreground, and Outline.

If a shape field is selected, Background and Line are displayed.

If both shape and scalar fields are selected—for example, a button field and an ellipse—all four choices are available.



4. Select a color from one of the palettes.

Your choice is displayed in the sample box.

Note: If more than one field is selected and if these selected fields do not share the same BgColor value, the sample box does not display any color. Instead, it displays a crosshatch pattern. However, when you click the Apply button in Step 6, the chosen color is applied to all of the selected fields.

5. (Optional) Select the Apply to Children box to apply the color you have chosen to any children of the selected field.

6. Click Apply.

Your changes are applied.

Note: You may keep the Color Palette open during an entire editing session. To close the color palette, click the standard Close button (X) in the upper right corner.

For more information about changing the background color of the entire form, see How You Can Set the Background of a Form (see page 124).

How You Can Use the Style Sheet to Change Field Colors

Every field on a frame has a field style. When you create a field initially, it uses the default style, Field Style 1. If you apply a different field style from the style sheet, the field's style changes accordingly.

A field may also have a unique style if its style attributes do not match those of any of the field styles defined in the style sheet. For example, suppose that Field Style 1 for a button field specifies that the background color is pale gray. If you change the BgColor property of the button field from CC_PALE_GRAY to CC_RED, the field style of the button field is changed subsequently to Unique Style—one that does not correspond with any style sheet styles.

For more information about using the style sheet to change field colors, see Style Sheets (see page 127).

Shape Fields


Convert a Field to a Different Type

You can convert fields of certain types to a related type. OpenROAD Workbench lets you convert between the following types of fields:

Choice fields

Consist of radio fields, list fields, and option fields

Composite fields

Consist of table fields, subforms, flexible forms, stack fields, matrix fields, and viewports

To convert a field

1. Select a field of one of the available types.

2. Click Edit, Convert To, and select the type you want to convert to.

Note: Only the appropriate types are displayed; the others are dimmed.

The field is converted to the type you selected.

Shape Fields

A shape field is a graphic element, a geometric figure, that provides a background for other fields on a form. Users cannot interact with shape fields. Shapes include:

Ellipses

Rectangles

Line segments

Because shapes are stored on a separate layer on the form, they are always “under” the scalar fields. All shapes consist of perimeter lines, which you can define using the Property Inspector. For example, you can set the line thickness or style of a shape.

Ellipses and rectangles also include a background, which is the area bounded by the perimeter. This background can be filled or unfilled. A shape field is transparent, or unfilled, if its BgPattern property is set to FP_CLEAR; otherwise, the field is filled. When a shape is unfilled, any shapes on the layers beneath it show through. A filled shape is opaque and covers any shapes below it.

Shape Fields


For more information about form layers, see How You Can Work with Overlapping Fields (see page 160) and How You Can Work with the Shape Layer (see page 160).

To work with any of the shape types, see the appropriate section, following.

Create a Rectangle Shape

A rectangle is a four-sided background shape that can be empty or filled.

To create a rectangle


2. Click the Rectangle icon on the field palette.

3. Click the form and draw the boundary for the rectangle shape.

Leave the rectangle selected on the form.

4. Using the Property Inspector, set the properties for the rectangle shape, including BgColor, Height, and Width.

Note: For complete descriptions of each field property, see Common Field Properties (see page 239).

Note: You can use the Property Inspector to align rectangle shapes precisely. By using the Position and Size filter, you can find and change the relevant properties.

Rectangle Shape Properties

Rectangle shapes have properties that are common to many other fields. Therefore, all of the properties for rectangle shapes are described in Common Field Properties (see page 239).

Shape Fields


Create an Ellipse Shape

An ellipse is a round or oval shape that can be either empty or filled.

To create an ellipse


2. Select the Ellipse icon on the field palette.

3. Draw the boundary for the ellipse shape on the form.

Note: To create a circle instead of an oval, hold down the Shift key while drawing the boundary for the ellipse.

Leave the ellipse selected on the form.

4. Set the properties for the ellipse shape, including LineColor, LineStyle, LineWidth, BgColor, and BgPattern.

For complete descriptions of each field property, see Common Field Properties (see page 239).

Ellipse Shape Properties

Ellipse shapes have properties that are common to many other fields. Therefore, all of the properties for ellipse shapes are described in Common Field Properties (see page 239).

Create a Line Segment

A line segment is a shape field that appears as a single line that you draw between two points on a form.

To create a line segment


2. Select the Line Segment icon on the field palette.

3. Choose the starting point on the form, and click and hold the primary mouse button.

Scalar Fields


4. Drag the line from the starting point to the ending point.

Note: To ensure that the line is either truly vertical or truly horizontal, hold down the Shift key while you draw the line.


6. Set the properties and style for the line segment.

Note: For more information about the various properties, see Line Segment Properties and Common Field Properties (see page 239).

For more information about using line segments to create a line chart, see the Programming Guide.

Scalar Fields A scalar field is a field that lets the application accept data from users or display data to users. Scalar fields include the following:

Free trim

Box trim

Single-line entry fields

Multiline entry fields

Buttons

Control buttons

Pop-up buttons

Radio fields

Option fields

List fields

List views

Toggle fields

Bar fields

Palette fields

Image trim

Image fields

Sliders

Scalar Fields


Scroll bars

Tree views

For more information about scalar fields on the Frame Editor's field palette, see Field Palette (see page 111).

Field Naming

With the exception of trim fields, which are created without a name, all scalar fields are given a default name at the time they are created. The default names have the form, fieldn, where n is a number.

In general, you should change the default name to something more meaningful so that your 4GL scripts are easier to understand. Some examples of meaningful names are:

exitbtn A button that says “Exit”

cancelbtn A button that says “Cancel”

emp_table A table field that is used to display employee information

Trim Fields

Trim fields are text elements or images and include free trim, box trim, and image trim fields. Trim fields consist of a foreground and a background. The foreground is the content of the trim (the image or the text) and the background is the area that surrounds it. You control the settings for the foreground and background separately. Trim is always opaque and covers any fields on the layers below it.

Create a Box Trim

Box trim is a field type that appears as text within a rectangular boundary on a a form. If the text does not fit within the width of the box, OpenROAD automatically wraps the text and lengthens the box to accommodate the extra lines of text. If you move or resize the box, Workbench readjusts the text within the box.

To create a box trim field


2. Select the Box Trim icon on the field palette.

Scalar Fields


3. Position the cursor on the form's background and draw a box.

Note: You do not need to be exact, because Workbench adjusts the box to accommodate the text.

When you release the mouse button, you are in Text Mode. Text Mode is the mode in which you can enter text in a box trim field. A blinking cursor indicates where to start entering text.

4. Enter sample box trim text, and then click the Select Mode icon on the field palette to exit Text Mode:

5. Select the box trim field to access its properties in the Property Inspector.

The text defaults to this field's TextValue property.

Note: You can also enter the text directly in the value cell for the TextValue property. You can even insert several spaces before your text so that it is right-justified in the box. When you press Enter, the specified text defaults to the field on the form.

For complete descriptions of each field property, see Box Trim Properties (see page 172) and Common Field Properties (see page 239).

Box Trim Properties

All the properties for box trim fields are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the box trim field type:

CharsPerLine

Indicates the number of average-sized characters that a box trim, free trim, or entry field can display, thereby controlling the size of the field.

Note: This number may differ from that specified for the MaxCharacters property. For example, suppose an entry field's data type is set to varchar(32), CharsPerLine is set to 10, and MaxCharacters to 32. The end user will be able to enter up to 32 characters, but the data in the entry field will scroll. When the entry field contains more characters than are visible, the end user can use the right and left arrow keys, as well as Home and End, to scroll through the entry field. The user can also insert and delete characters, using the Insert key to switch between overtype and insert mode.

Scalar Fields


TextValue

Displays the first 256 characters of text in the field, exactly as they appear. If this field is an entry field, then this property holds the first 256 characters of data. For multiline entry fields, this property does not include any extra spaces added for word wrap, although it does include hard tabs and newline characters.

If this field is a box trim or free trim field, this property holds the text that the field displays.

UseWidestCharacter

Specifies whether a maximum character width must be used to calculate the field width. This property applies only to entry fields, box trim, and free trim. It is used in conjunction with the CharsPerLine property. Possible values are:

TRUE

Specifies that a maximum character width is used to calculate the field width

FALSE

Specifies that a maximum character width is not used to calculate the field width

Create a Free Trim

Free trim is a field type that appears as text without a boundary on a form. You indicate the starting point for the free trim field and enter a text string of any length.

To add a free trim field to a frame


2. Select the Free Trim icon on the field palette.

3. Position the cursor on the form and click.

4. Enter the free trim text in the free trim field that appears.

Note: Workbench does not wrap the text. To start a new line, you must press Enter.

5. Click the Select Mode icon to exit Text Mode.

Scalar Fields


6. Select the free trim field to access its properties in the Property Inspector.

The text defaults to the TextValue property's value cell.

7. Select the BgColor property and change the background color on one of the palettes.

Note: For more information about the various properties, see Common Field Properties (see page 239).

8. Select the FgColor property, and choose a foreground color.

9. Change other properties such as IsBold, TypeFace, and TypeSize.

Note: You can also use the Frame Editor's font palette to specify type face, type size, italics, and boldface for an individual field. Additionally, you can apply these selected attributes to all fields that are currently selected by clicking the Apply button. If you also select the Apply to Children option, then the selected font attributes are applied to all selected fields and their children. Furthermore, if the form itself is selected and Apply to Children is on, the font palette applies to all fields on the form.

For complete descriptions of each field property, see Free Trim Properties (see page 174) and Common Field Properties (see page 239).

Free Trim Properties

All the properties for free trim fields are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to this type of field:

CharsPerLine



Scalar Fields


TextValue



UseWidestCharacter


TRUE


FALSE


Image Trim

Image trim is a field type that appears as a picture on a form. You specify the starting point for the field and provide the name of the file that contains the picture. OpenROAD Workbench saves the image with the form. You must create and maintain the image outside of Workbench.

For more information about using image trim, see the Programming Guide.

Supported Image Formats

OpenROAD accepts the following image formats:

GIF

XBM (black and white only)

Sun Raster (must be decompressed before being used)

TIFF

BMP

ICO

JPG

Scalar Fields


Create an Image Trim

You can create an image trim field to place a graphic on a form.

To create an image trim field


2. Select the Image Trim icon on the field palette.

3. Position the cursor on the form and then click.


4. Locate and select an image file, and click OK.

The image is displayed in the designated area.

5. Drag the image to where you want it on the form.

For complete descriptions of each field property, see Image Trim Properties (see page 176) and Common Field Properties (see page 239).

Image Trim Properties

All the properties for image trim are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the image trim field type:

DisplayPolicy

Specifies how the image will be displayed in the field. Available selections are:

DP_CLIP_IMAGE

Clips the image to fit the field

DP_AUTOSIZE_FIELD

Expands or shrinks the field to fit the image

DP_SCALE_IMAGE_H

Scales the image vertically to fit the field

Scalar Fields


DP_SCALE_IMAGE_W

Scales the image horizontally to fit the field

DP_SCALE_IMAGE_HW

Scales the image vertically and horizontally to fit the field (may cause distortion)

Default: DP_AUTOSIZE_FIELD

Image

Specifies a file containing the image to be displayed as the image field, if set to Bitmap. When you click this button, a standard File Selection dialog appears. Enter the directory path of the new image you want to use.

Bar Fields

A bar field is a form field that appears as a rectangle that represents a numeric value. The bar is displayed against a background, and the bar size compared to the background size illustrates the proportional value of the field. You specify the background size, and OpenROAD calculates the bar size based on the field's current value. Typically, a bar is sed for display only.

Bars are especially useful for creating bar graphs. Another effective way to use a bar is as a “percentage completed” indicator. A bar used in this manner provides feedback to the user about the progress of an activity.

Create a Bar Field

You can create a bar field on a form.

To create a bar field


2. Select the Bar Field icon on the field palette.

3. Position and size the bar field.

4. Set the properties for the bar field.

For complete descriptions of each field property, see Bar Field Properties (see page 178) and Common Field Properties (see page 239).

Scalar Fields


Bar Field Properties

All the properties for bar fields are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the bar field type:

FgBitmap

If set to Bitmap, specifies the graphic image that is to be used for the bar's foreground when FgPattern is set to FP_BITMAP.

Default: No Bitmap

FgPattern

Specifies a foreground pattern for a bar field only. Valid options are:

FP_BITMAP FP_CLEAR FP_CROSSHATCH FP_DARKSHADE FP_HORIZONTAL FP_LIGHTSHADE FP_SHADE FP_SOLID FP_VERTICAL FP_DEFAULT

Default: FP_DEFAULT

GrowFrom

Specifies the starting position for the bar. As the value of the field increases, the bar grows from the specified edge to the opposite edge. Valid options are:

GF_DEFAULT (system default value) GF_TOP GF_BOTTOM GF_LEFT GF_RIGHT

Default: GF_BOTTOM

MaxValue

Specifies the highest possible value for the field

MinValue

Specifies the lowest possible value for the field

Scalar Fields


Create a Button Field

A button field is represented as a rectangle that the user clicks to initiate an operation. Such buttons are commonly called push buttons or command buttons. In the Property Inspector, you can specify either text or an image as the label for the button.

Note: You can create Alt speed keys for button fields. For more information, see How You Can Define an Alt Speed Key (see page 261). For information about using buttons on portable forms, see the Programming Guide.

To create a button field


2. Select the Button Field icon on the field palette.

3. Position and size the button field.

4. Set the properties for the button field.

For complete descriptions of each field property, see Button Field Properties (see page 179) and Common Field Properties (see page 239).

Button Field Properties

All the properties for button fields are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the button field type:

BitmapLabel

Specifies a file containing the image to be displayed as the button label. When you click this button, a standard File Selection dialog appears. Enter the directory path of the new image you want to use.

Default: No Bitmap

IsAutoSized

Specifies whether the button field is forced to ignore its Height and Width property values and resize itself to fit the current text label (in the current font). If the text is changed, the button is resized accordingly. Possible values are:

TRUE

Specifies that the field is auto-sized

FALSE

Specifies that the field uses its Height and Width property values

Scalar Fields


TextAlignment

Specifies the alignment for a button's text label. Valid options are:

ALIGN_LEFT ALIGN_RIGHT ALIGN_TOP ALIGN_BOTTOM ALIGN_CENTER

Default: ALIGN_CENTER

TextLabel

Specifies the text for a button label

Default: “Button”

Image Fields

An image field is a field that displays a picture on a form. When you create the field, you specify its boundary. Since the field is meant to be dynamic during runtime, there is no static bitmap file associated with it at the time of creation.

For more information about working with image fields, see the Programming Guide.

More information:

Supported Image Formats (see page 175)

Create an Image Field

You can create an image field on a form.

To create a image field


2. Select the Image Field icon on the field palette.

3. Position and size the image field.

4. Set the properties for the image field.

For complete descriptions of each field property, see Image Field Properties (see page 181) and Common Field Properties (see page 239).

Scalar Fields


Image Field Properties

All the properties for image fields are described under Common Field Properties (see page 239), with the exception of the following property that is specific to the image field type.

DisplayPolicy

Specifies how the image will be displayed in the field. Available selections are:

DP_CLIP_IMAGE

Clips the image to fit the field

DP_AUTOSIZE_FIELD

Expands or shrinks the field to fit the image

DP_SCALE_IMAGE_H

Scales the image vertically to fit the field

DP_SCALE_IMAGE_W

Scales the image horizontally to fit the field

DP_SCALE_IMAGE_HW

Scales the image vertically and horizontally to fit the field (may cause distortion)

Default: DP_CLIP_IMAGE

Control Buttons

A control button is a control that appears on a form as a button that users can click to display a menu of commands or call a dialog. When you create a table field, OpenROAD Workbench automatically creates a control button with a default set of menu commands.

You can create control buttons independently of table fields or create a single control button that operates on multiple table fields with common commands. When you create an independent control button, you must create your own menu commands.

For more information about using control buttons in table fields, see Create a Table Field (see page 223). For more information about creating menu items, see Creating and Modifying Menus (see page 379).

Scalar Fields


Create a Control Button

You can create a control button on a form.

To create a control button


2. Select the Control Button icon on the field palette.

3. Click to place the control button on the form.

4. Set the properties for the control button.

For complete descriptions of each field property, see Control Button Properties (see page 182) and Common Field Properties (see page 239).

Control Button Properties

All the properties for control buttons are described under Common Field Properties (see page 239), with the exception of the following property that is specific to the control button field type:

FocusBehavior

Determines whether clicking this field causes the previous field to be exited and whether the Tab key moves the cursor to this field. For control buttons, the only valid options are FT_SETVALUE and FT_NOSETVALUE.

For more information on the available focus behaviors, see How You Can Set the Focus Behavior (see page 260).

Edit the Option Menu for a Control Button

Every control button that is part of a table field has an option menu with four default commands:

Insert Before Current Row

Delete Current Row

Delete All Rows

Copy Table

Scalar Fields


You can delete or modify any of these default commands, or add other commands using the Option Menu Editor. OpenROAD Workbench provides the script for each of the default commands. You must write the script for any menu items that you add.

Note: Independent control buttons have no default commands. You must create all the menu items and write the scripts for them.

To edit the option menu for a control button


2. Select the control button on the form.

3. Click Edit, OptionMenu on the floating menu bar.

The Option Menu Editor is displayed. For example:

4. Delete or modify the menu items, and add any new items.

5. Select the menu item and use the Property Inspector to edit the properties of a menu item.

For more information about setting properties for menu items, see Common Menu Properties (see page 393).

6. Click Edit, Script to create or edit the script for an option menu.

Workbench opens the Script Editor (or your system editor) and displays the script for the menu. For an item that you have just added, the script is blank.

For more information about using the Script Editor or your system editor to write scripts for option menus, see Writing Scripts and Procedures (see page 435) and the Programming Guide.

7. Click File, Close in the Option Menu Editor when you are finished editing the option menu.

Scalar Fields


Note: Active fields, including named composite fields (table fields excepted), may have a property option menu that pops up when the end user clicks the secondary mouse button over the field. (If you want a child field of a named composite field to use the composite field's property option menu, set the child field's IsPropOptInherited property to TRUE.) Property option menus are similar to option menus on control buttons. To edit a property option menu, click Edit, PropertyOptMenu.

Create a Pop-up Button

A pop-up button is a button control that has an option menu associated with it. Like the independent control button, you must define the pop-up button's option menu, creating all the menu items and writing scripts for them. Unlike a control button, which always looks like any other control button and never has text, a pop-up button may have either text or an image.

To create a pop-up button


2. Select the Pop-up Button icon on the field palette.

3. Position and size the pop-up button on the form.

4. Leave the field selected on the form.

5. Set the properties for the pop-up button, including BitmapLabel, PopupAlignment, and TextLabel in the Property Inspector.

Note: For complete descriptions of each field property, see Pop-up Button Properties (see page 185) and Common Field Properties (see page 239).

6. Click Edit, Option Menu.

The Option Menu Editor appears.

7. Define the option menu to be associated with the pop-up button.

For more information about creating menus and menu items, see Creating and Modifying Menus (see page 379).

8. Use the Property Inspector to set the properties for each menu item, including the ValueList property, where you specify the choices for a menu list using the Value List dialog.

For more information about defining choice lists, see Add and Delete List Field Items (see page 188).

9. Click File, Close in the Option Menu Editor when you are done editing the option menu.

Scalar Fields


Pop-up Button Properties

All the properties for pop-up buttons are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the pop-up button field type:

BitmapLabel

Specifies a file containing the image to be displayed as the button label. When you click this button, a standard File Selection dialog appears. Enter the directory path of the new image you want to use.

IsAutoSized

Specifies whether the button field is forced to ignore its Height and Width property values and resize itself to fit the current text label (in the current font). If the text is changed, the button is resized accordingly. Possible values are:

TRUE

Specifies that the field is auto-sized

FALSE

Specifies that the field uses its Height and Width property values

PopupAlignment

Specifies how the pop-up button's corresponding menu will be aligned relative to the button itself. Valid options are:

ALIGN_BOTTOM ALIGN_CENTER ALIGN_LEFT ALIGN_RIGHT ALIGN_TOP

Default: ALIGN_BOTTOM

TextAlignment

Specifies the alignment for a button's text label. Valid options are:

ALIGN_LEFT ALIGN_RIGHT ALIGN_TOP ALIGN_BOTTOM ALIGN_CENTER

Default: ALIGN_CENTER

Scalar Fields


List Fields

A list field displays a series of options from which the user can make one or multiple selections depending on its SelectionType property.

OpenROAD Workbench lets you activate the “quick find keys” feature for list fields. This feature lets end users type a character to move to the first (or next) row in the column whose value begins with that character.

Note: This feature is available only when the field bias is set to FB_CHANGEABLE. For more information, see Field Biases (see page 257).

Create a List Field

You can create a list field on a form.

To create a list field


2. Select the List Field icon on the field palette.

3. Position the cursor on the form and click to create the list field.

4. Set the properties for the list field.

For complete descriptions of each field property, see List Field Properties (see page 186) and Common Field Properties (see page 239).

List Field Properties

All the properties for list fields are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the list field type:

ExactWidth

Specifies the exact outer width of the field. If both MinimumWidth and ExactWidth are positive, ExactWidth takes precedence. If both MinimumWidth and ExactWidth are 0, the default width will be just big enough to hold the largest item in the field.

Default: 0

Scalar Fields


HasSingleCharFind

Specifies whether the end user may move the focus of the list field to the next row, whose value begins with the character the end user enters. Possible values are:

TRUE

Specifies that the end user can change the field focus

FALSE

Specifies that the end user cannot change the field focus

Default: TRUE

Note: The field bias must be set to Changeable for this feature to be available. For more information, see Field Biases (see page 257).

MinimumWidth

Specifies the minimum outer width of the field. If it is smaller than the smallest width of the items in the field, the largest width of the items is used.

Default: 0

SelectionType

Indicates the number of rows that the end user may select. Valid options are:

SEL_SINGLE

Specifies that only a single row in a list field or table field may be selected at a time

SEL_MULTIPLE

Specifies that multiple rows of a list field or table field may be selected at a time. To make multiple selections, the end user clicks the desired rows while holding down the Shift key.

For more information, see Set Multiple Selections for List Fields and Table Fields (see page 264).

Default: SEL_SINGLE

VisibleRows

Specifies the number of list field options displayed on the form at one time

Default: 4

ValueList

Specifies the choices for the list field using the Value List dialog.

For more information about how to specify the list of choices, see Add and Delete List Field Items (see page 188).

Scalar Fields


Add and Delete List Field Items

The following procedures describe how to modify the list of choices that a list field provides.

Note: You can also use these procedures to modify the choices for option fields, palette fields, radio fields, list views, and option menus associated with control and pop-up buttons.

To specify items in a list field


2. Select the list field on the form.

The Property Inspector displays its properties.

3. Select the ValueList property.

The Value List dialog appears:

4. Tab to the Display column and replace the default text, "First Item," with your text.

Repeat this step as many times as needed for any remaining items.

5. Select the default item for the list field, if any, by selecting the Default option.

6. Click OK.

The item text in the list field is replaced with the items you defined.

To add another item to an existing list field



The Property Inspector displays the list field's properties.

3. Select the field's ValueList property.

The Value List dialog appears.

Scalar Fields


4. Select the row in the Value List dialog where you want to insert the new item.

5. Click the control button to the right of the Default column.

An option menu appears:

6. Select where you want to insert the new row.

A new row appears in the Value List dialog.

7. Enter the text and display values for the new choice.

8. Click OK.

To delete an item from an existing choice list


The Property Inspector displays its properties.

2. Select the field's ValueList property.


3. Highlight the row you want to delete.

4. Click the control button to the right of the Default column.

An option menu appears.

5. Select Delete Current Row.

6. Click OK.

The specified item is deleted from the list field.

Note: You can also cut, copy, and paste list items using this same control button.

Single-line Entry Fields

A single-line entry field provides one line on which you can either display information for the end user or let the user enter (or modify) information. To restrict the content of the field, you can set it to any data type. For example, you can create an entry field in which only dates are allowed.

You can also provide a format to control the appearance of the data in the field. For information about setting up a format template, see Data Format Templates (see page 637).

Scalar Fields


An entry field does not include a field title or prompt. To include a title or prompt, place free trim next to the field. For more information about creating trim, see Create a Free Trim (see page 173).

For more information about using entry fields in portable forms, see the Programming Guide.

Create a Single-line Entry Field

You can create a single-line entry field on a form.

To create a single-line entry field


2. Select the Entry Field - Single Line icon on the field palette.

3. Position the cursor on the form, click, and then drag the cursor to size the entry field.

Note: Simulate Mode provides an easy way to test the size of a field. You can create a field, switch to Simulate Mode, and enter text of the length that you expect users to enter. The text remains in the field when you switch back to development mode. If the field is too long or too short for the text, you can adjust it, using the text as a guide. To enter Simulate mode, click Tools, Simulate on the floating menu bar.

4. Set the properties for the entry field.

Note: To resize entry fields, you can use the sizing handles technique described in Move and Resize Fields (see page 161). Alternatively, modify the values of the corresponding Width or Height properties. Also, you can align an entry field with its corresponding free trim field using any of the various alignment commands on the Layout menu.

For complete descriptions of each field property, see Single-line Entry Field Properties (see page 191) and Common Field Properties (see page 239).

Scalar Fields


Single-line Entry Field Properties

All the properties for single-line entry fields are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the single-line entry field type:

CharsPerLine



ForceCase

For varchar data, specifies that input always be displayed in uppercase or lowercase, no matter how the end user enters it. Valid options are:

FC_UPPER FC_LOWER FC_NONE (no case shift)

Default: FC_NONE

FormatString

Specifies either a data format template or a format string for an entry field used as a table field cell. Valid formats vary, depending on the field's data type. If this property is not set, OpenROAD uses the data type's default format.

Note: For more information about using various types of data format templates, see Data Format Templates (see page 637).

Scalar Fields


InputMasking

Specifies whether an input mask is used to format automatically the data the end user enters. Valid values are:

TRUE

Ensures that the field accepts only data that conforms to the data format template specified. (The format template is specified in the FormatString property value cell.)

FALSE

Specifies that the field accepts any data of the appropriate type, regardless of its format

Default: FALSE

Note: For more information about input masking and using data format templates, see Data Format Templates (see page 637).

IsMandatory

Specifies whether the end user is required to enter a value in the entry field before leaving it. If the end user never enters this field, this property can be used in conjunction with the CheckFailedMandatory method of the ActiveField class to check for a value.


TRUE

Specifies that the end user must enter a value in the field before exiting it

FALSE

Specifies that the end user need not enter a value in the field before exiting it

IsMultiLine

Specifies whether an entry field is single- or multiline. Valid value are:

TRUE

Specifies that multiple lines of text can be entered in the entry field

FALSE

Specifies that the Lines property cannot be set to anything but 1. (FALSE is the default setting for single-line entry fields; TRUE is the default setting for multiline entry fields.)

Default: FALSE

Scalar Fields


IsPassword

Specifies whether text is displayed as the end user enters or edits text in the entry field. Possible values are:

TRUE

Specifies that text is not displayed

FALSE

Specifies that text is displayed

Default: FALSE

Lines

Indicates the number of lines displayed in a single-line entry field

Default: 1

Note: Do not set this property to 1 to create a single-line entry field. To create a single-line entry field, you must set the IsMultiLine property to FALSE.

MaxCharacters

Specifies the value of MaxCharacters, a read-only property, which depends on the data type:

If the data type is Integer, MaxCharacters is 13 because the maximum number of characters for an integer is 13.

If the data type is Varchar(n), MaxCharacters is also n.

Note: By setting the CharsPerLine property to the value of the MaxCharacters property, you can get an approximate match between the allowable number of characters in the field and the width of the field.

TextValue



Scalar Fields


UseWidestCharacter


TRUE


FALSE


Default: FALSE

Multiline Entry Fields

Like a single-line entry field, a multiline entry field displays data. However, at the end of each line of a multiline entry field, OpenROAD automatically wraps the text to fill in the field.

You can use a multiline entry field to display information for the end user, or to provide a data entry area where the end user can enter or modify information. To allow the end user to enter or read text that is longer than the field, you can include a vertical scroll bar. A multiline entry field may also have a horizontal scroll bar.

For information about using entry fields in portable forms, see the Programming Guide.

Create a Multiline Entry Field

You can create a multiline entry field on a form.

To create a multiline entry field


2. Select the Entry Field - Multiline icon on the field palette.

Scalar Fields


3. Position the cursor on the form, click, and then drag the cursor to size the multiline entry field.

Note: Simulate Mode provides an easy way to test the size of a field. You can create a field, switch to Simulate Mode, and enter text of the length that you expect users to enter. The text remains in the field when you switch back to development mode. To enter Simulate mode, click Tools, Simulate on the floating menu bar.

4. Set the properties for the multiline entry field.

Note: The IsMultiLine property defaults to TRUE, whereas for single-line entry fields, this property defaults to FALSE.

For complete descriptions of each field property, see Multiline Entry Field Properties (see page 195), and Common Field Properties (see page 239).

Multiline Entry Field Properties

All the properties for multiline entry fields are described under Common Field Properties (see page 239), with the exception of the following properties or values that are specific to the multiline entry field type:

CharsPerLine



ForceCase

For varchar data, specifies that input always be displayed in uppercase or lowercase, no matter how the end user enters it. Valid options are:

FC_UPPER FC_LOWER FC_NONE (no case shift)

Default: FC_NONE

Scalar Fields


FormatString

Specifies either a data format template or a format string for an entry field used as a table field cell. Valid formats vary, depending on the field's data type. If this property is not set, OpenROAD uses the data type's default format.

Note: For more information about using various types of data format templates, see Data Format Templates (see page 637).

HasHorizontalScrollBar

Specifies whether a horizontal scroll bar is provided for the end user to move left and right through the text. Possible values are:

TRUE

Specifies a horizontal scroll bar

FALSE

Specifies no horizontal scroll bar

Default: FALSE

Note: This option is available for multiline format only.

HasScrollBar

Specifies whether a vertical scroll bar is provided for the user to move up and down through the text. Possible values are:

TRUE

Specifies a vertical scroll bar

FALSE

Specifies no vertical scroll bar

Default: TRUE

Note: This option is available for multiline format only.

IsMandatory

Specifies whether the end user is required to enter a value in the entry field before leaving it. If the end user never enters this field, this property can be used in conjunction with the CheckFailedMandatory method of the ActiveField class to check for a value.


TRUE

Specifies that the end user must enter a value in the field before exiting it

FALSE

Specifies that the end user need not enter a value in the field before exiting it

Scalar Fields


IsMultiLine

Specifies whether an entry field is single- or multiline. Valid value are:

TRUE

Specifies that multiple lines of text can be entered in the entry field

FALSE

Specifies that the Lines property cannot be set to anything but 1. (FALSE is the default setting for single-line entry fields; TRUE is the default setting for multiline entry fields.)

Default: TRUE

IsPassword

Specifies whether text is displayed as the end user enters or edits text in the entry field. Possible values are:

TRUE

Specifies that text is not displayed

FALSE

Specifies that text is displayed

Default: FALSE

Lines

Specifies the number of lines displayed in a multiline entry field

MaxCharacters

Specifies the value of MaxCharacters, a read-only property, which depends on the data type:

If the data type is Integer, MaxCharacters is 13 because the maximum number of characters for an integer is 13.

If the data type is Varchar(n), MaxCharacters is also n.

Note: By setting the CharsPerLine property to the value of the MaxCharacters property, you can get an approximate match between the allowable number of characters in the field and the width of the field.

TextValue



Scalar Fields


UseWidestCharacter


TRUE


FALSE


Default: FALSE

Option Fields

An option field appears as a drop-down list of values from which the end user can make one selection. Only the current value is displayed. In addition to selecting the current value, the end user can click the down arrow to select another value from the drop-down list.

An option field has an inner border and an external border. The inner border is either on or off depending on the setting of the InnerShadowWidth property. If the inner shadow width is LW_NOLINE, the inner border is turned off; otherwise it is on.

The external border depends on the outline width setting. When the outline width is set to LW_MINIMUM, the external border is identical to the inner border. The exception to this is when the TextLabel property contains a string. In this case, the external border encloses the text label also.

Note: For information about modifying the list of available options, see Add and Delete List Field Items (see page 188).

Create an Option Field

You can create an option field on a form.

To create an option field


2. Select the Option Field icon on the field palette.

Scalar Fields


3. Place the option field on the form.

4. Set the properties for the option field, including ExactWidth or MinimumWidth, InnerShadowWidth, Style, VisibleRows, and ValueList.

Note: For complete descriptions of each field property, see Option Field Properties (see page 199) and Common Field Properties (see page 239).

Option Field Properties

All the properties for option fields are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the option field type:

ExactWidth


Default: 0

InnerShadowWidth

Specifies the width of the shadow surrounding the text value. Valid options are:

LW_DEFAULT LW_THIN LW_NOLINE

Default: LW_DEFAULT

MinimumWidth


Default: 0

Style

Indicates whether the option field's values are editable. Valid options are:

OF_NORMAL

Specifies that the option field takes on only the values specified for the ValueList property

OF_EDITABLE

Specifies that the end user can enter a value, which then becomes the current value of the field and is displayed in the option field. This value, however, is not added to the actual list of values.

Default: OF_NORMAL

Scalar Fields


VisibleRows

Specifies the number of rows displayed in the drop-down list

Default: 0

Note: If this value is set to something less than the total number of rows, a scroll bar is automatically provided to allow access to the other rows. Otherwise, all the rows will be displayed with no scroll bars.

Create a Palette Field

A palette field appears as a group of buttons, each displaying an image and representing an option to the user (similar to the field palette in the Frame Editor). The user selects an option by clicking one of the images. You can display the buttons in multiple columns, either horizontally or vertically.

When you add an option to a palette field, you must specify an image file in addition to the text and integer values.

For information about modifying the available options, see Add and Delete List Field Items (see page 188).

To create a palette field


2. Select the Palette icon on the field palette.

3. Place the palette field on the form using its upper left corner as a guide.

Note: When determining the placement of a palette field on a form, keep in mind that its size is determined by its contents.

4. Select the ValueList property in the Property Inspector.

The Value List dialog appears. For example:

Scalar Fields


This dialog lets you specify the image and tooltip text to be associated with each button in the palette field. Edit the information and click OK.

For more information about defining choice lists, see Add and Delete List Field Items (see page 188).

5. Set the other properties for the palette field, including Columns and Orientation.


Palette Field Properties

All the properties for palette fields are described under Common Field Properties (see page 239), with the exception of the following property that is specific to the palette field type:

Columns

Specifies the number of columns in the field

Note: The columns can be displayed horizontally or vertically, depending on the value of the Orientation property.

Default: 2

Create a Radio Field

A radio field appears as a group of buttons, each of which represents an option for users of the application. When the user clicks a radio button, the selected option is turned on and all other options are turned off. You can display the buttons in multiple columns, either vertically or horizontally.

For more information about modifying the available options, see Add and Delete List Field Items (see page 188).

Note: You can create Alt speed keys for radio fields. For more information, see How You Can Define an Alt Speed Key (see page 261).

To create a radio field


2. Select the Radio Field icon on the field palette.

Scalar Fields


3. Click to place the radio field on the form.

Note: When determining the placement of a radio field on a form, keep in mind that its size is determined by its contents.

4. Set the properties for the radio field, including Columns and ValueList.

Note: For complete descriptions of each field property, see Radio Field Properties (see page 202) and Common Field Properties (see page 239).

Radio Field Properties

All the properties for radio fields are described under Common Field Properties (see page 239), with the exception of the following properties or values that are specific to the radio field type:

Columns

Specifies the number of columns in the field

Note: The columns can be displayed horizontally or vertically, depending on the value of the Orientation property.

Default: 1

ExactWidth


Default: 0

MinimumWidth


Default: 0

Scalar Fields


Create Scroll Bars

An independent scroll bar appears as an “elevator” that the user can slide into position on a bar to move the displayed portion of a form or field. For example:

An independent scroll bar looks identical to the scroll bars in list fields, table fields, multiline entry fields, and viewports. However, because an independent scroll bar is not associated with a field, you must provide a script to specify the actions that occur each time the user moves the elevator.

To create an independent scroll bar


2. Select the Scroll Bar icon on the field palette.

3. Position and size the scroll bar on the form.

4. Set the properties for the scroll bar, including ElevatorSize, PageSize, and StepSize.

Note: The scroll bar elevator is not sizable in Windows NT. This behavior may imply that there are additional rows in a table field even when all the rows are visible.

For complete descriptions of each field property, see Scroll Bar Properties (see page 204) and Common Field Properties (see page 239).

Scalar Fields


Scroll Bar Properties

All the properties for scroll bars are described under Common Field Properties (see page 239), with the exception of the following properties or values that are specific to the scroll bar field type:

ElevatorSize

Specifies the size of the elevator (an integer value).

The elevator is the indicator in the middle of the bar that normally represents the portion of the scrolled object that is currently displayed. The end user scrolls the bar by clicking and holding the mouse cursor on the elevator, and moving the mouse.

Default: 20

Note: If you attempt to change the ElevatorSize property to a value greater than the maximum value minus the current value, which is the value at which the top or left edge of the elevator rests, OpenROAD sets the ElevatorSize to the maximum value minus the current value. To avoid this, change the MaxValue property before setting ElevatorSize.

MaxValue


Default: 100

MinValue


Default: 0

PageSize

Specifies the size of the change in value for each page step (an integer value).

A page step is the distance the bar is scrolled each time the user clicks the arrow at either end of a scroll bar. For example, a value of 5 moves the elevator five units in the appropriate direction.

Default: 20

StepSize

Specifies the size of the change in value when clicking the step marker (an integer value).

Step markers are above and below the scroll bar elevator, often at the top and bottom of the scroll bar. For example, a value of 10 moves the elevator 10 units in the appropriate direction.

Default: 1

Scalar Fields


Create Sliders

A slider consists of a slider bar and a drag box. The user selects an integer value by dragging the box into position on the bar. A slider appears as a range of integer values from which the user can make one selection. You can specify the range or use the default range of 1 to 100.

To create a slider field


2. Select the Slider icon on the field palette.

3. Position and size the slider field on the form.

4. Set the properties for the slider field, including BgColor, MinValue, MaxValue, and Orientation.

Note: For complete descriptions of each field property, see Slider Field Properties (see page 205) and Common Field Properties (see page 239).

Slider Field Properties

All the properties for sliders are described under Common Field Properties (see page 239), with the exception of the following properties or values that are specific to the slider field type:

MaxValue


Default: 100

MinValue


Default: 0

Toggles (Check Boxes)

A toggle appears as an option that the user can click on or off (enable or disable). The label for a toggle can be text or an image. You can supply one text phrase for both states and use the toggle indicator, or you can turn off the toggle indicator and supply separate phrases or images for the on and off states.

Note: For more information about how text and image labels and the indicator interact, see the ToggleField class topic in the Language Reference Guide.

Scalar Fields


To display a group of toggles, you should create a toggle stack. When the toggles are included in a stack, rearranging the order of the toggles is easy because OpenROAD ensures that they are always correctly aligned. For more information about creating stack fields, see Create a Stack Field (see page 220).

Create a Toggle (Check Box)

You can create a toggle on a form.

To create a toggle


2. Select the Toggle icon on the field palette.

3. Place the toggle field on the form.

Note: When determining the placement of a toggle field on a form, keep in mind that its size is determined by its contents (text or bitmap).

4. Set the properties for the toggle field, including HasImageandText, HasIndicator, OffTextLabel, and OnTextLabel.

Note: For complete descriptions of each field property, see Toggle Properties (see page 206) and Common Field Properties (see page 239).

Toggle Properties

All the properties for toggle fields are described under Common Field Properties (see page 239), with the exception of the following properties or values that are specific to the toggle field type:

HasImageandText

Specifies whether to display both an image and text as the label

Default: FALSE

Note: If HasImageandText is set to TRUE and a bitmap label is specified, the HasIndicator property is ignored. If neither OffBitmapLabel nor OnBitmapLabel is specified, then the toggle field behaves as if HasImageandText is FALSE.

HasIndicator

Specifies whether a toggle indicator, a check mark, is displayed next to the label

Default: TRUE

Scalar Fields


OffBitmapLabel

Specifies a file containing the image to be displayed when the toggle is disabled. When you click this button, a standard File Selection dialog appears. Enter the directory path of the new image you want to use.

If you specify the OnBitmapLabel property but do not specify the OffBitmapLabel property, OpenROAD uses an inverse of the OnBitmapLabel bitmap image as the OffBitmapLabel.

Default: No Bitmap

Note: If OffBitmapLabel is set to Bitmap, then the HasIndicator property must also be set to TRUE.

OffTextLabel

Specifies the text displayed when the toggle is disabled

Default: Toggle Item

OnBitmapLabel

Specifies a file containing the image to be displayed when the toggle is enabled. When you click this button, a standard File Selection dialog appears. Enter the directory path of the new image you want to use.

If you specify the OffBitmapLabel property but do not specify the OnBitmapLabel property, OpenROAD uses an inverse of the OffBitmapLabel bitmap image as the OnBitmapLabel. See the example in OffBitLabel.

Default: No Bitmap

Note: If OnBitmapLabel is set to Bitmap, then the HasIndicator property must also be set to TRUE.

OnTextLabel

Specifies the text displayed when the toggle is enabled

Default: Toggle Item

List Views

A list view field lets the end user view and optionally manipulate or edit a list of items. The contents of the list view can be displayed in one of four display formats, or styles:

List

A simple list view

Details

A detailed list view

Scalar Fields


Icons

A list view with full-sized (large) icons

Small icons

A list view with reduced size (small) icons

An example of a list view field is the Connection Profiles portlet on the Connect tab of OpenROAD Workbench, shown here in Details style:

Note: For more information about dynamic creation of list view fields, see the Programming Guide.

Create a List View

You can create a list view on a form.

To create a list view


2. Select the List View icon on the field palette.

3. Place the list view field on the form.

4. Accept the default value of TRUE for the HasColumnHeaders property in the Property Inspector, as well as the default value of LVFS_DETAIL for the Style property.

Note: For complete descriptions of each field property, see List View Properties (see page 210) and Common Field Properties (see page 239).

5. Select the ColAttributes property.

The Column Attributes dialog appears:

Scalar Fields


6. Click in the Width column of the first item and change the column width (for example, 1000).

7. Tab to the next column, Header Text, and replace the default text, Column 1, with text of your choice (for example, Gender).

8. Repeat Steps 6 and 7, replacing the default text with your values for as many columns as you want for the field.

Note: To add a column, tab to the Width column in the first empty row and enter a value. This action in effect changes the number of columns in your list view.

9. Set the Text Alignment of all the columns using the drop-down menus.

Note: The first column in a list view must be left-aligned.

10. Click OK.

The ColAttributes property indicates the number of columns in your list view:

11. Select the ValueList property to specify the items for the first column only using the Value List dialog. (For example, you might want to specify "males" and "females" for the Gender column.)

Note: For more information about using the ValueList property to define a choice list for the list view, see Add and Delete List Field Items (see page 188). Also, for more information about populating the other columns in a list view, see the chapter “Working with List Views and Tree Views” in the Programming Guide.

Scalar Fields


List View Properties

All the properties for list views are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the list view field type:

ColAttributes

Specifies the number of columns, their width, and the alignment of text using the Column Attributes dialog

Default: 2 columns

Note: You can also specify the corresponding column headers using the same dialog, if HasColumnHeaders is set to TRUE.

DragItem

Specifies whether the end user may use the drag-and-drop method for manipulating items in the list view. Possible values are:

TRUE

Specifies that the end user may use drag-and-drop

FALSE

Specifies that the end user may not use drag-and-drop

Default: FALSE

Note: This property is available only when the Style property is set to LVFS_ICON or LVFS_SMALLICON.

EditLabel

Specifies whether the end user may edit the text labels. Possible values are:

TRUE

Specifies that the end user may edit text labels

FALSE

Specifies that the end user may not edit text labels

Default: FALSE

Scalar Fields


HasColumnHeaders

Specifies whether you must specify a column heading for each column in the list view. Possible values are:

TRUE

Specifies that you must specify a column heading for each column

FALSE

Specifies that the list view has no column headings

Default: TRUE

LargeImageHeight

Specifies the height of the images used for the full-sized icons when the Style property is set to LVFS_ICON

Default: 32 pixels

LargeImageWidth

Specifies the width of the images used for the full-sized icons when the Style property is set to LVFS_ICON

Default: 32 pixels

SmallImageHeight

Specifies the height of the images used for the small icons used when the Style property is set to LVFS_SMALLICON

Default: 16 pixels

SmallImageWidth

Specifies the width of the images used for the small icons used when the Style property is set to LVFS_SMALLICON

Default: 16 pixels

Style

Specifies the list view display format, or style. Valid options are:

LVFS_DETAIL

Displays items as a list with detailed information

LVFS_LIST

Displays items as a simple list

Scalar Fields


LVFS_ICON

Displays items as full-sized (large) icons with text labels below. See related properties, LargeImageHeight and LargeImageWidth.

LVFS_SMALLICON

Displays items as small icons with text labels below. See related properties, SmallImageHeight and SmallImageWidth.

Default: LVFS_DETAIL

Tree Views

A tree view field presents the end user with a hierarchical list of items in a tree structure that can be expanded or collapsed. Each item in the tree view consists of a label with an optional icon, and each item may also have an associated list of subitems.

The contents of the tree view can be displayed with buttons that expand and collapse subitems and with lines that link subitems to their parent items. Other end user options include highlighting the selected item in the tree view and editing item labels.

An example of a tree view field is OpenROAD's Field Tree window, discussed in Field Tree (see page 141). For example, the following Field Tree window displays the hierarchy of the fields in the Main frame of the SIS sample application:

Each item has a text label and an associated icon. Also, each branch of the tree can be expanded or collapsed, as indicated by the + and - buttons to the left of the icons, including the root of the tree, Main.

Scalar Fields


Note: The contents of a tree view are defined programmatically. Even though you can place a tree view field on your form and specify its properties, you cannot define its contents using the Frame Editor. Therefore, it initially appears empty. For more information about tree view fields, see the chapter “Working with List Views and Tree Views” in the Programming Guide.

Create a Tree View

You can create a tree view on your form.

To add a tree view field to your form


2. Select the Tree View icon on the field palette.

3. Place the tree view field on the form.

4. Set the properties for the tree view field, including AllowLabelEdit, HasButtons, HasLines, and HasRootLine.

As stated previously, the tree view initially appears empty even if you set HasButtons, HasLines, and HasRootLine to TRUE because the contents of the tree view must be defined programmatically.

Note: For complete descriptions of each field property, see Tree View Properties (see page 214) and Common Field Properties (see page 239). Additionally, see the Tree, TreeNode, and TreeViewField class topics in the Language Reference Guide.

Scalar Fields


Tree View Properties

All the properties for tree views are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the Tree View field type:

AllowLabelEdit

Specifies whether the end user may edit the text labels for items in the tree view. Possible values are:

TRUE

Specifies that the items are editable

FALSE

Specifies that the items are not editable

Default: FALSE

HasButtons

Specifies whether Expand/Collapse (+/-) buttons are placed to the left of a parent item so that the end user can click the button to expand or collapse its subitems. This provides the user with an alternative to double-clicking an item. Possible values are:

TRUE

Specifies Expand/Collapse buttons

FALSE

Specifies no Expand/Collapse buttons

Default: TRUE

Note: The HasButtons property by itself does not add buttons at the root level of the hierarchy. To do so, you must set all three properties—HasButtons, HasLines, and HasRootLine—to TRUE.

HasLines

Specifies that lines are drawn that link subitems to their parent items in the tree hierarchy. Possible values are:

TRUE

Specifies that lines are drawn

FALSE

Specifies no lines

Default: TRUE

Composite Fields


HasRootLine

Specifies whether lines are drawn, linking parent items to the root item. A root item is a top-level item in a hierarchical tree structure that has no parent. Possible values are:

TRUE

Specifies that lines are drawn

FALSE

Specifies no lines

Default: TRUE

ShowSelection

Specifies whether an item in a tree view remains highlighted when you tab to another field. Valid settings are:

TRUE

Specifies that the highlighted or selected text remains highlighted when you tab to another field. Any item in the tree view stays marked (until you move to another record in a database or close the window).

FALSE

Removes highlighting when an item in a tree view loses focus (for example, if you tab to another field). When the tree view regains focus, the previous selection will not be highlighted.

Default: TRUE

Composite Fields A composite field is a field that may contain other fields. Most composite fields can contain fields of any type, even other composite fields. A field contained within a composite field is referred to as a child field.

Composite fields include the following:

Flexible forms

Subforms

Matrix fields

Stack fields

Table fields

Viewports

Tab folders

Composite Fields


Like other fields, composite fields have events, such as ChildSetValue, that let you control the end user's interaction with the field.

Most composite fields are created by selecting the fields that you want to group together and then choosing one of the composite field type commands from the Group menu.

After you have created a composite field, you may add new fields to it by selecting the field from the palette and clicking the mouse inside the boundaries of the composite field. You can also delete fields in a composite field by selecting them and clicking Edit, Delete on the floating menu bar.

To add other existing fields to a composite field after it's been created, select the field and click Edit, Cut, and then paste it into the composite field (Edit, Paste).

Create a Composite Field

You can create a composite field that contains other fields—with the exception of tab folders and their tab pages.

To create a composite field


2. Create one or more basic fields using the procedures detailed elsewhere in this chapter.

3. Select the fields to be included in the composite field.

4. Select a composite field type for the selection group from the Group menu.

5. Specify the composite field's properties just like you would do for any other field.

The following sections discuss each of the composite fields in OpenROAD and include information about creating the field and setting its properties.

Create a Flexible Form

A flexible form appears as a group of fields that are contained by a flexible boundary. When you move an individual field in the group, the boundary stretches accordingly. If you select the flexible form itself, you can move the group of fields as a unit.

Flexible form fields are provided for form editing only; creating a flexible form field has no effect on the appearance of the form. By creating a flexible form, you can create a permanent selection group of fields.

Composite Fields


To create a flexible form


2. Select the group of fields to be included in the flexible form.

Note: For information about selecting fields, see Select Fields (see page 157).

3. Click Group, Flexible Form.

4. Set the properties and style for the flexible form.

Note: For complete descriptions of each field property, see Common Field Properties (see page 239).

Flexible Form Properties

Flexible forms have properties that are common to many other fields. Therefore, all the properties for flexible forms are described under Common Field Properties (see page 239).

Matrix Fields

A matrix field appears as a rectangle that contains fields arranged in rows and columns. The component fields stay aligned even if you rearrange or reorder them. The matrix field can include any combination of fields.

A matrix field is useful for forms that you intend to port to other systems, because the individual fields stay aligned when you port the form. For more information about using matrix fields to create portable forms, see the Programming Guide.

A matrix field is made up of cells, some of which can be empty. After creating a matrix field, you can add fields, move fields between cells, and remove fields. You can expand the matrix field by adding rows or columns or shrink the matrix field by deleting rows or columns.

By default, fields within a matrix field are centered in their respective fields. You can change the position of fields within the cells by using the Property Inspector to change the ChildGravity property of the matrix field. To change the position of an individual field within its matrix field cell, set the field's Gravity property. (You may use either the Property Inspector or the Gravity command on the Layout menu to change a field's gravity setting.)

Note: For more detailed information about the Gravity and ChildGravity properties, see the Gravity section under Common Field Properties (see page 239).

Composite Fields


Create a Matrix Field

You can create a matrix field to align combined fields.

To create a matrix field


2. Select the fields to be included in the matrix field.


3. Click Group, Matrix Field.

Workbench moves the individual fields into a matrix field, keeping the fields in similar relative positions.

4. Set the properties and style for the matrix field.

Note: For complete descriptions of each field property, see Matrix Field Properties (see page 218) and Common Field Properties (see page 239).

Matrix Field Properties

All the properties for matrix fields are described under Common Field Properties (see page 239), with the exception of the following properties or values that are specific to the matrix field type:

ChildBottomMargin

Specifies the bottom margin (in 1000ths of an inch) around each child field within the composite field, as well as between the child field and the bottom boundary of the composite field

ChildGravity

Specifies the default position of each child field relative to its cell in the composite field. Valid alignment options are:

FA_DEFAULT (system default value) FA_NONE FA_TOPCENTER FA_TOPLEFT FA_TOPRIGHT FA_CENTERLEFT FA_CENTER FA_CENTERRIGHT FA_BOTTOMCENTER FA_BOTTOMLEFT FA_BOTTOMRIGHT

For more information about the Gravity and ChildGravity properties, see the Gravity section under Common Field Properties (see page 239).

Composite Fields


ChildLeftMargin

Specifies the left margin (in 1000ths of an inch) around each child field within the composite field, as well as between the child field and the left boundary of the composite field

ChildRightMargin

Specifies the right margin (in 1000ths of an inch) around each child field within the composite field, as well as between the child field and the right boundary of the composite field

ChildTopMargin

Specifies the top margin (in 1000ths of an inch) around each child field within the composite field, as well as between the child field and the top boundary of the composite field

CollapsePolicy

Specifies what happens when an entire row or column in the matrix is empty. Valid options are:

CP_NONE

Specifies that empty rows and columns are allowed and maintained. If you set the Rows and Columns properties, the settings are enforced.

CP_BOTH

Specifies that empty rows and columns are removed automatically, as soon as the last field is removed from the row or column. Setting either the Rows or Columns property has no effect.

CP_ROWS

Specifies that empty rows are removed automatically, as soon as the last field in the row is removed. Setting the Rows property has no effect. However, empty columns are maintained, and you can set the Columns property.

CP_COLUMNS

Specifies that empty columns are removed automatically, as soon as the last field in the column is removed. Setting the Columns property has no effect. However, empty rows are maintained, and you can set the Rows property.

Default: CP_BOTH

Columns

May let you specify the number of columns within the matrix field, depending on the CollapsePolicy property setting

Composite Fields


Rows

May let you specify the number of rows within the matrix field, depending on the CollapsePolicy property setting

Note: The number of rows and columns should be consistent with the total number of child fields in the matrix field.

Stack Fields

A stack field appears as a set of fields that remain aligned if you rearrange or reorder them. The stack can include any combination of fields.

A stack field is useful for laying out fields so that they stay aligned when you port the form to another environment. For more information about using stack fields to create portable forms, see the Programming Guide.

Fields in a stack field are arranged either vertically or horizontally in a one-dimensional array, depending on the setting of the Orientation property in the Property Inspector.

The ChildTopMargin, ChildBottomMargin, ChildLeftMargin, and ChildRightMargin properties let you specify margins for each child field of a stack field. The ChildGravity property determines the position of child fields in the stack field cells. You can use the Property Inspector to set these properties; you can also use the Gravity property of a stack field's children to control the placement of the children in the stack field cells.

Create a Stack Field

You can create a stack field to align a group of fields.

To create a stack field


2. Select the fields to be included in the stack field.


3. Click Group, Stack Field.

Workbench moves the selected fields into a vertical or horizontal stack. To change this orientation, set the Orientation property in the Property Inspector.

4. Set the properties and style for the stack field.

Note: For complete descriptions of each field property, see Stack Field Properties (see page 221) and Common Field Properties (see page 239).

Composite Fields


Stack Field Properties

All the properties for stack fields are described under Common Field Properties (see page 239), with the exception of the following properties or values that are specific to the stack field type:

ChildBottomMargin

Specifies the bottom margin (in 1000ths of an inch) around each child field within the composite field, as well as between the child field and the bottom boundary of the composite field

ChildGravity

Specifies the default position of each child field relative to its cell in the composite field. Valid alignment options are:


For more information about the Gravity and ChildGravity properties, see the Gravity section under Common Field Properties (see page 239).

In general, this property should be set to FA_NONE. To align the child fields, use one of the alignment commands on the Layout menu.

ChildLeftMargin

Specifies the left margin (in 1000ths of an inch) around each child field within the composite field, as well as between the child field and the left boundary of the composite field

ChildRightMargin

Specifies the right margin (in 1000ths of an inch) around each child field within the composite field, as well as between the child field and the right boundary of the composite field

ChildTopMargin

Specifies the top margin (in 1000ths of an inch) around each child field within the composite field, as well as between the child field and the top boundary of the composite field

Composite Fields


Create a Subform

A subform appears as a group of fields that are contained by a fixed boundary on a form. You determine the boundary size when you create the subform. The fields within the subform can be of any type.

To create a subform


2. Select the fields to be grouped as a subform.

3. Click Group, Subform.

A composite subform field is created.

For complete descriptions of each field property, see Subform Properties (see page 222) and Common Field Properties (see page 239).

Subform Properties

All the properties for subforms are described under Common Field Properties (see page 239), with the exception of the following property values that are specific to the subform field type:

ChildGravity

Sets the position of each child field with respect to the subform. Valid alignment options are:


Unless the subform has only one child field, set ChildGravity to FA_NONE. To set the position of a child field relative to the subform, use the Gravity property of the individual child fields. You can also use the various alignment commands on the Layout menu to align child fields with respect to one another.

Note: For more information about the Gravity and ChildGravity properties, see the Gravity section under Common Field Properties (see page 239).

Composite Fields


Table Fields

A table field appears as active fields arranged in rows and columns. Each column is a stack of identical active fields. Each row consists of one active field from each column in the table field. You specify how many rows are displayed at one time; a vertical scroll bar lets the end user display the remaining rows.

Note: The end user can scroll through a table field by using the scroll bar or by tabbing through the columns.

OpenROAD Workbench provides two orientations for table fields:

Vertical table field

Displays columns vertically and rows horizontally

Horizontal table field

Displays columns horizontally and rows vertically

OpenROAD lets you activate the “quick find keys” feature for table fields. This feature lets end users type a character to move to the first (or next) row in the column whose value begins with that character.

Note: This feature is available only when the field bias is set to the Landable mode. For more information, see Field Biases (see page 257).

The following sections describe how to create and modify a table field. For more information about working with table fields in 4GL code, see the Programming Guide.

Create a Table Field

You create a table field from one or more existing fields. When you select Table Field from the Group menu on the floating menu bar, Workbench uses each selected field as the “prototype” cell for one column in the table field.

To create a table field


2. Select the fields to be included in the table field.


3. Click Group, Table Field.

OpenROAD creates the table field using the height of the tallest field to determine the height of each row. The width of each column is equal to whichever is greater: the length of the field itself or the length of the column title.

Composite Fields


4. Set the properties for the table field and its columns using the Property Inspector.

A table field consists of components that you can work with individually. You can also rearrange, resize, insert, and delete individual columns in the table field.

Note: For complete descriptions of each table field and column field property, see Table Field Properties (see page 510) and Column Field Properties (see page 229), respectively. Also, see Common Field Properties (see page 239).

After creating the table field, you can edit the table and column titles by switching to Text Mode. For more information about editing table fields, see How You Can Modify a Table Field (see page 230).

Note: You can also create table fields dynamically, including creating and mapping arrays to the table field so that it can accept and manage data. For an in-depth discussion about dynamically creating fields in OpenROAD, see the Programming Guide.

Table Field Properties

All the properties for table fields are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the table field type:

ColSeparatorColor

Specifies the color of the lines that separate table field columns

Default: CC_FOREGROUND

ColSeparatorStyle

Specifies the style of the lines that separate table field columns. Valid options are:

LS_DEFAULT (system default value) LS_SOLID LS_DASH LS_DOT LS_DASHDOT LS_DASHDOTDOT

Default: LS_SOLID

Composite Fields


ColSeparatorWidth

Specifies the width of the lines that separate table field columns. Valid options are:

LW_DEFAULT (system default value) LW_NOLINE LW_MINIMUM LW_EXTRATHIN LW_VERYTHIN LW_THIN LW_MIDDLE LW_THICK LW_MAXIMUM

Default: LW_NOLINE

ColumnResizable

Specifies whether the column is resizable

Default: FALSE

ColumnsDisplayed

Specifies the number of visible columns. If fewer than the total number of columns, a horizontal scroll bar appears.

CurOps

Specifies which operations for table fields are enabled or disabled regardless of the frame's mode. Valid options are:

OP_NONE

Specifies that no operations on the table field are allowed

OP_APPEND

Specifies that auto append is allowed at the end of the table field only

OP_APPENDINSERT

Specifies that appending or inserting rows to the table field is allowed

OP_APPENDDELETE

Specifies that auto append at the end of the table field and deleting rows are allowed

OP_APPENDINSERTDELETE

Specifies that all operations on the table field are allowed

OP_DELETE

Specifies that deleting rows from the table field only is allowed

Default: OP_NONE

Composite Fields


HasControlButton

Specifies whether OpenROAD creates a control button with default table field commands. You can edit the control button to add more commands or delete or modify the default commands. Possible values are:

TRUE

Specifies default table field commands

FALSE

Does not specify default table field commands

Default: FALSE

For more information about control buttons, see Create a Control Button (see page 182).

HasHeader

Specifies whether the column titles are displayed. Possible values are:

TRUE

Specifies column headers

FALSE

Specifies no column headers

Default: TRUE

HasHeader Buttons

Specifies whether the column titles are displayed as buttons. The table field has the same appearance as a list view. Possible values are:

TRUE

Specifies that column headers are displayed as buttons

FALSE

Specifies that column headers are not displayed as buttons

Default: TRUE

HasScrollBar

Specifies whether the table field has a scroll bar that lets end users scroll through the rows. Possible values are:

TRUE

Specifies a scroll bar

FALSE

Specifies no scroll bar

Default: TRUE

Composite Fields


IsHighlighted

Specifies whether the row that the end user has selected—the current row—is highlighted. Possible values are:

TRUE

Specifies that the current row is highlighted

FALSE

Specifies that the current row is not highlighted

Default: TRUE

NumVisibleRows

Specifies the number of rows to be displayed

Default: 4

QueryOps

Specifies the CurOps value to use when the CurMode property for a frame is set to FM_QUERY

ReadOps

Specifies the CurOps value to use when the CurMode property for a frame is set to FM_READ

RowSeparatorColor

Specifies the color of the lines between table field rows


RowSeparatorStyle

Specifies the style of the lines between table field rows. Valid options are:


Default: LS_SOLID

Composite Fields


RowSeparatorWidth

Specifies the width of the lines between table field rows. Valid options are:


Default: LW_NOLINE

ScrollingChangesSelection

Specifies whether scrolling the selected row out of view sets the new selected row to the topmost or bottommost visible row of the table field, depending on the direction of the scrolling. Otherwise, a single selection is unchanged by scrolling with the scroll bar. Possible values are:

TRUE

Specifies that the selected row changes as rows are scrolled

FALSE

Specifies that the selected row does not change as rows are scrolled

Default:

TRUE, if SelectionType is set to SEL_SINGLE

FALSE, if SelectionType is SEL_MULTIPLE (this property is automatically set to FALSE)

SelectionType

Indicates the number of rows that the end user may select. Valid options are:

SEL_SINGLE

Specifies that only a single row in a list field or table field may be selected at a time

SEL_MULTIPLE

Specifies that multiple rows of a list field or table field may be selected at a time. To make multiple selections, the end user clicks the desired rows while holding down the Shift key.

For more information, see Set Multiple Selections for List Fields and Table Fields (see page 264).

Default: SEL_SINGLE

Composite Fields


Title

Defines the title to be displayed for the table field

UpdateOps

Specifies the CurOps value to use when the CurMode property for a frame is set to FM_UPDATE

User1Ops

Specifies the CurOps value to use when the CurMode property for a frame is set to FM_USER1

User2Ops


User3Ops


Column Field Properties

Column fields have the following properties:

ColumnNumber

Specifies the ordinal position of the column in the table field

Default: 1, indicating the top or left

HasCellAttributes

Specifies whether you can set visual properties for individual cells in the column. Possible values are:

TRUE

Specifies that you can set visual properties for individual cells

Note: Setting HasCellAttributes to TRUE impacts application performance. For more information, see the chapter “Working with Arrays, Table Fields, and Collections” in the Programming Guide.

FALSE

Specifies that you cannot set visual properties for individual cells

Default: FALSE

Composite Fields


HasSingleCharFind

Specifies whether the end user may move the focus of the specified column to the next row whose value begins with the character the end user enters. (This property is valid only while focus is on a Landable entry field in the specified column.) Possible values are:

TRUE

Specifies that the end user can move the focus

FALSE

Specifies that the end user cannot move the focus

Default: TRUE

Title

Specifies the title that OpenROAD displays for the column field

Modify a Table Field

You can modify a table field in the following ways:

Move columns

Change column properties

Change visual characteristics of columns

Copy and paste other fields into a table field

See the appropriate procedure, following, for instructions on performing these actions.

To move a column

To select a column to move, click any cell in the column except the first cell.

The entire column is highlighted, and you can then move it as necessary.

To change the properties of a column

The first cell in the column is the prototype cell for the column. Select the first cell in the column to change the properties (in the Property Inspector) for the entire column.

To change the visual characteristics of a column

Select the entire column by clicking any cell in the column except the top cell. Change the properties in the Property Inspector.

Composite Fields


To copy and paste other fields into a table field

Use the commands on the Edit menu of the floating menu bar.

The copied field becomes the prototype for a new column of the table field.

For more information about copying fields, see Copy and Paste a Field (see page 162).

Viewports

A viewport provides a window on the form for viewing a larger field. The end user uses the viewport's scroll bars to view undisplayed portions of the field in the viewport. A viewport can contain one field of any type.

Using a viewport lets you add a field to a form that would not otherwise fit in a specified area. Viewports are most often used for images or subforms because you can set the height and width of the work area (inner rectangle) of a viewport.

Create a Viewport

When you create a viewport, you select a single field, a composite field, or a set of fields. OpenROAD Workbench automatically creates a flexible form that contains the fields you have selected. The viewport then contains a single composite field, the new flexible form field.

To create a viewport for an image field


2. Select the image field.


3. Click Group, Viewport.

The image field is then enclosed within a viewport field.

4. Set the properties for the viewport.

Note: For complete descriptions of each field property, see Viewport Properties (see page 232) and Common Field Properties (see page 239).

Composite Fields


Viewport Properties

All the properties for viewports are described under Common Field Properties (see page 239), with the exception of the following properties that are specific to the viewport field type:

ClipHeight

Specifies the height in pixels to which the image should be clipped

ClipWidth

Specifies the width in pixels to which the image should be clipped

ScrollBarWidth

(Read-only) Displays the width of the viewport's scroll bars

XOffset

Specifies the coordinate of the field in the viewport that appears at the left edge of the viewport. This property always has a non-negative value. Setting this property to 0 moves the viewport to the left edge of the viewed field.

YOffset

Specifies the coordinate of the field in a viewport that appears at the upper edge of the viewport. This property always has a non-negative value. Setting this property to 0 moves the viewport to the top edge of the field.

Create a Tab Folder

A tab folder field is used to present data or a series of choices in a multiple-page format. By default, it consists of three blank tab pages that resemble file folders. When the end user clicks one of the tabs on the tab bar, the corresponding page moves to the foreground and enables access to its data and fields.

This particular type of field lets you design forms that conserve space and present data more efficiently to the end user.

To create a Tab Folder


2. Select the Tab Folder icon on the field palette.

3. Position and size the tab folder field on the form.

Composite Fields


4. Specify the tab folder properties:

a. In the Property Inspector for the tab folder field, click the TabPageArray property.

The Tab Page Array dialog appears:

b. Replace the default text label, Page1, with the name of your first tab.

c. Tab to the other text labels, and replace the default text with your labels.

d. Specify any other settings for your tabs.

Note: For complete descriptions of each tab folder property, see Tab Folder Field under Tab Folder Properties (see page 234) and Common Field Properties (see page 239).

e. Click OK.

5. Specify Tab bar properties by clicking the tab bar field.

The Property Inspector changes focus from the tab folder field to the tab bar field. A tab folder consists of tab page fields and a tab bar field, as well as the tab folder field:

6. Set the SelectedIsBold property to TRUE in the Property Inspector.

7. (Optional) Specify other properties, such as DisplayBitmap, MultiTabStyle, OutlineColor, TabBgColor, and TabShape, for the tab bar field.

Note: For complete descriptions of each tab bar property, see Tab Bar Field under Tab Folder Properties (see page 234), and Common Field Properties (see page 239).

Composite Fields


8. Specify Tab page properties by clicking the Name Tab.

This lets you access the tab's corresponding tab page field:

9. Change the BgColor property to the color of your choice.

Note: For complete descriptions of each tab page property, see Tab Page Field under Tab Folder Properties (see page 234), and Common Field Properties (see page 239).

10. Add fields to this page, using the same method you used to add fields to the frame.

Note: A wizard is one example of the kind of frame that you can create using the tab folder. A wizard typically provides a sequence of pages; each page represents a step in a process and prompts the user to enter data or make decisions. The user proceeds to the next step, backs up to a previous step, or cancels the entire process. A Finish button on the last page of the wizard lets the user complete the process and commit the transaction.

Tab Folder Properties

All the properties for tab folders, as well as their corresponding tab page and tab bar fields, are described in Common Field Properties (see page 239), with the exception of the following properties that are specific to the tab folder field type.

Tab Folder Field

CurPageIndex

Indicates the index of the currently mapped tab page

Note: You can optionally change this value, which causes the current page to be unmapped and a new page to be mapped. It does not, however, cause any 4GL events to be generated. For more information, see the TabFolder class topic in the Language Reference Guide.

Composite Fields


IsShadowed

Specifies whether the tab folder shadows match those of its associated tab bar. Possible values are:

TRUE

Specifies that the tab folder shadows match the tab bar

FALSE

Specifies that the tab folder shadows do not match the tab bar

Default: TRUE

TabPageArray

Specifies the array containing all the tab pages in the tab folder. Only one tab page is displayed at a time. You can optionally insert new tab pages, or delete or modify any existing ones using this attribute.

Tab Page Field

DelayMkwidget

Specifies when the tab page is constructed. Possible values are:

TRUE

Specifies that the tab page is not actually constructed until it is displayed. (This may improve performance.)

FALSE

Specifies that the tab page is constructed at the time the tab folder is first displayed

Default: TRUE

For more information, see the TabPage class topic in the Language Reference Guide.

Tab Bar Field

BitmapPosition

Specifies which side of the tab the bitmap label is placed on. Valid options are:

POS_TOP POS_LEFT POS_BOTTOM POS_RIGHT

Default: POS_LEFT

Note: The DisplayBitmap property must be set to TRUE for this property to have effect.

Composite Fields


DisplayBitmap

Specifies whether a bitmap label is to be displayed on the tab. Possible values are:

TRUE

Displays a bitmap label

FALSE

Displays no bitmap label

Default: FALSE

DisplayText

Specifies whether a text label is to be displayed on the tab. Possible values are:

TRUE

Specifies a text label

FALSE

Specifies no text label

Default: TRUE

IsFixedWidth

Specifies whether all tabs are of equal width. Possible values are:

TRUE

Specifies tabs are of equal width

FALSE

Specifies that tabs may be of different widths

Default: TRUE

MultiTabStyle

Specifies what style to use if there are too many tabs to fit in the tab bar's display area. Valid options are:

TAB_SCROLL

Specifies that the tab bar scrolls to display additional tabs

TAB_OVERLAP

Specifies that the tab bar overlaps additional tabs

Default: TAB_SCROLL

NormalTabColor

Specifies the color of an unselected, or normal, tab


Composite Fields


NormalTextColor

Specifies the text color for an unselected tab

Default: CC_BLACK

SelectedIsBold

Specifies whether the text label of the selected tab is displayed in boldface. Possible values are:

TRUE

Specifies that the text label is displayed in boldface

FALSE

Specifies that the text label is not displayed in boldface

Default: FALSE

SelectedIsItalic

Specifies whether the text label of the selected tab is displayed in italics. Possible values are:

TRUE

Specifies italics for the text label

FALSE

Does not specify italics for the text label

Default: FALSE

SelectedIsPlain

Specifies whether the text label of the selected tab is plain, that is, neither bolded nor italicized. Possible values are:

TRUE

Specifies that the text label is plain

FALSE

Does not specify that the text label is plain

Default: TRUE

SelectedTabColor

Specifies the color of a selected tab


SelectedTextColor

Specifies the text color for a selected tab

Default: CC_BLACK

Composite Fields


SelectedTypeFace

Specifies the type face of the text on a selected tab. Valid options are:

TF_SYSTEM (system font) TF_COURIER TF_HELVETICA TF_LUCIDA TF_NEWCENTURY TF_TIMESROMAN

Default: TF_SYSTEM

SelectedTypeSize

Sets the point size of the text for a selected tab. Valid options are: 8, 10, 12, 14, 18, or 24.

Default: 8

Separation

Specifies the number of pixels separating a text label from a bitmap label

Default: 3

ShadowColor

Specifies the color for a tab's shadow

Default: CC_SYS_BTNSHADOW

TabBgColor

Lets you select a color from a color palette for the tab bar's background


TabGap

Specifies the number of pixels separating tabs, that is, the size of the tab gap

Default: 0

TabJustification

Specifies on which side of the tab bar the tabs are justified. Valid options are:

JU_LEFTORTOP

Specifies that tabs are left justified

JU_RIGHTORBOTTOM

Specifies that tabs are right justified

Default: JU_LEFTORTOP

Common Field Properties


TabShape

Specifies the shape of the tab. Valid options are:

COR_ROUNDED

Specifies tabs with rounded corners

COR_SQUARE

Specifies tabs with squared corners

COR_ANGLED

Specifies tabs with slightly angled corners

COR_SLOPED

Specifies tabs with steeply angled corners

Default: COR_ROUNDED

XMargin

Specifies the horizontal margin between the outside of the tab and the label in pixels

Default: 2

YMargin

Specifies the vertical margin between the outside of the tab and the label in pixels

Default: 2

Common Field Properties Many field properties, such as AnchorPoint, ControlField, Name, and TabSeqNum, are common to all fields, and others, like BgColor, FgColor, and MouseDownText, are common to a majority of the fields. Therefore, descriptions of these common properties follow immediately in alphabetical order.

These descriptions are then followed by in-depth discussions of some of the characteristics, such as focus behavior, gravity, and tab sequencing, that many of the fields share.



Property Descriptions AbsXLeft

Specifies the field's starting x-coordinate relative to the main form on the frame

Note: The absolute position properties (such as AbsXLeft and AbsYTop) specify position relative to the main form on the frame, while the relative position properties (such as XLeft and YTop) specify position relative to the field's immediate parent field.

AbsXRight

Specifies the field's ending x-coordinate relative to the main form

AbsYBottom

Specifies the field's starting y-coordinate relative to the main form

AbsYTop

Specifies the field's ending y-coordinate relative to the main form

AllBias

Sets the initial bias of the field for all frame modes

For more information on field biases and frame modes, see Field Biases (see page 257).

AnchorPoint

Specifies a predetermined anchor point for the field. Valid options are:

AP_NONE AP_TOPLEFT AP_TOPCENTER AP_TOPRIGHT AP_CENTERLEFT AP_CENTER AP_CENTERRIGHT AP_BOTTOMLEFT AP_BOTTOMCENTER AP_BOTTOMRIGHT

Note: Positioning by anchor point setting occurs at runtime. Attempts to change the size of an object leaves the anchor point at its original location.

BgBitmap

If set to Bitmap, specifies the graphic image used for the field's background when the BgPattern property is set to FP_BITMAP

Default: No Bitmap



BgColor

Lets you select a color from a color palette for the form's background

Default: CC_BACKGROUND

BgPattern

Lets you select a background pattern for the field. Valid options are:

FP_BITMAP FP_CLEAR FP_CROSSHATCH FP_DARKSHADE FP_HORIZONTAL FP_LIGHTSHADE FP_SHADE FP_SOLID FP_VERTICAL FP_DEFAULT (system default value)

Default: FP_DEFAULT

ClientText

Specifies user-definable text that can be stored and accessed at runtime as an attribute of the field

ControlField

If enabled, specifies that the end user is allowed to change the displayed value in the field without affecting the underlying data (the HasDataChanged property is not changed)

Cursor

Specifies a particular mouse cursor image associated with the field. The image can either be the default cursor, a predefined system cursor, or a custom cursor.

To set a custom cursor, see Use a Custom Cursor (see page 268).



DataType

Specifies the data type of the field's variable (if one exists). Valid options are:

Varchar—variable-length text, to 4096 characters

Smallint—a two-byte integer

Integer—a four-byte integer

Float—a decimal number

Money

Date

StringObject—an unlimited-length text string

Class

Depending on the type of field, the data type can be a simple data type, such as Date or Varchar, or it can be a class name (either a user-defined class or one of the system classes).

scalar fields

You must use a simple data type

multiline entry fields

You can select Varchar or StringObject. Selecting StringObject enables the field to hold text of an unlimited length. If you select Varchar, you must specify the maximum length of the field. Selecting any of the other data types (Smallint, Integer, Float, Money, or Date) defaults to a single-line entry field. For more information, see Single-line Entry Fields (see page 189).

composite field

To be assigned a data type, the child fields of the composite must match in name and data type the user class or system class that is being assigned to it.

Note: If you are not mapping a composite field to a defined class, do not set this property.

table field

The data type must be an array of the specified class, and the names and data types of the column fields of the table field must match the names and data types of the attributes of the assigned class.

For more information about specifying data types for field variables, see the Programming Guide.



Declared

Specifies whether OpenROAD declares a variable for the field at compile time

Default: TRUE

For more information, see Field Variables (see page 254) and the Programming Guide.

DefaultString

Specifies the value of the field when the DefaultValue property is set to DV_STRING. If not set, OpenROAD uses the data type's default format.

DefaultValue

Specifies the default value for the data type. This property determines how OpenROAD sets the field's initial value when the frame is run. Valid options are:

DV_SYSTEM

Specifies the default value for the data type. OpenROAD system defaults are:

null if the field is nullable

zero for the numeric non-nullable types

blank for character non-nullable types

For a choice field, the default is the first value in its value list. If the data type is a system class, this setting automatically allocates an object of the type associated with the class.

DV_NULL

Behaves like DV_SYSTEM except that OpenROAD does not automatically allocate an object for class data types. Instead, it sets the associated reference variable to null.

DV_STRING

Directs OpenROAD to convert the value specified for the DefaultString property to the correct data type and assign that value to the field.

Note: You cannot use DV_STRING if the data type is a class name or blank.

Default: DV_SYSTEM



FgColor

Specifies the foreground color of the field


Note: Setting the FgColor property sets an internal value. If the field is currently in reverse, that is, the IsReverse property is set to TRUE, the current background color changes. When the field is not in reverse video, the foreground color changes.

FocusBehavior

Determines whether clicking this field causes the previous field to be exited and whether the Tab key moves the cursor to this field.

For descriptions of the available focus behaviors, see How You Can Set Focus Behavior (see page 396).

Gravity

If a field is a child of a stack field or matrix field, specifies its alignment with respect to the stack field cell or matrix field cell that contains it. If a field is a child of a subform, this property specifies its alignment relative to the subform. Valid alignment options are:


Note: If a field is in a stack field or matrix field and its Gravity is FA_DEFAULT, OpenROAD uses the ChildGravity property setting for the stack field or matrix field to determine the field's position in its cell. For more information about the Gravity and ChildGravity properties, see Gravity (see page 255).

Height

Specifies the height of the field, measured in 1000ths of an inch

Note: When you create a field dynamically, its size and position default to 0, so you must set some combination of properties (such as XLeft, YTop, Height, and Width) to give the field a real size and position.



IsBold

Specifies whether text is displayed in boldface. Possible values are:

TRUE

Specifies boldface

FALSE

Does not specify boldface

IsItalic

Specifies whether text is displayed in italics. Possible values are:

TRUE

Specifies italics

FALSE

Does not specify italics

IsMoveBounded

Specifies whether the end user may move child fields outside the boundary of the composite field, that is, its parent field. Possible values are:

TRUE

Specifies that the end user may move child fields outside the boundary of the composite field

FALSE

Specifies that the end user may not move child fields outside the boundary of the composite field

Default: TRUE for all composite field types except flexible forms and table fields. (This property is not available for table fields.)

Note: This property is available only when the child field has a field bias of FB_MOVEABLE and only when the end user attempts to move the field, not when the application does.

IsNullable

Specifies whether the variable can be set to null. Possible settings are:

TRUE

Specifies that the variable can be null

FALSE

Specifies that the variable cannot be null

If the data type of the field is a class, this property is always TRUE.



IsPlain

Specifies whether any text on the field is to be displayed in plain style. Possible settings are:

TRUE

Sets IsBold and IsItalic to FALSE

FALSE

Does not modify IsBold and IsItalic

IsResizeBounded

Specifies whether the end user can resize child fields within the composite field. Possible settings are:

TRUE

Specifies that the end user cannot resize child fields

FALSE

Specifies that the end user can resize child fields beyond the borders of the composite field, although they still are kept within the composite itself

Default: FALSE for all composite field types except flexible forms, subforms, and table fields. (This property is not available for table fields.)

IsReverse

Specifies whether the field is currently displayed in reverse video, which means that the BgColor value is used for all foreground elements of the field—such as text—and the FgColor value is used for the field's background. Possible values are:

TRUE

Indicates that the field is currently in reverse video

FALSE

Indicates that the field is not in reverse video

Default: FALSE

Note: TRUE does not change the values of the BgColor and FgColor properties, only the way they are used.



LayerSequence

Specifies a field's sequence number within the layering, that is, the back-to-front order of fields within the two form layers (the field layer and the shape layer). The field that is farthest in the back is numbered 1. The default is determined by the order of creation.

You can move a field or shape to the bottom of its layer by setting this property to 1, and you can move a shape or field to the top of its layer by setting LayerSequence to any value greater than or equal to the number of objects in the layer.

LineColor

Specifies the color of a line segment or the perimeter line of an ellipse or rectangle shape


LineStyle

Specifies the style of either a line segment or the perimeter line of an ellipse or rectangle shape. Valid options are:


The following LineStyle options are available only if the LineWidth property is set to LW_DEFAULT or LW_MINIMUM:

LS_DASH LS_DOT LS_DASHDOT LS_DASHDOTDOT

LineWidth

Specifies the width of a line segment or the perimeter line of an ellipse or rectangle shape. Valid options are:




MouseDownText

Specifies the text that appears in the frame's status bar when the cursor is positioned over the field and the primary mouse button is clicked

MouseMoveText

Specifies the text that appears in the frame's status bar when the cursor moves over the field

Name

Specifies the name of the variable associated with the field. This name must be a valid OpenROAD name. You cannot have two fields with the same name (unless they belong to different composite fields with different names).







Note: You cannot change this property at runtime because 4GL cannot dynamically use different variable names for the same object.

Orientation

Specifies whether to display the field vertically or horizontally. Valid options are:

FO_DEFAULT (system default value) FO_VERTICAL FO_HORIZONTAL

Default: FO_VERTICAL

OuterHeight

Specifies the absolute height of a field (in 1000ths of an inch), which is a value equal to the value specified for the field's Height property plus the size of its border lines and shadows



OuterWidth

Specifies the absolute width of a field (in 1000ths of an inch), which is a value equal to the value specified for the field's Width property plus the size of its border lines and shadows

OutlineColor

Specifies the color of the border around a field or the shadow of its bounding box

Default: CC_SYS_HIGHLIGHT for tab bars; otherwise, CC_FOREGROUND

Note: If OutlineStyle is set to OS_SOLID or the OS_DEFAULT setting is treated as OS_SOLID, the OutlineColor property setting is enforced.

OutlineStyle

Specifies the style of the outline for the field. Valid options are:

OS_DEFAULT OS_SOLID OS_SHADOW OS_3D

OutlineWidth

Specifies the width of a field's border or the shadow of its bounding box. Valid options are:


QueryBias

Specifies the bias of the field when the frame's CurMode property is set to FM_QUERY


ReadBias

Specifies the bias of the field when the frame's CurMode property is set to FM_READ.




RequireRealField

Specifies whether a field is associated with a widget rather than taking advantage of performance and size enhancements provided for some fields by OpenROAD. A widget is a toolkit control often associated with a field. Possible settings are:

TRUE

Allows the field to be manipulated by the Bring to Front and Send to Back commands on the Layout menu. The field appears above other active fields and behaves in a manner consistent with other fields. The field has a widget associated with it.

FALSE

Specifies that, for a single-line entry field, free trim (except one whose bias is Changeable or Landable), or a non-default button field, OpenROAD creates the field, simulating the appearance and behavior of an equivalent form object created by your toolkit

Note: The primary disadvantage of using a field without the toolkit control is that such fields appear below fields created by the toolkit (real fields). Therefore, attempts to overlap real fields with those simulated by OpenROAD fail. If layering is important, as well as speed improvements achieved by using nonreal fields, consider grouping sets of fields inside of subforms or flexible forms. For more detailed information about toolkit controls and layering fields, see the Programming Guide.

Default: FALSE (except for box trim fields)

SeparatorColor

Specifies the color of the lines that separate matrix field or stack field components


SeparatorStyle

Specifies the style of the lines that separate matrix field or stack field components. Valid options are:




SeparatorWidth

Specifies the width of the lines that separate matrix field or stack field components. Valid options are:


Default: LW_DEFAULT

TabSeqNum

Directs the order in which fields within a composite field receive input focus from the keyboard as the Tab key is pressed. Depending on this setting, the field will be inserted in the existing tab sequence at the specified location. For more information, see Tab Sequencing (see page 266).

ToolTipText

Specifies descriptive text that is displayed when the end user points to a field with the cursor

TypeFace

Specifies the typeface for any text that is displayed on a field. Valid options are:

TF_SYSTEM (system font) TF_COURIER TF_HELVETICA TF_LUCIDA TF_NEWCENTURY TF_TIMESROMAN TF_NATIVE_FONT

TypeFaceName

Specifies any valid font name that can be set here when TypeFace is TF_NATIVE_FONT

TypeSize

Sets the point size for a specified typeface



UpdateBias

Specifies the bias of the field when the frame's CurMode property is set to FM_UPDATE.


User1Bias

Specifies the bias of the field when the frame's CurMode property is set to FM_USER1.


User2Bias



User3Bias



ValueList

Specifies the items displayed by a choice field (that is, list field, list view, option field, radio field, or palette field) and their corresponding integer values using the Value List dialog

Note: For more information, see Add and Delete List Field Items (see page 188). Also see the ChoiceField class topic in the Language Reference Guide.

Width

Specifies the width of the field in 1000ths of an inch

Note: When you create a field dynamically, its size and position default to 0, so you must set some combination of properties (such as XLeft, YTop, Height, and Width) to give the field a real size and position.

XAnchorPoint

Used with the YAnchorPoint property to position a field by setting relevant anchor point values. Its value represents a position that is relative to the field's parent. Changes to XLeft, YTop, AbsXLeft, or AbsYTop modify the associated values of XAnchorPoint (and YAnchorPoint) and vice versa.



XLeft

Specifies the x-coordinate (in 1000ths of an inch) of the left side of the field's bounding rectangle, relative to the field's parent.

Default: 0

Most fields are rectangular in shape. A bounding rectangle is the rectangular outer boundary of a field. For non-rectangular fields such as ellipses and line segments, the bounding rectangle is the smallest rectangle that can contain the field. Every field has a parent field (a composite field); this is true because the form itself is a composite field.

Notes:

When you create a field dynamically, its size and position default to 0, so you must set some combination of properties (such as XLeft, YTop, Height, and Width) to give the field a real size and position.

The relative position properties (such as XLeft and YTop) specify position relative to the field's immediate parent field, while the absolute position properties (such as AbsXLeft and AbsYTop) specify position relative to the main form on the frame.

XRight

Specifies the x-coordinate (in 1000ths of an inch) of the right side of the field's bounding rectangle, relative to the field's parent

Default: 0

Note: For more information about bounding rectangles, see the XLeft property.

YAnchorPoint

Used in conjunction with the XAnchorPoint property to position a field by setting relevant anchor point values. Its value represents a position that is relative to the field's parent. Changes to XLeft, YTop, AbsXLeft, or AbsYTop modify the associated values of YAnchorPoint (and XAnchorPoint) and vice versa.



YBottom

Specifies the y-coordinate (in 1000ths of an inch) of the bottom of the field's bounding rectangle, relative to the field's parent.

Default: 0


YTop

Specifies the y-coordinate (in 1000ths of an inch) of the top of the field's bounding rectangle, relative to the field's parent.

Default: 0


Field Variables

When you create a named field, OpenROAD Workbench also creates a variable that you can use in a script to refer to the field. The name of the variable is the same as the name of the field.

When you create a field using the Frame Editor, Workbench creates a default name, fieldn, for all except the following:

Composite fields (except table fields)

Shape fields

Trim fields

In most cases, it is a good idea to change the default name to a name that is meaningful. You can use the Currently Selected field in the Property Inspector to provide a name for an unnamed field. For more information, see Property Inspector (see page 135).

The variable associated with a field contains the field's value. To refer to a field's attributes in a script, you must use the field function.

For more information about field variables and the field function, see the Programming Guide.



Fields and System Classes

Every field created in OpenROAD Workbench is an object of its corresponding OpenROAD system class. For example, an entry field is an object of the EntryField class. The properties that you set for the field represent, in general, the system class attributes that you manipulate in your 4GL code.

For descriptions of the OpenROAD system classes and their attributes, see the Language Reference Guide.

Events and Scripts

Events are associated with most active fields, and end user actions cause most of these events. For example, events are generated when an end user clicks a button field, enters data in an entry field, or selects a row in a table field. For every event, you can provide an event block that contains 4GL code to handle that event. The code in the event block is executed each time the event occurs.

You can put the event blocks for an individual field in its own field script, or you can put the event blocks for all the fields on the form in the frame script.

For general information about using field scripts, see the chapter Writing Scripts and Procedures (see page 435). For a complete list of the events associated with a specific field type, see the Language Reference Guide.

Gravity

Because gravity is an attribute of the FormField class, every field has an alignment, or gravity, attribute. However, the gravity attribute is applicable only if a field's immediate parent is a matrix field, a stack field, or a subform.

Because a column field is a stack field, gravity also applies if a field's parent is a column field. Moreover, the form itself is a frame form; and because a frame form is a subform, gravity applies to a field whose parent is the form.

The gravity attribute is not particularly useful when a field's parent is the form itself. (The exception is FA_TOPLEFT.) For example, if you place a button field on a frame and set gravity to FA_CENTER, you “lose” the field because it will be centered in the 24-inch by 24-inch form. Consequently, you are forced to scroll the frame to locate the field. Gravity is quite useful, however, when a field's parent is a matrix field, a stack field, or a subform (other than the form itself).



The ChildGravity attribute is even much more useful than the Gravity attribute. Because gravity applies only when the immediate parent is a matrix field, a subform, or a stack field, only matrix fields, subforms, and stack fields (and their subclasses) have the ChildGravity attribute. For more information, see Matrix Field Properties (see page 218).

Note: For more information about the FormField class and using the gravity attribute, see the Language Reference Guide and the Programming Guide.

Set Gravity

You can set a field's gravity in the Frame Editor.

To set a field's gravity


2. Select a field in a matrix field, stack field, or subform.

3. Click the Gravity (or ChildGravity) property in the Property Inspector.

Note: You cannot move a child field away from its default position unless the parent field's Gravity property is set to FA_NONE.

4. Select one of the valid alignment options:

FA_DEFAULT FA_NONE FA_TOPCENTER FA_TOPLEFT FA_TOPRIGHT FA_CENTERLEFT FA_CENTER FA_CENTERRIGHT FA_BOTTOMCENTER FA_BOTTOMLEFT FA_BOTTOMRIGHT

Alternatively, select one of the alignment commands from the Layout Gravity submenu.



Field Biases

Each frame can operate in one of several modes. OpenROAD Workbench provides six frame modes: Update, Read, Query, and three user modes (User1, User2, User3) that you can use as you see fit. As a frame runs, you change its current mode by changing the CurMode attribute.

Every field has a bias for each of the six modes. The bias attributes of a field are as follows:

UpdateBias

ReadBias

QueryBias

User1Bias

User2Bias

User3Bias

Another bias attribute, AllBias, lets you set a single bias value for all six modes.

A field's current bias is the bias setting for a frame's current mode. The bias setting for a mode determines how the user interacts with the field when the frame is in that mode. A field's bias can be used, for example, to control whether a user can enter data in a field, whether the field is dimmed, and even whether the field is visible.

The current bias of a field may also determine what events are generated in connection with the field. For example, a DragSegment event is generated for a field only when the field has the DragSegment bias; no event is generated for a field when its bias is Dimmed.

When you create a field using the Frame Editor, a default initial bias is set for each frame mode. You can change a field's initial bias by using the Property Inspector or by using the Bias menu commands.

The following section describes the OpenROAD field biases. The biases are organized by the following categories:

Interactive (see page 258)

Passive (see page 258)

Select (see page 259)

Draw (see page 259)



Interactive Biases

FB_CHANGEABLE

Specifies that end users can select or tab to the field and, if appropriate, edit its contents

FB_LANDABLE

Specifies that end users can select or tab to the field, but cannot change its data

Passive Biases

FB_VISIBLE

Specifies that the field is displayed, but the end user cannot interact with it

Note: This bias does not even allow, for example, the end user to scroll multiline entry fields to view their entire contents. For such limited interaction, see the FB_VIEWABLE property.

FB_DIMMED

Specifies that the field is grayed out and end users cannot interact with it. (For systems that do not support the dimmed setting, selecting this bias makes the field visible.)

FB_INVISIBLE

Specifies that the field is not displayed on the form. Although end users cannot interact with the field, you can access it in your 4GL code.

FB_VIEWABLE

Specifies that the field is displayed on the form and end users may use the mouse only to scroll through its contents. (Because the field cannot accept input focus, keyboard interaction is not possible.)

The following table describes the behaviors of certain fields set to FB_VIEWABLE:

Field Type Behavior

Control button A single primary mouse-click displays the option menu, if one exists. End users may view the contents of the option menu, including its shortcut menus. However, the events associated with each menu item will not be generated.

Multiline entry field If it has scroll bars, end users can scroll the contents of the multiline entry field into view.

List field End users can scroll the contents of the list field into view.



Field Type Behavior

Option field End users can display the entire value list of the option field.

Table field End users can scroll through the contents of the table field.

Tree view End users can scroll through the contents of the tree view field, as well as expand and collapse its nodes.

Viewport End users can scroll through the contents of the viewport field.

Note: Those fields not listed are assumed to have the same behaviors as when they have the FB_VISIBLE bias.

Select Biases

FB_FLEXIBLE

Specifies that end users can select the field with the mouse and can move or resize the field

FB_RESIZABLE

Specifies that end users can select the field with the mouse and can resize the field but not move it

FB_MOVEABLE

Specifies that end users can select the field with the mouse and can move the field but not resize it

FB_MARKABLE

Specifies that end users can select the field with the mouse but cannot move or resize the field. The field changes to reverse video when selected.

Draw Biases

FB_CLICKPOINT

Specifies that the field can take a ClickPoint event (allowing you to discover exact cursor coordinates)

FB_DRAGBOX

Specifies that end users can draw a drag box through the field

FB_DRAGSEGMENT

Specifies that end users can drag a line segment through the field

For more information about using field biases and frame modes in your 4GL code, see the Programming Guide.



How You Can Set the Focus Behavior

Every active field has a focus behavior attribute (FocusBehavior) that controls the behavior of the field with respect to the input focus. Specifically, the focus behavior setting determines:

Whether the field can have the input focus

Whether the field is in the tabbing sequence (that is, whether the end user can tab to the field)

What happens to the field that currently has the input focus when the end user clicks the field or tabs to the field

You can use the Frame Editor's Property Inspector to set the initial value for a field's focus behavior. You can also use a frame's 4GL script to change the focus behavior as the frame is running.

The following describes each focus behavior setting and its effect:

FT_TABTO

Specifies that the field accepts the input focus and is part of the tabbing sequence. The field takes the input focus when the user clicks the field or tabs to the field. For more information, see Tab Sequencing (see page 266).

Clicking the field or tabbing to a field with this focus behavior may affect the field that currently has the input focus. For example, suppose that a frame has entry fields A and B. Suppose also that the focus behavior of field B is FT_TABTO. If the user clicks field B (or tabs to field B) when field A has the input focus, the following events occur in order:

1. A SetValue event for field A (if the user has changed the data in field A)

2. An Exit event for field A

3. An Entry event for field B

The SetValue event generated for field A enables the script to validate data in field A before the input focus switches to field B. If the data in field A is not correct, the program can execute a resume statement to prevent the remaining events from occurring. In this case, field A retains the input focus. (For descriptions of these events, see Events in the Language Reference Guide.)

Note: FT_TABTO is the default focus behavior for a single-line entry field.



FT_TAKEFOCUS

Specifies that the behavior is the same as for FT_TABTO, except that the field is not part of the tabbing sequence. The field can, however, take the input focus. Clicking the field causes the same sequence of events as for FT_TABTO.

Note: FT_TAKEFOCUS is the default behavior for multiline entry fields.

FT_SETVALUE

Specifies that the field is not part of the tabbing sequence and does not accept the input focus. Clicking the field causes a SetValue event for the field that has the input focus. This setting is useful for fields such as an OK button that performs data validation.

For example, suppose that a frame has an entry field, E, and a button field, OK. If the user clicks the OK button while field E has the input focus, the following events occur:

A SetValue event for field E (if the data in field E has changed since it took the input focus)

A Click event for field OK

This sequence of events enables the program to check the data in field E before processing the OK button. In this case, there is no Exit event for field E because field E does not lose the input focus.

FT_NOSETVALUE

Specifies that the field cannot take the input focus and is not part of the tabbing sequence. Clicking the field does not change the input focus and does not force a SetValue event for the field that has the input focus. This setting is useful for fields such as a Cancel button or a Help button where it is not necessary to check the data in the field that has the input focus.

Note: If a field's current bias conflicts with its focus behavior, the bias attribute retains control. For example, if a field's current bias is FB_VISIBLE and its focus behavior is FT_TABTO, the user cannot tab to the field.

How You Can Define an Alt Speed Key

OpenROAD can set Alt speed keys for Button, Toggle, and Radio fields.

To position an underscore character, indicating which Alt speed key is desired, place an ampersand (&) prior to the character to be underscored when you create the label for the field, for example, "&Save" to underscore the S. You can create the label in the Frame Editor's Property Inspector for the field, or it may be created or changed dynamically by your 4GL code.



OpenROAD maintains the dynamic speed key table and associates the speed key with the field. This is done automatically for three types of fields: buttons, toggles, and radio fields.

Considerations for Alt Speed Keys

When defining Alt speed keys, consider the following issues:

Control Bias

Alt speed keys are activated only if the bias of the field with which they are associated is FB_CHANGEABLE or FB_LANDABLE. When the Alt key and the underscored character are pressed, it is as if the mouse button is clicked while the cursor is positioned over the field.

Printable Characters

The characters that can be used for Alt speed keys are all the printable characters in the current character set, except space (“ ”) and ampersand (“&”). Characters whose internal value is greater than 127 (0x7F) are supported so long as they can be typed without using the Alt key and the numeric keypad. Alt+function keys are not supported (except in the user-defined speed key tables (see page 631)).

Case Significance

Case is not significant. The case of letters used as Alt speed keys is not significant—for example, both of the following button labels have Alt+K as the speed key: “O&K” and “O&k.” (Therefore, Alt+K and Alt+Shift+K would perform the same function.)

Including the “&” Character in a Label

Use double ampersands (“&&”) in the label of a field if you want to display a single ampersand as part of the label. For example, “This && That” displays as “This & That” with no underscore (and no Alt speed key).

Button Speed Keys

If the label for a button contains an ampersand, when the Alt key and the underscored character are pressed, the button is pressed as if the primary mouse button were clicked while the cursor is over the button. Focus behaviors, events, and so on, are the same as if the mouse were used.

Toggle Speed Keys

Both the ON-Label and the OFF-Label can have Alt speed keys. They can be the same (for example, “&On” and “&Off”) or different (such as “O&n” and “O&ff”).

If they are different, only the one currently displayed is active. In the same manner as for buttons, using the Alt speed key is identical to clicking with the primary mouse button.



Radio Button Speed Keys

Any, all, or none of the buttons in a radio field can have Alt speed keys associated with them. Pressing the Alt speed key associated with a radio button selects that button. In the same manner as for button fields, using the Alt speed key is identical to clicking with the primary mouse button.

Order of Precedence for Speed Keys

Speed keys using the Alt key can be defined in the following ways:

Alt speed keys

Defined by placing an ampersand in the label of a Button, Toggle, or Radio button

User speed keys

Defined by creating a user-defined speed key file

Menu speed keys

Defined by creating a menu item with an ampersand in its label

Only one action is performed when a speed key using the Alt key is pressed, even if that speed key is defined in more than one of the previous ways at the same time. The order of precedence for speed keys is Alt, User, then Menu.

Limitations

The following limitations apply to speed keys:

Only one Alt speed key is supported per label

If more than one ampersand is included in the text for a label, only the character following the last ampersand will be the Alt speed key. Prior ones are ignored. This does not apply to double ampersands used as an escape to display a single ampersand.

Duplicate Alt speed keys are not supported

Using the ampersand to define more than one field to have the same Alt speed key is not supported. If you use the ampersand in this way, only one of the fields will actually be associated with that Alt speed key. The field chosen cannot be predicted and is subject to random fluctuations while the frame is running. (Toggle fields may use the same Alt speed key for their ON-Label and OFF-Label, since only one of these will be active at a given time.) Take care when assigning Alt speed keys dynamically.



Set Multiple Selections for List Fields and Table Fields

You can set the selection mode for a list field or table field using the Property Inspector or 4GL code.

To set the selection mode using the Property Inspector


2. Select the list field or table field on the frame.

3. Click the SelectionType property in the Property Inspector.

4. Select one of the two possible values:

SEL_SINGLE

Specifies that the end user may select only one item at a time

SEL_MULTIPLE

Specifies that the end user may make multiple selections following the rules described in User Interactions (see page 264)

User Interactions

Selections made with the mouse or keyboard can be contiguous or disjoint. The end user can make single selections by clicking a row without keyboard modifiers or by using keyboard navigation keys (up arrow/down arrow, PgUp/PgDown, or Home/End) without modifiers to navigate to the desired row.

Contiguous Multiple Selections

Contiguous multiple selections can be made by clicking and dragging without modifiers. The Shift key modifier expands the ability to make multiple selections by making use of the concept of an anchor row. Clicking a row without the Shift key modifier moves the anchor to the selected row (even if you subsequently drag to a different row).

Keyboard navigation without the Shift key modifier moves the anchor to the selected row. However, whenever the Shift key is used as a modifier the anchor row remains unchanged. Using the Shift key causes all rows between the anchor row and the row navigated to, to become selected, causing all other rows to become deselected. Therefore, the end user can make contiguous selections by first setting the anchor without the Shift key and then navigating using the Shift key.



Disjointed Multiple Selections

The Ctrl key modifier to the mouse enables disjointed multiple selections. This is because using the Ctrl key modifier does not modify any selections outside of the range of its command. Doing a Ctrl+Click toggles the selection state only of the single row clicked on. Doing a Ctrl+Click+Drag does a contiguous selection (or deselection) of the rows dragged across, but does not affect any other rows.

Disjointed selections using the keyboard require use of Shift+F8 to first change the mode of selection. This causes both the anchor and all current selections to remain fixed while using navigation keys (except the Shift key modifier, which selects or deselects all rows between the anchor and the new row, but leaves all other current selections fixed). In the Shift+F8 selection mode, the Space key toggles the selection state of whichever row has the focus without modifying selections. It also changes the anchor to that row. This mode is toggled back to the usual keyboard mode if the field loses focus or if there are any mouse clicks.

The following table summarizes the result of all end user mouse actions:

Action Result Focus Anchor

Click The clicked row is selected. All other rows are deselected.

Moves to the clicked row.


Shift+Click Selects all rows between the anchor row and the clicked row (including clicked row). Leaves the anchor row selection state unchanged. Deselects all other rows.


Remains where it was.

Ctrl+Click Toggles the selection state of the clicked row. Leaves all other rows unchanged.



Shift+Ctrl+Click Sets selection state of all rows between the anchor row and the clicked row to the same state as the anchor row. All other rows remain unchanged.





Action Result Focus Anchor

Click+Drag Selects all rows from BtnDown row to BtnUp row. All other rows are deselected.

Moves to BtnUp row.

Moves to BtnDown row.

Shift+Click+Drag Same as Shift+Click BtnUp row.

Moves to BtnUp row.


Ctrl+Click+Drag Toggles selection state of BtnDown row. Sets all rows from BtnDown to BtnUp row to same state as BtnDown row. All other rows remain unchanged.

Moves to BtnUp row.

Moves to BtnDown row.

Shift+Ctrl+Click+ Drag

Same as Shift+Ctrl+Click BtnUp row.

Moves to BtnUp row.


Scrolling actions using the associated scroll bar do not change existing selections when Selection Type is Multiple. It does, however, change the focus row, so that the focus row remains visible. The default action of scrolling with Selection Type of Single is to change the selection. This can, however, be overridden by setting the ScrollingChangesSelection flag to FALSE.

You can force the table field to be scrolled in a 4GL script in exactly the manner as is currently done by setting the ActiveRow attribute. If the ActiveRow attribute is set to a row that is not currently visible, it is scrolled into view at the top of the table field.

Programming Interface

A row of a list field or a table field can be set to a selected or unselected state by a 4GL statement by setting an appropriate attribute. Setting the selection state of a row yields different results, based on the styles of selection currently in effect. In single selection, setting a row to the select state deselects the previously selected row. Additionally, for a list field, the value of the list field's variable is updated to represent the current selection. For a table field, the attributes CurRow and ActiveRow are updated.

For more information, see the Programming Guide.

Tab Sequencing

There are two kinds of tab sequencing: default tab sequencing and custom tab sequencing.



Default Tab Sequencing

The TabNumSeq property applies to active fields within a composite field. This property directs the order in which fields within a composite field receive input focus from the keyboard as the Tab key is pressed. By default, tab sequencing for a composite field is from left to right and top to bottom.

Custom Tab Sequencing

A custom tab sequence number can be assigned to an individual field on a frame's form either through the Frame Editor's Property Inspector or at runtime through a 4GL programming interface. For more information about using 4GL code, see the Programming Guide.

Although TabSeqNum is an attribute of the ActiveField system class, a tab sequence can logically be thought of as a property of CompositeField class, as an array of references to active fields. The order of the fields in the array determines their sequence as tab stops. The elements in this logical tab sequence array can be references to scalar fields or to other composite fields. Each of these composite fields may have its own tab sequence array as well.

The topmost-level object representing a frame's form is a FrameForm, which is a subclass of CompositeField. When a frame is activated, the field that initially takes the input focus is the first item in the tab sequence array of the FrameForm of the current frame.

At any given time, there is a current tab sequence array. If the end user tabs, the next field in the tab sequence gets the input focus. If that item is a composite field, then the first item in its tab sequence array gets the input focus. At the end of a tab sequence of a composite field, focus moves to the next item in the tab sequence of the parent field. In the case of the frame's form itself, which has no parent field, tabbing moves the focus from the last field in the form's tab sequence to the first field in the tab sequence.

Note: For more information about the ActiveField and CompositeField classes, see the Language Reference Guide.

The following table summarizes the target of the tab action based on the type of the current field and keys pressed:

Keys Pressed Current Field Is a Simple Field

Current Field Is a Composite Field

Tab Next field Next field within the composite field

Shift+Tab Previous field Previous field within the composite field



Keys Pressed Current Field Is a Simple Field

Current Field Is a Composite Field

Ctrl+Tab Next field The field after the composite field

Shift+Ctrl+Tab Previous field The field before the composite field

Modify the Tab Sequence

You can reset the tab sequence for a field using the Property Inspector.

To reset the tab sequence for a field



3. Click the TabSeqNum property in the Property Inspector.

Its value cell opens.

4. Replace the existing value (for example, replace 0 with 1).

Note: If the new value is already being used, the new tab sequence number is incremented.

5. (Optional) Repeat Steps 3 and 4 (entering different new values) for the other fields on the form.

Use a Custom Cursor

You can associate a specific mouse cursor image with each field you create. The image can be either a custom cursor, which is initially loaded from a file, or one of 13 predefined system cursors that OpenROAD provides.

The cursor can be associated with a field either at design time or runtime. When the mouse is moved over a field, the mouse cursor takes on the image associated with the field.

To specify a custom cursor


2. Select the field to which you want to assign a custom cursor.



3. Click the field's Cursor property in the Property Inspector.

The Cursors dialog appears:

This dialog lets you associate with a field a predefined system cursor, a custom cursor, or no cursor image at all.

4. Do one of the following:

Select System—The Cursors dialog displays a palette of predefined system cursors:

Select User—The Cursors dialog changes again, displaying the Change Image button and a sample box:

a. Click Change Image.

A standard File Selection dialog opens.

b. Locate a cursor bitmap file, and click OK.

The Cursors dialog displays your choice in the sample box.

5. Click OK.



How You Can Create or Edit a Field Script

To create or edit a script for any field, select the field and click Edit, Field Script on the floating menu bar. OpenROAD Workbench displays the field script (or a blank screen, if there is no script) in the Script Editor.

For more information about creating or editing scripts, see Writing Scripts and Procedures (see page 435).

Alternative Methods for Creating Fields 271

Chapter 7: Alternative Methods for Creating Fields


Create a Field from a Field Template (see page 271) Field Templates (see page 273) Create Fields from a Database Table (see page 275) Create Fields from a User Class (see page 277) Create Fields from an External Class (see page 279)

OpenROAD provides several alternative methods for creating fields. In this chapter, you will learn how to use each of these alternative methods, as well as how to create field templates.

Create a Field from a Field Template

You can create a field based on a field template that you have created previously and stored in the current application or one that is stored in an included application. Field templates are prototypes from which you can generate individual fields on a form. For more information about creating your own field templates, see Create a Field Template (see page 273).

You can also create fields by using templates that are paired with assistants to create automatically generated fields, such as bar graphs and meters, as discussed in Generating Fields from Predefined Templates (see page 341). The new field has the visual characteristics, properties, and associated 4GL code as defined in the template.

Create a Field from a Field Template


To create a field based on a field template you have created (or based on a field template in an included application)


2. Click Insert, Field from Field Template.

The Select a Field Template dialog appears:

This dialog lists field templates in the current application and any included applications.

3. Select the name of an application, and then select a field template from that application.

4. Click OK.

The Select Field Template dialog closes.

5. Position the field on the form as described in Position Fields (see page 155).

Workbench creates a field (or fields) based on the template.

6. (Optional) Use the Property Inspector to reset or modify any of the field's properties.

For more information, see Property Inspector (see page 135).

7. Write a script for the field, if necessary. To associate the script with the field, click Edit, Field Script on the Frame Editor's floating menu bar.

Workbench opens the Script Editor (or your system editor), where you can write the script for the field.

For more information about writing scripts, see Writing Scripts and Procedures (see page 435).

8. Click File, Save.

Field Templates


Field Templates

If you intend to create multiple fields that have the same purpose, you can create a field template that specifies the appearance and behavior of the field. Field templates are prototypes from which you can generate individual fields on a form. The field template can contain both the visual properties of the field and a field script.

Using field templates offers the following advantages:

Decreases time and errors involved in creating fields

Lets you standardize similar fields within and across your applications (by using included applications)

For example, you can create a template for a Save button that looks the same and executes the same 4GL code on every frame where you include it. You need only to create the button and write the code once; you then can use the same button whenever you need it without having to recreate the field or write a new script.

Because field templates are application components, you can use them on any frame in an application. You also can create one application containing all your field templates, and then include this application in every application that you create throughout your organization.

Create a Field Template

You create a field template using the Create Field Template dialog.

To create a field template


2. Click File, New, Field Template.

The Create Field Template dialog appears:

3. Enter a name for the field template in the Name field.

Field Templates


4. (Optional) Add a comment or description in the Remark entry field.

5. (Optional) Specify an assistant procedure in the Assistant field.

This option lets you attach an assistant for creating a generated field, in addition to applying your own field template. For more information about OpenROAD assistant technology, see the Programming Guide.

6. Click Create.

The Field Template Editor opens.

7. Click Edit, Field Template Properties.

Workbench opens the Field Template Properties window, which has many of the same functions and features as the Frame Editor, including a field palette, floating menu bar, and the Property Inspector. For more information, see Property Inspector (see page 135).

8. Use the field palette to create a field of any type you want.

You can create a single field or multiple fields that are grouped into a flexible form every time you close the Field Template Properties window.

For more information about setting field properties, see Creating and Using Basic Fields (see page 151).

9. (Optional) If you want to write a field script for the new field, select the field, and then click Edit, Field Script.

Workbench opens the Script Editor (or your system editor), so that you may edit the field script.


10. Click File, Close in the Field Template Properties window when you are done creating the field template.

Workbench returns you to the Field Template Editor.

11. Click File, Save and Close to save your field template and close the Field Template Editor.

Now you can create a field based on the template. The new field can be identical to the template, or you can modify it as desired. For more information about creating fields based on field templates, see Create a Field from a Field Template (see page 271).

For more information about how to apply field template changes to previously generated fields, see How You Can Apply Template Changes to Frames and Fields (see page 561). For more information about applying the OpenROAD predefined field templates and using their associated assistants, see Generating Fields from Predefined Templates (see page 341).

Create Fields from a Database Table



You can create a set of entry fields that correspond to the columns of a database table. You can specify how to create the fields in one of the following ways:

A set of individual simple fields that are left-justified vertically, with free trim titles derived from the column names

A table field with the table column names used as the table field column headers

To create fields from a database table


2. Click Insert, Fields from Database Table on the floating menu bar.

The Select a Database Table dialog appears:



3. Enter the name of the table or view in the entry field.

Alternatively, click List Tables to the right of the entry field (shown in the preceding illustration) to open the Table Selection dialog.

The Your Tables, Other Tables, and System Catalogs options control which tables appear in the dialog.

Note: The Refresh button refreshes the list of tables from the database. Refreshing is necessary only in the case where you create a new table while the Table Selection dialog is open.

4. Select one of the tables from the Table Selection dialog's list, and then click OK.

You are returned to the Select a Database Table dialog, and the name of the table you selected is displayed in the entry field.

5. Specify a display option by clicking the Simple Fields or Table Field option.

6. Click OK.

The Select a Database Table closes.

7. Position the cursor on the form where you wish to place the field and click the primary mouse button.

Workbench creates either simple fields or a table field based on the display option you specified earlier.

Create Fields from a User Class


8. Use the Property Inspector to set the field properties.

If you selected the Table Field option earlier, Workbench creates a default option menu for that table field's control button, and creates default scripts for the menu items of the option menu.

For more information about creating table fields, see Table Fields (see page 223).


You can create a set of fields that correspond to the simple attributes (attributes with simple data types) of a user class. Reference and array attributes are ignored. You can specify how to create the fields in one of the following ways:

A set of individual simple fields that are left justified, with free trim titles derived from the attribute names

A table field with the attribute names used as the table field column headers



To create fields from a user class


2. Click Insert, Fields from User Class on the floating menu bar.

OpenROAD displays the Select a User Class dialog that lists the user classes in the current application and all included applications.

3. Select an application (for example, core) and a user class (for example, bar_data).

4. Specify a display option by selecting the Simple Fields or Table Field option.

5. Click OK.

Workbench returns you to the Frame Editor.

6. Click the starting point for the fields on the form.

Workbench creates simple fields or a table field based on the display option you specified earlier.

Note: Private attributes are not used when creating fields from a user class.

7. Use the Property Inspector to set the field's properties.

Create Fields from an External Class


8. (Optional) If you want to write a field script for the new field, select the field, and then click Edit, Field Script.

Workbench opens the Script Editor (or your system editor), where you can write the script for the field.


For more information about using table fields, see Table Fields (see page 223). For more information about user classes, see Working With Classes (see page 411).


You can add external controls to your form. External controls, such as charts, grid controls, HTML controls, web browsers, and ActiveX controls are available from independent software vendors. OpenROAD supports Microsoft's ActiveX technology.

These external controls have properties, methods, and events just like other class objects. Therefore, they are treated as external classes in OpenROAD. Each external object in OpenROAD must have an external class to represent it. These external classes appear as normal OpenROAD system classes. As such, they can be created and manipulated like any other class using an editor.

Note: For more information about creating and registering external classes using the External Class Library Editor, see Create and Register External Class Libraries (see page 428).

To create fields from a registered external class

1. Follow the procedure in Create and Register External Class Libraries (see page 428) to create the external class libraries.


3. Click Insert, Field from External Object.

Workbench displays the Select External Object dialog, which lists all of the external objects that have been registered as OpenROAD components. Registration means that OpenROAD wrapper code has been generated for an external object's exported attributes, methods, and events.

4. Select an external object from the Select External Object dialog.

5. Click OK.

The Select External Object dialog closes.



6. Position the external object on the form (as described in Position Fields (see page 155)).

7. (Optional) Use the Property Inspector to reset any of the external object's default properties. For more information, see Property Inspector (see page 135).

Note: For more information about external controls and other external objects, see External Classes in the chapter “Working with Classes” of the Programming Guide.

Generating Frames from Predefined Templates 281

Chapter 8: Generating Frames from Predefined Templates


Include Predefined Template Packages in Your Application (see page 283) Frame Templates (see page 284) The about_box Template (see page 285) The Calculator Template (see page 287) The find_dialog Template (see page 290) The font_dialog Template (see page 294) The splash_screen Template (see page 297) The text_editor Template (see page 299) The financial_calculator Template (see page 302) The mastdetl Templates (see page 305) The toolbar_window Template (see page 338) The mclient_frame Template (see page 339)

OpenROAD Workbench provides a set of predefined frame templates that let you quickly integrate some of the components commonly featured in many of today's powerful applications. These templates are contained in a set of OpenROAD libraries that may be easily included in your application.

Each predefined frame template has an associated “assistant” that prompts you for information used in customizing the frame. This enables you to create the frame layout dynamically based on your input.

In this chapter, you will learn:

How to use the predefined frame templates included in Workbench to create frames

How to customize these generated frames using the assistants associated with the predefined templates

How end users can use these generated frames



Only the following templates are described in this chapter:

Library Template

core about_box (see page 285) calculator (see page 287) find_dialog (see page 290) font_dialog (see page 294) mclient (see page 339) splash_screen (see page 297) text_editor (see page 299)

Note: Creating frames with the dialog_box, empty_frame, and menu templates is described in Creating Basic Frames (see page 105). Also see Creating and Modifying Menus (see page 379). For more information on the mclient_frame template, see mClient Deployment (see page 611).

finance financial_calculator (see page 302)

mastdetl (see page 305)

detail (see page 328) explosion (see page 331) master_detail (see page 325) simple_field (see page 317) table_field (see page 321)

misc toolbar_window (see page 338)

Note: For more information, see Creating Toolbars (see page 399).

To use the finance, mastdetl, and misc libaries, you must include them in your application. For more information, see Include Predefined Template Packages in Your Application (see page 283).

Include Predefined Template Packages in Your Application


Include Predefined Template Packages in Your Application

To be able to use the templates in the finance, mastdetl, or misc libaries, you must include their packages in your application. The file names of these packages are:

finance.pkg

mastdetl.pkg

misc.pkg

Although the stat.pkg has no templates defined, you can include it also using the following procedure.

After you specify an included application, you can use any of its components in the current application. When OpenROAD calls a component in a running application and cannot find that component in the application itself, it looks through the included applications in the order in which you have listed them.

Note: If you add a component to an application that is in an included application that is being edited, you cannot reference the component in the first application until you close and reopen the second application.

To include an application in your application



3. Click the Included Applications portlet tab.

Note: Even though the default core application library is not displayed in this window, its components are available to all applications.

4. Beneath the Included Applications portlet header, click the Insert Application icon:

Note: If one or more applications are already included, the Insert Application Above and Insert Application Below icons are displayed. Select an included application and then click the appropriate icon.

The Add Included Application dialog appears. This dialog lets you add an application from the current database or an image (.img or .pkg) file.

5. Select the Include from Image File option.

The Add Included Application dialog changes slightly.

Frame Templates


6. Click Browse.


7. Select each library that you want to include (for example, misc.pkg).

Note: To specify any of the OpenROAD predefined application libraries, the image file name used is the application name with an extension of .pkg.

8. Click Open.

The name of the file you selected is displayed in the Image File field.

9. Click OK.

The Included Applications portlet now displays the selected application library as an included application.

10. Repeat Steps 4–9 to include any other applications.

The Include Applications window now displays all of the specified application libraries as included applications.

Frame Templates

A frame template is a frame that you use as a model for creating similar frames. The frame templates contain all the fields, menus, and 4GL scripts that define the static functionality common to all frames created from the templates. The assistant procedures that are coupled with the templates dynamically generate additional fields and queries that make frames created using a specific template unique from one another.

All the OpenROAD libraries and their corresponding frame templates are listed in the following table:

Library Frame Template

Core (default) about_box calculator dialog_box empty_frame find_dialog font_dialog mclient_frame menu splash_screen standard text_editor

finance financial_calculator

The about_box Template


Library Frame Template

mastdetl detail explosion master_detail simple_field table_field

misc toolbar_window

Notes:

Although the stat library is part of the core, it contains no frame templates.

Before you can begin to automatically generate frames, you must include the appropriate OpenROAD libraries in your application. If you did not do this earlier, do so now (see Include Predefined Template Packages in Your Application (see page 283)). By default, the core application library is included in your application. For instructions on including additional application libraries in your application, see Specify Included Applications (see page 89).


The about_box frame template is an OpenROAD core library template that creates a standard dialog containing basic information about the current application. It includes the application's name and version number, the name of the current database, current version information for OpenROAD, and an image trim field that you can customize with your company's logo.

The About box is typically displayed when a user clicks Help, About.

Create an About Box Frame

Using the Frame Editor, you can create an About box frame from the about_box frame template.

To create a frame using the about_box frame template

1. On the Develop tab, select the application in which you want to create the frame in the Applications portlet, and then select the header bar of the Components portlet to make it active.


3. The Create User Frame dialog appears.



4. Enter the component name in the Name field (for example, My_About_Box).


6. Select core from the Application list.

In the Template list, Workbench displays a list of the frame templates contained in the application library or included application that you specify.

7. Select about_box from the Template list.

8. Click Create.

The About Box Assistant appears.

9. Enter the current version number of your application in the Application version entry field.

The version can include text as well as numbers (for example, 1.0 Beta).

10. Click Generate.

The frame is created and displayed in the Frame Editor.

Note: All the fields containing text are blank, since the text strings only appear at runtime.

11. Change the default logo:

a. Select the image trim field in the upper left corner of the form, and then select the Image property in the Property Inspector.

A standard Browse dialog appears, displaying the default logo.

b. Click Browse.


c. Select a graphic file and click OK.

The selected logo appears in the Browse dialog.

12. Click OK.

The logo appears in the image trim field in the About Box frame.

13. Resize the graphic by using the field's resizing handles or specifying its Height and Width properties.

14. (Optional) Specify other frame properties using the Property Inspector.

Note: The two entry fields, db_name and or_info, cannot have their text values changed by resetting the default values in the Property Inspector; any changes are overridden by the text provided by OpenROAD at runtime.

For more information about using the Property Inspector, see Set Frame Properties (see page 113).

The Calculator Template


How You Can Call an About Box Frame

To call the About box frame, you must add the following items to all frames that will use it.

Note: If you want to implement the About command on a Help menu, you must first create the Help menu, and then add a menu button for the About command. For more information on creating menus, see Creating and Modifying Menus (see page 379).

Add an event block to the script for the About menu_button (in this example, it is called about_btn): on click menu.help.about_btn = {

callframe My_About_Box; }

You can also override the default application name and version number when you call the About box frame by adding appname and version parameters to your callframe statement. For example:

callframe My_About_Box(appname = 'My_Application', version = '1.0 Beta');

Test an About Box

You can test your About box frame by clicking Debug, Go on the Frame Editor's floating menu bar.


The calculator frame template is a core library template that creates a complete, four-function calculator in a pop-up frame. In addition to chained arithmetic calculations, the calculator includes memory storage and recall, square, square root, and inverse features.

Note: For information about the financial calculator, see The financial_calculator Template (see page 302).



Create a Calculator Frame

Using the Create User Frame dialog, you can create a calculator frame from the calculator frame template.

To create a frame using the calculator frame template



3. The Create User Frame dialog appears.

4. Enter the component name in the Name field (for example, My_Calculator).


6. Select core from the Application list and the calculator template from the Template list.

7. Click Create.

The Calculator Assistant appears.

8. Click Generate.


9. (Optional) Specify the frame's properties using the Property Inspector.


10. To test the calculator frame in operation, click Debug, Go on the Frame Editor's floating menu bar.

You should see the following Calculator frame:



Call a Calculator Frame

To open the calculator frame in your application, you must add a callframe statement to the script of each frame that will call it.

To open the calculator from a menu command

1. Create the menu item that will be used.

In the following example, a menu button called “Calculator” on a menu called “Tools” was used.

2. Add the following to the script of the calling frame:

on click menu.tools.calculator = { callframe My_Calculator; }

How a Calculator Works

The calculator that is created from the calculator frame template looks and operates like a standard pocket calculator. It appears as follows:

End users can enter numbers and operators by using the keyboard or clicking the calculator's buttons. The numbers appear in the current value field, while the cumulative result of the operations are shown in the field above it. Descriptions of the calculator functions follow:

Save

Saves the current value in the entry field to memory

Rcl

Recalls the most recently saved value from memory

The find_dialog Template


Set

Enables the user to set several calculator options. The Set button opens the following Preferences dialog:

This dialog lets you set the number of decimal places to display, the font size to be used in the entry field, and the Use + - * / = Keys option. When this option is enabled, the calculator polls for keyboard input and automatically processes any operators users type. If this option is disabled, users must press Enter before the operators they type are processed.

Off

Closes the calculator frame window

Sqrt

Performs the square root function on the value in the entry field

x^2

Performs the square function on the value in the entry field

1/x

Performs the inverse function on the value in the entry field

Clr

Clears the entry field; if clicked again, clears the cumulative total field

The find_dialog Template The find_dialog frame template is a core library template that provides a standard dialog for searching and optionally replacing text in a specified entry field on a form. It can be configured as either a Find or a Replace dialog.

If you want to use both Find and Replace dialogs in a single application, you can create a single frame and specify its type when you open it, or you can create a separate frame for each of the two dialog styles.



Create a Find Dialog Frame

You can create a Find dialog frame based on the find_dialog frame template.

To create a frame using the find_dialog frame template




3. Enter the component name in the Name field (for example, My_Find_Dialog).


5. Select core from the Application list and the find_dialog template from the Template list.

6. Click Create.

The Find/Replace Dialog Assistant appears.

7. Select the dialog style: click either Find dialog or Replace dialog.

The bitmap in the upper left corner of the assistant changes accordingly to display your dialog style selection.

Note: You can override either dialog style setting when the dialog is opened at runtime. For more information, see How You Can Call a Find Dialog Frame (see page 292).

8. Click Generate.


Note: In the Find/Replace dialog, the Search For and Replace With fields are both displayed, regardless of which default style you select.





How You Can Call a Find Dialog Frame

The Find or Replace dialog frame is useful in frames that have entry fields containing long textual data that may require editing. The callframe statement may optionally pass a reference for an entry field to be searched; but if it is omitted, the Find dialog frame automatically looks for an active entry field on the form of the parent frame.

You can indicate the style of dialog that you want to have displayed, “Find” or “Replace,” by passing a flag in the callframe statement. This overrides the initial dialog style that the frame was created with. If you omit this flag, the default dialog style is used.

In the following example, a callframe statement specifies both the dialog style and a particular entry field, “textfield”, as the field to search at runtime. This frame is then invoked with Find and Replace menu items. To do this:

1. On a pull-down menu called “Edit” on the frame from which you will be calling the Find dialog, create a menu button called “Find” and a menu button called “Replace”.

2. Create an entry field called “textfield.”

3. Add the event block for the Find menu item:

on click menu.edit.find = { callframe My_Find_Dialog(searchfield = field(textfield), allowreplace = FALSE) /* Find */ with parentframe = CurFrame; }

4. Add the event block for the Replace menu item:

on click menu.edit.replace = { callframe My_Find_Dialog(searchfield = field(textfield), allowreplace = TRUE) /* Replace */ with parentframe = CurFrame; }

In the preceding example, the Find and Replace menu items could have been used to search any entry fields on the form by omitting the searchfield parameter.

If there is only one entry field on a form that can be searched, the Find or Replace dialog can be opened using an openframe statement instead of callframe. This lets you switch back and forth between the parent frame and the dialog without having to close the dialog each time. In this case, you should verify that the dialog is not already open before creating a new instance of it. To facilitate this, the dialog sends a FindDlgClose or ReplaceDlgClose user event to its parent window whenever it is closing.



In the following example, a flag is set whenever the Find dialog is opened, and cleared whenever the corresponding user event is received. It is based on the previous example except that now an openframe statement is used, and the dialog for one active entry field is opened:

initialize()= declare dlg_open_flag = integer not null; enddeclare { dlg_open_flag=FALSE; } on UserEvent 'FindDlgClose' on UserEvent 'ReplaceDlgClose'= { dlg_open_flag = FALSE; } on click menu.edit.find = { if dlg_open_flag = FALSE then dlg_open_flag = TRUE; openframe My_Find_Dialog() with parentframe = CurFrame; endif; }

How a Find Dialog Frame Is Used When the Find dialog style is selected, the frame appears as follows when it is opened:

The font_dialog Template


Likewise, if a Replace dialog is created, it appears as follows:

Note: When testing the dialog without a parent frame to search, you receive a warning message when the dialog opens. Click OK to ignore this message.

Each dialog's Find Next button searches for the next occurrence of the string that is entered. Searches can be either case-sensitive or case-insensitive, and wrap to the beginning of the entry field when the last occurrence of the search string is found. In a Replace dialog, the user may replace each occurrence of the string individually or replace all occurrences globally.

By default, the Find or Replace dialog tries to identify an active entry field to search in the parent frame (the frame's current InputFocusField), unless a particular field is specified when the frame is opened.


The font_dialog frame template is a core library template that provides a standard interface for changing the font settings of field text at runtime. In addition to including controls for selecting the font typeface, size, and style, the dialog contains a sample display so that users can preview their changes before applying them.



Create a Font Dialog Frame

You can create a Font dialog using the font_dialog frame template.

To create a frame using the font_dialog frame template




3. Enter the component name in the Name field (for example, My_Font_Dialog).


5. Select Core from the Application list and the font_dialog template from the Template list.

6. Click Create.

The Font Dialog Assistant appears.

7. Click Generate.




How You Can Call a Font Dialog Frame

To open the Font dialog frame in your application, you must add a callframe statement to the script of the frame in which you want to change the font. In your callframe statement, you can optionally pass by reference the entry field to be changed. Otherwise, the dialog automatically searches for any active entry field in the parent frame.

You would perform the following steps:

1. Open the dialog by clicking Format, Font on the floating menu bar.

2. Specify “textfield” as the field to change.

3. On the frame from which you will be calling the Font dialog, create a menu button called “Font” on a pull-down menu called “Format”.



4. Create an entry field called “textfield.”

5. Add the event block for the Font menu item:

on click menu.format.font = { callframe My_Font_Dialog(fontfield = field(textfield)) with parentframe = CurFrame; }

When the dialog is created, its font settings and the Sample display box reflect the current font attributes of the active (selected) form field. You can override this behavior by passing a reference to any form field containing text when the Font dialog is opened. The Font dialog's frame script provides instructions and code samples that you can add to your parent frame to automatically track the currently selected field.

To use the My_Font_Dialog, you must provide an event handler in a parent frame script to open the dialog when required:

openframe My_Font_Dialog (fontField = currently_selected_field) with parentFrame = CurFrame;

The fontField parameter is optional. If you don not provide it, the template will try to find the current active field in the parent frame (the InputFocusField).

If you want the My_Font_Dialog to dynamically track the currently selected form field while the dialog is displayed, or if you want use it together with the Font_Bar toolbar segment, you must also include one or more of the event handlers described as follows.

To enable the Font dialog to track the currently selected field and display that field's font attributes, one or more of the following event handlers must be added to the parent frame's script (not the My_Font_Dialog script). Which event handlers to include depends on how much control you want to give the user.

To allow fonts to be set for entry fields only, include only the ChildEntry event handler. To also allow fonts to be set for other types of fields such as buttons, list fields, or trim, include one or both of the other handlers. If you only want to allow the font to be set for a particular field, no event handlers are needed. Instead, pass a reference to that field when the frame is created, as shown below:

openframe My_Font_Dialog (fontField = field (myField)) with parentFrame = CurFrame;

If you include event handlers to track the current field, you can add your own code to each of these handlers to perform application-specific processing.

The splash_screen Template


How a Font Dialog Frame Is Used

After the Font dialog frame is created and called from your application, it appears as follows:

The font settings and Sample display box reflect the current font attributes of the active form field. It lets the user set the font type, size, and style. By default, font changes are applied to the most recently selected entry field in the dialog's parent frame.

The Font dialog contains the following buttons:

OK

Applies the current font setting to the selected field and closes the dialog

Apply

Applies the current font settings to the selected field, leaving the Font dialog open

Close

Closes the dialog without applying any changes


The splash_screen frame template is a core library template that provides a start-up window, which appears briefly when your application starts up to identify the application name and version number. The template also includes an image trim field that you can customize with your company's logo.



Create a Splash Screen Frame

You can create a splash screen frame using the splash_screen frame template.

To create a frame using the splash_screen frame template




3. Enter the component name in the Name field (for example, My_Splash_Screen).


5. Select Core from the Application list and the splash_screen template from the Template list.

6. Click Create.

The Splash Screen Assistant appears.

7. Enter the current version number of your application in the Application version field.

The version can include text as well as numbers (for example, 1.0 Beta).

8. Enter the number of seconds you want the splash screen frame to be displayed in the Display time (sec) field.

9. Click Generate.


Note: All the fields containing text are blank; the text strings only appear at runtime.

10. Change the default logo:

a. Select the image trim field in the upper left corner of the form, and then select the Image property in the Property Inspector.

A standard Browse dialog appears, displaying the default logo.

b. Click Browse.


c. Select a graphic file and click OK.

The selected logo appears in the Browse dialog.

11. Click OK.

The logo appears in the My_Splash_Screen frame.

The text_editor Template


12. Resize the graphic using either the field's resizing handles or by specifying its Height and Width properties.

13. (Optional) Specify other frame properties using the Property Inspector.


14. Click Debug, Go on the floating menu bar to preview the splash screen frame.

How You Can Call a Splash Screen Frame

To display the splash screen frame when your application begins, add a callframe statement to the initialize script of your main application frame. For example:

callframe My_Splash_Screen;

You can override the default application name, version number, and display time when you open the splash screen frame by adding appname, version, and delay parameters to your callframe statement, as follows:

callframe My_Splash_Screen(appname = 'My_Application', version = '2.0 Beta' delay = 3.0);


The text_editor frame template is a core library template that provides a prepackaged text file editor, with a toolbar and standard menus for file, edit, find/replace, and format operations. You can include a text editor in your application to support the editing of text files or as a notepad for your users.

Creat a Text Editor Frame

You can create a text editor frame using the text_editor frame template.

To create a frame using the text_editor frame template




3. Enter the component name in the Name field (for example, My_Text_Editor).




5. Select core from the Application list and the text_editor template from the Template list.

6. Click Create.

The Text Editor Assistant appears.

7. Click Generate.




How You Can Customize a Text Editor Frame

To open the text editor frame from another frame in your application, add a callframe or openframe statement to the other frame's script, as follows:

openframe My_Text_Editor;

You can disable certain functionality, such as formatting, simply by removing the appropriate menu commands from your text editor frame and disabling the corresponding toolbar segments, if necessary. You can also supplement the text editor's functionality by adding your own menu commands or toolbar buttons.

How a Text Editor Is Used

The text editor frame handles text documents of any length. Files with embedded formatting, such as word processing documents, are not supported. Although the text editor lets you choose a font for the document, this is used only for the current display and is not saved with the file.



The text editor frame appears as follows:

Text Editor Functions

The text editor provides standard File menu commands for creating a new file, opening and closing a file, and saving to a file. The Edit menu contains functions for cutting, copying, and pasting text, in addition to Find and Replace to locate text strings. You can also invoke a standard Font dialog by clicking Format, Font.

Toolbar

A toolbar consists of a set of iconized items from which the user makes a selection by clicking the mouse pointer on it. Toolbar items typically consist of buttons that provide shortcuts for frequently used menu commands or for easy access to other features or frames.

The basic toolbar of the text editor frame has the following segments:

The first segment contains a cluster of buttons for the New, Open, and Save commands on the File menu.

The second segment contains a button group for Cut, Copy, and Paste on the Edit menu.

The third segment provides a set of controls for font changes.

The financial_calculator Template



The financial_calculator frame template is a finance library template that can be used to include a prepackaged calculator frame in your application. This calculator supports a variety of loan and investment calculations, including present value, future value, interest rate, duration, payment, and amortization.

Note: For information about a basic calculator, see The Calculator Template (see page 287).

Create a Financial Calculator Frame

You can create a financial calculator frame using the financial_calculator frame template.

To create a frame using the financial_calculator frame template




3. Enter a name for your new frame in the Name field (for example, My_Financial_Calculator).


5. Select finance from the Application list field and the financial_calculator template from the Template list field.

6. Click Create.

The Financial Calculator Assistant appears.

7. Click Generate.


The financial calculator frame can be run without any modifications.



How a Financial Calculator Is Used

The financial calculator created by the financial_calculator frame template provides a number of loan and investment calculations. It appears to the user as follows:

Numbers and operators can be entered using either the keyboard or by clicking the calculator's buttons. Descriptions of the financial calculator's fields and functions follow:

Present Value

Specifies the present value (the amount borrowed or invested)

Interest/Year

Specifies the amount of interest to be applied (paid or earned) to the present value per year

Future Value

Specifies the future value (the present value plus the interest over the course of the loan or investment period, based on the interest and payment value)

Number of Periods

Specifies the number of periods for which to calculate interest



Payment

Specifies the amount to be paid or earned per period

Principal Part

Specifies the portion of the payment that represents the borrowed amount, in the case of a loan

Interest Part

Specifies the portion of the payment that represents the interest on the borrowed amount, in the case of a loan

Decimal Places

Specifies the number of decimal places to be used in the Present Value field

Period

Specifies the specific period (throughout the Number of Periods duration) for the payment to be made

Pay at start

Specifies that the payment is made at the start of the period, if enabled; otherwise, specifies the end of the period

Periods/Year

Specifies the number of periods per year

Calculate

Calculates the data entered in the frame's editable fields and enters the result in the Present Value field

Reset

Clears all entry fields

Help

Displays a Help window for the financial calculator

Quit

Closes the running application

After the user enters values into the appropriate fields, clicking Calculate performs the calculations. To close the financial calculator frame, click Quit.

The mastdetl Templates



You can use the Frame Assistant to define the queries and the query result columns that are displayed in frames generated from the OpenROAD mastdetl frame templates—including simple field, table field, master-detail, detail, and explosion frames. You can also specify additional tables, including lookup, associate, or detail tables for these generated frames.

How You Can Create a Frame from a mastdetl Template

You can create a frame from one of the mastdetl templates using the Frame Assistant. Begin with the following steps:




3. Enter the component name in the Name field.


5. Select mastdetl from the Application list and a template from the Template list.

6. Click Create.

If you selected the detail or explosion template in Step 5, the Select a Parent dialog appears as shown in the following illustration:

For detail frames only, it is then followed by the Select Database Object dialog.



For a detail frame or an explosion frame: Specify its parent frame by selecting an application and a frame from the Application and Frame list fields, respectively, in the Select a Parent dialog, and then click OK.

If you selected the simple_field, table_field, or master_detail template in Step 5, then the Select Database Object dialog appears after clicking Create in Step 6. For example:

For simple field, table field, master-detail, and detail frames: Enter the name of the primary table or tables in the Select Database Object dialog, and click OK.

Alternatively, click the control button to select a valid table from the Table Selection dialog. For more information, see Table Selection Dialog (see page 308).

When you create a master-detail frame, the Frame Assistant appears:



The Frame Assistant consists of two distinct areas:

Query display area

Provides a pictorial view of the tables you specify and the join relationships between them. It lets you define lookup tables and associate tables, as well as detail tables (for master-detail and detail frames).

Join and result column properties area

Lets you specify join columns between tables, as well as set query expressions, query properties, and display properties for the result columns of the query.

Note: The contents of these two areas vary slightly depending on the predefined frame template selected. Therefore, see the individual Mastdetl template sections that follow this overview of the Frame Assistant.

7. (Optional) Select query expressions, query properties, and display properties for result columns.

For more information, see:

How You Can Set Query Expressions (see page 310)

How You Can Set Query Properties (see page 311)

How You Can Set Display Properties (see page 313)

Add Additional Tables to a Generated Frame (see page 332)

8. (Optional) Specify additional tables, including lookup or associate tables, for the generated frames.

For more information, see Add Additional Tables to a Generated Frame (see page 332).

9. (Optional) Specify join columns and join column properties.

For more information, see How You Can Define Join Column Properties (see page 314).

10. Click Generate.

The appropriate frame is created and displayed in the Frame Editor.

11. Specify the frame's properties using the Property Inspector.

For example, you can set such properties as BgColor, BgPattern, IsAutosized, IsMaximizable, IsMinimizable, IsResizeable, and WindowPlacement.




Table Selection Dialog

For simple field, table field, master-detail, and detail frames, the Select Database Object dialog provides a control button that opens the Table Selection dialog. Using the Table Selection dialog, you can select a valid table from a list of tables in the database. For example:

This dialog also displays the tables' owners, types, and the number of table rows. The check boxes at the bottom of the window are used to control the types of tables that are displayed, including user tables, DBA tables, and system catalogs.

To select a table in the Select a Table dialog

Select its row and click Select.

Click Refresh to update the display of tables currently in the database.



Table Definition in the Frame Assistant

When the Frame Assistant is opened, graphic icons for the specified primary tables are initially displayed. Additional tables can be added by using the three buttons located at the upper left corner of the query display area, shown in the following illustration:

The upper row of tables in the query display area represents the master query, and the additional rows specify one or more detail queries.

Note: In simple field and table field frames, detail tables cannot be added.

The primary table column contains those tables that serve as the primary source of data for the query. Additional tables that you add are displayed in other columns in the Frame Assistant window.



How You Can Set Query Expressions

The Frame Assistant lets you define the result columns included in a query. To display the query expressions, select the appropriate table in the query display area, and click Query Expressions in the center of the frame assistant.

The Frame Assistant changes accordingly:

Column Name

Displays all the columns defined in the specified primary table

Query Expression

Lists the query expression that will be used in the SQL query for each column.

In the Query Expression column, you can perform several operations. By clicking the control button, you can insert a row before the current row, delete the current row, or delete all rows. Also, the up and down arrow buttons move the currently selected query expression up or down one position in the list.

To create a new query expression for a table column, click its name in the Column Name list and click the “>” button. Clicking the “>>” button causes a new query expression for each table column to be created by moving all the column names into the Query Expression box.

Insert, Update, Delete Check Boxes

Determine whether data can be inserted, updated, or deleted in the generated frame. These settings apply to all tables in the frame.



How You Can Set Query Properties

You can also set the characteristics of the query of a specific table. This controls how values are retrieved from the table.

To display the query properties of a table, select the appropriate table in the query display area, and then click Query Properties in the center of the Frame Assistant.

The Frame Assistant changes accordingly:

Query Expression

Displays all the target query expressions/columns defined for the specified primary table and is used to identify which column's properties are being modified

Aggregate Function

Lets you select an aggregate function to be applied to the selected query expression/column. The possible choices of aggregate functions are as follows:

Group By

Combines the results for identical values in the column

Sum

Specifies the column total

Avg

Specifies the average (sum of the values/count)



Min

Specifies the minimum value

Max

Specifies maximum value

Count

Specifies the count of occurrences

Where

Used to further qualify the query for the column based on the contents of the Criteria field

--

Indicates that no aggregate function is specified

Sort Order

Lets you choose the order of rows in the results table:

Ascending

Sorts from the lowest value to the highest

Descending

Sorts from the highest value to the lowest

Column Result Criteria

Specifies the criteria to be used on the column to restrict the rows returned by the query. This field is applicable if Where is specified in the Aggregate column.

Select Distinct

When enabled, eliminates duplicate rows returned from the query



How You Can Set Display Properties

To specify the display characteristics of the fields generated for each of the result columns in a query, select the appropriate table in the query display area, and click Display Properties in the center of the Frame Assistant. The Frame Assistant changes accordingly:

Query Expression

Displays all the target query expressions/columns defined for the specified primary table and is used to identify which column's properties are being modified

Field Name

Specifies the value to be used for the field name and the caption of the field associated with the query expression

Usage

Specifies the operations that can be performed on the field. These operations are further restricted by the frame-wide values specified in the Insert, Update, and Delete options in the Query Properties.

The possible choices for the Usage column include:

Insert/Update

Specifies that new values for the field can be inserted and existing values for the field can be updated

Update only

Specifies that existing values for the field can be updated only



Insert only

Specifies that new values for the field can be inserted only

Display only

Specifies that the displayed value of a field cannot be modified

No display

Specifies that a field associated with the query expression is not generated

Criteria only

Specifies that the column can be used for qualification without a field being generated

Default: Insert/Update

Field Template

Lets you select a field template from any included application. To do so, click the control button to open the Select a Field Template dialog. Then select the desired application and field template, and click the Select button.

How You Can Define Join Column Properties

When you create a master-detail frame or add lookup, associate, or detail tables in the Frame Assistant, the join column or columns must then be configured to define the relationships between the tables.



To define the properties for a particular join column (master-detail or associate), click its join icon in the query display area. The Frame Assistant changes to display the join column properties:

The list on the left side displays the columns in the selected primary table. The right side list displays the columns in the selected lookup, associate, or detail table.



Add a Join

You can join columns using the Frame Assistant.

To define the columns to be joined

Select the desired column in each list field to be joined, and click Insert.

For example, a join is added to the Frame Assistant as follows:

The Default button adds a join between columns with the same name.

Delete a Join

You can delete joins using the Frame Assistant.

To delete a join

To delete a join that has been inserted, click Delete and then a particular join column.

To clear all joins, click Clear.

Delete Rule Options

The Delete Rule option field specifies how the deletion of rows is handled between the queries of a frame. The available options for Delete Rule are as follows:

Restrict (app)

Specifies that the application prevents the deletion of a master row if associated detail rows exist

Cascade (app)

Specifies that the application cascades the deletion of a master row by also deleting its associated detail rows



Restrict (dbms)

Specifies that the application assumes the presence of internal database rules that prevent the deletion of a master row if associated detail rows exist. The master row will be deleted if no such rules exist, orphaning its associated detail rows.

Cascade (dbms)

Specifies that the application assumes the presence of internal database rules that cascade the deletion of a master row by also deleting its associated detail rows. The master row will be deleted if no such rules exist, orphaning its associated detail rows.

None

Specifies that no delete rules are specified. The master row is deleted, regardless of whether there are associated detail rows.

The following sections illustrate in more detail how to create simple field, table field, master-detail, detail, and explosion frames. Subsequent sections describe how to add lookup, associate, and detail tables to your frame.

The simple_field Template

The simple_field frame template creates a standard database table browser. The generated frame consists of a matrix of entry fields, which are automatically loaded with the results of a single query against one or more joined tables. Each field maps by name and type to one of the result columns of the query. The frame can display only one row returned by the query at a time.

Note: Frames generated from this template cannot call frames generated from the detail or explosion frame templates. In contrast, a similar type of frame—a table field frame—can call detail or explosion frames. For more information, see The table_field Template (see page 321).

Create a Simple Field Frame

You can create a simple field frame using the simple_field template.

To create a frame using the simple_field template






3. Enter the component name in the Name field (for example, My_Simple_Field).


5. Select mastdetl from the Application list and the simple_field template from the Template list.

6. Click Create.

The Select Database Object dialog appears.

7. Enter the name of the primary table in the Table field.

For more information on using the control button to the right of the entry field to specify a table, see Table Selection Dialog (see page 308).

8. Click OK.

The Frame Assistant appears.

9. Using the Frame Assistant, you can optionally specify additional tables, including lookup or associate tables. You can also select query expressions, query properties, and display properties for result columns.






10. Click Generate.




How You Can Use a Simple Field Frame

The generated simple field frame provides a set of VCR buttons and a slider to navigate through each selected row, with its values updated automatically in a matrix of fields.

To see the simple field frame in operation, click Debug, Go on the floating menu bar.



The frame's Form menu provides commands to perform standard database row operations such as inserting a new row, duplicating the current row, deleting a row, and saving changes to the table. The Sort command lets you choose the order that the data rows appear in the frame. For more information, see How You Can Sort Data in a Frame (see page 319).

You can also perform queries based on the data you enter into one or more fields by clicking Form, Query. For more information, see How You Can Perform a Query (see page 320).

Note: Use the standard Close button in the upper right corner to close a running frame and return to the Frame Editor.

How You Can Sort Data in a Frame

By default, the sort order of the data that appears in the frame is based on the order of the columns in the table. In addition, each column returns data in ascending order. This sort order can be changed by clicking Form, Sort. The Set Data Sort Order dialog appears.

To change the sort order by columns, click a column in the Columns list field and click the right arrow. It then appears in the Order By Columns list field. Subsequent column choices appear in this list in the order they are chosen. Similarly, a column choice can be removed from the Order by Columns list by selecting it and clicking the left arrow button.

To change the sort order further, from within the Order by Columns list, click the column name and then click the up or down arrow. You can set whether the data for a column is sorted in ascending or descending order. By default, data is sorted in ascending order (that is, Asc is selected). To change the sort order for a column to descending order, select the Desc option from the option field.

When you click OK, the selected sort order takes effect, a new query is performed, and the data values are populated into the fields of the frame.



How You Can Perform a Query

When the Query is selected from the Form menu of a simple field frame, the Query dialog appears. On this dialog, you can perform queries based on data entered into one or more entry fields.

The following features are available:

Reading a Query

To read a saved query, click File, Read from File. This displays a standard File Selection dialog from which you can select a file.

Defining a Query

You enter data into the desired fields to define your query. Click Query, Clear to clear all fields on the form.

You can save the current query to a file by clicking File, Write to File. This also displays a standard File Selection dialog, allowing you to select the name and location of the file.

Running a Query

To perform the query, click Run (or click Query, Run).

Accessing Previous Queries

To navigate through previously run queries, click Query, Previous and Query, Next. As you step through each query, the matrix of fields is populated with the associated query data.

Viewing the SQL Commands

You can view the SQL statements and commands that will be executed when the current query is run, by clicking Query, View SQL.

Sorting Query Data

By clicking Query, Sort, you can select the sort order of the rows that are returned from the query. (This is the same sort order used for the simple field frame, accessed by clicking Form, Sort.)

For more information, see How You Can Sort Data in a Frame (see page 319).



The table_field Template

Like the simple_field frame template, the table_field frame template creates a standard database table browser. The generated frame consists of a table field, which is automatically loaded with the results of a single query against one or more joined tables. Each table field column maps by name and type to one of the result columns of the query. This frame can display all rows returned by the query at a time.

Note: Unlike simple field frames, frames generated from this template can call frames generated from the detail or explosion frame templates.

Create a Table Field Frame

You can create a table field frame using the table_field frame template.

To create a frame using the table_field frame template




3. Enter the component name in the Name field (for example, My_Table_Field).


5. Select mastdetl from the Application list and the table_field template from the Template list.

6. Click Create.


7. Enter the name of a primary table in the Table field of this dialog.




8. Click OK.


Using the Frame Assistant, you can optionally specify additional tables, including lookup or associate tables. You can also select query expressions, query properties, and display properties for result columns.






9. Click Generate.


Note: An Open Row and an Open List button are provided in the Frame Editor. They will appear in a running table field frame only if it is selected as the parent frame for either an explosion or a detail frame (for more information, see Create an Explosion Frame (see page 331) or Create a Detail Frame (see page 329)).



Use a Table Field Frame

When the table field frame is generated, it displays the table browser, containing the data rows resulting from the query and a current row indicator.

To run the table field frame

Click Debug, Go on the floating menu bar.

View Data

The table field frame provides a variety of features that let you view the data in a table. It contains a table browser with a vertical scroll bar that lets you scroll through the records. Its row indicator in the upper left corner of the frame indicates the currently selected record.

In a table field frame, you can choose which rows appear in your frame, as well as the order that they appear.



To sort data

Click Form, Sort to choose the order that the data rows appear in the frame.

For more information, see How You Can Sort Data in a Frame (see page 319).

To query data

Click Form, Query to perform a query on the database.

For more information, see How You Can Perform a Query (see page 320).

To find a row (to find a text string in the table field)

1. Click Row, Find.

The Find dialog appears:

2. (Optional) Select the Ignore Case option to make the search case-independent.

3. Select among the First, Any, Last, or All options to find a particular occurrence of the string.

4. Click Find.

If the string is found, the row in which it appears is highlighted.

Note: To repeat the last Find operation, click Row, Find Next.

Edit Data in a Table

The table field frame also lets the end user edit data in the table, including inserting, updating, or deleting rows (records).

To insert and delete data

Select one of the corresponding commands from the Row menu to perform standard row operations, such as adding a new row, duplicating the current row, deleting a row, or deleting all rows.



To update data

Click inside the table cell and enter the new value to update an existing value in the table.

Press Tab or Shift+Tab to move between the columns in the table. To move to the next row, press Enter or Tab.

To create a new table

1. Click Form, New.

2. Click the control button to create the first table row. Then select Create First Row from the menu, which creates the first row.

To save data

Click Form, Save.

Copy a Table

You can copy a table in a table field frame to the Clipboard.

To copy the table in a table field frame

1. Click Row, Copy Table.

The Copy Table dialog appears.

The two options on the dialog are:

Include Field Names

If enabled, specifies that field names are copied into the first row of the Clipboard

Flip Rows and Columns

If enabled, specifies that row and column data is reversed. The data that appears in the nth row is copied into the nth column, and vice versa.

2. Click Copy to Clipboard to perform the operation.



The master_detail Template

Like the simple_field and table_field frame templates, the master_detail frame template creates a database table browser. However, master-detail frames perform two queries that exist in a one-to-many master-detail entity relationship. The master query, which queries one or more joined tables, is used to populate the master portion of the frame; the detail query, which can also query one or more joined tables, is used to populate the detail portion of the frame.

Note: Frames generated from this template can call frames generated from the detail or explosion frame templates.

Create a Master-Detail Frame

You can create a master-detail frame using the master_detail frame template.

To create a frame using the master_detail frame template




3. Enter the component name in the Name field (for example, My_Master_Detail).


5. Select mastdetl from the Application list and the master_detail template from the Template list.

6. Click Create.


Note: The Select Database Object dialog displays two entry fields instead of the usual one.

7. Enter the name of the primary master table in the Master entry field.

8. Repeat this procedure for the primary detail table using the Detail entry field.




9. Click OK.

The Frame Assistant appears:

10. Click the join icon in the query display area.

11. Before generating the master-detail frame, you must define one or more join columns between the two tables. Then click Insert to create a join.

A line is drawn between the two columns indicating the join.








13. Click Generate.

If the tables you specified have “updatable” columns but no key, an Information dialog appears.



14. Click OK to continue.

The master-detail frame is created and displayed in the Frame Editor.

Note: An Open Row and an Open List button are provided in the Frame Editor. They will appear in the running frame only if the master-detail frame is selected as the parent frame to either an explosion or a detail frame (for more information, see Create an Explosion Frame (see page 331) or Create a Detail Frame (see page 329)).



How You Can Use a Master-Detail Frame

The generated master-detail frame displays a master and a detail section. The master section of a frame is used to display a single row passed to it from a calling frame's detail table field. It consists of a set of VCR buttons and a slider to navigate through each selected row, with its values updated automatically in a matrix of fields. Each field is mapped by name and type to the result columns of the master query.

The detail section of a detail frame is used to display the rows of a second query of one or more joined tables that are associated with the master query. It contains a table field, each of whose columns maps by name and type to the result columns of the detail query.

To see the master-detail frame in operation, click Debug, Go on the floating menu bar.

Master Query Table Operations

The Form menu provides commands to enable the user to perform standard database operations on the master query table, such as inserting a new row, duplicating a row, and saving the changes to the table. It also enables you to perform a query or sort the data in the master-detail frame. For more information about sorting and querying, see How You Can Use a Simple Field Frame (see page 318).



Detail Query Table Operations

As the user is navigating between rows of the master query, the table field in the detail section of the frame is automatically populated with those rows in the detail query associated with the current row in the master section. The Row menu commands also perform standard database operations on the detail database table, such as adding a new row, duplicating a row, finding text, and copying the table. (For more information on how to find text and copy a table, see Use a Table Field Frame (see page 322)).

A new table can also be created by clicking Form, New. To enter new data, click the control button and select Create First Row. For information about editing data in a table, see Use a Table Field Frame (see page 322).

Synchronous or Asynchronous Frame Processing

In the master-detail frame, keeping the data in the parent and explosion or detail (child) frames “in sync” could be a tedious job. However, using The OpenROAD frame templates, it is handled seamlessly by the frame's synchronization mode.

By default, the generated frame is synchronous, which means that the parent and child frames are both updated when a change is made in either frame. In asynchronous mode, the parent and child frames operate independently.

To make the frame asynchronous, click the control button and then clear Synchronous Detail Frame from the option menu, removing the checkmark.

When the parent frame is in asynchronous mode and the explosion or detail frame is displayed, its VCR buttons do not appear. There is no need for the parent and child to remain synchronized, so these buttons are not necessary. Thus, the presence of the VCR buttons on the explosion or detail frame is dynamic, depending on a selection made at runtime.

The detail Template

The detail frame template is used to generate a frame that binds a database query that exists with a one-to-many master-detail entity relationship with the detail table field associated with calling frames generated from the table_field, master_detail, or detail frame templates.

Although similar in appearance to frames generated from the master_detail frame template, detail frames perform only one query.

Note: Frames generated from this template can call frames generated from the detail or explosion frame templates.



Create a Detail Frame

You can create a detail frame using the detail frame template.

To create a frame using the detail frame template




3. Enter the component name in the Name field (for example, My_Detail_Frame).


5. Select mastdetl from the Application list and the detail template from the Template list.

6. Click Create.

The Select a Parent Frame dialog appears.

7. Specify the detail frame's parent frame by selecting an application and a frame from the Application and Frame list fields, respectively, and then click OK.


8. Enter the name of a detail table in the Detail field of this dialog.


9. Click OK.


10. Click the join icon in the query display area.

11. Before generating the detail frame, you must define one or more join columns between the two tables. Then click Insert to create a join.

A line is drawn between the two columns indicating the join.










13. Click Generate.

The detail frame is created and displayed in the Frame Editor.

Note: An Open Row and an Open List button are provided in the detail section of the frame in the Frame Editor. They will appear in the running frame only if the detail frame is selected as the parent frame for either an explosion or a detail frame (see Create an Explosion Frame (see page 331)).

14. (Optional) Specify the frame's properties using the Property Inspector. For example, set the IsResizeable property to TRUE.


Use a Detail Frame

The generated detail frame displays a master and a detail section. The master section of a detail frame is used to display a single row passed to it from a calling frame's detail table field. It consists of a set of VCR buttons and a slider to navigate through each selected row, with its values updated automatically in a matrix of fields. Each field is mapped by name and type to the columns of the parent frame's table field.

The detail section of a detail frame is used to display the rows of a second query of one or more joined tables that are associated with the detail query of the calling frame. It contains a table field, each of whose columns maps by name and type to the result columns of the detail frame's query.

To see the detail frame in operation

1. In the Frame Editor, open the parent frame with which it is associated.

2. Click Debug, Go on the floating menu bar.

3. Highlight a row in the detail table, and then click Open List to display the detail frame.

Note: The VCR buttons are not present if the parent is a master-detail frame running in asynchronous mode.



The Row menu provides commands to perform standard database row operations such as inserting a new row, duplicating the current row, finding text, copying the table, and saving changes to the table. For more information about finding text or copying a table, see Use a Table Field Frame (see page 322).

The explosion Template

The explosion frame template is used to generate a frame that displays in greater detail a single row from the table field of a frame generated from the table_field, master_detail, or detail frame templates.

Typically, for queries with a large number of result columns, creating a table field that represents all of them is inconvenient. A better solution is to have a select number of critical columns reflected in the table field, and use an explosion frame to display the values of all the other columns for the current row of the table field.

Although similar in appearance to frames generated from the simple_field frame template, explosion frames do not perform queries and are not meant to run stand-alone. They depend on a parent table field, master-detail, or detail frame to provide them with the data to be displayed.

Note: Explosion frames cannot call other frames generated from any of the other four mastdetl frame templates.

Create an Explosion Frame

You can create an explosion frame using the explosion frame template.

To create a frame using the explosion frame template




3. Enter the component name in the Name field (for example, My_Explosion).


5. Select mastdetl from the Application list and the explosion template from the Template list.

6. Click Create.

The Select a Parent Frame dialog appears.



7. Specify the explosion frame's parent frame by selecting an application and a frame from the Application and Frame list fields, respectively, and then click OK.

The explosion frame is created and displayed in the Frame Editor.



Use an Explosion Frame

The generated explosion field frame provides a set of VCR buttons to navigate through each selected row, with its values updated automatically in the matrix of fields.

Because explosion frames are not meant to perform queries or run stand-alone, they are generally run from a parent table field frame, master-detail frame, or detail frame.

To see the detail frame in operation

1. In the Frame Editor, open the parent frame with which it is associated.

2. Click Debug, Go on the floating menu bar.

3. Highlight a row in the detail table, and then click the Open Row button to display the explosion frame.

Note: The VCR buttons are not present if the parent is a master-detail frame running in asynchronous mode.

The Field menu provides commands to prevent a user from changing the values in one or more fields. A field cannot be edited by selecting a field and clicking Field, Freeze. The Unfreeze and Unfreeze All commands on the Field menu let you disable this feature for individual fields or all fields.

Add Additional Tables to a Generated Frame

You can specify additional tables—lookup, associate, and detail primary tables—while creating a frame using one of the mastdetl predefined templates.



Create Lookup Tables

Lookup tables are bound to a specific column in a primary table and are used to provide a list of possible values for those columns. Lookup tables are also used during user input as a validation mechanism.

To create a lookup table for a primary table

1. Create another master-detail frame.

For more information, see Create a Master-Detail Frame (see page 325).

2. Select the appropriate table icon in the query display area.

3. Click Add Lookup Table.


4. Enter the name of a lookup table in the Lookup field.


5. Click OK.

The lookup table is added to the query display area.

6. Insert a join between one or more columns (for example, emp_num), by clicking the Default button or Insert for individually selected columns.


7. Select the lookup table icon in the query display area.

8. Define the properties for your lookup table, as described in Lookup Table Properties (see page 334).



9. Click Generate.


For example:

Lookup Table Properties

After you have added a lookup table, you can define the join column between the lookup table and another participating table in the frame. The order that the fields appear in the lookup frame can be modified, and you can set whether the end user can further qualify lookup information.

To specify the properties of a lookup table, select the appropriate lookup table icon in the query display area, as shown in the example.

Non_Validating Lookups

When the Non-Validating Lookups option is enabled, the generated frame does not validate the fields in new records (that is, those to be inserted into the corresponding database table) against the values in each field's defined lookup table.

Table Columns

The list field on the left side of the Frame Assistant displays a list of columns in the selected primary table. The right side list field displays the columns in the selected lookup table.



Defining Join Columns

To define the columns to be joined, select the desired row in each list field to be joined, and click Insert. The Default button adds a join between columns with the same name.

Deleting Joins

You can click Delete and then click a particular join column to clear a join that has been inserted. To clear all joins, click Clear.

Field Order

The Order entry field lets you specify which columns appear in the lookup frame (if a value is entered), as well as the order that each field appears on the lookup frame (determined by a numeric value). By default, the Order field is populated with incrementing values as joins are added.

Lookup Qualification

To set whether the end user can further qualify information displayed in the lookup, select one of the following options in the Lookup Qualification option field:

Allow

Lets the user qualify the lookup frame

On Startup

Requires that the user qualify the lookup before the lookup frame appears

None

Specifies that the user cannot further qualify the lookup frame

Default: Allow

Lookup Frame Name

You can use a custom lookup frame instead of the default lookup frame by entering the name of the custom frame in the Lookup Frame Name field.

How You Can Use a Lookup Frame

A lookup table is used to provide the user with a list of possible choices for a field in a frame. This list is presented in a lookup frame that can allow the user to further qualify the choices in the lookup table. For example, in the master-detail frame just created, click in the Emp Num entry field.

Next, click Field, Lookup. The Lookup frame appears.



If the lookup frame was created with the Allow Lookup Qualification option, an end user can further qualify the information displayed in the lookup frame by clicking the Qualify button. This displays the Query dialog:

Note: For more information about using the Query dialog, see Create a Table Field Frame (see page 321).

Select any row from the lookup table and click OK.

Create an Associate Table

An associate table can be joined to a primary table to provide additional data. The columns from each table can be included as fields in the frame.

To create an associate table

1. Create another master-detail frame.

For details, see Create a Master-Detail Frame (see page 325).

2. Select the appropriate table icon in the query display area.

3. Click Add Associate Table.


4. Enter the name of an associate table in the Associate field.


5. Click OK.

The associate table icon is added to the query display area.

6. Insert a join between one or more columns by clicking Default or Insert for individually selected columns.

A line is drawn between the columns indicating the join.


7. Select the associate table icon in the query display area.



8. Click Display Properties.

The associate table properties appear.

9. Click in the desired field and select No display from the Usage field.

Note: Because you probably would not want to display this common field twice (once for each table), the No display option prevents duplicate fields in this case.

For more information about specifying operations that can be performed on fields, see How You Can Set Display Properties (see page 313).

10. Click Generate.


Create Detail Tables

You can add additional detail primary tables to frames generated from the master_detail and detail frame templates.

To create an additional detail table

1. Create a new master-detail frame.

For more information, see Create a Master-Detail Frame (see page 325).

2. Select the master primary table icon in the query display area.

3. Click Add Detail Table.


4. Enter the name of a detail table in the Detail field.


5. Click OK.

The detail table icon and a new join icon are added to the query display area.

6. Insert a join between one or more columns by clicking Default or Insert for individually selected columns.

A line is drawn between the columns indicating the join.


The toolbar_window Template


7. Set the desired query and display properties for the new master-detail relationship.






8. Click Generate.




10. To see the additional detail table in the frame, click Debug, Go on the floating menu bar.

The frame appears containing the additional detail table.

11. When you are finished, close the running frame and then click File, Close to exit the Frame Editor, saving changes appropriately.

The toolbar_window Template

The toolbar_window template is a misc library template that creates a standard dialog containing a basic toolbar in a stack field and a File menu with a Close command.

The basic toolbar of the text editor frame has the following segments:

The first segment contains a cluster of buttons for the New, Open, and Save commands on the File menu.

The second segment contains a button group for Cut, Copy, and Paste on the Edit menu.

The third segment provides a set of controls for font changes.

Note: For more information on creating custom toolbars, see Creating Toolbars (see page 399).

The mclient_frame Template


Create a Toolbar Frame

Using the Frame Editor, you can create a toolbar frame from the toolbar_window frame template.

To create a toolbar window using the toolbar_window frame template




3. Enter the component name in the Name field (for example, My_Toolbar_Window).


5. Select misc from the Application list and select toolbar_window from the Template list.

6. Click Generate.




The mclient_frame Template

The mclient_frame template is a core library template for use with mClient. You can use it to create full screen frames so that mClient can run on the Pocket PC.

For more information, see mClient Deployment (see page 611).

Generating Fields from Predefined Templates 341

Chapter 9: Generating Fields from Predefined Templates


Predefined Field Templates (see page 341) How You Can Add a Generated Field to a Frame (see page 342)

OpenROAD offers an extended set of field templates that can enhance the look and feel of your application frames. You can add various types of fields with a few mouse clicks. These templates are contained in OpenROAD Workbench libraries that may be easily incorporated in your application.

Note: Before you can begin to create fields from predefined templates, you must include the appropriate OpenROAD libraries in your application. By default, the core application library is included in your application. You may have performed this step previously if you have already automatically generated frames (as described in Generating Frames from Predefined Templates (see page 281)). If not, see Creating an Application (see page 81) for a description of how to include additional application libraries into your application.

Predefined Field Templates

OpenROAD Workbench contains many predefined field templates, which are contained in various libraries.

A predefined field template contains references to the data and procedures that appear in all instances of fields generated from that template. The customization procedures facilitate setting attributes whose values are unique to particular instances of fields generated from the template.

The field templates contain all of the 4GL scripts that define the static functionality that is common to all fields created from the templates. The field customization procedures that are coupled with the templates dynamically generate fields that are created from the same template unique from one another.

How You Can Add a Generated Field to a Frame


The OpenROAD libraries and their corresponding field templates are listed in the following table:

Library Field Template

core (default) analog_clock (see page 343) bar_graph (see page 345) calculator_control (see page 350) calendar (see page 351) countdown_timer (see page 352) date_field (see page 353) digital_clock (see page 354) elapsed_timer (see page 357) float_field (see page 358) gauge (see page 358) integer_field (see page 361) line_graph (see page 361) meter (see page 362) money_field (see page 365) smallint_field (see page 365) spin_control (see page 366) stop_watch (see page 370) timezone_control (see page 371)

misc edit_control (see page 371) query_bar (see page 373) tabbed_dialog (see page 376)


To add a generated field to a frame, you use the same basic steps presented in Creating and Using Basic Fields (see page 151). This section also describes how to set the properties for a field using the Property Inspector. For common field property descriptions, see Common Field Properties (see page 239).

The following sections describe how these fields are created using the OpenROAD predefined field templates and assistants. In some cases, techniques that developers can use to customize the generated field are discussed, as well as how a user can use the field.



The analog_clock Field Template

The analog_clock field template displays the time of day using a standard analog clock face (with hour and minute hands) and supports optional alarms that users can set. The clock operates and updates its display automatically.

Note: Only one analog clock should be entered into a frame. Multiple analog clocks in a frame will not operate correctly.

Create an Analog Clock Field

You can create an analog clock field using the analog_clock field template in the Frame Editor.

To create an analog clock field

1. On the Develop tab, in the Components portlet, open the frame in which you want to create the field from the field template.

2. Click Insert, Field From Field Template.

The Select a Field Template dialog appears.

3. Select the core application and the analog_clock template, and then click OK.

4. Position the field on the frame.

The Analog Clock Assistant appears.

The sample shown in the Assistant (in the upper left corner) reflects the time the dialog is opened and its display is updated, as specified.

5. Complete the dialog using the following information:

Enable Alarms

If enabled, lets the user set alarms

Display Seconds

If enabled, displays seconds in the analog clock

Time Zone

Specifies the time zone to use:

Default

Specifies the default time zone of GMT

Selected

Opens a list field, letting the user select another time zone



6. Click Generate.

The field is created and displayed in the Frame Editor:

Note: If you shrink or move the rectangle, the bell alarm icon will be repositioned automatically at runtime. Also, if the clock is made small enough, only the 5-minute interval ticks will be visible.

How an Analog Clock Field Works

When you run the frame containing the analog clock field, it displays the current time. The clock operates automatically and updates its display as specified. If you chose to display seconds, each individual second tick becomes red in turn to show the seconds.

An example of an analog clock display follows. Note that the second indicator is shown on the 11th second:



Setting Alarms

If the Enable Alarms feature is selected when the analog clock is created, the user can set alarms by clicking the clock, which opens the Timer Options dialog.

In this dialog, the user can set one or more alarms. The control button provides several options including inserting a row, deleting the current row, or deleting all rows. These functions are those provided in a table field frame (for more information, see Use a Table Field Frame (see page 322)).

Alarm Time

In the Time entry field, the user enters the time the alarm will be activated (for example, 12:00 PM).

Memo/Event Field

The Memo/Event field is used to enter a message to be displayed at the time of the alarm event.

Alarm Status

When the Status option is checked, the selected alarm is set.

When an alarm is set, a bell icon appears at the right edge of the analog clock field as an indicator. Alarms are active only while the frame containing the analog clock is running.

Alarm Messages

When an alarm is triggered, a message box appears containing the message associated with the alarm.

The timekeeping and display functions of the analog_clock field, as well as the digital_clock and elapsed_timer fields, are handled by a number of user classes. All three fields are based on the timer_manager user class, which in turn uses several private classes and subclasses to perform its functions. For more information, see the appendix “Generated User Classes” in the Language Reference Guide.

The bar_graph Field Template

The bar_graph field template displays the data from one to three data sets in a common bar graph format. The content of the graph is determined completely through the Graph Assistant dialog that serves both the bar_graph and line_graph field templates.



Create a Bar Graph Field

You can create a bar graph field using the bar_graph field template in the Frame Editor.

To create a bar graph field




3. Select the core application and the bar_graph template, and then click OK.


Note: The bar graph field is large compared to most frame fields. You should allow generous distances between it and adjacent fields.

The Graph Assistant appears.


Database Name

Identifies the database to which you are currently connected. To change the database, click Change Database. The Change Database dialog appears:

a. To change the host, enter its name in the Host field. Then click Databases to display the available databases on that host.

b. Select one of the databases from the list field (or enter the host name, followed by :: and the database name, for example, new_york::openroad).

c. Set any flag supported by the Connect method for a DBSession object in the Flags field.

d. Click OK.

Use Current

When enabled, specifies the database currently displayed in the Database Name entry field:

Table Types

Specifies the types of tables that you want to select from, including User, DBA, and System

Data Source

Specifies the name of a table or view that will provide the data for the bar graph. Enter the name directly into the field or click the = button for a list of tables to choose from.



Horizontal Axis

Specifies the name of a column within the specified table that will provide data for the graph. Enter the name directly into the field or click the = button for a list of columns from which to choose.

Note: Selecting <auto> causes the horizontal axis to be labeled with sequential numbers starting at the value entered in the Xmin field.

Data Set

Specifies the data sets to be used in the bar graph. You can define up to three data sets. Follow these steps:

1. Select a specific Data Set number by clicking one of the three toggle fields contained within the Data Set box. (Initially Data Set 1 is selected.)

2. In the Data Set box, click the = button next to the Data Set entry field to update the list field with the available data sets (columns), or directly enter the name of the data set to be used into the entry field.

Note: The data sets map to columns from the Data Source table.

3. (Optional) Specify the legend label to be associated with the Data Set in the Legend Label entry field. (If omitted, the column name entered in the Data Set entry field is used as the default.)

Repeat this process for up to three data sets.

Xmin

Specifies the minimum number of rows (on the horizontal axis) to be graphed

Xmax

Specifies the maximum number of rows (on the horizontal axis) to be graphed

Note: The Xmin and Xmax values are used to adjust the number of rows to be graphed. When the Horizontal Axis is chosen, the Xmin and Xmax values for that column are retrieved and displayed in these fields.

Rows

An informational field only, initially displays the total number of rows (records) in a table selected as the data source (in the Data Source field). The number of rows (in the Rows field) is then updated by computing a new count using the criteria “xaxis >= Xmin and xaxis <= Xmax”, where xaxis is the Horizontal Axis column name.



Horizontal Axis Label

Specifies a label to be used for the horizontal axis of your graph.

If omitted, this defaults to the column name specified in the Horizontal Axis entry field.

Vertical Axis Label

Specifies a label to be used for the vertical axis of your graph.

If omitted, this defaults to the table name specified in the Data Source entry field.

Y-Axis

Specifies the high, step, and low values that correspond to values that will be displayed in the graph. For more information on the Y-Axis box, see How You Can Edit a Bar Graph Field (see page 349).

Note: The High and Low values can be changed but such changes are not recommended.

6

6. Click Generate.

The graph is created and displayed in the Frame Editor as various components within a subform.

For more information on how to make changes to the generated bar graph, see How You Can Edit a Bar Graph Field (see page 349).



How You Can Edit a Bar Graph Field

The generated bar graph field shown in the following illustration contains three differently shaded rectangle shapes (or three differently shaded lines for the line graph), which represent each of the three possible data sets:

The properties of these rectangles or lines correspond to those of the bars or lines, which represent the data as drawn in the actual graph. These properties are described as follows:

Grid Line Color and Style

The grid line color and style is represented by a segment shape (line), which is identified by text Grid Line.

Default: solid, gray

Sizing the Display

The size of the display can be modified by adjusting the size of the drawform subform and its parent subform wrapper. The boxes for the vertical and horizontal labels and the legend may require adjustments depending on the length of the text used in them.



Y-Axis Endpoints and Step Interval

In the Graph Assistant, the Y-Axis box lists the high, step, and low values that correspond to values that will be displayed on the graph. The High and Low values may be adjusted for aesthetic and readability considerations.

Y-Axis Labeling

Lets you configure how the y-axis will be scaled and labeled. The available options are:

Auto Size

Specifies that either Zero Base or High Res is dynamically selected at runtime

Zero base

Specifies that zero (0) appears as one of the y-axis tick labels

High res

Provides the effect of zooming in on the data. Generally, the minimum value on the y-axis is slightly less than the data set minimum rather than being zero.

None

Specifies that no adjustments should be made to the labeling range; the actual maximum and minimum of the selected data is used as the endpoints of the y-axis. (This selection is not recommended for bar graphs whose data is all positive or all negative.)

How a Bar Graph Field Is Displayed

Upon executing the frame containing your bar graph field, the field is graphically displayed, using the data you named in the Graph Assistant.

The calculator_control Field Template

The calculator_control field template creates a complete four-function calculator in a user frame. In addition to chained arithmetic calculations, the calculator includes memory storage and recall, square, square root, and inverse features.

For more information, see the description of the calculator control field functions in Create a Calculator Frame (see page 288).



Create a Calculator Control Field

You can create a calculator control field using the calculator_control field template in the Frame Editor.

To create a calculator control field




3. Select the core application and the calculator_control template, and then click OK.

4. Position the field in the frame.

The Calculator Assistant appears.

5. Click Generate.

The field is created and displayed on the form.

How a Calculator Control Field Works

The calculator control field that is created by the calculator_control field template looks and operates like a standard pocket calculator.

For a description of the features of the calculator control field, see How a Calculator Works (see page 289).

The calendar Field Template

The calendar field template creates a calendar that lets the user select the day, month, and year. The full display can be used only in simple fields.

Create a Calendar Field

You can create a calendar field using the calendar field template in the Frame Editor.

To create a calendar field






3. Select core in the Application list and calendar in the Template list, and then click OK.

The cursor shape changes to indicate that you must set a position for the field.

4. Click the cursor at the point on the frame where you want to place the field.

The Calendar Assistant appears.

5. Click Generate.


How You Can Use a Calendar Field

When you run the frame containing a calendar field, it initially appears with the current day, month, and year selected:

You can change the current day displayed by clicking any of the dates in the calendar. Use the up and down arrow buttons next to the current month and year to increment or decrement their display.

The calendar field functionality is based on the Calendar_Object user class, which handles its processing. For more information about the Calendar_Object user class, see the appendix “Generated User Classes” in the Language Reference Guide.

The countdown_timer Field Template

The countdown_timer field template creates a countdown timer that displays a timer that counts down from a specified amount of time since the frame was opened and updates at a specified time interval. The display format is hours and minutes by default, but you can display seconds also.



Create a Countdown Timer Field

You can create a countdown timer field using the countdown_timer field template in the Frame Editor.

To create a countdown timer field




3. Select the core application and the countdown_timer template, and then click OK.


The Countdown Timer Assistant appears.


Amount to Countdown (hh:mm)

Specifies the time from which to count down when the frame is run

Timer Interval (in seconds)

Specifies the amount of time (in seconds) after which the countdown display is updated

Display Seconds

Specifies that seconds should be displayed in the countdown timer

6. Click Generate.


How a Countdown Timer Field Works

When the frame containing the countdown timer is executed, the field appears containing a specified initial (default) value. For example, the default values in the Countdown Timer Assistant dialog produce the following:

The date_field Field Template

The date_field field template is used to create an entry field of the type date.



Create a Date Field

You can create a date field using the date_field field template in the Frame Editor.

To create a date field




3. Select the core application and the date_field template, and then click OK.



How You Can Use a Date Field

When you run the frame, an empty entry field of type date appears. Any valid date, such as “1/30/06” may be entered and appears as shown when you press Enter:

You can modify the display format through the Property Inspector using date format templates. The field accepts only valid dates. For more information, see Property Inspector (see page 135).

The digital_clock Field Template

The digital_clock field template creates a digital clock that displays the time of day and supports optional alarms the user can set. You can choose either a 12- or 24-hour digital display format.

Note: Only one digital clock should be entered into a frame. Multiple digital clocks within a frame will not function properly.



Create a Digital Clock Field

You can create a digital clock field using the digital_clock field template in the Frame Editor.

To create a digital clock field




3. Select the core application and the digital_click template, and then click OK.

4. Position the field on the frame where you want the upper left corner of the field to be located.

The Digital Clock Assistant appears.


Enable Alarms

Specifies that the user will be able to set alarms

Display Seconds

Specifies that seconds are displayed on the digital clock

Display Format

Specifies whether the time should be presented in a 12-hour format or a 24-hour format

Time Zone

Specifies the time zone:

Default

Specifies the default time zone of GMT -5 Eastern (US, Canada)

Selected

Displays a list field that lets the end user select another time zone

6. Click Generate.




How You Can Use a Digital Clock Field

When users run the frame containing the digital clock field, it appears displaying the current time. The clock operates automatically and updates its display every minute or second, as specified. An example of a 12-hour clock display follows:

The following illustration of a digital clock displays the 24-hour format:

Setting Alarms

If the Enable Alarms feature is chosen when the digital clock is created, the user can set alarms or switch between 12- and 24-hour format by first clicking the clock. This displays the Timer Options dialog.

In the Timer Options dialog, the user can set one or more alarms. The control button provides several functions including inserting a row, deleting the current row or deleting all rows. These functions are provided in a table field frame (for more information, see the description in Use a Table Field Frame (see page 322)).

Alarm Time

In the Time entry field, the user enters the time the alarm will be activated (for example, 12:00). When the 12 Hour option is in effect, the time entered should include AM or PM. If the 24 Hour option is in effect, AM or PM is not needed.

The clock format (12-hour or 24-hour) can be changed if alarms are enabled. You can switch from one mode to the other by selecting the appropriate radio button.

Memo/Event Field

Used to specify a description of the alarm event

Alarm Status

When the Status box is checked, the selected alarm is set.

When an alarm is set, a bell icon appears at the right edge of the digital clock field as an indicator. Alarms are active only while the frame containing the digital clock is running.

Alarm Messages

When an alarm is triggered, a message box appears containing the message associated with the alarm.



The timekeeping, display, and alarm functions of the digital_clock field are handled by the Timer_Manager user class, along with a number of private user classes. For more information on the Timer_Manager class, see the appendix “Generated User Classes” in the Language Reference Guide.

The elapsed_timer Field Template

The elapsed_timer field template provides an elapsed timer that displays elapsed time in digital (hh:mm) format.

Note: Only one elapsed timer should be entered into a frame. Multiple elapsed timers within a frame do not function properly.

Create an Elapsed Timer Field

You can create an elapsed timer field using the elapsed_timer field template in the Frame Editor.

To create an elapsed timer field




3. Select the core application and the elapsed_timer template, and then click OK.


The Elapsed Timer Assistant appears.


Timer Update Interval (in seconds)

Specifies the amount of time between updates of the elapsed timer

Display Seconds

Specifies that seconds are displayed in the elapsed timer

6. Click Generate.


How an Elapsed Timer Field Works

When the frame containing the elapsed timer field is executed, the field appears as follows—displaying hours, minutes, and seconds (if specified) elapsed:



Timekeeping starts when the timer's frame is executed and continues until the running frame is closed. The timer operates automatically and updates its display at a specified frequency.

The timekeeping, display, and alarm functions of the elapsed_timer field are handled by the Timer_Manager user class, along with a number of private user classes. For more information on the Timer_Manager class, see the appendix “Generated User Classes” in the Language Reference Guide.

The float_field Field Template

The float_field field template is used to create an entry field of the type float.

Create a Float Field

You can create a float field using the float_field template in the Frame Editor.

To create a float field




3. Select the core application and the float_field template, and then click OK.


The field is created and displayed in the Frame Editor.

How You Can Use a Float Field

When you run the frame, an entry field appears, containing a value of type float, with a default value of 0.000:

You can enter any valid number such as 1.345 or 1.2E300. The field accepts only valid float values from -1.0E308 to 1.0E308.

The gauge Field Template

The gauge field template is used to create a thermometer-style bar gauge that can be used to monitor progress, resource levels, or other numeric data in your application. You have full control over the size, orientation, labeling, and range of the gauge. The value of the gauge is normally set and updated at runtime.



Create a Gauge Field

You can create a gauge field using the gauge field template in the Frame Editor.

To create a gauge field




3. Select the core application and the gauge template, and then click OK.


The Gauge Assistant appears.


Minimum

Specifies the lowest value in the gauge field

Initial

Specifies the initial value in the gauge field

Maximum

Specifies the highest value in the gauge field

Number of Divisions

Specifies the number of divisions in the gauge field. You can select between five, eight, or ten.

Default: Ten

Auto Range

Specifies that the end points of the gauge field will be adjusted automatically if the values exceed the specified minimum or maximum values

Direction of Indicator Movement

Specifies the desired direction of movement (minimum to maximum value) of the gauge

Edge to Place Ticks

Specifies the location of the tick marks on the gauge

High

Causes a high mark to be drawn on the gauge, indicating the highest value received since the frame began running



Low

Causes a low mark to be drawn on the gauge, indicating the lowest value received since the frame began running

Alarms

Specifies that messages are sent to the user if the gauge values meet preset conditions. A control appears in the Assistant window that lets you set the conditions, test values, and messages.

6. Click Generate.


How You Can Customize a Gauge Field

At runtime, the value of the gauge is initialized to its minimum value. To update the current value of the gauge as your frame executes, call the UpdateGaugeValue method for the field. For example:

declare PercentComplete = float; enddeclare { PercentComplete = RowsProcessed / TotalRows; MyGauge.UpdateGaugeValue(value = PercentComplete); }

How a Gauge Field Works

The value of the gauge is normally set and updated at runtime. An example of a gauge field that uses the default parameters in the Gauge Assistant dialog appears as follows:

The actual processing for the gauge field is handled by the Indicator_Manager user class, which in turn relies on additional private user classes to assist in gauge layout and drawing. For more information on the Indicator_Manager class, see the appendix “Generated User Classes” in the Language Reference Guide.



The integer_field Field Template

The integer_field field template is used to create an entry field of the type integer.

Create an Integer Field

You can create an integer field using the integer_field template in the Frame Editor.

To create an integer field




3. Select the core application and the integer_field template, and then click OK.



How You Can Use an Integer Field

When you run the frame, an entry field appears containing a value of type integer, with a default value of 0:

The field accepts numeric characters, and the plus (+) and minus (-) signs. The field accepts only valid integers in the range -2147483648 to 2147483647.

The line_graph Field Template

The line_graph field template creates a line graph that displays data from one to three data sets in a standard line graph format. The content of the graph is determined completely through the Graph Assistant that serves both the bar_graph and line_graph field templates.



Create a Line Graph

You can create a line graph field using the line_graph field template in the Frame Editor.

To create a line graph field




3. Select the core application and the line_graph template, and then click OK.

4. Click the cursor on the frame where you want to anchor the upper left corner of the graph.

Note: The line graph field is large compared to most frame fields. You should allow generous distances between it and adjacent fields.

The Graph Assistant appears.

5. Complete the dialog using the information provided in Create a Bar Graph Field (see page 346).

6. Click Generate.

After the graph is created, it is displayed in the Frame Editor as various components within a subform.

For more information on how to make changes to the generated graph, see How You Can Edit a Bar Graph Field (see page 349).

How a Line Graph Field Is Displayed

Upon executing the frame containing your line graph field, the field displays the data named in the Graph Assistant.

The meter Field Template

The meter field template is used to create a semicircular meter that resembles an automobile speedometer. A meter field can be used to monitor resource levels or other numeric data in your application. A meter field can be used to monitor resource levels or other numeric data in your application.



Create a Meter Field

You can create a meter field using the meter field template in the Frame Editor. When you create the meter, you can specify its size, orientation, divisions, minimum and maximum values, and the direction in which the indicator should move.

To create a meter field




3. Select the core application and the meter template, and then click OK.


The Meter Assistant appears.


Minimum

Specifies the lowest value in the meter field

Initial

Specifies the initial value in the meter field

Maximum

Specifies the highest value in the meter field

Number of Divisions

Specifies the number of divisions on the dial in the meter field. You can choose between eight or ten.

Default: Ten

Auto Range

Specifies that the endpoints of the meter will be adjusted automatically if the values exceed the specified minimum or maximum values

Clockwise/Counterclockwise

Specifies the direction of rotation (minimum to maximum value) of the meter

Orientation of Meter

Specifies the direction to which the midpoint of the meter points



High

Causes a high mark to be drawn on the meter, indicating the highest value received since the frame began running

Low

Causes a low mark to be drawn on the meter, indicating the lowest value received since the frame began running

Alarms

Specifies that messages are sent to the user if the meter values meet preset conditions. A control appears in the Assistant window that lets you set the conditions, test values, and messages.

6. Click Generate.


How You Can Customize a Meter Field

At runtime, the value of the meter is initialized to its initial value. To update the current value of the meter as your frame executes, call the UpdateGaugeValue method for the field. For example:

declare PercentComplete = float; enddeclare { PercentComplete = RowsProcessed / TotalRows; MyGauge.UpdateGaugeValue(value = PercentComplete); }

How a Meter Field Works

The value of the meter is normally set and updated at runtime. An example of a meter field that uses the default parameters in the Meter Assistant dialog appears as follows:



The actual processing for the meter field is handled by the Indicator_Manager user class, which in turn relies on additional private user classes to assist in gauge layout and drawing. For more information on the Indicator_Manager class, see the appendix “Generated User Classes” in the Language Reference Guide.

The money_field Field Template

The money_field field template is used to create an entry field of the type money.

Create a Money Field

You can create a money field using the money_field template in the Frame Editor.

To create a money field




3. Select the core application and the money_field template, and then click OK.



How a Money Field Works

When you run the frame, an entry field appears, containing a value of type money, with a default value of $0.00:

The field accepts only valid money data in the range -999999999999.99 to 999999999999.99.

The smallint_field Field Template

The smallint_field field template is used to create an entry field of the type smallint.



Creating a Smallint Field

You can create a smallint field using the smallint_field template in the Frame Editor.

To create a smallint field




3. Select the core application and the smallint_field template, and then click OK.



How a SmallInt Field Works

When you run the frame, an entry field appears, containing a value of type smallint, with a default value of 0:

The field accepts up to 5 numeric characters and the plus (+) and minus (-) signs. The field accepts only valid integers from -32768 to 32767.

The spin_control Field Template

The spin_control field template is used to create a control consisting of an entry field and up and down buttons that increment or decrement the value displayed in the field. A spin control can contain integer, float, money, date, or varchar data. In the case of a varchar field, the individual values come from a ChoiceList that can be built automatically or that you can provide.

When you create a spin control, you can set its minimum and maximum values, the increment value to add or subtract when the up or down button is clicked, and a flag indicating whether you want the field to wrap between its minimum and maximum values when either limit is reached. For date fields, the increment can be specified in date units (such as months). For other data types, the increment should be a numeric value.

When you are designing the field, you can further customize the entry field by modifying the display format of the entry field based on the data type.



Create a Spin Control Field

You can create a spin control field using the Frame Editor.

To create a spin control field




3. Select the core application and the spin_control template, and then click OK.


The Spin Control Assistant appears.


Spin Control Type

Specifies the type of spin control:

Integer

Float

Date

Money

ChoiceList (varchar)

Depending on the type of spin control selected, different controls appear in the Spin Control Assistant. For more information, see How You Can Specify Spin Control Values (see page 368).

Wrap Value

Specifies whether the value wraps:

Enabled

Specifies that when the specified maximum value is reached, it wraps to the minimum value and vice versa

Disabled

Specifies that the value stops incrementing or decrementing

6. Click Generate.




How You Can Specify Spin Control Values

There are five different types of spin controls that you can choose:

Integer

Float

Money

Date

ChoiceList (varchar)

For the first four types, the following fields appear in the Assistant window:

Initial Value

Specifies the value that is initially displayed in the field

Minimum Value

Specifies the lowest value that is displayed in the field

Maximum Value

Specifies the highest value that is displayed in the field

Increment Value

Specifies the amount that the value is incremented or decremented when the user clicks the up or down arrow button

The ChoiceList type automatically makes use of the Standard List 4GL procedure. (For more information, see the StdList function in the Language Reference Guide.) If you select ChoiceList as the Spin Control Type, the following choices are available:

List Type

Specifies the type of list to be created:

Weekdays

Lists weekday names (1–7, Sunday to Saturday)

Months

Lists month names (1–12, January to December)

States

Uses a predefined list of U.S. states (1–50, Alabama to Wyoming)



Query

Lists unique values from a specified table and column (row 1 through n, the maximum number of rows). When this option is chosen, the following fields appear:

Table Name

Specifies the variable name for the table to be used

Column Name

Specifies the variable name for the column to be used

Custom Name

Lists your own list of values

Note: When you use this option, take care that the list you provide is valid. Its values must be of the varchar data type and must be unique.

List Name

Specifies a variable name for the list

Initial Value

Specifies the index value of the initial selection in the list

How a Spin Control Field Works

When the frame containing the spin control is executed, the field appears, containing a specified initial (default) value. For example, the default values in the Spin Control Assistant dialog produces the following:

A user can type a new value into the entry field portion of the spin control, or use the increment or decrement buttons to change the value. If a valid value is typed, it is verified the next time the increment or decrement button is clicked, and “clipped” to the limits defined for the field if it is out of range. If the value entered is valid, the buttons increment or decrement it normally.

Another example of a generated spin control field, using the Weekdays choice list (ChoiceList Spin Control Type option), follows:

The functionality of the spin control is based on the Spin_Object user class, which handles its processing. For more information on the Spin_Object user class, see the appendix “Generated User Classes” in the Language Reference Guide.



The stopwatch_control Field Template

The stop_watch field template creates a stopwatch that shows the length of time since the timer's activation. The timer is updated at predetermined intervals. The display format is hours and minutes by default, but you can also display seconds.

Create a Stop Watch Field

You can create a stopwatch field using the stopwatch_field template in the Frame Editor.

To create a stopwatch field




3. Select the core application and the stop_watch template, and then click OK.


The Stop Watch Assistant appears.


Timer Update Interval (in seconds)

Specifies the amount of time (in seconds) after which the stopwatch display is updated

Display Seconds

Specifies that seconds are displayed in the stopwatch field

6. Click Generate.


How a Stop Watch Field Works

When the frame containing the stopwatch field is executed, the field appears containing a default value of 00:00. For example, the default values in the Stop Watch Assistant dialog produce the following:

To start the stopwatch, click Go. The button display then reads “Stop.” The time display is updated at the specified intervals. To stop the stopwatch, click Stop.



The timezone_control Field Template

The timezone_control field template creates a time zone field that displays a list of time zones.

Create a Time Zone Field

You can create a time zone field using the timezone_control field template in the Frame Editor.

To create a time zone field




3. Select the core application and the timezone_control template, and then click OK.



How a Time Zone Field Works

When the frame containing the time zone field is executed, the field appears with the Default option selected—which applies to the GMT time zone:

When the Selected option is chosen, the time zone list field then appears:

You can use the list field that appears to select the desired time zone.

The edit_control Field Template

The edit_control field template generates a self-contained text editor with support for File and Edit operations. It is used by the text_editor frame template and can also be included as a component of other frames.



Create an Edit Control Field

You can create an edit control field using the edit_control field template in the Frame Editor.

To create an edit control field




3. Select the misc application and the edit_control template, and then click OK.



How an Edit Control Field Works

When the frame containing the edit control field is executed, the field appears with a multiline entry field and a scroll bar:

Text may be entered into the scrollable edit control. However, the menus, toolbar, and other controls to trigger the functions usually found on the File and Edit menus in a typical frame must be provided by the frame.

All edit control functionality is provided by the companion Edit_Object user class. An edit object is automatically created and initialized by the field at runtime. Initialization is handled by a call to the edit object's Setup method, passing to it the required EditFrame and EditField attributes. For more information about the Edit_Object class, see the appendix “Generated User Classes” in the Language Reference Guide.



The query_bar Field Template

The query_bar field template provides a standard toolbar for automatically browsing and filtering the results of a QueryObject retrieval. The query bar contains component toolbar segments for browsing through retrieved records, modifying their sort order, and applying further selection criteria to narrow the result set.

Create a Query Bar

You can create a query bar using the query_bar field template in the Frame Editor.

To create a query bar field




3. Select the misc application and the query_bar template, and then click OK.



5. Resize the field and set its field properties, if necessary.

How You Can Develop a Query Bar

The query bar field manages the toolbar display area, provides a toolbar background, and handles sizing, but does not perform any actual query processing. All database and query support is handled by its component toolbar segments.

Toolbar Segments

The field templates that generate the toolbar segments of the query bar are shown in the following illustration:



These individual toolbar segments are placed in a “tools” stack field, which is the only child of the query bar field. Segments can be added, removed, or hidden as required by an application, although in most cases you will want to use the default query bar content.

Sizing and Positioning the Query Bar

By default, the query bar is sized to the width and height of its components (based on the size of its “tools” stack field) and can be placed anywhere in the frame. Typically, however, the query bar is anchored at the upper left corner of its frame and should be sized to match the frame's width. To accomplish this, you must add event-handling code to your query bar frame's script:

on WindowVisible = begin /* Position the field and set initial size */ Field(querybar).XLeft = 0; Field(querybar).YTop = 0; Field(querybar).Width = CurFrame.WindowWidth; End on WindowResized = begin Field(querybar).Width = CurFrame.WindowWidth; end

Handling Query Processing

The processing for all these segments is handled by a single Query_Control user class, which interfaces with your QueryObject. You must declare a query control in your frame's script. For more information about the Query_Control user class, see the appendix “Generated User Classes” in the Language Reference Guide.

The query control is designed for use with a composite field containing a set of simple fields that correspond to the columns in a database table. You can build this composite field by clicking Insert, Fields from Database Table in the Frame Editor, or you can construct it manually, ensuring that the name and data type of each component field match the corresponding column you want to retrieve from the table.



You must also create a QueryObject in your frame script that defines the base query on which the query control will operate. Initialize the QueryObject with the table and column names you want to retrieve, with optional sort order and where clauses. The query control uses these settings to retrieve an initial result set, and augments your default settings with the user's query bar choices.

To associate the query bar, query control, and QueryObject with one another, call the query control's Setup method, passing its references to the QueryObject and query bar:

status = QueryControl.Setup(querytarget = queryobject, querybar = field(querybar));

Then, call the query control's OpenQuery method to begin processing:

status = QueryControl.OpenQuery(querymode = QY_CACHE, queryscope = CurFrame.Scope, checkcols = TRUE);

Note: The query bar and query control support only read access to the database. Update, insert, and delete operations are not supported. The querymode should set QY_CACHE to enable the full set of browser capabilities.

After you call OpenQuery, all further processing is handled by the query control, based on the user's choices in the query bar. No additional programming is required.

For a complete example of a frame script to create and initialize a QueryObject and run it using a query bar and query control, see the appendix “Generated User Classes” in the Language Reference Guide.

Terminating Query Processing

You should also include handlers for the WindowClose event and for any buttons or menu items that could close the frame to terminate query processing when exiting. For example:

on Click menu.file.close, on WindowClose = beginqc.CloseQuery(); end

How a Query Bar Works

When the frame containing the query bar is executed, it appears as follows:



Browsing Records

The browse bar consists of four VCR-style buttons for moving to the first, previous, next, or last record of the result set. When the user clicks a button, the browse bar notifies the query control, which then moves to the proper record and displays it.

Sorting Records

The sort bar lets the user reorder the records in the result set. It contains an option field that lists all columns in the QueryObject, from which the user can choose a column to sort (initially, the order is Default).

After the user selects a column, the adjacent option field is used to select ascending (Up) or descending (Down) order. If you defined a default sort order when building your query object, the OrderBy column you specified is added to the user's selection as a secondary sort field. Only the first OrderBy column in the query object is used.

The new sort order is not applied until the user clicks the Go button, so the user can also change selection criteria before retrieving the new results.

Selecting Criteria

The criteria bar lets the user apply additional selection criteria to a result set. It contains an option field that lists all columns in the QueryObject and lets the user select a column to filter (by default, the selection is All Records).

After the user has selected a column, a second option field—populated with the list of available comparison operators for that data type—is used. The user can select a comparison operator from the list, and then enter a comparison value into an adjacent entry field. For example, a user might enter "cacctbal > 25" to restrict the query to customers whose account balance is greater than $25.00.

The selection criteria are not applied until the user clicks Go. Any sort order changes the user makes are also applied at that point. Any criteria you defined when creating the query object are added to the user's specification so that the original result set cannot be extended.

How a Query Is Executed

Clicking the Go button re-executes a query with the user's current selection criteria and sort order choices. The first record in the new result set is displayed; the user can then browse through the results using the browse bar.

The tabbed_dialog Field Template

The tabbed_dialog field template is used to provide the overall layout and page-switching functionality of a tabbed dialog and can be used as a starting point for developing a multi-paged dialog.



Create a Tabbed Dialog

You can create a tabbed dialog using the tabbed_dialog field template in the Frame Editor.

To create a tabbed dialog




3. Select the misc application and the tabbed_dialog template, and then click OK.


The Tabbed Dialog Assistant appears.

5. In the Number of Pages field, enter the number of pages to be included in the tabbed dialog.

Default: 2

Limits: 6 maximum

6. Click Generate.


You can place other control fields on each of the pages of the tabbed dialog, as desired. You can also change the title of the pages by modifying the property of the corresponding box trim.

How a Tabbed Dialog Works

At runtime, the user can switch between different display sheets by clicking the tab above the displayed page. The currently selected tab is highlighted to indicate its selected state.

After you have created a tabbed dialog, you can continue to place other control fields on each of its pages and make any necessary modifications to the field.

Creating and Modifying Menus 379

Chapter 10: Creating and Modifying Menus


Start the Menu Editor (see page 380) Types of Menu Items (see page 381) Create a Menu (see page 383) How You Can Create Menu Items (see page 385) Common Menu Properties (see page 393)

You can create a menu bar for any OpenROAD Workbench frame. A menu bar contains a set of pull-down menus available on the frame. A pull-down menu is a list of menu items from which the user makes a selection. Menu items each provide an operation (or command) by which the user communicates with the frame. Menu items are also called menu buttons.

You can provide 4GL code for a menu item—called a menu field script—to specify the operation that is performed when a user selects the menu item. For example, when the end user clicks File, Close in a frame, the program performs cleanup operations and closes the frame.

You use the Menu Editor to create pull-down menus for a frame. You can view and change the appearance of the menu as you are designing it. For each pull-down menu and menu item, you can specify their position, properties, appearance, and frame modes and biases.

Note: You cannot create toolbar menus with the Menu Editor. For information about creating toolbars that are associated with a frame's menu structure, see Creating Toolbars (see page 399).

Start the Menu Editor


Start the Menu Editor

In OpenROAD Workbench, menus and frames are integrally bound together. In fact, you can access the Menu Editor only from the Frame Editor.

To open the Menu Editor

1. Open the frame for which you want to create a menu (see Open an Existing Frame (see page 111)).

2. Click Tools, Menu on the Frame Editor's floating menu bar.

The Menu Editor appears.

For a labeled illustration of the Menu Editor interface, see Menu Editor Workspace (see page 380).

Menu Editor Workspace

You access the Menu Editor from the Frame Editor. The following shows the Menu Editor interface:

The Menu Editor workspace contains the following areas, in addition to its own menu bar:

Tool palette

Contains icons of Menu Editor menu items. You can add menu items to the menu you are designing by clicking the corresponding icon and then selecting where you want to add it.

For more information about the tool palette, see Menu Editor Tool Palette (see page 382).

Types of Menu Items


Menu layout area

Contains the simulated menu bar. This area is where you design your menu. While displayed in the Menu Editor, the menu bar is a simulation of the menu bar in the running frame.

Status bar

Displays error messages and helpful information

Types of Menu Items

There are a variety of menu items that you can create in Workbench, each serving a different functional purpose. The following menu bars from the Frame Editor illustrate the different types of menu items:

Types of Menu Items


A summary of these menu items follows:

Slide-off menu

Is a submenu composed of other menu items (for example, Select, Frame Style, and Convert To on the Edit pull-down menu)

Menu separator

Is a divider line that separates menu items into groups. Menu separators are for display purposes only.

Menu button (menu item)

Displays a word or phrase that users click to execute an operation (for example, any of the editing options such as Cut, Copy, Duplicate, and so on, on the Edit pull-down menu)

Menu toggle

Is an option that users can enable or disable (turn on or off). In the previous example, all the menu items on the View pull-down menu are menu toggles; however, only Field Palette and Property Inspector are enabled by default.

Menu list

Displays a set of options from which the user can make one selection. In the previous example, the Frame Style slide-off menu presents a menu list of field style options, with Field Style 1 selected by default.

Menu Editor Tool Palette

The Menu Editor provides a tool palette of icons that you can use to add the various menu items to your menu and the necessary tools for manipulating them, including:

An icon for each type of menu item that you can create

The Select Mode icon to select menu items

For more information on Select Mode, see How Select Mode Works (see page 383).

The Menu Editor's tool palette contains the following icons:

Create a Menu


How Select Mode Works

In Select Mode, you can select an individual menu item or a group of menu items to manipulate. You select and edit menu items in the same way that you work with fields. The following is the Select Mode icon on the Menu Editor's tool palette:

For more information about techniques for positioning and manipulating fields, see Position Fields (see page 155) and Select a Field (see page 136).

Create a Menu

You can create a menu using the Menu Editor, which you access from the Frame Editor.

For more information on opening the Menu Editor, see Start the Menu Editor (see page 380).

To create and modify menu bars



2. Lay out the menu bar and pull-down menus.

3. Set the properties for the pull-down menus and individual menu items using the Property Inspector, and then write scripts for all of them.

For complete descriptions of each menu item property, see the corresponding sections in this section, as well as Common Menu Properties (see page 393).

4. Click File, Close to exit the Menu Editor.

The working copy of the menu bar is saved and you are returned to the Frame Editor, where the actual menu for the frame being created or edited is displayed.

5. Click File, Save and Close to save the frame with its menu.

The following sections describe how to accomplish these tasks in more detail.

Create a Menu


How You Can Edit and Convert Menu Items

The Menu Editor's Edit menu contains commands that let you cut, copy, paste, duplicate, and delete menu items. Use these operations the same way you use them to modify fields on the form. You can cut or copy menu items from one menu and paste them into another.

The Edit, Convert To command lets you change menu items into buttons, toggles, or lists. You can select any combination of button, toggles, and lists, and then select one of the Convert To submenu commands. All the menu items that you selected are converted to the specified menu component.

Note: You cannot convert slide-off menus into any other type of menu item.

Create Scripts for Menu Items

You can include the event blocks for your menu items in the frame script, or you can create separate scripts for the individual menu items. For information about the available events for specific menu items, see the Language Reference Guide.

To create a script for an individual menu item

Select the item in the Menu Editor and then click Edit, Field Script.

For more information about using the Script Editor to write your scripts, see Writing Scripts and Procedures (see page 435).

How Menu Items and Variables Work

As with fields, each menu item can be associated with a 4GL variable. The menu item displays information to the user, and the variable associated with the menu item can be used by your application to set or return a value for that menu item process.

Workbench creates the corresponding variable for a menu or menu item when you enter a variable name in the Property Inspector. In your 4GL code, you can access the menu field only through its corresponding variable.

For more information about using menu item variables in your 4GL scripts, see the MenuField class section in the Language Reference Guide.

How You Can Create Menu Items



The following sections describe the various types of menu items, how to create them, and the properties that you can set for each type.

Note: Menu items that you add are not automatically functional. For more information about adding functionality to your menu items, see Writing Scripts and Procedures (see page 435).

Pull-down and Slide-off Menus

Pull-down (see page 671) and slide-off menus (see page 673) consist of a menu button that, when selected, displays a submenu of items. These items can be of any menu type, including another pull-down or slide-off menu.

Note: You cannot place a slide-off menu directly on the menu bar. All menu bar buttons must be pull-down menus to display the menu below the menu bar.

Create a Pull-down Menu

You can create a pull-down menu using the Menu Editor, which you access from the Frame Editor.

To create a pull-down menu



2. Click Insert, Pull-down/Slide-off Menu.



3. Click in the layout area.

For all new frames except those created with the menu template, Workbench automatically places the pull-down menu in the upper left corner of the form.

If, however, a frame is created with the menu template, Workbench provides a default File menu, as noted previously. Click the default File menu button to add a new pull-down menu, as shown in the following illustration:

In either case, Workbench inserts a pull-down menu, with a default label of “Pull-down,” and a single menu button, with a default label of “Button.”

4. Select the pull-down menu and use the Property Inspector to change the Name property to file and the TextLabel property to &File.

The default field name, “fieldn,” is replaced by “menu.file” in the Field List. Dot notation is used in 4GL code to reference submenu items on a pull-down or slide-off menu.

Note: The “&” can be used in the creation of speed keys. If you do not want to use speed keys with this menu item, enter only File for the TextLabel property. For more information on assigning speed keys, see How You Can Assign Speed Keys (see page 396).

5. (Optional) Specify other properties for the pull-down menu.

Note: For complete descriptions of each pull-down menu property, see Pull-down and Slide-off Menu Properties (see page 389) and Common Menu Properties (see page 393).

6. Select the default button, “Button.”

The Property Inspector changes focus.

7. Use the Property Inspector to change the Name property to save and the TextLabel property to &Save.



8. (Optional) Specify other properties for the menu button.

Note: For complete descriptions of each menu button property, see Menu Button Properties (see page 390) and Common Menu Properties (see page 393).

9. Close the Menu Editor.

10. Save your changes by clicking File, Save in the Frame Editor.

Create a Slide-off Menu

Slide-off menus work much like pull-down menus, except slide-off menus appear to the side of the menu button, instead of below it. You can create a slide-off menu using the Menu Editor, which you access from the Frame Editor.

Note: If you have no buttons on your menu bar, first add a pull-down menu button. For more information, see Create a Pull-down Menu (see page 385).

To create a slide-off menu



2. Add a pull-down menu in the layout area, as explained in Create a Pull-down Menu (see page 385).

3. Click Insert, Pull-down/Slide-off Menu.



4. Click at the top of the default menu button, “Button,” to insert a slide-off menu between it and the pull-down menu, “Pull-down.”

Note: When you are inserting a new menu item, if you click the lower part of an existing menu item, the new item is inserted below the existing menu item. However, if you click the upper part of an existing menu item, the new item is inserted above the existing menu item.

Workbench creates a default slide-off menu, with a default label of “Slide-off,” and one menu button for the first item in the submenu, as shown here:

Note: You can add additional items to the submenu, as you will see in other examples.

5. Select the slide-off menu and use the Property Inspector to set its properties, such as Name and TextLabel.

Note: For complete descriptions of each slide-off menu property, see Common Menu Properties (see page 393).

6. Add menu buttons, toggles, or lists on the pull-down menu.

For information, see:

Create Menu Buttons (see page 389)

Create a Menu Toggle (see page 390)

Create a Menu List (see page 392)

7. Use the Property Inspector to set each menu item's properties, including FocusBehavior, Name, SpeedKey, and TextLabel.

Note: For complete descriptions of each menu item property, see the corresponding sections in this chapter, as well as Common Menu Properties (see page 393).





Pull-down and Slide-off Menu Properties

Pull-down and slide-off menus have properties that are common to all menus and menu items. Therefore, all of the properties for pull-down menus and slide-off menus are described in Common Menu Properties (see page 393).

Create Menu Buttons

A menu button is a menu item that displays a word or phrase that the user can click to initiate an operation. You can specify the label for the button in the Menu Editor using the Property Inspector. The following example procedure details how to add a Close button to a menu.

To add a menu button to a menu

1. Click Insert, Menu Button in the Menu Editor.

2. Click the bottom of the text label of the Save menu button.

The Menu Editor inserts a generic menu button on the submenu.

3. Select the menu button and use the Property Inspector to change the Name property to close and the TextLabel property to &Close.

4. Click the SpeedKey property, and then select SK_CLOSE from its option field:



5. (Optional) Specify other properties for the menu button.

Note: For complete descriptions of each menu button property, see Menu Button Properties (see page 390) and Common Menu Properties (see page 393).



Menu Button Properties

All the properties for menu buttons are described under Common Menu Properties (see page 393), with the exception of the SpeedKey property, which is specific to this type of menu item.

SpeedKey

Lets you specify predefined keyboard combinations for common menu buttons, including Cut, Copy, Paste, Find, Help, Quit, and Save, as well as common table field option menu commands like Delete Row and Insert Row. These Alt speed keys have the same effect as selecting the menu button.

Note: For more information about speed keys, see How You Can Assign Speed Keys (see page 396).

Create a Menu Toggle

A menu toggle displays an option that the user can enable (turn on) or disable (turn off). Each time the user clicks the toggle, the status of the option switches. You must provide a label for the toggle, whether you use different labels for the on and off states, or one label for both.

The variable for a toggle is always of type integer. It can have the following values:

Enabled: 1

Disabled: 0

You can create a menu toggle using the Menu Editor.



To add a menu toggle to a menu

1. Click Insert, Menu Toggle in the Menu Editor.

2. Click at the bottom of the menu button in the slide-off menu.

The Menu Editor inserts a generic menu toggle:

Note: The HasIndicator property in the Property Inspector is automatically set to TRUE.

3. Select the menu toggle and use the Property Inspector to set its other properties, including Name, OffTextLabel, and OnTextLabel.

Note: For complete descriptions of each menu toggle property, see Menu Toggle Properties (see page 391) and Common Menu Properties (see page 393).

Menu Toggle Properties

All the properties for menu toggles are described under Common Menu Properties (see page 393), with the exception of the following properties or values that are specific to this type of menu item:

OffText Label

Specifies the text displayed when the toggle is disabled. When OnTextLabel is not specified, OpenROAD uses this label for both the on and off states indicating the enabled state with a checkmark.

OnText Label

Specifies the text displayed when the toggle is enabled



Create a Menu List

A menu list displays a series of options from which a user can make one selection. To select an option, the user clicks the corresponding item.

You specify the items for the list using the Value List dialog, which you can access from the Property Inspector. Like the choice fields—radio, list, option, and palette fields—you must provide the text entries for the list and an integer value for each text entry.

To add a menu list to a menu

1. Click Insert, Menu List in the Menu Editor.

2. Click at the top of of an existing menu item, if any.

The Menu Editor inserts a generic menu list before the clicked item.

3. With the menu list selected, click the ValueList property in the Property Inspector.


For more information about using this dialog to specify the choices for your menu list, see Add and Delete List Field Items (see page 188).

4. (Optional) Set other menu list properties including Name.

Note: For complete descriptions of each menu list property, see Menu List Properties (see page 392) and Common Menu Properties (see page 393).


6. Click File, Save and Close in the Frame Editor to save your changes.

Menu List Properties

All the properties for menu lists are described under Common Menu Properties (see page 393), with the exception of the ValueList property, which is specific to this type of menu item.

ValueList

Lets you specify the choices—text and corresponding integer values—for the menu list using the Value List dialog. You should specify one value to be displayed as the default value for the list.

Common Menu Properties


Create a Menu Separator

A menu separator is a line divider that separates the individual components of a menu into groups. Menu separators are used for display purposes only. It has no events and its only property is the variable name for the separator.

In your 4GL code, you can use the variable name, in conjunction with the field function, to make the separator visible or invisible to the user.

To add a separator to a menu

1. Click Insert, Menu Separator in the Menu Editor.

2. Click at the top or bottom of an existing menu item, depending on where you want to place the separator.

The Menu Editor inserts a menu separator between the toggle field and menu list.

3. (Optional) Specify the separator's properties using the Property Inspector.

Note: For complete descriptions of each menu separator property, see Common Menu Properties (see page 393).

4. Exit the Menu Editor by clicking File, Close.

5. Click File, Save and Close in the Frame Editor to save your changes.

Menu Separator Properties

Menu separators have properties that are common to all menus and menu items. Therefore, all the properties for menu separators are described in Common Menu Properties (see page 393).


Many of the menu item properties, such as Name and StatusText, are common to all menu items, and others, like BgColor, FgColor, FocusBehavior, and SpeedKey, are common to a majority of them. Therefore, descriptions of these common properties follow in alphabetical order. These descriptions are followed by in-depth discussions of some of the characteristics, including bias and focus behavior, which many of the menu items share.



Properties

Brief descriptions of the common properties follow:

ClientText

Specifies user-definable text that can be stored and accessed at runtime as an attribute of a menu item

FocusBehavior

Determines the effect of selecting a menu item on the field that currently has the input focus; specifically, it determines whether clicking the menu item triggers events for the currently selected field. Valid options are:

FT_SETVALUE FT_TABTO FT_NOSETVALUE FT_TAKEFOCUS

For descriptions of the available focus behaviors, see How You Can Set Focus Behavior (see page 396).

IsNullable

Specifies that the variable is nullable

Name

Specifies the name of the variable associated with the menu item

QueryBias

Specifies the bias setting for the menu item when the CurMode property for the frame is set to FM_QUERY.

For more information, see How You Can Set Menu Item Biases (see page 395).

ReadBias

Specifies the bias setting for the menu item when the CurMode property for the frame is set to FM_READ.

For more information, see How You Can Set Menu Item Biases (see page 395).

StatusText

Specifies the text that appears in the frame's status bar when the cursor is positioned over the menu item and the primary mouse button is clicked

TextLabel

Specifies the title displayed on the menu button

Note: This property is not available for menu separators.



UpdateBias

Specifies the bias setting for the menu item when the CurMode property for the frame is set to FM_UPDATE

User1Bias

Specifies the bias setting for the menu item when the CurMode property for the frame is set to FM_USER1

User2Bias


User3Bias


More information:

How You Can Set Menu Item Biases (see page 395)

How You Can Set Menu Item Biases

For each menu item you create, you can set a bias for each of the six user-definable frame modes (Update, Query, Read, User1, User2, and User3). For more information on frame modes, see Frame Modes (see page 123).

OpenROAD provides the following biases for menu items:

MB_ENABLED

Specifies that the user can select the menu item

MB_DISABLED

Specifies that the menu item is displayed (dimmed) but the user cannot select it or change it.

Note: This option is not available for menu separators.

MB_INVISIBLE

Specifies that the menu item is not displayed

You use the Bias menu to set the biases for a menu item. If you do not set the bias for a menu item, OpenROAD uses a default setting appropriate to the current frame mode.



The menu item biases let you make certain menu items available to the user under different conditions. You can also change the bias of a menu item dynamically at runtime.

For more information about frame modes and biases, see Frame Modes (see page 123).

How You Can Assign Speed Keys

Assigning a speed key to a menu button or menu toggle lets the user press Alt plus a speed key rather than selecting the menu item. For a menu button, pressing the speed key combination executes the command. For a menu toggle, pressing the speed key combination switches the option between the on and off states.

Predefined speed keys can be associated with a menu item by using the Property Inspector to set the SpeedKey property. The physical key mappings for these logical keys are different for each system. To assign your own logical key, select the User key and enter a number from 1 to 36.

For more information, see Speed Key Mapping (see page 631).

How You Can Set Focus Behavior

OpenROAD Workbench lets you control the effect that selecting a menu item has on the previous field on the form (the field previously having the input focus and displaying the text cursor). You control this behavior by setting the Focus Behavior property for each menu item.

The Focus Behavior property can have any of the following values:

FT_SETVALUE

Specifies that clicking this menu item triggers the SetValue event for the current field. However, since the focus remains in that field, there is no Exit field event.

This setting is useful for data validation tasks. For example, you could provide a Save menu item that activates a SetValue event block that validates the data in the field.

When you use this setting, OpenROAD activates the SetValue event for the current field only when the user has changed the data in the field. FT_SETVALUE is the default setting for all menu items.



FT_TABTO

Specifies that clicking this menu item triggers the SetValue and Exit events for the current field. If the current field is part of a composite field, you can use this setting to force validation and ChildExit events for the child fields. When you use this setting, OpenROAD always triggers the Exit event but only triggers the SetValue event if the user has changed data in the current field.

FT_NOSETVALUE

Clicking this menu item does not trigger the SetValue event for the current field. This setting is useful for menu items that do not require any interaction with data, such as Help, or those that do not require data validation, such as Cancel.

FT_TAKEFOCUS

Specifies the same as FT_TABTO.

Default: FT_SETVALUE

For more information about the focus behavior of menu items, see the description of the FocusBehavior attribute in the Language Reference Guide. Also, for information about the SetValue event, see the Language Reference Guide.

Creating Toolbars 399

Chapter 11: Creating Toolbars This section contains the following topics:

Start the Toolbar Editor (see page 399) Types of Toolbar Items (see page 400) Create a Toolbar (see page 402) How You Can Create Toolbar Items (see page 403)

After you create a frame and its menu, you can then create a toolbar for your frame and associate it with the frame's menu structure. A toolbar consists of a set of iconized items from which the user makes a selection by clicking the mouse pointer on it. Toolbar items typically consist of buttons that provide shortcuts for frequently used menu commands or for easy access to other features or frames.

You use the Toolbar Editor to create a toolbar for a frame, and you can change the toolbar's appearance as you are designing it. For each toolbar and toolbar item, you can specify its position, properties, appearance, and frame modes and biases.

Start the Toolbar Editor Like menus, toolbars and frames are integrally bound together. Therefore, you can access the Toolbar Editor only from the OpenROAD Workbench Frame Editor.

To start the Toolbar Editor

1. Open the frame in which you want to create a toolbar (see Open an Existing Frame (see page 111)).

2. Click Tools, Toolbars on the Frame Editor's floating menu bar.

The Toolbar Editor appears.

Types of Toolbar Items


Toolbar Editor Workspace

The following illustrates the Toolbar Editor's workspace:

The Toolbar Editor workspace is quite simple. It contains the following areas, in addition to its own menu bar:

Layout area

Contains the simulated toolbar. This area is where you design your toolbar. While displayed in the Toolbar Editor, the toolbar is a simulation of the toolbar in the running frame.

Status bar

Displays error messages and helpful information


There are a variety of toolbar items that you can create in OpenROAD Workbench, each serving a different functional purpose. All of these toolbar items should be familiar to you already because they are basic OpenROAD fields:

Button Field

Lets the user initiate an operation by clicking it. You can specify text or an image as the label for the button.



Option Field

Appears as a drop-down list of values from which the user can make one selection. Only the current value is displayed. In addition to selecting the current value, the user can click the down arrow to select another value from the drop-down list.

Space

Separates toolbar items for display purposes only

Toggle Field

Appears as an option that the user can click on or off (enable or disable). The label for a toggle can be either text or an image. You can supply one text phrase for both states and use the toggle indicator, or you can turn off the toggle indicator and supply separate phrases or images for the on and off states.

Insert Menu

The Toolbar Editor's Insert menu provides menu commands that you can use to add a toolbar and its various toolbar items to your frame. The Edit menu lets you manipulate them.

Note: The menu commands for toolbar items are grayed until you insert a top, bottom, left, or right toolbar in the layout area of the Toolbar Editor.

Using Select Mode

In Select Mode, you can select an individual toolbar item or a group of toolbar items to manipulate. You select and edit toolbar items in the same way that you work with basic fields.

For more information about techniques for positioning and manipulating fields, see How You Can Select and Position Fields (see page 499).

Create a Toolbar


Create a Toolbar

You can create a toolbar using the Toolbar Editor, which you access from the Frame Editor.

To create a toolbar



2. Insert a top, bottom, left, or right toolbar in the layout area, and then create toolbar items.

3. Set the properties for the toolbar and individual toolbar items using the Property Inspector, and then include 4GL code for handling the toolbar items in the frame script.

Note: The properties for the toolbars and toolbar items are common to other field properties. For complete descriptions of each toolbar property, see Common Field Properties (see page 239).

4. To exit the Toolbar Editor, click File, Close.

The working copy of the toolbar is saved and you are returned to the Frame Editor.

5. Click File, Save and Close in the Frame Editor to save the frame with its toolbar.

More information:

How You Can Create Toolbar Items (see page 403) How You Can Edit Toolbar Items (see page 403)

Scripts for Toolbar Items

You must include event blocks for your toolbar items in the frame script. For more information about the available events for toolbar items, see the Programming Guide.

For more information about using the Script Editor to write your frame scripts, see Writing Scripts and Procedures (see page 435).

How You Can Create Toolbar Items


How You Can Edit Toolbar Items

The Toolbar Editor's Edit menu contains commands that let you cut, copy, paste, and delete toolbar items. Use these operations the same way you use them to modify fields on the form. You can even cut or copy toolbar items from one toolbar and paste them into another. When you close the Toolbar Editor, your changes take effect.

Toolbar Items and Variables

As with fields, each toolbar item can be associated with a 4GL variable. The toolbar item displays information to the user; your application can use the variable associated with the toolbar item to set or return a value for that toolbar item process.

Workbench creates default variable names for toolbars and the fields within the toolbars. The default names have the form fieldn, where n is an integer. You should use the Property Inspector to assign more meaningful variable names. For example, if a frame has only one toolbar, you might name it “toolbar.” Similarly, a button that is used to close a frame might be named “close_btn.”

For more information about using toolbar item variables in your 4GL scripts, see the Programming Guide.

How You Can Create Toolbar Items The following sections describe the various types of toolbar items, how to create them, and the properties that you can set for each type.

Create a Toolbar

You can use the Workbench Toolbar Editor to create a toolbar for a control frame.

To create a toolbar

1. Open the frame in which you want to create the toolbar in the Frame Editor (see Open an Existing Frame (see page 111)).





3. Click Insert, Insert Top Toolbar in the Tool Editor.

Workbench creates a toolbar with a single button field at the top of the Toolbar Editor's layout area.

4. Select the button field, and then click the BitmapLabel property in the Property Inspector.

A standard Browse dialog appears.

By default, toolbar buttons display a blank, gray bitmap as indicated by the text in the FileHandle field in this dialog. You may replace the default bitmap with another one, or clear the default selection altogether so that you can add an icon or a text label. For instructions to add icons, see Use the Icon Gallery (see page 405).

5. Click Clear and then OK.

The BitmapLabel property's value cell now displays No Bitmap.

6. In the Property Inspector, set any other properties you want.

7. Replace the default field name, fieldn, for the Name property with a unique, descriptive name.

8. Enter a value in the value cell of the TextLabel property.

9. Select the main bar of the toolbar itself.

The Property Inspector changes focus to the main bar.

10. Enter a unique, descriptive name for the toolbar in the value cell of the Name property.

Note: The properties for the main bar of a toolbar are common to other field properties. For complete descriptions of each toolbar property, see Common Field Properties (see page 239).

Create Toolbar Buttons

You can create toolbar buttons using the Toolbar Editor.

To add additional toolbar buttons to a toolbar

1. Click Insert, Button Field in the Toolbar Editor.

2. Place the new button on the frame.

Repeat the first two steps to add more toolbar buttons.

3. Select the blank button, and then specify its properties using the Property Inspector.

Note: For more information about using the OpenROAD color palettes, see Field Colors (see page 164).



4. Enter a button name in the Name property and a label in the TextLabel property for each button you created.

Your changes are reflected in the Toolbar Editor.

Note: For complete descriptions of each field property, see Button Field Properties (see page 179) and Common Field Properties (see page 239).

5. Click File, Close to exit the Toolbar Editor.

You are returned to the Frame Editor. Note that the toolbar is not visible.

6. Click Debug, Go to view the toolbar.

Note: The toolbar you just added is not functional. For more information about adding frame and field scripts, see Writing Scripts and Procedures (see page 435).

7. Click Close in the upper right corner to close the running frame.



Use the Icon Gallery

The Icon Gallery lets you do the following:

Select standard icons for your toolbar buttons

Add a new icon to an existing category in the Icon Gallery

Add new categories, items, and icon images

Note: To access the Icon Gallery, open an existing frame in the Frame Editor or create a new one. Then access the Toolbar Editor and insert, for example, a top toolbar.

To select an icon from the Icon Gallery

1. Click View, Icon Gallery in the Toolbar Editor.

The Icon Gallery frame appears.

The available icons are organized into four categories or tab pages: File, Edit, Listview, and Help.

2. Click the tab for the desired category.

Use the scroll bars on each tab page to view all available icons.



3. Click the icon you want to use.

Tooltip text shows the dimensions of the selected icon in pixels.

4. Drag the highlighted icon to the toolbar field.

When the icon is applied to a toolbar button, the tooltip text is automatically set; for example, if you selected a Paste icon the tooltip text is set to “Paste.”

A category is a tab page in the Icon Gallery, for example, Edit. Icons related to editing are placed in this category.

To create a new category

1. Click File, New Folder in the Icon Gallery.

The New Page dialog appears.

2. Type a name for the category.

The name appears on a new tab in the Icon Gallery.

To add a new image to an existing category (tab page)

1. Select the desired category in the Icon Gallery, and then click Edit, New Item.

The New Item dialog appears.

2. Type a name for the new item.

The new item name appears in the left column of the tab page.

3. Click Edit, Add Icon.

A File Selection dialog appears.

4. Locate and select the desired icon bitmap and click Open.

The Icon Selection dialog displays the available images.

5. Select the desired icon image and click OK.

The bitmap appears in the row with the item name to the left. It can then be dragged to the toolbar.

6. If you want a border around the icon, click the icon, or check Show Icons with Outlines on the Icon Gallery View menu.

An item is the name of the operation you want to have illustrated with an icon, for example, Cut.



To add a new item to a category

1. Select the desired category in the Icon Gallery, and then click Edit, New Item.

The New Item dialog appears.

2. Type the name of the item.

The name of the item appears in the left column of the tab page.

3. Click Edit, Add Icon.

The File Selection dialog appears.

4. Locate and select the desired icon bitmap and click Open.

The Icon Selection dialog appears with the available images displayed.

5. Select the desired icon image and click OK.

The bitmap appears in the row with the item name to the left. It can then be dragged to the toolbar.

6. If you want a border around the icon, click the icon, or check Show Icons with Outlines on the Icon Gallery View menu.

To delete a tab page from the Icon Gallery

Select the category (tab page) you want to delete, and click File, Delete Folder.

To delete an item from the Icon Gallery

Select the item you want to delete, and click Edit, Delete Item.

To delete an icon from the Icon Gallery

Select the icon you want to delete, and click Edit, Delete Highlighted Icon.

Create an Option Field

You can create an option field using the Toolbar Editor.

To create an option field for a toolbar

1. Click Insert, Option Field in the Toolbar Editor.

A typical option field is added to the toolbar.

2. Select the ValueList property in the Property Inspector.




3. For each item in your choice list, tab to the Display column and replace the default text with text of your choice.

For more information about specifying items for a choice field, see Add and Delete List Field Items (see page 188).

4. (Optional) Specify other properties for the option field, including ExactWidth or MinimumWidth, InnerShadowWidth, Style, and VisibleRows.


Create a Toolbar Palette Field

You can create a palette field for a toolbar using the Property Inspector.

To create a palette field for a toolbar

1. Click Insert, Palette Field in the Toolbar Editor.

A palette field is added to the toolbar.

2. Select the palette field, and then select the ValueList property in the Property Inspector.

The Value List dialog appears:

Note: This dialog displays slightly different fields for palette fields than for option fields.

3. Click in the first cell of the Image column.


4. Locate and select an image file and then Click Open.

You are returned to the Value List dialog, and a truncated image is inserted in the first cell of the Image column.

Alternatively, you can now open the icon gallery.

5. Enter a value (for example, 2) in the second cell of the Value column.

6. Repeat the previous steps for subsequent cells in the Image column, if you have other buttons to modify.



7. Click OK.

The palette field now displays one or more buttons with the specified images.

Note: When creating a palette field, keep in mind that its size is determined by its contents. Therefore, 16 x 16 pixel bitmaps are commonly used for toolbar buttons, including palette buttons.

8. (Optional) Specify other properties for the palette field, including Columns and Orientation.

Note: For complete descriptions of each field property, see Palette Field Properties (see page 201) and Common Field Properties (see page 239).

Create a Toggle Field

You can create a toggle field for a toolbar using the Property Inspector.

To create a toggle field for a toolbar

1. Click Insert, Toggle Field in the Toolbar Editor.

A typical toggle field is added to the toolbar.

2. Click the BgColor property and select a background color from one of the palettes.

3. In the OffLabelText property, enter Inactive or other text for the off state.

4. Similarly, in the OnLabelText property, enter Active or other text for the off state.

5. (Optional) Specify other properties for the toggle field, such as HasImageandText and HasIndicator.

Note: For complete descriptions of each field property, see Toggle Properties (see page 206) and Common Field Properties (see page 239).

6. Close the Toolbar Editor by clicking File, Close.


7. Click Debug, Go on the Frame Editor's floating menu bar to test the toggle field.

The toggle field displays the “off” label text, for example, Inactive, in the running frame.

8. Click the toggle.

The default toggle indicator appears in the toggle field and the “on” label text, for example, Active, replaces the Inactive label.



9. Click the Close button in the upper right corner to close the running frame.



Working With Classes 411

Chapter 12: Working With Classes This section contains the following topics:

System Classes (see page 411) User Classes (see page 412) External Classes (see page 413) How You Can Create User Classes (see page 414) Create and Register External Class Libraries (see page 428) Class Browser (see page 432)

A class is a named object definition. Every object in OpenROAD belongs to a class. The class defines the attributes that describe the object and the methods you can use to operate on the object. Classes are similar to records in Pascal or structures in C.

In this chapter, we will examine the three types of classes used by OpenROAD—system classes, user classes, and external classes—and the relationships among them.

System Classes System classes are object definitions that OpenROAD provides. By using OpenROAD system classes and their associated attributes and methods, you can manipulate OpenROAD application components from your scripts and procedures.

The system classes include all OpenROAD Workbench application components, such as frames, forms, menus, field menus, and menu items. In addition, OpenROAD provides system classes that are used for classification only (known as “abstract” or “abstraction” classes in object-oriented programming), such as Object and FieldObject.

The Inheritance Hierarchy

OpenROAD system classes are organized into an inheritance hierarchy. In this hierarchy, a class that is a child of another class is considered its subclass and a class that is the parent of another class is considered its superclass. Each subclass inherits the attributes and methods for all its superclasses.

User Classes


The higher a class's position in the hierarchy, the more generalized the characteristics and functions that it defines. Classes lower in the hierarchy describe objects with specialized characteristics that function in a specific manner. For example, the characteristics and functions defined for the FieldObject system class apply to all fields and menu items, whereas the ButtonField system class defines a very specific object.

The inheritance hierarchy is useful in avoiding redundant definition of functions and characteristics. Attributes and methods are defined at the most general level possible and inherited by all subclasses.

For example, the ButtonField system class is a subclass of ScalarField. The complete list of attributes and methods available for ButtonField includes the attributes defined for ScalarField and its superclasses (ActiveField, FormField, FieldObject, and Object) as well as those defined specifically for ButtonField.

Note: For more information about class relationships and class inheritance, see the chapter “Working with Classes” in the Programming Guide. For more information about a particular class and its associated attributes and methods, see the Language Reference Guide.

User Classes

A user class is a set of developer-defined attributes (characteristics) and methods (behaviors) that you can use to refer to multiple data items as a single entity. You create user classes are classes that you create in the visual development environment as part of an application. A user class is a convenient way to manipulate related data elements as a single object.

When you create a user class, you specify attributes that describe the class and methods that define its behaviors. You can specify another user class as the superclass for a user class, as all classes in OpenROAD are organized into an inheritance hierarchy. The user class then inherits all the attributes and methods of the superclass.

After you create a user class, you can use it when you declare reference or array variables. You also can create a set of simple fields or a composite field that corresponds to the attributes of the user class. If you modify a user class definition, any objects of that class are modified accordingly.

Note: For more information about creating fields based on the attributes of a user class, see Create Fields from a User Class (see page 277).

External Classes


There are two ways you can create a user class in OpenROAD Workbench:

Using the Class Editor

Using the predefined OpenROAD frame and field templates that automatically generate user classes

For more information about creating a user class using the Class Editor, see How You Can Create User Classes (see page 414). For more information about the user classes that are generated from the predefined templates, see the "Generated User Classes" appendix in the Language Reference Guide.

Note: Like many other OpenROAD application components, user classes can also be created dynamically. For more information, see the chapter “Working with Classes” in the Programming Guide.

External Classes As mentioned previously in Create Fields from an External Class (see page 279), OpenROAD supports ActiveX Automation servers and ActiveX controls by treating these components and controls as external classes. An external class provides a named object definition that describes an external object, so that OpenROAD can use it seamlessly.

For example, it allows a spreadsheet, word processor, or other application to be used within an OpenROAD application. It also permits the inclusion of individual external controls—such as charts, grid controls, HTML controls, and web browsers—within an application. OpenROAD provides a container for the external object so that only its functionality is used. For, example, OpenROAD can read data from an external object, such as a Microsoft Excel spreadsheet, and use it in OpenROAD code.

Before you can use an external class in OpenROAD, you must register an external class library component with your application. Then you can declare and use external class objects and view their attributes and methods using the Class Browser. Registration means that OpenROAD wrapper code has been generated for an external object's exported attributes, methods, and events.

Note: For more information about creating external class libraries, see Create and Register External Class Libraries (see page 428). Also, for more information about viewing external class attributes and methods, see Class Browser (see page 432).

How You Can Create User Classes



In OpenROAD Workbench, you can create user classes to structure your organization's data into objects. These objects, with all of their characteristics and behaviors built in directly, can serve as the basis for your applications.

You define, edit, view, and delete user classes in OpenROAD Workbench. Using the Class Editor, you create a user class, define its attributes, and optionally declare and define its methods and superclass.

Create a User Class

You can create a user class using the Create User Class dialog.

To create a user class

1. Select the application in which you want to create the user class in the Applications portlet of the Develop tab.

2. Click the header bar of the Components portlet to make it active.

3. Click File, New, User Class.

The Create User Class dialog appears.

4. Enter the user class name in the Name entry field (for example, My_User_Class).


6. (Optional) Select the Derived toggle field to choose a parent class for your user class.

The Create User Class dialog changes slightly, allowing you to select an application and a parent class, and to choose whether to qualify the superclass.

7. Click Create.

Workbench displays the Class Editor, where you create the individual attributes and methods for the class.

Note: By default, the name of the parent class specified in Step 6 appears in the Superclass option field. If you want to specify a different superclass, proceed to the next step. If, however, the specified superclass is correct or if you want to accept the default system superclass, userobject, proceed to Step 7.



8. If you want, specify a new superclass in either of the following ways:

Select Qualify Superclass Name by selecting the option.

Or follow these steps:

a. In the Superclass field, enter the name of a user class from the current application or any included applications.

b. Click List Classes and select a class from the Select a Class dialog that appears.

c. Click OK.

The name of the user class you selected is displayed in the Superclass field.

9. Create the attributes for the user class (to supplement any attributes inherited from the superclass), as described in Create Attributes for a User Class (see page 415).

10. Create the methods for the user class (to supplement any methods inherited from the superclass), as described in Create Methods for a User Class (see page 421).

11. Save the user class using one of the commands from the Class Editor's File menu.

The user class is added to the Components portlet.

Create Attributes for a User Class

When you define attributes for a user class, you specify:

The name by which they are referenced

A remark describing the attribute (optional)

A data type

A default value (optional)

Nullability

You create attributes for a user class in the Class Editor.

To create attributes for a user class

1. Select the application that contains the user class in the Applications portlet of the Develop tab.

2. Double-click the user class in the Components portlet.

The Class Editor is opened.

3. Click the Attributes tab in the Class Editor.



4. Click Edit, Insert, New.

The Create Attribute dialog appears.

5. Enter a name for the attribute in the Name field (for example, my_attribute).

6. Specify the attribute's data type.

For example, you might select Integer from the Data Type option field.

Note: You cannot create a user class with a name of “int” or “integer.”

7. (Optional) Specify other properties for the attribute, such as Remark, Encapsulation (Private), and Default Value.

Note: The Private option, if selected, specifies that the attribute is private, meaning that it can be accessed only by a method of the current user class or any of its subclasses.

8. Click Create.

The Create Attribute dialog becomes the AttributeProperties dialog.

If you did not specify the properties for the attribute previously, this dialog lets you specify or edit them now.

9. (Optional) Edit the attribute's properties and then click Apply to put your changes into effect.

For descriptions of the properties of user class attributes, see Properties for User Class Attributes (see page 418).

10. (Optional) Create additional attributes by clicking New and using the previous steps in this procedure.

11. Click Close when you are finished creating attributes.

12. Click File, Save and Close to save your changes and close the Class Editor.

You are returned to the Class Editor where Workbench displays the attributes in the Attributes table field.

Create Attributes from a Table

An alternative method for creating attributes for a user class is to create them from a database table.

To create a set of attributes that correspond to the columns of a database table

1. Create a new user class or open an existing one (for example, My_User_Class).

For more information, see Create a User Class (see page 414).




3. Click Edit, Insert, From Database Table.

The Select a Database Table dialog appears.

4. Specify the table or view name in one of the following ways:

Enter the name of a table or view in the database that the application accesses.

Click the control button to the right of the entry field, and select a table from the Table Selection dialog that appears.

Click OK.

The name of the table you selected is displayed in the entry field.

5. Click OK.

Workbench displays the column names and data types on the Attributes tab in the Class Editor.

You can edit or delete any of the attributes as well as create additional attributes of your own.



Properties for User Class Attributes

Descriptions of properties that you can set for a user class attribute follow. User classes themselves have no properties.

Name

Specifies the name of the attribute. This name must be a valid OpenROAD name.







Notes:

You cannot change this property at runtime because 4GL cannot dynamically use different variable names for the same object.

If you create an attribute for a column of a database table, OpenROAD uses the column name as the attribute name by default. You can optionally change this name.

Remark

Specifies a description of the attribute

Encapsulation

If the Private toggle is enabled, specifies that the attribute can be accessed only by a method of the current user class or any of its subclasses

Note: In object-oriented programming, you can limit access to an object's attributes and methods. The process of allowing only the object itself to have access to its attributes and methods is called encapsulation. In OpenROAD, you accomplish this restriction by flagging an attribute or method as private. You can only reference a private attribute or method in the 4GL code of the methods of the defining user class or its subclasses. For more information, see Encapsulating Attributes and Methods in the chapter “Working with Classes” in the Programming Guide.



Type

Specifies the variable type of the attribute:

Simple

Reference

Array

Data Type

Specifies the data type of the attribute for simple type variables only. Valid options are:

Varchar

Integer

Smallint

Float

Decimal

Date

Money

Length

Specifies the maximum number of characters of the attribute for simple type variables and varchar data types only

Nullable

Specifies that a null value is allowed for simple type variables only

Note: If the data type of the attribute is a class, this property is always TRUE.

Class Name

Specifies the name of a system class or another user class in the current application or an included application for reference or array variables only



Default Value

Specifies the default value of the attribute. Valid options are:

System

Provides a system-assigned initial value

Null

Sets the initial value to a null string. (This option is always available for reference and array types, and only available for simple types if you have made the attribute nullable.)

String

Lets you specify a string for the initial value in an adjacent entry field. (This option is available only for simple type attributes.)

Edit an Individual Attribute

You can edit an individual attribute in the Class Editor.

To edit an individual attribute





4. Select the name of the attribute.

5. Click Edit, Properties.

Alternatively, position the mouse cursor on the name of the attribute and click the secondary mouse button.

The AttributeProperties dialog appears.

6. Change any of the attribute's properties as desired.

For descriptions of user class attribute properties, see Properties for User Class Attributes (see page 418).

7. Click Apply and then click Close.

You are returned to the Class Editor.

8. Click File, Save and Close in the Class Editor to save your changes and exit the editor.



Delete an Attribute

You can delete an attribute using the Class Editor.

To delete an attribute





4. Select the name of the attribute.

5. Select the name of the attribute to be deleted.


The attribute is deleted.

Create Methods for a User Class

The data type of an attribute or method can be either a simple data type or a class, including another user class. If a user class is defined as the data type, the user class must exist before you create the attribute or method.

You can create a method for a user class using the Class Editor.

When you define methods for a user class, you specify:

The name by which they are invoked

A data type for the return value (can be nullable)

A remark describing the attribute

To create a method for a user class




3. Click the Methods tab in the Class Editor.

4. Click Edit, Insert, New.

The Create Method dialog appears.

5. Enter a name for the method in the Name field (for example, my_method).



6. Select the Private (Encapsulation) option if you want to specify this method as private, meaning that the method is only accessible to this user class and its subclasses.

7. Specify the return value for the method.

8. Click Create.

The dialog changes to the MethodProperties dialog.

Like the AttributeProperties dialog, this dialog lets you specify or edit a method's properties if you did not do so previously.

For descriptions of the properties of user class methods, see Properties for User Class Methods (see page 423).

Note: You can click the New button to access the Create Method dialog again to create additional methods.

9. Define any other property settings.

10. Click Close.

Workbench displays the method on the Methods tab of the Class Editor.

11. Click File, Save and Close to save your changes to the user class.



Properties for User Class Methods

The following are descriptions of properties that you can set for a user class method:

Name

Specifies the name of the method. This name must be a valid OpenROAD name.







Note: You cannot change this property at runtime because 4GL cannot dynamically use different variable names for the same object.

Remark

Specifies a description of the method

Encapsulation

If the Private option is selected on the Create Method dialog, specifies that the method can be accessed only by a method of the current user class or any of its subclasses.

Note: In object-oriented programming, you can limit access to an object's attributes and methods. The process of allowing only the object itself to have access to its attributes and methods is called encapsulation. In OpenROAD, you accomplish this restriction by flagging an attribute or method as private. You can only reference a private attribute or method in the 4GL code of the methods of the defining user class or its subclasses. For more information, see Encapsulating Attributes and Methods in the chapter “Working with Classes” in the Programming Guide.



Return Value

Specifies the variable type of the method:

None

Simple

Reference

Array

Data Type

Specifies the data type of the method for simple type variables only. Valid options are:

Varchar

Integer

Smallint

Float

Decimal

Date

Money

Length

Specifies the maximum number of characters of the method's return value for simple type variables and varchar data types only

Nullable

Specifies that a null value is allowed for simple type variables only

Class Name

Specifies the name of a system class or another user class in the current application or an included application for reference or array variables only

Write 4GL Code for Your Methods

You define all of a user class's methods in a single 4GL script that is part of the user class source object. Any operations that can be performed syntactically in the 4GL code of a frame or procedure can be done in the 4GL code of a user class method, including invoking another of the class's methods.

The methods created in the script must correspond to methods defined for the user class. (For the syntax for method scripts, see the Language Reference Guide).



To write the 4GL code for your methods

Click Tools, Script in the Class Editor.

Workbench opens the Script Editor (or your system editor) for you to write the code for your methods.

You write one script for all the methods of a user class. Writing one such method script is covered in How You Can Use Attributes and Methods (see page 427).

Edit an Individual Method

You can edit an individual method using the Class Editor.

To edit an individual method




3. Click the Methods tab.

4. Select the name of the method.

5. Click Edit, Properties.

Alternatively, position the mouse cursor on the name of the method and click the secondary mouse button.

The MethodProperties dialog appears.

6. Change any of the method's properties as desired.

For descriptions of user class attribute methods, see Properties for User Class Methods (see page 423).

7. Click Apply and then Close to close the MethodProperties dialog.

8. Click Tools, Script to edit the script for a user class method.

Workbench calls the Script Editor (or your system editor) for you to edit the code for your methods.

9. Click Close to save your script changes and exit the Script Editor when you have finished editing the method.

10. Click File, Save and Close in the Class Editor.



Delete a Method

You can delete a method using the Class Editor.

To delete a method




3. Click the Methods tab.

4. Select the name of the method to be deleted.


The method is deleted.

Edit or View a User Class

You can edit or view a user class using the Class Editor.

To edit or view a user class




3. View or modify the attributes and methods of the class, as described in Create Attributes for a User Class (see page 415) and Create Methods for a User Class (see page 421).

Deleting a User Class

You delete a user class using the Class Editor.

To delete a user class



3. Select the user class in the list of Components.






How You Can Use Attributes and Methods

After you have created your user class, including its attributes and methods, you can relate it to either a frame or another component.

Your application can use the methods and attributes of a user class to process information provided by the application (or the end user or OpenROAD itself), and then take an appropriate action. In the simple example that follows, an error message box is displayed. However, you can use the same principles in creating more complex applications.

To demonstrate some of the concepts in this chapter, follow this example, which uses My_User_Class, one of its attributes, and its method. Note that some steps are abbreviated, since you should already be familiar with how to create or edit basic OpenROAD components.

1. Open My_User_Class or other user class in the Class Editor.

2. Click Tools, Script.

The Script Editor appears, allowing you to define method scripts.

3. Edit the predefined method script as follows:

method my_method ()= declare enddeclare { curmethod.infopopup( messagetext= 'my_method called!', messagetype=MT_ERROR); }

4. Click Close to save your method script changes and exit the Script Editor.

5. Save the My_User_Class user class component.

6. Create a new user frame, My_User_Frame.

7. Click Tools, Script on the Frame Editor's floating menu bar.

The Script Editor appears, allowing you to define the frame's script.

Create and Register External Class Libraries


8. Edit the predefined initialization script as follows:

initialize()= declare v1=My_User_Class enddeclare { v1.my_attribute=123; if v1.my_attribute=123 then v1.my_method(); endif; }

9. Click Close to save your frame script changes and exit the Script Editor.

10. Save My_User_Frame and then run the frame by clicking Debug, Go.

The following Information window should appear:

Note: For more information about writing and editing scripts, see Writing Scripts and Procedures (see page 435). For more information about writing the 4GL code for your own user class methods, see How You Can Write Methods in the chapter “Working with Classes” in the Programming Guide.


Registration means that OpenROAD wrapper code has been generated for an external object's exported attributes, methods, and events. You create and register external class libraries and, by inclusion, all of their external classes. Thereafter, any external class defined in this library can be used in your OpenROAD application. An external class is used in the same way that you would use a system or user class.



Register an External Class Library Component

You can register an external class library component using the External Class Library Editor.

To register and external class library



3. Click File, New, External Class Library.

The Create External Class Library dialog appears.

4. Enter a name in the Name field for the external class library component, for example, WebBrowser.




6. Click Create.

Workbench displays the External Class Library Editor, where you select an external class library (TypeLib) from its TypeLibs tree view.

7. Expand the TypeLibs tree to locate the external class library that contains the desired external object.

For example, select the Microsoft Internet Controls branch.

The vendor's external class library name and ID, as well as its version numbers, default appropriately to the TypeLib, TypeLib ID, Major Version, and Minor Version entry fields.

Note: When you register an external class in an external class library, be aware that a library may have more than one component, so you would have multiple external classes in OpenROAD for that one library. For more information about external classes, see “Working with Classes” in the Programming Guide.



8. Click File, Save and Close in the External Class Library Editor.

Your external class library is added to the list view in the Components portlet for your application.

Your external class libraries let you include some third-party external controls—such as labels, spin buttons, and web browsers—on your forms. To include external controls, in the Frame Editor, click Insert, Field from External Object. For an example, see Create Fields from an External Class (see page 279).

Edit or View an External Class Library

You can edit or view an external class library in the External Class Library Editor.

To edit or view an external class library

1. Select the application that contains the external user class library in the Applications portlet of the Develop tab.

2. Double-click the external user class library in the Components portlet.

The External Class Library Editor is opened.

3. View or modify the properties of the external class library, including Short Remark, TypeLib, Major Version, Minor Version, and TypeLib ID.

4. If you have edited the properties, click File, Save and Close to save your changes and close the External Class Library Editor.

Note: You must use the Class Browser to actually view the attributes and methods of an external class object. For more information, see Class Browser (see page 432).

Delete an External Class

You can delete an external class library in the External Class Library Editor.

To delete an external class library

1. Select the application that contains the external user class in the Applications portlet of the Develop tab.


3. Select the external user class in the list of Components.

Class Browser





Class Browser


Open the Class Browser

You open the Class Browser from the Develop tab of OpenROAD Workbench.

To open the Class Browser

1. Select the application whose classes you want to browse in the Applications portlet of the Develop tab.

2. Click the Class Browser portlet tab to make it active.

More information:

Class Browser (see page 432)

Default Viewing Mode

The Class Browser window displays your application's class inheritance hierarchy in a tree view in its left pane and the corresponding class attributes and methods in a tab folder in its right pane. For example:

Class Browser


To expand the tree view, click + to the left of the Object superclass. The Class Browser displays two main branches:

ExtObject branch

Contains all external classes registered for use by the current application

UserObject branch

Contains all of the user-defined classes for the current application

To view the methods of a control added previously, expand branches. Then click the Methods tab. The Class Browser displays the control's methods.

System Classes Viewing Mode

To view the class hierarchy for the OpenROAD system classes, click the System Classes icon beneath the Class Browser header bar, and then click the + button to the left of the Object superclass. All the OpenROAD system classes are displayed:

Class Browser


If a particular class has subclasses (that is, it is expandable), a + button appears to the left of the class name. If a class has no subclasses, no button is displayed.

For example, to view the subclasses belonging to another class, click the + button to the left of the desired class (for example, FieldObject). The FieldObject branch displays the FormField and MenuField subclasses. Now expand the FormField class and one of its subclasses, ActiveField:

This tree view graphically summarizes the discussion of shape and active field types in the chapter Creating and Using Basic Fields (see page 151). Also, the Attributes tab illustrates why many of the field properties listed in the Property Inspector are considered common.

To view the methods belonging to FieldObject, click the Methods tab in the right pane of the Class Browser.

The higher a class's position in the hierarchy, the more generalized are the characteristics and functions that it defines. Furthermore, the attributes and methods defined for a class (in this case, FieldObject) apply to all of its subclasses. If you expand in turn the ScalarField class and the ButtonField subclasses, you will see that the attributes for the ButtonField class are more specific than those of its superclass, FieldObject.

Writing Scripts and Procedures 435

Chapter 13: Writing Scripts and Procedures


How You Can Use Scripts (see page 435) Script Types (see page 436) How You Can Write Frame Scripts (see page 436) How Field and Menu Scripts Work (see page 437) How You Can Write User Class Scripts (see page 438) How You Can Write Include Scripts (see page 438) Script Editor (see page 438) How You Can Use Your System Editor (see page 442) How You Can Use Templates for II_WINDOWEDIT and II_WINDOWVIEW (see page 443) How Editing Multiple Scripts Works (see page 445)

You can develop or incorporate 4GL procedures into your applications. In OpenROAD Workbench, these 4GL procedures are identified as scripts. This chapter describes in detail how to use the Script Editor.

How You Can Use Scripts

You can use scripts for fields, menu items, and user class methods to perform a task when the user selects the field, item, or class. You can develop your scripts using the Script Editor—the Workbench text editing facility—or your own system editor.

Note: You can also include 4GL procedures in your script using the Include Script Editor.

All procedures and scripts must be written in 4GL, and may include preprocessor statements and macro variables as defined in the Programming Guide.

Note: The Script Editor only lets you edit your 4GL scripts; it does not let you edit the preprocessor output from your scripts. You may view the preprocessor output from your scripts by clicking Tools, View Processed Script on the Frame Editor's floating menu bar. However, you can edit the processed script using the Debugger.

For additional information about using the Debugger, see the Programming Guide.

Script Types


Script Types

The types of scripts you may use include the following:

Frame Scripts

Define the local variables for the frame and procedures for any of the frame events

Field Scripts and Menu Scripts

In addition to frame events, these include code for field and menu item events in the frame script. This method centralizes all the code for the frame in one script.

Alternatively, you can write separate scripts for individual fields and menu items. With this method, the script is always associated with the specific field or menu item, even when you copy or move it to another frame.

Scripts for User Class Methods

Scripts for user class methods define the behaviors available for user classes you create. You write one script for all the methods of the user class. For each method in the script, Workbench provides a template with the required format of the 4GL code for that method.

How You Can Write Frame Scripts

To write your frame script, you can use the Workbench Script Editor or your system editor. To open the Script Editor, click Tools, Script on the Frame Editor's floating menu bar.

If you prefer to use your system editor, you must set the environment variable, II_W4GL_SYSTEMEDITOR. For more information, see How You Can Use Your System Editor (see page 442).

A frame script contains the code for a specific frame, such as the code to declare and assign values to local variables or to display selected data on the form. A frame script can have three parts:

Initialize statement

(Optional) Declares parameters, local variables, and procedures for the frame. Because this statement is executed before the frame is actually displayed, this statement is also used to perform any start-up operations for the frame.

How Field and Menu Scripts Work


Event blocks

Contain code that OpenROAD executes when the user or the program initiates a specified action.

User-initiated actions include clicking a button on the form or exiting a field. Program-initiated actions include sending events between frames.

Local procedures

(Optional) Make code easier to read and eliminate duplication of code

For more information about writing 4GL scripts, see the Programming Guide.

How Field and Menu Scripts Work

A field script or menu script contains the code for a single field or menu item, respectively, such as a radio field or a menu toggle. Field and menu scripts can contain initialization code, event blocks and local procedures.

The initialize statements in field and menu scripts differ from those used in the frame script in that they contain no parameter declarations. A field's initialize block is executed during frame start-up, following the execution of the initialize block for the frame and preceding execution of the initialize block for any ancestors.

Because field scripts are associated directly with a field or menu item, it is not necessary to name the field or menu item in the event block. To call the editor, select the field or menu item, and then click Edit, Field Script in the Frame Editor or the Menu Editor. You can also code the field and menu scripts in the frame script.

Whether you include the code for an individual field or menu item in the frame script or in a field script is basically a matter of your personal preference or programming style. Putting all the code for the fields in the frame script lets you centralize the code for the frame. Using individual field scripts means that the script is permanently associated with the specific field or menu item if you copy or duplicate the field.

For more information about writing field and menu scripts, see the Programming Guide.

How You Can Write User Class Scripts


How You Can Write User Class Scripts

A user class script contains the 4GL code for the methods of a user class. This script defines the behavior of your user class. The user class script contains the source code for all the methods of that user class. For each method in the script, Workbench provides a template with the required format of the 4GL code.

To write user class scripts, click Tools, Script in the Class Editor.

For more information about the Class Editor and creating user classes and user class methods, see Working With Classes (see page 411). For more information about defining methods in user class scripts, see the chapter “Writing Scripts and Procedures” in the Programming Guide.

How You Can Write Include Scripts

An include script is a script that you can insert (include) into other scripts in your application. This helps avoid redundant coding of common application variables and procedures.

To reference an include script in your other scripts, you must use the #include statement to identify it, and it must already exist as a component of this application.

The #include statement has the following syntax:

#include include_script_name

When you compile the frame, the include script is merged into your script, and then compiled.

For more information about the #include statement and preprocessor extensions, see the Programming Guide. To create include script components, see the chapter Adding Other Components to Your Application (see page 447).

Script Editor

The Script Editor provides basic text editing facilities such as cutting, copying, and pasting. It also enables you to search for and replace selected text and to move to a specified line number in your code. It lets you edit frame, field, and menu item scripts concurrently.

Script Editor


Call the Script Editor

You can open the Script Editor from various editors.

To call the Script Editor

For frame scripts

Click Tools, Script on the Frame Editor's floating menu bar.

For field and menu scripts

Select the field or menu item and then click Edit, Field Script in the Frame (or Menu) Editor.

For user class scripts

Click Tools, Script in the Class Editor.

For include scripts

Click Tools, Script in the Include Script Editor.

If your script is contained in a text file, click File, Insert Script from File in the Script Editor. Workbench displays the File Selection dialog where you can specify the name and location of the file containing the script.

How You Can Edit Text with the Script Editor

You can cut and copy text, or find and replace text.

Cut and Copy Text

Cutting text removes the original text and stores it in the paste buffer. Copying text places the text in the paste buffer without removing the original text.

To cut or copy text

1. Select the text in your script by dragging the mouse cursor over it.

2. Click Edit, Cut or Edit, Copy.

3. Position the cursor where you want to insert the text, or select the text that you want to replace.

4. Click Edit, Paste.

The contents of the paste buffer are inserted.

Script Editor


Find and Replace Text

You can find and replace text in the Script Editor.

To find and replace specific text in a script

1. Click Find, Find in the Script Editor.

The Search/Replace dialog appears.

2. Enter the search string (the text you want to search for) in the Find String entry field.

3. Click Ignore Case to specify whether text in the script must match the case of the search string (for example, whether “declare” in the script matches the search string “Declare”).

4. Enter a replacement string (text with which to replace the search string), if desired.

The replacement string is always inserted into the text exactly as you entered it.

5. Click one of the following buttons on the dialog:

Replace All

Replaces every occurrence of the search string in the script automatically

Find

Finds the first occurrence of the search string

6. If you selected Find and the search string is found, click one of the following commands on the Find menu:

Find Next

Finds the next occurrence of the search string

Replace

Replaces the current occurrence of the search string with the replacement string

Replace and Find

Replaces the current occurrence of the search string and then finds the next occurrence

To find specific lines and change their text attributes

1. Click Find, Go to Line Number in the Script Editor.

The Go to Line Number dialog appears.

2. Enter the line number and click OK.

The line number you entered is highlighted.

Script Editor


3. Click Font, Bold to specify boldface or regular type.

Note: Using the Font menu commands affects the Script Editor only. The type and window of the system editor are not affected.

4. Click one of the size toggles on the Font menu to specify the type size.

Note: When you change the size of the type, the Script Editor window is resized to fit the current text.

How You Can Save or Cancel Your Script Changes

The Script Editor does not have an explicit save command. Your changes are saved when you click File, Close. You cannot save progressive versions of the script while you are in the Script Editor.

To cancel all changes you have made since you opened the script in the Script Editor, click File, Revert. Workbench restores your script to the way it appeared when you first displayed it in the Script Editor.

You can save a script to a text file by clicking File, Write Script to File and specifying the name and location of the file.

How You Can Navigate the Script Editor

The following table describes how to use the keyboard to navigate in the Script Editor:

Key Description

Left arrow Moves caret one character left

Right arrow Moves caret one character right

Up arrow Moves caret one line up

Down arrow Moves caret one line down

Page up Scrolls one window up

Page down Scrolls one window down

Home Moves caret to the beginning of the current line

End Moves caret to the end of the current line

Ctrl+Left arrow Moves caret one word left

Ctrl+Right arrow Moves caret one word right

How You Can Use Your System Editor


Key Description

Ctrl+Home Moves caret to the beginning of the file

Ctrl+End Moves caret to the end of the file

How You Can Use Your System Editor

As an alternative to the Script Editor, you can use your system editor instead. You can specify that Workbench call the system editor by setting the II_W4GL_SYSTEMEDITOR environment variable to TRUE.

II_W4GL_SYSTEMEDITOR

Specifies whether to use a system editor instead of the internal OpenROAD script editor. Possible settings are:

TRUE

Specifies that Workbench should call the system editor specified by II_WINDOWEDIT or II_EDIT environment variables. The system editor is automatically opened instead of the OpenROAD Script Editor.

Note: For view-only operations, II_WINDOWVIEW or II_VIEW is used in place of II_WINDOWEDIT or II_EDIT.

The system editor is called automatically for frame and field scripts and procedures.

FALSE

Specifies that Workbench should use its own Script Editor

Default: FALSE

Workbench checks the following environment variables to find the system editor to use:

II_WINDOWEDIT

Specifies the command template to invoke a system editor in edit mode. This is used to specify a system editor that Workbench uses instead of its own Script Editor for editing scripts.

For more information, see How You Can Use Templates for II_WINDOWEDIT and II_WINDOWVIEW (see page 443).

II_WINDOWVIEW

Specifies the command template to invoke a system editor in read-only or view mode. This is used (for a read-only editor) to specify a system editor that Workbench uses instead of its own Script Editor for viewing scripts.

For more information, see How You Can Use Templates for II_WINDOWEDIT and II_WINDOWVIEW (see page 443).

How You Can Use Templates for II_WINDOWEDIT and II_WINDOWVIEW


II_EDIT

Specifies a system editor that Workbench uses instead of its own Script Editor for editing scripts.

Note: There is no command template for this variable.

II_VIEW

Specifies a system editor that Workbench uses instead of its own Script Editor for viewing scripts.

Note: There is no command template for this variable.

Workbench checks the II_WINDOWEDIT and II_EDIT environment variables (in that order) to see if any are set. If one of the variables is set, OpenROAD uses it. Depending on your operating system, Workbench does the following:

Windows

If none of the variables is set, the Windows Notepad is used.

UNIX

If none of the variables is set, the vi editor is used.

Similarly, for a read-only editor, II_WINDOWVIEW, II_VIEW, and ING_EDIT (in that order) are checked.

Windows

If none of the variables is set, the Windows Notepad is used.

UNIX

If none of the variables is set, the vi editor is used.

When you are finished editing a script with the system editor, save or quit from the file as you normally do. Workbench closes the system editor window.


If your system editor allows parameters in the command line, you can use the II_WINDOWEDIT or II_WINDOWVIEW environment variable to specify a template for the command line. OpenROAD substitutes the field specifiers in the template with the appropriate values.



For Windows

The valid specifiers for Windows platforms are:

Specifier Description

%e Editor command

%t Window title

%l Line number (used when errors occur)

%f File name (required)

Note: All parameters except for the file name are optional.

For example, assume that your editor is “smartedt” and the command line to run the editor is the following:

smartedt /startline:100 /title:"xxx" filename

You would define the template for II_WINDOWEDIT and II_WINDOWVIEW as follows:

set II_WINDOWEDIT=smartedt /startline:%l /title:%t %f

set II_WINDOWVIEW=smartedt /startline:%l /title:%t %f

OpenROAD substitutes the specifiers %l, %t, and %f with the actual runtime values.

For UNIX

The valid specifiers for UNIX are:

Specifier Description

%g OpenROAD defines -geometry and -display parameters for your xterm

%n Unique name generated by OpenROAD

%t Title generated by OpenROAD

%l Line number (used when errors occur)

%f Temporary file used by OpenROAD (required)

Note: All parameters except for the file name are optional.

How Editing Multiple Scripts Works


For example, assume that your editor is vi and the command line to run the editor from an X terminal is the following:

$ xterm -e vi +10 filename &

You would define the template for II_WINDOWEDIT and/or II_WINDOWVIEW as follows:

$ setenv II_WINDOWEDIT 'xterm %g +sb -name "%n" -title "%t" -e vi +%l %f'

$ setenv II_WINDOWVIEW 'xterm %g +sb -name "%n" -title "%t" -e vi +%l %f'

OpenROAD substitutes the specifiers %g, %n, %t, %l and %f with the actual runtime values.

How Editing Multiple Scripts Works

OpenROAD Workbench lets you edit the frame script and a field or menu item script from the same frame simultaneously. It does not let you edit more than one field or menu item at a time.

If you are editing a field or menu item script and you select a different item, the current script is saved and the new item script is opened in its place.

If you use a system editor, you can open only one edit session at a time.

Adding Other Components to Your Application 447

Chapter 14: Adding Other Components to Your Application


Variable Types (see page 447) Create a Global Variable (see page 449) Macro Variables (see page 451) Global Constants (see page 454) Procedures (see page 456) Ghost Frames (see page 465) 3GL Sample Application (see page 467)

This chapter describes how to use the visual development environment to create and edit components that you use in programming the 4GL code for your applications. After you create these components, they are available for use in any script or procedure in the application.

For more information about using these objects in your 4GL code, see the Programming Guide.

Variable Types

OpenROAD variables contain or point to the data that an application manipulates. This data can be displayed to the user or used solely in scripts and procedures. The following are the various types of variables:

Simple Variable

Is a single data item with only one value

Reference Variable

Is a pointer to an object of a specific class

Array Variable

Is a named set of rows, all of which are reference variables that point to objects of the same class

Macro Variable

Is a variable whose value is substituted by the OpenROAD preprocessor into the 4GL source code prior to compilation

Variable Types


Ways to Create Variables

You can create variables in the following ways:

Specify a variable name in the Property Inspector for a field or menu item.

Such a variable contains the data associated with the field or menu item. OpenROAD automatically declares this variable so that, when you want to manipulate the field or menu item's data in your 4GL code, you simply reference the variable name.

If you are creating fields dynamically, you can specify in the Property Inspector that OpenROAD not declare a variable for the field.

For more information about creating fields dynamically, see the Programming Guide.

Declare a local variable in the script for a frame or procedure.

These variables are available for use only within the particular frame or procedure in which they are declared. They are not associated with a field or menu item, and users do not see their values.

For more information about declaring local variables, see the Programming Guide.

Create a global variable in the Global Variable Editor.

A global variable is a variable that you can use in any script or procedure in an application. It contains data that any script or procedure in the application can access. Global variables are not associated with field or menu items, and the data they contain is not displayed to the user.

For more information, see Create a Global Variable (see page 449) and the Programming Guide.

Define a macro variable in the Macro Variable Editor.

A macro variable is a preprocessor variable whose value is specified when the application is processed by the OpenROAD preprocessor.

For more information about macro variables, see Create a Macro Variable (see page 452) and the Programming Guide.

Create a Global Variable



You create, edit, view, and delete global variables in the Global Variable Editor.

To create a global variable

1. In the Applications portlet of the Develop tab, select the application in which you want to create, edit, or delete a global variable, and then select the header bar of the Components portlet to make it active.

2. Click File, New, Global Variable.

The Create Global Variable dialog appears.

3. Enter a name for the variable in the Name entry field (for example, My_Global_Variable).

Note: Global variable names must be unique within the application and cannot conflict with the names of any frames, constants, procedures, classes, or other global variables in the application.


5. Click Create.

Workbench displays the Global Variable Editor, where you create the variable definition:

6. Specify the properties for the variable.

For descriptions of each global variable property, see Global Variable Properties (see page 450).

7. Save the global variable by selecting the appropriate command from the File menu.



Global Variable Properties

Global variables have the following properties:

Type

Specifies the variable type:

Simple

Reference

Array

Length

Specifies the maximum number of characters for varchar data types

Nullable

Specifies whether or not simple variables are nullable.

You can either enter the name of the class directly, or access the class by clicking the control button to the right of the Class Name field and selecting it from the Select a Class dialog.

For more information about this dialog, see Set a Return Value (see page 120).

System

Provides a system-assigned initial value

Null

Sets the initial value to a null string

Note: This option is always available for reference and array variable types, and only available for simple types if you have made the variable nullable.

String

Lets you specify a string for the initial value in an adjacent entry field

Note: This option is available only for simple type variables.

Edit or View a Global Variable

You can edit or view a global variable using the Global Variable Editor.

To edit or view a global variable


2. Select the global variable in the Components portlet.

Macro Variables


3. Click File, Open or File, View.

Workbench displays the Global Variable Editor, where you can examine or modify the variable definition.

4. View or edit the definition for the variable.

For descriptions of each global variable property, see Global Variable Properties (see page 450).

5. Click File, Close and save your changes appropriately.

Delete a Global Variable

You can delete a global variable on the Develop tab.

To delete a global variable


2. Select the variable in the Components portlet.




Note: You must also remove all instances of the deleted component from your code, or you will receive an error message when Workbench compiles your application.

Macro Variables

A macro variable is a preprocessor variable whose value is specified when the application is processed by the OpenROAD preprocessor. If you specify macro variable names in your script, the corresponding value is substituted by the preprocessor before compiling.

OpenROAD provides built-in macro variables for your use. You can also create macro variables either in the frame script or by using the Macro Variable Editor. Macro variables let you compile your code conditionally; they also simplify code maintenance.

Macro Variables


Create a Macro Variable

You can create a macro variable for a user frame, or change the values of an existing macro variable in the Macro Variable Editor, which you access from the Frame Editor.

To create a macro variable or change the values of an existing macro variable

1. Open the desired frame in the Frame Editor (see Open an Existing Frame (see page 111)).

2. Click Tools, Macro Variables on the Frame Editor's floating menu bar.

Workbench displays the Macro Variable Editor. For example:

3. Enter a name, value, and optional Short Remark (comment) for each macro variable you want to create, or edit this information for existing macro variables.

For descriptions of each macro variable property, see Macro Variable Properties (see page 452).

4. Save the macro variable by selecting the appropriate command on the File menu.

Macro Variable Properties

You can set the following property for macro variables:

Value

Specifies the value of the macro variable.

If the value of the macro variable is a long expression that cannot fit in the Value column, click Edit, Value. Workbench opens the Script Editor or your system editor for you to write the expression.

For more information about using macro variables in your 4GL code, see the Programming Guide.

Macro Variables


Delete Macro Variables

User frames, ghost frames, frame templates, and 4GL procedures may all contain macro variables. You delete macro variables in the Macro Variable Editor.

To delete a macro variable

1. Select the application containing the component in the Applications portlet of the Develop tab.

2. Open the component containing the macro variable in the Frame Editor.

3. Click Tools, Macro Variables in the respective editor.

Workbench displays the Macro Variable Editor.

4. Select the macro variable to be deleted. For example:

5. Click the control button to the right of the table field.

A local option menu appears:

6. Click Delete Current Row.

7. Close the Macro Variable Editor.

8. Close the component editor, saving your changes.


Global Constants


Global Constants

A global constant is a value to which you give a name. You can then use this name to represent the value any place in an application. For example, you can substitute a brief name for a long phrase or value. You also can use a constant for a value, such as a sales tax rate, that you might need to update in many places throughout an application.

Create a Global Constant

You create, edit, view, and, delete global constants in the Constant Editor.

To create a global constant

1. In the Applications portlet of the Develop tab, select the application in which you want to create, edit, or delete a constant, and then select the header bar of the Components portlet to make it active.

2. Click File, New, Global Constant.

The Create Global Constant dialog appears.

3. Enter a name for the global constant in the Name entry field (for example, My_Constant).


5. Click Create.

Workbench displays the Constant Editor:

6. Select the data type option for the constant: Varchar, Integer, Smallint, Float, Decimal, Date, or Money.

If you select Varchar, an entry field appears, allowing you to enter a length.

If you select Decimal, the Precision and Scale entry fields appear, allowing you to enter this information.

Global Constants


7. Specify a value for the constant.

Note: The value must be consistent with the data type you have specified.

8. Save the constant by selecting the appropriate command on the File menu.

Edit or View a Global Constant

You can edit or view global constants in the Constant Editor.

To edit or view a global constant


2. Select the constant in the Components portlet.


Workbench displays the Constant Editor.

4. Enter a new remark, data type, length, or value for the constant.

5. Click File, Close and then save your changes appropriately.

Delete a Global Constant

You can delete a global constant on the Develop tab.

To delete a global constant


2. Select the name of the constant in the Components portlet.




The constant is deleted.


Procedures


Procedures

A procedure is a set of statements that you can call by name from a script. You can write procedures in 4GL, and you can call existing 3GL and database procedures. Because procedures are associated with an entire application, rather than with individual frames, you can call any procedure from any script in the application.

Create a 4GL Procedure

A 4GL procedure is a set of 4GL statements that you can call by name in an application. 4GL procedures are written in fourth-generation languages such as Java. You can create, edit, and delete 4GL procedures on the Develop tab.

To create a 4GL procedure

1. In the Applications portlet of the Develop tab, select the application in which you want to create, edit, or delete a component, and then select the header bar of the Components portlet to make it active.

2. Click File, New, 4GL Procedure.

The Create Procedure dialog appears.

3. Enter a name for the procedure in the Name field (for example, My_4GL_Procedure).


5. Specify the properties for the procedure.

For descriptions of each property, see 4GL Procedure Properties (see page 458).

Procedures


6. Click Create.

Workbench displays the 4GL Procedure Editor. Workbench also calls the Script Editor (or your system editor) and displays a script template containing the keywords required for a 4GL procedure for you to write the procedure code:

7. Write the script for the procedure.

For more information about using the Script Editor to write procedures, see Writing Scripts and Procedures (see page 435).

8. Click File, Close in the Script Editor.

9. (Optional) Click Tools, Compile in the 4GL Procedure Editor to compile the procedure.

Note: This step is not required because OpenROAD automatically compiles the procedure the next time you run the procedure. For more information, see How You Can Compile 4GL Procedures (see page 459).

10. Click Debug, Go in the 4GL Procedure Editor to test the procedure.

To stop running the procedure, click Debug, Stop.

Note: You also can use the Workbench's Run toolbar button to test the current application, thus ensuring that the procedure receives any parameters it needs from the frame or procedure that calls it. For more detailed information, see Running an Application (see page 577).

11. Save the 4GL procedure by selecting the appropriate command on the File menu.

Procedures


4GL Procedure Properties

You can set the following properties for 4GL procedures:

Return Value

Specifies the data type of the return value:

None

Simple

Reference

Array

Length

Specifies the maximum number of characters for the return value for simple varchar data types.

You can enter the name of the class directly, or access the class by clicking the control button to the right of the entry field and selecting it from the Select a Class dialog. For more information about this dialog, see Set a Return Value (see page 120).

SCP Generation

Selects one of the following options:

No SCP

Specifies that SCPs should not be generated

Generate SCP

Specifies that SCPs should be generated

Include in SCP MetaData

Specifies that both SCPs and SCP meta data should be generated

SCP Name

If you selected the Generate SCP option, specifies a name for the generated SCP. Workbench provides a default name, which you can change.

Procedures


How You Can Compile 4GL Procedures

After you have written a 4GL procedure, you can compile it by clicking Tools, Compile in the 4GL Procedure Editor. While it is compiling the procedure, Workbench provides status messages at the bottom of the 4GL Procedure Editor window. For example:

If it finds any errors, Workbench opens the Compilation Errors window. For more information about this window, see the How You Can View Compilation Errors (see page 147).

View or Edit 4GL Procedures

You can view or edit a 4GL procedure in the Procedure Editor and the Script Editor.

To view or edit a 4GL procedure


2. Select the name of the procedure.

Procedures



The 4GL Procedure Editor appears. It also calls the Script Editor (or your system editor), where you can edit the procedure code.

The following is a simple example using different kinds of variables in a 4GL procedure:

4. Change any of the procedure's properties in the Procedure Editor.

5. To edit the procedure code, switch to the Script Editor and make your changes.


Delete a 4GL Procedure

You can delete a 4GL procedure on the Develop tab.

To delete a 4GL procedure


2. Select the procedure in the Components tab.

Procedures



A standard Confirmation dialog appears.


Workbench deletes the procedure.


How You Can Use Local 4GL Procedures

You can write a 4GL procedure that is local to an individual frame. Local procedures are not application components; you write a local 4GL procedure as part of a frame script. Because you declare local procedures within the script, you do not need to create a local procedure in the 4GL Procedure Editor.

For more information about using local procedures, see the Programming Guide.

Create and Register 3GL Procedures and Database Procedures

You can create a 3GL procedure or database procedure after you register it.

Register a 3GL Procedure or Database Procedure

You must register all database procedures and those 3GL procedures that you call directly from your 4GL code. You need not register 3GL procedures that are called only from other 3GL procedures. You register procedures on the Develop tab.

Note: You can create numbered versions of 3GL procedures.

To register a 3GL procedure or database procedure


2. Click File, New, 3GL Procedure or File, New, Database Procedure.

The appropriate Create Procedure dialog appears.

3. Enter a name for the 3GL procedure or database procedure in the Name field (for example, My_3GL_Procedure).


Procedures


5. Click Create.

The appropriate editor (3GL Procedure or Database Procedure Editor) appears.

6. Specify the properties for the procedure. For example, click Browse in the 3GL Procedure Editor.


7. Select the DLL file containing the desired procedure (for example, libq32_1.dll).

Your choice is entered in the Library Name field:

8. (Optional) Click Strip Path to strip the file's path from the Library Name entry field.

9. (Optional) Specify other properties for the procedure.

For descriptions of each of these properties, see 3GL Procedure and Database Procedure Properties (see page 463).

10. Save the procedure by selecting the appropriate command from the File menu.

Create a 3GL Procedure or Database Procedure

Note: You must register a procedure in OpenROAD Workbench before you can create it. For more information, see Register a 3GL Procedure or Database Procedure (see page 461).

You create procedures in the Script Editor.

Procedures


To create a 3GL procedure or database procedure

1. Write the procedure in the appropriate language using the Script Editor.

2. Make the procedure available for use by your application as follows:

For 3GL procedures

Compile the source code and then link it into the OpenROAD runtime system. For more information, see How You Can Deploy Applications with 3GL Procedures (see page 585).

For database procedures

Create the procedure as part of your database.

3GL Procedure and Database Procedure Properties

Note: The only property you can set for a database procedure is its Remark.

3GL procedures have the following properties:

Library Name

Defines the location where the library is located. When you click Browse, a standard File Selection dialog appears. The StripPath option strips the path from the library name.

Return Value Data Type

Specifies the data type of the value returned by the procedure:

None

Varchar

Smallint

Integer

Float

Money

Date

Language

Specifies the language in which the 3GL procedure is written:

C

PASCAL

C_PASCAL

Procedures


View and Edit 3GL Procedures and Database Procedures

You can view and edit 3GL procedures and database procedures on the Develop tab.

To view the properties of a 3GL procedure or database procedure


2. Select the procedure in the Components portlet.


The appropriate editor—3GL Procedure or Database Procedure Editor—appears.

Note: If you select Open, you can change any of the procedure properties.


Delete a 3GL Procedure or Database Procedure

You can delete a 3GL procedure or database procedure on the Develop tab.

To delete a 3GL procedure or a database procedure


2. Select the procedure in the Components list.




Workbench deletes the procedure.


Ghost Frames


Ghost Frames

Ghost frames are used to manage and coordinate applications without user interaction. Ghost frames differ from other OpenROAD user frames in that they do not contain forms (thus making them invisible to the user). However, you can use ghost frames like regular user frames in the following ways:

You can call ghost frames from other frames and procedures.

Ghost frames can send and receive user events.

Ghost frames also differ from 4GL procedures in that they can receive and execute user and database events. Ghost frames are useful for handling operations that run continuously without requiring user intervention.

For more information about ghost frames, see How You Can Create Non-interactive Applications (see page 39).

Create a Ghost Frame

You can create a ghost frame in the Ghost Frame Editor.

To create a ghost frame


2. Click File, New, Ghost Frame.

The Create Ghost Frame dialog appears.

3. Enter a name for the ghost frame in the Name field (for example, My_Ghost_Frame).


5. Click Create.

The Script Editor (or your system editor) appears. The Ghost Frame Editor is also opened:

By default, Workbench creates your ghost frame with no return value. To accept this default, proceed to Step 7.

Ghost Frames


6. Specify the properties for the ghost frame.

For descriptions of each ghost frame property, see Ghost Frame Properties (see page 466).

7. Write the 4GL code for the ghost frame in the Script Editor (or your system editor).

8. Save the ghost frame by selecting the appropriate command on the File menu.

For more information about using ghost frames in an application, see the Programming Guide. For more information about writing frame scripts, see Writing Scripts and Procedures (see page 435).

Ghost Frame Properties

You can set the following properties for ghost frames:

Return Value

Specifies the data type of the return value:

None

Simple

Reference

Array

Length

Specifies the maximum number of characters for the return value for simple return values and varchar data types

Class Name

Specifies the name of a system class or user class in the current application, or an included application for reference or array return values.

You can enter the name of the class directly, or access the class by clicking the control button to the right of the entry field and selecting it from the Select a Class dialog. For more information about this dialog, see Set a Return Value (see page 120).

3GL Sample Application


Delete a Ghost Frame

You can delete a ghost frame on the Develop tab.

To delete a ghost frame

1. In the Applications portlet of the Develop tab, select the application in which you want to create, edit, or delete a component, and then select the header bar of the Components portlet to make it active.Select the name of the ghost frame.




Workbench deletes the ghost frame.



If you have installed the OpenROAD Development package, a sample application, test_3gl, is included in the OpenROAD installation in the following directory:

Windows

%II_SYSTEM%\ingres\w4glsamp\3gl

UNIX or Linux

$II_SYSTEM/ingres/w4glsamp/3gl

This sample application demonstrates how you can use 3GL functions in your 4GL code.

How the 3GL Sample Application Works on Windows

The directory %II_SYSTEM%\ingres\w4glsamp\3gl contains the following files:

test_3gl.exp

Is an export file of the OpenROAD application used to run the sample 3GL procedure

samp3gl.c

Is the sample 3GL source



samp3gl.def

Is the module definition file for building a DLL

makefile

Is the makefile for compiling and linking a DLL

To use the demo application, you must perform the following basic steps:

1. Import the sample application into your database.

2. Build the sample application.

3. Set up the run environment for the sample application.

4. Run the sample application.

See the following sections for details on each of these steps.

Import the Sample Application into Your Database

Import the test application into your database by entering the following command at the command prompt:

w4gldev backupapp in dbname test_3gl "%II_SYSTEM%\ingres\w4glsamp\3gl\test_3gl.exp"

dbname

Specifies the name of the database into which you are importing the test_3gl application

Build the Sample Application

You can build the 3GL application by importing it into your database, making an application image using the MakeImage utility, and using the makefile to build the sample application.

To build the sample application

1. Make an application image using the MakeImage utility, using "test_3gl.img" as the image name.

Note: You may skip this step if you want to run the application directly from OpenROAD Workbench.

2. Use the makefile provided to compile samp3gl.c and link the DLL (samp3gl.dll):

cd %II_SYSTEM%\ingres\w4glsamp\3gl nmake /f makefile all

More information:

Use the MakeImage Utility (see page 569)



How You Can Set Up the Run Environment

Ensure that OpenROAD can find samp3gl.dll. There are two ways to do this:

Set the environment variable II_LIBU3GL to point to the location of samp3gl.dll.

You may do this either by setting the Windows environment variable, II_LIBU3GL, or by using the ingsetenv command:

ingsetenv II_LIBU3GL %II_SYSTEM%\ingres\w4glsamp\3gl\samp3gl.dll

Whether you set the Windows environment variable or use ingsetenv, you must specify the full path if the directory where you placed the dll is not in the search path.

If you want to use a variable other than II_LIBU3GL, set that variable the same way you would set II_LIBU3GL, but remember you must run the application with the -m flag.

Ensure that samp3gl.dll is in a directory that is in your search path.

All the 3GL procedures in the test_3gl application are defined as being in samp3gl.dll. If the DLL is in the search path, OpenROAD will find it when you run the application.

How the 3GL Sample Application Works on UNIX or Linux

The directory $II_SYSTEM/ingres/w4glsamp/3gl contains the following files:

test_3gl.exp

Is an export file of the OpenROAD application used to run the sample 3GL procedure

samp3glu.c

Is the sample 3GL source for UNIX or Linux

makefile_hp

Is the makefile for compiling and linking a shared library on the HP platform

makefile_sol

Is the makefile for compiling and linking a shared library on Sun Solaris 2.x

makefile_aix and samp3glu.aix

Are the makefile and exports file for compiling and linking a shared library on IBM AIX 4.3.2



makefile_axp

Is the makefile for compiling and linking a shared library on Compaq Tru64 UNIX platform. Special compiler flags are used to interface correctly with OpenROAD.

makefile_lnx

Is the makefile for compiling and linking a shared library on Linux 6.1 or 6.2. Special compiler flags are used to interface correctly with OpenROAD.

To use the demo application, you must perform the following basic steps:

1. Import the sample application into your database.

2. Build the sample application.

3. Set up the run environment for the sample application.

4. Run the sample application.

See the following sections for details on each of these steps.

Import the Sample Application into Your Database

Import the test application into your database by entering the following command on the command line:

w4gldev backupapp in dbname test_3gl "%II_SYSTEM%\ingres\w4glsamp\3gl\test_3gl.exp"

dbname

Specifies the name of the database into which you are importing the test_3gl application



Build the Sample Application

You can build the 3GL application by importing it into your database, making an application image using the MakeImage utility, and using the makefile to build the sample application.

To build the sample application

1. Make an application image using the MakeImage utility, using "test_3gl.img" as the image name.

Note: You may skip this step if you want to run the application directly from OpenROAD Workbench.

2. Use the makefile provided for your platform to compile samp3glu.c and create the shared library (samp3gl.shared-lib-suffix):

cd $II_SYSTEM/ingres/w4glsamp/3gl make -f makefile_your-platform

The shared library samp3gl.shared-lib-suffix will be created and placed into $II_SYSTEM/ingres/lib.

More information:

Use the MakeImage Utility (see page 569)

How You Can Set Up the Run Environment

Ensure that OpenROAD can find samp3gl.shared-lib-suffix. There are two ways to do this:

Set the environment variable II_LIBU3GL to point to samp3gl.shared-lib-suffix.

You may do this either by setting the system environment variable, II_LIBU3GL, or by using the ingsetenv command:

ingsetenv II_LIBU3GL $II_SYSTEM/ingres/lib/samp3gl.shared-lib-suffix

Whether you set the system environment variable or use ingsetenv, you must specify the full path if the directory where you placed the shared library is not in the search path.

If you want to use a variable other than II_LIBU3GL, set that variable the same way you will set II_LIBU3GL but remember you must to run the application with the -m flag.

Ensure that samp3gl.shared-lib-suffix is in a directory that is in your search path.

All the 3GL procedures in the test_3gl application are defined as being in samp3gl.shared-lib-suffix. If the shared library is in the search path, OpenROAD will find it when you run the application.



Run the Sample Application

You can use the following procedure to run the 3GL sample application on any platform.

To run the application

If you made an image of the application, you can run the image file by using the RunImage utility. Enter the following on the command line:

w4glrun test_3gl.img

If you used a variable other than II_LIBU3GL, then set the -m flag to specify that variable.

Note: You can also run the application directly from OpenROAD Workbench.

After the sample is running, you may invoke all the functions by clicking the Call All 3GL Procedures button, or invoke individual functions by selecting the associated radio buttons. A message box will display a message about the results. Both the return value and the argument values are checked after each call to ensure that they are correct.

More information:

RunImage Utility Parameters (see page 64)

Creating Reports in OpenROAD 473

Chapter 15: Creating Reports in OpenROAD


Start OpenROAD Reporter (see page 474) OpenROAD Reporter Window (see page 475) Report Design Techniques (see page 478) Setup/Cleanup (see page 493) Save the Report Query and Document (see page 494) How You Can Design Report Documents (see page 496) Set Page Breaks (see page 523) How You Can Enhance Report Design (see page 524) Preview and Print Report Documents (see page 532) Export a Report (see page 534) Delete a Report (see page 534) RWConv Utility (Report Converer) (see page 534)

OpenROAD includes the OpenROAD Reporter, a repository-based report writing utility that lets you view or print reports. This report development tool features sophisticated graphic design capabilities. Its graphical interface lets you literally “draw” a report using various fonts, colors, geometric shapes, and dynamic images. The graphic designer provides open API capability, a graphical layout editor, and a query editor. After creating a report, you generate it using data from your relational database. Reporter provides multiple database support.

This chapter describes the Reporter window and the basics of configuring a report. It also provides detailed procedures for designing a report and enhancing its appearance.

Start OpenROAD Reporter


Start OpenROAD Reporter

You start OpenROAD Reporter in the OpenROAD Workbench.

To start OpenROAD Reporter


2. Click Tools, Reporter.

The OpenROAD Reporter window appears.

Note: If you did not install the Reporter with OpenROAD, the Reporter Setup window appears.

To set up OpenROAD Reporter

1. Specify the vnode and database name in the Database field using the following form:

vnode::database_name

2. Enter the user name that you want to use to log in to the specified database in the User field.

3. Click the Install button:

OpenROAD Reporter is unpacked and installed, and the Reporter window appears.

OpenROAD Reporter Window



The Reporter window contains menus, the file and text command toolbars, and an option field displaying any open report documents.

To display Layout and Query toolbars

Click View, Toolbars.

The available toolbars, which help you perform basic operations and simplify document design, are listed in OpenROAD Reporter Toolbars (see page 476).

OpenROAD Reporter Main Menus

The following menus are available in the main OpenROAD Reporter window. Many menu commands are also available as buttons on the Reporter toolbars.

File Menu

Includes the usual file management commands that let you create a new file, open, import, or export a file; save, revert to last saved version of a file, import from or export to a file; close, delete, compile, or print a file; and exit the program

Edit Menu

Includes the usual editing commands—Undo, Redo, Cut, Copy, Paste, and so on—as well as commands letting you fuse two texts, select fields, access the Query Editor, delete the current page, insert a new page, and refresh the display

View Menu

Includes commands that let you view the status bar, pages of the report document, and SQL code. The Toolbars command lets you specify which toolbars you want displayed in the Reporter window.

Options Menu

Includes commands that let you specify the arrangement of components in the Reporter window, set the grid spacing, and save settings now or on exiting



Insert Menu

Includes commands that let you choose select mode, add text, and add fields to your report document

Layout Menu

Includes commands that let you enhance the appearance of the report in various ways. This menu also contains two status indicators: The Lock/Unlock toggle under the Position & Size command and Object Has Default API Code, which Reporter sets when the user edits the API code for a field.

Tools Menu

Includes commands that let you adjust document properties, to edit the lists of fields and variables in the current document, to access the Procedure List, to manage the Image Catalog, to set default screen fonts, and to synchronize properties and propagate graphical properties to children

Window Menu

Includes the Close All command

Help Menu

Includes the standard help commands

OpenROAD Reporter Toolbars

OpenROAD Reporter toolbars are user-selectable for viewing. Toolbars are docked (part of the Reporter main window) with one exception: the Object Position toolbar is floating (a separate frame). The field palette can be either docked or floating.

Note: For toolbar buttons, modifications apply to selected fields in the document. For example, a field must be selected before changing the borders of that field.

File Toolbar

Buttons on the file toolbar include the standard Open, Close, Save, Print, Cut, Copy, Paste, Duplicate, Undo, Redo, Previous Page, and Next Page.

To hide or display the File toolbar, click View, Toolbars, File Toolbar.



Text Toolbar

Buttons on the text toolbar include the standard font selection, font size, Bold, Italic, Underline, Outline, and justification. These action buttons produce one of two results. If a field is selected in the work area, the selected command is applied to that field (if possible). If no field is selected in the work area, clicking a toolbar button sets the default for the next field creation.

To hide or display the Text toolbar, click View, Toolbars, Text Toolbar.

Field Palette

The floating field palette is displayed when you first open Reporter.

To hide the field palette, click View, Toolbars, Palette, and clear the checkmark.

To dock the field palette so that it is displayed as a horizontal toolbar in the Reporter window, click Options, Palette Docked.

The field palette contains buttons for the numerous tools available in Reporter. These include buttons for selecting the mode for the type of field you want to create such as Text, Box Trim, Single Field, Variable Field, Date, Rectangle, and so on.

You can configure the floating field palette either as a square, or a single or double row. Drag the right or left edge of the palette to make it wider or narrower.

Layout Toolbar

The layout toolbar includes buttons for the color, gravity, alignment, and line attributes palettes.

To hide or display the Layout toolbar, click View, Toolbars, Layout Toolbar.

Query Toolbar

The Query toolbar contains buttons for accessing the Setup/Cleanup dialog, the Query and Sort Editors, and the SQL Code Viewer.

To hide or display the Query toolbar, click View, Toolbars, Query Toolbar.

Object Position Toolbar

The Object Position toolbar shows the absolute position of a selected field and lets you edit the coordinates of the selected field, or in a multiple selection, the fields enclosed in a bounding box.

To hide or display the Object Position toolbar, click View, Toolbars, Position Toolbar.

Report Design Techniques



This section describes design and formatting concepts and procedures useful in creating a report document.

When you create a new report document or customize an existing report created in Reporter, you can use any of the following report design techniques:

Add, change, or delete report sections

A report section is the basic unit of layout in a report document. Each section can contain fields, text, and graphics. There are three types of sections, which are described in Report Section Types (see page 496).

Add report details, including text, fields, and graphics

Text includes field labels and page and report headers and footers.

A field is a reference in a report document to an individual piece of data. It can be a database field, which displays information from one column in a query result or it can be a computed field, which displays a value computed from the data using a function or formula. For more information see How You Can Create Data Fields (see page 500).

Graphics—logos, designs, photos, or other pictures—can be imported into the report. You can also draw lines, rectangles, and ellipses. For more information, see How You Can Use Shapes & Images Fields (see page 516).

Format the page display

You can format margins, text, fields, and data alignment on the report page; place borders around the report; and apply fonts, styles, and color to the report document contents. For more information, see How You Can Enhance Report Design (see page 524).

Design Considerations

In creating a new report using Reporter, basic design considerations include:

Formatting the report document, including selecting the type of presentation (Form, Page Layout, or Tabular), page size (Letter, Legal, A4, and so on) and page orientation (Portrait or Landscape)

For Tabular and Form presentations, specifying the database tables to be included in the report document and how they are related (defining the report query)



Selecting the types of fields to be included in the report document and grouping fields

You may add free trim, box trim, image, date and time, page number, and entry fields to the report; then group the entry fields into stack, matrix, or table fields.

Note: For complete descriptions of the various field types and instructions for creating, positioning, and manipulating fields, see Creating and Using Basic Fields (see page 151).

Determining where data breaks should occur

Each of these considerations is discussed in the sections that follow.

How You Can Format a Report Document

Formatting a report means specifying document properties, including the presentation type, page size, and page orientation. These properties are specified in the Reporter Document Properties window.

After the Reporter window is displayed, you can open and edit any existing report stored in the repository, import a report, or create a new report document.

Open a Report

You can open a report from the Reporter Documents dialog.

To open an existing report

1. Click File, Open Report Catalog.

The Reporter Documents dialog appears.

2. From the list of existing reports, select the one you want to view or edit.

3. Click Edit (or View Only) to open the file.

Import a Report

You can import a report from the Load from file dialog.

To import an existing report

1. Click File, Import from File.

The Load from file dialog appears.

2. Browse to find the desired file (.rep), select it, and click Open to open the file.



Create a New Report

The three types of reports you can create using Reporter are:

Form (see page 483)

Page Layout (see page 484)

Tabular (see page 485)

For more information, see the sections on creating each of these report types.

To create a new report document

Click File, New.

The Reporter Document Properties dialog appears. For more information, see Set Report Document Properties (see page 480).

This dialog lets you set various document properties, including generation and page configuration options, and access the Query Editor.

Set Report Document Properties

The first step in designing a Reporter document is to give it a name. Next, if necessary, you change the generation options. Then you select the type of presentation, page size, and page orientation.

You can design a report in the Reporter Document Properties dialog.

To begin designing a report

1. Type a name for your report in the Name field.

2. (Optional) Enter a short remark.

If you want to include a longer comment, click Long Remark.

3. Change the Generation options—the 4GL Procedure Name, the Print Panel Name, and the Database Name—if desired.

4. Click the icon for the desired report presentation type—Form, Tabular (the default), or Page Layout.

For an explanation of these fields, see Document Properties (see page 481).

5. Click the icon for the desired page orientation—Portrait (default) or Landscape.



6. Select values for Format, Unit, and Margins, or accept the defaults.

For an explanation of the available options for these fields, see Document Properties (see page 481).

7. Click Query Definition to access the Query Editor for a Form or Tabular report.

Note: You can defer this step; however, you must define a query before creating data fields.

Document Properties

You can set the following properties in the Reporter Document Properties dialog:

Name

Defines the document name, which may be any unique name

Limits: 32 characters maximum

Important! You cannot change Document Name or Page Configuration after document creation. Use the Save As command to save your report under a new name.

Short Remark

Specifies a brief description of the document

Limits: 50 characters maximum

4GL Procedure Name

Specifies the name of the generated 4GL procedure (report source code)

Print Panel Name

Specifies the name of the generated user window that launches report execution

Database Name

Specifies the name of the database from which table information for the report is obtained.

The report definition is stored in the database that Reporter initially connects to; however, for each document, you can specify the database from which table information is to be obtained for defining queries and creating fields. By default, this database is used when the report is run. When more than one open report uses the same database, connections are shared. If a report is opened that specifies a non-existent database, the default database is used.



Page Configuration

Specifies one of three available options, represented by icons at the top of the Page Configuration control box. The icons, from left to right, are:

Style Description

Form report presentation allows one record of data per form (with multiple pages possible). Alternatively, a single form can contain only static fields. Form reports are suitable for forms of various kinds and for mail merges.

Tabular report presentation allows columnar-style reports. The Tabular style is suitable, for example, for sales and inventory reports.

Page Layout Template report presentation allows the creation of a template that includes only static fields. This template cannot be printed.

Important! You cannot change Document Name or Page Configuration after document creation. Use the Save As command to save your report under a new name.

Document Format

Specifies one of the following page size formats:

European standard page sizes (in inches):

A3 (11.69 x 16.53) A4 (8.26 x 11.69) A5 (5.83 x 8.26) B4 (10.12 x 14.34) B5 (7.17 x 10.12)

North American standard page sizes (in inches):

Letter (8.5 x 11) Tabloid (11 x 17) Legal (8.5 x 14) Statement (5.5 x 8.5) Executive (7.5 x 10) Folio (8.5 x 13) Quarto (8.47 x 10.83) 10 x 14

Page Orientation

Specifies landscape or portrait orientation



Unit

Specifies unit of measurement in millimeters, dots, or inches. All the measures used by the graphic editor (except grid and duplicate spacing) are converted to the selected unit.

Units are used when generating OpenROAD Reporter source code. The PostScript unit (dot) generated from a pixel unit is approximately 1/72 inch.

Margin

Specifies a range of values for setting top, bottom, and right margins. Defaults are provided.

Long Remark

Opens an editor where you can enter a long comment. The editor contains three menus—File, Edit, and Format—that let you access Microsoft Notepad as well as Read from and Write to files. Edit commands let you search for text and cut, copy, and paste text. Format commands let you change fonts and font sizes in your remark.

Query Definition

Opens the Query Editor to define a query

Create a Form Report

The following example describes how a report with “Form” as the presentation type might be used. The procedure steps are intended only to show you how to begin creating the report. For instructions to add fields to a report document, see Create Tabular Reports (see page 485).

The Form report presentation can contain static fields and data fields. It cannot have header or footer sections.

To create a Form report

1. Set the desired properties in the Document and Generation Options control sections of the Document Properties dialog. For more information, see Set Report Document Properties (see page 480).

2. In the Page Configuration edit control, click Form Layout.

3. Select a format.

4. Click OK.

OpenROAD Reporter displays Page 1/1 of the Form report document.

5. Add the fields you want on Page 1 of the report document by selecting the appropriate tools from the field palette.



6. Click in the work area and drag the cursor to draw a field (rectangular area).

Continue adding (and grouping) fields until you have included all the information you want your report to contain.

Click Next Page in the file toolbar to create additional pages.

7. Click Save on the file toolbar to save your work.

Then follow instructions in Preview and Print Report Documents (see page 532).

Create a Page Layout Template

The following example offers a suggestion of how a report with the Page Layout presentation type might be used. The procedure steps are intended only to show you how to start creating the report. For more information about adding fields to a report document, see Create Tabular Reports (see page 485).

The Page Layout template contains only static fields. This template can be a repository for commonly used static fields (trim and images). These fields can be cut and pasted into other documents. A page layout template can also provide the static framework into which data can be embedded.

To create a page layout template

1. Set the desired properties in the Document Properties dialog.

For more information, see Set Report Document Properties (see page 480).

2. In the Page Configuration box, click Page Layout.

3. Select a format.

4. Click OK.

OpenROAD Reporter displays Page 1/1 of the page layout template document.

5. Add the fields you want in the report by selecting Free Trim mode in the field palette.



6. Click in the work area and drag the cursor to draw a free trim field (rectangular area).

Continue adding (and grouping) fields until you have included all the information you want your report to contain.

Click Next Page on the file toolbar to create additional pages.

7. Click Save on the file toolbar to save your work.

Then follow instructions in Preview and Print Report Documents (see page 532).

Create Tabular Reports

The Tabular report presentation can contain data fields, static fields, and special fields (date and time, page numbers). When you select the Tabular presentation type, Reporter creates a report that includes the following:

Report header

Detail page

Report footer

For guidelines and restrictions that apply when working with report sections, see Report Section Types (see page 496).

After you have selected document properties and chosen page configuration options, the next step in designing a Tabular report is to specify the report data by defining tables and their relationships.

To begin creating a Tabular report

In the Reporter Document Properties dialog, click the Tabular presentation icon in the Page Configuration edit control, and then click Query Definition.

Alternatively, from the Reporter Edit menu, select Query, Edit Query.

How You Can Define a Query

The first step in defining a query is to access the Query Editor. In the Query Editor, select the tables you want to include in your query.

The Query Editor's Edit menu also provides two commands that let you qualify table names:

Add Schema to Query Table

Remove Schema from Query Table



A Where Clause Editor can be accessed from the Query Editor, which lets you add where clause restrictions.

After tables are selected to include in the query and their master-detail status designated, you access the Join Definition dialog to specify table joins.

If you want, you can use the Sort Columns dialog to specify how you want rows of data ordered.

Each of these steps and procedures is described in the sections that follow.

Define a Query

You can define a query in the Reporter Document Properties window (see Set Report Document Properties (see page 480)). Then, you can specify a query definition for the report and view SQL statements.

To begin defining a query

1. Click Query Definition in the Reporter Document Properties window.

The Query Editor appears. Available Ingres tables are shown in the Tables List.

2. Click Edit, View Columns in the Query Editor if you want to view a list of table columns for the highlighted table in the Query Editor's Tables List.

A Table Columns dialog appears, which shows all columns associated with the selected table and lists the total number of columns retrieved for that table.



To specify a query definition for the report

1. Drag and drop the table icons for the tables of your choice to the Query Definition pane.

Alternatively, double-click the items in the Tables List that you want to include in the report query.

The table name is highlighted in the Table List, and an x appears in the toggle field to the right of the table name.

Table names you select appear as icons in the Query Definition pane.

When tables are placed in the Query Definition pane, they are designated as primary or secondary master (M, m) or primary or secondary detail (D, d) button, as indicated by the icons—M,m, D,d—located to the right of the Alias field.

With the exception of Primary Master, you can change these designations by clicking the table icon then clicking the desired secondary master or primary or secondary detail icon.

More than one table can be specified, but only one table can be a Master table and only one can be a Detail table. For more information, see Query Editor Fields (see page 488).

2. Click the appropriate join icon in the Query Definition pane to access the Reporter Join Query Editor. For more information, see Create Table Join Definitions (see page 491).

Important! Table names cannot be changed after document creation. Tables may be added or deleted; deleting a table removes associated fields from the report.

To view SQL statements

Select at least one table and then, in the Query Editor, click Edit, View SQL Code.

Note: You can also access the SQL Code Viewer by clicking SQL Code in the Reporter query toolbar.

The SQL Code Viewer appears.

The Query Editor supports correlation names for tables, permitting you to specify auto joins. By default, the correlation name is the table name; you can modify this in the Alias entry field.

After the relations are generated, you can define table joins or generate them automatically by checking the Automatic Joins Research command on the Query Editor Edit menu.



Query Editor Fields

The following are descriptions of the fields in the Query Editor:

Tables List

Indicates the names of tables available to include in the report document. The tables you select appear as icons in the Query Definition pane.

Table Name

Indicates the name of the selected table

Alias

Specifies an optional alternate name of the table you selected

Primary Master (M)

Specifies the primary master table of the query. Only one M table is permitted. Clicking the M button creates a primary Master-Detail relationship between the tables you have selected.

Secondary Master (m)

Specifies the secondary master table of the query. Multiple m tables are permitted (1:1 relationship with M table). Clicking the m button creates a secondary Master-Detail relationship between the tables you have selected.

Primary Detail (D)

Specifies the primary detail table of the query. Only one D table is permitted (1:N relationship with M table). Clicking the D button creates a primary Detail-Master relationship between the tables you have selected.

Secondary Detail (d)

Specifies the secondary detail table of the query. Multiple d tables are permitted (1:1 relationship with D table). Clicking the d button creates a secondary Detail-Master relationship between the tables you have selected.

Query Definition Pane

Shows icons representing the tables you have selected; relationships between tables are shown as labeled connectors. A “1” on the connector between two tables indicates a one-to-one relationship; an “N” indicates a one-to-many relationship.

Pattern

Defines a pattern-matching string to restrict the names of tables to be listed; for example, s% would retrieve only table names beginning with “s”

Table

Specifies the name of selected table and its owner



Qualify Table Names

Table names can be qualified by a schema name. (A schema is a named collection of tables in a database.) Reporter can display multiple identical table names; therefore, it may be necessary to prefix the schema to the table name to clarify which table is being referenced.

You can choose whether you want to use schemas. Using schemas means that you can specify a particular table that will not be dependent on the user or DBA. You can also include in a query tables of the same name but with different owners.

To select whether a schema (owner) should be used to qualify the selected table name in the query

In the Query Editor, click Edit, Add Schema to Query Table or Edit, Remove Schema from Query Table.

How You Can Change the Query Table Owner

When you are defining or editing a query, multiple tables having the same name—but different owners—may appear. Reporter issues a warning when it detects a table-owner pair that is not a part of the current database. Mismatches are flagged with an asterisk (*), and the table name appears in CC_RED.

To prevent any problems related to mismatched ownership of tables, we recommend that you reconcile tables in the query with the current database. Mismatches can happen if a report is imported from a different database or if tables existing at the time the report was first created have been dropped.

Auto Search for Table Owners

Reporter enables the Auto Search for Table Owners command when it detects a mismatch. (You can manually enable this option by clicking Edit, Auto Search for Table Owners in the Query Editor.)

Auto Search tries to match tables with appropriate owners—Current User, DBA, someone else—in that order. Table names of successfully matched query tables appear in CC_BLUE. These matches, however, are only Reporter's suggestions; they cannot be saved directly. Permanent reassignment of owners can be accomplished only by using the Change Query Table Owner option.



Change Query Table Owners

The Change Query Table Owner option lets you assign new owners to tables defined in a query.

To assign new owners to tables defined in a query

1. Select a table in the Query Definition pane of the Query Editor.

2. Select a table with the same name from the Tables List.

3. Click Edit, Change Query Table Owner in the Query Editor.

Important! Changing ownership of a query table may invalidate existing join definitions. It is the user's responsibility to verify that existing join definitions are still valid.

Add Restrictions to the Where Clause

The Where Clause Editor lets you define the selection criteria (that is, restrict the criteria) for the tables you want the database to access. You can create or delete where clause restrictions.

To create or edit a where clause restriction in the Query Editor

1. Click Edit, Where Clause.

The Where Clause Editor appears.

In the Where Clause Editor, toolbar buttons and corresponding menu commands are available for creating, editing, and deleting a where clause restriction.

Toolbar buttons and corresponding menu toggle commands are also available for viewing the where clause restriction text, for viewing the where clause restriction graphically, and for viewing SQL code for the where clause.

2. Click Edit, Graphic in the Where Clause Editor.

3. Double-click the graphic (rectangular box) in the graphic area of the Where Clause Editor.

The Reporter Query Columns dialog appears.

4. Select a table name and a column name.

5. Click Select.

The Reporter Query Restriction dialog appears.

The Reporter Query Restriction dialog shows the selected table/column name and lets you add or edit a query restriction.

6. If required, change the AND to OR by clicking the down arrow for the drop-down box on the upper left side of the dialog.



7. If required, change the operator by clicking the down arrow for the drop-down box on the left side of the dialog.

8. Type the text for the desired restriction in the entry field on the right.

9. Click OK.

The Where Clause Editor appears, showing both the text for the restriction you entered and its graphic representation.

10. Repeat steps 3 through 9 to add other restrictions to the where clause.

11. Click Save to save your work.

To delete a where clause restriction

1. Click the box associated with the restriction you want to delete in the graphic area.

2. Click Edit, Delete in the Where Clause Editor.

To close the Where Clause Editor

Click Close in the upper right corner of the window.

A confirmation pop-up appears.

Create Table Join Definitions

The Edit menu in the Reporter Join Query Editor lets you create, edit, or delete table join definitions.

To create a table join definition

1. Click a join icon in the Query Definition pane of the Query Editor.

The Reporter Join Query Editor appears—unless no joins are currently defined, in which case, OpenROAD automatically opens the Join Definition dialog.

2. Click Edit, Create in the Reporter Join Query Editor.

The Reporter Join Definition dialog appears.

To select columns for the table join definition

1. Click the folder icon to the right of the Column field associated with the Left Table.

The Select a Column dialog appears.

2. Select the name of the table in the Table Name list for which you want to specify a column.

3. Select the name of the desired column in the Column Name list.



4. Click Select (or press Enter) to add the selected column to the table join definition.

Repeat this procedure to add other columns to the table join definition.

In the Reporter Join Query Editor, the column selections are displayed under these headings: Left Table, Left Column, Right Table, and Right Column.

5. Click Close.

If all required joins between tables have not been defined, a confirmation pop-up dialog appears.

To edit joins

Click Edit, Edit Joins in the Query Editor.

You can modify the default joins, created when you added a table, to make them user-defined joins. User-defined joins are not recalculated automatically. Click Edit, Joins Research in the Query Editor to perform this operation. (The user-defined joins then become default joins.)

Specify Sort Columns

Sort columns may be table columns or calculated fields created in the document. Sort columns determine the ordering of data in a report. When more than one sort column is specified, the higher on the list an item appears, the more significant the item; for example, if you sort by student name, “course” generates output ordered by student name and, within each name, by course.

To specify table sort columns

1. Click Edit, Sort in the Query Editor.

Note: You can also access the Reporter Sort Columns dialog by clicking Edit, Query Edit Sort.

The Reporter Sort Columns dialog appears.

In the Show field, All Columns in Selected Tables is displayed. You can click the down arrow to select Column/Expression in Select Clause.

Selecting All Columns in Selected Tables lets you select table and column names. Selecting Column/Expression in Select Clause only lets you choose alias names.

2. Select a table name.

The columns associated with the selected table appear in the Column Name field.

If you selected Column/Expression in Select Clause, select an alias name and skip to Step 4.

Setup/Cleanup


3. Select the column name that you want to add to sort columns.

4. Click Add to Sort Columns.

The selected column (or alias) name appears in the Alias field in the lower section of the dialog.

5. Repeat steps 2 through 4 for each column you want to add to sort columns.

If you want to remove any columns from the list, select the column name and click Remove from Sort Columns.

If you attempt to remove a column that has been defined as a break column, a Message pop-up appears.

Click OK to close the Message pop-up.

6. Click the up or down arrows to change the order of the sort columns.

Clicking the up arrow moves the selected item up one line. Clicking the down arrow moves the selected item down one line.

7. Click the toggle field under Order Type to select ascending or descending sort order for each sort column.

The default is asc (ascending).

8. Click OK to return to the Reporter Join Query Editor.

Setup/Cleanup

The Setup/Cleanup command lets you embed SQL statements that do not involve data retrieval into Reporter. The Reporter utility executes setup statements before it processes the main report query; cleanup statements are processed after the main report query.

Embedded groups of SQL setup statements can perform tasks such as creating temporary tables for use in the report document. Reporter executes the setup statement after substituting Reporter utility variables into the SQL statements.

Embedded groups of SQL cleanup statements can perform tasks such as dropping temporary tables created in the setup section. Reporter executes the cleanup statement after substituting Reporter utility variables into the SQL statements.

Save the Report Query and Document


Use Setup/Cleanup

You use Setup/Cleanup in the Query Editor.

To use Setup/Cleanup

1. Click Edit, Setup/Cleanup.

Note: You can also access Setup/Cleanup by clicking Edit, Query, Setup/Cleanup in the Reporter.

The Setup/Cleanup dialog appears.

2. Type the desired SQL statements in either the Report Setup or Report Cleanup multiline entry fields.

3. Click Verify.

If there are errors, a Message pop-up appears, followed by an SQL Compilation Errors in User Code Editor, which lets you view the errors.

4. Click OK to close the editor.

5. After you have corrected any errors in the Setup/Cleanup dialog, click Execute only if you want the Setup or Cleanup statements to take effect immediately (which may be necessary if the report runs against temporary tables).

After you have defined the report, you can execute Cleanup to remove the temporary tables.

6. Click Save to save the Setup or Cleanup statements.

You are returned to the report document.


After creating or modifying report queries and documents, you should save your changes.

To save the report query

1. Click OK on the Query Editor toolbar.

If you have not defined all required joins, a confirmation pop-up appears.

Note: If all joins have been defined, skip to Step 5.

2. If you click View Errors, the Reporter Text Editor appears.

3. Click Close.

You are returned to the Query Editor. You can then finish defining joins.



4. Click OK again after you have corrected the problem.

The Reporter Document Properties window appears.

5. Click OK.

The header report page is displayed.

To save the report document

Select one of the following save options:

Save

Click Close in the upper right corner of the window.

A standard confirmation pop-up appears. Click Save Before to save the report document.

Save As

Lets you save a report document under a new name:

1. Click File, Save As in the Reporter.

The standard Save As dialog appears.

2. Enter a new report document name in the File Name field.

3. Click OK.

Revert to Last Saved

Removes changes made to the working copy of the report document since it was last saved or checked in:

1. Click File, Revert to Last Saved with the report document selected.


2. Click OK to revert to the last-saved report, losing changes made in the current session.

The current version of the report document is deleted and the last saved copy in the database is displayed.

Delete

Deletes a report document:

1. Click File, Delete in the Reporter with the report document you want to delete selected.

A standard confirmation pop-up appears.

2. Click OK to confirm that you want to delete the report.

How You Can Design Report Documents



After you have specified your document's format and defined a query, the next step in creating a report document is to design the report's layout by selecting and arranging fields. This is where you begin to literally “draw” the report.

The fields you draw are placed in either a header, detail, or footer section of the report. For more information, see Report Sections (see page 496).

Report Sections

A report section is the basic unit of layout in a report. Sections can contain fields, text, and graphics. The sections in a Tabular Reporter document are created automatically. The Form and Page Layout types of report presentation have only detail sections (pages) to which can be added text, fields, and graphics.

Report Section Types

The following are the three report section types in a Tabular report document:

Header Report Page

Is the first page of the report. A header report section (or page) can be used for report titles and dates. It can be printed as a separate report title page.

Detail Report Page

Contains the main body of the report's data. It can contain page headers and footers. The entire body section prints for each row of data retrieved from your database.

Footer Report Page

Is the last page of the report. A footer report page may be used for any purpose. Typically, footer report pages are used to display aggregate summary information.



How You Can Work with Sections

Working with report sections in Reporter requires only that you take note of which types of fields can be added to each section.

Header Section

The header section (header report page) is created automatically when you create a Tabular report. You include whatever information you want to appear in the header by simply adding fields in the work area.

Select the appropriate tools from the field palette, then click in the work area and drag the cursor to draw the types of fields you want to include in the report's header section. For example:

To create a report title, add a free trim field, then type the title of the report in the field.

To include a date in the header section, add a date field.

To include a logo or other image, add an image field.

Note: The Form report type and the Page Layout template do not have header or footer sections.

To view a header report page

Click View, Header Report.

The window title changes to Header Report Page.

Detail Section

The detail section (detail report page) contains the body of the report. It is created automatically for all Tabular reports. It is the only section in Form and Page Layout type report presentations.

A detail page for a Tabular report can have page headers and footers. The master row on a tablefield report is part of the page header.

Select the appropriate tools from the field palette, then click in the work area and drag the cursor to draw the types of fields you want to include in the report's detail section.

To view a detail report page

Click View, Detail Page.

The window title changes to Detail Report Page.



Footer Section

A footer section (footer report page) is created automatically when you create a new Tabular report. The Footer section may contain summary information or any other information.

Select the appropriate tools from the field palette, then click in the work area and drag the cursor to draw the types of fields you want to include in the report's footer.

For more information about adding a calculated or aggregate field to the footer page, see How You Can Create Data Fields (see page 500).

To view a footer report section

Click View, Footer Report.

The window title changes to Footer Report Page.

Icons that Let You Navigate a Report

The following icons let you navigate in a report:

Next Page

To go to the next page of the report, or to create a new page, click the Next Page (right arrow) icon in the file toolbar. Alternatively, click View, Next Page.

Previous Page

To go to the previous page of the report, click the Previous Page (left arrow) icon in the file toolbar. Alternatively, click View, Previous Page.

Goto Page

To go to a specific page of the report:

1. Click View, Goto Page.

2. Select the section or type of field you want to go to from the Go to What option field, or enter a page number in the Enter Page Number entry field.

3. Click Close.

The specified OpenROAD Reporter section or page appears.

Insert New Page

To insert a new page in the report, click Edit, Insert New Page. The new page is added following the current last page of the report. (Form type reports only.)

Delete Current Page

To delete the current page from the report, click Edit, Delete Current Page. (Form reports only.)



How You Can Select and Position Fields

A report document can contain a variety of field types. The Reporter field palette and Insert menu commands let you create the types of fields shown in the following list, or you can include fields from an existing page layout template:

Data Fields

Static Text Fields

Shapes & Images

Special Fields

Fields from Page Layout

You create and modify fields in the sections of your report. After fields are created, you can manipulate their properties (line width and height, borders, font type, font size, color, and so on) to make the report more attractive.

All field types have properties associated with them. These properties can be set or modified in dialogs. To access the Properties dialogs, use the secondary mouse button to click the field.

To delete a field

Select the field and press the Delete key.

Edit Menu Commands for Manipulating Fields

The Edit menu contains the following commands for manipulating fields:

Cut

Removes the selected field to the clipboard. From there it can be pasted into a new location.

Copy

Copies the selected field to the clipboard. From there it can be pasted into a new location.

Paste

Pastes a copied or cut field from the clipboard to the desired location.

To paste a field

Position the cursor, and then click the secondary mouse button to paste the field. Alternatively, click Paste in the file toolbar or select Paste from the Edit menu.



Absolute Paste

Pastes a copied or cut field to the same (absolute) location on a different page.

To cut or copy a field

Go to a different page and then click Edit, Absolute Paste.

Duplicate

Duplicates the selected field below itself.

To duplicate a field

Select the field, then click Edit, Duplicate. You can then drag and drop the duplicated field wherever you want to position it.

How You Can Create Data Fields

A report data field references an individual piece of data. It can be either a database field, which displays information from one column in a query result, or a computed field, which displays a value computed from the data in a function or formula.

After you have defined a query, you can add data fields to the report document.

A data field maps to a field in the query result that you use to supply data for the report.

Data field creation methods include the following:

Single Field

Fields from Table

Variable Field

Each of the data field creation methods are described in the following sections. After data fields are created, they can be modified as described in Modify Field Properties (see page 505).



Create Single Fields

You can use Single Field Creation to create fields that are associated with data in the following ways:

Column of a Selected Table

A Column of a Selected Table type of field is one whose value is determined by the main query when the report is run. It references one of the columns selected from one of the tables specified in the FROM clause of the query.

Single Query

A field associated with a single query gets its value from a query that is not the main query. The query associated with such a field should be a singleton select.

A singleton select query is one for which only one row may be returned. If the query returns more than one row, a runtime error will result. By default, the singleton query is run before the main query; however, by checking the Generate in Main Select toggle when creating the field, the query will be issued in the detail section once for each row returned by the main query.

Calculated Expression

A calculated expression field uses functions and arithmetic operators to compute a value. You define a computed field by combining values in other report fields or by using functions.

To create a single field

1. Click Insert, Data Fields, Create Single Field.


The Reporter DataField List dialog appears.

Note: The Reporter DataField List dialog lists all data fields currently defined in the document. If no data fields are listed, the Reporter DataField Properties dialog appears automatically, allowing you to create a new data field.



3. Select an existing item in the Columns/Expressions list and click Create Field.

Alternatively, to create a new single field using single field creation:

a. Click the N (New) button.

The Reporter DataField Properties dialog appears.

b. In the Reporter DataField Properties dialog, from the Attach To list, select the desired option (Single Query, Column of a Selected Table, or Calculated Expression).

The Reporter DataField Properties dialog changes to reflect the option you select in the Attach To list field.

To attach a single field to a “Single Query”

1. Enter an alias name.

The alias name is used to create a variable in the generated report code.

Note: The alias name must be used in the select statement. The select statement must retrieve only one row and column.

The Attached Query multiline entry field displays the query associated with the Single Query field. This query is specified when the field is created. The Generate Query in Main Select toggle determines when the attached query is issued. It is independent of the main report query generated automatically by Reporter.

2. Click Check to validate your SQL request.

3. Click in the Generate Query in Main Select toggle field if you want the query to be issued in the detail section once for each row returned by the main query.

4. Click OK.

The Reporter DataField List dialog appears with the selected column added to the list.

5. Click Create Field.

The field you created appears in the work area.

6. Click File, Save to save your work.

To attach a single field to a “Column of a Selected Table”

1. Select the desired table (or accept the default) and column.

The Selected Column field displays your choice.

2. Select the Is a Break Column check box if you want to insert a page break.

3. Click OK.

The Reporter DataField List dialog appears with the selected column added.




The field is created and added to the Detail page of the report document.


To attach a single field to a “Calculated Expression”

Note: When you select Calculated Expression from the Attach To list, the lower half of the Reporter DataFields Properties dialog changes to display four tables—Tables, Columns, Functions, Operators—from which you can select the desired values.

1. Double-click the function you want to use in the Functions list field.

For more information, see Types of Functions (see page 503).

2. Double-click the arithmetic operator you want to use in the Operators list.

3. Double-click the appropriate column name in the Columns list.

The result of your selections appears in the Expression Text entry field. You can edit this text if you want.

4. Click Check to validate the syntax of your user-defined expression.

5. In the Alias Name field, enter the name of the calculated field you are creating.

6. Click OK.

The Reporter DataField List dialog appears with the new calculated field.


The new data field is created and added to the report document.


Types of Functions

OpenROAD Reporter supplies various functions that you can use to create computed fields. The functions perform sophisticated calculations. For example, you can use functions to rank field values or to return the future value of an investment.

When you use a function in a computed field, you must specify certain variables on which the function operates.



The following descriptions summarize the functions available in OpenROAD Reporter:

Aggregate Functions

Perform calculations (for example, counting, summing, and averaging) on grouped data or data for the entire report. Aggregate functions ignore Null values in their computations. For example, the Avg() function does not include the Null value when it computes the average.

Generally, you insert a computed field containing an aggregate function in a report header or footer. The placement of the field determines the value returned by the function.

Note: If your report contains a large amount of data, you can improve performance and memory usage by placing aggregate functions in the report footer. Placing an aggregate function in a report header requires the most time and memory to evaluate.

String Functions

Manipulate text strings and fields with a text data type in the report definition. For example, text functions let you compare strings, insert and extract characters within strings, and convert lowercase strings to uppercase strings.

Date and Time Functions

Calculate dates and times using serial numbers. For example, you can use a function to add a number of weeks to a date and get the future date back.

Numeric Functions

Perform common mathematical operations on data defined in the report definition, such as raising a value to a power or returning an absolute value.

Conversion Functions

Convert a field or value of one data type to a value of another data type. For example, Reporter provides functions that convert date values to number values or text values, number values to date values or text values, and so on.



Create Fields from Tables

You may create more than one field at a time, but all fields that are created together must be associated with a single table in the main query.

To create fields from tables in the main query

1. Click Insert, Data Fields, Fields from Table.


When you release the mouse button, the Reporter Table Selection dialog appears.

3. In the Tables list, select the table from which you want to select columns.

The Selected Table field displays the corresponding table name.

4. Click the toggle field to the right of the desired column in the Columns list.

An x should appear in the toggle field.

5. Click the Select/Unselect toggle field to select all items in the Column List.

6. In the Pattern field, enter a pattern-matching string (eight characters maximum) to restrict the names of columns to be listed; for example, d% would retrieve only column names beginning with “d”.

7. Click in the Create Fields Labels toggle field if you want labeled table columns.

8. Click Create.

The detail page of the report appears and the selected table fields are displayed.


Modify Field Properties

Data fields are edited in the Reporter DataField Properties dialog. After data fields have been created, the distinction between the methods used to create them—Single Field or Fields from Table—goes away. Fields are edited individually. When you select the field you want to edit, the dialog that appears reflects the properties of that field as well as its data type.

To modify data field properties

1. Click Tools, DataField List.

The DataField List dialog appears.

2. Click Edit (the middle icon on the right side of the dialog).

A “No Details” version of the Reporter DataField Properties dialog appears.

3. Click All Details if you want to view more detail.



4. Make the desired edits.

5. Click Open API Code to view or edit the code for the field, if desired.

6. Click Save to save your edits.

Create a Variable Field

The variable field creation option is only for fields whose value is obtained by explicit assignment rather than by SQL selection. Variable fields are created and managed by the user. They correspond to local variables or parameters in the generated 4GL procedure.

You can create variable fields in the Variables List dialog.

To create a variable field

1. Click Insert, Data Fields, Variable Field.


The Variables List dialog appears.

Note: The Variables List dialog lists all existing variables. If there are no available variables, the Variable Properties dialog appears automatically, letting you choose an appropriate variable or create a new variable.

3. Select the desired variable from the Variables list.


The variable field is added to the report document.

To create a new variable

1. Click the N (New) button on the right side of the Variables List dialog.

The Variables Properties dialog appears.

2. Set the variable properties as desired.

For more information, see Variable Properties (see page 507) and Modify Variable Field Properties (see page 509).

3. Click OK.


4. Click Close, or click the N (New) button to create another new variable.

When you click Close, the report document appears.



Variable Properties

The Variable Properties dialog contains the following options:

Name

Specifies the name of the variable field. You can click the file folder icon to select a variable name from a list of available variables.

Data Type

Specifies one of the following data type options:

Varchar—variable-length text, to 4096 characters

Smallint

Integer—a four-byte integer

Float—a decimal number

Money

Date

Note: For multiline entry fields, select Varchar and specify the maximum length of the field. Selecting any of the other data types (Smallint, Integer, Float, Money, or Date) defaults to a single-line entry field.

Length

Specifies the desired field length

Nullable

Specifies whether the variable field is nullable

Default Value

Lets you select either System or String as the default value

Format

Specifies single line or multiline format. This field is displayed when the selected Data Type is varchar.

Display Size

Specifies the display size

Set Maximum Characters

Specifies the maximum number of characters allowed by a single-line entry field's Format or Data Type

Rotation

Specifies the desired rotation in degrees. Changes to rotation appear only after the report is run.



Template

Is displayed when the selected data type is not varchar. Click the down arrow to display a list of available templates.

Expression

The entry fields in this edit control—Report's Header, Page's Header, and so on—accept expressions or values that may be assigned to the variable. These expressions can reference other variables and fields that are already defined.

The various locations listed—Headers, Detail Sections, Footers—represent the locations in the report where the assignment takes place. Expressions can be entered into all locations. If more than one location is specified, the Generate Print In field is activated for specifying the location from which the value is used for printing.

Is Parameter

Specifies a variable as a parameter of the generated report (in which case, the value of the variable is determined during the report execution)

Report's Header

Lets the user enter expressions or values to be assigned to the variable at the report's header location

Page's Header

Lets the user enter expressions or values to be assigned to the variable at the page's header location

Detail Section

Lets the user enter expressions or values to be assigned to the variable at the detail section's location

Page's Footer

Lets the user enter expressions or values to be assigned to the variable at the page's footer location

Report's Footer

Lets the user enter expressions or values to be assigned to the variable at the report's footer location

Generate Print In

Indicates the location from which the value is used for printing. This field is activated if both Page Header and Footer are selected.



Modify Variable Field Properties

You can modify variable field properties in the Reporter Variables List dialog.

To modify a variable field

1. Click Tools, Variables List.

The Reporter Variables List dialog appears.

2. Click the Edit icon on the right side of the dialog.

The Variable Properties dialog appears.

3. Make the desired changes.

4. Click OK.


5. Click Close.

The report document appears.

Delete a Data Field

You can delete a data field using the DataField List dialog.

To delete a data field

1. Select the data field you want to delete and press the Delete key.

The DataField List dialog appears.

2. Click the Delete button (the bottom icon to the right of the Columns/Expressions list).

A standard confirmation pop-up appears.

3. Click OK to delete the data field.

How You Can Group Fields

After you have created fields, you can group them in the report document work area using the following commands:

TableField

StackField

MatrixField

You access these commands from the Layout menu. Select the Group command, then select the desired command from the slide-off menu.



Group Table Fields

A table field presents data in rows and columns.

To group fields into a table field

1. Select any field you want to include in the group.

Sizing handles appear around the selected field.

To select several fields, hold down the Shift key while drawing a rectangle around them with the mouse.

When you release the primary mouse button, all selected fields are highlighted.

2. Click Layout, Group, TableField.

The TableField Properties dialog appears.

The TableField Properties dialog lets you edit the current table field. The field or fields you want to edit must be selected.

3. Set the properties as desired.

For more information, see Table Field Properties (see page 224).

4. Click OK.

You are returned to the detail page of the report, which now displays a table field.

Table Field Properties

You can set the following properties for table fields:

Has Column Title

Specifies whether the column gets a title. Set to ON to add to the top of each column a trim corresponding to the title of the column. This trim behaves the same way as trim created from the palette, for example, you can change the value by clicking the Select Mode icon in the field palette.

Has Fixed Height

Lets you define the table field size. If the number of lines to be printed is fewer than the visible rows number, blank lines are printed to fill in the table field.

Number of Visible Rows

Lets you select the number of rows you want in a generated a table field. The table field continues to the following page if the database selection returns more than the desired number of lines for the table field. The table field may have fewer than the number of visible rows if the selection returns fewer rows (no blank lines).



Group Stack Fields

A stack field appears as a set of fields that remain aligned if you rearrange or reorder them. The stack can include any combination of fields. A stack field aligns fields either horizontally or vertically, and keeps them together in a group.

To group fields into a stack field

1. Select the fields you want grouped.


To select several fields, hold down the Shift key while drawing a rectangle around them. When you release the primary mouse button, all selected fields are highlighted.

A solid outline appears around the grouped fields.

2. Click Layout, Group StackField.

The specified fields are grouped together into a stack field as indicated by the solid outline.


For more information, see Set Stack Field Properties (see page 511).

Set Stack Field Properties

You can set Stack Field properties in the StackField Properties dialog.

To set stack field properties

1. Right-click the stack field.

The StackField Properties dialog appears.

2. Set the desired properties, which are described Stack Field Properties (see page 512).

3. Click OK, or click Open API Code to view or edit the Open API code.

If you click OK, you are returned to the detail page of the report, which displays the stacked field.

More information:

Edit Open API Code (see page 515)



Stack Field Properties

You can set the following properties for stack fields:

Orientation

Specifies whether the field is to be displayed vertically or horizontally

Default Child Gravity

Selects the position of each simple field relative to its cell in a stack field. Depending on the Orientation setting, there are either three vertical options or three horizontal options.

Child Margin

Sets the distance (in 1000ths of an inch) between the individual stack field components and the Left, Right, Top, or Bottom boundary of the stack field

Rotation

Defines the desired rotation in degrees. This setting overrides any child field setting. Changes to rotation appear only after the report is run.

Group Matrix Fields

A matrix field appears as a rectangle that contains fields arranged in rows and columns. The component fields stay aligned even if you rearrange or reorder them. The matrix field can include any combination of fields. A matrix field presents data in a rectangular array.

To group fields into a matrix field

1. Select the fields you want grouped.


To select several fields, hold down the Shift key while drawing a rectangle around them. When you release the primary mouse button, all selected fields are highlighted.

2. Click Layout, Group, MatrixField.

The specified fields are grouped together into a matrix field as indicated by the solid outline.


For more information, see Set Matrix Field Properties (see page 513) and Matrix Field Properties (see page 513).



Set Matrix Field Properties

After creating a matrix field, you can edit its properties in the MatrixField Properties dialog.

To set matrix field properties

1. Right-click the matrix field.

The MatrixField Properties dialog appears.

2. Set the desired properties, which are described in Matrix Field Properties (see page 513).

3. Click OK, or click Open API Code to view or edit the Open API code.

When you click OK, you are returned to the detail page of the report, which displays the matrix field.

More information:

Edit Open API Code (see page 515)

Matrix Field Properties

You can set the following properties for matrix fields:

Default Child Gravity

Selects the position of each simple field relative to its cell in a matrix field

Child Margin

Sets the distance (in 1000ths of an inch) between the individual matrix field components and the Left, Right, Top, or Bottom boundary of the matrix field

Collapse Policy

Specifies what happens when an entire row or column in the matrix is empty. Valid options are:

NONE

Specifies that empty rows and columns are allowed and maintained. If you set the Rows and Columns properties, the settings are enforced.

BOTH

Specifies that empty rows and columns are removed automatically, as soon as the last field is removed from the row or column. Setting either the Rows or Columns property has no effect.



EMPTY ROWS

Specifies that empty rows are removed automatically, as soon as the last field in the row is removed. Setting the Rows property has no effect. However, empty columns are maintained, and the Columns property is enforced.

EMPTY COLUMNS

Specifies that empty columns are removed automatically, as soon as the last field in the column is removed. Setting the Columns property has no effect. However, empty rows are maintained, and you can set the Rows property.

Default: BOTH

Rotation

Defines the desired rotation in degrees. This setting overrides any child field setting. Changes to rotation appear only after the report is run.

Note: If any grouped fields overlap other fields, use the Cut and Paste toolbar buttons to move fields around so they do not block other fields.

Static Text Fields

Static text fields include the following:

Free Trim

Box Trim

Free Trim from File

Box Trim from File

More information:

Create a Free Trim or Box Trim Field (see page 514)

Create a Free Trim or Box Trim Field

You can create a free trim or box trim field or use one from another file.

To create a free trim or box trim field

1. Click Insert, Static Text Fields, Free Trim or Insert, Static Text Fields, Box Trim.

2. Drag the cursor in the work area to draw the field.



3. Type the desired text in the Free Trim or Box Trim field.

If you want, right-click to access the corresponding Properties dialog to set the rotation property or view or edit the Open API code. For more information, see Edit Open API Code (see page 515).

4. Click OK to close the dialog, save the changes, and return to the report document.

To use free trim or box trim fields from another file

1. Click Insert, Static Text Fields, Free Trim from File, or Insert, Static Text Fields, Box Trim from File.

The Select File Name dialog appears.

2. Select the name of the file containing the trim you want to copy.

3. Click Open.

Fuse Text from Separate Static Fields

You can combine the text in two separate static fields.

To fuse two texts

1. Select one of the two fields you want to combine. Hold down the Shift key to select the second field.

A solid border outlines each field.

2. Click Edit, Fusion of 2 Texts.

A solid border appears around the two fields that are now combined into one.

Edit Open API Code

Several properties dialogs give you access to the Open API Code Editor/Browser for Field, which lets you edit code for the selected field.

To edit or view the Open API code for the field

1. Click Open API Code in the Free Trim or Box Trim Properties dialog.

The Open API Code Editor (or Browser) for Field appears.

2. Edit the Open API code in the Replace with Code pane.

If you change your mind, click Reset to Default.

3. Click OK to generate the code and return to the report document.



How You Can Use Shapes & Images Fields

You can use shapes and images to enhance the appearance of the report document.

Click the desired icon in the field palette:

Create Line

Create Rectangle

Create Ellipse

Create Image Trim

Alternatively, click Insert, Shapes & Images, then select the desired shape or image field command from the slide-off menu. For more information, see Create, Move, or Resize Shape Fields (see page 516) and Create Image Fields (see page 517).

Create, Move, or Resize Shape Fields

Shape fields include graphic objects such as lines, rectangles, and ellipses.

To create a line, rectangle, or ellipse

1. Click the appropriate icon in the field palette.

2. Click in the work area and drag the cursor to draw the selected shape.

Note: A line cannot extend from one report section to another.

To move a line in your report document

1. Click the line to select it.

Selection handles appear at either end of the line.

2. Position the cursor anywhere on the line except on a selection handle and drag the line to a new location.

To resize a line in your report document

1. Click the line to select it.

Selection handles appear at either end of the line.

2. Drag a selection handle at one end of the line to a new position.



To move a rectangle or ellipse

1. Click the shape to select it.

Selection handles appear around the border of the shape.

2. Position the cursor anywhere in the shape except on a selection handle and drag the shape to a new location.

To resize a rectangle or ellipse in your report definition

1. Click the shape to select it.

Selection handles appear around the border of the shape.

2. Drag any selection handle to a new position to resize the shape.

Modify Shape Field Properties

You can modify shape field properties in the appropriate Properties dialog.

To edit shape field properties

1. Right-click the field you want to edit.

The appropriate Properties dialog—Segment Shape, Rectangle Shape, Ellipse Shape—appears.

2. Enter the rotation property, if desired.

Note: Changes to rotation appear only after the report is run.

3. Click Open API Code to view or edit the code if you want.

The Open API Editor for Field appears.

For more information on core editing procedures, see Edit Open API Code (see page 515).

4. Click OK to save your work and return to the report document.

Create Image Fields

Image fields include images in GIF, BMP, or RAST format.

Note: To include a PostScript image, you must use a conversion tool to convert the image to a supported format.



To create an image field

1. Click Insert, Shapes & Images, Image.


The ImageField Properties dialog appears.

In the ImageField Properties dialog, Image Trim is selected by default. Image Trim refers to a static image (comparable to text trim). Image Field refers to a dynamic image, which is selected at runtime based on the query.

For instructions to create each type of image, see the appropriate procedure, following.

To create an image trim field

1. Click the File folder button to the right of the Image File field.

The Current Selection dialog appears.

2. Select a file that includes an OpenROAD compatible image.

This file name is used when the report is printed.

3. Click Open.

You are returned to the ImageField Properties dialog, and your selection is added to the Image File Entry field.

4. Click Show Bitmap to preview the static image.

5. In the DB Storage edit control, click the arrow to the right of the option field (just below the Image Name field) and select one of the following options:

Insert into Catalog

Do Not Insert into Catalog

Select from Catalog

If you choose Select from Catalog and then click the file folder to the right of the Image Name entry field, the Reporter Images dialog appears.

6. To select an image from the catalog, click All Images in Database, or click one of the three options under Images Referenced In (the default):

Current document

All documents by current user

All documents by all users

The content of the list of images in the database depends on criteria as defined by other options.



7. Click Select Image.

You are returned to the ImageField Properties dialog.

Note: In the Options edit control of the ImageField Properties dialog, you can define how the image will be displayed in the field.

8. Click the down arrow in the Behavior field to access a drop-down box.

9. Select one of the following display choices:

Scale Image Width & Height to Field

Scale Image Width to Field

Scale Image Height to Field

Clip Image to Field

Image Unchanged

10. Click Show Bitmap to preview the static image, which is displayed in the ImageField Properties dialog.

11. If desired, click Open API Code to view the code in the Open API Code Editor/Browser for Field.

12. Click OK to import the selected image and return to the report document.

To create a dynamic image field

1. Click Image Field in the ImageField Properties dialog.

The Reporter DataField List dialog appears.

Note: This dialog lists all existing table columns. If there are no columns listed, the Reporter DataField Properties dialog appears automatically, allowing you to choose an appropriate table.



2. Select the desired table column from the Columns/Expressions list. (See Note at the end of this section.)

Alternatively, to create a new entry, click N (New).

The Reporter DataField Properties dialog appears:

a. Select a table from the Tables list field.

b. Click the folder button to the right of the Alias Name field.

The Reporter Variables dialog appears.

c. Double-click the appropriate variable in the Select a DataField list field.

The variable is added to the Columns list field and the Selected Column entry field in the Reporter DataField Properties dialog; the DbHandle toggle is checked by default.

d. In the Alias Name field, type the name of the image you are creating.

e. Click OK.

The Reporter DataField List dialog reappears, displaying the new entry.


You are returned to the Reporter DataField Properties dialog.

4. Click OK.

The dynamic image field indicated by “Image” is added to the report document. The actual image is not visible until you run the report.

The placement and sizing of a dynamic image field you create can be tested using a sample graphic. To create a sample image in the report document, click the Image field using the secondary mouse button to access the ImageField Properties dialog. Then follow the instructions in Image Trim, beginning with Step 3.

Note: If the selected column is not a DbHandle, a pop-up message prompts you to click N (New) to select an appropriate entry, or click Edit to mark an existing name as a DbHandle. (DbHandle is the term OpenROAD uses for a link into a bitmap stored in the database.)

In either case, the DataField Properties dialog appears:

a. Select an appropriate column name (if you clicked New).

b. Click the DbHandle edit control.

c. Click OK to return to the Reporter DataField List dialog.

d. Click Create Field.



Modify an Image Field

You can modify an image field in the ImageField Properties dialog.

To modify an image field

1. Click Tools, Images List.

The ImageField Properties dialog appears.

2. Make the desired modifications.

3. Click OK.

Special Fields

OpenROAD Reporter provides two special fields:

Date & Time

Displays the current date, time, or both

Page Number

Displays the page number

Create a Date & Time Field

You can create a field that displays the date and time.

To create a Date & Time field

1. Click Insert, Special Fields, Date & Time.

2. Click in the work area and drag the cursor to draw a field (rectangular area). When you release the mouse button, the DateField Properties dialog appears.

The date and time are formatted using a template.

3. Click OK to accept the current template, or for a list of common date and time templates, click the file folder icon.

The Example Date Templates dialog appears.

4. Use the slider to browse the list of templates, and then select the desired template.

5. Click Select.

The selected date and time field appear in the report document.



Insert a Page Number Field

You can create a field that displays the page number using the Page Number Properties dialog.

To create a Page Number field

1. Click Insert, Special Fields, Page Number.

2. Click in the work area and drag the cursor to draw a field (rectangular area). When you release the mouse button, the Page Number Properties dialog appears.

The Page Number Properties dialog lets you specify page number layout. The page number is formatted using a template.

3. Click the Template file folder icon for a list of common page number templates.

The Example Page # Templates dialog appears.

4. Select the desired template and click Select.

The selected page number field appears in the main report window.

Create Fields from a Page Layout Template

Fields from a Page Layout template can be included in the current report document.

To include fields from a Page Layout template

1. Click Insert, Fields from Page Layout.

The Select a Document dialog appears.

2. Select a Page Layout template from the list.

If you want, click >>> to view an expanded dialog that displays the owner and the properties of the template you selected.

3. Click Select.

The selected template document is opened. You can copy all or part of this document into your report.

Set Page Breaks


Lock or Unlock Fields

You can lock a selected field to a particular location or unlock it from that location. This function lets you move a set of fields without moving the locked one.

To lock or unlock a field

1. Select the field or fields you want to lock or unlock.

2. Click Layout, Position & Size, Lock.

Repeat Creation

The Repeat Creation toggle command lets you remain in create mode. You can then create another field of the same type without choosing select mode each time.

To activate the Repeat Creation feature

Click Insert, Repeat Creation.

Note: Repeat Creation does not apply to free trim and box trim fields; trim fields require you to choose select mode from the field palette to complete or repeat the creation process.

Set Page Breaks

A break column is a column that defines a page break. When the value of a column changes, a data break occurs. In Form type reports, a data break occurs on each row. In Tabular type reports, a data break may occur on any number of columns.

A data break always results in a page break. However, in Tabular type reports, page breaks may occur without data breaks if there are sufficient detail rows to fill the table field. You can determine where page breaks occur in a report by setting page breaks.

To add a page break (break column)

1. Create a data field or select an existing data field.

For more information, see How You Can Create Data Fields (see page 500).

2. Click Tools, Properties.

The Reporter DataField Properties dialog appears.

How You Can Enhance Report Design


3. Click the Is a Break Column toggle field.

4. Click Save.


After you have completed the design and layout of the report document, you can enhance its appearance in the following ways:

Align text, fields, and data—align left, align right, center, or justify

Format the display of text on the page—wrap, truncate, and specify line spacing for text displays

Add borders around selected fields

Change fonts and point sizes

Apply bold, italics, and underlining

Add color

Create a report title page

Control page breaks

You can specify the format of a field before you enter information in it. Reporter applies the formatting as you enter text and continues to use this formatting on new fields until you reset it or reposition the cursor. For example, if you create a new field, it has the same attributes as the previous one.

When you copy or move a field, Reporter also copies or moves the formatting. Select the Copy Attributes and Paste Attributes commands on the Layout menu to apply the attributes of a selected field to another field.

Character Formatting

Character formatting determines how report text—including letters, numbers, punctuation, and symbols—appears on the screen and in print. Character formatting lets you choose:

Fonts and font sizes

Outline

Underlined, bold, or italic styles

Color

Gravity

Select character formatting before you type text in the report.



Align Fields

You can align a field with the left margin or the right margin, or you can center or justify the field. Column data aligns with the column margins. Data outside a column aligns with the page margins of the report.

To align fields

1. Click Layout, Position & Size, Align.

The Alignment palette appears.

2. Each icon in the Alignment palette indicates how a selected field in the document is aligned. (For a description of each icon, see online help.)

Icons are arranged in three rows:

The first row is for vertical alignment.

The second row is for horizontal alignment.

The third row is for aligning fields with the margins.

Vertical and horizontal alignment can be combined.

3. Click the icon (toggle button) for the desired alignment.

To cancel an alignment selection, clear the toggle button.

Align Text

Text within a table field can be left-aligned, right-aligned, centered, or justified.

To align text within a table field

1. Select the text you want to align.

2. Click one of the following buttons on the text toolbar:

Note: Alignment takes effect when the report is run.



Adjust Height and Width

You can adjust the height and width of a field in the report relative to another field.

To adjust the height or width of one field to match that of another

1. Click the field you want another field to match, then hold down the Shift key and select the other field.

2. Click Layout, Position & Size, Adjust Height or Layout, Position & Size, Adjust Width.

The adjusted field appears in the report document.

How You Can Format Text Displays

Text display refers to the placement of text (or database fields containing text) that is too large to be displayed on a single line within the column or page margins of a report. Reporter either wraps the text (continuing it on the next line), or truncates it at the column or page margin. Wrapping applies to text fields but not to number or date fields.

Note: By default, Reporter wraps text in multiline fields and truncates it in single-line fields.

How You Can Add Field Borders

Borders are rectangular boxes around fields. By specifying part of a border, you can outline part of a field, such as its top or bottom. You can choose the width of the border, the pattern (whether the border is a solid or broken line), the style (regular or shadow box); and you can choose square, angled, or rounded corners.

You can place a single border around as many individual fields as you want by clicking the Outline button in the text toolbar. Reporter draws a border around each field until it reaches a field for which the Outline option is not selected.



Add a Border to a Report Field

You can add a field border using the Line Attributes palette.

To add a border to a field in a report

1. Select the composite field (or column or section) that you want to surround with a border.

2. Click Layout, Line Attributes.

The Line Attributes palette appears.

3. In the Line Attributes palette, click the Outline tab.

4. Select the desired Outline options (Width, Pattern, Style, and Type).

5. Click Close to close the dialog and apply the attributes you selected.

To add a partial border (or line) to a field in a report

Follow the procedure for adding a border—but select the segment of a field rather than a composite field—and click the Line tab in the Line Attributes palette.

You can then select a width, pattern, and style for the line.

Change Font and Font Size

You can mix different fonts and font sizes in a report document.

Note: Point size refers to the height of the character. One point is approximately 1/72 inch.

To change font settings in the report

1. Click the down arrow in the font list box in the text toolbar, and select a font style from the drop-down list.

2. Click the down arrow in the font size list box in the text toolbar, and select a size from the drop-down list.

3. Select the Free Trim or Box Trim mode, then click in the work area and drag the cursor to draw a field (rectangular area).



4. Begin typing the desired text.

The text you type will have the font style and size you selected.

Note: To print using a particular font, the font must be installed for the selected printer.

5. Click Bold, Italic, or Underline on the text toolbar to apply one of these options to the selected text, if you want.

Note: The Underline feature takes effect when the report is run.

Set the Default Font

Reporter includes mapping that translates the standard OpenROAD font names into available system fonts. You can modify this mapping by providing font files in standard OpenROAD format.

To change the font mapping

1. Click Tools, Font.

The Reporter Font Setup dialog appears.

2. In the Configuration Files control panel, click the folder icon to the right of the Fonts field to change the path name.


3. Select the desired drive, folder, and file name.

4. Click the folder icon to the right of the Font Size field to change the path name

The Reporter Font Name and Font Size control panels display the current screen font names and font sizes.

To change the screen font name

1. Click the down arrow to the right of the Screen Font Name field.

2. Select the desired font.

3. Click OK.

The new setting takes effect when you create a new report.

To restore the system default font setting

1. Click Default.


2. Click Continue if you want to restore the default.



Change Report Field Colors

You can add color to report fields using the color palette.

To add color to the report field's background, text, and borders

1. Select the field or text to which you want to apply color.

Note: Setting colors with no fields selected results in setting default values for the next field created.

2. Click Layout, Color.

The Reporter Color Properties dialog (color palette) appears.

3. Select the OpenROAD or System color palette.

The default colors at startup are:

Field Part Color

Background White

Foreground Black

Line Black

Outline Black

4. Select the desired field property from the Property list. Available properties are:

Foreground

Background

Line

Outline

5. Use the up and down arrows or the slider to browse the list of available colors.

6. Click the desired color.

The selected color is displayed in the Selected Color box.

7. Click Close.

The color palette applies the new color to the selected part of all selected fields in the report document.



Set Gravity

Use the Gravity command to specify the alignment of one or more fields. This command is used to align fields relative to one another on the current page.

To set gravity on the current page

1. Select the field you want to align.

2. Click Layout, Position & Size, Gravity.

The Gravity palette appears.

3. Click the appropriate button to apply the gravity you want:

Row 1—Top Left, Top Center, Top Right

Row 2—Center Left, Center, Center Right

Row 3—Bottom Left, Bottom Center, Bottom Right

Click the X (no gravity) button if you want to remove the selected field's gravity.

Note: If you select this option, OpenROAD uses the current setting of the ChildGravity attribute in a stack field or matrix field to determine the field's alignment.

4. Click Close to return to the report document.

The setting you selected is applied to the current page of the report document.

Propagate to Children

The Propagate to Children option lets you apply graphical properties—colors, line size, fonts, and so on—to all components of a composite field.

To apply graphical properties to all components of a composite field

1. Select a composite field.

2. Click Tools, Propagate to Children to check the command.

Clear Propagate to Children if you do not want graphical properties applied to all components.

3. Set the desired graphical properties.



Synchronize Properties

The Synchronize Properties option lets you change the behavior of the color or gravity palettes.

If Synchronize Properties is checked and only one field is selected, the open palettes reflect current field settings (for example, the color palette indicates current background color for the selected field; the line attribute palette indicates the current line or outline settings, and so on).

If Synchronize Properties is unchecked, palettes are not refreshed when changing the selected field in the report document.

To change the behavior of the color or gravity palettes

Click Tools, Synchronize Properties to select or clear the option.

Change Grid Spacing

OpenROAD Reporter lets you place fields anywhere on the form or align them on a default grid. Using the grid makes it easier to align fields accurately.

To change grid spacing

1. Click Options, Grid Spacing.

The Grid Spacing dialog appears.

2. Specify the size of the cells in the grid in any of the following ways:

Enter values (in 1000ths of an inch) in the Width and Height fields.

Use the horizontal and vertical sliders.

Click the cell in the center of the model grid; then use the resize handle to adjust the size of the cell.

3. (Optional) Click the Grid On/Off edit control.

When the Grid On/Off toggle field is checked in the Grid Spacing dialog, all fields are automatically aligned with the grid points as you add them to the report document.

4. Click Apply.

Reporter changes all of the grid cells to the specified size.

Preview and Print Report Documents


Duplicate Spacing

Duplicate spacing refers to the relative position where a duplicate field will be created and place in relation to the original field.

To set values for duplicate spacing and apply those values

1. Click Options, Duplicate Spacing.

The Duplicate Spacing dialog appears.

2. Specify the position of the duplicate field in the grid in any of the following ways:

Enter values (in 1000ths of an inch) in the Width (X) and Height (Y) fields.

Use the horizontal and vertical sliders.

Click the B (duplicate) icon in the model grid; then use the resize handle to adjust the position of the duplicate field.

3. Click Apply.

Reporter creates a duplicate field at the position you specified.

How You Can Add Graphics

You can import logos, designs, photos, or other graphics into the report.

For more information, see How You Can Use Shapes & Images Fields (see page 516).


Reporter documents can be previewed and printed by simply specifying the database connection and the file name.

To specify the report you want to print

1. Click File, Print.

The Running Report dialog appears. This dialog lets you run the report against the database and then preview the report online and print a hard copy.

2. If necessary, enter the name of the database to which you want the report to connect.

3. If necessary, enter the connect flag in the DBMS Connect Flags field.



4. If necessary, enter the directory path name in the Output File Directory entry field.

5. Type the name of the report file you want to print in the File field.

Alternatively, click the folder icon to the right of the File field to select the report.

The file name you enter or select is for a temporary file that holds the current report prior to printing. Each time the report is run, this file is overwritten.

6. (Optional) Check the Run Report and Save Report Procedure options.

If the Run Report option is unchecked, the current report does not run and an existing temporary file is printed directly from your disk. You can print any existing report file in this way; however, the data may be out of date because it is not coming from the database at the time of printing.

7. Click Go to run the report against the database.

To preview and print the report

1. Click Preview.

2. Click Go.

The Print Preview window displays the header page of the report.

3. Click Next Page to view the first detail page.

Continue clicking Next Page until you have viewed all the pages you want to preview.

4. Click Print in the Print Preview window.

Alternatively, close the Print Preview window and select the Print option in the Running Report dialog.

The Print dialog appears.

5. Specify the print range (All or Pages); for Pages, enter the From and To page numbers.

If you are printing from the Print Preview window, the default is Current Page; other options are All and Pages.

6. Select the number of copies.

7. Click OK to print the report.

Export a Report


Export a Report

You can export a report document to another file.

To export a report

1. Make the report document you want to export the active document in Reporter.

2. Click File, Export from File.

The Write to File dialog appears.

3. Select the desired file to export, or enter the name of the report document you want to export in the File name field.

4. Click Open.

Delete a Report

You can delete a report in OpenROAD Reporter.

To delete a report

1. Make the report document you want to delete the active document in Reporter.


A confirmation pop-up appears, indicating that the current document will be closed and removed from the catalog.

3. Click Continue (or click Cancel if you change your mind).

A second confirmation pop-up appears, stating that the selected document will be deleted.

4. Click OK to delete the report, or click Cancel to stop the deletion.

RWConv Utility (Report Converer)

The RWConv utility lets you convert existing Report-Writer reports from the system catalog into OpenROAD 4GL procedures that can be run using the Reporter API.

For more information, see Managing and Deploying Applications (see page 537).

RWConv Utility (Report Converer)


Convert a Report Using the RWConv Utility

You can convert a report in Reporter.

To convert a Report-Writer report

1. Click Tools, Procedure List on the Reporter menu bar.

The Report Procedure Tool window appears.

2. Click Reports, Convert RW Reports in the Report Procedure Tool window.

The RWConv Utility dialog appears.

3. In the Output In field, enter the location for the converted report, or use the default directory.

4. Select the report you want to convert from the list of reports, and click Convert.

Click Cancel if you change your mind.

5. After the report is converted, click Run to run the report.

Note: If the converted Report-Writer report procedures will be run from another application, the rwconv.img must be included in the application along with repcomp.img and repopen.img.

Managing and Deploying Applications 537

Chapter 16: Managing and Deploying Applications


How You Can Access the OpenROAD Utilities (see page 537) How You Can Create Application Versions Using the VersionApp Utility (see page 538) How You Can Delete Application Versions (see page 542) How You Can Import and Export Applications and Components (see page 546) How You Can Generate Reports for Applications and Components (see page 555) How You Can Apply Template Changes to Frames and Fields (see page 561) How You Can Compile Applications and Components (see page 565) How You Can Create an Application Image (see page 569) How You Can Image Included Applications (see page 575) Running an Application (see page 577) Set Defaults (see page 584) How You Can Deploy Applications with 3GL Procedures (see page 585) How You Can Use Commands from a File (see page 586) How You Can Deploy a Web-based OpenROAD Application with the OpenROAD eClient Packaging Tool (see page 587) mClient Deployment (see page 611) How You Can Create and Distribute Help Files (see page 613)

This chapter describes the procedures used in managing and deploying your applications after you have completed application development.

How You Can Access the OpenROAD Utilities

OpenROAD provides the following utilities that let you manage your applications and components:

VersionApp (see page 538)

DestroyApp (see page 542)

PurgeApp (see page 542)

ImportApp (see page 546)

ExportApp (see page 546)

DocumentApp (see page 556)

ApplyTemplate (see page 561)

How You Can Create Application Versions Using the VersionApp Utility


CompileApp (see page 565)

MakeImage (see page 569)

RunImage (see page 577)

RunDBApp (see page 577)

QueryImage (see page 559)

You can access the OpenROAD utilities from the OpenROAD Workbench Tools menu. You can also start a utility by entering the appropriate utility command in your workstation window.

Throughout this chapter, the syntax specified for many of the utilities contains the generic parameters database and -uusername. The precise syntax for database may differ on different servers; for example, it may be vnode::dbname on Ingres or one of the Enterprise Access products.

Also, the -uusername parameter may be available exclusively to users with certain privileges. For example, in Ingres, only the database administrator, the Ingres system administrator, or a superuser can use this parameter. It may also include a password (-uusername/password).

Note: For the command syntax for a particular utility, see the section in this chapter specific to the utility.


OpenROAD provides the VersionApp utility for creating numbered versions of an application. A numbered version of an application is an application that has a version number assigned to it and can no longer be modified. This is useful for managing different versions of the same application.

The VersionApp utility "freezes" your working copy of the application and assigns a version number to it. It uses the highest numbered version of each component in the application to create the numbered version of the application.

If you have not saved all of the application's components, you must specify the -p parameter (private). This parameter tells the utility how to handle private versions (that is, those components that are not saved). By default, the utility aborts when it encounters a component that is in use; the -p parameter lets you specify an alternate behavior.



If the working version of a saved component is different from the most recent numbered version, the VersionApp utility saves the working version as a numbered version and includes it in the new numbered version of the application. You can change this behavior by using the -w parameter (ignore).

For a complete description of VersionApp parameters, see Parameters for the VersionApp Utility (see page 540).

Create Numbered Application Versions Using the VersionApp Utility

The VersionApp utility lets you create numbered versions of an application.

To access the VersionApp utility

1. Select the application for which you want to create numbered versions in the Applications portlet of the Develop tab.

2. Click Project, Version.

The Version dialog appears.

3. Set parameters for the specified application.

See the descriptions for each of these parameters in Parameters for the VersionApp Utility (see page 540).

4. Click Go.

Command Line Method of Creating Numbered Application Versions

To create numbered versions of an application, start the VersionApp utility by entering the following command at the command line:

w4gldev versionapp database application [-uusername] [-e] [-p{abort|ignore|version}] [-w{ignore|version}] [-rremark] [-f] [-l] [-T{yes|yes,min|all|all,min|no|logonly}] [-A]

Parameters are explained in Parameters for the VersionApp Utility (see page 540). The following additional flags are available from the command line:

database

Specifies the name and location of the database in which the application resides

application

Specifies the name of the application to delete

-e

Causes OpenROAD to write the component's 4GL script and any errors to the Trace window if any component has compilation errors



all,min

Specifies that messages be displayed in the Trace window and that the Trace window appears minimized as an icon

logonly

Specifies that the Trace window does not appear, but a log file is created

Parameters for the VersionApp Utility

You can specify the following parameters on the command line or using the Version dialog in the VersionApp utility:

Remark (-r)

Defines a remark for the application version

Checked In (-w)

Specifies how to handle the saved versions of components that have been changed since you created the last highest version number of that component:

Ignore

Directs OpenROAD to ignore the saved versions and include the highest numbered version of the components. This option fails if there are no numbered versions of the component.

Version

Directs OpenROAD to save the working version of the component as a numbered version and include it in the application version

Default: Version

Private Versions (-p)

Specifies how to handle your private versions of components in the application:

Abort

Directs OpenROAD to abort the command if there are private versions

Ignore

Directs OpenROAD to ignore the private versions and use the highest numbered version of the component in this version of the application

Version

Directs OpenROAD to save all your private versions and give them version numbers

Default: Abort



Force Compilation (-f)

Forces compilation of all components in the version

Ignore Locks (-l)

Unlocks any locked versions of components

Username (-u)

Only the database administrator for the database, the Ingres system administrator, or a superuser can use this parameter.

Lets you use this command as if you were another user, username.

Notes:

You, not username, own all files created by OpenROAD.

This entry field can be used only if Execute in Background is enabled.

Log Path (-L)

Specifies the name of a log file. This entry field can be used only if Execute in Background is enabled and Trace Window is set to Yes. If the log path specified is not a full path, the file is created in the ingres\files directory.

Trace Window (-T)

Lets you control display of the Trace window by entering one of the following values:

All

Specifies that the Trace window does appear

Yes

Specifies that the Trace window appears but suppresses informational messages output by the system

Yes (Minimized)


No

Specifies that the Trace window does not appear, and a log file is not created

Note: This entry field can be used only if Execute in Background is enabled.

Append to Log File (-A)

Causes the trace output of the current command to be appended to the end of the existing error log file. Otherwise, that log file is replaced. This entry field can be used only if Execute in Background is enabled.

Note: The error log file, w4gl.log, is located in %II_SYSTEM%\ingres\files.

How You Can Delete Application Versions


Execute in Background

Begins a new process while you are using this utility.

If enabled, Execute in Background makes Username, Log Path, Trace Window, and Append to Log File available for use.

Note: You can set defaults for this utility using the Set Tool Defaults dialog. See Set Defaults (see page 584).


In OpenROAD Workbench, you can delete an application or an individual component from the current database by selecting the item on the Develop tab and clicking File, Delete. For more information, see Delete Applications and Components (see page 102).

You also can delete applications and components using the DestroyApp (see page 542) and PurgeApp (see page 544) utilities.

Delete an Application Using the DestroyApp Utility

To use the DestroyApp utility, enter the following command at the command line:

w4gldev destroyapp database application [-uusername] [-vversion] [-ccomponent] [-t] [-T{yes|yes,min|all|all,min|no|logonly}] [-A]

Note: DestroyApp is not available as a menu command in Workbench because you can simply delete an application or an application version by clicking File, Delete.

Parameters for the DestroyApp Utility

The following describes the parameters for the DestroyApp utility:

database


application




-uusername

Only the database administrator for the database, the Ingres system administrator, or a superuser can use this parameter.


Note: You, not username, own all files created by OpenROAD.

-vversion

Specifies the version of the application to delete

Important! If you do not specify a specific version, the entire application will be deleted.

-ccomponent

Identifies a single component to be deleted from the application

Transaction (-t)

Specifies that transactions are committed after each component is deleted from the database

Important! Using this parameter decreases contention and log file use. However, if your database server terminates abnormally or the DestroyApp utility is aborted before completion, only some of the application components are deleted.

-TTrace


all


yes


yes,min


all,min




no


logonly


-AAppend to Log File

Causes the trace output of the current command to be appended to the end of the existing error log file. Otherwise, that log file is replaced.


How You Can Delete All Versions of a Component

You can use the Workbench's Delete menu command to delete components. For more information about using Delete, see Delete Applications and Components (see page 102).

You can also use the PurgeApp utility to purge all the numbered versions of a component that are not included in any application versions.

Delete all Numbered Versions of a Component Using the PurgeApp Utility

The fastest method of accessing the PurgeApp utility is from OpenROAD Workbench.

To use the PureApp utility

1. Select the component you want to delete in the Applications portlet of the Develop tab.

2. Click Project, Purge.

The Purge dialog box appears.

3. (Optional) Select the Execute in Background option if you want to run the utility as a new process. Then specify any of the other options described in Parameters for the PurgeApp Utility (see page 545).

4. Click Go to start the purge.




Command Line Method of Deleting Numbered Component Versions

The PurgeApp utility lets you remove all component versions in your application that are not included in any of your application versions. You may delete only numbered versions using this utility.

To purge your application components, start the PurgeApp utility from the command line using the following command:

w4gldev purgeapp database application [-uusername] [-T{yes|yes,min|all|all,min|no|logonly}] [-A]

Parameters are explained in Parameters for the PurgeApp Utility (see page 545). The following additional flags are available from the command line:

database


application


all,min


logonly

Specifies that the Trace window does not appear, but all messages are saved in a log file

Parameters for the PurgeApp Utility

The following describes the parameters for the PurgeApp utility:

Username (-u)



Trace Window (-T)


All


Yes


How You Can Import and Export Applications and Components


Yes (Minimized)


No










In OpenROAD Workbench, you can import or export components. You also can use the ImportApp and ExportApp utilities to copy applications and components between a file and the database, or vice versa.

ImportApp

Lets you copy either an entire application or an individual component from a text file created previously by ExportApp into a database

ExportApp

Lets you copy either an entire OpenROAD application or a single application component from the database into a text file

These utilities enable you to:

Move an application from one system to another

Back up an application outside of OpenROAD

Copy frames and procedures between applications



Notes:

OpenROAD export files are ASCII files. When transporting export files, be sure to do an ASCII-mode transfer so that translation between <LF> and <CR/LF> is handled correctly.

OpenROAD image files are binary files. When transporting image files between different platforms, be sure to do a binary-mode transfer to avoid any conversion problems.

Import an Individual Component

In Workbench, you can import an individual component into an application. To import a single component, you must have previously exported that individual component to a separate text file.

If there is a name conflict, the Import command aborts. To replace an existing component, first delete the component before importing its replacement.

To import a component

1. Click the application into which you want to import the component on the Applications portlet of the Develop tab.

2. Click the Components header bar to activate the portlet.

3. Click File, Import.


4. Locate and select the .exp file containing the component you want to import.

5. Click Open.


Import an Application

The ImportApp utility lets you copy an entire application or a single application component from an exported file into a database.



You should run the ImportApp utility with a value for the -n parameter (described in Parameters for the ImportApp Utility (see page 549)) to resolve name conflicts between imported and existing applications and components. Such conflicts can arise in any of the following situations:

If the name of a component being merged into an existing application already exists in that application

If you create a new application with the same name as an application that already exists in the database

The most efficient method of accessing the ImportApp utility is from the Develop tab of Workbench.

To import an application

1. Click the header bar of the Applications portlet on the Develop tab to make it the active portlet.

2. Click File, Import.

The Import an Application dialog appears.


See the descriptions for each of these parameters in Parameters for the ImportApp Utility (see page 549).

4. Click Go.

Command Line Method of Importing an Application from a File

To import an application from a file, start the ImportApp utility from the command line:

w4gldev backupapp in database application file [-ccomponent] [-uusername] [-e] [-f] [-n{prompt|abort|replace|version}] [-m] [-t] [-T{yes|yes,min|all|all,min|no|logonly}] [-A]

Parameters are explained in Parameters for the ImportApp Utility (see page 549). The following additional flags are available from the command prompt:

database


application


file

Specifies the name of the file from which the application or component is being imported. Click Browse to display a standard File Selection dialog.



yes,min

Specifies that the Trace window appears minimized as an icon but suppresses all informational messages output by the system

all,min


logonly


Parameters for the ImportApp Utility

You can specify the following parameters using the Import an Application dialog:

Input File

Specifies the name of the file from which the application or component is being imported. Click Browse to display a standard File Selection dialog.

Application Name

Specifies the name of the application that is to be created or merged into

Name Conflict (-n)

Specifies how to treat name conflicts with one of the following values:

Prompt

Requests a prompt when there is a conflict

Abort

Directs OpenROAD to abort this utility and to back out any components that were already added

Replace

Replaces the old component with the new component

Version

Specifies that if an application or application component being imported already exists, the existing application or component is versioned before being replaced

Default: Abort

Display Errors (-e)

If any component has compilation errors, causes OpenROAD to write the component's 4GL script and any errors to the Trace window

Merge (-m)

Merges the components from the input file into the existing application



Transaction (-t)

Specifies that transactions are committed after each component is added to the database

Important! Using this parameter decreases contention and log file use. However, if your database server crashes or the ImportApp utility is aborted before completion, only some of the application components are loaded.


Forces compilation of the application components before they are loaded into the database.

If there is a compilation error, the component is still loaded into the database, but is marked as “out of date.”

If you do not include this parameter, components are copied into the database marked “out of date,” and are compiled the first time you compile or run the application.

Username (-u)

Lets you use this command as if you were another user, username. This entry field can be used only if Execute in Background is enabled.


Log Path (-L)


Trace Window (-T)


All


Yes


Yes (Minimized)


No












Examples: ImportApp Utility

The following example imports an application, “myapp,” from the export file “myapp.bck.” This command also forces the application components to be compiled before being loaded into the database:

w4gldev backupapp in mydatabase myapp myapp.bck -f

The following example replaces the “myapp” application in mydatabase with the application contained in the file “myapp.bck”:

w4gldev backupapp in mydatabase myapp myapp.bck -nreplace

The following example imports a frame, TestFrame, from the file “testframe.frm” into the “myapp” application, and prompts the user if the frame already exists in the application:

w4gldev backupapp in mydatabase myapp testframe.frm -ctestframe -nprompt

The following example imports the backup version of the “myapp” application and merges all the components into the “bigapp” application. If any components in bigapp have the same names as those in myapp, it replaces them with the components from myapp:

w4gldev backupapp in mydatabase bigapp myapp.bck -m -nreplace



Export an Individual Component

In Workbench you can export an individual component from the Develop tab.

To export a component

1. Select the application containing the component to export in the Applications portlet of the Develop tab.

2. Select the component to be exported in the Components portlet.

3. Click File, Export.


4. Navigate to the directory where you want to export the file.

5. Name the file.

6. Click Save.


Export Applications and Components

The ExportApp utility lets you copy an entire application or a single application component from the database to an export file. You can later import it from the export file into the database. The easiest method of accessing the ExportApp utility is from the Workbench Develop tab.

To export an application

1. Select the application that you want to export in the Applications portlet of the Develop tab.

2. Click File, Export.

The Export Application dialog appears.


See the descriptions for each of these parameters in Parameters for the ExportApp Utility (see page 553).

4. Click Go.



Parameters for the ExportApp Utility

You can specify the following export parameters using the Export Application dialog:

Output File

Specifies the name of the file to which the application will be exported. Click Browse to display a standard File Selection dialog.

Username (-u)


Notes:



Log Path (-L)


Trace Window (-T)


All


Yes


Yes (Minimized)


No












Command Line Method of Exporting an Application to a File

To export an application to a file using the command line, enter the following command at the command line:

w4gldev backupapp out database application file [-ccomponent] [-uusername] [-vversion] [-T{yes|yes,min|all|all,min|no|logonly}] [-A] [-t]

Parameters are explained in Parameters for the ExportApp Utility (see page 553). The following additional flags are available from the command line:

database


application


file

Specifies the name of the file to which the application will be exported

-vversion

Specifies the version of the application to export

-ccomponent

Identifies a single component to be exported from the application

all,min


logonly


How You Can Generate Reports for Applications and Components


-t

Specifies that transactions are committed after each component is deleted from the database

Important! Using this parameter decreases contention and log file use. However, if your database server terminates abnormally or the DestroyApp utility is aborted before completion, only some of the application components are deleted.

Examples: ExportApp Utility

The following example exports the working version of all components in the “myapplication” application to export file “myapp.bck”:

w4gldev backupapp out mydatabase myapplication myapp.bck

The following example exports the working version of the Test frame to “test.frm”:

w4gldev backupapp out mydatabase myapplication test.frm -ctest


OpenROAD provides two utilities that let you produce a report about the contents of your applications:

DocumentApp utility

Generates reports about database-resident applications and components

QueryImage utility

Generates reports about applications in image files

Document an Individual Component

In OpenROAD Workbench you can generate a report for an individual component from the Develop tab.

To document a component

1. Select the component to be documented in the Components portlet of the Develop tab.

2. Click Project, Document.




3. Specify the name of the file for output.

4. Click Save.


Document Applications and Components Using the DocumentApp Utility

The DocumentApp utility saves to a file a report about an application in a database or one of the application's components. The report lists all the properties of the application and the properties and scripts for all application components. The report combines information that otherwise is available only through the application scripts and the Property Inspector.

The easiest method of using the DocumentApp utility is from the Workbench Develop tab.

To use the DocumentApp utility

1. Select the application you want to document about in the Applications portlet of the Develop tab.

2. Click Project, Document.

The Document Application dialog appears.


See the descriptions for each of these parameters in Parameters for the DocumentApp Utility (see page 556).

4. Click Go.

Parameters for the DocumentApp Utility

The following parameters can be specified using the Document dialog:

Output File

Specifies the name of the file to which the information about the component or application is to be written. Click Browse to display a standard File Selection dialog.

4GL Source Only (-s)

Prints a report containing only the 4GL source code for objects that have 4GL scripts, such as user class methods, procedures, and frames. For frames, the report also includes any field scripts.



All Attributes (-a)

Requests a complete listing of the attributes for all fields in a frame.

Note: Using this parameter can produce a very long report. If you do not use this parameter, the report contains information only about component and field names, data types, and scripts.

Username (-u)


Notes:



Log Path (-L)


Note: This parameter is only available when accessing this utility from the Project menu.

Trace Window (-T)


All


Yes


Yes (Minimized)


No













Command Line Method of Documenting an Application

To generate a report on an application or component, start the DocumentApp utility by entering the following command at the command line:

w4gldev documentapp database application file [-uusername] [-ccomponent] [-vversion] [-s] [-a] [-T{yes|yes,min|all|all,min|no|logonly}] [-A]

Parameters are explained in Parameters for the DocumentApp Utility (see page 556). The following additional flags are available from the command line:

database


application


file

Specifies the name of the file to which the information about the component or application is to be written

-vversion

Specifies the version of the application to document

-ccomponent

Identifies a single component in the application to be documented

all,min


logonly




Document Imaged Applications Using the QueryImage Utility

The QueryImage utility produces a report containing the following information about a binary image file:

The name and properties of the application in the file (and any included applications)

The names and properties of the components in each application

The easiest method of accessing the QueryImage utility is from the Develop tab.

To use the QueryImage utility


2. Click Project, Query.

The Query Image File dialog appears.

3. Select the image file you want to query, and set parameters.

See the descriptions for each of these parameters in Parameters for QueryImage (see page 559).

4. Click Go.

Note: QueryImage can be accessed from the Start menu or command prompt as described in Command Line Method for Documenting an Application Image (see page 560).

Parameters for the QueryImage Utility

You can specify the following parameters using the Query Image File dialog:

Input File

Specifies the name of the image file. Click Browse to display a standard File Selection dialog.

Output File

Specifies the name of file to which the report is to be written. Click Browse to display a standard File Selection dialog.

Log Path (-L)




Trace Window (-T)


All


Yes


Yes (Minimized)


No










Command Line Method for Documenting an Application Image

To generate a report on an application image, start the QueryImage utility by entering the following command at the command line:

w4gldev queryimage imagefile outfile [-T{yes|yes,min|all|all,min|no|logonly}] [-A]

How You Can Apply Template Changes to Frames and Fields


Parameters are explained in Parameters for QueryImage (see page 559). The following additional flags are available from the command line:

imagefile

Specifies the name of the image file

outfile

Specifies the name of the file to which the report is to be written

all,min


logonly



Another management function of OpenROAD includes the ability to incorporate new features or enhancements that have been made to a frame or field template into existing frames or fields. You can “upgrade” a frame or field by using the ApplyTemplate utility. This utility also works for those frames and fields that have been generated using template assistants.

The ApplyTemplate utility can be used to regenerate specialized changes to the user areas of a frame, or to incorporate the generic changes of the frame and field templates.

Note: Fields generated from field templates are completely overwritten when the ApplyTemplate utility is run; therefore, any changes made to the field are lost.

Apply Alternate Templates to Frames or Fields Using the ApplyTemplate Utility

The easiest method of accessing the ApplyTemplate utility is from the Develop tab.

To use the ApplyTemplate utility

1. Select the application to which you want to apply changes in the Applications portlet of the Develop tab.

2. Click Tools, Apply Templates.

The Apply dialog appears.




See the descriptions for each of these parameters in Parameters for the ApplyTemplate Utility (see page 564).

4. Click Go.

The Apply Template Utility dialog appears:

This dialog contains two columns:

Source column

Is used to select the template whose changes are to be applied

Destination column

Is used to select the frames targeted by the operations

The Applications list box displays all the applications in the database that contain frames that have been generated by predefined templates (or contain frames containing fields generated by templates if you select the Field Templates option).



To use the Apply Template Utility dialog

Note: If you want to apply changes to frames that you have created, start with Step 2.

1. Click the Fields button if you want to apply changes to fields.

2. Select the desired application in the database in the Applications list field.

Depending on whether the Frame Templates or Field Templates option is selected, when an application is selected, the Frame Templates (or Field Templates) list field is populated with the names of the frame templates (or field templates) that have been used to generate frames (or fields) in the selected application.

3. Select a template from the Frame Templates (or Field Templates) list.

If the Frame Templates option is selected, the Frames list field is populated with a list of all frames in the application that have been generated from this template.

If the Field Templates option is selected, the Frames list field is populated with a list of all frames in the application containing fields that have been generated from this template.

4. Select one or more frames from the Frames list in which changes are to be applied.

You can use the Select All and Clear All buttons to select all frames or clear all frames, respectively.

5. Select the mode of operation in which the ApplyTemplate utility is to be run, including one of the following:

Batch

Specifies that the frame or field changes are applied automatically based on the assistant procedure coded by the developer

Interactive

Specifies that the appropriate frame or field assistant dialog is called so that you can enter your own customization parameters associated with the frame or field

6. Click Apply.

The static properties of the frame (or field) template are applied to the target frame or frames; and if appropriate, the corresponding frame assistant or field assistant is called.

The modifications are made to the application's components in the database. If you want these changes to be applied to images that have been previously created, you need to run the MakeImage utility (see page 569) again to create a new image.



For more information about how to ensure compatibility between the ApplyTemplate utility and your assistant procedures, see the chapter “Writing a Template Assistant” in the Programming Guide. This chapter also provides guidelines on how a frame is partitioned, and which areas developers can customize without being affected by future regeneration of the dynamic portions of the frame.

Parameters for the ApplyTemplate Utility

You can specify the following parameters using the Apply dialog:

Username (-u)


Notes:



Log Path (-L)


Note: This parameter is available only when accessing this utility from the Project menu.

Trace Window (-T)


All


Yes


Yes (Minimized)


No



How You Can Compile Applications and Components









Command Line Method for Upgrading Templates

To upgrade your frames and fields that have been previously generated, start the ApplyTemplate utility by entering the following command at the command line:

w4gldev runimage applytmp.img -ddatabase [-T{yes|yes,min|all|all,min|no|logonly}] [-A]

Parameters are explained in Parameters for the ApplyTemplate Utility (see page 564). The following additional flags are available from the command line:

applytmp.img

Specifies the image file to apply the template upgrade

-ddatabase

Specifies the database

all,min


logonly



In OpenROAD Workbench, you can either compile a user frame, ghost frame, user class, or 4GL procedure component explicitly as a separate step, or you can use the CompileApp utility to compile an application and all of its components.



Compile a Component

You can compile components—user frame, ghost frame, user class, or 4GL procedure—on the Develop tab.

To compile the current component

1. Open the component you want to compile in the Components portlet of the Develop tab.

The appropriate editor appears.

2. Click Project, Compile.

A message informs you either that your component successfully compiled or that an error message was generated.

Compile an Application

The CompileApp utility compiles an application or any of its components. Compilation is done automatically when you make an image, but you can also compile explicitly as a separate step. If there are any compilation errors, the utility displays an error message and continues compiling the next component.

The easiest way to compile an application is to access the CompileApp utility from the Develop tab.

To use the CompileApp utility

1. Select the application you want to compile in the Applications portlet of the Develop tab.

2. Click Project, Compile.

The Compile dialog appears.


See the descriptions for each of these parameters in Parameters for the CompileApp Utility (see page 566).

4. Click Go.

Parameters for the CompileApp Utility

You can specify the following parameters using the Compile dialog:

Ignore Locks (-l)

Unlocks any locked components

OpenSQL Warnings (-wopen)

Produces a warning error at compilation time for any SQL statement that is not compliant with OpenSQL




Forces recompilation of all application components, even those that have not been changed since the last compilation.

If you are compiling a single component (with the -ccomponent parameter), this parameter forces compilation of the specified component.

Display Errors (-e)

Causes OpenROAD to write the component's 4GL script and any errors to the Trace window, if any component has compilation errors

Username (-u)


Notes:



Log Path (-L)



Trace Window (-T)


All


Yes


Yes (Minimized)


No













Command Line Method for Compiling Applications

To access the CompileApp utility, enter the following command at the command line:

w4gldev compileapp database application [-ccomponent] [-uusername] [-e] [-f] [-l] [-wopen] [-T{yes|yes,min|all|all,min|no|logonly}]

Parameters are explained in Parameters for the CompileApp Utility (see page 566). The following additional flags are available from the command line:

database


application


-ccomponent

Specifies a component to compile

all,min


logonly


How You Can Create an Application Image



When your OpenROAD application is ready to be run, you can create an image of the application. An application image is a version of an application that is stored in an operating system file outside of the database. The performance of an application is significantly better when it is run from an image than from the database.

Keep in mind that an image reflects the state of an application at the time you created the image. If you make any subsequent changes to the application, you must create a new image to incorporate those changes.

Use the MakeImage Utility

The easiest way to use the MakeImage utility is to access it from the Develop tab.

To use the MakeImage utility

1. Select the application you want to image in the Applications portlet of the Develop tab.

2. Click Project, Image.

The Make Image dialog appears.


See the descriptions for each of these parameters in Parameters for the MakeImage Utility (see page 569).

4. Click Go.

Parameters for the MakeImage Utility

You can specify the following parameters using the Make Image dialog:

Output File

Specifies the name of the image file to create. Image files end with the extension .img. Click Browse to display a standard File Selection dialog.

Included Applications Override (-i)

Specifies the name of the application for which an image will be generated. Click Browse to display a standard File Selection dialog.

Application Name Override (-a)

Specifies a new name for the application image file



Library (-l)

Causes all components of the application, including non-executable components (that is, include scripts, field templates, and frame templates) to be included in the resulting image file.

Such an image file is sometimes referred to as an “application library” and can be used as a library of templates during development.


Forces recompilation of all application components, even those that have not been changed since the last compilation

Display Errors (-e)

Causes OpenROAD to write the component's 4GL script and any errors to the Trace window, if any component has compilation errors

Generate SCPs (-s)

Causes OpenROAD to generate Service Call Procedures for the application before making an image

Generate SCP Metadata (-m)

Causes OpenROAD to generate SCP metadata for the application before making an image

Metadata Interface Name (-n)

Lets you enter a metadata interface name if you select Generate SCP Metadata. OpenROAD supplies a default name.

Metadata Interface Version (-r)

Lets you enter a metadata interface version if you select Generate SCP Metadata. OpenROAD supplies a default version.

Username (-u)


Notes:



Log Path (-L)




Trace Window (-T)


All


Yes


Yes (Minimized)


No










Command Line Method for Creating an Application Image

To create an application image, start the MakeImage utility by entering the following command at the command line:

w4gldev makeimage database application file [-uusername] [-f] [-l] [-vversion] [-aappname] [-e] [-ifilename] [-s] [-m] [-nappname] [-rversion] [-T{yes|yes,min|all|all,min|no|logonly}] ] [-A]

Parameters are explained in Parameters for the makeimage Command Line Utility (see page 572).



Parameters for the makeimage Command Line Utility

You can specify the following parameters using the w4gldev makeimage command line utility:

-i (Included Applications Override)

Specifies the name of the application for which an image will be generated.

This flag corresponds to the Included Applications Override field on the Make Image dialog box. For more information, see Use the MakeImage Utility (see page 569).

-l (Library)

Causes all components of the application, including non-executable components (that is, include scripts, field templates, and frame templates) to be included in the generated image file. Such an image file is sometimes referred to as an “application library” and can be used as a library of templates during development.

This flag corresponds to the Library option on the Make Image dialog box. For more information, see Use the MakeImage Utility (see page 569).

-f (Force Compilation)

Forces recompilation of all application components, even those that have not been changed since the last compilation.

This flag corresponds to the Force Compilation option on the Make Image dialog box. For more information, see Use the MakeImage Utility (see page 569).

-e (Display Errors)

Causes OpenROAD to write the component's 4GL script and any errors to the Trace window, if any component has compilation errors.

This flag corresponds to the Display Errors option on the Make Image dialog box. For more information, see Use the MakeImage Utility (see page 569).

-s (Generate SCPs)

Causes OpenROAD to generate Service Call Procedures and include them in the application. For example:

w4gldev makeimage corsac::apped4fs myasoapp myasoapp.img -s -Tall

This flag corresponds to the Generate SCPs option on the Make Image dialog box. For more information, see Use the MakeImage Utility (see page 569).



-m (Generate SCP Metadata)

Causes both Service Call Procedures and SCP metadata to be generated and included in the application image file. For example:

w4gldev makeimage corsac::apped4fs myasoapp myasoapp.img -m -Tall

This flag corresponds to the Generate SCP Metadata option on the Make Image dialog box. For more information, see Use the MakeImage Utility (see page 569).

-nappname (Metadata Interface Name)

Causes the specified ASCII text name to be used as the interface name for the SCP metadata. By default, the interface name is the application name. For example:

w4gldev makeimage corsac::apped4fs myasoapp myasoapp.img -m -nmyapp

This flag corresponds to the Metadata Interface Name field on the Make Image dialog box. For more information, see Use the MakeImage Utility (see page 569).

-rversion (Metadata Interface Version)

Causes the specified version number (ASCII text) to be used as the interface's version for the SCP metadata. By default, the interface version is -1 (working version). For example:

w4gldev makeimage corsac::apped4fs myasoapp myasoapp.img -m -rversion1.1

This flag corresponds to the Metadata Interface Version field on the Make Image dialog box. For more information, see Use the MakeImage Utility (see page 569).

-u (User Name)



-L (Log Path)

Specifies the name of a log file. This flag can be used only when the -T flag is set to yes. If the log path specified is not a full path, the file is created in the ingres\files directory.

This flag corresponds to the Log Path field on the Make Image dialog box. For more information, see Use the MakeImage Utility (see page 569).

-v (Existing Version Flag Behavior)

Specifies which version of the application to use when creating the image file. Because the -m and -s flags can generate SCP calls and SCP meta data only for the current working version of an application, the -s and -m flags are ignored when -v is specified, and a warning message is generated.



-T (Trace Window)


all


yes


yes,min


all,min


no


logonly


This flag corresponds to the Trace Window field on the Make Image dialog box. For more information, see Use the MakeImage Utility (see page 569).

-A (Append to Log File)



This flag corresponds to the Append to Log File option on the Make Image dialog box. For more information, see Use the MakeImage Utility (see page 569).

-aappname (Rename the Application Image File)

Renames the application in the image file to appname

How You Can Image Included Applications



OpenROAD applications can reference, or include, other OpenROAD applications, using the components of the included application.

Root Application

A root application is the application that includes other applications. During development, a root application can include other applications either from the database or from image files. During deployment, included applications must exist in image files, either in separate files or within the same image file as the root application.

You specify included application references in the Included Applications portlet for the root application. For more information about this window, see Specify Included Applications (see page 89).

Each included application reference has the following format:

appname [version_number] [image_filename]

Definitions of these parameters follow:

appname

Specifies the name of the application to be included

version_number

Specifies the version of the application to be included. If not specified, the current working version is used.

image_filename

Specifies the name of the image file containing the application to be included. If the application is included from the database instead of an image file, this parameter is omitted.

How Referencing Images Works

When you make an image of a root application that references included applications from the database (that is, by not specifying an image file name in the references), all of those included applications are also imaged and added to the resulting image file of the root application. This may not be desirable, especially if you plan to have several applications share a common utility image.



If the included application reference contains an explicit image file name, the referenced application is not added to the root application image file. Instead, the root application will dynamically bind to the specified image file name at runtime.

During development, it is convenient (for debugging, and for keeping up with the latest versions) to reference included applications directly from the database. Therefore, you generally do not want to specify an image file name with your included application references in the Included Applications window. But, for deployment, it is more space-efficient to reference shared image files, rather than having the shared images be duplicated within the image file of each root application that uses them.

How You Can Override Included Application References

To enable you to develop with included applications from the database and then easily switch to shared images for deployment, OpenROAD provides the “-l” flag with the MakeImage utility to override the included application references.

For more information, see Parameters for the MakeImage Utility (see page 569).

How You Can Use an Override File

When the root application is imaged, you can use an override file to modify the included application references when using the MakeImage utility.

You specify an override file using the “-i” flag with the MakeImage utility. For more information, see Parameters for the MakeImage Utility (see page 569).

The file should contain one line for each included application reference to be overridden. Each line has the same format as the basic included application reference:

appname [version_number] [image_filename] [-ifilename]

For each appname referenced by the root application, if there is a line for that appname in the override file, that line temporarily replaces the existing reference in the root application. Use zero (0) for the version_number to indicate that the current working version is to be used.

Running an Application



OpenROAD provides two utilities that let you run applications outside the visual development environment:

RunDBApp utility

Runs an application that is stored in a database.

For more information, see Run an Application from the Database Using the RunDBApp Utility (see page 577).

RunImage utility

Runs an application that is stored in an image file.

For more information, see Run an Application from an Image Using the RunImage Utility (see page 580).

Run an Application from the Database Using the RunDBApp Utility

To run an application from a database, start the RunDBApp utility in one of the following ways:

(Windows only) Access RunDBApp through the Start menu, Run command

Enter the following command at the command line:

w4gldev rundbapp database application [-ccomponent] [-uusername] [-menvironment_var] [-gfilename] [-ifilename] [-nowindows] [-realfields] [-bidi] [-vversion] [-T{yes|yes,min|all|all,min|no|logonly}] [-A] [-/dbmsflags dbmsflags] [-/appflags appflags]

Parameters for the RunDBApp Utility

The RunDBApp utility takes the following parameters:

database


application

Specifies the name of the application to run

-ccomponent

Specifies a component (frame or procedure) to use as the starting point for the application. By default, the application starts with the frame or procedure specified in the application's Property Inspector.



-uusername

Lets you use this command as if you were another user, username


-gfilename

Specifies a file containing initial values for the global variables and constants in the application.

The values remain in effect for the duration of the current OpenROAD session.

-ifilename

Lets you specify a file containing overrides for the version and location of any included applications.

For more information about specifying an override file, see Parameters for the MakeImage Utility (see page 569).

-nowindows

Lets the application run without the window manager running.

This option does not provide full “batch mode” execution, because some interaction with the application still may be required through the Trace window.

-realfields

Instructs OpenROAD to create a separate windows system control for each field on a form. By default, OpenROAD multiplexes a single control for many fields to save time and memory.

-bidi

Displays OpenROAD application GUI components from right to left.

-vversion

Specifies the version number of the application to run

-menvironment_var

Lets you specify the name of a different environment variable to contain your list of DLLs or shared libraries to be searched when resolving 3GL procedure calls. If it is present, this parameter overrides any existing specification of II_LIBU3GL.



-T


all


yes


yes,min


all,min


no


logonly


-A





Run an Application from an Image Using the RunImage Utility

In OpenROAD Workbench, you can use the RunImage utility to run an application from an image. The easiest way to access this utility is as follows.

To use the RunImage utility

1. Click Start, All Programs, Ingres instance, OpenROAD Runimage.

The RunImage dialog appears:


See the descriptions for each of these parameters in Parameters for the RunImage Utility (see page 580).

3. Click OK.

Parameters for the RunImage Utility

You can specify the following parameters using the RunImage dialog:

File

Specifies the name of the image file to run

-database

Specifies the name and location (host machine) of the database that contains the data to be used in the application. This database need not be the same database that was specified when the application was created.



-component

Specifies a component (frame or procedure) to use as the starting point for the application. By default, the application starts with the frame or procedure specified in the application's Property Inspector.

-username

Lets you use this command as if you were another user, username


-m

Lets you specify the name of a different environment variable to contain your list of DLLs or shared libraries to be searched when resolving 3GL procedure calls. If it is present, the -m parameter overrides any existing specification of II_LIBU3GL.

-included app override file

Lets you specify a file containing overrides for the version and location of any included applications.

For more information about specifying an override file, see How You Can Image Included Applications (see page 575).

-global const file

Specifies a file containing initial values for the global variables and constants in the application.

The values remain in effect for the duration of the current OpenROAD session.

-A(ppend to log)



-realfields

Instructs OpenROAD to create a separate windows system control for each field on a form. By default, OpenROAD multiplexes a single control for many fields to save time and memory.

-bidi

Specifies that OpenROAD application GUI components be displayed from right to left



-T(race)


Yes


Yes (Minimized)


No



Command Line Method to Run an Application from an Image

To run an application from an image, start the RunImage utility from the Start menu, Run command or by entering the following command at the command line:

w4glrun appfile.img [-ccomponent] [-uusername] [-ddatabase] [-menvironment_var] [-gfilename] [-ifilename] [-nowindows] [-realfields] [-bidi] [-T{yes|yes,min|all|all,min|no|logonly}] [-A] [-/dbmsflags dbmsflags] [-/appflags appflags]

Parameters are explained in Parameters for the RunImage Utility (see page 580). The following additional flags are available from the command line:

appfile.img

Specifies the image file to run

-/dbmsflags and -/appflags

For more information, see How You Can Set Metaflags for the RunDBApp and RunImage Utilities (see page 583).

all




all,min


logonly


Note: If you have installed the OpenROAD Development package, you can use the w4gldev runimage command instead of w4glrun.

How You Can Set Metaflags for the RunDBApp and RunImage Utilities

For the RunDBApp and RunImage utilities, you can set metaflags that provide more advanced features. You can specify a metaflag only on the RunDBApp and RunImage command lines.

Metaflags begin with “-/” and they must appear after all other command line parameters because their “value” is terminated by either the next metaflag or by the end of the command.

The available metaflags for RunDBApp and RunImage and their possible values are:

-/dbmsflags dbmsflags

Specifies initial DBMS connection flags for the applications. The string of flags following this metaflag overrides the string of DBMS flags that was specified in the application's Property Inspector.

-/appflags appflags

Passes parameters to your application. These parameters are placed in the AppFlags attribute of the SessionObject of the running application.

Note: Appflags contains an array of appflag objects. Each appflag object consists of a name, and an array of values.

Application parameters may be of the following kinds:

Positional parameters

A parameter is positional if there is no equal sign (=) in its first 32 characters. All other parameters are keyword parameters.

Keyword parameters

A keyword parameter is assigned the values that come after the equal sign (possibly separated by commas if an array of values is used).

Set Defaults


Appflags are subject to the following restrictions:

Values and names must not contain a space, tab, newline, carriage return, quote, apostrophe, comma, or the equal sign.

Names must not exceed 32 characters.

Note: If these rules are violated, the behavior is undefined.

Set Defaults

In OpenROAD Workbench, you can specify, view, and edit default settings for the following utilities:

Apply Template

CompileApp

DocumentApp

ExportApp

ImportApp

MakeImage

PurgeApp

QueryImage

VersionApp

To change the defaults for one of these utilities

1. Click Tools, Options, Defaults on the Develop tab.

The Set Tool Defaults dialog appears.

2. Select the appropriate tab for the utility for which you want to change defaults.

Use the arrow buttons to display the rest of the utility name tabs if you do not see the utility name you want.

3. Specify the defaults.

4. Click Save Defaults.

For descriptions of the available parameters, see the specific utility section in this chapter.

The defaults you set will be displayed the next time you open the dialog for that utility.

How You Can Deploy Applications with 3GL Procedures


How You Can Deploy Applications with 3GL Procedures

This section describes how to provide executable code for the 3GL procedures called by your 4GL applications.

Certain platforms handle libraries differently:

Windows

Your 3GL code must be compiled and linked into dynamic link libraries (DLLs), which are then made available to the OpenROAD runtime system for use with your application.

UNIX or Linux

The basic premise is similar to that of Windows, but the 3GL load modules may or may not be shared libraries, depending on your particular platform.

For more information about how to implement 3GL procedures and how to compile and link your 3GL source code into DLLs or load modules, see the Programming Guide.

How You Can Use 3GL DLLs or Shared Libraries

After you have compiled and linked your 3GL procedure source code into DLLs (as described in the Programming Guide), you must deploy those DLLs with your application image files, and ensure that the appropriate 3GL DLLs are made available to the OpenROAD runtime system when your application is run.

Note: As used in this guide, “DLLs” refers to both dynamic link libraries and shared libraries.

When you run a 4GL application (using RunDBApp or RunImage), you provide a list of DLLs to be searched when resolving 3GL procedure calls. When your 4GL application calls a 3GL procedure, the OpenROAD runtime system searches each of the DLLs in the list until it finds one containing the specified procedure. It then binds and executes that 3GL code.

There are three ways to provide this list of DLLs to the OpenROAD runtime system:

Using the II_LIBU3GL environment variable

Set this environment variable to contain your list of DLL names (and paths). If you specify multiple DLLs, separate them with a semicolon.

The following example illustrates setting the environment variable on a Windows platform:

set II_LIBU3GL= c:\mypath\mylib.dll; c:\mypath2\mlib2.dll

How You Can Use Commands from a File


Using the -m parameter

The -m parameter for RunDBApp and RunImage lets you specify the name of a different environment variable to contain your DLL list. If it is present, the -m parameter overrides any existing specification of II_LIBU3GL.

For more information about the -m parameter, see RunImage Utility Parameters (see page 64).

Using the 3GL Procedure Editor

In the 3GL Procedure Editor, you can specify the DLL name that contains the 3GL procedure. If the full path is not included, then the DLL must reside in a directory on the Path environment variable. At runtime, if the specified DLL is missing or does not contain the procedure, OpenROAD will not look at II_LIBU3GL or the -m parameter to resolve the procedure.

How You Can Use Commands from a File There is one additional metaflag that you can use on any OpenROAD command line. It lets you put some of the command line parameters into a file, and then reference that file from the command line. This is particularly helpful on systems that impose limits on the length of the command line.

-/include=filename

Specifies the text file containing the actual command line flags so that you can reference that file from the command line.

The filename specification must include the full directory path, if it is not in the current working directory.

Conceptually, -/include=filename is replaced by the contents of the referenced text file. This replacement occurs before the search for other metaflags.

Rules for specifying parameters in the text file follow:

You cannot put the main command parameter (for example, the “runimage” of “w4gldev runimage”) into the file.

You cannot put the -T or -A flags into the file.

Each parameter must be specified in the format of an SQL string literal: enclosed in single quotes (') with embedded single quotes doubled (''). (Hexadecimal literals are not supported.)

If a parameter contains no apostrophes ('), spaces, or tabs, the enclosing apostrophes can be omitted.

A parameter cannot contain a newline character.

Multiple parameters can be specified in a single record, separated by spaces, tabs, or both.

How You Can Deploy a Web-based OpenROAD Application with the OpenROAD eClient Packaging Tool


Leading and trailing spaces and tabs are removed.

No attempt is made to do any shell-like variable substitution.


The OpenROAD eClient enables you to deploy and run OpenROAD runtime and OpenROAD applications on Microsoft Windows client workstations equipped with only Microsoft Internet Explorer. The eClient is a digitally signed, self-contained control that contains a packaged version of OpenROAD runtime. When the eClient is placed on a web server and referenced using OBJECT tags on an HTML web page, a client machine running Internet Explorer can automatically download and install the runtime, and run user applications.

After users download an eClient application using Internet Explorer, they can launch the application independently of the web browser using a Start menu shortcut, or command prompt command.

The eClient application accesses the OpenROAD Server to perform all database access. If an Ingres Net Client is already installed, an OpenROAD application accesses the database directly.

For more information on system requirements and operating system support for the eClient, see the readme.

Before you can launch an eClient application, you must do the following:

Deploy the eClient application and library cabinet files

Install the eClient runtime

How the eClient Runtime Is Installed on Client Workstations

A single cabinet (CAB) file, digitally signed by Ingres Corporation, contains the OpenROAD eClient runtime. The web server hosts the CAB file, which you must reference on an HTML page. Any client workstation that loads the HTML page that references this CAB file automatically downloads and installs the runtime, if it has not already been installed. The user needs only to click OK on the Internet Explorer's common digital signature trust dialog; no other installation or configuration is required.



oraxp.cab—eClient Cabinet File

The eClient is packaged as a Microsoft CAB (cabinet) file named oraxp.cab that must be hosted on your web server to be available to web clients. This file is in the eclient folder of your OpenROAD installation.

\

To package your OpenROAD applications for distribution over a web server, you must create (and optionally digitally sign) your own CAB file containing the appropriate OpenROAD application image, any other data files required by your application, and several required installation files. In addition to creating the CAB file for your application, you must also create and publish an HTML page that contains the OBJECT tags necessary to cause the client's Internet Explorer browser to download, install, and run the eClient runtime and your eClient application.

The OpenROAD eClient Packaging Tool (MakeCAB) provides an alternative to using the manual steps for creating CAB files. You can use this graphical interface to automatically package your OpenROAD applications in CAB format and generate the basic HTML page required to deploy your application.

How eClient Applications and Library Cabinet Files Are Deployed

Each OpenROAD eClient application, along with its library cabinet files, is packaged into a single CAB file. This enables the application to be downloaded automatically. Basic deployment consists of the following steps:

1. Create an HTML page that references the OpenROAD eClient runtime and your application, using HTML OBJECT tags.

2. Install the HTML page, the eClient runtime CAB, and your application CAB on your web server.

3. Open the HTML page in Internet Explorer on the client workstation.

The browser downloads and installs the CAB files, if necessary, and then launches the OpenROAD application.

After an eClient application is installed, you can also launch it (in Run Mode 2) with the w4glrun utility. For more information, see How You Can Use MakeCAB from the Windows Command Prompt.

How You Can Set Up Your Web Server

To run eClient applications, you must copy the OpenROAD eClient runtime (oraxp.cab) and optionally the OpenROAD Transformation Runtime (complib.cab) to a generally accessible directory on your web server. These files are in the eclient folder in your OpenROAD installation.



You must have read/write access to the web server directory where you will be saving your application CAB files and HTML pages. If you want to use MakeCAB to write directly to these folders, they must be available as a network share because MakeCAB currently does not support FTP or HTTP publishing.

Guidelines for Preparing OpenROAD Applications

The eClient Packaging Tool assumes that the OpenROAD applications being published have already been completely tested and debugged. The following conditions apply:

Your application should be partitioned, and any required database access should be accomplished using the OpenROAD Server. The OpenROAD eClient runtime package does not contain Ingres/Net but it can use an existing Ingres/Net installation. OpenROAD client/server-based applications can be deployed using the eClient. However, deploying and configuring Ingres/Net on each workstation is the user's responsibility.

The OpenROAD application images must have been created using the OpenROAD MakeImage utility and be locally available to the MakeCAB utility. For more information on MakeImage, see How You Can Create an Application Image (see page 569).

After you have completed these tasks, you can continue with the generation of the CAB file and publication of the application on your web server.

How You Can Use a Digital Signature

In addition to packaging your application in CAB format, you may want to digitally sign the application. The OpenROAD eClient is digitally signed by Ingres Corporation. When running an eClient application for the first time, users will be presented with a digital signature dialog prompting them to choose whether to install the eClient. The dialog indicates that the digital signature of the eClient has been verified and that the content of the CAB file is safe to install.

The process of digitally signing an application is separate from the creation of the CAB file; it is not part of the MakeCAB utility. To digitally sign an application, you must use Microsoft SignCode or other digital signature utility. For more information on this utility, see the MSDN web site.

It is not necessary that your application be digitally signed; however, clients may need to modify their Internet Explorer settings. For more information, see Change Internet Explorer Security Settings for an Unsigned Application (see page 590).



Change Internet Explorer Security Settings for an Unsigned Application

If you want users to be able to download and run an unsigned application generated by MakeCAB, they must lower their security settings in Internet Explorer. We recommend that the option “Download Unsigned ActiveX Controls” be set no lower than “Prompt.”

To change Internet Explorer security settings

1. Open Internet Explorer.

2. Click Tools, Internet Options.

The Internet Options dialog appears.

3. Click the Security tab and click Custom Level.

The Security Settings dialog appears.

4. Set the Download Unsigned ActiveX Controls to Prompt.

5. Click OK to save your settings and close the Security Settings dialog.

6. Click OK to close the Internet Options dialog.

OpenROAD Web Publisher

The OpenROAD Web Publisher (the eClient Packaging Tool—MakeCAB utility) enables you to do the following:

Generate and publish a CAB file containing your OpenROAD application

Generate and publish a default web page containing the basic formatting (OBJECT tags) required to start the application from a web browser

The Web Publisher consists of seven tab pages and a common button bar used to manage and monitor its tasks. A Status icon on the left side of the button bar validates whether all required information for each tab is present. If information is missing or incorrect on a tab, the Status icon displays a warning symbol; clicking the icon opens a pop-up frame containing detailed information about the error condition.



The following is an illustration of the Web Publisher:

For more information about the Web Publisher interface, see OpenROAD Web Publisher Interface (see page 595).

How You Can Use the OpenROAD Web Publisher

The first five tabs (Project, Control, Contents, Environment, and Install File) define the content of the CAB file. The last two tabs (Libraries and Web Page) define the OBJECT tags that must be included in the HTML page so that the required components are downloaded from the web server when the eClient application is run on user workstations. After the required information is complete, the Build button on the common button bar generates the cabinet file and writes the HTML web page to disk.



makecab.ini—Example and Default Settings

The default settings used for new projects are saved in %II_SYSTEM%\ingres\eclient\makecab.ini. Users can edit this information according to their specifications. The following is an example of a makecab.ini file:

[General] AppsDirectory=C:\ingresii\ingres\eclient\ BackColor=0xFFFFFF CurrentDirectory=C:\ingresii\ingres\eclient\ HomeDirectory=C:\ingresii\ingres\eclient\ TempDirectory=C:\ingresii\ingres\eclient\ TempDirUrl=file:///C:/ingresii/ingres/eclient/

[Oraxp Versions] DefaultVersion=1,1,0,12 Version1=1,1,0,12 Description1=OpenROAD 2006 Version2=1,0,3,7 Description2=OpenROAD 4.1 SP3 Version3=1,0,1,3 Description3=OpenROAD 4.1 SDK Version4=1,0,0,9 Description4=OpenROAD 4.1 SP2

[Complib Versions] DefaultVersion=1,1,0,12 Version1=1,1,0,12 Description1=OpenROAD 2006 Version2=1,0,3,7 Description2=OpenROAD 4.1 SP3 Version3=1,0,1,3 Description3=OpenROAD 4.1 SDK Version4=1,0,0,9 Description4=OpenROAD 4.1 SP2

For more information on each of the parameters in the makecab.ini file, see makecab.ini—Parameter Descriptions (see page 592).

makecab.ini—Parameter Descriptions

The makecab.ini file contains the following sections:

[General]

[Oraxp Versions]

[Complib Versions]



These sections contain the following parameters:

[General]

Contains information used to control default directory locations, URL addresses, and background color for newly created projects. This section contains the following parameters:

AppsDirectory

Specifies the default directory that the file selection dialog uses when adding 4GL image files to your project

BackColor

Specifies the default background color of HTML controls in hexadecimal

CurrentDirectory

Currently not used

HomeDirectory

Specifies the default directory location of project files

TempDirectory

Specifies the default directory to place generated CAB and HTML files

TempDirUrl

Specifies the default URL used for CAB and HTML files

[Oraxp Versions]

Contains lookup information used when selecting the OpenROAD eClient runtime control version number on the Libraries tab of the MakeCAB utility.

The MakeCAB utility loads this section of the makecab.ini file when it is first launched and compares it with the contents of the %II_SYSTEM%\ingres\eclient\oraxp.rel file. This file contains the official historical version information of the current and prior releases of the OpenROAD eClient. Any new versions found in oraxp.rel will be added to the makecab.ini file.



This section contains the following parameters:

DefaultVersion

Specifies the default OpenROAD eClient version to be used when new projects are created. The default version initially is set to the most recent release in the oraxp.rel file.

Version# and Description#

Specifies the default values displayed in the Select eClient Version dialog when you click Choose to select your eClient version. You can define other versions by clicking Add on the Select eClient Version dialog. The information you add will be saved in the makecab.ini file. These new versions must have both a unique version number and description, otherwise they cannot be added.

[Complib Versions]

Contains lookup information used when selecting the Transformation Runtime control version number on the Libraries tab. The historical release information for this file is stored in complib.rel.

XML Project Files

The OpenROAD Web Publisher can save the active package definition to a project file formatted as an XML document. The button bar contains four buttons used to manage these project files. For more information about these buttons, see Common Web Publisher Buttons (see page 595).



OpenROAD Web Publisher Interface

The following sections describe each tab, field, option, and control available in the OpenROAD Web Publisher.

Common Web Publisher Buttons

The OpenROAD Web Publisher contains buttons that are available on all tabs. You use these buttons to maintain the XML project file, build the CAB and HTML files, and provide the user with help and status information about the project and use of the application. The buttons appear dimmed if the operation is not applicable based on the project status.

Status icon

Displays the current status of each tab:

No exclamation point indicates that the information on this tab is complete.

A warning symbol indicates that there is missing or incorrect information on the tab. Clicking this icon provides additional details on the status of the current tab.



New

Creates a new XML project file. A file selection dialog lets you navigate the directory structure. When a new file is entered, default values are loaded into the MakeCAB utility based on the contents of the makecab.ini file.

Open

Opens an existing XML project file. A file selection dialog lets you navigate and select an XML project file. The contents of the XML project file are loaded into the MakeCAB utility. The window title changes to reflect the currently open project file.

Save

Saves the current project to an XML file. A file selection dialog lets you navigate the directory structure and name the file. This button is active only if changes are pending on the current project.

Save As

Saves the current project as a new XML project file. This operation is convenient when duplicating existing projects. A file selection dialog lets you navigate the directory structure and enter a new file name.

Build

Builds the CAB and HTML files for 4GL Control projects, or builds the CAB file for 4GL Library projects. This button is active only when the project contains all the required information. If there are pending changes in the project, you first must save the project to keep the project file in sync with the HTML file.

Exit

Exits the MakeCAB application



Project Tab

The Project tab is used to define the location and URL of the CAB and HTML files. In addition to the Project tab, you must complete the Package and Contents tabs before you can build the CAB.

This tab contains the following fields and controls:

Output cabinet file location

Specifies the location of the CAB file to be generated. If you have read/write LAN access to your web server, you can write the CAB file directly to the server. Otherwise, you must manually move the file there after it is generated locally. You can enter the location directly in the field or use Find to navigate the directory structure and select a file.



Output cabinet URL

Specifies the URL of the CAB file on your web server. This is the location relative to the hosting web page. If the CAB file will be in the same directory as the HTML page, simply enter the name of the CAB file. Otherwise, you can use an absolute URL (that is, http://...) or a relative URL (for example, “/common/cabs/...” or “appcabs/...”).

Output HTML file location

Specifies the output location of the HTML file to be generated. If you enter the location of an existing HTML file, it will be modified each time the CAB is built to keep the version information in the OBJECT tag in sync with the cabinet file.

If you have read/write LAN access to your web server, you can write the CAB file directly to the server. Otherwise, you must manually move the file there after it is generated locally. You can enter the location directly in the field or use Find to navigate the directory structure and select a file.

Application URL

Specifies the URL of the HTML file on your web server. This link is used to launch your eClient application. You can use the Start button to launch the application URL and run the application. Start is active only when both the specified CAB and HTML files exist.

Notes/History

Specifies any useful information or change history that can be stored with the XML project



Control Tab

The Control tab is for entering basic control information used by the OpenROAD eClient runtime to run the application. The contents are placed in the installation file that is part of your CAB file.


Name

(Required) Specifies a descriptive name for your application. This name is displayed in the “%SystemRoot%\Downloaded Program Files” directory.

Description

(Required) Specifies a complete description of the package



Unique Identifier

(Required) Specifies a GUID, a universal unique identifier for your package. This field is automatically generated. Use the Reassign button to generate a new GUID.

Note: After the package is published, you should not generate a new GUID because the connection to the original package will be lost. Instead, use the Version field to trigger clients to download a new version of the package.

Version

(Required) Specifies a mandatory comma-separated list of four numerical values that are used to indicate the version of the package. It is common to start with “1,0,0,0” and increase one or more of these numbers with each new release of the CAB. The four positions specify the major and minor numbers associated with a particular version of the application. For example, a version string of “1,2,3,4” could represent major release 1, minor release 2, version 3, fix level 4.

Changing this value, republishing the CAB, and updating all HTML pages to reflect the new version will trigger a download of the application on client workstations the next time they access the web page. Clicking the Increment button automatically increases the current version number.

Type

(Required) Specifies the type of application:

4GL Control

Only 4GL Control applications can be run.

4GL Library

Library applications are commonly used to distribute included images that represent the infrastructure of many applications. These images often change less frequently than the top-level applications.

For more information on using included libraries, see Libraries Tab (see page 607).



Run Mode

(Required for Type=4GL Control) Specifies the run mode for OpenROAD eClient applications:

Mode 0 (Runs inside the browser window)

Specifies that the application runs inside the browser window as if it is part of the HTML page. Child frames that the application accesses using the callframe statement appear directly in the browser and overlay the parent frame. Returning from the called child frame causes the parent frame to be redisplayed. Child frames accessed by the openframe statement will open in their own client windows.

Note: Closing the browser will cause the application to terminate unconditionally. Because of restrictions in Microsoft's implementation of Internet Explorer, it is not currently possible to trap this event. Reloading the browser page will cause the application to restart, and using the Back or Forward button will cause the application to terminate.

In mode 0, the eClient cannot display menu bars, toolbars, or status bars because these window areas are owned by Internet Explorer. If your application uses any of these constructs and they are essential for the navigation and use of your application, you first must make changes to the OpenROAD application. Menu bars can be emulated on the top form of an OpenROAD user frame with pop-up buttons. Toolbars can be redrawn on the top form. A user-written status bar is necessary to replace the OpenROAD status bar. Child frames that are opened using the openframe statement and applications running in Mode 1 or 2 do not carry this restriction and do not need to be modified.

Mode 1 (Runs as a separate client window)

Specifies that the application runs as a separate client window attached to the browser process. Like Mode 0, closing the browser will terminate the OpenROAD eClient application. Otherwise, the visual behavior of a Mode 1 application is identical to a traditional OpenROAD client application.

Mode 2 (Runs in its own window)

Specifies that applications run in their own window detached from the browser process. Closing the browser has no effect on the application.

Runtime command flags

(Optional) Specifies any runtime flags that are passed to the OpenROAD eClient application when it is run. This field may contain any of the flags that are allowed by the OpenROAD w4glrun command.

For more information on using the w4glrun command, see Command Line Method to Run an Application from an Image (see page 582).



Control background color

(Required) Specifies the hexadecimal background color using the format “0xNNNNNN”. For example, use 0xFFFFFF for white. To open a color selection dialog containing hexadecimal codes and descriptions, click Choose.

Note: The hexadecimal representation uses the HTML-based color representation. The information included in the installation file converts this information to the OLE control hexadecimal color format.

Contents Tab

The Contents tab is used to define the 4GL image and data files held in the CAB file.




4GL Images

Adds OpenROAD image files to the CAB. 4GL Control applications can contain only one image file. Use the Add button to navigate the directory structure and select an OpenROAD image file. To delete a row from the list, select the row and click Remove.

Data Files

Adds any data files required by the application. 4GL Library applications cannot include data files. Any additional resources required by a 4GL Library application should be added as 4GL images. Click Add to navigate the directory structure and select a resource data file. To delete a row from the list, select the row and click Remove.

Deleted Files

Specifies the files to be deleted from the eClient directory on the client workstation when this version of the eClient is installed. Use the Define button to enter an image file or data file that existed in the prior version of the CAB file that you want to delete. To delete a row from the list, select the row and click Remove. Image and data files (from the previous tables) that are deleted from a built cabinet file are automatically added to the deleted files list if they are removed from the CAB.



Environment Tab

The Environment tab is used to define session-level environment variables that are defined to the operating system before the eClient application is run.

Variables can refer to other variables using the syntax %xxx%. These variables are referenced in two passes: the variables that do not reference other variables are followed by the ones that do. You can use only one level of nesting when defining these environment variables.




Add

Opens a pop-up dialog used to enter a new environment variable name and value

Edit

Edits an existing environment variable. Select the environment variable before clicking this button. A pop-up dialog opens, containing the name and value of the variable, which you can change.

Remove

Removes an existing environment variable. Select the environment variable before clicking this button.

The following special environment variables control the eClient runtime environment and can be specified or overridden on the Environment tab:

II_ECLIENT_URL

Contains the value of the URL string used to launch the eClient application. This lets server parameters be passed to the application.

II_ECLIENT_APPDIR

Contains the location of the current eClient applications installation directory named with the application's unique identifier (GUID). This is also the current directory when the OpenROAD eClient runtime executes the application.

II_ECLIENT_ROOT

Contains the parent directory of the application's installation directory. This is useful for constructing references to other application directories.

II_ECLIENT_LIBDIR

Contains the value of the eClient shared library installation directory

II_ECLIENT_RUNMODE

Contains the value of the run mode (0, 1, 2) of the current eClient application.

For more information on run modes, see Control Tab (see page 599).



II_ECLIENT_VERSION

Contains the version string of the eClient runtime currently installed. It is presented in the comma-delimited format also used in the HTML <OBJECT> tag.

II_ECLIENT_ORRUNDIR

Contains the directory value used by the OpenROAD eClient runtime to locate the orrun.dll file. This lets the application package its own version of orrun.dll in its CAB file and use that version independently of the runtime version stored in the standard eClient directory structure.

Install File Tab

The Install File tab displays the contents of the Install4GL.txt file that is packaged with your CAB file and used by OpenROAD eClient runtime to control the properties of the running application.




Install File

Identifies the OpenROAD installer file generated by the Web Publisher based on the settings for your package. This file is included in the CAB file with the Install4GL.exe utility to install the application on the client workstation. This field is display-only and reflects the options selected and data entered in the other tabs of the Web Publisher.

Libraries Tab

The Libraries tab is used to define dependencies on other 4GL library applications. An OpenROAD eClient application is always dependent on the OpenROAD eClient CAB (oraxp.cab). ABF applications transformed into OpenROAD using TransForge will also be dependent on the OpenROAD Transformation Runtime CAB (complib.cab).

You can also create your own user libraries, CAB files you package using the MakeCAB utility. The eClient library applications must be defined as a 4GL Library on the Control tab of the MakeCAB utility when they are generated.



Creating 4GL Libraries is a common and convenient way to publish foundational applications that may be shared among several applications. Foundational applications are typically the OpenROAD image files that are part of the included application list of the OpenROAD image file contained in a 4GL Control application.


OpenROAD eClient runtime control version number

Specifies the OpenROAD eClient version number required by the application. The contents of this field is included as part of the OpenROAD eClient OBJECT tag in the generated HTML file.

You can enter a version from the keyboard or click Choose to open a lookup dialog containing the OpenROAD eClient versions from the [Oraxp Versions] section of the makecab.ini file. You can select a version and click OK, or click Cancel to exit the lookup dialog.

You can add new versions to the makecab.ini file by clicking Add on the lookup dialog. Added versions must contain both a unique version and description. They are permanently added to the end of the [Oraxp Versions] section of the makecab.ini file and displayed at the bottom of the lookup list.

URL of the OpenROAD eClient control

Specifies the URL of the eClient CAB file (oraxp.cab) on your web server. You must place this CAB file on your web server before you can run any OpenROAD eClient applications. This file is located in your %II_SYSTEM%\ingres\eclient directory.

Transformation Runtime is required

Specifies whether your application requires the OpenROAD Transformation Runtime. ABF applications transformed into OpenROAD with TransForge require that this option be selected.

Transformation Runtime control version number

Specifies the Transformation Runtime version number required by the application. The contents of this field are included as part of the Transformation Runtime OBJECT tag in the generated HTML file. You can enter a version number from the keyboard or click Choose to display a lookup dialog containing the Transformation Runtime versions from the [Complib Versions] section of the makecab.ini file. You can select a version and click OK, or click Cancel to exit the lookup dialog.

You can add new versions to the makecab.ini file by clicking Add on the lookup dialog. Added versions must contain both a unique version and description. They are permanently added to the end of the [Complib Versions] section of makecab.ini file and displayed at the bottom of the lookup list.



URL of the Transformation Runtime control

Specifies the URL of the OpenROAD Transformation Runtime CAB file (complib.cab) on your web server. You must place this CAB file on your web server before you can run any OpenROAD Transformation Runtime-based applications. This file is located in your %II_SYSTEM%\ingres\eclient directory.

User Libraries

Lets you specify a 4GL Control Library XML project file containing the 4GL Library application required by this application. Click Add to navigate the directory structure and select a project file.

Web Page Tab

The Web Page tab is used to display the contents of the HTML page that is loaded or generated based on the library dependencies and other information provided in the project. The Build button writes the contents of this tab to the HTML file location provided on the Project tab. Modifications to the library dependencies, unique identifier, version, and background color are immediately reflected on this tab.




Web Page

Displays the loaded or generated HTML. You can modify the HTML and save it. The generated HTML is designed only to provide the basic OBJECT tags required to download and run the application. You may want to use an external HTML editor to perform full page layout.

Note: After the HTML page is generated by the Web Publisher, the only subsequent modifications that MakeCAB makes to it are to ensure that the information in the OBJECT tags is kept up to date. For example, although the Application Description is used initially to generate the TITLE tag of the HTML page, changes to the Description will not be reflected in the TITLE tag. The Web Publisher works this way to preserve any formatting of the HTML page that was performed in an external HTML editor.

Use the Web Deployment Assistant to Create a Web Deployment Package

Starting on the Deploy tab, you use the Web Deployment Assistant (wizard) to create web deployment packages. To create a web deployment package, follow these steps:

1. Click the header bar of the Web Deployment Packages portlet on the Deploy tab to activate it.

2. Click the New icon on the toolbar.

The Web Deployment Assistant appears.

3. Select one of the following options:

Automatically configure the application selected on the Develop tab.

Select an application image file to deploy.

Import a package created with the eClient Packaging Tool.

Manually create a web deployment package.

4. Select a web server.

5. Select a target folder for eClient files.

6. Name your web deployment package configuration file (.xml).

Your web deployment package is saved and displayed in the Web Deployment Packages portlet. When selected, the details for the package are displayed in the portlet tabs on the right side of the Deploy tab. For more information on the portlet tabs, see Deploy Tab (see page 56).

mClient Deployment


mClient Deployment

The OpenROAD Mobile Client (mClient) lets you deploy and run OpenROAD applications on a Pocket PC 2003. mClient consists of:

OpenROAD runtime

OpenROAD Remote Server Object for the Pocket PC

These components enable application developers to develop OpenROAD applications on a desktop and run them on a Pocket PC. They also support communication between an OpenROAD application on a Pocket PC and an OpenROAD Server, using wireless protocols to access data stored in Ingres and other DBMS databases.

How You Can Install mClient

You can install mClient on a Pocket PC 2003 or on a desktop using the emulator, which is a program that runs complete Pocket PC 2003 software independently on your desktop PC.

Note: For more information and links to Pocket PC resources, see the readme file in the following OpenROAD installation directory:

II_System\ingres\mclient

mClient consists of two CAB files, located in the %II_SYSTEM%\ingres\mClient directory. When you run these files, they install the mClient in the %II_SYSTEM%\ingres\mClient directory.

The two CAB files are:

ormc_ppc.ARMV4.CAB

Installs the mClient on a Pocket PC 2003

ormc_ppc.WCE420X86.CAB

Installs the emulator, which is used to test the mClient applications on a desktop without using the actual Pocket PC 2003

mClient Deployment


To install the mClient

Locate the shared folder to get the appropriate file, and double-click to run it.

All included application images must reside in the same directory of the calling application image. If you call any functions from an OpenROAD package (for example, the AVERAGE function of the stat.pkg), you must put that package in the same directory of your application on the Pocket PC.

For more information on installing Pocket PC software, see the Readme_mClient.txt file in the %Ingres_II%\ingres\mclient directory.

Launch mClient

Launch the mClient application by tapping the OpenROAD application image, using the stylus pen.

In the emulator, you can launch an OpenROAD application by double-clicking the application image file.

Differences Between Desktop and Pocket PC

When you run OpenROAD on a desktop and run it on a Pocket PC, you will see some differences. The following sections describe some of those differences.

Frame Title and the Navigation Bar

Across the top of the Pocket PC screen is the navigation bar. It contains the title of the foreground window, the current time and an OK or Smart Minimize button. The foreground OpenROAD frame title is displayed on the navigation bar.

OK and Smart Minimize Button

The Smart Minimize (X) button does not close the application but minimizes it by putting it behind the desktop/today window. The OK button closes the frame. Which button appears on the navigation bar is decided by the IsTitled, IsClosable, and IsMinimizable attributes of the FrameSource class.

Is Titled Is Closable Is Minimizable Navigation Bar Button

True Nothing

False True OK Button

False False True MinimizeButton

How You Can Create and Distribute Help Files


Is Titled Is Closable Is Minimizable Navigation Bar Button

False False False Nothing

Menu Bar

The menu bar on the Pocket PC appears at the bottom of the screen and the foreground window owns the menu bar. The OpenROAD frame menu bar appears at the bottom. There is a limit of 8 menus maximum on the menu bar and 16 menu items per menu.

Bottom Tabfolder

You can create a Pocket PC-style bottom tabfolder by setting the tabbar BarPosition attribute to the new POS_BOTTOM value. You need to make the tabfolder as big as the mClient frame template and set each tab page BgColor attribute to CC_WHITE and set the tabbar attributes to the following attributes:

Tabbar Attribute

SelectedTabColor CC_WHITE

TabShape COR_SQUARE

BarPosition POS_BOTTOM

NormalTabColor CC_SYS_BTNFACE

TabBgColor CC_SYS_BTNFACE


OpenROAD includes a Help button on the menu bar of each window to access information about OpenROAD procedures and reference material, such as description of various editors, 4GL syntax, system classes and their methods, and events.

The information is displayed in the standard Windows Help format, with hypertext links between topics.

You can also create your own help text files and link the files to your OpenROAD application. The steps in the following sections provide an overview of the procedures for creating and linking Help files.



Create Help Files

On UNIX platforms, no default help compiler is provided. Help files created on Windows platforms, however, can be read using the UNIX version of OpenROAD.

If you are creating your own Help files in a Windows environment, perform the following procedure.

To create Help files in a Windows environment

1. Author the topic files and save them as .RTF (rich text format) files.

2. Using any system editor, create an .HPJ project file that lists all the .RTF topic files in your online help system and any options, such as secondary windows and color for non-scrolling regions.

3. Run the .HPJ file through the Windows 95 or Windows NT Help compiler.

The output is a compiled .HLP file that you can specify in your application and view with the Windows Help Viewer.

Specify Help Files in Your Application

You can specify help files for your application using an “on Click” event block.

To link your Help files to your application

1. Decide which Help menu items you want in your application (for example, Contents, Search, How to Use Help).

2. Create a Help menu for each frame that calls the Help file.

Note: You can speed this process by adding the Help menu to the frame template for your application.

3. For each menu item, write an “on Click” event block that calls the following method:

CurSession.WinHelp(command=commandname,topic='Topic Title',context=context, helpfile='filename.hlp');

For more information about the WinHelp method, see online help.



If the Help file specified does not include the path, this method searches for the named Help files in the following locations in the order listed (if the help file is a full name, no search occurs):

The location of the application.img file

II_W4GLAPPS_DIR

%II_SYSTEM%\ingres\w4glapps

Note: During development—that is, when running the application from the database—you can place the development Help file in II_W4GLAPPS_DIR. During deployment, move the Help file to the same location as the application image file.

Call Help Topics

There are various ways to manipulate the help system from your application.

To call the table of contents for the online help system

on Click = { CurSession.WinHelp (command=HV_CONTENTS,helpfile='myapp.hlp'); };

To call help for fields

Context-sensitive help for fields requires that each field have a help topic associated with it. One way to do that is to embed the field help topic in the field's ClientText attribute. For example, the client text for a field could contain the string “helptopic=Employee Name;”.



You can use the following code to check for the keyword “helptopic” in the field's client text at runtime. If the keyword is found, the code calls Help and specifies the value for that keyword as the topic:

on Click = declare topic = varchar(32) not null; enddeclare { if CurFrame.InputFocusField is not null then topic = _StringParseKeyword(keyword = 'helptopic', string= CurFrame.InputFocusField.ClientText); if topic != '' then CurSession.WinHelp(command = HV_KEY, topic = topic, helpfile = 'myapp.hlp'); else message 'No help for this field.'; endif; else message 'Select a field before choosing Field Help.'; endif; }

Note: _StringParseKeyword() is a general-purpose procedure, documented in online help and the Programming Guide.

To display online help for a frame

on Click = { CurSession.WinHelp(command = HV_KEY, topic = 'Add Employees', helpfile = 'myapp.hlp'); }

To call information about the help system itself (that is, to include the How To Use Help menu command)

on Click = { CurSession.WinHelp(command = HV_HELPONHELP, helpfile = 'myapp.hlp') }

For more information about creating help files, see the Microsoft Visual C++ Help documentation.

Environment Variables 617

Appendix A: Environment Variables This section contains the following topics:

How You Can Set Environment Variables (see page 617) Environment Variables for All Platforms (see page 619) Environment Variables for Windows (see page 626) Environment Variables for Ingres Installations (see page 627) How You Can Use International Characters (see page 628) How You Can Specify Color Tables (see page 629)

OpenROAD uses environment variables extensively to control its behavior. You can set these environment variables on a per-installation or a per-user basis to customize the operation of OpenROAD. Some of these variables are available only when connecting to an Ingres database.

The lists in the following sections describe all the environment variables available on each platform, along with the possible values that you can assign, and the default value used if you do not set the variable.

How You Can Set Environment Variables

You can set environment variables in the following ways:

Set the environment variable as you would any other environment variable according to your operating system rules.

Set the environment variable in a special text file called symbol.tbl that resides in the “files” directory of your OpenROAD installation.

During the installation of OpenROAD, the installation process creates a default version of this file that should suffice for most user's needs.

If you specify an environment variable both in the system environment and in the symbol.tbl file, the system value takes precedence over the symbol.tbl value. This enables you to override the per-installation values specified in the symbol.tbl file (that multiple users would access) by per-user values (especially on multi-user systems such as Windows NT and UNIX) set in the current user environment.

Some entries in the following lists say “if defined,” which means that you need not assign any particular value to the variable; any value you assign will activate the meaning of the variable. Note, however, that you cannot use an empty value (for example, you cannot specify only “keyword =”). Instead, use a meaningful value such as TRUE.

How You Can Set Environment Variables


How You Can Use the symbol.tbl File

The symbol.tbl file is maintained by the following Ingres utilities:

ingsetenv utility

Lets you set environment variables. Issue a command using the following format:

ingsetenv keyword value

keyword

Specifies one of the environment variables discussed in this appendix

value

Specifies the text of a legal value for the variable being set

ingunset utility

“Unsets” environment variables and uses the following format:

ingunset keyword

keyword

Specifies one of the environment variables discussed in this appendix

ingprenv utility

Displays the current settings of all defined environment variables in the symol.tbl file

The symbol.tbl file usually resides in the “files” directory of your OpenROAD installation. You must have a system environment variable called II_SYSTEM set to point to your OpenROAD installation for OpenROAD to execute properly. You can change the location of the symbol.tbl file by setting a system environment variable called II_CONFIG to specify the full path name of the file.

For more information on these utilities, see the Ingres Command Reference Guide.

Environment Variables for All Platforms



The following environment variables apply to OpenROAD on all platforms:

IIW4GL_DEBUG_3GL

Specifies that OpenROAD produces a trace listing of all 3GL procedures (defined in the Component Catalog) as they are called during execution. This can be useful for debugging.

II_4GL_DECIMAL

Specifies the decimal point character for 4GL source. Valid values are “.” and “,”. This variable is different from II_DECIMAL, which OpenROAD uses for data representation and database access, so you must set both to completely change the decimal point character.

Default: “.”

II_CHARSET

Specifies the name of a character set file. Valid values are:

arabic chineses chineset decmulti elot437 greek hebrew hproman8 ibmpc437 ibmpc850 iso88591 iso88592 iso88595 iso88599 kanjieuc korean shiftjis slav852 thai

Default: a default internal character set

For more information, see How You Can Use International Characters (see page 628).



II_CHARSETxx

Specifies the name of a character set file for this OpenROAD installation. The xx suffix is the value of the II_INSTALLATION variable. If you do not define II_INSTALLATION, II_CHARSET is used instead. Default and valid values are the same as for II_CHARSET.

For more information, see How You Can Use International Characters (see page 628).

II_COLORTABLE

Specifies the name of a color table file in the “files” directory of the OpenROAD installation. If neither II_COLORTABLE nor II_COLORTABLE_FILE is given, the default is wdepth4.ctb or wdepth8.ctb for Windows and depth4.ctb or depth8.ctb for UNIX, depending on the pixel depth of the display being used. Displays with fewer than 256 colors (such as 64 or 16) use the depth4 files; displays with 256 or more use the depth8 files. Specifying II_COLORTABLE_FILE overrides this variable.

For more information, see How You Can Specify Color Tables (see page 629).

II_COLORTABLE_FILE

Specifies the full path specification of a color table file. If you do not set this, OpenROAD uses II_COLORTABLE instead.

II_CONFIG

Specifies the location for a variety of configuration and message files used by OpenROAD and Ingres. These files include symbol.tbl, which holds other environment variable settings. These files are opened in both read-only and read-write modes. You must have read/write privileges on the directory that this variable specifies. You can set this environment variable using symbol.tbl. You can also redirect log files using II_LOG.

Default:

Windows:

%II_SYSTEM%\ingres\files

UNIX:

$II_SYSTEM/ingres/files



II_DATE_FORMAT

Specifies the date format for DATE values retrieved by a database access. This is different from the display formatting you can use to show DATE values in a form. Valid values include:

multinational multinational4 finland sweden iso us german

Default: us

II_DECIMAL

Specifies the decimal point character for floating and decimal data values retrieved by database access. Valid values are “.” and “,”. This is different from II_4GL_DECIMAL that OpenROAD uses for 4GL source, so you must set both variables to completely change the decimal point character.

Default: “.”

II_EDIT

Specifies a system editor that OpenROAD uses instead of its own Script Editor for viewing or editing scripts

II_FONT_CONVENTION

Specifies a font convention file that describes mappings for font names. OpenROAD provides these files in the “files” directory of the OpenROAD installation.

To use one of these files, specify its name (without the .ff suffix) as the value of II_FONT_CONVENTION.

II_FONT_FILE

Specifies a font convention file that describes mappings for font names. If this file does not have the suffix .ff or is not located in the “files” directory of the OpenROAD installation, specify the path and full file name as the value of II_FONT_FILE.

II_INSTALLATION

Specifies a network installation code used by many subsystems of OpenROAD. Valid values are up to three alphabetic characters, or one alphabetic and one numeric character.

This variable is typically set during OpenROAD installation. If you install OpenROAD and another Ingres toolset on the same computer, the values of II_INSTALLATION for the two must be different.

Default: the empty string for some things and II for others



II_KEYBOARD

Specifies the name of a keyboard mapping file contained in the “files” directory of your OpenROAD installation. For more information, see Speed Key Mapping (see page 631) and II_KEYBOARD (see page 631).

II_KEYBOARD_FILE

Specifies the full path and file name of a keyboard mapping file that either does not have the default .kbd suffix or does not reside in the “files” directory of your OpenROAD installation. Specifying this variable overrides the II_KEYBOARD variable. For more information, see Speed Key Mapping (see page 631) and II_KEYBOARD_FILE (see page 632).

II_LANGUAGE

Specifies the natural language used by this OpenROAD installation. This variable determines the default location of the message text files and other things. Possible values are:

english japanese french flemish german italian dutch finnish danish spanish swedish norwegian hebrew

Default: english

II_LIBU3GL

Specifies the file names of the dynamic link libraries containing your 3GL procedures. If you specify more than one file, separate file names with semicolons (;).

The path (directory) is optional. It is needed only if the DLL is not in the current directory.

II_LOG

Specifies the location for the w4gl.log file. OpenROAD uses this file at runtime. If II_LOG is not specified, %II_SYSTEM%\ingres\files (for Windows) or $II_SYSTEM/ingres/files (for UNIX) is used.



II_MONEY_FORMAT

Specifies the currency format to use for money values retrieved by database access. You must specify L: (for leading) or T: (for trailing) followed by a currency symbol (one or more characters). This is different from the display formatting you can use to show money values in forms.

Default: L:$

II_MONEY_PREC

Specifies the number of decimal places to use for money values retrieved by database access. Valid values are 0, 1, and 2. This is different from the display formatting you can use to show money values in forms.

Default: 2

II_MSGDIR

Specifies the location of the OpenROAD message text files. Default is the “files/language” directory. (See II_LANGUAGE for possible values.) Usually set during OpenROAD installation.

II_SCREEN_HEIGHT_INCHES

Specifies the height of the display in inches. If desired, you may use millimeters instead by setting II_SCREEN_HEIGHT_MMS. Setting only one of II_SCREEN_HEIGHT_xxxx or II_SCREEN_WIDTH_xxxx enables OpenROAD to calculate the other value to preserve the aspect ratio based on the pixel size of the display. These values are used to translate OpenROAD dimensions (in 1000ths of an inch) to screen pixels. You need not specify this value. If not specified, OpenROAD calculates the values from the information provided by the windowing system.

II_SCREEN_HEIGHT_MMS

Specifies an alternative method of specifying screen height in millimeters. See II_SCREEN_HEIGHT_INCHES.

II_SCREEN_WIDTH_INCHES

Specifies the width of the display in inches. If desired, you may use millimeters instead by setting II_SCREEN_WIDTH_MMS. Setting only one of II_SCREEN_HEIGHT_xxxx or II_SCREEN_WIDTH_xxxx enables OpenROAD to calculate the other value to preserve the aspect ratio based on the pixel size of the display. These values are used to translate OpenROAD dimensions (in 1000ths of an inch) to screen pixels. You need not specify this value. If not specified, OpenROAD calculates the values from the information provided by the windowing system.

II_SCREEN_WIDTH_MMS

Alternative method of specifying screen width in millimeters. See II_SCREEN_WIDTH_INCHES.



II_SYSTEM

Specifies the location of your OpenROAD installation. This environment variable is usually set during the installation process.

II_TEMPORARY

Specifies the path name of a directory that OpenROAD uses to store temporary files. If not specified, OpenROAD uses the current directory.

II_VIEW


II_W4GLAPPS_DIR

Specifies the path for the location of OpenROAD application image files, often used for included applications. If not set, II_W4GLAPPS_SYS is used.

II_W4GLAPPS_SYS

Specifies the path for the location of the OpenROAD system image files. If not set, the following directories are used:

Windows:

%II_SYSTEM%\ingres\w4glapps

UNIX:

$II_SYSTEM/ingres/w4glapps

II_W4GL_CACHE_LIMIT

Specifies the size, in bytes, of the Source Object Cache. Setting this environment variable causes OpenROAD to free unused objects when the size of the cache exceeds this amount. If you do not set this variable, objects are stored in the cache until OpenROAD exits.

II_W4GL_HASSTATUSBAR

Specifies whether informational messages for the menu items in Workbench are displayed in the frame's status bar when each menu item is highlighted by the mouse. Set to TRUE to enable this feature.

Default: FALSE (the status bar displays no messages)

Note: For user frames, you must set the HasStatusBar property in the Property Inspector.



II_W4GL_LINEWIDTHS

Overrides the default settings for LW_MINIMUM, LW_VERYTHIN, LW_THIN, LW_MIDDLE, LW_THICK, and LW_MAXIMUM (and its equivalent, LW_VERYTHICK). The value of this variable must be a list of six values separated by commas. Each value represents its respective line width in pixels. All values within the list must be present, and none can be equal to zero. The list must be in a non-decreasing order, for example, the default values may be specified as 1,3,5,7,9,11, or 1,2,3,4,5,6 or 2,9,9,9,9,20.

II_W4GL_OPEN_IMAGES

Specifies the maximum number of image files OpenROAD keeps open at a time. If you specify zero, OpenROAD keeps an unlimited number of open image files.

Limits: Minimum value is 2

Default: 10

II_W4GL_SYSTEMEDITOR

Specifies whether the system editor is automatically invoked instead of Workbench's built in Script Editor. Possible values are:

TRUE

Specifies that the system editor is opened

FALSE

Specifies that OpenROAD's built-in Script Editor is opened

II_WINDOWEDIT

Specifies a system editor that OpenROAD uses instead of its own Script Editor for editing scripts

For more information, see How You Can Use Your System Editor (see page 442).

II_WINDOWVIEW

Specifies a system editor that OpenROAD uses instead of its own Script Editor for viewing scripts

For more information, see How You Can Use Your System Editor (see page 442).

ING_EDIT


PICTURE_DIR

Specifies the path for the directory in which to store bitmap image files. This environment variable is used by field templates that display images.

Environment Variables for Windows


STRING_DIR

Specifies the path for the directory in which to store string object files. This environment variable is used by field templates that save and load string objects from files.

VASA_FILE

Specifies a path and file name for the OpenROAD Server Manager initialization file. (The default file is vasa.ini in the II_SYSTEM\ingres\files directory.) This variable is checked when the Server Manager starts. If the variable is not null and points to a valid file, then that file is used instead of the default vasa.ini. If this variable is not specified, OpenROAD then checks the II_CONFIG variable. If this variable is not null and points to a valid file, then that file is used instead of the default vasa.ini. Lastly, II_SYSTEM is checked.

For more information on the Server Manager, see the Server Reference Guide.

More information:

Writing Scripts and Procedures (see page 435)

Environment Variables for Windows

The following environment variables apply to OpenROAD installations on Windows platforms:

II_FORCE_C_CONVENTION

Specifies that OpenROAD always uses the C language calling convention when calling your 3GL procedures, regardless of the language setting in the 3GL Procedure component editor. This is necessary for Windows NT.

Default: the language given by the 3GL procedure definition

II_TRUNCATE_W4GL_LOGFILE

Specifies that OpenROAD continually monitors the log file size to ensure that it never grows beyond 32768 bytes.

Environment Variables for Ingres Installations


Environment Variables for Ingres Installations

The following environment variables apply to OpenROAD installations connecting to an Ingres database:

II_CONNECT_LOG

Specifies a full path and file name for OpenROAD to use to log database connections. If not given, no logging is performed.

II_CONNECT_RETRIES

Specifies a maximum number of retries to use when connecting to the database, and whether to delay retrying. Valid values are any positive integer number greater than zero optionally followed by “d” or “D” to specify delaying retries.

Default: one try with no delay

II_W4GL_LOCKS

Lets you modify the default number of page locks for an encoding table to any value appropriate to the environment. For example, if frames are small or development is taking place in a single-user environment, the value can be lowered. For more information, see How You Can Set Page Locks (see page 627).

How You Can Set Page Locks

The default number of page locks for the II_ENCODINGS and II_SRCOBJ_ENCODED catalogs is 80. This number should be adequate under most circumstances. In addition, the II_W4GL_LOCKS environment variable lets developers modify the default number of page locks for the encoding table to any value appropriate to the environment. If frames are small or development is taking place in a single-user environment, the value can be lowered.

The following simple Terminal Monitor script can help you evaluate the number of pages used for encoding the various components in your OpenROAD development database. The query provides a list of components and the number of pages needed to store their encoding. The displayed number helps you decide whether you must set the II_W4GL_LOCKS environment variable and what value to assign to it.

How You Can Use International Characters


/* Terminal Monitor script to find the largest encoded component */

create view w4gl as select entity_id = encode_object, num_pages = count(encode_sequence) from ii_encodings group by encode_object union all select entity_id, num_pages = count(sequence_no) from ii_srcobj_encoded group by entity_id

\p\g select e.entity_name, w.entity_id, num_pages = sum(w.num_pages) from w4gl w, ii_entities e where w.entity_id = e.entity_id group by entity_name, w.entity_id order by num_pages \p\g drop view w4gl \p\g \q

How You Can Use International Characters

When inserting and retrieving international characters using OpenROAD, you may need to set the environment variable II_CHARSETxx on the client side, with the suffix xx being the value of the client's II_INSTALLATION variable. Possible configurations follow.

For an OpenROAD client against any Ingres server:

If the client's II_INSTALLATION is "II," you must add the value of II_CHARSETII to the symbol.tbl file. For example:

II_CHARSETII = iso88591

Then you must shut down and restart Ingres Networking.

For an OpenROAD client running against a local Windows NT Ingres server:

If the NT server does not have its II_CHARSETxx defined, nothing needs to be done.

If the NT server has its II_CHARSETxx defined, you first must set the II_CHARSETxx variable in the OpenROAD client's symbol.tbl file to the same value as the server. Then shut down and restart Ingres Networking.

How You Can Specify Color Tables



A Color Table file is a plain text file that contains lines of color definitions. The color definitions must be in a certain order and a certain format. There must be exactly 62 color definitions to redefine the OpenROAD colors. Lines beginning with blank, “*”, or the tab character are considered comments.

Each line consists of three numeric values from 0 to 255 separated by spaces or tabs that are the red, green, and blue values of the color respectively. The fourth string on the line is the name of the color.

For example, these entries are taken from the wdepth8.ctb file supplied with OpenROAD:

Red Green Blue Resulting Color

255 0 0 Light red

0 255 0 Light green

0 0 255 Light blue

255 255 0 Light yellow

0 255 255 Light cyan

255 0 255 Light pink

128 64 0 Light brown

255 128 0 Light orange

128 0 255 Light purple

160 160 164 Light gray

The color definitions must be in the following order:

1. Light red 20. Gray

2. Light green 21. Pale red

3. Light blue 22. Pale green

4. Light yellow 23. Pale blue

5. Light cyan 24. Pale yellow

6. Light pink 25. Pale cyan

7. Light brown 26. Pale pink

8. Light orange 27. Pale brown

9. Light purple 28. Pale orange



10. Light gray 29. Pale purple

11. Red 30. Pale gray

12. Green 31. Custom 1

13. Blue 32. Custom 2

14. Yellow 33. Custom 3

15. Cyan ...

16. Pink 59. Custom 29

17. Brown 60. Custom 30

18. Orange 61. Black

19. Purple 62. White

In OpenROAD, the CC_FOREGROUND and CC_BACKGROUND colors are set using the values of the window text and window background as set in the Color applet of the Control Panel.

Speed Key Mapping 631

Appendix B: Speed Key Mapping This section contains the following topics:

Keyboard Map Files (see page 631) Keyboard Mapping (see page 633)

OpenROAD lets you assign speed keys to menu buttons and toggles by selecting a logical key name for the menu item from a list of supplied constants. The logical key assigned to the menu item may map to the keys on physical keyboards differently. This appendix discusses how you can customize keyboard mappings, and how the logical key names map by default to various physical keyboards.

Keyboard Map Files

At startup time, OpenROAD performs a default mapping of logical key names to physical keyboard keys that is most appropriate for your system. The default mapping can be overridden, however, by specifying a keyboard map file. A keyboard map file contains an alternative mapping of logical names to physical keyboard keys that may be more appropriate for your needs than the default mapping.

How You Can Specify a Keyboard Map File

There are two environment variables you can use to specify a specific keyboard map file:

II_KEYBOARD

II_KEYBOARD_FILE

For more information about how to set environment variables in OpenROAD, see Environment Variables (see page 617).

II_KEYBOARD

This variable specifies the prefix name of a text file containing the custom keyboard mapping. OpenROAD makes two assumptions about the file specified by prefix name with II_KEYBOARD:

The file has a file extension of .kbd.

The file resides in the "files" directory of the OpenROAD installation.

Keyboard Map Files


Windows:

%II_SYSTEM%\ingres\files\prefix_name.kbd

UNIX:

$II_SYSTEM/ingres/files/prefix_name.kbd

II_KEYBOARD_FILE

You can specify a full path name and file extension for a keyboard map file by using the II_KEYBOARD_FILE environment variable. If this environment variable has a value, it takes precedence over the value of II_KEYBOARD.

How You Can Format Keyboard Map Files

The OpenROAD keyboard map file is a text file with a specific format. The file describes 23 OpenROAD system-defined keys and 36 user-defined keys. The file contains one line for each key with four entries for each line. The entries are arranged in four columns separated by tabs. All of the columns are mandatory.

Because the contents of some columns require specific values, it is best to copy an existing keyboard map file as a template if you want to modify the file or create a new one.

The following table describes the columns:

Column Description

1 Index that OpenROAD uses to map the key. It is read into memory and must always match the text label in column 4.

Note: Do not change the entries in this column.

2 Text that appears in the pull-down menu for the speed key

3 Virtual key name for the keystroke that occurs

4 Internal symbol name used by OpenROAD, which must match the text label in column 1

Note: Do not change the entries in this column.

Keyboard Mapping


Keyboard Mapping

You can use the following virtual key definitions to define keystrokes:

VK_BACK VK_TAB VK_RETURN VK_SHIFT

VK_CONTROL VK_MENU VK_PAUSE VK_CAPITAL

VK_ESCAPE VK_SPACE VK_PRIOR VK_NEXT

VK_END VK_HOME VK_LEFT VK_UP

VK_RIGHT VK_DOWN VK_SCROLL VK_0

VK_1 VK_2 VK_3 VK_4

VK_5 VK_6 VK_7 VK_8

VK_9 VK_A VK_B VK_C

VK_D VK_E VK_F VK_G

VK_H VK_I VK_J VK_K

VK_L VK_M VK_N VK_O

VK_P VK_Q VK_R VK_S

VK_T VK_U VK_V VK_W

VK_X VK_Y VK_Z VK_NUMPAD0

VK_NUMPAD1 VK_NUMPAD2 VK_NUMPAD3 VK_NUMPAD4

VK_NUMPAD5 VK_NUMPAD6 VK_NUMPAD7 VK_NUMPAD8

VK_NUMPAD9 VK_MULTIPLY VK_ADD VK_SEPARATOR

VK_SUBTRACT VK_DECIMAL VK_DIVIDE VK_F1

VK_F2 VK_F3 VK_F4 VK_F5





VK_F22 VK_F23 VK_F24 VK_NUMLOCK

VK_LSHIFT VK_RSHIFT VK_LCONTROL VK_RCONTROL

VK_LMENU VK_RMENU VK_INSERT VK_DELETE

Keyboard Mapping


If a key is defined in the mapping file, it will activate if assigned to an actual menu item. For example, if the VK_RETURN key is mapped to SK_USER1 and SK_USER1 is not used, it does not change any behavior. On the other hand, if it is assigned to a menu item attached to the frame, it overrides the default behavior and raises that event block.

The same mapping is used for all platforms. However, the older definitions in the PC keyboard files still work. Any keyboard file that used UNIX definitions must be changed to use the new virtual key definitions.

There are 104 different key definitions available. OpenROAD has a limit of 59 slots available for speed key definitions that are active for the life of a session.

Keyboard File Map Example

The following is an example of a keyboard map file:

Index Pull-down Menu Text Virtual Key Name Internal Symbol Name

-23 Shift+Ctrl+S Shift-Ctrl-VK_S SK_SAVE_AS

-22 Shift+Ctrl+R Shift-Ctrl-VK_R SK_REPLACE_FIND

-21 "" "" SK_LOOKUP

-20 "" "" SK_FIND

-19 F8 VK_F8 SK_DETAILS

-18 Shift+Ctrl+F Shift-Ctrl-VK_F SK_NEXT

-17 F1 VK_F1 SK_HELP

-16 F7 VK_F7 SK_PROPS

-15 F11 VK_F11 SK_TFFIND

-14 F12 VK_F12 SK_TFDELETEALLROWS

-13 F2 VK_F2 SK_TFINSERTROW

-12 F3 VK_F3 SK_TFDELETEROW

-11 F5 VK_F5 SK_GO

-10 F4 VK_F4 SK_SAVE

-9 Ctrl+F4 Ctrl-VK SK_CLOSE

-8 Ctrl+X Ctrl-VK SK_CUT

-7 Ctrl+V Ctrl-VK SK_PASTE

-6 Ctrl+C Ctrl-VK SK_COPY

Keyboard Mapping


Index Pull-down Menu Text Virtual Key Name Internal Symbol Name

-5 Shift+F2 Shift-VK_F2 SK_DUPLICATE

-4 Del VK_Delete SK_DELETE

-3 Alt+F4 Alt-VK_F4 SK_QUIT

-2 Ctrl+Z Ctrl-VK_Z SK_UNDO

-1 Shift+Ctrl+Z Shift-Ctrl-VK_Z SK_REDO

1 Ctrl+1 Ctrl-VK_1 SK_USER1


...



11 Ctrl+A Ctrl-VK_A SK_USER11

12 Ctrl+B Ctrl-VK_B SK_USER12

...

35 Ctrl+Y Ctrl-VK_Y SK_USER35

36 Ctrl+F5 Ctrl-VK_F5 SK_USER36

Data Format Templates 637

Appendix C: Data Format Templates This section contains the following topics:

Format Templates (see page 637) Input Masking and Data Validation (see page 638) Numeric Templates (see page 638) Date Format Templates (see page 643) Varchar Templates (see page 650)

This appendix provides information about using data format templates for single-line entry fields. A single-line entry field provides one line on which you can either display information for the end user or let the user enter (or modify) information. This appendix discusses:

A general discussion of format templates and input masking and their relationship to the data type of an entry field

Valid formats for numeric and date fields

Defining formats for varchar fields

Format Templates

After adding a single-line entry field to your form, you can use the Property Inspector to define a format template for the data to be displayed in the field. A format template is a picture of how the data in a field should look, and specifies what type of data the end user can enter.

Format Templates for Field Types

The data type of the field determines many of the characteristics of the format template. For each data type, you can define a custom format.

For numeric and varchar data types, a format template consists of character set definitions and special characters that represent the valid characters that the end user can enter.

Input Masking and Data Validation


To the end user, the template provides visual clues about the type and format of the data to be entered. In OpenROAD, each character set definition in the template represents one or more valid characters. For more information, see Numeric Templates (see page 638) and Varchar Templates (see page 650), respectively.

For date data types, end users follow the form of the example date in the field to enter the actual date. For more information, see Date Format Templates (see page 643).

How You Can Set the Format Template at Runtime

As an alternative method to using the Property Inspector, you can set the format template at runtime. To do so, set the EntryField's FormatString attribute in your 4GL code, using the following syntax:

's"FormatString"'

Input Masking and Data Validation In conjunction with formats, OpenROAD provides input masking. Input masking ensures that end users always enter a valid character in a field that has a format specified. If the end user enters a character that is invalid for the field's format, the machine beeps and the end user cannot leave the position or field until a correct entry is made.

For numeric and date fields, the validity of the end user's entry is checked when the end user attempts to leave the field. If the field has input masking enabled (turned on), then the validity is checked as the data is entered. Inappropriate keystrokes cause the machine to beep, and the incorrect values are not accepted. Similarly, input masking can also be enabled for varchar fields when using data format templates.

Input masking is an optional feature for numeric, date, and varchar entry fields. That is, you can specify a format template for a numeric, date, or varchar field without enabling the input masking feature.

Numeric Templates

Numeric templates consist of one or more special characters. Each of the special characters represents what data can be entered at that position in the number.

Numeric Templates


Define a Numeric Template

You can define a numeric template using the Property Inspector.

To define a numeric template

1. Open an existing user frame or create a new frame in the Component portlet of the Develop tab.

2. Place an entry field on the form.



4. Select Integer from the base data type option field.

5. Click OK.

6. Click the DefaultValue property, and then select DV_STRING from its list of options.

7. Click the FormatString property.

An entry field opens:

8. Enter a format template in this entry field (for example, +++,+++,+++), and then press Enter.

For more information about specifying numeric templates and for examples, see Numeric Template Syntax (see page 640).

9. (Optional) Set the InputMasking property to TRUE.

For information about how input masking affects the end user's interaction with the template, see Input Masking and Numeric Templates (see page 643).

Numeric Templates


10. (Optional) Specify other properties for the entry field, such as IsMandatory and IsPassword.

Note: For complete descriptions of each field property, see Single-line Entry Field Properties (see page 191) and Common Field Properties (see page 239).

11. Select any of the Save commands from the Frame Editor's File menu.

Numeric Template Syntax

Numeric templates consist of one or more special characters. A special character represents some set of characters. The end user can enter any character in the set defined for a special character in the position occupied by the special character.

When you create a numeric template, use one special character for each space of the column width. For example, “$$$$” specifies that the column is four digits wide and a dollar sign should be printed to the left of whatever number is displayed in the field.

Note: You must use quotation marks around the template characters when you specify a template in the Property Inspector. Likewise, if you are setting the FormatString attribute in your 4GL code, you must use quotation marks. For more information about the FormatString attribute, see the Language Reference Guide.

You can include any printable character directly in a template by preceding it with a backslash. For example, to include the percent symbol in a template, enter \%. The backslash does not appear in your data.

Special Template Characters

The following table describes the special template characters:

Code Description

n If a digit remains in the number, display the digit. If no digits remain, display zero.

z If a digit remains in the number, display the digit. If no digits remain, display a space.

This code is used for standard blank-padded numeric fields.

Numeric Templates


Code Description

$ If a digit remains in the number, display the digit. If no digits remain, display a floating dollar sign immediately to the left of the last digit. If a dollar sign has already been displayed, display a space.

This code can be used to display a dollar sign directly to the left of the number or to place a dollar sign in a fixed position in the field.

– If a digit remains in the number, display the digit. If no digits are left and the number is negative, a floating minus sign is displayed immediately to the left of the last digit. If a minus sign has already been displayed, a space is inserted. If the number is positive, a space is inserted.

+ If a digit remains in the number, display the digit. If no digits are left, display a floating sign (+ or –) to the left of the last digit. If one has already been displayed, display a space.

, If a digit remains in the number, display a comma in this position. If no digits remain, display a space.

This code is used for inserting commas to break up large numbers.

Note: If the II_DECIMAL environment variable is set to a comma, then a comma in the template displays a period. For more information, see Environment Variables for All Platforms (see page 619).

. Display the decimal point in this spot.

Note: If the II_DECIMAL environment variable is set to a comma, then a comma in the template displays a period. For more information, see Environment Variables for All Platforms (see page 619).

* If no digits remain, display an asterisk.

This code is useful for filling a number on the left with asterisks (for example, for checks).

space If a digit remains in the number, displays a blank space in this position.

Using this code is equivalent to specifying a backslash followed by a space.

CR (two characters)

If the number is negative, insert the characters CR (for credit). If the number is positive, display two blanks.

You can specify the characters in uppercase or lowercase (or one of each).

Numeric Templates


Code Description

DB (two characters)

If the number is negative, insert the characters DB (for debit). If the number is positive, display two blanks.

You can specify the characters in uppercase or lowercase (or one of each).

\c Any character, c, preceded by a backslash is printed in the position specified.

This code lets you insert characters such as hyphens and slashes into a template.

( ), [ ],{ }, < >

If the number is negative, displays it within the specified symbols.

Note: The floating symbols ($, +, and –) are displayed only once in the field. If a field is specified without “n” in the numeric positions and a value of zero is encountered, the field is blanked.

Examples of Numeric Templates

The following examples demonstrate the use of templates.

Note: A pound sign (#) indicates a blank space:

Data Type Format Example Data Output

integer zzzzzzzz 123 #####123

integer zZzZz.Zz 0 ########

integer zzzzzzzz.nn 0 ########.00

integer +++,+++,+++ 23456 ####+23,456

float ---,---,---.NN 23456.789 ####23,456.79

float ---,---,---.zz 3142.666 #####-3,142.67

money $$$,$$$,$$$.nnCr 235122.21 ###$235,122.21

money $$$,$$$,$$$.nnDb 235122.21 ###$235,122.21Db

money $zz,zzz,zzn.nn 1234.56 $#####1,234.56

money $**,***,***.nn 12345 $****12,345.00

money +$$,$$$,$$$.nn 54321 ###+54,321.00

integer nnn\nn\nnnn 023243567 023-24-3567

Date Format Templates


Input Masking and Numeric Templates

After you enter a numeric template, you can enable input masking for the field by setting the InputMasking property to TRUE. OpenROAD automatically validates your template. If you have entered a template that is inappropriate for a numeric field, it displays a message to that effect and does not let you exit the field until you enter a valid numeric template.

Enabling input masking affects how the field interacts with the end user when the application is running:

If input masking is not defined for a field

Means that the end user can enter data, and its data type is checked when the end user tries to leave the field

If input masking is enabled for the field

Means that each character as the end user enters it must meet the criteria specified by the template. If it does not, OpenROAD beeps and the end user must type another character.

Note: When input masking is enabled, the end user cannot enter a negative number unless the format template includes a negative indicator.


In OpenROAD, you can enter dates into entry fields as any combination of absolute and interval dates and times. Therefore, your format templates for date fields can also be composed of any such combination.

Define a Date Template

You can define a date template using the Property Inspector.

To define a date template

1. Open the frame or frame template in the Frame Editor and select the field for which you want to set a date template.



3. Select Date as the base data type.

4. Click OK.




6. Click the FormatString property, enter a date template in its entry field (for example, 2/ 3/07), and then press Enter.

For more information about and examples of specifying date templates, see Absolute Date and Time Format Templates (see page 644) and Time Interval Format Templates (see page 647).


For more information about how input masking affects the end user's interaction with the template, see Input Masking and Date Templates (see page 649).

Absolute Date and Time Format Templates

You can specify the absolute date and time template formats for entry fields with a date data type by entering an example date indicating exactly how you want each date and time element to be printed. You specify an absolute date and time template by entering the template in the field's FormatString property in the Property Inspector.

Notes:

If you specify an absolute date and time template by setting the FormatString attribute in your 4GL code, you must place double quotation marks (") around the example date. For more information about the FormatString attribute, see the Language Reference Guide.

Do not use the “d” and enclosing quotation marks.

The following representative date and time is the example value used when specifying the date format:

Sunday, 1901 February 3 at 4:05:06 p.m.

In this template:

Sunday represents the day of the week

1, 01, or 1901 represents the year

2 or 02 represents the month

3 or 03 represents the day of the month

4 or 04 represents the hour



5 or 05 represents the minute

6 or 06 represents the second

p or p.m. represents a.m. or p.m.

This example date is used because Sunday is the first day of the week, and arguments 1, 2, 3, 4, 5, and 6 are the year, month, day, hour, minute, and second, respectively.

When you specify a date or time format, you use the example elements to indicate both position and style as follows:

Day

Includes the example word Sunday in the date template to include the appropriate day of the week as part of the date when displaying dates in the field.

Month

Uses either a single or double digit for the month. Use a 2 (single digit) for the month to display the months of January through September as a single digit.

For example, July is displayed as 7 and November as 11. Use 02 for the month to display all the months as two-digit numbers. In this case, July appears as 07. Use the example month “February” to print the month name. In this case, July appears as “July.”

Year

Specifies the year in the same manner as the month. If you use the single digit 1 in the template to indicate the year, the years zero through nine are displayed with only one digit. The year 2004 appears as 4, while 2014 appears as 14.

Examples: Date and time formats

If you use the four digits 1901, all four digits of the year are displayed. For example, 2004 is displayed as 2004.

You can arrange the arguments in various combinations in any order. For example:

3/2/1 tells OpenROAD to display first the day (3), then the month (2), and then the year (1) with each element separated by slash marks.

The date January 15, 1988, appears as 15/1/88.

In the template Sunday 2/3/1, the date January 15, 1988, is displayed as Friday 1/15/88.



Note: Separators and other characters are reproduced in the field exactly as they are entered in the template. To use one of the special reserved template characters or symbols, precede it with a backslash. For example, to use the numeral 2 in the date template as a constant rather than the template symbol for month number, enter it as \2.

Guidelines for Using Absolute Date Templates

Observe the following guidelines when using absolute date templates:

On a date template you can enter only the month's name of February, the weekday of Sunday, and the time designation p or p.m.

You can specify 24-hour time by using 16 instead of 4 for 4 p.m.

You cannot use p or p.m. with 24-hour time.

Display the numeric day of the year by specifying the day and year, but leaving out the month.

For example, 3/1901 in the template results in dates like 121/1988 for April 30, 1988.

You can create ordinal numbers from numerals by appending the appropriate suffix (st, nd, rd, or th).

For example, the template 3rd day of February 1901 produces a date like 15th day of January, 1988.

Numbers requiring more than one digit use up preceding blanks or zeros.

If there are no preceding blanks or zeros remaining, the number expands to the right. A blank following a letter, word, or number is not used up by a succeeding number. Columns of numbers can be lined up by preceding them with an appropriate number of blanks or zeros.

Examples of Absolute Date Templates

The following table provides examples of absolute date and time templates:

Format Example Data Output

2/3/1 25-oct-1982 10/25/82

2/3/1 5-jun-1909 6/5/9

2/ 3/01 25-oct-1982 10/25/82

2/ 3/01 5-jun-1909 6/ 5/09

03-02-01 5-oct-1982 07:24:12 05-10-82

010203 5-oct-1982 821005

1\|2\|3 5-oct-1982 82|10|5




FEBRUARY, 1901 1-sep-2134 09:13:02 SEPTEMBER, 2134

FEBRUARY, 1901 2-apr-1962 17:46:03 APRIL, 1962

Sunday 5-oct-1983 Wednesday

SUN Feb 3 16:05 1901 13-oct-1983 07:24:03 THU Oct 13 07:24 1983

FEB 03 4:05:06 p.m. 12-dec-1983 22:13:03 DEC 12 10:13:03 p.m.

04:05:06 PM 5-oct-1983 14:08:45 02:08:45 PM

04:05:06 PM 5-oct-1983 07:29:12 07:29:12 AM

16:05 pst 5-oct-1983 14:08:45 14:08 pst

3/01 5-oct-1983 278/83

February 3rd 29-jul-1954 July 29th

3rd day of 1901 11-may-1999 131st day of 1999

Time Interval Format Templates

Time interval formats show the amount of elapsed time rather than an absolute date or time. Use interval templates for a date entry field that contains interval data.

As with the date format, you specify time interval formats by using a string to indicate exactly how you want a time interval to be printed. A representative interval has been selected to provide the example values you can use when specifying how you want the time to be printed. This example time interval is:

1 year 2 months 3 days 4 hours 5 minutes 6 seconds

You can arrange various combinations of the units of the time interval in any order.



Guidelines for Using Time Interval Templates

Observe the following guidelines when using interval templates:

There are 30.4375 days in a month and 365.25 days in a year.

The smallest unit specified is rounded up.

Numbers requiring more than one digit use up preceding blanks or zeros.

If there are no preceding blanks or zeros to the left, the number expands to the right. A blank following a letter, word, or number is not used up by a succeeding number. You can line up columns of numbers by preceding them with an appropriate number of blanks or zeros.

The word immediately following a number is made singular if the number is one, or plural if the number is zero or greater than one.

You can prevent this behavior by preceding the word with a backslash (\). Any character preceded by a backslash is printed as you enter it.

Examples of Time Interval Templates

The following table provides examples of time interval templates:


1 year 3 years 5 mos 16 days 3 years

2 MONTHS, 3 DAYS 3 years 5 mos 1 days 41 MONTHS, 1 DAY

3 3 years 5 mos 16 days 1263

1 yr 3 day 1 yr 5 mos 16 days 1 yr 168 days

4 hours 6 seconds 23 hrs 8 mins 53 secs 23 hours 533 seconds

04:05 \hours 23 hrs 0 mins 53 secs 23:01 hours

3 days 4 hours 23 hrs 8 mins 53 secs 0 days 23 hours

1 yr 2 mos 3 days 200 yrs 11 mos 28 days 200 yrs 11 mos 28 days

1 yr 2 mos 3 days 5 yrs 1 mos 3 days 5 yrs 1 mo 3 days



Input Masking and Date Templates

After you enter a date template, you can turn on input masking for the field by setting the InputMasking property to TRUE. OpenROAD then validates your template. If you have entered a template that is inappropriate for a date field or is not a date template that allows input masking, OpenROAD does not let you exit the field until you enter a valid date template.

Enabling input masking for a date field affects what date templates you can use and how the end user can interact with the field when the application is running.

When you want to use input masking on a date field, the template must meet the following requirements:

The template must be an absolute date or time format template.

The template cannot include an ordinal number (for example, 1st, 2nd, or 3rd).

Do not include the letters that create the ordinal number (st, nd, and so forth) in the template.

To specify the month, use 02, Feb, or Fe.

You cannot use the full name of the month.

To specify the day, use 03, Sun, or Su.

You cannot use the full name of the day.

The template cannot include the alignment format item (|).

There must be adequate room for all the digits required by the format.

The input masking feature requires the end user to enter a specified character in a specified position. Consequently, each format must include specifications for all required positions.

For example, assume that you specify a format representing the month/day/year that looks like this (with no leading blanks or zeros in front of the digits):

2/3/1

If you enable input masking, this format is unacceptable because all the entries can be at least two digits (00/00/00 or 00/00/0000) and the preceding format only allows for the one digit in each part. To specify a format compatible with input masking, use either of the following formats:

2/ 3/ 1

(blanks preceding the digits) for a blank-filled date on output

“02/03/01”

for a zero-filled date on output.

Varchar Templates


When end users enter data in a date field that has input masking enabled, OpenROAD accepts only numbers in the numeric portions of the template and alphabetic characters in the non-numeric portions (month and day names).

Varchar Templates

Templates for varchar entry fields consist of special characters that indicate what characters the end user can enter at the corresponding position in the text string. In defining your varchar template, you can use any combination of special characters that are predefined by OpenROAD or that you have defined yourself.

Note: You can only define templates for single-line varchar entry fields. Multiline varchar entry fields do not use templates.

Define a Varchar Template

You can define a varchar template using the Property Inspector.

To define a varchar template

1. Open the frame or frame template in the Frame Editor and select the field for whicy you want to set a varchar template.



3. (Optional) Accept the default Varchar base data type, but change the value of its corresponding Length property.


Varchar Templates


5. Click the FormatString property, enter a varchar template in its entry field, and then press Enter.

For example, if you enter aaazz, as shown here, the end user must enter three alphabetic characters in the first three places and numeric characters in the last two places:

For more information about specifying varchar templates, see How You Can Create a Custom Varchar Template (see page 651). Also, see Examples of Varchar Templates (see page 658) for sample varchar templates.


How You Can Create a Custom Varchar Template

In addition to the sample varchar templates that OpenROAD provides, you can design your own templates. For example, you might want a template that limits entry in a particular position to one of three characters.

To create a custom varchar template, you can use any combination of the predefined special characters, user-defined special characters, and customized character sets. OpenROAD lets you define up to 12 different custom character sets in a single template.

After a custom character set is defined in a template, you can use it any number of times in the template. Combining custom character sets, constant characters, and the special characters gives you full flexibility in creating a template that suits your needs.

Varchar Templates


Using Special Characters

OpenROAD provides a number of special characters that you can use in a custom varchar template. Each special character represents a set of characters from which the end user can choose to enter at the specified position.

In our previous example, the special characters “a” and “z” represent alphabetic characters and digits, respectively. Therefore, using the aaazz template, end users can make entries such as “Afm35” or “pRt44” but not entries such as “2acm5” or “C342d.” They must enter alphabetic characters in the first three places and numeric characters in the last two places.

The following table describes the special characters that you can use in a varchar template:

Character Description

a Any alphabetic character

h Any hexadecimal digit

n Any digit (the default is 0)

o Any printable 7-bit character

p Any printable character

q Any character that can be the first character in an OpenROAD name

r Any character that can be the second or subsequent character in an OpenROAD name

s Any 7-bit character

t Any character

x Alphabetic and numeric characters

z Digits (the default is a space)

i, j, k, l, m User-defined characters. For more information about defining these special characters, see How You Can Define a Special Character for a Character Set (see page 654).

You can use templates to perform the following tasks:

Enforce mandatory entry (the end user must make an entry).

All of the special characters support mandatory entry.

For information about using mandatory entry, see How You Can Force Mandatory Entry (see page 657).

Force the case of an entry.

Varchar Templates


Insert a default entry if the end user fails to make an entry.

If you want to force the case of an end user's entry or insert a default entry if the end user makes no entry, you must use a user-defined special character.

Note: The predefined special characters do not support forced case or default entries.

The Escape Character

In addition to the special characters, a template can also include constant (or literal) characters. To specify that a character be read as a literal in a template, precede the character with the backslash escape character (\).

How You Can Define a Character Set

You can limit an end user's entries to some set of characters that are broader or more narrow than those available using the predefined special characters. To accommodate these needs, OpenROAD lets you define a custom character set. If the set you want is small (for example, one or two characters), use the following syntax:

[c{c}]

where c represents the valid character or characters. You can include any number of valid characters. Simply use this syntax in the template in the positions where you want the specified characters. You must include the square brackets.

For example, the following template lets the end user enter only the letters “a,” “b,” or “c” in the first position:

[abc]nnn

If you want to specify a range of characters, use the following syntax:

[c-c2]

where c represents the beginning character in the range and c2 represents the ending character, for example [a-g].

For either syntax, OpenROAD forces the end user to enter one of the specified characters in the specified position.

Varchar Templates


In either syntax, the case of the characters is unimportant for alphabetic characters. You can use an uppercase or lowercase character to represent the character. To force the end user's entry to either case, use the special formatting character that specifies forced case. (For more information about forcing case, see How You Can Specify Uppercase or Lowercase (see page 656).)

When you define a character set for a single position this way, you cannot enforce mandatory entry in that position. To enforce mandatory entry, define the character set with a user-defined special character.

If you are defining a large character set or are using the set in several places in your custom template, define a special character to represent the set and use that character in the template. For information about defining special characters, see How You Can Define a Special Character for a Character Set (see page 654).

How You Can Define a Special Character for a Character Set

In addition to the predefined special characters for varchar templates, OpenROAD provides five special characters (“i,” “j,” “k,” “l,” and “m”) whose meaning you can define by associating one of the user-defined special characters with a custom character set. This feature makes it easy to define a custom character set and specify that set in several positions in your custom template.

To use a user-defined special character, define the special character at the first instance of its use in the template and then put the special character in the template for subsequent occurrences.

In the same way that OpenROAD defines each of its predefined characters to represent some set of characters, you can define each of these special characters to represent some set of one or more characters. To do so, use the following syntax:

[c=c1{c2}]

where c is one of the five special characters and c1 and c2 represent the characters that you want to include in the set of characters defined for the special character. You can include any number of characters in the set.

You can also specify a range of characters for your special character. For example:

[c=c1-c2]

In this case, c represents the special character, c1 represents the beginning of the range, and c2 represents its end.

Varchar Templates


When you include a user-defined special character in a template, the first instance of the character in the template must be its definition. For subsequent occurrences, you just use the special character. In the following template example, the special character “j” represents the numbers “4” and “6”:

[j=46]aazaj

This template describes a field of six characters, of which the first and last must be either a 4 or a 6.

Special Characters in User-defined Character Sets

OpenROAD provides a set of predefined special characters that you can use in the definition of a custom character set. These characters can appear only in a character set definition. You cannot place them directly in a template definition.

These special characters are useful because you can force the case or apply a default to any of the characters represented by these built-in special characters. (The predefined special characters—described in Using Special Characters (see page 652)—do not allow you to apply forced case or a default to any of the characters that they represent.)

The following table lists the predefined special characters that you can use in a custom character set definition:

Character Represents

# Any digit

@ Any alphabetic character

* Any printable character

+ Any printable character (only 7 bits)

& Any character that can be the first character in a name

% The second and subsequent characters in a name

: Any hexadecimal digit

Use these characters to force the case of an entry or to provide a default for the entry. For example, the following template specifies a four-letter entry:

aaaa

If you want the first position to be an uppercase letter, you cannot force case on the special character “a.” Instead, you must use the special character “@”:

[@/u]aaa

Varchar Templates


To include any of these special characters literally in the template, use the escape character with the character. For example, the following template lets the end user enter a two-figure percentage value:

nn\%

How You Can Specify a Default Character

To specify a default character for a position, include the following syntax in your character set definition:

//c

where c is the default character.

For example, assume that you want end users to enter a 4-digit number. Users must enter at least two numbers, but if they fail to enter the final two numbers, the numeral “1” should appear in those positions. The following template achieves this behavior:

nn[#//1][#//1]

The "n" forces entry of a digit in those positions. The other two positions allow entry of a digit, but insert the specified default if the end user does not make an entry.

When you specify a default character for a position, OpenROAD inserts the default character whenever the end user inserts a space in that position or fails to make an entry in that position. The only exception occurs when the space is a valid entry for that position. In such instances, OpenROAD places the space in the position. If a space is not a valid entry, then OpenROAD places the default character in the position.

OpenROAD always considers the specified default character a valid character for the position even if it is not part of the character set defined for that position by the template.

How You Can Specify Uppercase or Lowercase

To force the case of the end user's entry, use the following values in the special character definition.

For uppercase

/U or /u

For lowercase

/L or /l

Varchar Templates


You can include only one case specification in each special character definition. For example, to have the end user enter a part number that consists of an uppercase letter from A–D, followed by three numbers, you could use the following template:

[a-d/U]nnn

The end user can make entries in lowercase or uppercase, but the data will appear in the field in uppercase.

How You Can Force Mandatory Entry

Mandatory entry means that the end user cannot exit the field without providing a valid entry. To specify mandatory entry, use an uppercase special character. For example, to have the end user enter a part number with a two-letter code followed by two numbers and one final letter, you could use the following template to force mandatory entry of the first two letters are mandatory:

AAnna

Examples of User-defined Character Sets

The following table provides examples of user-defined character sets:

Example Description

[\#-\*] All of the characters found between “#” and “*” in the ASCII collating sequence

[A0\[\]/u] The letter “a,” forced to uppercase, the digit “0” and square brackets

[#abc] Any character acceptable in your installation as a digit and the letters “a,” “b,” and “c”

[&\*\$] Any character acceptable in your system as the first character in a name and the characters “*” and “$”

[abc//a] The characters “a,” “b,” and “c”; the default is “a” if the end user fails to make an entry or enters a space.

Varchar Templates


Examples of Varchar Templates

The following table shows some examples of varchar templates:

Example Description

nnn\-nn\-nnnn This template, with embedded dashes, lets the end user enter 9 digits, for example, for a Social Security number.

AA\-nnnn This template specifies two mandatory alphabetic characters and four digits, a dash separating the alphabetic and numeric characters.

nn\% This template specifies two digits and places a percent sign following the digits.

[e/u][x/u]nnnn \-[#//0][#//0]

This templates specifies that the end user enter an “e” and “x” in the first and second positions, respectively, followed by four digits and then two more digits. The template forces uppercase on the first two positions, inserts zeros by default in the last two positions if the end user makes no entries in those positions, and puts a dash before the final two positions.

N\='[ja-m/l]jjj\'

This template specifies a five-character entry. The first position is a digit and is a mandatory entry. The final four positions can be any character between “a” and “m,” inclusive. The final four positions are set off by single quotation marks and are forced to lowercase.

Glossary 659

Glossary 3GL procedure

A 3GL procedure is a set of 3GL statements that you can call by name in an application. 3GL procedures let you access code written in third-generation languages, such as C or C++.

4GL procedure

A 4GL procedure is a set of 4GL statements that you can call by name in an application. 4GL procedures are written in fourth-generation languages such as Java.

ABF

ABF is an abbreviation for Application-By-Forms.

about_box frame template

The about_box frame template is an OpenROAD core library template that creates a standard dialog containing basic information about the current application. It includes the application's name and version number, the name of the current database, current version information for OpenROAD, and an image trim field that you can customize with your company's logo.

active frame

An active frame is a frame that has the input focus and that end users can work in. Users can click the mouse in the frame, select menu or button operations, or enter data. They can also reposition the frame on the screen.

analog_clock field template

The analog_clock field template displays the time of day using a standard analog clock face (with hour and minute hands) and supports optional alarms that users can set.

AppFlags

AppFlags provide support to automatically load, version, and save an XML project file and to build the CAB file and HTML page for a web application.

application image

An application image is a version of an application that is stored in an operating system file outside of the database.


associate table

An associate table can be joined to a primary table to provide additional data. The columns from each table can be included as fields in the frame.

bar field

A bar field is a form field that appears as a rectangle that represents a numeric value. The bar is displayed against a background, and the bar size compared to the background size illustrates the proportional value of the field.

bar_graph field template

The bar_graph field template displays the data from one to three data sets in a common bar graph format.

borders

Borders are rectangular boxes around fields. By specifying part of a border, you can outline part of a field, such as its top or bottom.

bounding rectangle

A bounding rectangle is the rectangular outer boundary of a field. For non-rectangular fields such as ellipses and line segments, the bounding rectangle is the smallest rectangle that can contain the field.

box trim

Box trim is a field type that appears as text within a rectangular boundary on a a form.

break column

A break column is a column that defines a page break.

build command

A build command is a saved settings profile for use with an OpenROAD utility (for example, MakeImage).

build script

A build script is an ordered collection of build commands.

button field

A button field is represented as a rectangle that the user clicks to initiate an operation. Such buttons are commonly called push buttons or command buttons.

Glossary 661

calculated expression field

A calculated expression field uses functions and arithmetic operators to compute a value.

calculator frame template

The calculator frame template is a core library template that creates a complete, four-function calculator in a pop-up frame.

calculator_control field template

The calculator_control field template creates a complete four-function calculator in a user frame. In addition to chained arithmetic calculations, the calculator includes memory storage and recall, square, square root, and inverse features.

calendar field template

The calendar field template creates a calendar that lets the user select the day, month, and year.

called frame, calling frame

When one of these statements or a procedure appears in a frame script, the frame that contains the statement is referred to as the calling frame, and the frame to which control is passed is the called frame.

character formatting

Character formatting determines how report text—including letters, numbers, punctuation, and symbols—appears on the screen and in print.

child field

A field contained within a composite field is referred to as a child field.

class

A class is a named object definition.

Class Browser



column of a selected table field

A Column of a Selected Table type of field is one whose value is determined by the main query when the report is run. It references one of the columns selected from one of the tables specified in the FROM clause of the query.

composite field

A composite field is a field that may contain other fields. Most composite fields can contain fields of any type, even other composite fields.

control button

A control button is a control that appears on a form as a button that users can click to display a menu of commands or call a dialog.

control frame

The control frame application type displays a single frame that provides access to other frames and lets the user quit the application.

countdown_timer field template

The countdown_timer field template creates a countdown timer that displays a timer that counts down from a specified amount of time since the frame was opened and updates at a specified time interval.

current bias

A field's current bias is the bias setting for a frame's current mode. The bias setting for a mode determines how the user interacts with the field when the frame is in that mode.

database connection profile

A database connection profile is a collection of settings used to establish a connection with a local or remote database.

database event

Database events provide communication between two applications that are connected to the same database.

Database Procedures

A database procedure is a set of SQL statements that you can call by name in an application. Database procedures let you call data-oriented procedures that are stored and executed within the database server.

Glossary 663

data-driven application

A data-driven application lets you provide different operational choices to different users from a single frame that can be used throughout several applications. The choices that appear on the menu are stored in a database table or a runtime array and are displayed selectively at runtime based on such information as the end user's login or group ID.

date_field field template

The date_field field template is used to create an entry field of the type date.

detail frame template

The detail frame template is used to generate a frame that binds a database query that exists with a one-to-many master-detail entity relationship with the detail table field associated with calling frames generated from the table_field, master_detail, or detail frame templates.

digital_clock field template

The digital_clock field template creates a digital clock that displays the time of day and supports optional alarms the user can set.

duplicate spacing

Duplicate spacing refers to the relative position where a duplicate field will be created and place in relation to the original field.

eClient

The eClient is a digitally signed, self-contained control that contains a packaged version of OpenROAD runtime. When the eClient is placed on a web server and referenced using OBJECT tags on an HTML web page, a client machine running Internet Explorer can automatically download and install the runtime, and run user applications.

edit_control field template

The edit_control field template generates a self-contained text editor with support for File and Edit operations. It is used by the text_editor frame template and can also be included as a component of other frames.

elapsed_timer field template

The elapsed_timer field template provides an elapsed timer that displays elapsed time in digital (hh:mm) format.


ellipse

An ellipse is a round or oval shape that can be either empty or filled.

encapsulation

The process of allowing only the object itself to have access to its attributes and methods is called encapsulation.

event blocks

Event blocks are blocks of 4GL code that OpenROAD executes when the user or the program initiates a specified action or event.

explosion frame template

The explosion frame template is used to generate a frame that displays in greater detail a single row from the table field of a frame generated from the table_field, master_detail, or detail frame templates.

external class

An external class defines the class properties, methods, and events for one or more external objects.

external object

External objects are external controls such as charts, grid controls, HTML controls, and web browsers from independent software vendors.

field script


field templates

Field templates are prototypes from which you can generate individual fields on a form.

Field Tree

The OpenROAD Field Tree lets you view all of the fields defined to a frame and provides you with an alternative method of locating and selecting a field on the frame currently being edited.

Glossary 665

financial_calculator frame template

The financial_calculator frame template is a finance library template that can be used to include a prepackaged calculator frame in your application. This calculator supports a variety of loan and investment calculations, including present value, future value, interest rate, duration, payment, and amortization.

find_dialog frame template

The find_dialog frame template is a core library template that provides a standard dialog for searching and optionally replacing text in a specified entry field on a form. It can be configured as either a Find or a Replace dialog.

flexible form

A flexible form appears as a group of fields that are contained by a flexible boundary. When you move an individual field in the group, the boundary stretches accordingly.

float_field field template

The float_field field template is used to create an entry field of the type float.

floating menu bar

The floating menu bar is the free-standing menu bar of the Frame Editor.

font_dialog frame template

The font_dialog frame template is a core library template that provides a standard interface for changing the font settings of field text at runtime. In addition to including controls for selecting the font typeface, size, and style, the dialog contains a sample display so that users can preview their changes before applying them.

form

A form is a two-foot by two-foot “canvas” that lies beneath a frame's window. It is the portion of the frame where the user displays or modifies data, views illustrations, reads instructions, and selects options.

format template

A format template is a picture of how the data in a field should look, and specifies what type of data the end user can enter.


foundational application

Foundational applications are typically the OpenROAD image files that are part of the included application list of the OpenROAD image file contained in a 4GL Control application.

frame

A frame is a window that consists of a form, with or without a menu, used to display and input data.

Frame Editor

The Frame Editor is the primary editor in the OpenROAD development environment for creating, viewing, and modifying frames.

frame template

A frame template is a frame that you use as a model for creating similar frames.

free trim

Free trim is a field type that appears as text without a boundary on a form.

gauge field template

The gauge field template is used to create a thermometer-style bar gauge that can be used to monitor progress, resource levels, or other numeric data in your application.

ghost frame

Ghost frames are used to manage and coordinate applications without user interaction. Ghost frames differ from other OpenROAD user frames in that they do not contain forms (thus making them invisible to the user).

global constant

A global constant is a value to which you give a name. You can then use this name to represent the value any place in an application.

global procedure

A global procedure is a procedure that can be shared among frames, applications, and procedures.

Glossary 667

global variable

A global variable is a variable that you can use in any script or procedure in an application. It contains data that any script or procedure in the application can access.

image field

An image field is a field that displays a picture on a form.

image file

An image file is a compiled, executable version of an OpenROAD application. File names end with the extension .img.

image trim

Image trim is a field type that appears as a picture on a form.

inactive frame

An inactive frame is one in which the end user cannot execute an operation.

include script

An include script is a segment of 4GL code that you can include in any script or procedure in an application.

included application

An included application is an application that is embedded in another application.

initialize block

An initialize block is an optional portion of a script used to declare parameters, local variables, and procedures.

input masking

Input masking ensures that end users always enter a valid character in a field that has a format specified. If the end user enters a character that is invalid for the field's format, the machine beeps and the end user cannot leave the position or field until a correct entry is made.

integer_field field template

The integer_field field template is used to create an entry field of the type integer.


keyboard map file

A keyboard map file contains an alternative mapping of logical names to physical keyboard keys that may be more appropriate for your needs than the default mapping.

line segment

A line segment is a shape field that appears as a single line that you draw between two points on a form.

line_graph field template

The line_graph field template creates a line graph that displays data from one to three data sets in a standard line graph format.

list field

A list field displays a series of options from which the user can make one or multiple selections depending on its SelectionType property.

list view field

A list view field lets the end user view and optionally manipulate or edit a list of items.

local procedure

A local procedure is a procedure that lets you modularize code for a single frame, field, or procedure.

lookup table

Lookup tables are bound to a specific column in a primary table and are used to provide a list of possible values for those columns. Lookup tables are also used during user input as a validation mechanism.

macro variable

A macro variable is a preprocessor variable whose value is specified when the application is processed by the OpenROAD preprocessor.

master-detail template

Like the simple_field and table_field frame templates, the master_detail frame template creates a database table browser. However, master-detail frames perform two queries that exist in a one-to-many master-detail entity relationship.

Glossary 669

matrix field

A matrix field appears as a rectangle that contains fields arranged in rows and columns. The component fields stay aligned even if you rearrange or reorder them. The matrix field can include any combination of fields.

mclient_frame template

The mclient_frame template is a core library template for use with mClient.

menu bar

A menu bar contains a set of pull-down menus available on the frame.

menu button

A menu button is a menu item that displays a word or phrase that the user can click to initiate an operation.

menu field script

You can provide 4GL code for a menu item—called a menu field script—to specify the operation that is performed when a user selects the menu item.

menu frame

A menu frame is an otherwise empty frame except that it contains a menu bar.

menu item

Menu items each provide an operation (or command) by which the user communicates with the frame. Menu items are also called menu buttons.

menu script


menu separator

A menu separator is a line divider that separates the individual components of a menu into groups. Menu separators are used for display purposes only.

menu toggle

A menu toggle displays an option that the user can enable (turn on) or disable (turn off). Each time the user clicks the toggle, the status of the option switches.


meter field template

The meter field template is used to create a semicircular meter that resembles an automobile speedometer. A meter field can be used to monitor resource levels or other numeric data in your application.

money_field field template

The money_field field template is used to create an entry field of the type money.

multiline entry field

Like a single-line entry field, a multiline entry field displays data. However, at the end of each line of a multiline entry field, OpenROAD automatically wraps the text to fill in the field.

multiple use frame

The multiple use frame structure uses a single frame to step the user through related tasks. Wizards are examples of multiple use frames.

numeric template

Numeric templates consist of one or more special characters. Each of the special characters represents what data can be entered at that position in the number.

object

An object in object-oriented programming (OOP) is a data structure that holds values that you can manipulate. Each OpenROAD component—such as a frame, form, or menu item—is an object.

option field

An option field appears as a drop-down list of values from which the end user can make one selection. Only the current value is displayed.

page step

A page step is the distance the bar is scrolled each time the user clicks the arrow at either end of a scroll bar.

palette field

A palette field appears as a group of buttons, each displaying an image and representing an option to the user (similar to the field palette in the Frame Editor). The user selects an option by clicking one of the images.

Glossary 671

pop-up button

A pop-up button is a button control that has an option menu associated with it.

pop-up frame

Pop-up frames are frames that remain on top of the calling frame as long as the pop-up is active.

procedure

A procedure is a set of statements that you can call by name from a script. You can write procedures in 4GL, and you can call existing 3GL and database procedures.

property filters

The Property Inspector features property filters that restrict the display of properties to certain types. For example, you may want to use a property filter to limit the list of available properties to those concerning only the frame's appearance.

pull-down menu

Pull-down menus consist of a menu button that, when selected, displays a submenu of items. These items can be of any menu type, including another pull-down or slide-off menu.

query_bar field template

The query_bar field template provides a standard toolbar for automatically browsing and filtering the results of a QueryObject retrieval.

radio field

A radio field appears as a group of buttons, each of which represents an option for users of the application. When the user clicks a radio button, the selected option is turned on and all other options are turned off.

read/write application

A more complex type of control frame application, the read/write application provides concurrent frames that let end users enter data in some frames and select data in other frames.

read-only application

A read-only application is one that opens several concurrent read-only frames from the control frame. This lets end users have several concurrent frames for display purposes.


rectangle

A rectangle is a four-sided background shape that can be empty or filled.

registration

Registration means that OpenROAD wrapper code has been generated for an external object's exported attributes, methods, and events.

report section

A report section is the basic unit of layout in a report. Sections can contain fields, text, and graphics.

root application

A root application is the application that includes other applications.

root item

A root item is a top-level item in a hierarchical tree structure that has no parent.

RWConv utility

The RWConv utility lets you convert existing Report-Writer reports from the system catalog into OpenROAD 4GL procedures that can be run using the Reporter API.

scalar field

A scalar field is a field that lets the application accept data from users or display data to users.

schema

A schema is a named collection of tables in a database.

sequential frames

Sequential frames force the user to follow a set of sequential steps by closing the control frame as the detail frame opens. A separate frame is used for each individual section of the task.

shape field

A shape field is a graphic element, a geometric figure, that provides a background for other fields on a form. Users cannot interact with shape fields.

Glossary 673

simple field

A simple field is an individual field that is not a composite field.

simple_field frame template

The simple_field frame template creates a standard database table browser. The generated frame consists of a matrix of entry fields, which are automatically loaded with the results of a single query against one or more joined tables.

single-line entry field

A single-line entry field provides one line on which you can either display information for the end user or let the user enter (or modify) information.

singleton select query

A singleton select query is one for which only one row may be returned. If the query returns more than one row, a runtime error will result.

slide-off menu

Slide-off menus consist of a menu button that, when selected, displays a submenu of items. These items can be of any menu type, including another pull-down or slide-off menu.

slider

A slider consists of a slider bar and a drag box. The user selects an integer value by dragging the box into position on the bar.

smallint_field field template

The smallint_field field template is used to create an entry field of the type smallint.

sort columns

Sort columns can be table columns or calculated fields created in the document. Sort columns determine the ordering of data in a report.

spin_control field template

The spin_control field template is used to create a control consisting of an entry field and up and down buttons that increment or decrement the value displayed in the field. A spin control can contain integer, float, money, date, or varchar data.


splash_screen frame template

The splash_screen frame template is a core library template that provides a start-up window, which appears briefly when your application starts up to identify the application name and version number.

stack field

A stack field appears as a set of fields that remain aligned if you rearrange or reorder them. The stack can include any combination of fields.

step marker

Step markers are above and below the scroll bar elevator, often at the top and bottom of the scroll bar. For example, a value of 10 moves the elevator 10 units in the appropriate direction.

stop_watch field template

The stop_watch field template creates a stopwatch that shows the length of time since the timer's activation. The timer is updated at predetermined intervals.

style sheet

A style sheet defines the appearance of each type of field that can appear on any frame using that template. A style sheet lets you specify certain style attributes for each type of field that you can create for that frame or frame template.

subform

A subform appears as a group of fields that are contained by a fixed boundary on a form. You determine the boundary size when you create the subform. The fields within the subform can be of any type.

system classes

System classes are object definitions that OpenROAD provides. By using OpenROAD system classes and their associated attributes and methods, you can manipulate OpenROAD application components from your scripts and procedures.

tab folder

A tab folder field is used to present data or a series of choices in a multiple-page format. By default, it consists of three blank tab pages that resemble file folders. When the end user clicks one of the tabs on the tab bar, the corresponding page moves to the foreground and enables access to its data and fields.

Glossary 675

tabbed_dialog field template

The tabbed_dialog field template is used to provide the overall layout and page-switching functionality of a tabbed dialog and can be used as a starting point for developing a multi-paged dialog.

table field

A table field appears as active fields arranged in rows and columns. Each column is a stack of identical active fields. Each row consists of one active field from each column in the table field.

table_field template

Like the simple_field frame template, the table_field frame template creates a standard database table browser. The generated frame consists of a table field, which is automatically loaded with the results of a single query against one or more joined tables. Each table field column maps by name and type to one of the result columns of the query.

text display

Text display refers to the placement of text (or database fields containing text) that is too large to be displayed on a single line within the column or page margins of a report. Reporter either wraps the text (continuing it on the next line), or truncates it at the column or page margin.

Text Mode

Text Mode is the mode in which you can enter text in a box trim field. A blinking cursor indicates where to start entering text.

text_editor frame template

The text_editor frame template is a core library template that provides a prepackaged text file editor, with a toolbar and standard menus for file, edit, find/replace, and format operations.

timezone_control field template

The timezone_control field template creates a time zone field that displays a list of time zones.

toggle (check box)

A toggle appears as an option that the user can click on or off (enable or disable).


toolbar

A toolbar consists of a set of iconized items from which the user makes a selection by clicking the mouse pointer on it. Toolbar items typically consist of buttons that provide shortcuts for frequently used menu commands or for easy access to other features or frames.

toolbar_window template

The toolbar_window template is a misc library template that creates a standard dialog containing a basic toolbar in a stack field and a File menu with a Close command.

tree view field

A tree view field presents the end user with a hierarchical list of items in a tree structure that can be expanded or collapsed.

trim field

Trim fields are text elements or images and include free trim, box trim, and image trim fields. Trim fields consist of a foreground and a background. The foreground is the content of the trim (the image or the text) and the background is the area that surrounds it.

user class

A user class is a set of developer-defined attributes (characteristics) and methods (behaviors) that you can use to refer to multiple data items as a single entity.

user class script

A user class script contains the 4GL code for the methods of a user class. This script defines the behavior of your user class. The user class script contains the source code for all the methods of that user class.

user event

User events provide a simple, effective way for actions in one frame to trigger actions in another frame.

user frame

A user frame consists of a form that you design, a script whose code you write, and, sometimes, a menu that you create.

Glossary 677

viewport

A viewport provides a window on the form for viewing a larger field. The end user uses the viewport's scroll bars to view undisplayed portions of the field in the viewport.

vnode

A vnode is a virtual node, which provides all connection data to connect to an Ingres installation on a remote system.

widget

A widget is a toolkit control often associated with a field.

Index 679

Index

3

3GL procedures 3GL Procedure Editor • 461, 585 components • 93 creating • 462 described • 27 editing • 464 registering • 29, 461 sample application • 467 scope • 29 setting properties • 463 viewing • 464

4

4GL procedures 4GL Procedure Editor • 456, 459, 461

compilation error messages • 147 compiling • 459 components • 93 creating • 456 deleting • 460, 464, 467 editing • 459 frame scripts • 23 local • 461 scope • 29 setting properties • 458 starting applications • 32 testing • 456 types • 27 using • 26 viewing • 459

4GL statements • 25

A

About dialog box creating • 285 customizing • 287

Active fields described • 151 events • 255

Active frames • 32 ActiveX controls • 35, 279, 413, 590

Aggregate functions defined • 503 using in queries • 311 using in reports • 503

Alignment fields in reports • 525 palette • 525 text in reports • 525

Alphanumeric identifiers application properties • 82 in property descriptions • 240 in user class attributes • 418 in user class methods • 423 rules governing • 24

AppFlags • 577, 582, 583, 659 Application Browser

displaying application versions • 73 displaying component versions • 76 refreshing the display • 73, 76

Applications 4GL procedures • 32 accessing data • 82 callframe statement • 33 CompileApp utility • 566 compiling • 565, 566 components • 21

developing • 90 concurrency style • 32 concurrent frames • 35 control frames • 33 copying • 551 creating • 81 creating versions • 538 customizing • 84 customizing a session • 85 data-driven • 34 deleting • 102 deploying • 537 detail frames • 33 displaying versions • 73 editing • 96 generating a report • 555 gotoframe statement • 33 icons • 82, 114


images creating • 569 MakeImage utility • 569 reporting • 559

importing and exporting • 546 include scripts • 87 included applications • 87, 89 management • 537

field templates • 39 frame templates • 38 style sheets • 38 using utilities • 537

multiple developers • 96 multiple-use frames • 31, 34 non-interactive • 39 openframe statement • 34 printing a report • 556 properties

DBMS Connect Flags • 82 modifying • 84 setting • 81

read/write with concurrent frames • 34 read-only • 34 renaming • 101 reports

databases • 556 images • 559

RunDBApp utility • 577 RunImage utility • 580 running • 577, 580

multiple applications • 104 single applications • 103

runtime parameters • 87 sequenced frames • 33 sequential frames • 31 starting a development session • 61 starting frame • 32 structuring • 21 types

database sessions • 35 data-driven • 34 detail frame • 33 read/writeframe • 34 read-only • 34

versions VersionApp utility • 539

Videos • 31, 33 working copies of components • 96

ApplyTemplate utility applying template changes • 561 parameters • 564

Assigning speed keys • 396 Assistants

About Box • 285 Analog Clock Assistant • 343 Calculator Assistant • 288, 351 Calendar Assistant • 351 Countdown Timer Assistant • 353 Digital Clock Assistant • 355 Elapsed Timer Assistant • 357 Financial Calculator • 302 Find/Replace Dialog • 291 Font Dialog • 295 Frame • 305, 317, 321, 325, 329 Gauge Assistant • 359 Graph Assistant • 346, 362 Meter Assistant • 363 Spin Control Assistant • 367 Splash Screen Assistant • 298 Stop Watch Assistant • 370 Text Editor • 299

Attributes creating for user classes • 415 editing • 420, 425 setting properties • 418

Audience for guide • 18 Automatically generated fields

predefined field templates • 341

B

Background colors • 126 forms • 124

Bar fields creating • 177 described • 177 properties • 178

Biases field • 257 menu items • 395

Borders adding to reports • 526

Box trim creating • 171 properties • 172

Bring to Front operation fields • 160

Index 681

Build tab • 55 Button fields

creating • 179 properties • 179 using with Alt speed keys • 262

C

Calculator creating • 288, 302 how it works • 289 template • 287

Calculator frames creating • 287 customizing • 289

Calling frames • 33 Script Editor • 439

Changing field appearance at runtime • 123 frame modes • 123 global constants at runtime • 30

Child frames communicating with parent frame • 33 described • 33 tracking • 34

Choice fields, converting • 167 Class Browser

accessing • 432 overview • 432 using • 432

Classes external classes • 413 inheritance hierarchy • 411 subclasses • 411 superclasses • 411 system classes • 411 user classes • 412

Code, modularizing • 27 Color tables • 629 Colors

changing in reports • 529 changing in Workbench • 164, 165 fields • 164 palettes • 126

Columns prototype cells • 230 specifying sort order • 492

Command line handling long commands • 586

Commands include from a file • 586 start Workbench • 63 w4gldev backupapp in • 548 w4gldev backupapp out • 554 w4gldev compileapp • 568 w4gldev destroyapp • 542 w4gldev documentapp • 558 w4gldev makeimage • 571 w4gldev purgeapp • 545 w4gldev queryimage • 560 w4gldev rundbapp • 577 w4gldev runimage • 582 w4gldev versionapp • 539 w4glrun runimage • 582

Committing database transactions • 35 Compilation Errors window • 147 CompileApp utility • 566 Compiling

4GL procedures • 459 applications • 565 CompileApp utility • 566 frames • 146, 147

complib.cab eClient library file • 588, 607 complib.rel eClient library history file • 592 Component relationships, displaying • 78 Components

3GL procedures • 93 4GL procedures • 93 cross referencing • 78 current version • 96 database procedures • 93 deleting • 102 developing • 90 displaying relationships • 78 displaying versions • 76 editing • 96 field templates • 95 frame templates • 95 generating a report • 555 ghost frames • 92 global constants • 94 global variables • 94 include scripts • 94 printing a report • 556 private version • 96 private versions • 538 purging • 545 saving • 98 user classes • 92


user frames • 91 working copies • 96

Composite fields converting • 167 creating • 153, 215, 231 deleting • 163 described • 151, 153, 215 scope of variables • 29 selecting • 158

Concurrency application types • 32 read/write applications • 34 read-only applications • 34 transaction management • 35

Concurrent frames managing database transactions • 35 read only • 34 read/write applications • 34

Connect tab • 47 Consistency, managing applications • 38 Constants

Constant Editor • 30 creating • 30 editing or viewing • 455 scope • 29

Control buttons editing option menus • 182

Control frames, selecting a style • 33 Converting

choice fields • 167 composite fields • 167 fields • 167

Copying applications • 551 fields • 162 scripts • 439

Core default included application • 88 frame templates • 284

Creating 3GL procedures • 462 4GL procedures • 456 About boxes • 285 application images • 569 application versions • 538 applications • 81 bar fields • 177 box trim • 171 button fields • 179 calculators • 288, 302

composite fields • 153, 215, 231 database procedures • 462 database table browsers • 317, 321, 325 detail frames • 329 dialogs • 107, 108 ellipse shapes • 169 explosion frames • 331 field scripts • 270 field templates • 271, 273 fields

from a database table • 275 from an external class • 279 from field templates • 271 from user classes • 277

Find dialogs • 290 flexible forms • 216 Font dialogs • 295 forms • 108 frame templates • 142 frames • 105, 107, 108 frames from frame templates • 142, 144 frames from predefined templates • 281 global constants • 30, 454 global variables • 449 image fields • 180 image files • 569 image trim • 175 libraries • 575 list fields • 186 macro variables • 451 matrix fields • 217 menu separators • 393 menus • 42, 383 multiline entry fields • 194 multiple fields • 156 option fields • 198 palette fields • 200 radio fields • 201 Replace dialogs • 290 scalar fields • 170 scroll bars • 203 shape fields • 167 single-line entry fields • 189 sliders • 205 splash screens • 298 stack fields • 220 subforms • 222 table fields • 223 text file editors • 299 toggles • 205

Index 683

user class attributes • 415, 416 methods • 421

variables • 448 viewports • 231

Customizing About boxes • 287 applications • 84 calculators • 289 Font dialogs • 295 OpenROAD Connection Profiles window • 71 OpenROAD Workbench • 71 splash screens • 299 work sessions • 85

Cutting text in scripts • 439

D

Data format templates date format templates • 643 numeric templates • 638 using • 637 varchar templates • 650

Data, validating • 638 Database applications

RunDBApp utility • 577 running • 577

Database events • 28 Database procedures

components • 93 creating • 462 described • 27 editing • 464 registering • 29, 461 scope • 29 setting properties • 463 viewing • 464

Database sessions locking • 35 transactions and concurrent frames • 35

Database table browser creating • 317, 321, 325 using • 318, 322, 327

Database transactions, concurrent frames • 35 Databases

accessing application data • 82 application reports • 556 creating fields from tables • 275 creating user classes from tables • 416 DocumentApp utility • 556

procedures • 29 scope • 29

Data-driven applications • 34 Date format templates • 649

absolute date and time format templates • 644

defining • 643 examples • 646, 648 guidelines • 646 input masking • 649 overview • 643 time interval format templates • 647

DBMS Connect Flags application properties • 82 previewing and printing report documents •

532 Debug tab • 51 Debugging

applications • 103 frames • 146

Declaring constants • 28 local variables • 29 parameters • 23 variables • 28

Deleting 3GL procedure • 464 4GL procedures • 460, 464, 467 application versions • 542 applications • 102, 542 attributes • 421 component versions • 544 components • 102 composite fields • 163 data fields • 509 database connection profile • 71 database procedure • 464 delete field styles • 133 DestroyApp utility • 542 external classes • 431 fields • 163 frames • 149 ghost frames • 467 global constants • 455 global variables • 451 joins • 316 macro variables • 453 methods • 426 numbered component versions • 544 PurgeApp utility • 544


reports • 534 user classes • 426

demo, 3GL application • 467 Deploy tab • 56 deploying web-based applications • 587 DestroyApp utility

deleting applications • 542 parameters • 542

Detail frame application • 33 creating • 329 using • 330

Develop tab • 49 Dialogs

About Box Assistant • 285 Add Included Application • 89 Analog Clock Assistant • 343 Application Properties • 82, 84, 85, 87 Apply • 561 Apply Template Utility • 561 AttributeProperties • 415, 420, 425 BoxTrim Properties • 514 Browse • 125, 403 Calculator Assistant • 288, 351 Calendar Assistant • 351 Change Database • 346 Close • 98 Column Attributes • 208, 210 Compile • 566 Confirmation • 84, 85, 149, 426, 451, 455,

460, 464, 467 Copy Table • 324 Countdown Timer Assistant • 353 Create 3GL Procedure • 461 Create Application • 81, 82 Create Attribute • 415 Create Connection Profile • 67, 68 Create Database Procedure • 461 Create Field Template • 90, 273 Create Frame Template • 142 Create Ghost Frame • 465 Create Global Variable • 449 Create Method • 421 Create User Class • 414 Create User Frame • 90, 107, 108, 144,

285, 288, 291, 295, 302, 329 creating • 107, 108 Cursors • 268 Data Type • 120, 639, 643, 650 DateField Properties • 521

Digital Clock Assistant • 355 Document • 556 Duplicate Spacing • 532 Elapsed Timer Assistant • 357 Example Date Templates • 521 Example Page # Templates • 522 Export • 552 File Selection • 67, 84, 85, 89, 125, 130,

176, 179, 185, 206, 285, 298, 408, 461 Financial Calculator Assistant • 302 Find Application Property • 74, 99 Find Component Property • 77, 99 Find/Replace Dialog Assistant • 291 Font Dialog Assistant • 295 Frame Assistant • 305, 317, 321, 325, 329 FreeTrim Properties • 514 Gauge Assistant • 359 Go to Line Number • 440 Graph Assistant • 346, 362 Grid Spacing • 134, 531 ImageField Properties • 517 Import an Application • 547 Join Definition • 491 Load from File • 479 Make Image • 569 MatrixField Properties • 513 Meter Assistant • 363 Method Properties • 421 Page Number Properties • 522 Preferences • 289 Print • 532 Query • 320, 335 Query Image • 559 Rename Application • 101 Rename Component • 101 Reporter Color Properties • 529 Reporter DataField List • 501, 517 Reporter DataField Properties • 501, 505,

523 Reporter Document Properties • 480 Reporter Documents • 479 Reporter Font Setup • 528 Reporter Images • 517 Reporter Query Columns • 490 Reporter Query Restriction • 490 Reporter Sort Columns • 492 Reporter Table Selection • 505 RunImage • 580 Running Report • 532 Save As New Template • 130

Index 685

Search/Replace • 440 Select a Class • 120, 414, 450, 466 Select a Column • 491 Select a Database Table • 275, 416 Select a Document • 522 Select a Field Template • 271, 313, 343 Select a Frame Template • 130 Select a Parent Frame • 305, 329, 331 Select a User Class • 277 Select Application Columns • 74, 99 Select Component Columns • 77, 99 Select Component Types • 78 Select Database Object • 305, 317, 325,

329 Select External Object • 279 Select Starting Component • 84, 103 Set Data Sort Order • 319 Set Tool Defaults • 584 Setup/Cleanup • 494 Spin Control Assistant • 367 Splash Screen Assistant • 298 StackField Properties • 511 Stop Watch Assistant • 370 Tab Page Array • 232 Tabbed Dialog Assistant • 377 Table Selection • 275, 308, 416 TableField Properties • 510 Text Editor Assistant • 299 Timer Options • 344, 356 Value List • 186, 188, 200, 240, 392, 408 Variable Properties • 506, 509 Variables List • 506 Version • 539

digital signature • 589 Displaying

application versions • 73 component versions • 76

Document documenting application images • 559, 560 documenting applications • 558 saving reports • 532

DocumentApp utility documenting applications • 558 reporting on applications • 556

Documentation • 18

E

eClient complib.cab library file • 588, 607 complib.rel file • 592 deploying • 587, 588 digital signature • 589 Install4GL. exe file • 606 Install4GL.txt file • 606 installing • 587 MakeCAB utility • 588, 590, 595 makecab.ini file • 592 oraxp.cab cabinet file • 588, 607 oraxp.rel history file • 592 orrun.dll file • 604 run modes • 599 runtime command flags • 599 setting up web server • 588 w4glrun runtime command • 599

Editing 3GL procedures • 464 4GL procedures • 459 applications • 96 components • 96 database procedures • 464 field scripts • 270 frame templates • 146 frames • 146 global constants • 455 global variables • 450 multiple scripts • 445 option menus • 182 scripts • 439

copying • 439 cutting • 439 finding and replacing text • 440

user class attributes • 420, 425 user class methods • 420, 425 user classes • 426

Editors 3GL Procedure Editor • 461, 464 4GL Procedure Editor • 459 Class Editor • 412, 414 Constant Editor • 454, 455 Database Procedure Editor • 461, 464 External Class Library Editor • 279, 431 Field Template • 273 Frame Editor • 107, 108, 109 Frame Template Editor • 142


Ghost Frame Editor • 465 Global Variable Editor • 448, 449, 450 Include Script Editor • 435, 439 Macro Variable Editor • 448 Menu Editor • 105, 380 Option Menu Editor • 182, 184 Script Editor • 105, 270, 438, 456, 459 Style • 127 system editor • 435, 442, 456, 459 Toolbar Editor • 105, 399

Ellipse shapes creating • 169

Environment variables for all platforms • 619 for Ingres • 627 for Windows platforms • 626 II_4GL_DECIMAL • 619 II_CHARSET • 619 II_CHARSETxx • 619 II_COLORTABLE • 619 II_COLORTABLE_FILE • 619 II_CONFIG • 619 II_CONNECT_LOG • 627 II_CONNECT_RETRIES • 627 II_DATE_FORMAT • 619 II_DECIMAL • 619 II_EDIT • 442, 619 II_FONT_CONVENTION • 619 II_FONT_FILE • 619 II_FORCE_C_CONVENTION • 626 II_INSTALLATION • 619 II_KEYBOARD • 619 II_KEYBOARD_FILE • 619 II_LANGUAGE • 619 II_LIBU3GL • 619 II_LOG • 619 II_MONEY_FORMAT • 619 II_MONEY_PREC • 619 II_MSGDIR • 619 II_SCREEN_HEIGHT_INCHES • 619 II_SCREEN_HEIGHT_MMS • 619 II_SCREEN_WIDTH_INCHES • 619 II_SCREEN_WIDTH_MMS • 619 II_SYSTEM • 619 II_TEMPORARY • 619 II_TRUNCATE_W4GL_LOGFILE • 626 II_VIEW • 442, 619 II_W4GL_CACHE_LIMIT • 619 II_W4GL_HASSTATUSBAR • 619 II_W4GL_LINEWIDTHS • 619

II_W4GL_LOCK • 627 II_W4GL_OPEN_IMAGES • 619 II_W4GL_SYSTEMEDITOR • 436, 442, 619 II_W4GLAPPS_DIR • 614, 619 II_W4GLAPPS_SYS • 619 II_WINDOWEDIT • 442, 619 II_WINDOWVIEW • 442, 619 IIW4GL_DEBUG_3GL • 619 ING_EDIT • 619 PICTURE_DIR • 619 setting • 617 STRING_DIR • 619 system editor • 442 VASA_FILE • 619

Errors, compilation • 147 Event blocks

field scripts • 255 frame scripts • 436 scope • 29 using • 23

Events fields • 255 in scripts • 23, 255

Executing applications • 32 frames • 32

Explosion frame creating • 331 Unfreeze All command • 332 Unfreeze command • 332 using • 332

ExportApp utility examples of use • 555 exporting applications • 552 parameters • 553 setting defaults for • 584

Exporting applications • 546 components • 546 ExportApp utility • 546, 552

External classes creating fields from • 279 libraries • 92, 428 overview • 413

External controls • 279

Index 687

F

Field capabilities at runtime • 123 Field palette

displaying • 113 hiding • 113 overview • 111

Field placement • 161 Field scripts

creating • 270 editing • 270 event blocks • 255 scalar fields • 29 scope • 29

Field styles creating multiple styles for a field type •

129 deleting • 133

Field Template Editor Field Template Properties window • 273 using • 273

Field templates application management • 39 ApplyTemplate utility • 561, 564, 565 components • 95 creating • 271, 273 for creating fields • 271

Field Tree window • 141, 212 Field variables, scope • 29 Fields

biases • 257 color • 164 composite • 153, 215, 231 converting • 167 copying • 162 creating

creating from database tables • 275 creating from external classes • 279 creating from field templates • 271 creating from user classes • 277

events • 255 field type descriptions • 151 FocusBehavior property • 260 grouping • 158 moving • 161 overlapping • 160 resizing • 161 scalar • 152, 170 selecting • 157

selection box • 158 setting

setting focus behavior • 260 setting gravity • 255 setting selection type • 264

shape • 167 shape fields • 152 simple fields • 151 tab sequencing • 266 using field styles • 127 variables • 254

Files symbol.tbl • 617, 618 w4gl.log • 39, 538, 549, 566, 569

Find dialog calling • 292 creating • 291 find_dialog template • 290 using • 293

Finding and replacing text in scripts • 440 Flexible forms

creating • 216 properties • 217, 240

Focus behavior properties • 240 setting • 260, 396

Font dialog box creating • 295 customizing • 295

Fonts changing in reports • 527 character formatting • 524 setting default • 528

Format templates • 649 Format, images • 175, 180 Forms

background • 124 creating • 108 described • 22 shape layer • 160 simulating • 148

Frame Frame styles

selecting • 33 style sheets • 127

modes • 123 properties • 114 scripts

described • 23, 436 event blocks • 23, 436


initialize blocks • 23 initialize statement • 436 local procedures • 436 scope • 29

Frame Assistant setting lookup table priorities • 334 using to create

detail frames • 329 master-detail frames • 325 simple field frame • 317 table field frame • 321

Frame Editor color palette • 109 compilation error messages • 147 field palette • 109, 111 field templates • 271 Field Tree window • 141 font palette • 109, 173 frame templates • 142 overview • 109 Property Inspector • 113, 135

Frame Template Editor creating • 142 setting properties • 144

Frame template properties descriptions • 114, 144 setting • 144

Frame templates • 284 about_box • 285 application management • 38 ApplyTemplate utility • 561 calculator • 287 components • 95 creating • 142 detail • 328 Dialog_Box • 107 editing • 146 Empty_Frame • 107 explosion • 331 financial_calculator • 302 find_dialog • 290 font_dialog • 294 Master_detail • 325 mclient_frame • 339 Menu • 107 simple_field • 317 splash_screen • 297 table_field • 321 text_editor • 299

using style sheets • 127 Frames

4GL frame scripts • 23 active state • 32 associating an icon • 114 called vs. calling • 33 changing mode • 123 child • 33 compiling • 146, 147 concurrent

read/write applications • 34 read-only application • 34

control frames • 33 controlling flow • 31 creating • 105 creating from frame templates • 142, 144 debugging • 146 default mode • 123 deleting • 149 described • 24 editing • 146 frame mode options • 123 inactive state • 32 invoking • 32 moving between • 26 multiple use • 31 parent • 33 pop-up • 114 positioning • 124 properties • 113 running • 148 scope • 29 sequential • 31 setting a return value • 120 setting a title • 114 setting properties • 113 sharing among applications • 37 sharing information between • 27 standardizing • 37 starting applications • 32 testing • 146 using style sheets • 127 viewing • 146

Functions aggregate • 503 numeric • 503

Index 689

G

Generating fields from templates • 341 frames from templates • 281 reports

report for applications • 555 report for components • 555

Ghost frames components • 92 creating • 465 described • 25 in non-interactive applications • 39 setting properties • 466

Global constants changing at runtime • 30 components • 94 creating • 30, 454 customizing • 30 deleting • 455 described • 28 editing • 455 initializing • 85 scope • 30 standardizing • 28 viewing • 455

Global procedures • 27 Global variables

4GL procedures • 29 components • 94 creating • 449 deleting • 451 described • 28 description • 28 editing • 450 initializing • 85 setting properties • 450

Gravity described • 255 palette • 530 setting • 256, 530

Grouping fields • 158

I

Icons applications • 82, 114 associating with frames • 114 Frame Editor palette • 111

II_WINDOWEDIT template • 443 II_WINDOWVIEW template • 443 Image fields

creating • 180, 517 described • 180 modifying • 521 porperties • 181 using • 516

Image files creating • 569 incorporating included applications • 575 running • 577

Image trim creating • 175

Images application reports • 559 creating an application image • 569 formats • 175, 180 MakeImage utility • 569 QueryImage utility • 559 RunImage utility • 577 running • 577

Imaging included applications • 575 libraries • 575

Importing applications • 546 components • 546 ImportApp utility • 546, 547

Inactive frames • 32 Include scripts

components • 94 writing • 438

Included applications core, default • 88 defining • 87 libraries • 87 using • 89

Initialize blocks declaring variables • 29 scope • 29 using • 23, 29

Initialize statement field and menu scripts • 437 frame scripts • 436 local variables • 29

Initializing global variables and constants • 85 local variables and procedures • 29


Input masking date format templates • 649 numeric format templates • 643 overview • 638, 649

Install4GL. exe eClient executable • 606 Install4GL.txt eClient installation file • 606 Installation • 18 International characters • 619, 628

K

Key definitions • 632, 633, 634 Keyboard map files

example • 634 formatting • 632 selecting a file • 631 speed keys • 631 using II_KEYBOARD • 631 using II_KEYBOARD_FILE • 632

Keyboard operations, speed keys • 35

L

Libraries Core • 88 creating • 575 external class • 92, 428, 429 included applications • 87 specifying in the MakeCAB utility • 607

Line Attributes palette • 527 List fields

creating • 186 deleting • 188 described • 186 modifying value lists • 188 properties • 186 setting selection type • 264

Local procedures creating • 456 described • 27 frame scripts • 436 modularizing code • 27 scope • 29 using 4GL procedures • 461

Local variables scope • 29

Locking database sessions • 35

M

Macro variables creating • 452 deleting • 453 described • 451 properties • 452

makecab.ini eClient initialization file • 592 MakeImage utility

creating application images • 569 parameters • 569

Manage tab • 58 Master-detail frame assistant

adding associate tables • 336 detail tables • 337 lookup tables • 333

defining join column properties • 314 setting

display properties • 313 query expressions • 310 query properties • 311

using lookup frames • 335 Matrix fields

creating • 218 described • 217 grouping • 512 properties • 218, 513

mClient deploying • 611 installing • 611 launching • 612 mclient_frame template • 339

Menu buttons creating • 389 properties • 390 speed key mapping • 35

Menu commands Application Properties • 84, 85, 87 Button Field • 404 Class Browser • 432 Close • 98 Color Palette • 126 Columns • 74, 77 Compile • 147, 566 Component Palette • 74 Convert To • 384 Cross Reference • 78 Defaults • 584

Index 691

Delete • 67, 149 Details • 71, 74 Edit • 67 Field Palette • 113 Field Script • 384, 437, 439 Generated From • 78 Go • 87, 103, 104 Go to Line Number • 440 Grid Spacing • 134 Icon • 74 Import • 547 Insert Field • 113 Insert Top Toolbar • 403 Layout Bring to Front • 157, 160 Layout Gravity • 256 Layout Resize to Largest • 161 Layout Resize to Smallest • 161 Layout Send to Back • 157, 160 List • 74 Make Image • 569 Menu commands • 392 Menu Toggle • 390 New • 67, 89, 90 New User Frame • 144 Open • 96, 146 Option Field • 407 Palette Field • 408 Properties • 74 Pull-down/Slide-off Menu • 385, 387 Read Style from File • 130 Referenced By • 78 Refresh Application List • 73 Refresh Current Application • 73, 76, 97 Rename • 101 Revert to Last Saved • 98 Save • 98 Save and Close • 98 Save As • 98, 142 Save As New Template • 98, 142 Save As New Version • 98 Save Private • 98 Script • 438, 439 Select All • 158 Select Children • 158 Select Parent • 158 Show Application Versions • 73 Show Component Versions • 76 Simulate • 146, 148 Sort • 74, 77 Status Bar • 71, 74

Stop • 104, 146 Style Sheet • 127 System Classes • 433 Toggle Field • 409 Toolbar • 71 Tools Simulate • 164 Types • 78 View • 146 View Composite Outlines • 158 View Property Inspector • 138 Write Style to File • 130

Menu Editor accessing • 380 layout area • 380 status bar • 380 tool palette • 380, 382

Menu items assigning speed keys • 396 converting • 384 creating • 385 editing • 384 focus behavior • 396 scripts • 384 setting biases • 395 types • 381 variables • 384

Menu lists creating • 392 properties • 392

Menu operations, syntax • 36 Menu separators

creating • 393 properties • 393

Menu toggles assigning speed keys to • 396 creating • 390 properties • 391

Menus control buttons • 182 converting menu items • 384 creating menu items • 385 editing menu items • 384 types • 381

metaflags • 583 Metaflags

-/include • 586 RunDBApp Utility • 583 RunImage Utility • 583


Methods creating for user classes • 421 editing • 420, 425 properties • 423 scripts • 424

Modes default frame mode • 123 draw biases • 259 frame mode options • 123

Modularizing code • 27 Monitor tab • 52 Mouse

selecting operation style • 35 user actions • 264

moving fields • 161 Multiline entry fields

creating • 194 described • 194 properties • 195

Multiple fields creating • 156 selecting • 137

Multiple-use frame structure • 31 Multiple-user frames, data-driven • 34

N

Name conflicts in copying applications and components • 547

Non-interactive applications creating • 39 ghost frames • 25, 465

Numeric format templates defining • 639 input masking • 643 overview • 638 syntax • 640

Numeric functions • 503

O

Objects alphanumeric identifiers • 24 described • 24 naming • 24 naming rules • 82, 240, 418, 423

Open frames commit statement • 35 opening • 111

rollback statement • 35 unrelated • 35

OpenROAD color palettes • 126 Constant Editor • 30 documentation • 18 error log file • 39 Field Tree feature • 141 interface • 42 Menu Editor • 380 naming rules • 82, 240, 418, 423 OpenROAD Connection Profiles window • 67 starting a development session • 61 Style Editor • 127 Toolbar Editor • 399 Trace window • 39

OpenROAD Connection Profiles window accessing • 67 customizing • 71

OpenROAD eClient • 587 OpenROAD eClient Packaging Tool (MakeCAB

utility) • 588, 590, 595 OpenROAD mClient

deploying • 611 installing • 611 launching • 612 mclient_frame template • 339

OpenROAD Reporter Alignment palette • 525 detail page • 497 detail section • 497 document contents • 499 field palette • 476 file toolbar • 476 footer page • 497 footer section • 497 Gravity palette • 530 header page • 497 header report page • 494 header section • 497 Join Query Editor • 491 layout toolbar • 476 Line Attributes palette • 527 main menus • 475 object position toolbar • 476 OpenAPI Code Browser for Field • 515 OpenAPI Code Editor for Field • 515 Print Preview window • 532 Query Editor • 486 query toolbar • 476

Index 693

report sections • 496 Reporter Text Editor • 494 revert to last saved command • 494 Save As command • 494 setting default font • 528 setup/cleanup statements • 493 SQL Code Viewer • 486 starting • 474 text toolbar • 476 toolbars • 476 Where Clause Editor • 490 window • 475 working with sections • 497

OpenROAD Workbench Class Browser • 432 Class Editor • 412, 414 Component Cross Reference window • 78 component mode • 76 creating a frame • 107, 108 customizing • 71 description • 17 Field Template Editor • 273 Frame Editor • 107, 108, 109 Frame Template Editor • 142 installing • 18 Menu Editor • 105 overview • 42 Script Editor • 105 starting • 61 Toolbar Editor • 105

Operation styles, selecting • 35 Option fields

creating • 198, 407 described • 198 properties • 199

Option Menu Editor, using • 182, 184 Option menus

editing control buttons • 182 oraxp.cab eClient cabinet file • 588, 607 oraxp.rel eClient history file • 592 orrun.dll eClient runtime file • 604 Overlapping fields • 160

P

Palette fields creating • 200, 408 properties • 201

Palettes color palettes • 126 field palette • 111 font palette • 173 Frame Editor • 109 Menu Editor • 380, 382

Parameters ApplyTemplate utility • 564 CompileApp utility • 566 declaring • 23 DestroyApp utility • 542 DocumentApp utility • 556 ExportApp utility • 553 ImportApp utility • 549 makeimage command line utility • 572 MakeImage utility • 569 PurgeApp utility • 544, 545 QueryImage utility • 559 RunDBApp utility • 577 RunImage utility • 580 specifying for runtime • 87 VersionApp utility • 540

Parent frames communicating with child frames • 33 described • 33

Pocket PC • 611 Pop-up frames, specifying • 114 Positioning frames • 124 Predefined frame templates, using • 281, 305 prefixes • 138 Print Preview window • 532 Printing a report on applications • 556 Private versions

creating • 538 working copies • 96

Procedures 3GL • 27, 93, 462, 463 4GL • 27, 29, 93, 456, 458 database • 27, 29, 93, 462, 463 described • 456 overview • 26 scope • 29 starting applications • 32 types • 26

Properties 3GL procedures • 463 4GL procedures • 458 database connection profiles • 68 database procedures • 463 FocusBehavior • 260


frame templates • 114 frames • 113, 114 ghost frames • 466 global variables • 450 Gravity • 255 menu lists • 392 menu toggles • 390 modifying application properties • 84 SelectionType • 264 setting

application properties • 81 frame properties • 113

user class attributes • 418 user class methods • 423

Property Inspector described • 135 Field List feature • 136 miscellaneous features • 138 multiple field selection • 137 property filters • 137 Property Filters feature • 137 using • 113

property setting prefixes • 138 Prototype cells

columns • 230 tablefields • 230

PurgeApp Utility parameters • 544 purging components • 545

Purging applications • 102 components • 544, 545

Q

Queries defining • 486 performing • 320 saving a report query • 494

Query Editor defining a query • 486 fields • 488 query definition pane • 486 single field mode • 501

Query tab • 54 QueryImage utility • 559

parameters • 559 reporting on application images • 559

R

Radio fields creating • 201 properties • 202

Read/write applications • 34 Read-only applications • 34 Refreshing the Application Browser display •

73, 76 Registering

3GL procedures • 29, 461 database procedures • 29, 461 external class libraries • 428

Renaming applications and components • 101 Replace dialogs

creating • 291 find_dialog frame template • 290 using • 440

Reporting DocumentApp utility • 556 QueryImage utility • 559

Reports adding borders • 526 adding graphics • 532 adjusting fields • 526 alignment options • 525 box trim fields • 514 box trim from file fields • 514 changing colors • 529 changing fonts • 527 converting • 534 converting with RWConv • 535 creating • 480 creating fields • 496 creating Tabular • 485 data breaks • 523 data fields • 500 date and time field • 521 defining joins • 491 defining query • 485 deleting • 494, 534 deleting data field • 509 design considerations • 478 designing • 478 duplicate spacing • 532 editing document properties • 481 editing joins • 491 enhancing design • 524 exporting • 534

Index 695

fields from table presentation • 505 for application images • 559 for applications • 556 for components • 556 for resident applications • 556 Form presentation • 483 formatting • 479, 524 free trim fields • 514 free trim from file fields • 514 fusing two texts • 515 generating • 556, 559 grid spacing • 531 grouping fields • 509 image fields • 517 importing • 479 locking fields • 523 manipulating fields • 499 matrix fields • 512 modifying

data field properties • 505 image fields • 521 shape field properties • 517 variable field properties • 509

moving around in • 498 Open API code • 515 opening • 479 page breaks • 523 Page Layout presentation • 484 page number fields • 522 positioning fields • 499 previewing • 532 printing • 532 propagate graphical properties • 530 query table owner • 489 repeat creation • 523 saving document • 494 saving query • 494 selecting columns • 491 selecting field • 499 setting document properties • 480 setting gravity • 530 setting matrix field properties • 513 setting stack field properties • 511 setting table field properties • 510 shape fields • 516 single fields • 501 sorting columns • 492 special fields • 521 stack field properties • 511 stack fields • 511

static text fields • 514 synchronize properties • 531 table fields • 510 table join definitions • 491 table names • 489 Tabular presentation • 485 text display options • 526 variable field properties • 507

Resizing fields • 161

Resizing fields • 161 Return values

setting for frames • 120 run modes

eClient • 599 RunDBApp utility • 577

metaflags • 583 parameters • 577 running from a database • 577

RunImage utility • 577 metaflags • 583 running from an image • 580

Running application images • 577 applications • 577 applications from a database • 577 applications from an image • 580 database applications • 577 frames • 148 image files • 577 multiple applications • 104 single application • 103

Running applications testing • 103

Runtime changing field appearance • 123 changing global constants • 30

Runtime parameters, specifying • 87

S

sample application, 3GL • 467 Sample applications

Videos • 31, 33 Saving

components • 98 Scalar fields

creating • 170 description • 152, 170

Scalar fields, field script • 29


Scope constants • 29 frames • 29 procedures • 29 variables • 29

Script Editor calling • 439 canceling edits • 441 interface • 441 saving edits • 441 using • 270, 438

Scripts creating for menu items • 384 creating for toolbar items • 402 described • 436 editing • 439 editing multiple scripts • 445 initialize block • 437 types • 436 user class methods • 424 using • 435 writing

field • 437 frame • 436 include scripts • 438 menu • 437 user class • 438

Scroll bars creating • 203

Selecting composite fields • 158 fields • 157 operation style • 35 simple fields • 157

Selection box fields • 158

Send to Back operation fields • 160

Sequential frames applications • 31 committing database transactions • 35

Server Manager initialization file • 619 Sessions

customizing • 85 Setting

3GL procedure properties • 463 4GL procedure properties • 458 database procedure properties • 463 focus behavior • 396 focus behavior for fields • 260

frame properties • 113 frame template properties • 144 ghost frame properties • 466 global variable properties • 450 menu item biases • 395 page locks • 627 return values for frames • 120 selection type for a field • 264

Shape fields creating • 167 description • 151, 152, 167

Shapes description • 167

Shapes and layers forms • 160

Sharing frames applications • 37 enhancing productivity • 37

Simple fields selecting • 157

Simulating forms • 148

Single-line entry fields creating • 189 data format templates • 637 mandatory entry • 657

Sliders creating • 205

Special characters numeric format templates • 640 varchar templates • 652, 653, 654, 655,

656, 657 Specifying

initial values constants • 85 global variables • 85

runtime parameters • 87 Speed keys

assigning to menu items • 396 attributes • 35 keyboard map files • 631 keyboard operations • 35 menu buttons • 35 mouse operations

mouse operations • 35 operations • 35 setting • 631

Splash screens creating • 298 customizing • 299

Index 697

Stack fields creating • 220

Standardizing global constants • 28 user interaction • 34

Starting a development session • 61 Starting frames

opening • 32 Statements

callframe • 25, 32, 33 commit • 35 connect • 68 gotoframe • 25, 32 openframe • 25, 32, 34 rollback • 35 SQL statements • 28

Style sheets application management • 38 overview • 127

Subforms creating • 222

Syntax menu operations • 36

System classes, overview • 411 System editor

environment variables • 442 using • 436, 442

T

Tab sequences modifying • 268 overview • 266

Table fields creating • 223 modifying • 230 setting selection type • 264

Tablefields prototype cells • 230

Tables creating user classes • 416

Tabs • 42 Build • 55 Connect • 47 Debug • 49 Deploy • 56 Manage • 56 Monitor • 52 Query • 51 Tabs Develop • 49

Templates for II_WINDOWEDIT and II_WINDOWVIEW

• 443 Templates, data format • 637 Testing

4GL procedures • 456 frames • 146

Text file editor creating • 299

Titles setting for frames • 114

Toggles creating • 205

Toolbar Editor accessing • 399 Edit menu • 401 Insert menu • 401 inserting toolbar items • 401 layout area • 400

Toolbar items creating • 403 editing • 403 scripts • 402 types • 400 variables • 403

Toolbars adding spaces • 400 creating buttons • 400 creating option fields • 400 creating toggle fields • 400 creating toolbar items • 403 editing toolbar items • 403

Transaction management concurrent frames • 35

Trim fields • 171

U

User classes components • 92 creating attributes • 415 creating attributes from tables • 416 creating fields • 277 creating methods • 421 deletingg • 426 editing • 426 setting attribute properties • 418 setting method properties • 423 viewing • 426


User events described • 28 ghost frames • 465

User frames components • 91

Using 4GL procedures • 26 ActiveX controls • 279 Class Browser • 432 color palettes • 126 color tables • 629 data format templates • 637 detail frames • 330 escape character • 653 explosion frames • 332 external controls • 279 field palette • 111 Field Tree feature • 141 Frame Assistant • 305 included applications • 89 international characters • 628 local 4GL procedures • 461 lookup frames • 335 master-detail frames • 327 Option Menu Editor • 182, 184 property filters • 137 Property Inspector • 135, 136 Script Editor • 270, 438 scripts • 435 simple field frames • 318 special characters • 640, 652, 653, 654,

655, 656, 657 symbol.tbl • 618 system editor • 436, 442 table field frames • 322 text editor frames • 300

Utilities • 537 ApplyTemplate • 561 CompileApp • 566 DestroyApp • 542 DocumentApp • 556 ExportApp • 552 ImportApp • 547 MakeImage • 569, 575 overview • 537 PurgeApp • 545 QueryImage • 559 RunDBApp • 87, 577 RunImage • 87, 580 VersionApp • 538, 539

V

Validating data • 638 Varchar templates

character sets • 653, 654, 655, 657 creating a custom template • 651 default character • 656 defining • 650 escape character • 653 examples • 657, 658 mandatory entry • 657 overview • 650 special characters • 652 specifying case • 656

Variables creating • 447, 448 defining • 28 describing • 447 field • 29 fields • 254 menu items • 384 scope • 29 toolbar items • 403 types • 447 use of () (parentheses) • 29

vasa.ini initialization file • 619 VersionApp utility

creating applications versions • 539 Versions

numbered • 538 private • 538

Viewing 3GL procedures • 464 4GL procedures • 459 compilation errors • 147 database procedures • 464 frames • 146 global constants • 455 user classes • 426

Viewports creating • 231

W

w4glrun, eClient runtime command • 599 web server, setting up for eClient • 588 web-based applications • 587 Windows

Class Browser • 432 Compilation Errors • 147

Index 699

Component Cross Reference • 78 executing without the window manager • 39 Field Template Properties • 273 Field Tree • 141 OpenROAD Connection Profiles • 67 placement • 124 Trace • 39

Writing field scripts • 437 frame scripts • 436 include scripts • 438 menu scripts • 437 user class scripts • 438

X

XML project file for MakeCAB utility • 594, 595, 607