Progress

Progress
Programming
Handbook
2001 Progress Software Corporation. All rights reserved.

Progress
software products are copyrighted and all rights are reserved by Progress Software Corporation.
This manual is also copyrighted and all rights are reserved. This manual may not, in whole or in part, be
copied, photocopied, translated, or reduced to any electronic medium or machine-readable form without
prior consent, in writing, from Progress Software Corporation.
The information in this manual is subject to change without notice, and Progress Software Corporation
assumes no responsibility for any errors that may appear in this document.
The references in this manual to specific platforms supported are subject to change.
Progress, Progress Results, Provision and WebSpeed are registered trademarks of Progress Software
Corporation in the United States and other countries. Apptivity, AppServer, ProVision Plus, SmartObjects,
IntelliStream, and other Progress product names are trademarks of Progress Software Corporation.
SonicMQ is a trademark of Sonic Software Corporation in the United States and other countries.
Progress Software Corporation acknowledges the use of Raster Imaging Technology copyrighted by
Snowbound Software 1993-1997 and the IBM XML Parser for Java Edition.
IBM Corporation 1998-1999. All rights reserved. U.S. Government Users Restricted Rights Use,
duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Progress is a registered trademark of Progress Software Corporation and is used by IBM Corporation in the
mark Progress/400 under license. Progress/400 AND 400
are trademarks of IBM Corporation and are used

by Progress Software Corporation under license.
Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the
United States and other countries.
Any other trademarks and/or service marks contained herein are the property of their respective owners.
.
Product Code: 4533
Item Number: 81101;9.1C
May 2001
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii
Organization of This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii
Volume 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii
Volume 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxv
How to Use This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxvii
WebSpeed Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxvii
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxviii
Syntax Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxix
Example Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xliii
Progress Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlvi
Other Useful Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlvii
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlvii
Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlix
Reporting Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . l
4GL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . li
Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . li
DataServers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lii
SQL-89/Open Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lii
SQL-92 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . liii
Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . liii
WebSpeed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . liv
Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lv
1. Introducing the Progress 4GL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.1 What Is a 4GL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.1.1 A Powerful Application Builder . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.1.2 More Complex Applications Supported . . . . . . . . . . . . . . . . . . 13
Contents
iv
1.1.3 Less Development Effort Required . . . . . . . . . . . . . . . . . . . . . . 14
1.1.4 Less Platform Knowledge Required . . . . . . . . . . . . . . . . . . . . . 16
1.2 ProgressThe Flexible and Complete 4GL . . . . . . . . . . . . . . . . . . . . . . 16
1.2.1 Flexibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.2.2 Consistency. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.2.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
1.2.4 Interoperability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
1.2.5 Connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
1.2.6 Portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
1.2.7 Localizability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
1.3 Understanding Progress Syntax and Semantics . . . . . . . . . . . . . . . . . . . 112
1.3.1 Elements of Progress Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 112
1.3.2 Blocks and Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
1.3.3 Block Context and Resource Scope . . . . . . . . . . . . . . . . . . . . . 116
1.3.4 Compile-time Versus Run-time Code . . . . . . . . . . . . . . . . . . . . 119
1.4 Compile-time Versus Run-time Execution . . . . . . . . . . . . . . . . . . . . . . . . 126
1.4.1 Compile-time Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
1.4.2 Run-time Execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
2. Programming Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.1 Procedure- and Event-driven Programming . . . . . . . . . . . . . . . . . . . . . . 22
2.2 Flow of Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.2.1 Program Execution in a Procedure-driven Program . . . . . . . . . 22
2.2.2 Program Execution in an Event-driven Program . . . . . . . . . . . 25
2.3 Program Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.3.1 Program Structure in a Procedure-driven Program. . . . . . . . . . 28
2.3.2 Program Structure in an Event-driven Program . . . . . . . . . . . . 29
2.4 When to Use the Procedure-driven and Event-driven Models . . . . . . . . 212
3. Block Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.1 Blocks and Their Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.1.1 REPEAT, FOR, and DO Blocks . . . . . . . . . . . . . . . . . . . . . . . . 32
3.1.2 Procedure Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.1.3 Trigger Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.1.4 EDITING Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.1.5 Block Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.1.6 Looping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.1.7 Record Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.1.8 Frame Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.1.9 Record Scoping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
3.1.10 Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
3.1.11 Error Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
3.2 Procedure Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
3.3 External Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Contents
v
3.3.1 Procedure Filenames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
3.3.2 Standard Execution Options . . . . . . . . . . . . . . . . . . . . . . . . . . 321
3.3.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
3.3.4 Procedure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
3.3.5 Procedure Context and the Procedure Call Stack . . . . . . . . . . 323
3.3.6 Shared Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
3.3.7 Procedure Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
3.4 Internal Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
3.4.1 Internal Procedure Definition . . . . . . . . . . . . . . . . . . . . . . . . . . 330
3.4.2 Internal Procedure Execution . . . . . . . . . . . . . . . . . . . . . . . . . 331
3.4.3 Internal Procedure Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
3.4.4 Standard Execution Options . . . . . . . . . . . . . . . . . . . . . . . . . . 331
3.4.5 Internal Procedures and Encapsulation . . . . . . . . . . . . . . . . . . 332
3.4.6 Shared and Local Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
3.4.7 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
3.4.8 Internal Procedures and the Call Stack . . . . . . . . . . . . . . . . . . 337
3.5 Persistent and Non-persistent Procedures . . . . . . . . . . . . . . . . . . . . . . 337
3.5.1 Advantages of Persistent Procedures . . . . . . . . . . . . . . . . . . . 338
3.5.2 Creating Persistent Procedures . . . . . . . . . . . . . . . . . . . . . . . . 338
3.5.3 Working with Persistent Procedures . . . . . . . . . . . . . . . . . . . . 339
3.5.4 Deleting Persistent Procedures . . . . . . . . . . . . . . . . . . . . . . . . 341
3.5.5 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
3.5.6 Persistent Procedure Context and Shared Objects . . . . . . . . 344
3.5.7 Run-time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
3.5.8 Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
3.5.9 Condition Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
3.5.10 CURRENTLANGUAGE Changes . . . . . . . . . . . . . . . . . . . . . 346
3.6 User-defined Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
3.6.1 Locally Defined User-defined Functions . . . . . . . . . . . . . . . . . 348
3.6.2 Externally Defined User-defined Functions . . . . . . . . . . . . . . . 351
3.6.3 Remotely Defined User-defined Functions . . . . . . . . . . . . . . . 352
3.7 Procedure Overriding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
3.7.1 Feature Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
3.7.2 Super Procedure Prototyping . . . . . . . . . . . . . . . . . . . . . . . . . 355
3.7.3 Programming Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
4. Named Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.1 Feature Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.2 Programming Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5. Condition Handling and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.1 Progress Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.2 Rules About UNDO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.2.1 Infinite Loop Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Contents
vi
5.3 The ERROR Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.3.1 The ERRORSTATUS System Handle . . . . . . . . . . . . . . . . . . 56
5.3.2 Default Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.3.3 Overriding the Default Handling . . . . . . . . . . . . . . . . . . . . . . . . 510
5.4 The ENDKEY Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
5.5 The STOP Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
5.6 The QUIT Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
5.7 The ENDERROR Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
5.7.1 Distinguishing ERROR and ENDKEY . . . . . . . . . . . . . . . . . . . 521
5.7.2 ENABLE/WAITFOR Processing . . . . . . . . . . . . . . . . . . . . . . . 523
5.8 How Progress Handles System and Software Failures . . . . . . . . . . . . . . 524
5.9 Progress Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
5.10 Application Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
6. Handling User Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.1 The Keyboard and the Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.1.1 Key Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.1.2 Key Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.1.3 Key Translation Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.2 Key Codes and Key Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.3 Key Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
6.4 Changing the Function of a Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
6.5 Using Mouse Buttons and Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
6.5.1 Portable and Physical Buttons . . . . . . . . . . . . . . . . . . . . . . . . . 627
6.5.2 Specifying Mouse Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
6.6 Telling Progress How to Continue Processing . . . . . . . . . . . . . . . . . . . . 629
6.7 Monitoring Keystrokes During Data Entry . . . . . . . . . . . . . . . . . . . . . . . . 635
6.7.1 Editing Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
6.7.2 User Interface Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
6.7.3 Using Editing Blocks and User Interface Triggers. . . . . . . . . . . 636
7. Alternate I/O Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
7.1 Understanding Input and Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7.2 Changing the Output Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7.2.1 Output to Printers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.2.2 Additional Options for Printing on Windows . . . . . . . . . . . . . . . 74
7.2.3 Output to Files or Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
7.2.4 Output to the Clipboard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Contents
vii
7.2.5 Resetting Output to the Terminal . . . . . . . . . . . . . . . . . . . . . . . 76
7.2.6 Sending Output to Multiple Destinations . . . . . . . . . . . . . . . . . 77
7.2.7 Stream I/O vs. Screen I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
7.2.8 A Printing Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
7.3 Changing a Procedures Input Source . . . . . . . . . . . . . . . . . . . . . . . . . . 714
7.3.1 Input From Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
7.3.2 Input from Devices, Directories, and the Terminal . . . . . . . . . . 715
7.3.3 Receiving Input from Multiple Sources. . . . . . . . . . . . . . . . . . . 716
7.3.4 Reading Input with Control Characters . . . . . . . . . . . . . . . . . . 718
7.4 Defining Additional Input/Output Streams . . . . . . . . . . . . . . . . . . . . . . . 718
7.5 Sharing Streams Among Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
7.6 Summary of Opening and Closing Streams . . . . . . . . . . . . . . . . . . . . . . 724
7.7 Processes as Input and Output Streams (NT and UNIX only) . . . . . . . . 725
7.8 I/O Redirection for Batch Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
7.9 Reading the Contents of a Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
7.10 Performing Code-page Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
7.11 Converting Non-standard Input Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
7.11.1 Using QUOTER to Format Data. . . . . . . . . . . . . . . . . . . . . . . . 731
7.11.2 Importing and Exporting Data . . . . . . . . . . . . . . . . . . . . . . . . . 737
7.11.3 Using the PUT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
7.11.4 Using the IMPORT Statement . . . . . . . . . . . . . . . . . . . . . . . . . 740
8. The Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
8.1 &GLOBAL-DEFINE and &SCOPED-DEFINE Directives . . . . . . . . . . . . 82
8.1.1 Example Using &GLOBAL-DEFINE. . . . . . . . . . . . . . . . . . . . . 82
8.1.2 Preprocessor Name Scoping . . . . . . . . . . . . . . . . . . . . . . . . . . 83
8.2 &UNDEFINE Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
8.3 &IF, &THEN, &ELSEIF, &ELSE, and &ENDIF Directives . . . . . . . . . . . 86
8.4 DEFINED( ) Preprocessor Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
8.5 The &MESSAGE Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
8.6 Referencing Preprocessor Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
8.7 Expanding Preprocessor Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
8.8 Using Built-in Preprocessor Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
8.8.1 Built-in Preprocessor Name References . . . . . . . . . . . . . . . . . 814
8.8.2 Quoting Built-in Names and Saving {&SEQUENCE} Values . 816
8.9 Nesting Preprocessor References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
8.10 Arguments to Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818
8.11 Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818
9. Database Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
9.1 Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
9.1.1 Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
9.1.2 The CONNECT Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
9.1.3 Auto-connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Contents
viii
9.1.4 Multi-database Connection Considerations . . . . . . . . . . . . . . . 95
9.1.5 Run-time Connection Considerations . . . . . . . . . . . . . . . . . . . . 95
9.1.6 Connection Failures and Disruptions . . . . . . . . . . . . . . . . . . . . 96
9.1.7 Progress Database Connection Functions . . . . . . . . . . . . . . . . 98
9.1.8 Conserving Connections vs. Minimizing Overhead. . . . . . . . . . 99
9.2 Disconnecting Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910
9.3 Logical Database Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911
9.4 Database Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
9.4.1 Creating Aliases in Applications . . . . . . . . . . . . . . . . . . . . . . . . 913
9.4.2 Compiling Procedures with Aliases. . . . . . . . . . . . . . . . . . . . . . 914
9.4.3 Using Shared Record Buffers with Aliases . . . . . . . . . . . . . . . 916
9.5 Data-handling Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
9.6 Adding and Deleting Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
9.7 Defining a Set of Records to Fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
9.8 Fetching Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
9.8.1 Order of Fetched Records. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
9.8.2 Sample Record Fetches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
9.8.3 ROWID and RECID Data Types . . . . . . . . . . . . . . . . . . . . . . . . 923
9.8.4 Results Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
9.8.5 FIND Repositioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
9.9 Fetching Field Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
9.9.1 Field List Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
9.9.2 Specifying Field Lists in the 4GL. . . . . . . . . . . . . . . . . . . . . . . . 933
9.9.3 Avoiding Implied Field List Entries . . . . . . . . . . . . . . . . . . . . . . 935
9.9.4 Updating and Deleting with Field Lists . . . . . . . . . . . . . . . . . . . 935
9.9.5 Cursor Repositioning and Field Lists . . . . . . . . . . . . . . . . . . . . 936
9.9.6 Field List Handling in Degenerate Cases . . . . . . . . . . . . . . . . . 937
9.10 Joining Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938
9.10.1 Specifying Joins in the 4GL. . . . . . . . . . . . . . . . . . . . . . . . . . . . 940
9.10.2 Using Inner Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943
9.10.3 Using Left Outer Joins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945
9.10.4 Implementing Other Outer Joins . . . . . . . . . . . . . . . . . . . . . . . . 946
9.10.5 Mixing Inner and Left Outer Joins . . . . . . . . . . . . . . . . . . . . . . 947
9.11 The CONTAINS Operator, Word Indexes, and Word-break Tables . . . . 947
9.11.1 Understanding the CONTAINS Operator, Word Indexes, and Word-
break Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948
9.11.2 Creating and Viewing Word Indexes. . . . . . . . . . . . . . . . . . . . . 948
9.11.3 Using Word-break Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
9.11.4 Writing Queries Using the CONTAINS Operator . . . . . . . . . . . 958
9.11.5 Word Indexing External Documents . . . . . . . . . . . . . . . . . . . . . 961
9.11.6 Word Indexing Non-Progress Databases . . . . . . . . . . . . . . . . . 962
9.12 Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
9.12.1 Choosing Between Sequences and Control Tables . . . . . . . . . 963
9.12.2 Creating and Maintaining Sequences . . . . . . . . . . . . . . . . . . . . 967
9.12.3 Accessing and Incrementing Sequences . . . . . . . . . . . . . . . . . 968
Contents
ix
9.13 Database Trigger Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972
9.13.1 Storing Triggers in an Operating System Directory . . . . . . . . . 972
9.13.2 Storing Triggers in an R-code Library . . . . . . . . . . . . . . . . . . . 973
9.14 Using the RAW Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973
9.15 Multi-database Programming Techniques . . . . . . . . . . . . . . . . . . . . . . . 975
9.15.1 Referencing Tables and Fields . . . . . . . . . . . . . . . . . . . . . . . . 975
9.15.2 Positioning Database References in an Application . . . . . . . . 977
9.15.3 Using the LIKE option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
9.16 Creating Schema Cache Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
9.16.1 Building a Schema Cache File. . . . . . . . . . . . . . . . . . . . . . . . . 978
9.16.2 Example Schema Cache File Creation . . . . . . . . . . . . . . . . . . 980
9.16.3 Using a Schema Cache File . . . . . . . . . . . . . . . . . . . . . . . . . . 982
10. Using the Browse Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
10.1 Understanding Browse Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
10.2 Defining a Query for a Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
10.2.1 Using Field Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
10.2.2 Planning for the Size of the Data Set . . . . . . . . . . . . . . . . . . . . 104
10.3 Defining a Browse Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
10.3.1 Defining a Read-only Browse . . . . . . . . . . . . . . . . . . . . . . . . . 105
10.3.2 Defining an Updatable Browse . . . . . . . . . . . . . . . . . . . . . . . . 107
10.3.3 Defining a Single- or Multiple-select Browse . . . . . . . . . . . . . . 109
10.3.4 Using Calculated Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
10.3.5 Sizing a Browse and Browse Columns . . . . . . . . . . . . . . . . . . 1013
10.3.6 Searching Columns (Windows Only) . . . . . . . . . . . . . . . . . . . . 1015
10.4 Programming with a Browse Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
10.4.1 Browse Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
10.4.2 Refreshing Browse Rows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
10.4.3 Repositioning Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
10.4.4 Updating Browse Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
10.4.5 Creating Browse Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
10.4.6 Deleting Browse Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
10.4.7 Locking Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
10.4.8 Moving Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
10.4.9 Overlaying Widgets on Browse Cells. . . . . . . . . . . . . . . . . . . . 1034
10.4.10 Using Multiple Browse Widgets for Related Tables . . . . . . . . 1037
10.4.11 Browse Style Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
10.5 Resizable Browse Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040
10.5.1 Resizing the Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040
10.5.2 Moving the Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
10.5.3 Resizing the Browse-column . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
10.5.4 Moving the Browse-column . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042
10.5.5 Changing the Row Height . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
10.5.6 Additional Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
Contents
x
10.5.7 User Manipulation Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044
10.5.8 Code Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045
10.6 Using Browse Widgets in Character Interfaces . . . . . . . . . . . . . . . . . . . . 1046
10.6.1 Character Browse Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047
10.6.2 Control Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048
10.6.3 Functional Differences from the Windows Graphical Browse . 1052
11. Database Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
11.1 Database Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
11.2 Schema and Session Database Triggers . . . . . . . . . . . . . . . . . . . . . . . . 113
11.2.1 Differences Between Schema and Session Triggers . . . . . . . . 113
11.2.2 Trigger Interaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
11.2.3 Schema Triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
11.2.4 CREATE Schema Trigger Example . . . . . . . . . . . . . . . . . . . . . 117
11.2.5 DELETE Schema Trigger Example. . . . . . . . . . . . . . . . . . . . . . 117
11.2.6 ASSIGN Schema Trigger Example. . . . . . . . . . . . . . . . . . . . . . 118
11.2.7 REPLICATIONCREATE Schema Trigger Example . . . . . . . . 118
11.2.8 REPLICATIONDELETE Schema Trigger Example . . . . . . . . 119
11.2.9 REPLICATIONWRITE Schema Trigger Example. . . . . . . . . . 119
11.3 Implementing Trigger-based Replication . . . . . . . . . . . . . . . . . . . . . . . . . 1110
11.3.1 4GL Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
11.3.2 Data Dictionary Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111
11.3.3 Trigger-based Replication Procedure . . . . . . . . . . . . . . . . . . . . 1111
11.4 Detecting and Capturing Data Collision . . . . . . . . . . . . . . . . . . . . . . . . . 1117
11.4.1 Create a Collision Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117
11.4.2 Analyze the Log Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1118
11.4.3 Replication Process Configuration . . . . . . . . . . . . . . . . . . . . . . 1120
11.4.4 Session Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1121
11.4.5 FIND Session Trigger Example . . . . . . . . . . . . . . . . . . . . . . . . 1124
11.4.6 WRITE Session Trigger Example . . . . . . . . . . . . . . . . . . . . . . . 1124
11.5 General Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125
11.5.1 Metaschema Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125
11.5.2 User-interaction Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125
11.5.3 FIND NEXT and FIND PREV . . . . . . . . . . . . . . . . . . . . . . . . . . 1125
11.5.4 Triggers Execute Other Triggers . . . . . . . . . . . . . . . . . . . . . . . 1126
11.5.5 Triggers Can Start Transactions . . . . . . . . . . . . . . . . . . . . . . . . 1126
11.5.6 Default Error Phrase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
11.5.7 RETURN ERROR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
11.5.8 Where Triggers Execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
11.5.9 Storing Trigger Procedures in Libraries . . . . . . . . . . . . . . . . . . 1127
11.5.10 ESQL Access to Database Objects . . . . . . . . . . . . . . . . . . . . . 1127
11.5.11 Disabling Triggers for Dump/Load . . . . . . . . . . . . . . . . . . . . . . 1127
11.5.12 SQL Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
Contents
xi
12. Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
12.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
12.2 Transactions Defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
12.3 All-or-nothing Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
12.4 Understanding Where Transactions Begin and End . . . . . . . . . . . . . . . 128
12.5 How Much to Undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215
12.6 Controlling Where Transactions Begin and End . . . . . . . . . . . . . . . . . . 1218
12.6.1 Making Transactions Larger . . . . . . . . . . . . . . . . . . . . . . . . . . 1219
12.6.2 Making Transactions Smaller. . . . . . . . . . . . . . . . . . . . . . . . . . 1221
12.7 Transactions and Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223
12.8 Transactions and Subprocedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234
12.9 Transactions with File Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1236
12.10 Transactions and Program Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 1236
12.10.1 Transactions in Multi-database Applications . . . . . . . . . . . . . . 1239
12.10.2 Transactions in Distributed Applications . . . . . . . . . . . . . . . . . 1240
12.11 Determining When Transactions Are Active . . . . . . . . . . . . . . . . . . . . . 1240
12.12 Progress Transaction Mechanics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1241
12.12.1 Transaction Mechanics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1241
12.12.2 Subtransaction Mechanics. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1241
12.13 Efficient Transaction Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1242
13. Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
13.1 Applications in a Multi-user Environment . . . . . . . . . . . . . . . . . . . . . . . . 132
13.2 Sharing Database Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
13.2.1 Using Locks to Avoid Record Conflicts . . . . . . . . . . . . . . . . . . 134
13.2.2 How Progress Applies Locks . . . . . . . . . . . . . . . . . . . . . . . . . . 136
13.3 Bypassing Progress Lock Protections . . . . . . . . . . . . . . . . . . . . . . . . . . 138
13.4 How Long Does Progress Hold a Lock? . . . . . . . . . . . . . . . . . . . . . . . . 1310
13.4.1 Locks and Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1311
13.4.2 Locks and Multiple Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315
13.5 Resolving Locking Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1316
13.6 Managing Locks to Improve Concurrency . . . . . . . . . . . . . . . . . . . . . . . 1320
13.7 Changing the Size of a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1322
13.7.1 Making a Transaction Larger . . . . . . . . . . . . . . . . . . . . . . . . . . 1323
13.7.2 Making a Transaction Smaller . . . . . . . . . . . . . . . . . . . . . . . . . 1324
14. Providing Data Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
14.1 Progress User ID and Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
14.1.1 User ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
14.1.2 Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
14.2 Validating Progress User IDs and Passwords . . . . . . . . . . . . . . . . . . . . 143
14.3 Run-time Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
14.3.1 Checking for User IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
14.3.2 Defining Activities-based Security Checking . . . . . . . . . . . . . . 1410
Contents
xii
15. Work Tables and Temporary Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
15.1 Work Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
15.1.1 Characteristics of Work Tables . . . . . . . . . . . . . . . . . . . . . . . . . 152
15.1.2 Producing Categorized Reports . . . . . . . . . . . . . . . . . . . . . . . . 153
15.1.3 Using Work Tables to Collect and Manipulate Data . . . . . . . . . 157
15.1.4 Using Work Tables for Complex Sorting. . . . . . . . . . . . . . . . . . 159
15.1.5 Using Work Tables for Cross-tab Reports . . . . . . . . . . . . . . . . 1513
15.2 Temporary Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1515
15.2.1 Characteristics of Temporary Tables . . . . . . . . . . . . . . . . . . . . 1515
15.2.2 Defining a Temporary Table . . . . . . . . . . . . . . . . . . . . . . . . . . . 1516
15.2.3 Using Database, Temporary, and Work Tables . . . . . . . . . . . . 1516
15.2.4 Similarities Between Temporary and Work Tables . . . . . . . . . 1519
15.2.5 Differences Between Temporary and Work Tables . . . . . . . . . 1519
15.2.6 Defining Indexes for Temporary Tables . . . . . . . . . . . . . . . . . . 1522
15.2.7 Tailoring Temporary Table Visibility and Life Span . . . . . . . . . 1523
15.2.8 Temporary Tables As Parameters . . . . . . . . . . . . . . . . . . . . . . 1525
15.2.9 Temporary Table Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1527
15.3 Dynamic Temporary Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1529
15.3.1 Static and Dynamic Temp Tables . . . . . . . . . . . . . . . . . . . . . . . 1529
15.3.2 Creating a Dynamic Temptable. . . . . . . . . . . . . . . . . . . . . . . . 1529
15.3.3 Dynamic Buffers for Dynamic Temptables . . . . . . . . . . . . . . . 1533
15.3.4 Dynamic Temptables as Local and Remote Parameters . . . . 1535
15.3.5 Error Handling and Messages. . . . . . . . . . . . . . . . . . . . . . . . . . 1537
16. Widgets and Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
16.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
16.1.1 Widget Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
16.2 Static Versus Dynamic Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
16.2.1 Creating Widgets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
16.2.2 Using Widget Handles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
16.2.3 Static Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
16.2.4 Dynamic Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1612
16.3 Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615
16.3.1 Widget Handles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615
16.3.2 Procedure Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1616
16.3.3 Query, Buffer, and Buffer-field Handles . . . . . . . . . . . . . . . . . . 1616
16.3.4 Server Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1616
16.3.5 Component Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1616
16.3.6 Transaction Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1616
16.3.7 System Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617
16.3.8 Handle Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1619
16.4 Widget Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1620
16.4.1 Attribute References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1621
16.4.2 Referencing Attribute Values . . . . . . . . . . . . . . . . . . . . . . . . . . 1621
Contents
xiii
16.4.3 Setting Attribute Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1622
16.4.4 Attributes in Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1622
16.4.5 Attribute Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
16.5 Widget Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
16.5.1 Method References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
16.5.2 Invoking Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1624
16.5.3 Methods in Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1624
16.5.4 Method Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625
16.6 Widget Realization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1626
16.6.1 Becoming Realized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1626
16.6.2 Becoming Derealized. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629
16.7 Resizing Widgets Dynamically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630
16.8 User-interface Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1631
16.8.1 User-interface Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1631
16.8.2 Trigger Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634
16.8.3 Trigger Execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
16.8.4 Trigger Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
16.8.5 Reverting Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1639
16.8.6 Universal Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640
16.8.7 Applying Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642
17. Representing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
17.1 Using the VIEWAS Phrase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
17.1.1 Multiple Representations for a Single Value . . . . . . . . . . . . . . 172
17.1.2 A Values Default Representation . . . . . . . . . . . . . . . . . . . . . . 172
17.2 Fill-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
17.2.1 Format and Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
17.2.2 Fill-in Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
17.2.3 Fill-in Fonts on Windows in Graphical Interfaces. . . . . . . . . . . 176
17.3 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
17.4 Sliders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
17.4.1 Manipulating a Slider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1710
17.4.2 Range and Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1710
17.4.3 Example Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1712
17.5 Toggle Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1714
17.6 Radio Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1719
17.6.1 Defining a Radio Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1720
17.6.2 Example Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1721
17.7 Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724
17.7.1 Defining an Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724
17.7.2 Using an Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1726
17.7.3 Attributes and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727
17.7.4 Adding Functionality to an Editor . . . . . . . . . . . . . . . . . . . . . . . 1728
17.8 Selection Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730
Contents
xiv
17.8.1 Defining a Selection List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1731
17.8.2 Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1732
17.8.3 Character Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1732
17.8.4 Example Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1733
17.9 Combo Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1739
17.9.1 Defining a Combo Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740
17.9.2 Working with Combo Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . 1742
17.9.3 Example Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1743
17.10 Applying Formats When Displaying Widgets . . . . . . . . . . . . . . . . . . . . . 1749
17.10.1 Using the FORMAT Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
17.10.2 Character Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
17.10.3 Integer and Decimal Formats . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
17.10.4 Logical Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757
17.10.5 Date Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
18. Buttons, Images, and Rectangles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
18.1 Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
18.1.1 Button Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
18.1.2 Default Buttons in Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . 189
18.2 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
18.3 Rectangles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1815
19. Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
19.1 What Is a Frame? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
19.2 Why Progress Uses Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
19.3 Static and Dynamic Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
19.4 Frame Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
19.4.1 How Progress Allocates Frames. . . . . . . . . . . . . . . . . . . . . . . . 195
19.4.2 Default Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
19.4.3 Specifying Default Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
19.4.4 Controlling Frame Allocation. . . . . . . . . . . . . . . . . . . . . . . . . . . 199
19.4.5 The Procedure Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910
19.4.6 Block A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910
19.4.7 Block B . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910
19.4.8 Block C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910
19.5 Types of Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1911
19.6 Frame Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915
19.7 Triggers and Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1917
19.8 Frame Flashing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918
19.9 Frame Families . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1919
Contents
xv
19.9.1 Defining a Frame Family . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1922
19.9.2 Using Frame Families . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1922
19.10 Frame Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1926
19.10.1 Viewing and Hiding Frames . . . . . . . . . . . . . . . . . . . . . . . . . . 1927
19.10.2 Advancing and Clearing Frames . . . . . . . . . . . . . . . . . . . . . . . 1934
19.10.3 Retaining Data During Retry of a Block . . . . . . . . . . . . . . . . . . 1934
19.10.4 Creating Field-group Widgets . . . . . . . . . . . . . . . . . . . . . . . . . 1934
19.11 Using Shared Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1935
19.12 Field-group Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939
19.12.1 Field-group Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941
19.12.2 Field-group Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942
19.12.3 Field-group Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942
19.12.4 Field-group Position Relative to Frame . . . . . . . . . . . . . . . . . . 1943
19.12.5 Z order and Field Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1943
19.12.6 Field-group Visibility and Scrolling . . . . . . . . . . . . . . . . . . . . . . 1944
19.12.7 Accessing Field Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
19.13 Validation of User Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1949
19.13.1 Recommended Validation Techniques . . . . . . . . . . . . . . . . . . 1949
19.13.2 The Rules of Frame-based Validation . . . . . . . . . . . . . . . . . . . 1950
19.13.3 Forcing Frame-wide Validation . . . . . . . . . . . . . . . . . . . . . . . . 1950
19.13.4 Disabling Data Dictionary Validation on a Frame or Field . . . . 1954
20. Using Dynamic Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
20.1 Managing Dynamic Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
20.1.1 Static Versus Dynamic Widget Management. . . . . . . . . . . . . . 202
20.1.2 Setting Up Dynamic Field-level Widgets . . . . . . . . . . . . . . . . . 204
20.1.3 Setting Up Dynamic Frames . . . . . . . . . . . . . . . . . . . . . . . . . . 207
20.2 Managing Dynamic Widget Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
20.2.1 Named Widget Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2010
20.2.2 Unnamed Widget Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2014
20.3 Creating and Using Dynamic Queries . . . . . . . . . . . . . . . . . . . . . . . . . . 2015
20.3.1 Creating a Query Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2016
20.3.2 Using a Query Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017
20.3.3 The Buffer Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2018
20.3.4 The Buffer-field Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2020
20.3.5 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2022
20.3.6 Dynamic Query Code Example . . . . . . . . . . . . . . . . . . . . . . . . 2023
20.4 Creating and Using a Dynamic Browse . . . . . . . . . . . . . . . . . . . . . . . . . 2025
20.4.1 Creating the Dynamic Browse . . . . . . . . . . . . . . . . . . . . . . . . . 2026
20.4.2 Creating Dynamic Browse Columns . . . . . . . . . . . . . . . . . . . . 2027
20.4.3 Dynamic Enhancements to the Static Browse . . . . . . . . . . . . . 2030
21. Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
21.1 Multiple-window Pros and Cons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Contents
xvi
21.1.1 Windows Versus Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . 213
21.1.2 Multiple Windows and Transactions . . . . . . . . . . . . . . . . . . . . . 213
21.2 Window Attributes and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
21.3 Window Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
21.4 Creating and Managing Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
21.4.1 Creating Window Families . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
21.5 Window-based Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
21.5.1 Non-persistent Multi-window Management . . . . . . . . . . . . . . . 2115
21.5.2 Persistent Multi-window Management . . . . . . . . . . . . . . . . . . . 2116
22. Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
22.1 Menu Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
22.1.1 Menu Bar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
22.1.2 Pop-up Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
22.2 Menu Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
22.3 Features for Menu Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
22.4 Defining Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
22.4.1 Static Menu Bars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
22.4.2 Static Pop-up Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2211
22.5 Nested Submenus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2212
22.6 Enabling and Disabling Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2213
22.7 Menu Toggle Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2215
22.8 Duplicating Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2216
22.9 The MENUDROP Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2218
22.10 Menu Item Accelerators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2218
22.10.1 Defining Accelerators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2218
22.10.2 Accelerators in Character Interfaces . . . . . . . . . . . . . . . . . . . . 2220
22.11 Menu Mnemonics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2221
22.12 Dynamic Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2221
22.12.1 Properties of Dynamic Menus . . . . . . . . . . . . . . . . . . . . . . . . . . 2222
22.12.2 Dynamic Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2223
22.12.3 Querying Sibling Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2226
22.12.4 Example of a Dynamic Menu . . . . . . . . . . . . . . . . . . . . . . . . . . 2227
22.12.5 Dynamic Pop-up Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229
23. Colors and Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
23.1 Making Colors and Fonts Available to an Application . . . . . . . . . . . . . . . 232
23.1.1 Progress Default Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
23.1.2 Progress Default Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
23.1.3 Application Colors and Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . 234
23.2 Assigning Colors and Fonts to a Widget . . . . . . . . . . . . . . . . . . . . . . . . . 234
23.3 Assigning Colors and Fonts to ActiveX Automation Objects and ActiveX Controls
237
23.4 Color and Font Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Contents
xvii
23.5 Color in Character Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
23.5.1 Widget States and Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
23.5.2 Color Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
23.6 Colors on Windows in Graphical Interfaces . . . . . . . . . . . . . . . . . . . . . . 239
23.6.1 Systems with the Palette Manager . . . . . . . . . . . . . . . . . . . . . 239
23.6.2 Systems without the Palette Manager . . . . . . . . . . . . . . . . . . . 2310
23.7 Managing Colors and Fonts in Graphical Applications . . . . . . . . . . . . . 2310
23.8 Allowing the User to Change Colors and Fonts . . . . . . . . . . . . . . . . . . . 2311
23.8.1 Establishing Dynamic Colors . . . . . . . . . . . . . . . . . . . . . . . . . . 2311
23.8.2 Color Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312
23.8.3 Color Dialog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313
23.8.4 Saving a Modified Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2315
23.8.5 Font Dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2315
23.8.6 Font Dialog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2316
23.8.7 Saving a Modified Font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318
23.9 Accessing the Current Color and Font Tables . . . . . . . . . . . . . . . . . . . . 2318
23.9.1 COLORTABLE Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318
23.9.2 FONTTABLE Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2320
23.10 Retrieving and Changing Color and Font Definitions . . . . . . . . . . . . . . . 2321
23.10.1 Changing Resource Definitions . . . . . . . . . . . . . . . . . . . . . . . . 2321
23.10.2 Using GETKEYVALUE and PUTKEYVALUE . . . . . . . . . 2321
23.11 Managing Application Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . 2323
23.11.1 Understanding Environment Management. . . . . . . . . . . . . . . . 2323
23.11.2 Using Environment Management Statements . . . . . . . . . . . . . 2323
23.11.3 Managing Multiple Environments. . . . . . . . . . . . . . . . . . . . . . . 2324
23.12 Managing Color Display Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2326
24. Direct Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
24.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
24.2 Mouse Buttons on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
24.3 Selecting Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
24.3.1 Selecting by Pointing and Clicking. . . . . . . . . . . . . . . . . . . . . . 246
24.3.2 Box Selecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
24.3.3 Sets of Selected Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
24.4 Moving and Resizing Field-level Widgets . . . . . . . . . . . . . . . . . . . . . . . 248
24.5 Moving and Resizing Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2410
24.6 Custom Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2410
24.7 Interaction Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2411
24.8 Direct-manipulation Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2411
24.8.1 General Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2411
24.8.2 Order of Direct-manipulation Events . . . . . . . . . . . . . . . . . . . . 2415
24.9 Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2417
Contents
xviii
25. Interface Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
25.1 Progress Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
25.1.1 Character-based Environment . . . . . . . . . . . . . . . . . . . . . . . . . 252
25.1.2 Graphical Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
25.1.3 Alert Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
25.2 Frame Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
25.2.1 Using Frame Phrase Options . . . . . . . . . . . . . . . . . . . . . . . . . . 257
25.2.2 Setting Frame Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
25.2.3 Rules for Frame Phrases and Attributes . . . . . . . . . . . . . . . . . . 2511
25.3 Frame Design Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2511
25.3.1 Frame-level Design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2511
25.3.2 Field- and Variable-level Design . . . . . . . . . . . . . . . . . . . . . . . 2513
25.3.3 FORM and DEFINE FRAME Statements . . . . . . . . . . . . . . . . . 2513
25.3.4 FRAMEROW and FRAMECOL Options . . . . . . . . . . . . . . . . 2520
25.3.5 Positioning Frames with FRAMELINE . . . . . . . . . . . . . . . . . . 2524
25.3.6 Positioning Frames with FRAMEDOWN. . . . . . . . . . . . . . . . . 2525
25.3.7 Scrolling Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2527
25.3.8 Scrollable Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2532
25.3.9 Strip Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2534
25.3.10 Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2538
25.3.11 Frames for Nonterminal Devices . . . . . . . . . . . . . . . . . . . . . . . 2541
25.3.12 Multiple Active Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2541
25.4 Tab Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2543
25.4.1 Tab Order for a Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2543
25.4.2 Tab Order for a Frame Family. . . . . . . . . . . . . . . . . . . . . . . . . . 2544
25.4.3 Tabbing and DATAENTRYRETURN . . . . . . . . . . . . . . . . . . 2548
25.5 Active Window Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2549
25.6 Three-dimensional Effects (Windows only; Graphical interfaces only) . . 2549
25.6.1 THREED, Rectangles, and Images. . . . . . . . . . . . . . . . . . . . . 2551
25.6.2 THREED and Window Widgets . . . . . . . . . . . . . . . . . . . . . . . 2552
25.6.3 2D and 3D Widget Size Compatibility . . . . . . . . . . . . . . . . . . . . 2552
25.7 Windows Interface Design Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2552
25.7.1 Incorporating Tooltip Details . . . . . . . . . . . . . . . . . . . . . . . . . . . 2552
25.7.2 Accessing the Windows Help Engine . . . . . . . . . . . . . . . . . . . . 2553
25.7.3 Displaying the Small Icon Size . . . . . . . . . . . . . . . . . . . . . . . . . 2553
A. R-code Features and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A1
A.1 R-code Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A2
A.1.1 Factors that Affect R-code Size . . . . . . . . . . . . . . . . . . . . . . . . A3
A.1.2 R-code File Segment Layout . . . . . . . . . . . . . . . . . . . . . . . . . . A4
A.2 R-code Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A5
A.3 R-code Libraries and PROPATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A6
A.4 R-code Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A7
A.4.1 Standard R-code Execution Environment . . . . . . . . . . . . . . . . A7
Contents
xix
A.4.2 Memory-mapped R-code Execution Environment . . . . . . . . . A11
A.4.3 R-code Directory Management . . . . . . . . . . . . . . . . . . . . . . . . A13
A.4.4 R-code Execution Environment Statistics . . . . . . . . . . . . . . . . A14
A.5 R-code Portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A17
A.6 Code Page Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A18
A.7 Database CRCs and Time Stamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . A18
A.7.1 Time Stamp Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A19
A.7.2 CRC Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A19
A.7.3 CRC Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A20
A.7.4 CRC Versus Time Stamp Validation . . . . . . . . . . . . . . . . . . . . A21
A.8 R-code CRCs and Procedure Integrity . . . . . . . . . . . . . . . . . . . . . . . . . . A24
A.8.1 Assigning CRCs to Schema Triggers . . . . . . . . . . . . . . . . . . . A24
A.8.2 Validating CRCs for Schema Triggers . . . . . . . . . . . . . . . . . . A25
A.8.3 RCODEINFO Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A25
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index1
Contents
xx
Figures
Figure 11: Measures of 4GL Efficiency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Figure 21: A Procedure-driven Application Calling the Operating System . . . . . . . 23
Figure 22: Flow of Execution in a Procedure-driven Program . . . . . . . . . . . . . . . . 24
Figure 23: The Operating System Interacting with an Event-driven Application . . 25
Figure 24: Flow of Control in an Event-driven Program . . . . . . . . . . . . . . . . . . . . . 26
Figure 31: Procedure Call Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Figure 32: Object Sharing Among External Procedures . . . . . . . . . . . . . . . . . . . . 326
Figure 61: Key Labels, Key Codes, and Key Functions . . . . . . . . . . . . . . . . . . . . . 62
Figure 62: Progress Key Translation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Figure 63: Key Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Figure 64: The p-gon1.p Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
Figure 71: The Unnamed Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Figure 72: Redirecting the Unnamed Output Stream . . . . . . . . . . . . . . . . . . . . . . . 73
Figure 73: Multiple Output Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Figure 74: The OUTPUT CLOSE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Figure 75: Redirecting the Unnamed Input Stream . . . . . . . . . . . . . . . . . . . . . . . . 715
Figure 76: Multiple Input Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Figure 77: Multiple Output Streams Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
Figure 78: How QUOTER Prepares a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
Figure 79: Extracting QUOTER Input with SUBSTRING . . . . . . . . . . . . . . . . . . . . 735
Figure 81: Name Scoping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Figure 91: Data Movement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917
Figure 92: The Primary Data-handling Statements . . . . . . . . . . . . . . . . . . . . . . . . 918
Figure 93: Inner Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
Figure 94: Left Outer Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
Figure 95: Inner Join Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944
Figure 96: Left Outer Join Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946
Figure 97: Database Fields and Sequences Comparison . . . . . . . . . . . . . . . . . . . 963
Figure 98: Sequences and Overlapping Transactions . . . . . . . . . . . . . . . . . . . . . . 966
Figure 99: Positioning Database References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977
Figure 101: Resizable Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1046
Figure 102: Character Browse in Row Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047
Figure 103: Character Browse in Edit Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048
Figure 111: Cascading Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1116
Figure 112: Example Replication Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1120
Figure 121: Transaction Undo Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Figure 122: Transaction Involving Two Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Figure 123: The Transaction Block for the p-txn11.p Procedure . . . . . . . . . . . . . . . 1235
Figure 131: Multi-user Update Scenario Without Locks . . . . . . . . . . . . . . . . . . . . . . 132
Figure 132: Multi-user Update Scenario with Locks . . . . . . . . . . . . . . . . . . . . . . . . . 134
Figure 133: How Progress Applies Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Figure 134: Locks and Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1311
Figure 135: Transaction Size and Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1322
Contents
xxi
Figure 136: Making Transactions Larger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323
Figure 137: Making Transactions Smaller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325
Figure 141: Sample Activity Permissions Entries . . . . . . . . . . . . . . . . . . . . . . . . . . 1411
Figure 142: User with Permission to Run a Procedure . . . . . . . . . . . . . . . . . . . . . . 1412
Figure 143: User Without Permission to Run a Procedure . . . . . . . . . . . . . . . . . . . 1413
Figure 144: Sample Security Record for Activity Permissions . . . . . . . . . . . . . . . . 1416
Figure 145: Summary of Run-time Security Process . . . . . . . . . . . . . . . . . . . . . . . 1418
Figure 151: Processing a Table for a Categorized Report . . . . . . . . . . . . . . . . . . . 154
Figure 152: Using Work Tables to Produce a Categorized Report . . . . . . . . . . . . . 156
Figure 153: Maintaining Work Tables in Sorted Order . . . . . . . . . . . . . . . . . . . . . . 1511
Figure 154: Comparing Two Sorting Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512
Figure 161: User-interface Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Figure 162: A Widget Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Figure 191: Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Figure 192: Frame Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Figure 193: Controlling Frame Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Figure 194: Types of Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1911
Figure 195: Frame Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915
Figure 196: Frame Family (Windows Graphical Interface) . . . . . . . . . . . . . . . . . . . 1920
Figure 197: Frame Family (Character Interface) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1921
Figure 198: Frame Family Viewing Demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1933
Figure 199: Shared Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1935
Figure 1910: Field-Group Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941
Figure 211: Window Family . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2113
Figure 221: Window with a Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Figure 222: Button with a Pop-up Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Figure 223: Menu Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Figure 231: Windows Color Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312
Figure 232: Windows Font Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2315
Figure 233: Changing Font 11 to Bold 8-Point Arial . . . . . . . . . . . . . . . . . . . . . . . . 2317
Figure 241: Highlight Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Figure 242: Selection Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Figure 243: Drag Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Figure 244: Resize Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Figure 245: Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2417
Figure 246: Grid Enlargement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2417
Figure 251: Character-based Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Figure 252: Frame Family Tab Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2546
Figure A1: R-code File Segment Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A5
Figure A2: Standard R-code Execution Environment . . . . . . . . . . . . . . . . . . . . . . A8
Figure A3: Memory-mapped R-code Execution Environment . . . . . . . . . . . . . . . . A12
Figure A4: Progress Client Startup Options for yd . . . . . . . . . . . . . . . . . . . . . . . A14
Figure A5: Execution Buffer Map for yd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A15
Figure A6: Accessing the Session Sort File for yd . . . . . . . . . . . . . . . . . . . . . . . A15
Figure A7: Procedure Segment Information for yd (Part 1) . . . . . . . . . . . . . . . . . A16
Contents
xxii
Figure A8: Procedure Segment Information for yd (Part 2) . . . . . . . . . . . . . . . . . A17
Contents
xxiii
Tables
Table 31: Block Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Table 32: Starting Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Table 33: Search Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Table 51: Progress Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Table 61: Progress Key Input Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Table 62: Key Codes and Key Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Table 63: Alternate Key Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
Table 64: Progress Key Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
Table 65: Actions You Assign to Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626
Table 66: Mouse Buttons on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
Table 71: Printing Options for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
Table 72: Using Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
Table 73: Quoter Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
Table 81: Preprocessor Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Table 82: Preprocessor Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Table 83: Functions Allowed in Preprocessor Expressions . . . . . . . . . . . . . . . . . 89
Table 84: Built-in Preprocessor Name References . . . . . . . . . . . . . . . . . . . . . . . 814
Table 91: Connection Failure Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Table 92: Progress Database Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Table 93: Record Fetching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
Table 94: Results Lists for Specific Query Types . . . . . . . . . . . . . . . . . . . . . . . . 927
Table 95: Is the Dot a Word Delimiter? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
Table 96: Word Delimiter Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
Table 97: Comparison of Sequences and Control Tables . . . . . . . . . . . . . . . . . . 965
Table 98: Sequence Statements and Functions . . . . . . . . . . . . . . . . . . . . . . . . . 968
Table 101: Browse and Query Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
Table 102: Row Mode Control Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1049
Table 103: Edit Mode Control Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
Table 111: Replication 4GL Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
Table 112: Replication Changes Log Table Schema . . . . . . . . . . . . . . . . . . . . . . . 1112
Table 113: Collision Log Table Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1118
Table 121: Starting Transactions and Subtransactions . . . . . . . . . . . . . . . . . . . . . 1217
Table 131: When Progress Releases Record Locks . . . . . . . . . . . . . . . . . . . . . . . 1313
Table 141: Values to Use for ID Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Table 151: Database, Temporary, and Work Tables . . . . . . . . . . . . . . . . . . . . . . . 1517
Table 152: Temporary Table Options, Visibility, and Life Span . . . . . . . . . . . . . . . 1524
Table 153: Identifying Sender and Receiver Parameters . . . . . . . . . . . . . . . . . . . 1526
Table 161: System Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617
Table 162: Realizing Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1626
Table 163: Derealizing Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629
Table 164: Mouse Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632
Table 165: Other Progress Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1633
Table 166: Trigger Scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
Contents
xxiv
Table 171: Default Display Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
Table 172: Character Display Format Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
Table 173: Numeric Display Format Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755
Table 174: Logical Display Format Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757
Table 175: Date Display Format Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
Table 181: Using NOFILL and Color with Rectangles . . . . . . . . . . . . . . . . . . . . . 1815
Table 191: Determining Frame Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912
Table 201: Static Versus Dynamic Widget Management . . . . . . . . . . . . . . . . . . . . 202
Table 231: Progress Default Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Table 232: Colors Used in Character Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Table 241: Direct-manipulation Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Table 242: Direct-manipulation Mouse Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Table 251: Maximized Window Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Table 252: Frame Border Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Table A1: R-code Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A2
Table A2: Metaschema Fields in CRC Calculation . . . . . . . . . . . . . . . . . . . . . . . . A20
Contents
xxv
Examples
p-hello1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
p-hello2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
p-blocks.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
p-block1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
p-clock1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
p-ctrt0.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
p-ctrt1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
p-ctrt2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
p-procd.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
p-eventd.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
p-bkchp.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
p-bkchp2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
p-bkchp3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
p-bkchp4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
p-bkchp5.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
p-bkchp6.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
p-bkchp7.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
p-borfrm.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
p-strscp.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
p-stscp2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
p-wkscp.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
p-wkscp1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
p-wkscp2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
p-wkspc3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
p-wkstr.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
p-frref1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
p-frref2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
p-bkchpa.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
p-exprc1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
p-exprc2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
p-share1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
p-share2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
p-share3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
p-intprc.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
p-inprc1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
p-exprc3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
p-persp1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
p-persp2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
p-udf1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
p-udf2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
p-udfdef.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
p-udf3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
p-pomain.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Contents
xxvi
p-podrvr.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
p-posupr.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
pnedrvr.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
pnepub.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
pnesub1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
pnesub2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
pitundo.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
pitund2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
perrst2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
p-error.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
p-txn6.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
p-error2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
p-error3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
ptxn7.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
p-txn8.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
pimpeof.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
ptxn9.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
pstop.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
perror4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
p-error4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
perror5.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
pretstr.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
pretval.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
p-action.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
p-intro.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
p-gon1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
p-keys.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
p-gon2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
p-kystka.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
p-kystkb.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
p-kystk.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
p-kystk2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639
p-kystk3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
p-kystk4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
p-io.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
p-iop2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
p-wgetls.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
p-wchpr.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
p-chgot2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
p-out.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
_osprint.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
p-datf1.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
p-chgin.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
p-io3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
p-chgin2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Contents
xxvii
p-dfstr.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
p-sstrm.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
p-dispho.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
p-osdir.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
p-osfile.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
p-codpag.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
p-datf1.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
p-datf12.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
p-datf12.q . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
p-datf13.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734
p-chgin3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734
p-datf13.q . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734
p-datf14.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
p-chgin4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
p-datf14.q . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
p-datf15.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
p-chgin5.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
p-export.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
p-datf16.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
p-exprt2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
p-datf17.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
p-putdat.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
p-datf18.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
p-import.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
p-imprt2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
p-datf12.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
p-impun1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
p-datf13.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
p-impun2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
p-datf14.d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
p-impun3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
main.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
include.i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
p-proc.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
p-incl.i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
p-main.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
p-inclde.i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
p-editrc.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819
p-editrc.i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820
p-cust.f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
parm3.pf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
topproc.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
subproc.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
p-infor.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
mainprc1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910
Contents
xxviii
subproc1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910
subproc2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910
alias1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913
alias2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
dispcust.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
main2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
makebuf.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
disp.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
p-fldls1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934
p-rldls2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934
p-join1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944
p-join2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945
p-mainproc.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977
db1proc.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977
db2proc.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977
p-schcs1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
p-schcs2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
p-br01.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
p-br02.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
p-br03.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010
p-br04.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
p-br05.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014
p-br06.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
p-br07.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021
p-br08.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
p-br09.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028
p-br11.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
p-br12.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
p-br13.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
p-br14.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035
p-br15.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037
p-rszbrw.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045
crcust.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
p-dltcst.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
p-ascust.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
p-sestrg.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1124
p-trans.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
p-txn1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
p-txn2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
p-txn3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
p-check.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213
p-check2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214
p-txn3a.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215
p-txn5.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215
p-txn3a.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219
Contents
xxix
p-txn4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219
p-check.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
p-txn10.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
p-check.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1222
p-txn12.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223
p-txn13.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1225
p-txn14.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1229
p-txn11.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234
p-txn11a.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234
p-var.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1236
p-tnchp.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1238
p-nord2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1240
p-lock1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
p-lock2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
p-lock3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
p-lock6.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
p-lock7.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
p-lock4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1311
p-lock12.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315
p-lock4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1316
p-lock5.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1316
p-lock6.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1319
p-lock13.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1321
p-txn3a.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1322
p-txn4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323
p-txn10.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325
_login.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
p-passts.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
p-csmnu3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
p-adcus2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
p-adcust.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
p-adcus3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
p-prmsn.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411
p-adcus4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1414
p-delcs2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1414
p-itlst2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415
p-rept6.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415
p-chkprm.i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416
p-secadm.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417
p-secupd.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417
p-wrk1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
p-wrk2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
p-wrk3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
p-wrk4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1510
p-wrk3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512
Contents
xxx
p-wrk4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512
p-wrk5.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1514
p-ttnodb.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1521
p-tmptbl.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1528
p-ttdyn2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1534
p-passdb.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1536
p-getdb.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537
p-dybuts.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1614
p-method.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625
p-trig1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634
p-says.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1635
p-pers1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1638
p-rev.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640
p-utrig.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641
p-apply.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642
p-repos3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1643
p-fillin.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
p-slider.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1712
p-tbox.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715
p-tbox2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1718
p-radio1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1721
p-radio2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1722
p-edit.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725
p-edit2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1728
p-sel1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1733
p-sel2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1736
p-combo1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1743
p-combo2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746
p-ftchp2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
p-but1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
p-arrows.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
p-but2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
p-ldimg.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812
p-frm1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
p-frm2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
p-frm3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
p-frm4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
p-form.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
p-deffrm.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
p-frm5.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
p-frm6.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1911
p-frm7.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913
p-frm8.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913
p-frm9.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1914
p-frm10.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1916
Contents
xxxi
p-frm11.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1916
p-frm12.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1917
p-frm13.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918
p-frm14.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918
p-frmwin.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1919
p-fof1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1922
p-fof2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1924
p-form1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1927
p-form2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1928
p-hide.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1928
p-ovrlay.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1930
p-dicust.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1935
p-updord.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1935
p-dicust.i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1935
p-dicust.i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1936
p-dicust.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1937
p-updord.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1938
p-frmval.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1953
p-dynfl1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
p-dynfrm.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
p-dybut2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011
p-dybut3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012
p-unname.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2015
p-qryob1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2019
p-qryob2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2021
p-fnlqry.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2023
p-dybrw1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2027
p-dybrw2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2028
p-dybrw3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2029
p-stbrw1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2031
p-wina.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
p-wow1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2111
p-win1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2115
p-perwn1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2117
p-perwn2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2120
p-perwn3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2126
p-bar.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
p-popup.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2211
p-menu.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2214
p-popup2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2217
p-dymenu.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2227
p-dypop.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229
p-clrfnt.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
p-cdial1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313
p-fdial1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2316
Contents
xxxii
p-dirman.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
p-manual.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2410
p-wbars.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
p-frm15.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
p-frm16.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
p-frm17.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2511
p-form4.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2515
p-frm19.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2517
p-form3.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2517
p-back.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2519
p-frrow.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2521
p-frrow1.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2522
p-frrow2.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2523
p-frline.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2524
p-frdown.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2525
p-scroll.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2527
p-scrlab.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2532
p-strip.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2534
p-chsmnu.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2536
p-diagbx.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2539
p-frm18.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2542
p-foftab.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2547
p-threed.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2550
p-trload.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A27
Preface
Purpose
This book provides the 4GL programmer with in-depth information about various programming
topics for the Progress 4GL. Use it along with the Progress Language Reference as a
comprehensive guide and reference to programming with Progress. For information on
Progress/SQL, see the Progress Embedded SQL-89 Guide and Reference.
Audience
This book is intended for Progress developers and anyone who needs to read and understand
Progress code. The reader should have the basic knowledge of Progress provided by the
Progress Language Tutorial for Windows and Progress Language Tutorial for Character.
Organization of This Manual
This manual consists of two volumes, Volume 1 and Volume 2. The contents of each volume is
as follows:
Volume 1
Chapter 1, Introducing the Progress 4GL
Progress is a flexible and complete 4GL. This chapter describes the foundations and
essential features of the Progress 4GL, and introduces its basic syntax and semantics.
Chapter 2, Programming Models
Progress Programming Handbook
xxxiv
The Progress 4GL supports two basic programming models: the procedure-driven model
and the event-driven model. This chapter describes each model, explains their differences,
and suggests how to choose one or a mixture of these models for your application
development.
Chapter 3, Block Properties
Progress is a block-structured language. This chapter describes the types of blocks
Progress supports and the properties of each. This includes a description of the techniques
for data and functional encapsulation in the 4GL. This chapter also describes user-defined
functions and procedure overriding.
Chapter 4, Named Events
Describes how to use Progress named events, and how Progress procedures can create,
subscribe to, and unsubscribe to them.
Chapter 5, Condition Handling and Messages
Describes how Progress handles unusual conditions such as errors and application
termination. This chapter also discusses Progress messages.
Chapter 6, Handling User Input
Describes how Progress handles input from the keyboard and the mouse. This chapter
includes examples of how you can monitor data entry from the user.
Chapter 7, Alternate I/O Sources
Describes how your Progress application can handle I/O to and from operating system files
and special devices.
Chapter 8, The Preprocessor
Describes the features and capabilities of the Progress preprocessor, a tool for conditional
4GL compilation.
Chapter 9, Database Access
Describes the Progress 4GL statements that allow you to read and write data in a database.
This chapter also describes techniques for browsing database data on a display.
Chapter 10, Using the Browse Widget
Describes how to design and interact with browse widgets and the queries they represent.
Preface
xxxv
Chapter 11, Database Triggers
Describes how you can provide blocks of code, in the database or in your application, that
execute when specific database events occur.
Chapter 12, Transactions
Describes statements and techniques that Progress provides to manage updates to a
database, including the ability to undo and retry updates in a reliable sequence.
Volume 2
Chapter 13, Locks
Describes how Progress uses record locks to manage multi-user access to a database.
Chapter 14, Providing Data Security
Surveys the types of security that Progress supports. This chapter focuses specifically on
how you can provide run-time security within an application.
Chapter 15, Work Tables and Temporary Tables
Describes two types of memory-resident table structures you can use within a Progress
application to temporarily store data.
Chapter 16, Widgets and Handles
Surveys the types of user-interface components (widgets) and system objects that Progress
supports, and the 4GL techniques for interacting with them, including attributes, methods,
and user-interface triggers.
Chapter 17, Representing Data
Describes the widgets that you can use to represent data for variables and database fields:
fill-ins, text, editors, sliders, toggle boxes, radio sets, selection lists, and combo boxes.
This chapter also describes Progress display formats.
Chapter 18, Buttons, Images, and Rectangles
Describes how to use push button, image, and rectangle widgets in your applications.
xxxvi
Chapter 19, Frames
Describes how Progress manages frame widgets and how you can interact with frames and
frame families in your applications.
Chapter 20, Using Dynamic Widgets
Describes dynamic (run-time defined) widgets and compares the 4GL techniques for
managing static (compile-time defined) and dynamic widgets. This chapter explains how
to include dynamic widgets in your application and manage groups of dynamic widgets
using widget pools.
Chapter 21, Windows
Describes how Progress provides windows to an application and how you can manage
windows and window families with the 4GL. This chapter includes basic examples of
typical multi-window applications.
Chapter 22, Menus
Describes how you can use menu bars, pull-down menus, and pop-up menus in your
applications.
Chapter 23, Colors and Fonts
Surveys Progress support for colors and fonts, including the techniques for modifying
colors and fonts within an application.
Chapter 24, Direct Manipulation
Describes how to make widgets selectable, movable, and resizable.
Chapter 25, Interface Design
Surveys the techniques for laying out and managing widgets within a frame or window.
Appendix A, R-code Features and Functions
Describes the structure and management of Progress r-code, the executable code into
which Progress compiles 4GL procedures. This appendix also describes techniques for
tuning r-code size and performance, and the use of time stamps and cyclic redundancy
checks (CRCs) to maintain r-code and database integrity.
Preface
xxxvii
How to Use This Manual
The two volumes of this manual treat programming topics in depth. For information on basic
Progress 4GL concepts and how to start programming in Progress, see the Progress Language
Tutorial for Windows and Progress Language Tutorial for Character for your user-interface
environment. For information on the standard tools for developing Progress applications, see
the Progress Basic Development Tools manual.
This manual treats programming topics in depth. For information on basic Progress 4GL
concepts and how to start programming in Progress, see the Progress Language Tutorial for
Windows and Progress Language Tutorial for Character for your user-interface environment.
For information on the standard tools for developing Progress applications, see the Progress
Basic Development Tools manual.
WebSpeed Considerations
If you are reading this manual to learn more about SpeedScript programming, note that the
following chapters and sections do not apply to developing WebSpeed applications:
Volume 1
Chapter 1, Introducing the Progress 4GL: The Compile-time Versus Run-time Execution
section does not apply.
Chapter 3, Block Properties: The EDITING Blocks section does not apply.
Chapter 5, Condition Handling and Messages: Only the Progress Conditions, Rules About
UNDO, The ERROR Condition, and The STOP Condition sections apply.
Chapter 6, Handling User Input
Chapter 7, Alternate I/O Sources: Only the Understanding Input and Output, Changing the
Output Destination, (Output to Files or Devices and Stream I/O vs. Screen I/O),
Changing a Procedures Input Source (Reading Input with Control Characters), Defining
Additional Input/Output Streams, Sharing Streams Among Procedures, and Summary of
Opening and Closing Streams sections apply.
Chapter 10, Using the Browse Widget
Volume 2
Chapter 16, Widgets and Handles: Only the material on system handles, attributes, and
methods applies. See Pocket WebSpeed for a list of SpeedScript elements.
Chapter 17, Representing Data
Chapter 18, Buttons, Images, and Rectangles
Chapter 19, Frames
xxxviii
Chapter 20, Using Dynamic Widgets
Chapter 21, Windows
Chapter 22, Menus
Chapter 23, Colors and Fonts
Chapter 24, Direct Manipulation
Chapter 25, Interface Design
Typographical Conventions
This manual uses the following typographical conventions:
Bold typeface indicates:
Commands or characters that the user types
That a word carries particular weight or emphasis
Italic typeface indicates:
Progress variable information that the user supplies
New terms
Titles of complete publications
Monospaced typeface indicates:
Code examples
System output
Operating system filenames and pathnames
The following typographical conventions are used to represent keystrokes:
Small capitals are used for Progress key functions and generic keyboard keys.
ENDERROR, GET, GO
ALT, CTRL, SPACEBAR, TAB
Preface
xxxix
When you have to press a combination of keys, they are joined by a dash. You press and
hold down the first key, then press the second key.
CTRLX
When you have to press and release one key, then press another key, the key names are
separated with a space.
ESCAPE H
ESCAPE CURSORLEFT
Syntax Notation
The syntax for each component follows a set of conventions:
Uppercase words are keywords. Although they are always shown in uppercase, you can
use either uppercase or lowercase when using them in a procedure.
In this example, ACCUM is a keyword:
Italics identify options or arguments that you must supply. These options can be defined
as part of the syntax or in a separate syntax identified by the name in italics. In the
ACCUM function above, the aggregate and expression options are defined with the
syntax for the ACCUM function in the Progress Language Reference.
You must end all statements (except for DO, FOR, FUNCTION, PROCEDURE, and
REPEAT) with a period. DO, FOR, FUNCTION, PROCEDURE, and REPEAT
statements can end with either a period or a colon, as in this example:
SYNTAX
ACCUM aggregate expression
FOR EACH Customer:
DISPLAY Name.
END.
xl
Square brackets ([ ] ) around an item indicate that the item, or a choice of one of the
enclosed items, is optional.
In this example, STREAM stream, UNLESSHIDDEN, and NOERROR are optional:
In some instances, square brackets are not a syntax notation, but part of the language.
For example, this syntax for the INITIAL option uses brackets to bound an initial value
list for an array variable definition. In these cases, normal text brackets ( [ ] ) are used:
NOTE: The ellipsis (...) indicates repetition, as shown in a following description.
Braces ({ }) around an item indicate that the item, or a choice of one of the enclosed
items, is required.
In this example, you must specify the items BY and expression and can optionally specify
the item DESCENDING, in that order:
In some cases, braces are not a syntax notation, but part of the language.
For example, a called external procedure must use braces when referencing arguments
passed by a calling procedure. In these cases, normal text braces ( { } ) are used:
SYNTAX
DISPLAY [ STREAM stream ] [ UNLESS-HIDDEN ] [ NO-ERROR ]
SYNTAX
INITIAL [ constant [ , constant ] ... ]
SYNTAX
{ BY expression [ DESCENDING ] }
SYNTAX
{ &argument-name }
Preface
xli
A vertical bar (|) indicates a choice.
In this example, EACH, FIRST, and LAST are optional, but you can only choose one:
In this example, you must select one of logicalname or alias:
Ellipses (...) indicate that you can choose one or more of the preceding items. If a group
of items is enclosed in braces and followed by ellipses, you must choose one or more of
those items. If a group of items is enclosed in brackets and followed by ellipses, you can
optionally choose one or more of those items.
In this example, you must include two expressions, but you can optionally include more.
Note that each subsequent expression must be preceded by a comma:
In this example, you must specify MESSAGE, then at least one of expression or SKIP, but
any additional number of expression or SKIP is allowed:
SYNTAX
PRESELECT [ EACH | FIRST | LAST ] record-phrase
SYNTAX
CONNECTED ( { logical-name | alias } )
SYNTAX
MAXIMUM ( expression , expression [ , expression ] ... )
SYNTAX
MESSAGE { expression | SKIP [ (n) ] } ...
xlii
In this example, you must specify {includefile, then optionally any number of argument
or &argumentname = argumentvalue, and then terminate with }:
In some examples, the syntax is too long to place in one horizontal row. In such cases,
optional items appear individually bracketed in multiple rows in order, left-to-right and
top-to-bottom. This order generally applies, unless otherwise specified. Required items
also appear on multiple rows in the required order, left-to-right and top-to-bottom. In cases
where grouping and order might otherwise be ambiguous, braced (required) or bracketed
(optional) groups clarify the groupings.
In this example, WITH is followed by several optional items:
In this example, ASSIGN requires one of two choices: either one or more of field, or one
of record. Other options available with either field or record are grouped with braces and
brackets. The open and close braces indicate the required order of options:
SYNTAX
{ include-file
[ argument | &argument-name = "argument-value" ] ... }
SYNTAX
WITH [ ACCUM max-length ] [ expression DOWN ]
[ CENTERED ] [ n COLUMNS ] [ SIDE-LABELS ]
[ STREAM-IO ]
SYNTAX
ASSIGN { { [ FRAME frame ]
{ field [ = expression ] }
[ WHEN expression ]
} ...
| { record [ EXCEPT field ... ] }
}
Preface
xliii
Example Procedures
This manual provides numerous example procedures that illustrate syntax and concepts.
Examples use the following conventions:
They appear in boxes with borders.
If they are available online, the name of the procedure appears above the left corner of the
box and starts with a prefix associated with the manual that references it, as follows:
e- Progress External Program Interfaces, for example, e-ddeex1.p
lt- Progress Language Tutorial for Windows, for example, lt-05-s3.p
p- Progress Programming Handbook, for example, p-br01.p
r- Progress Language Reference, for example, r-dynbut.p
If the name does not start with a listed prefix, the procedure is not available online.
If they are not available online, they compile as shown, but might not execute for lack of
completeness.
Accessing Files in Procedure Libraries on Windows Platforms
Documentation examples are stored in procedure libraries, prodoc.pl and prohelp.pl, in the
src directory where Progress is installed.
You must first create all subdirectories required by a library before attempting to extract files
from the library. You can see what directories and subdirectories a library needs by using the
PROLIB list command to view the contents of the library. See the Progress Client Deployment
Guide for more details on the PROLIB utility.
Extracting source files from a procedure library involves running PROENV to set up your
Progress environment, creating the directory structure for the files you want to extract, and
running PROLIB.
xliv
Extracting Source Files from Procedure Libraries on Windows Platforms
1 From the Control Panel or the Progress Program Group, double-click the Proenv icon.
2 The Proenv Window appears, with the proenv prompt.
Running Proenv sets the DLC environment variable to the directory where you installed
Progress (by default, C:\Program Files\Progress). Proenv also adds the DLC
environment variable to your PATH environment variable and adds the bin directory
(PATH=%DLC%;%DLC%\bin;%PATH%).
3 Enter the following command at the proenv prompt to create the prodoc directory in your
Progress working directory (by default, C:\Progress\Wrk):
4 Create the langref directory under prodoc:
5 To extract all examples in a procedure library directory, run the PROLIB utility. Note that
you must use double quotes because Program Files contains an embedded space:
PROLIB extracts all examples into prodoc\langref.
To extract one example, run PROLIB and specify the file that you want to extract as it is
stored in the procedure library:
PROLIB extracts r-syshlp.p into prodoc\langref.
MKDIR prodoc
MKDIR prodoc\langref
PROLIB "%DLC%\src\prodoc.pl" -extract prodoc\langref\*.*
PROLIB "%DLC%\src\prodoc.pl" -extract prodoc/langref/r-syshlp.p
Preface
xlv
Extracting Source Files from Procedure Libraries on UNIX Platforms
To extract p-wrk1.p from prodoc.pl, a procedure library, follow these steps at the UNIX
system prompt:
1 Run the PROENV utility:
Running proenv sets the DLC environment variable to the directory where you installed
Progress (by default, /usr/dlc). The proenv utility also adds the DLC environment
variable to your PATH environment variable and adds the bin directory
(PATH=%DLC%;%DLC%\bin;%PATH%).
2 At the proenv prompt, create the prodoc directory in your Progress working directory:
3 Create the proghand directory under prodoc:
4 To extract all examples in a procedure library directory, run the PROLIB utility:
PROLIB extracts all examples into prodoc\langref.
To extract one example, run PROLIB and specify the file that you want to extract as it is
stored in the procedure library:
PROLIB extracts p-wrk-1.p into prodoc/proghand.
install-dir/dlc/bin/proenv
mkdir prodoc
mkdir prodoc/proghand
prolib $DLC/src/prodoc.pl -extract prodoc/proghand/*.*
prolib $DLC/src/prodoc.pl -extract prodoc/proghand/p-wrk-1.p
xlvi
Progress Messages
Progress displays several types of messages to inform you of routine and unusual occurrences:
Execution messages inform you of errors encountered while Progress is running a
procedure (for example, if Progress cannot find a record with a specified index field
value).
Compile messages inform you of errors found while Progress is reading and analyzing a
procedure prior to running it (for example, if a procedure references a table name that is
not defined in the database).
Startup messages inform you of unusual conditions detected while Progress is getting
ready to execute (for example, if you entered an invalid startup parameter).
After displaying a message, Progress proceeds in one of several ways:
Continues execution, subject to the error-processing actions that you specify, or that are
assumed, as part of the procedure. This is the most common action taken following
execution messages.
Returns to the Progress Procedure Editor so that you can correct an error in a procedure.
This is the usual action taken following compiler messages.
Halts processing of a procedure and returns immediately to the Procedure Editor. This
does not happen often.
Terminates the current session.
Progress messages end with a message number in parentheses. In this example, the message
number is 200:
** Unknown table name table. (200)
Preface
xlvii
Use Progress online help to get more information about Progress messages. On the Windows
platform, many Progress tools include the following Help menu options to provide information
about messages:
Choose HelpRecent Messages to display detailed descriptions of the most recent
Progress message and all other messages returned in the current session.
Choose HelpMessages, then enter the message number to display a description of any
Progress message. (If you encounter an error that terminates Progress, make a note of the
message number before restarting.)
In the Procedure Editor, press the HELP key (F2 or CTRLW).
On the UNIX platform, you can use the Progress PRO command to start a single-user mode
character Progress client session and view a brief description of a message by providing its
number. Follow these steps:
1 Start the Progress Procedure Editor:
2 Press F3 to access the menu bar, then choose HelpMessages.
3 Type the message number, and press ENTER. Details about that message number appear.
4 Press F4 to close the message, press F3 to access the Procedure Editor menu, and choose
FileExit.
Other Useful Documentation
This section lists Progress Software Corporation documentation that you might find useful.
Unless otherwise specified, these manuals support both Windows and Character platforms and
are provided in electronic documentation format on CD-ROM.
Getting Started
Progress Electronic Documentation Installation and Configuration Guide (Hard copy only)
A booklet that describes how to install the Progress EDOC viewer and collection on UNIX
and Windows.
install-dir/dlc/bin/pro
xlviii
Progress Installation and Configuration Guide Version 9 for UNIX
A manual that describes how to install and set up Progress Version 9.1 for the UNIX
operating system.
Progress Installation and Configuration Guide Version 9 for Windows
A manual that describes how to install and set up Progress Version 9.1 for all supported
Windows and Citrix MetaFrame operating systems.
Progress Version 9 Product Update Bulletin
A guide that provides a brief description of each new feature of the release. The booklet
also explains where to find more detailed information in the documentation set about each
new feature.
Progress Application Development Environment Getting Started (Windows only)
A practical guide to graphical application development within the Progress Application
Development Environment (ADE). This guide includes an overview of the ADE and its
tools, an overview of Progress SmartObject technology, and tutorials and exercises that
help you better understand SmartObject technology and how to use the ADE to develop
applications.
Progress Language Tutorial for Windows and Progress Language Tutorial for Character
Platform-specific tutorials designed for new Progress users. The tutorials use a
step-by-step approach to explore the Progress application development environment using
the 4GL.
Progress Master Glossary for Character and Progress Master Glossary for Character
(EDOC only)
Platform-specific master glossaries for the Progress documentation set. These books are
in electronic format only.
Progress Master Index and Glossary for Windows and Progress Master Index and Glossary for
Character (Hard copy only)
Platform-specific master indexes and glossaries for the Progress hard-copy documentation
set.
Progress Startup Command and Parameter Reference
A reference manual that describes the Progress startup commands and parameters in
alphabetical order.
Preface
xlix
Welcome to Progress (Hard copy only)
A booklet that explains how Progress software and media are packaged. An icon-based
map groups the documentation by functionality, providing an overall view of the
documentation set. Welcome to Progress also provides descriptions of the various services
Progress Software Corporation offers.
Development Tools
Progress ADM 2 Guide
A guide to using the Application Development Model, Version 2 (ADM 2) application
architecture to develop Progress applications. It includes instructions for building and
using Progress SmartObjects.
Progress ADM 2 Reference
A reference for the Application Development Model, Version 2 (ADM 2) application. It
includes descriptions of ADM 2 functions and procedures.
Progress AppBuilder Developers Guide (Windows only)
A programmers guide to using the Progress AppBuilder visual layout editor. AppBuilder
is a Rapid Application Development (RAD) tool that can significantly reduce the time and
effort required to create Progress applications.
Progress Basic Database Tools (Character only; information for Windows is in online help)
A guide for the Progress Database Administration tools, such as the Data Dictionary.
Progress Basic Development Tools (Character only; information for Windows is in online help)
A guide for the Progress development toolset, including the Progress Procedure Editor and
the Application Compiler.
Progress Debugger Guide
A guide for the Progress Application Debugger. The Debugger helps you trace and correct
programming errors by allowing you to monitor and modify procedure execution as it
happens.
Progress Help Development Guide (Windows only)
A guide that describes how to develop and integrate an online help system for a Progress
application.
l
Progress Translation Manager Guide (Windows only)
A guide that describes how to use the Progress Translation Manager tool to manage the
entire process of translating the text phrases in Progress applications.
Progress Visual Translator Guide (Windows only)
A guide that describes how to use the Progress Visual Translator tool to translate text
phrases from procedures into one or more spoken languages.
Reporting Tools
Progress Report Builder Deployment Guide (Windows only)
An administration and development guide for generating Report Builder reports using the
Progress Report Engine.
Progress Report Builder Tutorial (Windows only)
A tutorial that provides step-by-step instructions for creating eight sample Report Builder
reports.
Progress Report Builder Users Guide (Windows only)
A guide for generating reports with the Progress Report Builder.
Progress Results Administration and Development Guide (Windows only)
A guide for system administrators that describes how to set up and maintain the Results
product in a graphical environment. This guide also describes how to program, customize,
and package Results with your own products. In addition, it describes how to convert
character-based Results applications to graphical Results applications.
Progress Results Users Guide for Windows and Progress Results Users Guide for UNIX
Platform-specific guides for users with little or no programming experience that explain
how to query, report, and update information with Results. Each guide also helps advanced
users and application developers customize and integrate Results into their own
applications.
Preface
li
4GL
Building Distributed Applications Using the Progress AppServer
A guide that provides comprehensive information about building and implementing
distributed applications using the Progress AppServer. Topics include basic product
information and terminology, design options and issues, setup and maintenance
considerations, 4GL programming details, and remote debugging.
Progress External Program Interfaces
A guide to accessing non-Progress applications from Progress. This guide describes how
to use system clipboards, UNIX named pipes, Windows dynamic link libraries, Windows
dynamic data exchange, Windows ActiveX controls, and the Progress Host Language Call
Interface to communicate with non-Progress applications and extend Progress
functionality.
Progress Internationalization Guide
A guide to developing Progress applications for markets worldwide. The guide covers
both internationalizationwriting an application so that it adapts readily to different
locales (languages, cultures, or regions)and localizationadapting an application to
different locales.
Progress Language Reference
A three-volume reference set that contains extensive descriptions and examples for each
statement, phrase, function, operator, widget, attribute, method, and event in the Progress
language.
Database
Progress Database Design Guide
A guide that uses a sample database and the Progress Data Dictionary to illustrate the
fundamental principles of relational database design. Topics include relationships,
normalization, indexing, and database triggers.
Progress Database Administration Guide and Reference
This guide describes Progress database administration concepts and procedures. The
procedures allow you to create and maintain your Progress databases and manage their
performance.
lii
DataServers
Progress DataServer Guides
These guides describe how to use the DataServers to access non-Progress databases. They
provide instructions for building the DataServer modules, a discussion of programming
considerations, and a tutorial. Each DataServer has its own guide, for example, the
Progress DataServer for ODBC Guide, the Progress DataServer for ORACLE Guide, or
the Progress/400 Product Guide.
MERANT ODBC Branded Driver Reference
The Enterprise DataServer for ODBC includes MERANT ODBC drivers for all the
supported data sources. For configuration information, see the MERANT documentation,
which is available as a PDF file in installation-path\odbc. To read this file you must
have the Adobe Acrobat Reader Version 3.1 or higher installed on your system. If you do
not have the Adobe Acrobat Reader, you can download it from the Adobe Web site at:
http://www.adobe.com/prodindex/acrobat/readstep.html.
SQL-89/Open Access
Progress Embedded SQL-89 Guide and Reference
A guide to Progress Embedded SQL-89 for C, including step-by-step instructions on
building ESQL-89 applications and reference information on all Embedded SQL-89
Preprocessor statements and supporting function calls. This guide also describes the
relationship between ESQL-89 and the ANSI standards upon which it is based.
Progress Open Client Developers Guide
A guide that describes how to write and deploy Java and ActiveX applications that run as
clients of the Progress AppServer. The guide includes information about how to expose
the AppServer as a set of Java classes or as an ActiveX server.
Progress SQL-89 Guide and Reference
A user guide and reference for programmers who use interactive Progress/SQL-89. It
includes information on all supported SQL-89 statements, SQL-89 Data Manipulation
Language components, SQL-89 Data Definition Language components, and supported
Progress functions.
Preface
liii
SQL-92
Progress Embedded SQL-92 Guide and Reference
A guide to Progress Embedded SQL-92 for C, including step-by-step instructions for
building ESQL-92 applications and reference information about all Embedded SQL-92
Preprocessor statements and supporting function calls. This guide also describes the
relationship between ESQL-92 and the ANSI standards upon which it is based.
Progress JDBC Driver Guide
A guide to the Java Database Connectivity (JDBC) interface and the Progress SQL-92
JDBC driver. It describes how to set up and use the driver and details the drivers support
for the JDBC interface.
Progress ODBC Driver Guide
A guide to the ODBC interface and the Progress SQL-92 ODBC driver. It describes how
to set up and use the driver and details the drivers support for the ODBC interface.
Progress SQL-92 Guide and Reference
A user guide and reference for programmers who use Progress SQL-92. It includes
information on all supported SQL-92 statements, SQL-92 Data Manipulation Language
components, SQL-92 Data Definition Language components, and Progress functions. The
guide describes how to use the Progress SQL-92 Java classes and how to create and use
Java stored procedures and triggers.
Deployment
Progress Client Deployment Guide
A guide that describes the client deployment process and application administration
concepts and procedures.
Progress Developers Toolkit
A guide to using the Developers Toolkit. This guide describes the advantages and
disadvantages of different strategies for deploying Progress applications and explains how
you can use the Toolkit to deploy applications with your selected strategy.
liv
Progress Portability Guide
A guide that explains how to use the Progress toolset to build applications that are portable
across all supported operating systems, user interfaces, and databases, following the
Progress programming model.
WebSpeed
Getting Started with WebSpeed
Provides an introduction to the WebSpeed Workshop tools for creating Web applications.
It introduces you to all the components of the WebSpeed Workshop and takes you through
the process of creating your own Intranet application.
WebSpeed Installation and Configuration Guide
Provides instructions for installing WebSpeed on Windows and UNIX systems. It also
discusses designing WebSpeed environments, configuring WebSpeed Brokers,
WebSpeed Agents, and the NameServer, and connecting to a variety of data sources.
WebSpeed Developers Guide
Provides a complete overview of WebSpeed and the guidance necessary to develop and
deploy WebSpeed applications on the Web.
WebSpeed Version 3 Product Update Bulletin
A booklet that provides a brief description of each new feature of the release. The booklet
also explains where to find more detailed information in the documentation set about each
new feature.
Welcome to WebSpeed (Hard copy only)
A booklet that explains how WebSpeed software and media are packaged. Welcome to
WebSpeed also provides descriptions of the various services Progress Software
Corporation offers.
Preface
lv
Reference
Pocket Progress (Hard copy only)
A reference that lets you quickly look up information about the Progress language or
programming environment.
Pocket WebSpeed (Hard copy only)
A reference that lets you quickly look up information about the SpeedScript language or
the WebSpeed programming environment.
lvi
1
Introducing the Progress 4GL
The Progress Fourth Generation Language (4GL) represents the culmination of several
foundation technologies integrated into a single programming environment. These technologies
include:
A block-structured syntax with control structures (including blocks, procedures, and
functions) that let you encapsulate flexible and powerful application objects.
An integrated front-end manager featuring an event-driven architecture that you can use
to create and manage flexible user interfaces for both graphical and character
environments.
An integrated back-end manager that includes both a native Progress Relational Database
Management System (RDBMS) and a DataServer facility that you can use to access many
third-party RDBMSs and flat file systems.
A compiled intermediate code, executed by a run-time interpreter, that is both efficient and
portable across a range of platforms and application environments.
The following sections include an overview of how Progress integrates these technologies and
covers the following topics:
What is a 4GL?
Progressthe flexible and complete 4GL
Understanding Progress syntax and semantics
Compile-time versus run time-execution
12
1.1 What Is a 4GL?
Before describing the Progress 4GL, it is helpful to understand what a 4GL is. The Progress
4GL is an application development language that allows you to solve a range of application
problems with much less effort than earlier language technologies.
1.1.1 A Powerful Application Builder
Figure 11 shows the relative power of the four basic generations of computer languages, using
three measures of development efficiency.
Figure 11: Measures of 4GL Efficiency
4GL
2GL
3GL
1GL
Machine Languages
Macro Assembly
Languages
C++,
Pascal,
Basic,
COBOL,
etc.
Progress,
System 1032,
Model 204,
etc.
Application Complexity
Supported
Development Effort
Required
Platform Knowledge
Required
3 2
1
13
Each successive generation of language tools:
Provides greater capacity to handle ever more complex applications
Requires less development effort per application
Requires less knowledge and management of the platform where an application is
developed and deployed
The more a tool set supports these three indicators, the more effectively a developer can deliver
application solutions.
1.1.2 More Complex Applications Supported
A 4GL supports complex applications by providing application-oriented language features.
These are features that reflect the application problem rather than the capabilities of a particular
machine.
For example, where an earlier generation language might allow you to see data only as a stream
of bytes or characters, a 4GL presents data with equal ease as a byte stream or as related
collections of objects in a database. Similarly, where a less powerful language provides only
basic arithmetic and logical operations, a 4GL also provides application-oriented operations for
record reading and writing, database navigation, searching, sorting, time and date conversion,
and user interface management, to name just a few.
To support these more complex operations efficiently, reliably, and with a high degree of
flexibility, a modern 4GL like Progress provides a run-time manager. This run-time manager
maintains a consistent environment for developing and deploying applications, whether single
platform or multi-platform, local or distributed.
14
1.1.3 Less Development Effort Required
A powerful 4GL provides a basic set of operations that do a lot of work with little developer
intervention. At the same time, the language allows a fine degree of control over the basic
operations it provides. This allows the developer to satisfy a variety of design requirements
using the same basic set of tools.
To support an application with a single window, a 3GL like C or COBOL must perform many
different input/output operations and keep track of a variety of processing conditions for each
operation. In a 4GL like Progress, the same basic set of operations can manage a single
application window or many windows, depending on the requirements of the application and
the type of user interface environment in which it runs.
For example in Progress, one of the simplest, yet most powerful, tools is the FOR statement.
This statement provides iterative record reading and display management capabilities so
powerful that you can write an entire application with it.
This is one such classic Progress application:
FOR EACH Item: DISPLAY Item. END.
15
This statement reads each record from a database table named Item in the sports database
provided with Progress. It displays all the fields of each record in a default window frame
complete with column labels. Every time the frame fills up, it automatically prompts the user to
display the next frame:
From this simple start, there are dozens of ways to modify this application to select and combine
data or change its appearance on the display. Compared with this single FOR statement, to
develop this application in a 3GL requires several hundred lines of code.
16
1.1.4 Less Platform Knowledge Required
The consistent run-time environment of a 4GL like Progress insulates the developer from many
platform management concerns. There is little or no need to learn the compilers, linkers, and
debuggers of the environment where the application is developed and deployed.
Along with offering the developer greater independence from the platform on which they work,
the self-contained run-time environment of a 4GL is often portable across many platforms.
Progress is the most flexible and complete of these run-time 4GLs, because it both provides a
common language to interact with many platforms and optimizes that language to interact with
many of the unique features of each platform.
1.2 ProgressThe Flexible and Complete 4GL
The Progress 4GL excels in seven main areas, all supported within the language:
Flexibility Rapid application development and testing
Consistency Integration of user interface, database, and logic with a single language
Security Multi-user access control and data management
Interoperability Interfaces to and from external and remote programs and systems
Connectivity Access to databases in local and client/server configurations
Portability Development and deployment on multiple platforms
Localizability Development and deployment support for national languages
The following sections describe these major language areas and where to find more information
on them. Later sections in this chapter describe the syntax and structure of a 4GL application
and how to build one.
17
1.2.1 Flexibility
Progress is an interpreted language with a run-time compiler to rapidly build and test
applications. With the help of the Application Development Environment (ADE), most of
which is built using the 4GL, you can compile and run applications on the fly. The compiler
generates an efficient run code (r-code) that the Progress run-time interpreter can execute
immediately, without additional operating system intervention (no machine language
generation or linkage required).
You can also compile and execute 4GL routines directly from within your application. Thus,
changes to the code and even the scope of an application can often be made in a matter of
minutes. See the Compile-time Versus Run-time Execution section in this chapter for
information on how to compile and execute 4GL applications. See Appendix A, R-code
Features and Functions. for a description of the structure and utility of Progress r-code.
1.2.2 Consistency
The Progress 4GL supports all front-end, back-end, and distributed application logic with a
single block-structured language that includes the following features:
Consistent data model
Consistent user interface model
Encapsulation
Common event handler
Choice of programming models
Integrated preprocessor
Default processing
Integrated application help
18
Consistent Data Model
The 4GL presents a consistent model for external (database) and internal (memory) data
management. That is, you can work with both database fields and variables using similar data
manipulation and user interface techniques. Progress also protects variables and database fields
at run time using similar update and data consistency mechanisms (transactions). Progress
transactions also support multi-user database access with the help of a flexible lock manager.
For information on how Progress manages variable and field values in the user interface, see
Chapter 17, Representing Data. For information on how Progress manages database records
and program variables in transactions, see Chapter 12, Transactions. For information on the
4GL elements you can use to coordinate multi-user database transactions, see Chapter 13,
Locks.
The 4GL supports implicit access to database records and fields using record-reading blocks
(including the FOR statement described earlier). You can also read database records and fields
explicitly using record-reading statements that access either single or multiple records (queries)
at a time. This includes B-tree indexing and support for joins within a single database or
between the tables of multiple databases. For information on Progress 4GL mechanisms for
accessing databases, see Chapter 9, Database Access.
Progress also uses the same data model (with appropriate variations) to access non-Progress
databases and file systems with DataServers. For more information on the 4GL variations
required to access DataServers, see the Progress DataServer guide for each DataServer.
The 4GL also supports memory-resident temporary tables. You define temporary tables much
like groups of variables. They are, in fact, variables grouped into memory-resident database
records. Thus with temporary tables, Progress allows you to define arrays of records and access
them with the same 4GL interface used to access database records. For information on how to
use these memory-resident tables, see Chapter 15, Work Tables and Temporary Tables.
Single-User Interface Model
The 4GL uses a single internal model (with some variations) for both graphical and character
user interfaces. This model represents the user interface as related hierarchies of widgets, where
a widget is any single user interface object that you can define completely in the 4GL.
This single widget model supports several different visualizations, depending on the operating
environment. In graphical environments, like Windows, widgets are 4GL-aware controls that
include such objects as windows, frames, selection lists, fill-ins, and database browse widgets.
In character-environments, the 4GL supports many of the same widgets in character form. See
Chapter 10, Using the Browse Widget, and most of the remaining chapters starting with
Chapter 16, Widgets and Handles, for information on using 4GL widgets.
19
Encapsulation
Using basic external and internal procedure blocks, Progress provides an encapsulation
mechanism that allows you to create 4GL-based objects. That is, you can package data, widgets,
and code into a single unit that your application can access through a controlled interface, much
like encapsulated object modules in C and some other languages.
You create and manage encapsulated objects at run-time by executing external procedure files
persistently. See Chapter 3, Block Properties, for information on external and internal
procedures, persistent procedures, and user-defined functions. See also Chapter 21,
Windows, which shows one way you can use persistent procedures to manage a user
interface.
An ADE application-building tool, the AppBuilder, includes an implementation of encapsulated
objects, Progress SmartObjects. These include a variety of objects that you can combine to build
many types of database applications using the current version of the Progress Application
Development Model (ADM). For more information, see the Progress AppBuilder Developers
Guide.
Common Event Handler
The 4GL language provides a common event handler for both user interface and database
events, which are programmable using triggers. This event handler allows your application to
manage all supported graphical and character user interfaces using similar trigger routines. The
same mechanism helps to streamline the coding of data integrity rules by trapping various
database read and write events. For information on how to use database triggers, see Chapter
11, Database Triggers. See also Chapter 6, Handling User Input, and Chapter 16, Widgets
and Handles, for information on how to work with user interface triggers.
Choice Of Programming Models
With block control structures and event triggers, you can choose from a range of program
models to implement your applications, from purely procedure-driven to purely event-driven.
See Chapter 2, Programming Models, which compares the two basic procedure-driven and
event-driven program models, and how they can be used in the 4GL. See Chapter 3, Block
Properties, for information on the basic block control structures of the 4GL.
Integrated Preprocessor
The Progress 4GL requires no preprocessing steps separate from compilation for any aspect of
4GL application development. However, there is an integrated 4GL preprocessor for
conditional compilation to help your application adapt to varying environmental requirements.
For information on this facility, see Chapter 8, The Preprocessor.
110
Default Processing
A rich set of overridable defaults allows your applications to be as simple or as complex as user
requirements demand. These defaults allow you to develop useful applications with as little as
one line of code, or as many lines as you need to manage complex user interfaces and multi-user
database queries and transactions. This includes default error-handling capabilities available
from the statement to the application level. For information on the error-handling facility and
its defaults, see Chapter 5, Condition Handling and Messages. Other defaults are described as
they apply to each 4GL feature.
Integrated Application Help
The 4GL provides access to a variety of application help facilities, depending on your
applications user interface. For applications running in a graphical user interface (GUI), you
can build a complete hypertext on-line help system using the Progress Help compiler. Through
the 4GL, you can also provide context-sensitive access to this help system.
For applications running in any user interface (character or GUI), you can provide field-level
help. Field-level help automatically prompts the user when they give input focus to a field. You
can specify the prompt (or help string) for each database field directly in the Progress Data
Dictionary or using 4GL help strings.
For more information on both on-line help and field-level help, see the Progress Help
Development Guide.
1.2.3 Security
Progress provides mechanisms to maintain application and database security for multi-user
applications. You can authenticate user IDs and passwords and check them for activity-based
access rights. For information on how to establish and validate Progress user IDs and
passwords, see Chapter 14, Providing Data Security.
1.2.4 Interoperability
Progress offers a rich variety of interfaces to systems and applications outside Progress. The
most basic of these is access to alternate I/O sources, such as printers, operating system
sequential files, and pipes. For more sophisticated applications, Progress provides 4GL access
to a variety of external program interfaces on supported operating systems, including:
A host language call interface to C language functions
System clipboards
UNIX named pipes
111
Windows dynamic link libraries
Windows dynamic data exchange
ActiveX Automation support
ActiveX control container support
For information on the basic system access capabilities of the 4GL, see Chapter 7, Alternate
I/O Sources. For more information on the supported external program interfaces, see the
Progress External Program Interfaces manual.
The 4GL also includes a related, but separate, SQL implementation. This is especially effective
when accessed as Progress Embedded SQL-89 (ESQL) from a host language application that
seeks to read and write to a Progress database. You can precompile Progress/ESQL-89 queries
into Progress r-code for more efficient execution from the host language application. For more
information on Progress/SQL-89, see the Progress SQL-89 Guide and Reference, and for more
information on Progress/ESQL-89, see the Progress Embedded SQL-89 Guide and Reference.
You can also access Progress from a Microsoft Open Database Connectivity (ODBC)
application using the MERANT Progress ODBC Driver. For more information on this driver,
see the MERANT documentation. For more information on how this driver works with
Progress, see the Progress SQL-89 Guide and Reference.
1.2.5 Connectivity
Progress supports a distributed application environment and a client/server database
environment. Through the Progress 4GL and utilities, you can establish and manage
connections to local and remote databases, and local and distributed application logic. For
information on designing, developing, deploying, and running distributed Progress
applications, see Building Distributed Applications Using the Progress AppServer. For
information on connecting to local and remote Progress databases, see Chapter 9, Database
Access. For information on using the Progress 4GL to connect to Progress DataServers (which
allow Progress applications to access certain non-Progress databases), see the Progress
DataServer guides.
1.2.6 Portability
Progress applications and r-code are portable across operating environments, with certain
platform restrictions due to differences in combinations of machines, user interfaces, and
DataServers. In general, platform-specific features that you implement in the 4GL usually
compile on different development platforms. However, you might not be able to execute the
r-code without error on platforms where the features are not supported.
112
One use of the 4GL preprocessor is to allow you to implement features supported by different
platforms in a single application. You can then conditionally compile these features based on
the platform where you choose to deploy an instance of the application. However, even where
different platforms support the same 4GL features, they might not execute the same generated
r-code. That is, you might have to compile your application on some of the platforms where you
plan to run it. See Appendix A, R-code Features and Functions, for information on the r-code
portability rules for different machines, user interfaces, and DataServers.
1.2.7 Localizability
One of the unique features of Progress is a high level of international language support. This
includes the flexibility to localize a single application for multiple national languages, or even
cultural regions. Progress even provides support for native double-byte application
development and deployment for East Asian languages, such as Chinese and Japanese. For more
information on language support, see the Progress Internationalization Guide.
1.3 Understanding Progress Syntax and Semantics
The following sections describe some general features of Progress syntax and semantics. Some
of these features are more fully described in later chapters.
1.3.1 Elements of Progress Syntax
Progress is a block-structured, but statement-oriented language. That is, much of the behavior
of a Progress application depends on how statements are organized into blocks. However, the
basic executable unit of a Progress application is the statement.
Statements
This is the basic syntax of a Progress application:
Thus, a Progress 4GL application consists of one or more statements. Each statement consists
of a number of words and symbols entered in a statement-specified order and terminated by a
period ( . ) or a colon ( : ), depending on the type of statement.
SYNTAX
statement { . | : } [ statement { . | : } ...
113
This is a one-statement application that displays Hello, World! in a message alert box:
Comments
A Progress application can also contain non-executable comments wherever you can put white
space (except in quoted strings). Each comment begins with /* and terminates with */, and
you can nest comments within other comments:
p-hello1.p
MESSAGE "Hello, World!" VIEW-AS ALERT-BOX.
p-hello2.p
/*/* Simple Application */*/
MESSAGE /* Statement Keyword */ "Hello, World!" /* String */
VIEW-AS ALERT-BOX /* Options */ . /*/* Period Terminates */
-^--------^- Statement */
114
Blocks
In Progress, a block is a sequence of one or more statements, including any nested blocks, that
share a single context. A context consists of certain resources that a block of statements share.
The content of this shared context depends on the type of block and its relationship to other
blocks. The sample procedure, p-blocks.p, shows a typical layout of blocks in a procedure:
In response to choosing a button, this procedure calculates the sum of all customer balances in
the sports database and displays it in a message alert box.
The most basic block is the procedure, and the most basic procedure is an external procedurea
file containing one or more statementsbecause this is the smallest unit that Progress can
compile separately. Thus, p-hello2.p is an external procedure with one statement, and
p-blocks.p is an external procedure with several statements. An external procedure block is
also the only type of block that requires no special syntax to define it. Progress always defines
an external procedure block, by default, when the procedure executes.
You must begin all other types of blocks with appropriate header statements. Header statements,
such as the DO, FOR, and PROCEDURE statements shown in p-blocks.p, are typically
terminated with a colon, although you can use a period. You generally must terminate the block
begun with a header statement with an END statement.
p-blocks.p
/* BEGIN EXTERNAL PROCEDURE BLOCK */
DEFINE BUTTON bSum LABEL "Sum Customer Balances".
DEFINE VARIABLE balsum AS DECIMAL.
DEFINE FRAME A bSum.
ON CHOOSE OF bSum IN FRAME A DO: /* BEGIN Trigger Block */
RUN SumBalances(OUTPUT balsum).
MESSAGE "Corporate Receivables Owed:"
STRING(balsum, "$>,>>>,>>>,>>9.99") VIEW-AS ALERT-BOX.
END. /* END Trigger Block */
ENABLE bSum WITH FRAME A.
WAIT-FOR WINDOW-CLOSE OF FRAME A.
PROCEDURE SumBalances: /* BEGIN Internal Procedure Block */
DEFINE OUTPUT PARAMETER balance-sum AS DECIMAL INITIAL 0.
FOR EACH customer FIELD (Balance): /* BEGIN Iterative Block */
balance-sum = balance-sum + Balance.
END. /* END Iterative Block */
END. /* END Internal Procedure Block */
/* END EXTERNAL PROCEDURE BLOCK */
115
1.3.2 Blocks and Context
The context of a block generally lies within the code defined by the beginning and end of the
block. For an external procedure, the block beginning and end is the first and last statement in
the file. For any other block, it is the blocks header and END statement. The context of an
external procedure includes all data, widgets, triggers, and internal procedures that it defines.
This is the only type of block that can define trigger and internal procedure blocks within its
context. Thus, the external procedure context is often called the main block of the procedure.
For example, the variable, balsum, is defined in the main block of p-blocks.p and can be
modified by all statements and blocks defined within p-blocks.p, such as the trigger block.
However, the internal procedure, SumBalances, defines an output parameter, balance-sum, that
can only be modified within the context of its own block.
In general, any data or widgets that you define within the context of a procedure or trigger block,
are available only to the statements of that procedure or trigger block. However, any data or
widgets that you define within other types of blocks are actually part of the nearest enclosing
procedure or trigger context, not the context of the block where they are defined.
For example, this procedure calculates the sum of customer balances using a variable,
balance-sum, defined within a FOR block:
However, balance-sum is actually assigned to the outer procedure context, so the MESSAGE
statement, outside the FOR block, can also reference it.
Variable definitions are always assigned to the nearest enclosing procedure or trigger context,
because Progress maintains the run-time values for variables in a single stack frame for the
entire procedure or trigger. (Progress implements trigger blocks in much the same way as
procedure blocks.) Thus, when a procedure A calls another procedure B, all of procedure As
variable values are saved for the return from procedure B. However, when Progress executes a
DO, FOR, or other type of block, no prior variable values are saved before the block executes.
Likewise, there is no separate data context to maintain variables defined within these blocks.
Therefore, Progress maintains the variables defined within these blocks as though they were
defined directly in the procedure context.
p-block1.p
FOR EACH Customer FIELDS (Balance):
DEFINE VARIABLE balance-sum AS DECIMAL INITIAL 0.
END.
MESSAGE "Corporate Receivables Owed:"
STRING(balance-sum, "$>,>>>,>>>,>>9.99") VIEW-AS ALERT-BOX.
116
1.3.3 Block Context and Resource Scope
The context of some blocks also helps determine the scope of certain resources. On the other
hand, the scope of other resources might have little to do with the context in which you initially
define them. Scope is really the duration that a resource is available to an application. Scope can
very depending on the resource and the conditions of application execution.
In general, the scope of resources created at compile time (when Progress compiles your
application) is determined at compile time; the scope of resources created at run time (when
Progress executes your application) is determined at run time. (See the Compile-time Versus
Run-time Execution section.) The scope of a resource begins when the resource is instantiated
(created in your application) and ends when the resource is destroyed (removed from your
application).
For example, a FOR statement defines the scope of any database buffer that it implicitly defines
for record reading. The scope of such a record buffer is identical to the context of the FOR block,
because the buffer is deleted when the FOR block finishes with it. For example, in p-block1.p,
the scope of the Customer buffer ends when the FOR block completes. Although the
MESSAGE statement following the FOR block can access balance-sum, it can no longer access
the Balance field for any record read into the Customer buffer by the FOR block.
Unscoped Resources
On the other hand, this procedure fragment does not even compile, precisely because the FOR
block defines the scope of FRAME A. It appears that FRAME A is defined and available in the
procedure context. However, the DEFINE FRAME statement does not scope the frame that it
defines. Instead, the frame is scoped by the context of its first use, in this case the FOR block.
As a result, the frame is actually deleted at run time when the FOR block completes. Progress
knows this and thus prevents this fragment from compiling:
The solution is to either use a FORM statement to scope the frame to the procedure block, or
define a separate frame for the second reference.
DEFINE FRAME A Name Balance WITH 10 DOWN.
FOR EACH Customer FIELDS (Name Balance) WITH FRAME A:
DEFINE VARIABLE balance-sum AS DECIMAL INITIAL 0.
DISPLAY Name Balance.
DOWN.
END.
FIND FIRST Customer.
DISPLAY Name Balance WITH FRAME A.
117
Dynamic Resources
In general, dynamic resources are resources that you implicitly or explicitly create and delete at
run time. Record buffers that a FOR statement implicitly defines are dynamic buffers: Progress
creates them when the FOR block executes and deletes them when its execution completes.
Frames scoped to a FOR block are dynamic in the same way. The whole context of a procedure
is dynamic: Progress creates its local data and user interface resources when you call the
procedure and deletes them when the procedure returns or otherwise goes out of scope.
However, Progress allows you to create and delete many dynamic resources explicitly. These
include external procedure contexts (persistent procedures) and most user interface widgets. In
general, the scope of a dynamic resource lasts from the time you create it to the time you delete
it or when the Progress client session ends, which ever occurs first. When a procedure block
completes execution and its context goes out of scope, this does not affect the scope of any
dynamic resources that you have created in that context. The completion of the procedure can
only affect whether the resources are still accessible from the context that remains.
Progress allows you to define handles to most dynamic resources. These handles are variables
that point to the resources you have created. You must ensure that handles to these resources are
always available to your application until you delete the resources. If you create a dynamic
widget within a procedure and do not delete it before the procedure completes, the widget
remains in scope within your Progress session. If you also lose the original handles to these
widgets when the procedure ends, you might not be able to access them again. If you cannot
access them, you cannot delete them. In effect, they become memory lost to Progress and the
system (that is, a memory leak), as in p-clock1.p.
118
This example calls a procedure, get-time, to display the current time for five seconds on request.
When get-time executes, it creates a new window for the clock and hides that window before
returning. However, the handle to the window, clock-handle, is part of the get-time context and
is lost when the procedure returns. Thus, each time get-time returns, it makes another windows
worth of memory unavailable for use until Progress exits. The correct way for get-time to
manage its clock window is to use the DELETE WIDGET statement to explicitly delete the
window before returning.
For more information on blocks, context, and scoping, see Chapter 3, Block Properties. For
more information on frame scope, see Chapter 19, Frames For more information on managing
dynamic widgets, see Chapter 20, Using Dynamic Widgets.
p-clock1.p
DEFINE VARIABLE show-time AS LOGICAL.
DEFAULT-WINDOW:HIDDEN = TRUE.
REPEAT:
MESSAGE "Choose: OK to see the current time" SKIP
" Cancel to stop clock"
VIEW-AS ALERT-BOX BUTTONS OK-CANCEL UPDATE show-time.
IF show-time THEN RUN get-time.
ELSE QUIT.
END.
PROCEDURE get-time:
DEFINE VARIABLE clock-handle AS WIDGET-HANDLE.
DEFINE VARIABLE current-time AS CHARACTER FORMAT "x(8)".
DEFINE FRAME clock SKIP(.5) SPACE(1) current-time SKIP(.5)
WITH THREE-D NO-LABELS TITLE "Current Time" CENTERED.
current-time:SENSITIVE = TRUE.
CREATE WINDOW clock-handle ASSIGN
HEIGHT = FRAME clock:HEIGHT
WIDTH = FRAME clock:WIDTH
TITLE = "Clock"
MESSAGE-AREA = FALSE
STATUS-AREA = FALSE
ROW = 1
COLUMN = 1.
CURRENT-WINDOW = clock-handle.
current-time = STRING(TIME, "HH:MM:SS").
DISPLAY current-time WITH FRAME clock.
PAUSE 5 NO-MESSAGE.
clock-handle:HIDDEN = TRUE.
END.
119
1.3.4 Compile-time Versus Run-time Code
Like many languages, the Progress 4GL includes two basic types of code:
Compile-time, sometimes known as nonexecutable code
Run-time, sometimes known as executable code
However, as an interpretive language, Progress syntax combines compile-time and run-time
components in many more ways than a compiled language like C. The flexibility of this syntax
helps implement the rich variety of overridable defaults that characterizes the Progress 4GL.
Compile-time Code
Certain statements exist only to generate r-code when Progress compiles them. These are
compile-time statements. That is, they create static data and user interface resources (widgets)
that the run-time statements can reference and modify, but not destroy, during execution.
Run-time Code
Run-time statements use the static resources created by compile-time statements, but can also
create, use, and destroy dynamic resources at run time. That is, run-time statements include
statements that interact with static resources, dynamic resources, or both. Many run-time
statements also include compile-time options. These are options that generate resources at
compile time that are later used by the same statements at run time.
Which Code Is Which?
How can you identify the type of code you are using? There are some general features of 4GL
syntax that provide the clues. The following procedure that computes factorials, p-ctrt0.p,
illustrates many of these features.
120
Compile-time Syntax Elements
Most compile-time code consists of the following syntax elements:
Compile-time statements, including the FORM statement and all other 4GL statements
that begin with the DEFINE keyword:
The non-executable components of block header statements and END statements:
p-ctrt0.p
DEFINE VARIABLE xvar AS INTEGER VIEW-AS FILL-IN.
DEFINE VARIABLE yvar AS INTEGER VIEW-AS SLIDER MAX-VALUE 16 MIN-VALUE 1.
DEFINE VARIABLE zvar AS INTEGER VIEW-AS FILL-IN.
DEFINE VARIABLE fact-compute AS LOGICAL.
DEFINE BUTTON bOK LABEL "OK".
DEFINE BUTTON BCancel LABEL "Cancel" AUTO-GO.
FORM SKIP (.05)
"Enter upper factorial to compute:" yvar FORMAT ">>" SKIP(.05)
"Factorial of" xvar FORMAT ">>" "=" zvar SKIP(.05)
bOK bCancel
WITH FRAME zFrame NO-LABELS.
ON CHOOSE OF bOK DO:
ASSIGN yvar
zvar = 1.
DO xvar = 1 TO yvar WITH FRAME zFrame:
.
.
.
END.
END.
ENABLE yvar bOK bCancel WITH FRAME zFrame.
WAIT-FOR GO OF FRAME zFrame.
&MESSAGE This procedure has {&LINE-NUMBER} lines.
121
Options and phrases associated with compile-time statements, wherever they appear:
NOTE: The compile-time variable references, xvar, zvar, and yvar, in the ASSIGN,
DISPLAY, and ENABLE statements reference the static widgets ( FILL-IN or
SLIDER) that represent the variable values at run time. Thus, Progress
distinguishes variables from their representation. (See also the following
Run-time Syntax Elements section.)
Literal expressions (constants):
Preprocessor directives and definitions:
ASSIGN yvar
zvar = 1.
zvar = xvar * zvar.
DISPLAY xvar zvar FORMAT ">,>>>,>>>,>>>" WITH FRAME zFrame.
MESSAGE "Compute next factorial" VIEW-AS ALERT-BOX
QUESTION BUTTONS YES-NO UPDATE fact-compute.
IF NOT fact-compute THEN LEAVE.
END.
END.
ASSIGN yvar
zvar = 1.
zvar = xvar * zvar.
END.
END.
&MESSAGE This procedure has {&LINE-NUMBER} source lines.
122
Run-time Syntax Elements
Most run-time code consists of the following syntax elements:
All statements other than compile-time statements:
The options and phrases associated with run-time statements, including the executable
components of block header statements, except those options and phrases that are also
associated with compile-time statements (such as Format and Frame phrases):
The block header statements of iterative blocks (DO, FOR, and REPEAT blocks) all have
executable components. These executable components monitor and enforce the iteration
conditions (when the block starts and stops executing) and select any database data that
are available to the block. For more information, see Chapter 3, Block Properties.
ASSIGN yvar
zvar = 1.
zvar = xvar * zvar.
END.
END.
ASSIGN yvar
zvar = 1.
zvar = xvar * zvar.
END.
END.
123
Assignment statements and non-literal expressions (variables, functions, attributes, and
methods):
NOTE: Progress distinguishes variables from their data representation. However, the
references to yvar, xvar, and zvar in the ASSIGN and DISPLAY statements
reference both the variables and their static widget representations because
Progress moves data between them implicitly at run time. Progress makes this
distinction explicit for variables and dynamic widgets because you must move
data between them explicitly at run time. For more information on the
relationship between widgets and data, see Chapter 16, Widgets and Handles
Progress also allows run-time expressions to qualify some compile-time options. See the
example in the How Compile-time Code and Run-time Code Interact section.
How Compile-time Code and Run-time Code Interact
Because the Progress 4GL is a run-time interpreted language, it can combine compile-time and
run-time code in a number of interesting and powerful ways.
For example, as noted earlier, some run-time statements can also include compile-time options.
Thus, you can define a static frame in which to display data using a FORM statement, then add
options to that static frame definition using Frame phrase options in subsequent run-time
statements, such as FOR and DISPLAY.
ASSIGN yvar
zvar = 1.
zvar = xvar * zvar.
END.
END.
124
In example procedure p-ctrt1.p, the data fields, frame type, and title for frame alpha are all
defined at compile time and in three different statements:
This procedure also illustrates a compile-time option (DOWN) qualified by a run-time
expression (iter). The DOWN option specifies the type of frame for frame alpha at compile time.
However, the number of iterations (rows of data displayed) in the down frame are determined
at run time. This is possible, because certain design-oriented widget options (attributes) can
actually be modified up to the point that the widget is realized (ready for viewing by the window
system). Progress realizes frame alpha, a static widget, at the point of its first use, in the
DISPLAY statement.
Another interesting thing about this procedure is that the iter value that qualifies the DOWN
option is set after the DOWN option appears in the code:
This is possible because Progress knows where the run-time iteration value for the DOWN
option comes from at run time, and uses the last value set before the frame is realized in the
DISPLAY statement.
NOTE: If the value for a run-time expression is unknown (?), Progress uses whatever default
applies to the qualified compile-time option. So, in the example, if iter is not assigned
a value before its use with the DOWN option, Progress uses the DOWN option
default. In this case, the alpha frame displays as many rows as the frame can fit in its
window.
p-ctrt1.p
DEFINE VARIABLE iter AS INTEGER.
DEFINE FRAME alpha Customer.Name Customer.Phone.
iter = 10.
MESSAGE "iter =" iter VIEW-AS ALERT-BOX.
FOR EACH Customer WITH FRAME alpha iter DOWN:
iter = 5.
DISPLAY name phone balance WITH TITLE "Customer Balances".
END.
MESSAGE "iter =" iter VIEW-AS ALERT-BOX.
FOR EACH Customer WITH FRAME alpha iter DOWN:
iter = 5.
.
.
.
125
A powerful example of the interaction between compile-time and run-time code is the use of the
VALUE option in a number of run-time statements. In example procedure p-ctrt2.p, the
VALUE option allows you to use a run-time expression (proc-name[proci]) to provide a
compile-time object name:
In the RUN statement, the object name is the name of a procedure to execute. Procedure
p-ctrt2.p thus shows how the same three procedures can be executed using static
compile-time object names or using object names evaluated by the VALUE option at run time.
NOTE: The three procedures executed by p-ctrt2.p, including p-join2.p, p-foftab.p,
and p-wow1.p appear in later chapters of this manual and are also available on-line.
For more information on accessing the on-line versions, see the preface of this
manual.
Further examples of compile-time/run-time interactions appear throughout this manual,
especially in the chapters on blocks, widgets, and interface design.
p-ctrt2.p
DEFINE VARIABLE proci AS INTEGER.
DEFINE VARIABLE whand AS WIDGET-HANDLE.
DEFINE VARIABLE proc-name AS CHARACTER EXTENT 3
INIT ["p-join2.p", "p-foftab.p", "p-wow1.p"].
CREATE WINDOW whand. CURRENT-WINDOW = whand.
MESSAGE "These are STATIC procedure executions." VIEW-AS ALERT-BOX.
RUN p-join2.p.
DELETE WIDGET whand.
RUN p-foftab.p.
RUN p-wow1.p.
DO proci = 1 TO 3:
IF proci = 1 THEN
MESSAGE "These are DYNAMIC procedure executions."
VIEW-AS ALERT-BOX.
RUN VALUE(proc-name[proci]).
END.
126
1.4 Compile-time Versus Run-time Execution
In Progress you execute a procedure using the RUN statement. However, you can use two basic
techniques to compile and execute a procedure:
Compile-time execution You can compile the procedure file on the fly when you
execute it using the RUN statement. In this case, Progress locates the procedure file,
compiles it to a temporary r-code file, then executes the temporary r-code file.
Run-time execution You can generate an r-code file from the procedure file using the
COMPILE statement or the Application Compiler in the ADE. Then, when you execute
the procedure with the RUN statement, Progress locates and executes the r-code file
directly.
Both techniques use the PROPATH environment variable settings. That is, both the COMPILE
and RUN statements locate procedures using PROPATH. (For more information on the
PROPATH environment variable, see the Progress Client Deployment Guide.) How the RUN
statement executes a procedure (compile-time or run-time execution) depends on how you set
up your environment and when you choose to compile the procedure. Each technique provides
different capabilities and advantages.
1.4.1 Compile-time Execution
The RUN statement performs compile-time execution when Progress cannot find an existing
r-code file that corresponds to the specified procedure. Because r-code is interpreted, there is no
need to link an additional machine executable; the RUN statement can thus execute the
procedure immediately after compiling it.
Compile-time execution has two main uses:
Rapid prototyping and testing
Dynamic 4GL Code Generation
Rapid Prototyping and Testing
Rapid prototyping allows you to quickly complete a code and test cycle for a procedure or a
whole application without any concern for compile-time or run-time optimizations. After you
have filled in your application architecture, you can then fine tune it using the Application
Compiler and other Progress tools and utilities.
127
Dynamic 4GL Code Generation
Dynamic code generation is an advanced technique that you can see at work in the Progress
AppBuilder. From within any application that includes the Progress compiler, you can write
4GL code fragments to a file, execute the file as a procedure, and remove the file, all under
application control.
1.4.2 Run-time Execution
Compile-time execution can save time in development. However, to improve application
performance, the first step is to ensure that it is running in r-code form.
Thus, run-time execution has two main uses:
Application fine tuning and deployment
Optimized dynamic code generation
Application Fine Tuning and Deployment
This is the technique most often used during final construction and deployment of an end-user
application. Executing an r-code file is generally much faster than compile-time executing a
procedure source file. After you have completed all prototyping and testing, you might fine tune
each procedure using the Application Compiler. (For more information on the Application
Compiler, see the Progress Basic Development Tools (Character only) book, and in graphical
interfaces, the on-line help for the Application Compiler.) You might then use the compiler to
generate all the r-code files for your application and tune its final performance using database
administration utilities, such as PROMON, to help establish optimum values for session startup
and database connection parameters. For more information on application deployment, see the
Progress Client Deployment Guide and the Progress Developers Toolkit.
Optimized Dynamic Code Generation
If your application includes the Progress compiler to generate and execute code dynamically,
you can increase performance using the COMPILE statement. This allows you to save
semi-permanent r-code files between sessions that execute much more quickly from startup. It
is also a more secure way to generate dynamic code, because you can remove the procedure
source files during each session, leaving only the r-code. The Application Compiler also uses
this technique to compile procedures for applications. For more information on the COMPILE
statement, see the Progress Language Reference.
128
2
Programming Models
This chapter describes two general programming models that Progress supports and describes
how to determine which model best suits your development effort. These models are as follows:
Procedure-driven programming
Event-driven programming
22
2.1 Procedure- and Event-driven Programming
Procedure-driven programming, which you can think of as traditional programming, defines
the programming process as the development of procedures that explicitly direct the flow of
data and control.
Event-driven programming defines the programming process as the development of procedures
that respond to the flow of data and control as directed by the user, program, or operating
system.
These programming models differ in flow of execution and structure. In addition, each model
works best with a particular programming environment. The following sections describe these
models in more detail.
2.2 Flow of Execution
The difference between the procedure-driven and event-driven models is primarily one of
program flow. In a typical procedure-driven program, the execution of program statements is
predetermined and controlled by the programmer. It generally runs from the beginning of the
source file to the end. The programmer codes any branches or loops. In a typical event-driven
program, program execution is largely determined by the system. First the programmer sets up
a series of actions (triggers) to be executed in response to specific events. Then the system waits
for user input to initiate these events. Finally, the system responds to these events, thereby
controlling program execution.
2.2.1 Program Execution in a Procedure-driven Program
The flow of execution in a procedure-driven program is generally top-down and linear. User
interaction with the program is limited; the user can choose from a few preprogrammed tasks.
Each of these tasks consists of several actions that have been prearranged by the programmer.
The sequence of these actions is also determined by the programmer; once a user selects a task,
the application leads the user step-by-step through the actions required to complete the task. As
actions are performed, the program might provide the user with status messages.
Programming Models
23
In the procedure-driven model, the application initiates calls to the operating system for user
input when the program is ready. Figure 21 shows this process.
Figure 21: A Procedure-driven Application Calling the Operating System
Because movement from procedure to procedure is preprogrammed, the programmer is said to
determine the flow of execution. The program performs only one process at a time. Generally,
execution flows from the beginning of the source code to the end. The program may contain
code loops, branches, and jumps that alter this flow, but it is the programmer who must plan for
and manage the conditions for such alterations.
Application
Operating System
24
Figure 22 shows the flow of execution in a typical procedure-driven program.
Figure 22: Flow of Execution in a Procedure-driven Program
Program execution typically begins at a unique starting point, such as when the user issues a
RUN statement. Execution continues line by line through any number of procedures. With the
exception of programmed branches to other procedures, program execution is sequential, both
within the program and within each procedure. Program execution stops when it reaches the end
point in the program. Because branching and looping behavior is tightly controlled, you can
trace the flow of execution in a procedure-driven program.
Procedure 1
Start
End
User Input
Procedure 2 Procedure 3
Programming Models
25
2.2.2 Program Execution in an Event-driven Program
The flow of execution in an event-driven program is primarily determined by the system and,
to some extent, by the user. Event-driven programs respond to input by repeatedly checking for
events. An event is any type of interaction a user or operating system can have with an
application. Events can occur as a result of user action or program code, or they can be triggered
by the system.
In the event-driven model, virtually all actions supported by the application are available to the
user at all times. The user can interact with the program freely, choosing from many simple
tasks and combining them in any order to achieve a desired goal. Also, the user can usually
change or undo an action easily, without disrupting the current task. Instead of just displaying
status messages, event-driven applications display the effects of actions as they occur.
In the event-driven model, the operating system sends information on many kinds of events to
the application. The application responds to and takes action on only those events that it has
been preprogrammed to recognize and ignores any other events. Figure 23 shows this process.
Figure 23: The Operating System Interacting with an Event-driven
Application
Operating System Application
26
Because it triggers events, the system is said to determine the flow of execution. The
programmer sets up a series of triggers to be executed in response to events. Each trigger is a
programmed response, a self-contained block of code that performs a specific task. Once these
triggers are set up, the system waits for actions that initiate another sequence of events. This
sequence of events determines which of the predefined triggers are executed and in what order.
The programmer does not generally define the order in which these triggers are executed.
Figure 24 shows the flow of execution in a typical event-driven program:
Figure 24: Flow of Control in an Event-driven Program
Definitions
User Input
Main Logic
(WAIT-FOR)
Trigger 1
Trigger 2
Trigger 3
Triggers
Program Flow
User Input
User Input
Programming Models
27
Program execution starts at the top of the program and proceeds sequentially to an
input-blocking point where the program waits for events. During program initialization, the
program sets up the user interface: it registers definitions for the functional objects of the user
interface (buttons, frames, and triggers). Then the program enters a WAIT-FOR state. While a
program is in a WAIT-FOR state, the program is said to be blocking for input. In this state, the
user interacts with the functional components of the interface to initiate events. When the user
performs an action that initiates a specific event, an event handler or trigger code block
executes.
The main purpose of the WAIT-FOR condition is to control dismissing the interface. While a
program is in this state, the user can interact with user interface objects, based on what their
labels indicate about their associated functions, to initiate events. The user initiates an event by
performing an action that triggers an event, usually with the keyboard or mouse. When there are
no more events to trigger, the user can either cancel the transaction or initiate the event that
satisfies the WAIT-FOR condition. After dismissing the interface, program control returns to
the interface that called it, if any.
Progress supports user interface triggers that allow users to associate a task (large or small) with
an action, such as choosing a button or menu item, or entering a field. In addition, Progress
supports the normal control structures required for procedure-driven programming as well as
flexible control structures (ON, ENABLE, DISABLE, WAIT-FOR, and PROCESS EVENTS
statements) for event-driven programming.
In an event-driven application, complex sequences of actions are not preprogrammed. Only the
specific individual actions are preprogrammed. Each of these actions might be associated with
an action that takes place in response to a menu item, button, or combination of key presses.
Event-driven programming is rooted in interrupt-driven, real-time operating system technology.
With interrupt-driven processing, the operating system can interact with the user and allow the
user to access the machine during program execution. Requests to the operating system
(interrupts) are acted on immediately. Events, therefore, resemble operating system or real-time
interrupts, where real-time refers to the requirement that the software coordinate its activities
with the real-world environment, in this case the user.
28
When you are interrupted while performing a task, you typically stop what you are doing, record
where you are, take care of the interruption, and later return to your original task. Interrupt
handling in computers provides for a similar process to occur in relation to the execution of a
program. When an interrupt signal occurs within a computer system, the computers central
processing unit:
1. Stops executing the current program or procedure and saves its context (WAIT-FOR).
2. Starts executing another program or procedure (trigger).
Thus, when a user initiates an event, it sends an interrupt signal to the operating system. This
signal then triggers a real-time response (it applies an event) in the program.
2.3 Program Structures
Another difference between procedure-driven programs and event-driven programs is in their
structure. Procedure-driven programs consist of structured code blocks, while event-driven
programs primarily contain blocks of trigger code.
2.3.1 Program Structure in a Procedure-driven Program
The basic structure of a procedure-driven program is as follows.
1. Test for a condition.
2. Execute a block of code.
3. Control the return.
The following example of a simple procedure-driven program using a FOR EACH loop
illustrates this structure:
p-procd.p
FOR EACH customer:
DISPLAY cust-num name phone WITH 6 DOWN.
PROMPT-FOR phone.
IF INPUT phone NE phoneyl
THEN DO:
MESSAGE "Phone Number changed".
BELL.
END.
ASSIGN phone.
END.
Programming Models
29
These notes help explain the code:
The FOR EACH statement starts an iterating block and finds one customer record in the
database on each iteration.
The DISPLAY statement moves the customer data from the database to the screen buffer
and displays six occurrences of the Cust-Num, Name, and Phone fields in an unnamed
default frame.
The PROMPT-FOR statement requests user input for the Phone field and then places it in
the screen buffer.
The IF . . . THEN statement includes an INPUT statement and a DO block. The code
instructs Progress to compare the current value in the Phone field to its value in the
database. If the two values are not the same, Progress displays the message Phone
Number changed, the terminal beeps, and program execution drops down to the next line,
the ASSIGN statement. If the two values are identical, Progress skips the DO block and
moves directly to the ASSIGN statement.
The ASSIGN statement instructs Progress to move the new Phone data into the database.
When all the customer records have been read, the program ends.
2.3.2 Program Structure in an Event-driven Program
An event-driven program is a collection of triggered responses. The basic structure is as follows.
1. Definitions Define and enable the user interface objects that comprise its interface.
2. Triggers Define the behavior that should occur in response to events applied to these
user interface objects. The code within a trigger block tells the system to watch for a
condition, execute a block of code, and control the return.
3. Main Logic Establish a WAIT-FOR state to allow the user to interact with the user
interface objects and then dismiss the user interface when the WAIT-FOR condition is
satisfied. The WAIT-FOR statement typically tests for the end condition.
210
The following example is a simple event-driven program using the WAIT-FOR statement:
p-eventd.p
DEFINE BUTTON btn_1 LABEL "Next".
DEFINE BUTTON btn_2 LABEL "Prev".
FIND FIRST customer.
DISPLAY cust-num name phone SKIP (0.5)
btn_2 TO 40 SPACE btn_1
SKIP (0.5)
WITH FRAME f SIDE-LABELS.
ON CHOOSE OF btn_1 DO:
FIND NEXT customer NO-ERROR.
IF NOT AVAILABLE customer THEN DO:
FIND LAST customer.
BELL.
END.
DISPLAY cust-num name phone WITH FRAME f.
END.
ON CHOOSE OF btn_2 DO:
FIND PREV customer NO-ERROR.
IF NOT AVAILABLE customer THEN DO:
BELL.
END.
DISPLAY cust-num name phone WITH FRAME f.
END.
ON LEAVE OF phone DO:
IF INPUT customer.phone NE customer.phone THEN DO:
ASSIGN customer.phone.
BELL.
MESSAGE "Phone Number changed."
VIEW-AS ALERT-BOX INFORMATION.
END.
END.
ENABLE phone btn_2 btn_1 WITH FRAME f.
WAIT-FOR GO OF FRAME f.
Programming Models
211
These notes help explain the code:
The two DEFINE BUTTON statements define two static buttons, btn_1 and btn_2, and
label them Next and Prev. These labels provide visual cues to the user that relate to
each buttons function.
The next two statements instruct Progress to find the first customer record in the database
and display the Cust-Num, Name, and Phone data in frame f, labeling each field to the left
and center.
The first ON statement defines trigger code that Progress executes each time the user
applies a CHOOSE event to btn_1, the Next button. This CHOOSE behavior applies only
to btn_1.
NOTE: At run time, the CHOOSE event in this example is applied by clicking btn_1.
Other programming techniques for applying a CHOOSE event include using a
4GL statement or a keyboard accelerator.
The trigger code instructs Progress to find the next customer record and omit any error
messages. In the next line, Progress tests whether a customer record was found. If not,
Progress finds the last customer record and the terminal beeps. Finally, Progress displays
the contents of the Cust-Num, Name, and Phone fields in frame f and ends processing in
the block.
The next ON statement defines trigger code that Progress executes each time the user
applies a CHOOSE event to btn_2, the Prev button. This CHOOSE behavior applies only
to btn_2.
The trigger code instructs Progress to find the previous customer record and omit any error
messages. In the next line, Progress tests whether a customer record was found. If not,
Progress finds the first customer record and the terminal beeps. Finally, Progress displays
the contents of the Cust-Num, Name, and Phone fields in frame f and ends processing in
the block.
The last ON statement defines trigger code that Progress executes each time the user
applies a LEAVE event in the Phone field. This LEAVE behavior applies only to the
Phone field.
The trigger code instructs Progress to compare the current value in the Phone field to its
value in the database. If the two values are not the same, Progress moves the new Phone
data into the database, the terminal beeps, an information box appears and displays the
message Phone Number changed, and processing ends in this block.
212
The ENABLE statement places the Phone field on the screen with the Prev and Next
buttons in frame f. (When Progress executes this statement, frame f is viewed on the
screen.)
The WAIT-FOR statement establishes a WAIT-FOR condition for frame f. When the user
applies a GO event, the WAIT-FOR condition is satisfied.
2.4 When to Use the Procedure-driven and Event-driven Models
Choosing a programming model has a lot to do with the environment in which your application
runs. Progress supports both character and window interfaces for several operating system
environments.
Multi-tasking windowing systems, such as Microsoft Windows, offer many graphical interface
objects that are more intuitive for end users. In graphical interfaces, Progress supports the use
of colors, fonts, and direct manipulation (selecting, moving, and resizing) of screen objects by
the user. Attributes and methods for these objects provide visual feedback to the user. In this
environment, the user has access to multiple windows and can use a mouse and keyboard to
enter complex input to the program. Graphical interface objects are designed to receive events
from the operating system. Thus, if you plan to use these objects, you should use the
event-driven model.
Character interfaces, which Windows and UNIX provide, supply a few user interface objects,
including fields, text, and primitive graphics. In this environment, the user has access to only
one window at a time and uses the keyboard to enter input to the program. The program
processes the input behind the scenes and displays the final results as another stream of
characters on the users screen. In general, you should use the procedure-driven model
whenever a simple character interface is all your application requires.
Progress offers event-driven capabilities for both graphical and character environments.
Specifically, Progress provides versions of the graphical user interface objects for character
interfaces through its windowing system. Your application might combine elements of both
event-driven and procedure-driven design.
3
Block Properties
The Progress language is block structured, letting you group together parts of your procedures
into blocks. Blocks are useful in two significant ways:
You can use blocks to apply a se1est of characteristics to a group of statements rather than
applying the characteristics on a statement-by-statement basis.
Progress provides a wide range of automatic processing services for blocks.
This chapter describes:
The different kinds of blocks and their properties
Procedure properties
External procedures
Internal procedures
Persistent and non-persistent procedures
User-defined functions
Procedure overriding
32
3.1 Blocks and Their Properties
Progress provides the following types of blocks:
REPEAT blocks
FOR blocks
DO blocks
Procedure blocks
Trigger blocks
EDITING blocks
3.1.1 REPEAT, FOR, and DO Blocks
REPEAT, FOR, and DO blocks consist of a block header statement (REPEAT, FOR, or DO)
followed by zero or more statements terminated by an END statement. Each of these blocks can
contain any other type of block, except a procedure and trigger block. REPEAT, FOR, and DO
blocks execute wherever they appear in a procedure or trigger block.
3.1.2 Procedure Blocks
There are two types of procedure blocks: external and internal. An external procedure block
consists of a text file containing zero or more statements that you can compile into a unit and
that you can execute by name using the RUN statement. An external procedure is the most basic
block and can contain all other types of statements and blocks.
An internal procedure block consists of a PROCEDURE statement followed by one or more
statements terminated by an END statement that you can execute by name using a RUN
statement. An internal procedure is always compiled as part of an external procedure. An
internal procedure cannot contain other internal procedure blocks, but it can contain any other
type of statement or block that an external procedure can contain. For more information on
procedure blocks, see the Procedure Properties section.
Block Properties
33
3.1.3 Trigger Blocks
A trigger block consists of a single statement, or zero or more statements starting with DO and
ending with END, that defines a database trigger, user-interface trigger, or procedure trigger. It
appears as part of a user-interface widget or trigger definition, and can contain all other types of
blocks except procedure blocks. A trigger block executes in response to an event, depending on
the type of trigger. For more information on database triggers, see Chapter 11, Database
Triggers. For more information on user-interface triggers, see Chapter 16, Widgets and
Handles. For information on procedure triggers, see the External Procedures section in this
chapter.
3.1.4 EDITING Blocks
An EDITING block appears as the EDITING-phrase part of an input-blocking statement, such
as PROMPTFOR, SET, or UPDATE. It consists of the EDITING block header followed by
zero or more statements terminated by an END statement. This block executes once for each
key stroke received during execution of the input statement, and thus allows the application to
manage the input for each field one key stroke at a time.
NOTE: The EDITING block is maintained primarily for compatibility with earlier versions.
Event-driven applications generally use user interface triggers to manage user input.
For more information on EDITING blocks and user interface triggers, see Chapter 6,
Handling User Input.
3.1.5 Block Properties
Progress provides a different set of default processing services for each type of block. Table 31
shows what properties Progress associates with each type of block. Implicit properties are those
that come by default. Explicit properties are those that you can associate with the block by
adding Progress keywords, phrases, or statements to the block definition. The properties in this
table represent the basic properties associated with the type of block. Progress provides
additional properties depending on the block type.
Table 31: Block Properties (1 of 2)
Property REPEAT FOR DO
Procedure or
Trigger
Implicit Explicit Implicit Explicit Implicit Explicit Implicit Explicit
Looping YES WHILE
TO/BY
YES
5
WHILE
TO/BY
NO WHILE
TO/BY
NO NO
34
Record
reading
NO NO YES Record
Phrase
NO NO NO NO
Frame
scoping
YES WITH
FRAME
YES WITH
FRAME
NO WITH
FRAME
YES NO
Record
scoping
YES FOR YES NO NO FOR
YES
1
NO
UNDO YES TRANS
ACTION
ON
ERROR
YES TRANS
ACTION
ON
ERROR
NO TRANS
ACTION
ON
ERROR
YES N0
ERROR
processing
YES ON
ERROR
YES ON
ERROR
NO ON
ERROR
YES NO
ENDKEY
processing
YES ON
ENDKEY
YES ON
ENDKEY
NO ON
ENDKEY
YES NO
STOP
processing
YES
2
ON STOP
YES
2
ON STOP NO ON STOP YES NO
QUIT
processing
YES
2
ON QUIT
YES
2
ON QUIT NO ON QUIT YES NO
System
transaction
YES
2
TRANS
ACTION
3
YES
2
TRANS
ACTION
3
NO TRANS
ACTION
3
ON
ERROR
2
YES
2
NO
Parameter
Passing
NO NO NO NO NO NO NO
YES
1
1
A record is scoped to the containing .p unless you explicitly define the buffer in a trigger or internal procedure
2
Only if the block contains database updates or reads with exclusive locks and there is no higher level transaction active.
3
Only for procedure blocks.
4
Only for procedure blocks.
5
Using the EACH option.
Table 31: Block Properties (2 of 2)
Property REPEAT FOR DO
Procedure or
Trigger
Block Properties
35
Scope is one of the basic properties of all blocks. Scope is the duration that a resource is
available to an application, and blocks determine the scope of certain resources. For example,
records and certain types of frame definitions are automatically scoped to certain blocks (see
Table 31). Although you can place them in other blocks, local data and widget definitions are
always scoped to the smallest enclosing procedure block (internal or external). Similarly, the
compiler accepts a trigger or internal procedure block in most other blocks. However, trigger
definitions are scoped to the enclosing trigger or procedure block (internal or external) in which
they are defined, and internal procedure definitions are always scoped to the enclosing external
procedure block in which they are defined. Thus, an internal procedure defined in a REPEAT
block is actually defined only once (not for the number of times the block repeats), and is
available for execution anywhere in the external procedure.
The following sections explain the looping, record reading, frame scoping, and record scoping
block properties. For information on the UNDO, ERROR, ENDKEY, STOP, and QUIT
properties, see Chapter 5, Condition Handling and Messages. For information on
transactions, see Chapter 12, Transactions.
3.1.6 Looping
Looping, or iteration, is one of the automatic processing services that Progress provides for
blocks. REPEAT blocks and FOR EACH blocks iterate automatically and you can force a DO
block to iterate by using a DO WHILE, or a DO variable = expression1 TO expression2 [BY
k]. The following code fragments show iterations using these block statements:
p-bkchp.p
/* This REPEAT block loops through its statements until the user
presses the END-ERROR (F4) key. */
REPEAT:
PROMPT-FOR customer.cust-num.
FIND customer USING cust-num.
DISPLAY customer WITH 2 COLUMNS.
END.
p-bkchp2.p
/* This FOR EACH block reads the records from the customer
table one at a time, processing the statements in the
block for each of those records. */
FOR EACH customer:
END.
36
REPEAT and FOR EACH blocks iterate automatically. You can make a DO block iterate by
using the WHILE option or the TO option in the DO block header:
3.1.7 Record Reading
The FOR EACH block is the only block statement that automatically reads records each time it
iterates. The following examples demonstrate this:
You can be more specific about which records you want to read by using a record phrase in the
FOR EACH block header:
p-bkchp3.p
/* This block loops through its statements for the first 5 customers. */
DEFINE VARIABLE i AS INTEGER.
DO i = 1 TO 5:
FIND NEXT customer.
END.
p-bkchp4.p
/* This FOR EACH block reads the records from the customer
table one at a time, processing the statements in the
block for each of those records. */
FOR EACH customer:
END.
p-bkchp5.p
/* The record-spec (made up of a simple WHERE phrase in
this example) tells the FOR EACH block to read only
those records from the customer file that have a
credit-limit greater than 50,000. */
FOR EACH customer WHERE credit-limit > 50000:
END.
Block Properties
37
3.1.8 Frame Allocation
Each statement that displays data or prompts you to enter data uses a frame for display or input
of that data. A procedure can use many different frames. Progress uses these guidelines to
determine which frame a particular statement uses to display data:
If the statement explicitly names a frame, the statement uses that frame to display data.
If the statement does not explicitly name a frame, Progress displays the data in the default
frame for the block in which the statement occurs.
Progress automatically allocates a frame for REPEAT, FOR EACH, triggers, and procedure
blocks that display data. If you do not use the Frame phrase with these blocks, Progress creates
an unnamed frame. The unnamed frame is the default frame for the block. If you name a frame
in the block header, that frame becomes the default frame for the block and Progress does not
allocate an unnamed frame for that block. Progress scopes the frame named in the block header
statement to that block if it is the first block to reference the frame.
If you do not specify a default frame for a DO block in the block header, the default frame for
the DO block is the default frame for the nearest enclosing FOR EACH, REPEAT, trigger, or
procedure block, or the nearest enclosing DO block that explicitly names a frame.
Progress creates separate frames for DO blocks only if you specify a frame phrase in the DO
statement. If the frame phrase contains the FRAME keyword and names a new frame, then
Progress creates a separate frame and that frame is the default frame for the DO block. If the
frame phrase does not contain the FRAME keyword, then Progress creates a new unnamed
frame and that becomes the default frame for the DO block.
This procedure demonstrates frame allocation for the procedure block and a REPEAT
statement:
p-bkchp6.p
/* The default frame for the procedure block is an unnamed
frame.The first DISPLAY statement uses a different frame,
aaa.The default frame for the REPEAT block is bbb.The
PROMPT-FOR statement does not use the default frame for the
block;instead it uses frame aaa.The DISPLAY statement uses
the default frame for the REPEAT block. */
DISPLAY "Customer Display" WITH FRAME aaa.
REPEAT WITH FRAME bbb:
PROMPT-FOR customer.cust-num WITH FRAME aaa.
END.
38
In this procedure, Progress allocates frame aaa to the procedure block. This frame is not the
default frame for the procedure block. If a subsequent statement in the procedure block
displayed data without naming a frame, Progress would create an unnamed frame and it would
be the default frame for the procedure block. As it stands, the procedure block has no default
frame. The default frame for the procedure block is always an unnamed frame.
The default frame for the REPEAT block is frame bbb. Since the DISPLAY statement contained
within the REPEAT block does not specify a frame, it uses the default frame bbb.
Frame Scope
The scope of a frame is the outer-most block in which you reference that frame. (Hiding a frame
or setting its VISIBLE attribute does not scope the frame; nor does the DEFINE FRAME
statement.) The following procedure demonstrates this:
Progress scopes every frame to a block. Scoping a frame to a block does not make that frame
the default frame for the block. Progress automatically scopes frames to REPEAT, FOR EACH,
and procedure blocks. Progress only scopes frames to DO blocks if you indicate a new frame in
a frame phrase (DO WITH FRAME).
Frame Services
Progress provides these services for each of the frames scoped to a block:
Advancing
Hiding and viewing
Clearing
Retaining previously entered data during RETRY of a block
Progress determines when to provide these services based on the block to which it scopes the
frame. For more information on frame scoping, see Chapter 19, Frames.
p-bkchp7.p
/* The scope of frame aaa is the procedure block because
that is the first block that references frame aaa. */
REPEAT:
END.
Block Properties
39
Borrowed Frames
Any trigger or internal procedure can reference frames that are scoped to the containing
procedure. A user interface trigger for a frame or field-level widget automatically borrows the
frame for that widget from the containing procedure. This holds true even if the frame is the
default (unnamed) frame. This allows you to reference the field value within the trigger without
specifying the frame. You can borrow other frames by referencing them within the trigger or
internal procedure. For example, the following procedure contains several instances of
borrowed frames:
In p-borfrm.p, a LEAVE trigger is defined for the Creditlimit field in updframe. Because the
trigger borrows that frame, you do not have to qualify the field reference in the ASSIGN
statement with the frame name. The ON statement for the NEXTFRAME trigger of the Name
field explicitly references promptframe. Therefore, Progress assumes that frame when you
reference the Name field in the FIND statement. The DISPLAY and ENABLE statements
explicitly borrow the updframe from the outer procedure.
p-borfrm.p
FORM
Customer.Name LABEL "Search String"
WITH FRAME prompt-frame.
FORM
Customer.Name Customer.Credit-limit
WITH FRAME upd-frame.
ON NEXT-FRAME OF Customer.Name IN FRAME prompt-frame
DO:
FIND Customer USING Customer.Name.
DISPLAY Customer.Name Customer.Credit-limit WITH FRAME upd-frame.
ENABLE Customer.Credit-limit WITH FRAME upd-frame.
END.
ON LEAVE OF Customer.Credit-limit
ASSIGN Customer.Credit-limit.
STATUS INPUT "Press " + KBLABEL("NEXT-FRAME") + " to search; " +
KBLABEL("END-ERROR") + " to exit".
ENABLE Customer.Name WITH FRAME prompt-frame.
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.
310
3.1.9 Record Scoping
When Progress reads a record from the database, it stores that record in a record buffer. The
scope of the record is the portion of the procedure where that record buffer is active. Record
scope determines when Progress clears the record from the buffer, when it writes the record to
the database, and how long a record lock is in effect.
Generally, the scope of a record is the smallest enclosing block that encompasses all references
to the record. That is, the record is active until the block ends. However, there are exceptions to
this rule depending on whether the record is weak scoped, strong scoped, or introduced by a free
reference.
The exceptions are as follows:
A strong-scoped reference occurs for buffers that are referenced in the header of a
REPEAT FOR or DO FOR block. Any reference to that buffer within the REPEAT FOR
or DO FOR block is a strong-scoped reference.
A weak-scoped reference occurs for buffers that are referenced in the header of a FOR
EACH or PRESELECT EACH block. Any reference to that buffer within the FOR EACH
or PRESELECT block is a weak-scoped reference.
All other references to records are free references.
The general scoping rules are as follows:
If you have a strong-scoped reference to a buffer, you cannot reference that buffer in a
containing block. The buffer is always scoped to the strong-scope block. You can
however, have two sequential blocks that each contain strong-scoped references to the
same buffer.
If you have a weak-scoped reference to a buffer, you can reference that same buffer outside
the weak-scope block. This raises the scope of the buffer to the outer block. You cannot,
however, nest two weak-scope blocks for the same buffer. Also, a weak-scope block
cannot contain any free references to the same buffer.
If you have a free reference to a buffer, Progress tries first to scope that buffer to the
nearest enclosing block with record scoping properties. However, other references to the
same buffer outside that block cause Progress to raise the scope to a higher block.
Block Properties
311
The following example contains two DO FOR blocks that each contain a strong-scoped
reference to the customer buffer:
p-strscp.p
In p-strscp.p, the customer buffer is scoped to each of the DO FOR blocks. Because
strong-scoped blocks cannot be nested, you cannot change the outer DO to a DO FOR
customer.
You cannot make a free reference to the customer buffer outside the DO FOR block. For
example, the following code does not compile:
p-stscp2.p
If you try to compile p-stscp2.p, you get a compile error.
DO:
DO FOR customer:
DISPLAY cust-num name WITH FRAME a.
END.
DO FOR customer:
FIND NEXT customer.
DISPLAY cust-num name WITH FRAME b.
END.
END.
Strong scope
Strong scope
/* This code cannot compile. */
DO:
DO FOR customer:
DISPLAY cust-num name.
END.
FIND NEXT customer.
END.
Invalid free reference
Strong scope
312
The following example contains two FOR EACH blocks that each contain a weak-scoped
reference to the customer buffer:
p-wkscp.p
In p-wkscp.p, the customer buffer is scoped to each of the FOR EACH blocks. However,
because these blocks apply a weak scope, you can reference the buffer outside these blocks and
Progress automatically enlarges the scope. For example, the following procedure contains a
weak-scope reference and a free reference to the customer buffer:
p-wkscp1.p
In p-wkscp1.p, the scope of the customer buffer is referenced in the FOR EACH block, but a
free reference also occurs outside the FOR EACH block. The scope is raised to the procedure
block.
DO:
FOR EACH customer:
END.
FOR EACH customer:
END.
END.
Weak scope
Weak scope
FOR EACH customer:
END.
DISPLAY customer.cust-num name WITH FRAME b.
Scope raised to
procedure
Block Properties
313
You cannot nest two blocks that apply a weak scope to the same buffer. For example, the
following code does not compile:
p-wkscp2.p
You can however, enclose a weak-scoping block within a strong-scoping block, as in the
following example:
p-wkspc3.p
In p-wkscp3.p, the scope of the customer buffer is raised from the weak-scope FOR EACH
block to the strong-scope DO FOR block.
/* This code does not compile. */
DEFINE VARAIBLE saved-rep LIKE customer.sales-rep.
DO:
FOR EACH customer:
saved-rep = customer.sales-rep.
FOR EACH customer:
IF customer.sales-rep = saved-rep
THEN DISPLAY cust-name WITH FRAME a.
DOWN WITH FRAME a.
END.
END.
END.
Weak
scope
Nesting weak
scope not
allowed
DO FOR customer:
FOR EACH customer:
END.
END.
Weak scope
Scope raised
to DO FOR
block
314
You can also have sequential strong-scope and weak-scope blocks for the same record, as in the
following example:
p-wkstr.p
Note that the scope is not raised in p-wkstr.p. Instead, the DO FOR and FOR EACH blocks
each scope the customer record separately. A reference to the customer buffer outside these
blocks would be invalid and would cause a compiler error.
Any reference that is neither a strong-scope reference nor a weak-scope reference is a free
reference. For example, the following code contains two free references to the customer buffer:
p-frref1.p
In p-frref1.p, the first free reference occurs within the REPEAT block. Progress initially tries
to scope the customer buffer to that block. However, because another free reference occurs after
the REPEAT block, Progress raises the scope to the procedure.
DO FOR customer:
END.
FOR EACH customer:
END.
Weak scope
Strong scope
REPEAT:
FIND NEXT customer.
LEAVE.
END.
FIND NEXT customer.
Scope raised to procedure
Block Properties
315
The following example also contains two free references to the customer buffer. However, in
this case each reference is enclosed in a REPEAT block:
p-frref2.p
In this case, Progress still raises the scope to the procedure block. This means that the first
iteration of the second REPEAT block finds the second customer record.
To determine the scope of a block, compile your procedure using the LISTING option. For
example, to compile the p-frref2.p procedure, issue this command:
COMPILE p-frref2.p LISTING p-frref2.out.
REPEAT:
FIND NEXT customer.
LEAVE.
END.
REPEAT:
FIND NEXT customer.
END.
Scope raised to procedure
316
The p-frref2.out argument specifies the file in which you want Progress to store the listing
information. You can use any valid filename. When you view this file, you see the following
screen:
This listing shows that the buffer sports.customer is scoped to the procedure block.
p-frref2.p PROGRESS(R) Page 1
{} Line Blk
-- ---- ---
1 1 DO:
2 2 REPEAT:
3 2 FIND NEXT customer.
4 2 DISPLAY cust-num name WITH FRAME a.
5 2 LEAVE.
6 1 END.
7 1
8 2 REPEAT:
9 2 FIND NEXT customer.
10 2 DISPLAY cust-num name WITH FRAME b.
11 1 END.
12 1
13 END.
p-frref2.p PROGRESS(R) Page 2
File Name Line Blk. Type Tran Blk. Label
-------------------- ---- --------- ---- --------------------------------
p-frref2.p 0 Procedure No
Buffers: sports.Customer
p-frref2.p 1 Do No
p-frref2.p 2 Repeat No
Frames: a
p-frref2.p 8 Repeat No
Frames: b
Block Properties
317
Record scoping provides several services. The scope of a record tells Progress:
When to write the record to the database. Progress automatically writes a modified record
to the database at the end of the record scope, as shown in this procedure.
When to release a record for use by other users in a multi-user system. Progress releases a
record at the end of each iteration of the block to which the record is scoped. Whether the
record will then be available for other users depends on the type of lock on the record and
on whether a transaction is still active. See Chapter 12, Transactions and Chapter 13,
Locks for more details.
When to validate the record against any unique index and mandatory field criteria defined
in the Dictionary.
When to reinitialize the current position within an index. Progress maintains this position
for each index used within a records scope. The position is initialized upon entry to the
block to which the record is scoped.
How to resolve references to unqualified field names. Within a records scope, you can use
field names (without specifying the table) to refer to fields that do not share a name with
fields in other tables in the database. You must include the table name when you reference
fields of the same name from two or more tables.
3.1.10 Transactions
A transaction is a set of changes to the database that is either executed completely or leaves no
modification to the database. A subtransaction is nested in a transaction and encompasses all
activity within one iteration of the following kinds of blocks: DO ON ERROR, FOR EACH,
procedure, REPEAT, and triggers. Table 32 shows which kinds of blocks start transactions and
subtransactions.
p-bkchpa.p
/* On each iteration of the loop, the FOR EACH statement reads a
single record from the database into the record buffer. The scope
of the record is the FOR EACH block because that is the outermost
block that references the record. At the end of the record scope,
which is the end of the iteration that uses that record, Progress
writes the record to the database. */
FOR EACH customer:
UPDATE customer WITH 2 COLUMNS.
END.
318
For more information on transactions, see Chapter 12, Transactions.
When an error occurs, Progress performs differently depending on the context. Progresss error
processing allows you to accept default action depending on the type of error, or to define the
error behavior yourself. The following section discusses error processing.
3.1.11 Error Processing
Progresss error processing depends on what type of error is generated. Progress recognizes the
following errors:
A procedure-generated error
A predefined error key
A predefined ENDKEY key
The ENDERROR key
A system or software failure
The STOP key
Table 32: Starting Transactions
Type of
Block
Transaction
Not Active
Transaction
Active
DO TRANSACTION
FOR EACH TRANSACTION
REPEAT TRANSACTION
Any DO ON ENDKEY, DO ON
ERROR, FOR EACH, REPEAT, or
procedure block that contains
statements that modify the database
or that read records using an
EXCLUSIVELOCK.
Starts a transaction Starts a subtransaction
Any FOR EACH, REPEAT, or
procedure block that does not contain
statements that modify the database
or read records using an
EXCLUSIVELOCK.
Does not start a
transaction
Starts a subtransaction
Block Properties
319
Progress performs default processing when it encounters these errors. When Progress
encounters a procedure error or the user presses a predefined error key, Progress performs an
UNDO, RETRY. When the user presses a predefined endkey, Progress performs an UNDO,
LEAVE. When the user presses ENDERROR, Progress performs an UNDO, LEAVE if the
user has not entered any keyboard events, and an UNDO, RETRY if they have. When the user
presses STOPS, Progress undoes the current transaction and retries the startup procedure. When
the system fails, Progress undoes any partially completed transactions for all users on the
system.
For more information on how Progress handles errors and how you can handle errors within the
4GL, see Chapter 5, Condition Handling and Messages.
3.2 Procedure Properties
The procedure is the fundamental block in Progress. All types of procedures, external and
internal, have certain common properties:
They can contain all other types of blocks.
You can execute them by name using the RUN statement.
They can accept run-time parameters for input or output.
They can define their own data and user interface environment (context) with restrictions
depending on the type of procedure.
They can share data and widgets defined in the context of another procedure, with
restrictions depending on the type of procedure.
They can execute recursively. That is, they can run themselves in a new context.
You can nest most blocks within a procedure. For example, you can include a DO, FOR, or
REPEAT block within another DO, FOR, or REPEAT block. The number of times that you can
nest blocks depends on your setting of the Nested Blocks (nb) startup parameter. The default
depth is 50. For more information on nb, see the Progress Startup Command and Parameter
Reference.
Depending on the type of procedure, you can define any number of local objects within its
context, including buffers, temporary tables, queries, variables, I/O streams, frames, and many
other widgets. You can reference each one of these objects within the procedure after it is
defined. In addition, you can share or pass many of these objects among procedures in different
ways.
320
The actual content of a procedures context and how it is managed depends on whether the
procedure is an external or internal procedure, and on how you define and execute it.
3.3 External Procedures
There are actually two types of external procedures: non-persistent and persistent. Most of this
section applies to both. For information on persistent procedures and how they differ from
non-persistent procedures, see the Persistent and Non-persistent Procedures section.
The external procedure is the most basic procedure. It can contain a single 4GL statement, many
statements, or it can be an empty file. Its main characteristic is that it is a block of code that can
be created, stored, and compiled separately from all other procedures as an operating system
file. As such, you can run call an external procedure from any other procedure by specifying its
filename in a RUN statement:
3.3.1 Procedure Filenames
You can specify filename using any of these forms:
The unquoted name of the procedure file.
VALUE(charexpression), where charexpression is any character expression equal to
the procedure filename.
An unquoted reference to an r-code library member. For more information on r-code
libraries and how to reference them, see the Progress Client Deployment Guide.
For example, this statement runs the procedure file p-exprc2.p, listed later in this section:
NOTE: When Progress encounters a RUN statement, it first searches for an available internal
procedure whose name matches filename. If it cannot find a matching internal
procedure, it then tries to find the external procedure. For more information on
internal procedures, see the Internal Procedures section.
SYNTAX
RUN filename [ runoptions ]
RUN p-exprc2.p.
Block Properties
321
Because an external procedure is an operating system file, the maximum length and
composition of an external procedure filename depends on your operating system. By
convention, procedure source files end with a .p or .w extension. The compiled versions of
procedure files, r-code files, must end with a .r extension. If you specify the name of a source
file, Progress tries to find and execute the corresponding r-code file before compiling and
executing the source file.
Progress also imposes additional limits to promote compatibility between versions of operating
systems like UNIX. For more information on the length and composition of external procedure
names, see the section on Progress limits in the Progress Client Deployment Guide.
3.3.2 Standard Execution Options
The runoptions of the RUN statement can include run-time parameters, compile-time
arguments, and the NOERROR option for handling run-time errors. For information on the
NOERROR option, see Chapter 5, Condition Handling and Messages.
Run-time parameters include comma-separated data items enclosed in parentheses. Each data
item is preceded by INPUT, OUTPUT, INPUTOUTPUT, or BUFFER, corresponding to the
type of parameter defined by the DEFINE PARAMETER statement in the procedure. In
general, the data items passed in the RUN statement must match, in data type and order, the
corresponding parameters defined in the called procedure. For more information on run-time
parameters, see the examples and the paragraphs on procedure parameters that follow.
Compile-time arguments consist of any space-separated strings that you want to pass to the
procedure at compile time. When executed with compile-time arguments, Progress
automatically recompiles the procedure, substituting each argument for {n} in the 4GL, where
n is an integer specifying the ordinal position of the argument in the RUN statement, starting at
1. Compile-time arguments must follow any run-time parameters in the statement. You can only
specify compile-time arguments when running external procedures.
3.3.3 Examples
This is an external procedure that displays the names of all the customers in the sports database,
sorted by name.
NOTE: Any statement or group of statements that you enter in a Procedure Editor buffer
become an external procedure when you save or execute the buffer. Also, all the
procedure files saved by AppBuilder are external procedures. For information on the
FOR EACH customer BY name: DISPLAY name.
322
NOTE: Procedure Editor, see the Progress Basic Database Tools (Character only) manual,
and in graphical interfaces, the on-line help for the Procedure Editor. For information
on the AppBuilder, see the Progress AppBuilder Developers Guide.
This is an external procedure that returns, as an output parameter, the name of a customer in the
sports database when given a customer number as an input parameter. If the specified customer
does not exist, the procedure returns the unknown value (?) as the customer name:
This external procedure calls p-exprc1.p with a user-specified customer number and displays
the resulting customer name in a message. Note that p-exprc2.p is a top-level,
application-driven procedure:
For more information on the application- and event-driven models, the two basic techniques for
writing Progress applications, see Chapter 2, Programming Models.
p-exprc1.p
DEFINE INPUT PARAMETER pcust-num LIKE customer.cust-num.
DEFINE OUTPUT PARAMETER pname LIKE customer.name INITIAL ?.
FOR EACH customer:
IF customer.cust-num = pcust-num THEN DO:
pname = customer.name.
RETURN.
END.
END.
p-exprc2.p
DEFINE VARIABLE vcust-num LIKE customer.cust-num INITIAL 0.
DEFINE VARIABLE vname LIKE customer.name.
DO WHILE NOT vcust-num = ?:
SET vcust-num LABEL "Customer Number" WITH SIDE-LABELS.
IF NOT vcust-num = ? THEN DO:
RUN p-exprc1.p (INPUT vcust-num, OUTPUT vname).
MESSAGE "Customer" vcust-num "is" vname + ".".
END.
END.
Block Properties
323
3.3.4 Procedure Parameters
A procedure parameter passes a value to a procedure or returns a value from a procedure at run
time. To define a parameter for a procedure, you specify the DEFINE PARAMETER statement
in the procedure block. This statement can appear anywhere before you first reference the
parameter in the procedure. The required information you specify in the DEFINE
PARAMETER statement includes:
The name you use to reference the parameter in the procedure.
How the parameter is used: for input, output, both input-output, or to pass a buffer.
The data type of the parameter.
Input parameters pass data to a procedure when it is called, and output parameters return data
from the called procedure to the calling procedure when the called procedure completes
execution. Buffers are always passed for input-output. In general, the data items passed in the
RUN statement must match, in data type and order, the corresponding parameters defined in the
called procedure.
In the previous examples, the RUN statement in p-exprc2.p passes vcustnum and vname to
the parameters pcustnum and pname, respectively in p-exprc1.p. For more information on
procedure parameters, see the Progress Language Reference.
3.3.5 Procedure Context and the Procedure Call Stack
In the previous examples, when p-exprc2.p calls p-exprc1.p, p-exprc2.p waits on the
procedure call stack until p-exprc1.p completes execution and returns. The procedure call
stack is an internal memory structure that Progress uses to keep track of procedure context and
scope. When one procedure calls another, Progress saves the context of the calling procedure
on the call stack. The called procedure then establishes the new current context. When the called
procedure returns, Progress re-establishes the context of the calling procedure as the current
context.
NOTE: Triggers also execute and interact with the call stack like procedures. When a trigger
executes in response to an event, its context becomes the current context. For more
information, see Chapter 11, Database Triggers.
324
Figure 31 shows how the procedure call stack maintains procedure context and scope in a
Progress client. It shows an application, your-app.p, running from the Procedure Editor, which
is also on the stack. As each procedure calls the next, its context is saved on the stack.
Figure 31: Procedure Call Stack
Progress can save any number of procedures on the call stack (that is, you can nest any number
of procedure calls), depending on the size of each saved context and the size of the call stack.
The size of the context depends on the size and number of definitions created and maintained
by the procedure. The size of the call stack depends on the setting of the Nested Blocks (nb)
startup parameter and the Stack Size (s) startup parameter (in 1K units). The default for nb is
50 and the default for s is 40. For more information on nb and s, see the Progress Startup
Command and Parameter Reference.
NOTE: There is a distinction between procedure scope and context. While the procedure
context is the actual environment in which a procedure executes, the procedure scope
is the duration that its context remains available to the application. For example, in
Figure 31, while the context of your-app.p and subprc1.p might be invisible to
each other, subprc1.p remains within the scope of your-app.p.
Progress Client
edit.p
subprc1.p
subprc1a.p
your-app.p
_proedit.p
Procedure
Call Stack
subexec.p
.
.
.
Block Properties
325
3.3.6 Shared Objects
In general, without procedure parameters, the context of a called external procedure is invisible
to the calling procedure. For example, p-exprc2.p (in the previous examples) cannot directly
access the customer buffer defined in p-exprc1.p. Also for external procedures, the context of
the calling procedure is generally invisible to the called procedure. In other words, a procedures
context is generally local to itself. However, external procedures can pass information and
resources among them using shared objects (data, streams, or user interface widgets).
Scoped Versus Global
There are two kinds of shared objects: scoped and global. A scoped shared object is accessible
from the point of creation only for the scope of the procedure that first defines it. A global
shared object is accessible from the point of creation until the end of the Progress session. Thus
a called procedure can reference a scoped shared object that is created by a calling procedure
(or any other procedure still on the call stack) prior to the call. Any procedure can access a
global shared object after it is created.
NOTE: Any scoped shared objects created or referenced in the context of a persistent
procedure remain available as long as the procedure persists. For more information,
see the Persistent and Non-persistent Procedures section.
Figure 32 shows how you can reference scoped and global shared objects outside of the
procedure context in which they are created. (By definition, a procedure can reference any
shared object created in its own context.) The Main Procedure starts out by creating scoped
shared object A. It subsequently calls Subprocedure 1, which creates global shared object B and
scoped shared object C. Subprocedure 1 calls Subprocedure 2 and the Main Procedure
subsequently calls Subprocedure 3.
326
Figure 32: Object Sharing Among External Procedures
All the procedures can reference A because it is created in the Main Procedure, before any
subprocedures are called. All procedures except the Main Procedure can reference B even
though it is created in a subprocedure, because B is global. Note that the Main Procedure cannot
reference global B, because when the Main Procedure is compiled, B has not yet been created.
Subprocedure 2 is the only procedure that can reference all of shared objects A, B, and C
because it is called within the scope of scoped objects A and C. Subprocedure 3 can only
reference A and B, because C is out of scope.
Thus, a scoped shared object is accessible to any procedure, as long as the initial procedure that
creates the object is still in scope. A global shared object is accessible to any procedure as long
as the initial procedure that creates the object has executed prior to the first reference to the
object, whether or not the initial procedure is still in scope.
Create Scoped A
Subprocedure 1
Create Global B
Create Scoped C
Reference A
Subprocedure 3
Reference A
Subprocedure 2
Reference B
Reference A
Reference C
Time
Main Procedure
Reference B
Block Properties
327
Defining and Referencing
Any object defined using the NEW SHARED option in its DEFINE statement creates a scoped
shared object. Any object defined using the NEW GLOBAL SHARED option creates a global
shared object. Any object defined using the SHARED option (without NEW or GLOBAL)
creates a reference to a previously created scoped or global shared object. Currently, the only
objects that can be globally shared are variables and streams. For example, the following
procedures define and use both scoped and global shared variables:
Procedure p-share1.p defines a scoped shared variable (sharedvar) that p-share2.p and
p-share3.p can reference, and p-share2.p defines a global variable (globvar) that p-share3.p
can reference. Note that p-share1.p cannot reference globvar because p-share1.p compiles
and references any variable before p-share2.p can define it.
For information on shared buffers, see Chapter 9, Database Access, in this manual, and on
shared streams, see Chapter 7, Alternate I/O Sources. Any other Progress objects that include
the NEW and SHARED keywords in their definition can also be shared. For more information,
see the DEFINE statement for the objects in the Progress Language Reference.
p-share1.p
DEFINE NEW SHARED VARIABLE sharedvar AS CHARACTER INITIAL "Shared".
RUN p-share2.p.
RUN p-share3.p.
p-share2.p
DEFINE NEW GLOBAL SHARED VARIABLE globvar AS CHARACTER INITIAL "Global".
DEFINE SHARED VARIABLE sharedvar AS CHARACTER.
DISPLAY sharedvar + " in p-share2.p." FORMAT "x(22)" WITH NO-LABELS.
p-share3.p
DEFINE SHARED VARIABLE sharedvar AS CHARACTER.
DEFINE SHARED VARIABLE globvar AS CHARACTER.
DISPLAY sharedvar + " in p-share3.p." FORMAT "x(22)" SKIP
globvar + " in p-share3.p." FORMAT "x(22)" WITH NO-LABELS.
328
3.3.7 Procedure Handles
A procedure handle is a value that identifies the context of an external procedure. Every active
external procedure has a procedure handle associated with it. The THISPROCEDURE system
handle returns the current procedure handle value as a HANDLE data type from within any
executing block of an external procedure.
NOTE: A system handle, like a function, returns the handle to a Progress widget, procedure,
or other system object. For more information on system handles, see Chapter 16,
Widgets and Handles.
Procedure handles have attributes that you can use to store and retrieve information on the
particular procedure. These attributes are especially useful for working with persistent
procedures. For information on the attributes of a procedure handle, see the
THISPROCEDURE System Handle reference entry in the Progress Language Reference. For
information on referencing attributes, see Chapter 16, Widgets and Handles, in this manual.
For information on using procedure attributes with persistent procedures, see the Persistent and
Non-persistent Procedures section.
Procedure Triggers
You can also use the THISPROCEDURE handle to define and execute local procedure triggers
and internal procedures from anywhere in your application. A procedure trigger is a block of
code defined with the ON statement that executes in response to an event applied to the
specified procedure handle. For more information on internal procedures and how to execute
them using procedure handles, see the Internal Procedures section.
This is the basic syntax to define a procedure trigger:
The eventlist can be any comma-separated list of Progress event names you choose, from
keyboard to high-level widget events. For lists of keyboard events see Chapter 6, Handling
User Input. For lists of all other events, see the Progress Language Reference. The
procedurehandle can specify any valid procedure handle value, but you generally use the
THISPROCEDURE system handle for the current procedure. The block can be a single
statement or a DO block.
NOTE: Progress processes events for procedure triggers with no interpretation. Although
you must use a Progress-supplied event name to specify a procedure event, the name
is used only to identify the trigger block for execution.
SYNTAX
ON event-list OF procedure-handle block
Block Properties
329
You can store and pass the procedurehandle to other external procedures using parameters,
shared variables, and shared temporary table fields defined with the HANDLE data type. As
long as the specified external procedure remains in scope, other procedures can use this handle
to execute procedure triggers and internal procedures defined in the specified procedure.
NOTE: A procedure handle value remains valid only as long as the specified procedure is in
scope. Once the procedure goes out of scope, the specified value is invalid and can
be reused. You can use the VALIDHANDLE function and TYPE procedure handle
attribute to test whether a procedure handle value is valid. The TYPE attribute must
return PROCEDURE to filter out any re-use as a widget handle.
Applying Events to Procedure Triggers
You can execute a procedure trigger anywhere in an application using the APPLY statement
with this syntax:
The event can be a character expression that evaluates to any event name specified in the
eventlist of a trigger for procedurehandle. The procedurehandle must be a valid procedure
handle value for which the specified trigger has been defined.
This example is an external procedure that defines and executes its own procedure trigger,
displaying the message Hi!. The phandle variable is for illustration. You can also use
THISPROCEDURE directly in the ON and APPLY statements:
Your decision whether to use procedure triggers or internal procedures to execute code in an
external procedure context is design dependent. In general, internal procedures provide the
greatest flexibility, because you can reference them by any name you define and you can pass
them run-time parameters. Internal procedures can also map directly to Windows dynamic link
library (DLL) functions.
SYNTAX
APPLY event TO procedure-handle
DEFINE VARIABLE phandle AS HANDLE.
phandle = THIS-PROCEDURE.
ON RETURN OF phandle MESSAGE "Hi!".
APPLY "RETURN" TO phandle.
330
3.4 Internal Procedures
An internal procedure is a block of code defined within an external procedure that you can
execute by name within the context of the containing external procedure. Internal procedures
allow you to modularize your code and reduce the number of external files in an application. A
single external procedure (.p or .w) can contain any number of internal procedures.
NOTE: There are actually two types of internal procedure: 4GL and DLL internal
procedures. This section applies mainly to 4GL internal procedures. DLL internal
procedures provide access to DLL functions on Windows. While DLL internal
procedures execute different code than 4GL internal procedures, you call them by
name in the same way as any 4GL internal procedure. For more information on
defining and using DLL internal procedures, see the Progress External Program
Interfaces manual.
3.4.1 Internal Procedure Definition
This is syntax to define an internal 4GL procedure block:
You can terminate the PROCEDURE statement with a period or a colon. The maximum length
of an internal procedure name is context dependent. In general, it is not limited by operating
system or the 32 character maximum for variable names. For more information on internal
procedure name length and composition, see the Progress Client Deployment Guide.
The block can contain one or more of any Progress statement except another PROCEDURE
statement. The block can also be empty.
NOTE: You cannot define an internal procedure within another. Only an external procedure
can contain internal procedures.
SYNTAX
PROCEDURE name :
block
END [ PROCEDURE ] .
Block Properties
331
3.4.2 Internal Procedure Execution
You execute an internal procedure using the RUN statement with this syntax:
You can invoke the RUN statement for an internal procedure at the following points in an
application:
From the containing external procedure.
From any internal procedure (including itself) in the containing external procedure.
From any other external procedure using the IN handle option, where handle specifies a
containing external procedure that is in scope. The IN handle option is described later in
this section.
3.4.3 Internal Procedure Names
You can specify procname using any of these forms:
The unquoted name of the internal procedure as specified in the PROCEDURE statement.
VALUE(charexpression), where charexpression is any character expression equal to
the name of the internal procedure as specified in the PROCEDURE statement.
In general, when Progress encounters a RUN statement, it first searches the available internal
procedures for procname. If it cannot find the specified internal procedure and the RUN
statement does not use the IN option, Progress tries to find an external procedure in either r-code
or source code form that matches procname. For more information on external procedures and
r-code, see the External Procedures section.
3.4.4 Standard Execution Options
The runoptions can include the same run-time parameters and NOERROR option, as in
external procedures. However, you cannot pass compile-time arguments {n} to an internal
procedure because internal procedures are always compiled as part of the containing external
procedure. Thus, you must specify any compile-time arguments used in an internal procedure
definition when you call the containing external procedure that defines it. For more information
on compile-time arguments, see the External Procedures section.
SYNTAX
RUN proc-name [ IN handle ] [ run-options ]
332
3.4.5 Internal Procedures and Encapsulation
The IN handle option allows you to execute an internal procedure that is defined in any external
procedure context. The handle can be any field, variable, parameter, system handle, or attribute
expression that returns a valid procedure handle. This capability promotes code re-use and
encapsulation. Encapsulation is a technique of modular design where you hide (encapsulate)
related data and functionality from other external procedures and provide all access to the
hidden data through internal procedures defined by the hidden context. It also allows you to
break up a larger external procedure into several smaller ones, especially if you encounter
r-code segment limits (see Appendix A, R-code Features and Functions). For more
information on procedure handles, see the External Procedures section.
Valid Procedure Handles
To be valid, the procedure handle must identify one of the following external procedures that
also defines the internal procedure you want to execute:
The currently executing procedure or any procedure waiting on the call stack.
A persistent procedure.
In short, the procedure handle must identify the context of a procedure that is still in scope when
you execute the internal procedure. For more information on procedure context, procedure
scope, and the procedure call stack, see the External Procedures section.
NOTE: You can use the VALIDHANDLE function and the TYPE procedure handle
attribute to test whether a procedure handle identifies an active procedure context.
VALIDHANDLE returns TRUE if the specified procedure context is in scope. The
TYPE attribute must also return PROCEDURE to filter out valid widget handles.
For information on persistent procedures and how to obtain procedure handles for them, see the
Persistent and Non-persistent Procedures section. Otherwise, your procedure handle must be
set to the THISPROCEDURE system handle within the external procedure that contains the
internal procedure you want to execute.
Block Properties
333
Condition Handling
Internal procedures executed with the IN handle option raise ERROR on the RUN statement for
the following conditions:
The handle value is invalid.
The specified internal procedure does not exist in the procedure specified by handle.
Run-time parameters do not match the internal procedure definition.
You can trap these ERROR conditions using the NOERROR option of the RUN statement.
3.4.6 Shared and Local Context
Internal procedures are part of the context of the containing external procedure. An internal
procedure can access anything in the containing procedures context, including shared objects
and run-time parameters passed to the containing procedure. Also, like external procedures, the
local context of an internal procedure is generally invisible to the procedure that calls it. In other
words, while the containing procedures context is visible to the internal procedures context,
the local context of the internal procedure is invisible to the containing procedure.
While an internal procedure can access shared objects defined in the containing procedure, you
cannot introduce any shared object definitions in the internal procedure itself. For example, the
statement DEFINE NEW SHARED FRAME results in a compiler error.
In addition, you cannot define local or shared streams, temporary tables, or work tables in an
internal procedure. However, you can define local variables, queries, user-interface widgets,
and buffers within an internal procedure.
Progress scopes buffers defined in an internal procedure to that procedure. When the procedure
ends, you can no longer access those buffers. An internal procedure can also reference buffers
from a containing procedure.
334
Progress follows these steps to resolve buffer references:
1 Progress searches for a defined buffer that satisfies the reference, looking first in the local
procedure. If it does not find the defined buffer, it searches for it in the containing
procedure.
2 If Progress cannot find an explicitly defined buffer, it looks for other references to the
same implicit buffer. Progress looks first in the local procedure. If it does not find an
implicit reference, it searches for an implicit reference in the containing procedure.
3 If Progress cannot find an existing implicit reference to the same buffer, it tries to create a
new implicit buffer. Progress scopes the new buffer to the procedure block of the
containing procedure file.
An internal procedure has its own frame list and can reference by name any frame already
named in the containing procedure. Progress resolves references to named frames by first
looking in the internal procedure, then looking through the frames named in the containing
procedure. If it finds none, the internal procedure gets a new local frame. A frame scoped to the
containing procedure and used in the internal procedure is a borrowed frame. The internal
procedure can add fields to a borrowed frame but cannot use a local program variable in any of
the frames expressions. This is because Progress might evaluate a borrowed frames
expressions outside the scope of the internal procedure.
Block Properties
335
3.4.7 Examples
The following external procedure defines and calls three internal procedures. The external
procedure p-intprc.p runs the internal procedure getcust for each customer number you enter.
The internal procedure getcust runs getord and getord runs getitem. The result is that you see
the orderline and item information if the customer exists and has orders:
p-intprc.p
DEFINE BUFFER cust_buf FOR customer.
DEFINE BUFFER ord_buf FOR order.
DEFINE VARIABLE t-i-cust-num LIKE customer.cust-num.
DEFINE VARIABLE t-i-item-num LIKE item.item-num.
REPEAT:
UPDATE t-i-cust-num.
RUN getcust.
END.
PROCEDURE getcust:
FIND FIRST cust_buf WHERE cust_buf.cust-num = t-i-cust-num NO-ERROR.
IF NOT AVAILABLE cust_buf
THEN DO:
MESSAGE "Customer not found.".
RETURN ERROR.
END.
ELSE DO:
FIND FIRST ord_buf OF cust_buf NO-ERROR.
IF AVAILABLE ord_buf
THEN RUN getord.
ELSE MESSAGE "No orders for customer.".
END.
END PROCEDURE. /* getcust */
PROCEDURE getord:
FOR EACH order-line OF ord_buf:
DISPLAY order-line WITH FRAME foo.
t-i-item-num = order-line.item-num.
RUN getitem.
END.
END PROCEDURE. /* getord */
PROCEDURE getitem:
FIND FIRST item WHERE item.item-num = t-i-item-num.
DISPLAY cust_buf.cust-num cust_buf.name item.item-num item.item-name
WITH FRAME foo1.
END PROCEDURE. /* getitem */
336
The next two procedures duplicate the functionality of p-intprc.p by separating the internal
procedures and the update loop into separate external procedures. The procedure defining the
internal procedures, p-inprc1.p passes its procedure handle to p-exprc3.p. Thus, p-exprc3.p
runs getcust in p-inprc1.p:
p-inprc1.p
DEFINE BUFFER cust_buf FOR customer.
DEFINE BUFFER ord_buf FOR order.
DEFINE VARIABLE t-i-item-num LIKE item.item-num.
RUN p-exprc3.p (INPUT THIS-PROCEDURE).
PROCEDURE getcust:
DEFINE INPUT PARAMETER t-i-cust-num LIKE customer.cust-num.
FIND FIRST cust_buf WHERE cust_buf.cust-num = t-i-cust-num NO-ERROR.
IF NOT AVAILABLE cust_buf
THEN DO:
MESSAGE "Customer not found.".
RETURN ERROR.
END.
ELSE DO:
FIND FIRST ord_buf OF cust_buf NO-ERROR.
IF AVAILABLE ord_buf
THEN RUN getord.
ELSE MESSAGE "No orders for customer.".
END.
END PROCEDURE. /* getcust */
PROCEDURE getord:
FOR EACH order-line OF ord_buf:
DISPLAY order-line WITH FRAME foo.
t-i-item-num = order-line.item-num.
RUN getitem.
END.
END PROCEDURE. /* getord */
PROCEDURE getitem:
FIND FIRST item WHERE item.item-num = t-i-item-num.
DISPLAY cust_buf.cust-num cust_buf.name item.item-num item.item-name
WITH FRAME foo1.
END PROCEDURE. /* getitem */
Block Properties
337
3.4.8 Internal Procedures and the Call Stack
Note that, like external procedures, Progress moves internal procedures on and off the procedure
call stack as they call other procedures. For more information on the procedure call stack, see
the External Procedures section.
3.5 Persistent and Non-persistent Procedures
An external procedure can be either non-persistent or persistent. A non-persistent procedure
creates and maintains its context only until it returns from execution. In other words, the context
of a non-persistent procedure remains in scope only until the RUN statement that executes it
completes. An external procedure is non-persistent by default.
A persistent procedure creates its context when it executes and then maintains that context after
it returns until the end of the Progress session, or until it is explicitly deleted. In other words,
the context of a persistent procedure remains in scope after the RUN statement that executes it
completes until you remove it. Thus, as long as its context is in scope, the triggers and internal
procedures of a persistent procedure remain available for execution by your application. An
external procedure creates a persistent context when you execute it using a RUN statement with
the PERSISTENT option.
NOTE: If you run an application that creates persistent procedures from an ADE tool, that
tool (for example, the Procedure Editor or User Interface Builder) removes all
instances of persistent procedures still created when the application terminates.
p-exprc3.p
DEFINE INPUT PARAMETER db-procs AS HANDLE.
DEFINE VARIABLE t-i-cust-num LIKE customer.cust-num.
REPEAT:
UPDATE t-i-cust-num.
RUN getcust IN db-procs (INPUT t-i-cust-num).
END.
338
3.5.1 Advantages of Persistent Procedures
Persistent procedures promote modular application design and development by more easily
allowing you to distribute functionality among several procedures. For example, you might
build a persistent procedure that provides access to a database through a set of local buffers that
it otherwise hides from the rest of the application. Or your persistent procedure might create and
manage its own windows while allowing independent access (non-modal access) to other
windows in your application. Aside from helping to manage functionality, the additional
modularity also helps to avoid hitting r-code segment limits.
Thus, creating a persistent procedure whose context you access through internal procedures
provides the most effective means to achieve encapsulation in Progress. For more information
on using internal procedures to promote encapsulation, see the Internal Procedures section.
You can also use a persistent procedure to create multiple versions of the same context. Each
time you call a persistent procedure, it creates a separate instance of its context. Your
application (and user) can access and manage each context independently from the others. If
your persistent procedure manages its own windows, you can use this feature to provide some
(but not all) of the capabilities of the Microsoft multiple document interface (MDI).
For more information on using persistent procedures to manage multiple windows, see Chapter
21, Windows.
3.5.2 Creating Persistent Procedures
To make an external procedure persistent, execute it using the PERSISTENT option of the RUN
statement. This is an instantiating RUN statement, because it both executes the external
procedure and creates a persistent instance of its context:
The filename and run-options are the same as for any external procedure (see the External
Procedures section).
The handle is a field or variable defined with the HANDLE data type. The RUN statement sets
handle to a procedure handle value that identifies the current context of the persistent procedure.
You can use this procedure handle to invoke procedure triggers or internal procedures defined
in the persistent procedure context. For information on procedure handles, see the External
Procedures section.
SYNTAX
RUN filename PERSISTENT [ SET handle ] [ run-options ]
Block Properties
339
For example, this code fragment creates two persistent procedures from db-tools.p and
dde-tools.p, and assigns the procedure handles to hdbtools and hddetools, respectively:
Assume that these two procedures interact with the sports database (db-tools.p) and a
spreadsheet application using Windows Dynamic Data Exchange (DDE) (dde-tools.p). The
fragment then runs the internal procedures within these persistent procedures to add customer
information to a spreadsheet named Customer Activity. (For more information on using DDE,
see the Progress External Program Interfaces manual.)
This application fragment shows how you can use persistent procedures to set up modular
environments that encapsulate processing details from the rest of an application.
3.5.3 Working with Persistent Procedures
If you do not specify handle when you create a persistent procedure, you can obtain the handle
for the procedure using the SESSION system handle. Progress maintains all handles to
persistent procedure instances in a chain that you can access. The SESSION handle has two
attributes, FIRSTPROCEDURE and LASTPROCEDURE, that provide access to the first and
last persistent procedures (respectively) that are created. These attributes return procedure
handles that you can use to reference attributes of each persistent procedure context. For a
complete list of these attributes, see the THISPROCEDURE System Handle reference entry in
the Progress Language Reference.
For example, using the NEXTSIBLING attribute with the FIRSTPROCEDURE handle value
or the PREVSIBLING attribute with the LASTPROCEDURE handle value, you can follow
the entire chain of persistent procedure handles to locate the one you want. Note that
PREVSIBLING of FIRSTPROCEDURE and NEXTSIBLING of LASTPROCEDURE
specify invalid handles to terminate the chain. You can check the validity of any procedure
handle value in the chain using the VALIDHANDLE function. It returns TRUE for a valid
value and FALSE for an invalid value.
DEFINE VARIABLE hdb-tools AS HANDLE.
DEFINE VARIABLE hdde-tools AS HANDLE.
DEFINE VARIABLE ldone AS LOGICAL INITIAL FALSE.
DEFINE BUFFER cust-buf FOR customer.
RUN db-tools.p PERSISTENT SET hdb-tools.
RUN dde-tools.p PERSISTENT SET hdde-tools (INPUT "Customer Activity").
RUN get-first-customer IN hdb-tools (BUFFER cust-buf).
DO WHILE NOT ldone:
RUN add-to-spread-sheet IN hdde-tools (BUFFER cust-buf).
RUN get-next-customer IN hdb-tools (BUFFER cust-buf, OUTPUT ldone).
END.
340
The PRIVATEDATA attribute is especially helpful in identifying a particular persistent
procedure in the chain. When initially created with the RUN statement, a persistent procedure
can set this attribute to a unique character value that helps identify its context to other
procedures. You can use shared data to help manage the values for this private data. Note that
the FILENAME attribute might not be sufficient to identify a specific persistent procedure
instance, because you can create multiple instances of the same persistent procedure.
Other attributes of procedure handles that help manage persistent procedures include the
PERSISTENT, CURRENTWINDOW, and INTERNALENTRIES attributes. When used
with the THISPROCEDURE handle, the PERSISTENT attribute returns TRUE if the current
procedure is being run persistently. This is useful if you want to write a procedure to run either
persistently or non-persistently, providing different code options for each mode of execution.
The CURRENTWINDOW attribute allows you to assign a unique current window to a
procedure context that never changes as long as the procedure remains in scope or until you
reset it. This is especially useful for persistent procedures that maintain their own windows. For
more information, see Chapter 21, Windows.
The INTERNALENTRIES attribute returns a comma-separated list of all the internal
procedures defined within the specified external procedure. This is helpful to identify the
functional capabilities (internal procedures) provided to your application by each type of
persistent procedure that you create. The GETSIGNATURE method returns the type and
parameters of a specified internal procedure.
For example, this code fragment uses several attributes to select persistent procedures that
participate in the application user interface, and makes their current windows visible:
For more information on attribute references, see Chapter 16, Widgets and Handles.
DEFINE VARIABLE hcurrent AS HANDLE.
DEFINE VARIABLE hnext AS HANDLE.
DEFINE VARIABLE hwindow AS WIDGET-HANDLE.
hcurrent = SESSION:FIRST-PROCEDURE.
DO WHILE VALID-HANDLE(hcurrent):
IF hcurrent:PRIVATE-DATA = "USER INTERFACE" THEN DO:
hwindow = hcurrent:CURRENT-WINDOW.
hwindow:VISIBLE = TRUE.
END.
hcurrent = hcurrent:NEXT-SIBLING.
END.
Block Properties
341
3.5.4 Deleting Persistent Procedures
You can delete an instance of a persistent procedure using the DELETE PROCEDURE
statement:
This statement removes the procedure context specified by handle, a procedure handle to the
context of a persistent procedure. If handle identifies a non-persistent procedure context or is
otherwise invalid, the statement returns the ERROR condition. The NOERROR option allows
you to ignore or trap statement ERROR conditions as you want.
When this statement completes execution, all resources defined in the specified procedure
context are returned to the system and the procedure handle value ceases to be valid. The
procedure handle is also removed from the session chain of persistent procedures. Any local
buffers associated with the persistent context are disconnected and their data validated, possibly
firing write triggers. If the validation fails, the DELETE PROCEDURE statement returns the
ERROR condition and pends the deletion until all buffer validations succeed and any write
triggers fire.
Note that if you execute the DELETE PROCEDURE statement in the context of the procedure
you are deleting, the delete pends until execution leaves the persistent context and returns to the
context of the calling external procedure. This happens when you execute the statement in a
trigger or internal procedure that is defined within the persistent procedure.
SYNTAX
DELETE PROCEDURE handle [ NO-ERROR ]
342
3.5.5 Examples
These examples illustrate several features of persistent procedures. The application returns a
customer name from the sports database when you enter a customer number. The main
event-driven procedure, p-persp1.p, creates a persistent procedure from p-persp2.p and
stores its handle in hdb-tools:
p-persp1.p
DEFINE VARIABLE hdb-tools AS HANDLE.
DEFINE VARIABLE out-message AS CHARACTER FORMAT "x(60)".
DEFINE VARIABLE vcust-num LIKE customer.cust-num INITIAL 0.
DEFINE VARIABLE vname LIKE customer.name.
DEFINE BUTTON bcancel LABEL "Cancel Database Access".
DEFINE FRAME CustFrame
vcust-num LABEL "Customer Number"
vname LABEL "Customer Name"
bcancel
WITH SIDE-LABELS.
ON RETURN OF vcust-num IN FRAME CustFrame DO:
ASSIGN vcust-num.
RUN get-cust-name IN hdb-tools (INPUT vcust-num, OUTPUT vname).
DISPLAY vname WITH FRAME CustFrame.
END.
ON CHOOSE OF bcancel IN FRAME CustFrame DO:
DEFINE VARIABLE hcurrent AS HANDLE.
DEFINE VARIABLE hnext AS HANDLE.
hcurrent = SESSION:FIRST-PROCEDURE.
DO WHILE VALID-HANDLE(hcurrent):
hnext = hcurrent:NEXT-SIBLING.
IF hcurrent:PRIVATE-DATA = "DATABASE" THEN DO:
RUN destroy-context IN hcurrent (OUTPUT out-message).
MESSAGE out-message.
END.
hcurrent = hnext.
END.
APPLY "WINDOW-CLOSE" TO CURRENT-WINDOW.
END.
RUN p-persp2.p PERSISTENT SET hdb-tools.
ENABLE ALL WITH FRAME CustFrame.
Block Properties
343
This persistent procedure provides two internal procedures to the application, getcustname
and destroycontext. The getcustname procedure performs the database access for the
application, and the destroycontext procedure deletes the context of the persistent procedure
from the application.
Note that while p-persp1.p controls the application, p-persp2.p provides all the code to
manage itself, in this case to delete its own context. If you write an application with many
persistent procedures, each one can provide a common set of internal procedures with the same
name and interface, such as deletecontext. Thus, the deletecontext in one persistent procedure
might operate differently than that in another, but they all can be called in the same context of
the controlling procedure.
In fact, p-persp1.p illustrates this generic procedure capability when you choose the bcancel
button, by looping through the persistent procedure chain to delete the p-persp2.p context. You
can create any number of different persistent procedures with the PRIVATEDATA attribute
set to "DATABASE," and with many additional variations on the theme.
NOTE: Persistent procedures that manage their own user interface often create and manage
their own widget pools. For more information, see Chapter 21, Windows.
p-persp2.p
THIS-PROCEDURE:PRIVATE-DATA = "DATABASE".
PROCEDURE get-cust-name:
DEFINE INPUT PARAMETER pcust-num LIKE customer.cust-num.
DEFINE OUTPUT PARAMETER pname LIKE customer.name.
FIND customer WHERE customer.cust-num = pcust-num NO-ERROR.
IF NOT AVAILABLE(customer) THEN
pname = ?.
ELSE
pname = customer.name.
END PROCEDURE.
PROCEDURE destroy-context:
DEFINE OUTPUT PARAMETER out-message AS CHARACTER FORMAT "x(60)".
DELETE PROCEDURE THIS-PROCEDURE.
out-message = THIS-PROCEDURE:PRIVATE-DATA + " module deleted.".
END PROCEDURE.
344
3.5.6 Persistent Procedure Context and Shared Objects
While the context of a persistent procedure remains available to your application, there are
certain capabilities that persistent procedures do not allow:
Static dialog boxes You cannot maintain static dialog boxes in a persistent procedure.
Any static dialog boxes that a persistent procedure defines go out of scope when the
instantiating RUN statement returns to the calling external procedure. For more
information, see Chapter 21, Windows.
Shared streams or frame, browse, and menu widgets You cannot create or access
shared streams or shared frame, browse, or menu widgets in a persistent procedure. If you
do, the instantiating RUN statement does not create the procedure context and returns with
the ERROR condition.
DISABLE TRIGGERS Statement You cannot execute the DISABLE TRIGGERS
statement anywhere while executing code in a persistent procedure. Otherwise, Progress
raises the ERROR condition at that point.
All other widgets and shared objects are allowed in a persistent procedure.
Scoped Object Sharing
In persistent procedures, scoped object sharing works differently than in non-persistent
procedures. When a persistent procedure references a shared object, the scoped shared object
stays in scope as long as the persistent procedure remains in scope. In other words, a shared
object can go out of scope only when no persistent procedure remains that references it. For
more information on scoped shared objects, see the External Procedures section.
Persistent Shared Objects and the Call Stack
Note that after a persistent procedure is created, it no longer appears on the procedure call stack.
Only its triggers and internal procedures go on the call stack when they execute other
procedures.
Normally Progress resolves scoped shared objects by looking for them on the call stack.
However, if the trigger or internal procedure of a persistent procedure calls an external
procedure that references scoped shared objects, Progress resolves these objects by looking for
them in the context of the persistent procedure as well as on the call stack. For more information
on the procedure call stack, see the External Procedures section.
Block Properties
345
3.5.7 Run-time Parameters
Any persistent procedure created using a RUN statement invoked with INPUT, OUTPUT, or
INPUTOUTPUT run-time parameters continues to have access to these parameters after the
RUN statement completes execution. The output values are returned to the caller at the time that
the procedure returns from its instantiation. However the parameters remain available to the
persistent procedure context just like local variables.
Buffer parameters work differently in persistent procedures. During execution of the
instantiating RUN statement, a buffer is passed by reference and any new value returned, just
as for a non-persistent procedure. However, after the procedure returns from creating its
persistent context, Progress creates a copy of the buffer parameter and resets its cursors as an
initially defined local buffer for use in the persistent context. Thus, to give the persistent
procedure context continued access to a buffer from the calling (instantiating) context, both the
calling and persistent context must define a common shared buffer.
NOTE: Run-time parameters passed to the internal procedures of a persistent procedure
function no differently than if passed to any other internal or non-persistent
procedure. For more information, see the External Procedures section.
3.5.8 Transaction Management
Transactions behave for persistent procedures in exactly the same way as for non-persistent
procedures. If a transaction (or subtransaction) begins during execution of an instantiating RUN
statement, the transaction is not held open pending deletion of the procedure context. Thus, the
transaction is accepted or rejected by the time the instantiating procedure returns to its caller.
The same is true for any trigger or internal procedure defined in the persistent procedure context
that opens a transaction or subtransaction. If you want to undo work done by a trigger or internal
procedure defined by a persistent procedure, you must enclose it within a transaction bound
entirely by the context of the trigger or internal procedure block. Otherwise, the transaction
completes when the trigger or internal procedure returns and cannot be undone. Thus, persistent
procedures encourage the use of atomic transactions no larger than the context of an
encapsulated trigger or internal procedure.
For more information on transaction management, see Chapter 12, Transactions.
UNDO Processing
Any database work subject to UNDO that also creates a persistent procedure can be undone.
However, the persistent procedure context remains persistent. In other words, UNDO does not
delete any persistent procedures. Otherwise, all records that can be disconnected for UNDO
during execution of a non-persistent procedure, can also be disconnected during instantiation of
a persistent procedure.
346
Schema Changes and Schema Locks
If your application makes a change to the schema of a database, and another procedure tries to
access a table in that database, Progress automatically restarts the application and any persistent
procedures created during the session are deleted.
If a persistent procedure accesses a database table during its instantiating execution, the schema
share lock that it obtains remains in effect until the procedure is deleted.
3.5.9 Condition Management
In general, if a STOP or QUIT condition or a RETURN ERROR occurs on an instantiating RUN
statement, the executed procedure returns unscoped as a non-persistent procedure and no
context is created for it. For more information on condition management, see Chapter 5,
Condition Handling and Messages.
STOP and QUIT Conditions with Persistent Procedures
If a STOP or QUIT condition is not handled by a corresponding ON STOP or ON QUIT phrase,
Progress performs the standard STOP or QUIT action and deletes all persistent procedure
instances created in the session. Also, any system error such as a hard CTRLC, that raises an
untrappable STOP condition, initiates the same STOP processing.
Database Disconnection
Normally, when a database disconnects due to a network error or execution of the PROSHUT
utility, Progress raises an untrappable STOP condition and unwinds the procedure call stack to
the point above which no procedures reference the disconnected database. At that point Progress
converts the untrappable STOP condition to a trappable STOP condition. Before unwinding the
call stack, Progress also deletes any persistent procedures that reference the disconnected
database.
3.5.10 CURRENTLANGUAGE Changes
If the CURRENTLANGUAGE variable changes, all persistent procedure instances continue
to function using the text segment with which they were created. CURRENTLANGUAGE
changes affect only inactive external procedures (external procedures that are neither persistent
nor active on the procedure call stack). For more information on languages and translation, see
the Progress Internationalization Guide manual.
Block Properties
347
3.6 User-defined Functions
Progress 4GL user-defined functions let your application define a logical rule or transformation
once, then apply the rule or transformation with absolute consistency an unlimited number of
times. For example, if you are developing a weather application that converts temperatures
between Celsius (C) and Fahrenheit (F), you can write two user-defined functions, one for
converting from C to F and one for converting from F to C. Then, whenever your application
must convert a temperature in either direction, you merely reference one of the user-defined
functions.
The definition of a user-defined function can reside in the procedure that references it, in a
procedure external to the procedure that references it, or in a procedure remote to the procedure
that references it. In other words, a user-defined function can be defined locally, externally, or
remotely.
User-defined functions follow the rules of scope and visibility that internal procedures follow.
For more information, see the section Shared and Local Context.
Some restrictions apply to user-defined functions:
You cannot define a work table, a temporary table or any shared variable, object or stream
within a user-defined function.
A user-defined function cannot contain any input-blocking statements, such as UPDATE
or PROMPTFOR, where the program waits for events.
The examples in this section use a user-defined function that accepts a number of type
INTEGER, multiplies the number by two, and returns the result. The examples reside on-line in
%DLC%\src\prodoc\langref on Windows and in $DLC/src/prodoc/langref on UNIX.
This section covers the following topics:
Locally-defined user-defined functions
Defining them
Referencing them
Referencing them before defining them
Externally-defined user-defined functions
Remotely-defined user-defined functions
348
3.6.1 Locally Defined User-defined Functions
The following procedure defines doubler(), then references it three times:
Defining User-defined Functions
The FUNCTION statement defines doubler(), a user-defined function that accepts an integer,
multiplies it by two, and returns the result.
The FUNCTION statement specifies the name of the function (doubler), the data type the
function returns (INTEGER), and the following information on the single parameter: its mode
(INPUT), its name within the definition (parm1), and its data type (INTEGER).
The functions logic resides in the RETURN statementspecifically, in the expression that
follows the RETURN keyword. The logic is so simple (taking a number and multiplying it by
two) that it does not need separate statements. If the logic were more complex and needed
separate statements, they would reside between the FUNCTION statement and the RETURN
statement.
The END FUNCTION statement ends the block that the FUNCTION statement begins. If you
omit END FUNCTION and run the procedure, nothing appears, because Progress includes the
DISPLAY statement within the user-defined function, which is probably not what you want.
Progress Software Corporation recommends that when you define a user-defined function, you
conclude the block with the END FUNCTION statement.
Referencing User-defined Functions
The DISPLAY statement references doubler() three times:
1. Passing doubler() the literal 0
p-udf1.p
/* Demonstrates defining and referencing a user-defined function */
/* Define doubler() */
FUNCTION doubler RETURNS INTEGER (INPUT parm1 AS INTEGER).
RETURN (2 * parm1).
END FUNCTION.
/* Reference doubler() */
DISPLAY "doubler(0)=" doubler(0) skip
"doubler(1)=" doubler(1) skip
"doubler(2)=" doubler(2) skip.
Block Properties
349
The previous example defines the user-defined function by using the FUNCTION statement.
Here is its syntax:
For functionname, substitute the name of the function. For datatype, substitute the data type
the function returns. For param, which stands for parameter, substitute the following syntax:
The preceding syntax shows three ways of specifying a parameter, which correspond to the
three types of parameter that user-defined functions allow: scalar (elementary data item),
temporary table, and database table buffer. In the top third of the syntax diagram, which
describes scalar parameters, note how each parameter has a mode (INPUT, OUTPUT, or
INPUTOUTPUT), a name, and a data type.
For more information on the FUNCTION statement, see its reference entry in the Progress
Language Reference.
Referencing User-defined Functions Before Defining Them
Progress lets a procedure reference a user-defined function before defining it, as long as the
procedure declares (preannounces) the user-defined function first. In other words, a procedure
can declare, reference, and define a user-defined function, in that order. The declaration
describes the user-defined function just enough to enable the Progress compiler, which reads
procedure files from top to bottom, to resolve references to it.
NOTE: These declarations are sometimes called forward declarations.
SYNTAX
FUNCTION function-name [ RETURNS ] data-type
[ ( param [ , param ] ... ) ]
{ FORWARD | [ MAP [ TO ] actual-name ] IN proc-handle }
SYNTAX
{
{ [ INPUT ] | OUTPUT | INPUT-OUTPUT }
param-name AS data-type
| { [ INPUT ] | OUTPUT | INPUT-OUTPUT }
TABLE FOR temp-table-name [ APPEND ]
| BUFFER buffer-name FOR database-table-name
}
350
To declare a user-defined function, code a FUNCTION statement that includes:
The name of the function
The data type that the function returns
For each parameter, the mode and data type
The FORWARD keyword
Here are some additional notes on declaring user-defined functions:
A function declaration does not need the END FUNCTION statement.
If you declare a function, when you subsequently define the function, you need specify
only the function name, the return type, and the logic.
The following procedure declares, references, and defines the user-defined function doubler().
Note that the references occur before the definition:
p-udf2.p
/* Forward-declares, references, and defines a user-defined function */
/* Forward declare doubler() */
FUNCTION doubler RETURNS INTEGER (INPUT parm1 AS INTEGER) FORWARD.
/* Reference doubler() */DISPLAY "doubler(0)=" doubler(0).
DISPLAY "doubler(1)=" doubler(1).
DISPLAY "doubler(2)=" doubler(2).
/* Define doubler() */FUNCTION doubler RETURNS INTEGER.
RETURN (2 * parm1).
END FUNCTION.
Block Properties
351
3.6.2 Externally Defined User-defined Functions
Progress lets procedures reference user-defined functions whose definitions reside in external
procedures. The following example, which consists of two procedures, illustrates this.
The first procedure, p-udfdef.p, defines doubler():
The second procedure, p-udf3.p, runs the first procedure persistently, declares doubler(),
references it, and deletes the persistent procedurein that order:
p-udfdef.p
/* Defines user-defined function doubler() */
FUNCTION doubler RETURNS INTEGER (INPUT parm1 AS INTEGER).
RETURN (2 * parm1).
END FUNCTION.
p-udf3.p
/* references an externally-defined user-defined function */
/* define items */
DEFINE VARIABLE myhand AS HANDLE.
DEFINE VARIABLE mystr AS CHARACTER FORMAT "x(20)".
/* forward declare doubler() */
FUNCTION doubler RETURNS INTEGER (INPUT parm1 AS INTEGER) IN myhand.
/* run the procedure that doubler() */
RUN src\prodoc\langref\p-udfdef.p PERSISTENT SET myhand.
/* reference doubler() */
DISPLAY "doubler(0)=" doubler(0) skip
"doubler(1)=" doubler(1) skip
"doubler(17)=" doubler(17) skip.
/* delete the procedure that defines doubler */
DELETE PROCEDURE(myhand).
352
3.6.3 Remotely Defined User-defined Functions
Progress lets procedures reference user-defined functions whose definitions reside in remote
procedures. (A remote procedure is a procedure that runs in a Progress AppServer on a remote
machine.) Remotely-defined user-defined functions have one restriction: they cannot contain
buffer parameters.
NOTE: If a remote procedure defines a user-defined function that contains one or more
buffer parameters, the local procedure cannot reference that user-defined function.
The remote procedure, however, can, because to the remote procedure, the
user-defined function is local.
Remotely-defined user-defined functions are identical to externally-defined user-defined
functions, except that the RUN statement uses the ON SERVER option, and that buffer
parameters are not allowed.
For an example of a remotely-defined user-defined function, see the example of the
externally-defined user-defined function in the previous section, and in the RUN statement, add
the ON SERVER option. For an actual example, see Building Distributed Applications Using
the Progress AppServer.
3.7 Procedure Overriding
Progress supports a mechanism for overriding Progress internal procedures and user-defined
functions. This accomplishes the following goals:
Implementing a basic object-oriented programming principle of great value in designing
Progress components that build on standard behavior.
Replacing the dispatch mechanism, which the ADM of previous versions of Progress
implemented in 4GL code. The new mechanism makes overriding procedures faster,
cleaner, and completely transparent to callers, who can now invoke potentially multiple
layers of application behavior by using an ordinary RUN statement.
Another term for this behavior is dynamic procedure scoping. Progress dynamically scopes the
name space in which Progress searches for a procedure someone wishes to run, and extends that
name space to more than one running procedure instance.
Block Properties
353
This section covers the following topics:
Feature summary
Super procedure prototyping
Programming example
NOTE: For a complete description of the 4GL elements described in this section, see the
Progress Language Reference.
3.7.1 Feature Summary
Progress procedure overriding allows the following:
The programmer can write different versions of an internal procedure, all with the same
name, inserting each into a different procedure file. The same applies to user-defined
functions.
The programmer can make a procedure file a super procedure of the local procedure file
or of the current Progress session by using the ADDSUPERPROCEDURE method (and
can reverse this action by using the REMOVESUPERPROCEDURE method). When
the local procedure file invokes an internal procedure or user-defined function, Progress
searches for it using well-defined search rules.
For more information on the search rules, see the ADDSUPERPROCEDURE( )
Method reference entry in the Progress Language Reference.
Table 33: Search Rules
Step Location
1 Local procedure (the procedure with the original RUN statement)
2 Super procedures of the local procedure file
3 Current Progress session
4 External procedures
354
An internal procedure can invoke the super version of itself by using the RUN SUPER
statement. A user-defined function can do the same by using the SUPER function.
NOTE: When a super procedure executes a RUN SUPER statement, you can specify that
Progress continue to search the super procedure chain of the local procedure
instead of the super procedure chain of the current super procedure. This behavior
is controlled by an optional parameter of the ADDSUPER PROCEDURE
method. For more information, see the Progress Language Reference.
The programmer can get a list of the super procedure handles associated with a procedure
file or with the current Progress session by using the SUPERPROCEDURES attribute.
For each procedure handle, the program can use the INTERNALENTRIES attribute to
determine the internal procedures and user-defined functions the corresponding procedure
file contains. For each internal procedure and user-defined function, the program can
determine the signature by using the GETSIGNATURE method.
NOTE: An internal procedure or user-defined function can exclude itself from the
INTERNALENTRIES attributes list by defining itself using the PRIVATE
option. For more information on the PRIVATE option, see the PROCEDURE
Statement and FUNCTION Statement reference entries in the Progress
Language Reference.
The super version of an internal procedure (or user-defined function) can get a handle to
the procedure file of the original version by using the TARGETPROCEDURE system
handle. Similarly, the super version can get a handle to the procedure file of the original
invocation (RUN statement or user-defined function invocation) by using the
SOURCEPROCEDURE system handle. TARGETPROCEDURE and
SOURCEPROCEDURE thus allow access to the attributes and objects associated with
the original procedure files.
The programmer can write prototypes for internal procedures and user-defined functions
invoked in the local procedure file and implemented in super procedures. When a
prototype appears, the Progress compiler stores its information so that the
INTERNALENTRIES attribute and GETSIGNATURE method can access it.
For more information on super procedure prototyping, see the Super Procedure
Prototyping subsection of this section.
Block Properties
355
3.7.2 Super Procedure Prototyping
A procedure file can include a prototypeas in function prototypefor each internal
procedure and user-defined function invoked by (or in) the procedure file and implemented (at
run time) in a super procedure. At compile time, Progress adds information from each prototype
to the procedure files INTERNALENTRIES attribute, which lists the procedure files internal
procedures and user-defined functions. At run time, the programmer can examine the
INTERNALENTRIES attribute, and for each routine on the list, can invoke the
GETSIGNATURE method to get the routines signature.
NOTE: If the definition of an internal procedure or user-defined function uses the PRIVATE
option, the routine does not appear in the INTERNALENTRIES attribute of a
procedure file other than the original, and the routines signature is not returned by
the GETSIGNATURE method of a procedure file other than the original.
Prototyping Internal Procedures
To write a prototype for an internal procedure whose implementation resides (at run time) in a
super procedure, use the PROCEDURE statement with the IN SUPER option. The syntax is as
follows:
proc-name
The name of the internal procedure.
For each parameter, code a DEFINE PARAMETER statement the regular way.
If your program includes such a prototype, GETSIGNATURE(procname) returns the
signature in the following format:
SYNTAX
PROCEDURE proc-name IN SUPER:
PROCEDURE,,parameters
356
Prototyping User-defined Functions
To write a prototype for a user-defined function whose implementation resides (at run time) in
a super procedure, use the FUNCTION statement with the IN SUPER option. The syntax is as
follows:
functionname
The name of the user-defined function.
returntype
The data type of the item the function returns. For a list of data types, see the reference
entry for the FUNCTION statement in the Progress Language Reference.
parameters
The parameters of the user defined function. For the parameter syntax, see the reference
entry for the FUNCTION statement in the Progress Language Reference.
If you include the prototype in your program, compile the program, examine the
INTERNALENTRIES attribute of the super procedure, and invoke the GETSIGNATURE
method for the function, GETSIGNATURE returns the signature in the following format:
Prototyping Routines Implemented IN SUPER and Locally
A program might define a user-defined function IN SUPER and also implement the function
locally. The local implementation might invoke its super version (by using the SUPER
function), or might override it entirely. The programmer might write two prototypes, one
FORWARD and the other IN SUPER. The Progress compiler permits this, and also verifies that
the parameters of the prototype match those of the local definition.
Similarly, a program might define an internal procedure IN SUPER and also implement the
internal procedure locally. (In this case, the program contains only one prototype, since internal
procedures do not normally have prototypes.) The Progress compiler permits this.
In both cases, at run time, Progress invokes the local implementation.
SYNTAX
FUNCTION function-name RETURNS return-type
[ ( parameters ) ] IN SUPER
FUNCTION,return-type,parameters
Block Properties
357
3.7.3 Programming Example
The following example consists of three procedure files: a main routine, a driver, and a third
procedure file that becomes a super procedure of the driver.
The main routine, procedure file p-pomain.p, runs the driver procedure persistently:
p-pomain.p
/* p-pomain.p */
DEFINE VARIABLE h AS HANDLE.
DEFINE VARIABLE a AS CHARACTER.
FUNCTION sample2 RETURNS CHARACTER (INPUT-OUTPUT a AS CHARACTER) IN h.
RUN p-podrvr.p PERSISTENT SET h.
RUN sample1 IN h (INPUT-OUTPUT a).
MESSAGE a VIEW-AS ALERT-BOX.
a = "".
MESSAGE sample2(a) VIEW-AS ALERT-BOX.
358
The driver, procedure file p-podrvr.p, runs the third procedure file persistently, makes it a
super procedure of itself, defines the internal procedure sample1, and defines the user-defined
functions sample2, GetPartName, and SetPartName:
p-podrvr.p
/* p-podrvr.p */
FUNCTION SetPartName RETURNS INTEGER (INPUT a AS CHARACTER) FORWARD.
DEFINE VARIABLE localPartName AS CHARACTER.
/* Add a super procedure */
RUN p-posupr.p PERSISTENT SET h.
THIS-PROCEDURE:ADD-SUPER-PROCEDURE (h).
SetPartName("2000 Calendar").
PROCEDURE sample1:
DEFINE INPUT-OUTPUT PARAMETER a AS CHARACTER.
a = a + "proc: Part name is: ".
/* Invoke procedure sample1 in the super procedure. */
RUN SUPER (INPUT-OUTPUT a).
END PROCEDURE.
FUNCTION sample2 RETURNS CHARACTER (INPUT-OUTPUT a AS CHARACTER).
a = a + "func: Part name is: ".
/* Invoke function sample2 in the super procedure. */
SUPER (INPUT-OUTPUT a).
RETURN a.
END FUNCTION.
FUNCTION GetPartName RETURNS CHARACTER ():
RETURN localPartName.
END FUNCTION.
FUNCTION SetPartName RETURNS INTEGER (INPUT partname AS CHARACTER):
localPartName = partname.
END FUNCTION.
Block Properties
359
The third procedure file, p-posupr.p, defines a new version of the internal procedure sample1
and a new version of the user-defined function sample2:
To start the example, run p-pomain.p.
p-posupr.p
/* p-posupr.p */
FUNCTION GetPartName RETURNS CHARACTER () IN H.
PROCEDURE sample1:
DEFINE INPUT-OUTPUT PARAMETER a AS CHARACTER.
h = TARGET-PROCEDURE.
a = a + GetPartName().
MESSAGE "TARGET-PROCEDURE is:" TARGET-PROCEDURE:FILE-NAME
VIEW-AS ALERT-BOX.
MESSAGE "SOURCE-PROCEDURE is:" SOURCE-PROCEDURE:FILE-NAME
VIEW-AS ALERT-BOX.
END PROCEDURE.
FUNCTION SAMPLE2 RETURNS CHARACTER (INPUT-OUTPUT a AS CHARACTER):
h = TARGET-PROCEDURE.
a = a + GetPartName().
RETURN a.
END.
360
4
Named Events
Progress supports an event mechanism which lets you use named events in 4GL programs.
Named events provide several benefits:
First, they let a procedure or widget notify one or more other procedures that some event
has occurred, without requiring the procedures to know about each other or to maintain
lists of handles to each other. In short, named events decouple communications. This lets
you develop applications from components that you build independently and assemble
flexibly.
Second, they replace the notify procedure, which the ADM of previous versions of
Progress implemented in 4GL code. By contrast, the ADM of the current version of
Progress implements named events in 4GL code. This makes applications that use the
current ADM and SmartObjects cleaner, faster, and easier to debug.
NOTE: Progress named events are completely different from the key function, mouse,
widget, and direct manipulation events. For more information on direct manipulation
events, see the Progress Language Reference.
The chapter covers the following topics:
Feature summary
Programming example
NOTE: For a complete description of the 4GL language elements mentioned in this chapter,
see the Progress Language Reference.
42
4.1 Feature Summary
Progress named events allow the following:
Any procedure or widget within the current Progress session can generate a named event
by using the PUBLISH statement.
Any procedure within the current Progress session can subscribe to a named event by
using the SUBSCRIBE statement. Each subscriber contains an internal procedure that
Progress runs when the named event occurs. By default, the name of this internal
procedure (the local internal procedure) is the name of the event. The subscriber can
specify a different name by using the SUBSCRIBE statements RUNPROCEDURE
option.
NOTE: A widget can publish, but not subscribe to, a named event.
A potential subscriber can find out about named events of interest by using the
PUBLISHEDEVENTS attribute.
Subscribers can cancel subscriptions by using the UNSUBSCRIBE statement.
Named events can pass parameters and thus have signatures (the number of parameters,
and the data type and mode (INPUT, OUTPUT, etc.) of each).
NOTE: Progress supports named events within single Progress sessions only. In other words,
a procedure in one session cannot subscribe to a named event created in another
session. You can, however, build a Progress procedure that functions as a message
broker, routing named events among procedures or widgets within a single Progress
session.
Named Events
43
4.2 Programming Example
The following example consists of four procedure files: a driver, a publisher, and two
subscribers. The driver, p-nedrvr.p, runs the publisher and the two subscribers persistently,
and then subscribes to the event NewCustomer on behalf of the second subscriber:
The publisher, p-nepub.p, publishes the event NewCustomer:
pnedrvr.p
/* p-nedrvr.p */
DEFINE VARIABLE hPub AS HANDLE.
DEFINE VARIABLE hSub1 AS HANDLE.
DEFINE VARIABLE hSub2 AS HANDLE.
DEFINE BUTTON bNewCust LABEL "New Customer".
DEFINE BUTTON bQuit LABEL "Quit".
RUN p-nepub.p PERSISTENT set hPub.
RUN p-nesub1.p PERSISTENT set hSub1 (hPub).
RUN p-nesub2.p PERSISTENT set hSub2.
/* Subscribe to event NewCustomer on behalf of subscriber 2 */
SUBSCRIBE PROCEDURE hSub2 TO "NewCustomer" IN hPub.
FORM bNewCust bQuit WITH FRAME x.
ENABLE ALL WITH FRAME x.
ON CHOOSE OF bNewCust RUN NewCust in hPub.
WAIT-FOR CHOOSE OF bQuit OR WINDOW-CLOSE OF CURRENT-WINDOW.
pnepub.p
/* p-nepub.p */
PROCEDURE NewCust:
DEFINE VARIABLE name AS CHARACTER INITIAL "Sam".
/* Let subscriber know new customer */
PUBLISH "NewCustomer" (INPUT name).
END PROCEDURE.
44
The first subscriber, p-nesub1.p, subscribes to the event NewCustomer:
The second subscriber, p-nesub2.p, already subscribed to the event NewCustomer, cancels all
subscriptions:
To start the example, run the driver, p-nedrvr.p.
pnesub1.p
/* p-nesub1.p */
DEFINE INPUT PARAMETER hPub AS HANDLE.
SUBSCRIBE TO "NewCustomer" IN hPub.
PROCEDURE NewCustomer:
DEFINE INPUT PARAMETER name AS CHAR.
MESSAGE "Subscriber 1 received event NewCustomer concerning " name
VIEW-AS ALERT-BOX.
END.
pnesub2.p
/* p-nesub2.p */
PROCEDURE NewCustomer:
DEFINE INPUT PARAMETER name AS CHAR.
MESSAGE "Subscriber 2 received event NewCustomer concerning " name
VIEW-AS ALERT-BOX.
/* This subscriber receives the first event, then removes itself */
UNSUBSCRIBE TO ALL.
END.
5
Condition Handling and Messages
Progress recognizes four special conditions:
The ERROR condition
The ENDKEY condition
The STOP condition
The QUIT condition
Progress defines a default response to each of these conditions, but you can override these
defaults within your application. This chapter details how Progress handles each of these
conditions and how you can change that handling. It also covers:
How Progress responds to system and software errors
Progress messages
52
5.1 Progress Conditions
Progress handles the conditions listed in Table 51. Conditions may be raised by specific 4GL
statements, procedure errors, or keyboard events.
Table 51: Progress Conditions
Condition
Primary
Causes
Default
Processing
To Override
Default
Processing
ERROR RETURN ERROR executed by a
trigger or run procedure.
OR
Procedure error, such as creating a
duplicate entry in a unique index or
performing a FIND, FIND FIRST,
or FIND LAST for a nonexistent
record.
OR
The user presses ERROR.
Undo and retry the nearest
REPEAT, FOR EACH, or
procedure block.
Within a database trigger, undo and
return ERROR.
ON ERROR
phrase
ENDKEY The user presses ENDKEY.
OR
A FIND NEXT or FIND PREV
fails.
OR
Reach the end of an input file.
Undo and leave the nearest
REPEAT, FOR EACH, or
procedure block.
ON ENDKEY
phrase
STOP STOP statement executed.
OR
The user presses STOP.
Undo the current transaction and
retry the startup procedure (or return
to the Editor).
ON STOP
phrase
QUIT QUIT statement executed. Undo the current transaction and
return to the operating system (or to
the Editor). On an AppServer,
terminate the session and return to
the Progress client.
ON QUIT
phrase
53
For each condition, you may want to accept the default Progress processing. In many situations
this provides the functionality you would want. However, you can also override the default
behavior.
5.2 Rules About UNDO
Within an ON ERROR, ON ENDKEY, ON STOP, or ON QUIT phrase, you can specify a block
to be undone. This is the syntax for the UNDO option:
Within this syntax, you can name the block to be undone, label1. The block you name must be
the current block or a block that contains the current block. If you omit label1, Progress
determines the block to undo. It chooses the innermost containing block with the error property.
The following blocks have the error property:
FOR
REPEAT
Procedure blocks
DO blocks with the TRANSACTION keyword or ONERROR phrase
SYNTAX
UNDO [ label1 ]
[ , LEAVE [ label2 ]
| , NEXT [ label2 ]
| , RETRY [ label1 ]
| , RETURN [ ERROR | NO-APPLY ] [ return-string ]
]
54
Optionally, you can specify the action Progress takes after undoing the block:
LEAVE that block or an enclosing block.
Perform the NEXT iteration of the the block or an enclosing block.
RETRY the current iteration of the block.
RETURN to the calling procedure. If you are within a user-interface trigger, you can
return NOAPPLY to cancel the action. In any other context, you can return ERROR to
raise the ERROR condition in the caller. You can also pass a return string back to the
caller. The caller can read that string by invoking the RETURNVALUE function.
The default action is to retry the block that was undone.
For more information on UNDO, see the Progress Language Reference.
5.2.1 Infinite Loop Protection
If a statement within a block forces an undo and retry of the block, an infinite loop is possible.
That is, it is possible that whatever caused the block to be undone and retried the first time
(whether it is a condition such as ERROR or an explicit UNDO statement), may recur during
the retry. If Progress detects that such an infinite loop would occur, then it does not retry the
block. Instead it performs the NEXT iteration of a FOR EACH block or iterating DO block; it
performs a LEAVE on a REPEAT block, procedure block, trigger block, or non-iterating DO
block.
Progress detects that an infinite loop would occur if the following conditions are true:
The block does not reference any statements that block for user input (such as the
UPDATE or WAITFOR statements) before the error occurs.
The block does not reference the RETRY function before the error occurs.
If the block contains statements that block for input, then Progress assumes the user can prevent
an infinite loop by supplying different input. If the block contains a reference to the RETRY
function then Progress assumes that you have done your own programming to avoid infinite
loops.
55
For example, the following code specifies that the DO block should be retried if the FIND
statement produces an error. However, this would lead to an infinite loop (with i always equal
to 1) if the specified record does not exist:
If you run this procedure, Progress performs a NEXT rather than a RETRY when an error
occurs. Therefore, you see the displayed value of i iterate from 1 to 10. After the tenth error, the
procedure ends. Thus, the infinite loop is avoided.
In the following example, the RETRY function is referenced before the statement that causes
the error. Therefore, Progress does not detect that an infinite loop occurs on retry:
If you run this code, Progress enters an infinite loop in which i is always 1. Because the RETRY
function is referenced before the error, Progress assumes that you are handling the infinite loop
problem. You can fix this by changing the ON ERROR phrase to perform a NEXT or LEAVE
rather than a RETRY. Alternately, you can perform some processing when RETRY is true that
changes the value of i.
pitundo.p
DO i = 1 TO 10 ON ERROR UNDO, RETRY:
DISPLAY i.
FIND Customer WHERE Cust-num = 999.
END.
pitund2.p
DO i = 1 TO 10 ON ERROR UNDO, RETRY:
IF RETRY
THEN MESSAGE "Retrying DO loop.".
DISPLAY i.
FIND Customer WHERE Cust-num = 999.
END.
56
5.3 The ERROR Condition
There are three common ways a procedure can generate the ERROR condition:
The RETURN ERROR statement is executed.
The user presses ERROR.
A statement cannot be executed properly. For example, the procedure may try to create a
duplicate entry in a unique index or find a record that does not exist.
5.3.1 The ERRORSTATUS System Handle
Many Progress statements support the NOERROR option. If you specify this option, the
ERROR condition is not generated by that statement. Instead, if the statement cannot execute
properly, execution continues with the next statement. You can subsequently check whether an
error occurred by examining the attributes of the ERRORSTATUS system handle.
The ERRORSTATUS handle contains information on the last statement executed with the
NOERROR option. You can determine whether Progress attempted to raise the error condition
in that statement by reading the value of the ERROR attribute of ERRORSTATUS. To retrieve
the error messages and error numbers, first read the value of the NUMMESSAGES attribute,
then use the methods ERRORSTATUS:GETMESSAGE(n) and
ERRORSTATUS:GETNUMBER(n). For more information on these methods, see the
Progress Language Reference section on the ERRORSTATUS System Handle.
The ERRORSTATUS:ERROR attribute remains true until the completion of the next
statement with the NOERROR option.
57
The following program attemps to retrieve a record from the customer table with NOERROR.
If an error occurs, you are prompted to display the message:
5.3.2 Default Handling
When the ERROR condition occurs anywhere outside of a trigger block, Progress follows these
steps:
1. Looks for the closest block with the error property.
2. Undoes and retries that block.
FOR EACH blocks, REPEAT blocks, and procedure blocks automatically have the error
property. This means that each of these blocks implicitly has the ON ERROR UNDO, RETRY
phrase attached to it. The following two examples are the same:
perrst2.p
DEFINE VARIABLE i AS INTEGER NO-UNDO.
FORM WITH FRAME bbb.
FIND customer USING cust-num NO-LOCK NO-ERROR.
IF ERROR-STATUS:ERROR THEN DO:
MESSAGE ERROR-STATUS:NUM-MESSAGES
" errors occurred during conversion." SKIP
"Do you want to view them?"
VIEW-AS ALERT-BOX QUESTION BUTTONS YES-NO
UPDATE view-errs AS LOGICAL.
IF view-errs THEN
DO i = 1 TO ERROR-STATUS:NUM-MESSAGES:
MESSAGE ERROR-STATUS:GET-NUMBER(i)
ERROR-STATUS:GET-MESSAGE(i).
END.
END.
ELSE
END.
FOR EACH customer:
FOR EACH customer ON ERROR UNDO, RETRY:
58
A DO block has the error property if its header contains the TRANSACTION keyword or the
ON ERROR phrase.
When the ERROR condition occurs within a database trigger block, Progress follows these
steps:
1. Undoes the trigger block.
2. Returns ERROR.
The following example shows how Progress handles a processing error:
p-error.p
If Progress is not handling a specific processing error the way you want, you can override
automatic error handling by handling the error yourself.
Progress has no predefined ERROR key. However, you can define any control key or other
special key as the ERROR key. Then, when the user presses that key at an input prompt, the
procedure does error processing.
REPEAT WITH 1 COLUMN 1 DOWN:
FIND customer USING cust.num.
DISPLAY name address city state postal-code credit-limit.
END.
p-error.p
Customer
Record
Found?
1. Search outward for the first block
statement with the ERROR property.
2. The first block encountered is the
REPEAT block. It has the ERROR
property.
3. Undo the work done in the current
iteration of the REPEAT block and
retry that block.
Yes
Continue to the
next statement
No
59
The next example demonstrates what Progress does when the user presses a defined
ERROR key:
p-txn6.p
The ON statement defines F9 as the ERROR key. That is, when the user presses F9, Progress
raises the ERROR condition, searches for the closest block that has the error property and undoes
and retries that block.
NOTE: If you do not have an F9 key on your keyboard, you can modify this procedure to
name another key, such as F2 or PF2. Or, if your keyboard has no F or PF keys,
specify ON CTRLW ERROR to assign ERROR to the CTRLW keys.
When you run this procedure, the INSERT statement displays a screen similar to this:
ON F9 ERROR.
REPEAT:
INSERT order WITH 2 COLUMNS.
FIND customer OF order.
REPEAT:
CREATE order-line.
order-line.order-num = order.order-num.
DISPLAY order-line.order-num.
UPDATE line-num order-line.item-num qty.
FIND item OF order-line.
order-line.price = item.price.
UPDATE order-line.price.
END.
END.
Subtransaction
Transaction
510
If you press F9, Progress follows these steps:
1. Raises the ERROR condition.
2. Searches outward for the closest block that has the error property. REPEAT blocks have
the error property so Progress stops at the REPEAT block.
3. Undoes all work done in the current iteration of the REPEAT block and retries that
iteration of the REPEAT block.
In this case, Progress undoes and retries the transaction block.
If you run the p-txn6.p procedure again, and press F9 during the orderline block, Progress
undoes the subtransaction and retries that iteration of the inner REPEAT block.
5.3.3 Overriding the Default Handling
When an error occurs, you might not want Progress to perform the default error processing.
Rather than undoing and retrying the nearest block with the error property, you might want
Progress to take some other action. For example, you might want Progress to leave the block or
try the next iteration of the block. On the other hand, you might want Progress to undo a smaller
amount of work. You have two techniques to change the error handling:
Override the default error processing for a block by coding an explicit ON ERROR phrase
on the nearest REPEAT, FOR EACH, or procedure block.
Change the amount of work to be undone by adding the ON ERROR phrase to a DO block
(thus giving the DO block the error property) or specifying a different block in the ON
ERROR phrase.
Take the procedure p-error.p, shown earlier, as an example. In this procedure, if the FIND
statement fails, Progress undoes and retries that iteration of the REPEAT block. Suppose that
you want to change that error processing to the following: if the FIND statement fails, undo the
current iteration, and leave the REPEAT block. This is the modified p-error.p procedure.
511
In p-error2.p, the explicit ON ERROR phrase changes the handling of the ERROR condition:
p-error2.p
REPEAT WITH 1 COLUMN 1 DOWN ON ERROR UNDO, LEAVE:
END.
p-error2.p
Customer
Record
Found?
REPEAT block. Its ERROR
property is "ON ERROR UNDO, LEAVE.
iteration of the REPEAT block and
retry that block.
Yes
Continue to the
next statement
No
512
In the following example, the ON ERROR phrase is added to a DO block to change the amount
of work to be undone:
p-error3.p
Because the DO block has the error property, only the DO block is undone when an error occurs.
Therefore, the UPDATE statement is not retried; instead, execution continues from the
PROMPTFOR statement.
DEFINE VARIABLE do-lookup AS LOGICAL.
REPEAT WITH 1 COLUMN DOWN:
UPDATE do-lookup LABEL "Do you want to look up a customer?"
WITH FRAME ask-frame.
IF do-lookup
THEN DO:
DO ON ERROR UNDO, RETRY:
END.
END.
ELSE LEAVE.
END.
p-error3.p
Customer
Record
Found?
DO block. Its ERROR
property is ON ERROR UNDO, RETRY.
iteration of the DO block and
retry that block.
Yes
Continue to the
next statement
No
513
In p-error3.p, you made Progress undo less than the default amount of work. Suppose you
wanted Progress to undo more than the default amount of work. For example, in p-txn6.p,
shown earlier, if you make an error while entering an orderline (you pressed F9), you want to
undo all the work done on the current order. To do this, you add a label to the outer REPEAT
block and reference that label in the ON ERROR phrase of the inner REPEAT block:
Here, the inner REPEAT block explicitly says that, in the event of an error, Progress should
undo not the current REPEAT block but the outer oblock REPEAT block. In addition, it tells
Progress to retry the oblock block. This error processing applies to any kind of an error. That
is, it happens if you press F9, or if there is some sort of processing error such as the FIND
statements is unable to locate a record.
5.4 The ENDKEY Condition
The ENDKEY condition occurs when you press ENDKEY when input is enabled. It also occurs
if an attempt to find a record fails or you reach the end of an input stream.
Progress does not have a predefined ENDKEY on the keyboard. However, you can use the ON
statement to assign a key as ENDKEY, or you can define any control (CTRL) key or other special
key as ENDKEY. Then, when the user presses that key, the ENDKEY condition is raised. Also,
the ENDERROR key behaves like ENDKEY for the first I/O operation in a block.
NOTE: Do not confuse the ENDKEY with the END key. They are completely unrelated.
ptxn7.p
ON F9 ERROR.
o-block:
REPEAT:
o-l-block:
REPEAT ON ERROR UNDO o-block, RETRY o-block:
CREATE order-line.
DISPLAY line-num order-line.item-num qty.
SET line-num order-line.item-num qty.
END.
END.
514
When the ENDKEY condition occurs, Progress follows these steps:
1. Looks for the closest block that has the endkey property.
2. Undoes and leaves that block.
FOR EACH blocks, REPEAT blocks, triggers, and procedure blocks have the endkey property
by default. This means that each of these blocks implicitly has the ON ENDKEY UNDO,
LEAVE phrase attached to it. The following two examples are the same:
This example shows how Progress handles ENDKEY:
p-txn8.p
FOR EACH customer:
FOR EACH customer ON ENDKEY UNDO, LEAVE:
ON F9 ENDKEY.
o-block:
REPEAT:
o-l-block:
REPEAT:
CREATE order-line.
UPDATE line-num order-line.item-num qty.
END.
END.
Subtransaction
Transaction
515
The ON statement defines F9 as the ENDKEY. That is, when the user presses F9, Progress raises
the ENDKEY condition. Progress searches for the closest block that has the ENDKEY property
and undoes and leaves that block:
Before entering a sales rep value, press F9. Progress follow these steps:
1. Raises the ENDKEY condition.
2. Searches outward for the closest block that has the ENDKEY property. REPEAT blocks
have the ENDKEY property, so Progress stops at the outer REPEAT block.
3. Undoes all work done in the current iteration of the REPEAT block and leaves that
REPEAT block. Since there are no statements to process after the END statement of the
REPEAT block, Progress returns you to the Procedure Editor:
516
Press F9 while entering the second orderline. Progress follows these steps:
1. Raises the ENDKEY condition.
2. Searches outward for the closest block that has the ENDKEY property. REPEAT blocks
have the ENDKEY property so Progress stops at the inner REPEAT block.
3. Undoes all work done in the current iteration of the REPEAT block and leaves that
iteration of the REPEAT block.
4. After leaving the inner REPEAT block, the procedure continues with the next statement
after the END of the inner block, encounters the END of the outer REPEAT block, and
does the next iteration of the outer block.
Note that this means that the order record and first orderline record that you created are
committed to the database. Only the second orderline record is undone.
If you are importing data from an operating system file, the ENDKEY condition occurs when
you reach the end of the file. For example, p-impeof.p takes advantage of this:
Assume that customer.d contains three records. On the third pass through the REPEAT loop,
p-impeof.p creates a customer record and reads data from the last line from the file into that
record. On the next pass through the loop, the procedure creates another customer record.
However, the IMPORT statement fails because it has reached the end of the file. This causes the
ENDKEY condition. The default behavior for ENDKEY undoes the current iteration of the
REPEAT loop and therefore undoes the record creation.
pimpeof.p
INPUT FROM customer.d.
REPEAT:
CREATE customer.
IMPORT customer.
END.
517
You can override the default ENDKEY processing by adding the ON ENDKEY phrase to a
block. Suppose you wanted Progress to undo more than the current iteration of the inner
REPEAT block. That is, if you press F9 while entering an orderline, you want to undo all the
work done on the current order and leave the procedure together:
Here, the inner REPEAT block explicitly states that in the event of the ENDKEY condition,
Progress does not undo the current REPEAT block but the outer oblock REPEAT block. In
addition, it tells Progress to retry the oblock REPEAT block.
ptxn9.p
ON F9 ENDKEY.
o-block:
REPEAT:
0-1-block:
REPEAT ON ENDKEY UNDO o-block, RETRY o-block:
CREATE order-line.
UPDATE lin-num order-line.item-num qty.
price = cost.
UPDATE price.
END.
END.
518
5.5 The STOP Condition
The STOP condition occurs when a STOP statement is executed or when you press STOP when
input is enabled (or anytime in a character interface). Progress also raises the STOP condition
when an unrecoverable system error occurs; for example, when a database connection is lost or
a run procedure is not found. This stop key is usually mapped as follows:
CTRLBREAK (Windows)
CTRLC (UNIX)
When the STOP condition occurs, by default Progress follows these steps.
1. Undoes the current transaction.
2. If the application was started from a Progress tool such as the Procedure Editor, it returns
to that tool; otherwise, it reruns the startup procedure.
The default handling for the STOP condition is almost always appropriate. However, you can
override the default handling by adding the ON STOP phrase to a REPEAT, FOR EACH, or
DO statement:
In p-stop.p, the ON ERROR and ON STOP phrases cause the FOR EACH loop to retry if and
only if the STOP condition occurs. When this happens, the procedure displays an alert box that
lets you decide whether to continue.
pstop.p
FOR EACH Customer ON ERROR UNDO, LEAVE
ON STOP UNDO, RETRY:
IF RETRY
THEN DO:
MESSAGE "The STOP condition has occurred." SKIP
"Do you wish to continue?" VIEW-AS ALERT-BOX QUESTION
BUTTONS yes-no UPDATE continue-ok AS LOGICAL.
IF NOT continue-ok
THEN UNDO, LEAVE.
END.
UPDATE Customer.
END.
519
5.6 The QUIT Condition
The QUIT condition occurs when a QUIT statement is executed.
When the QUIT condition occurs, by default Progress follows these steps:
1. Commits the current transaction.
2. If the application was started from the Procedure Editor or User Interface Builder, returns
to that tool; otherwise, returns to the operating system.
NOTE: If you run a procedure that consists of only a QUIT statement from the Procedure
Editor, Progress exits the Procedure Editor.
The default handling of the QUIT condition is almost always appropriate. However, by using
the ON QUIT phrase in a REPEAT, FOR EACH, or DO statement, you can (cause undo work
to be undone) or override the rest of the default handling.
5.7 The ENDERROR Key
The ENDERROR key (usually F4 in a character interface, and ESCAPE on Windows in graphical
interfaces) is so called because sometimes Progress treats it as ERROR and other times treats it
as ENDKEY:
perror4.p
REPEAT WITH 1 COLUMN 1 DOWN:
UPDATE name address city state postal-code credit-limit.
END.
520
This code runs the following procedure:
At this point, you are at the PROMPTFOR statement in the procedure. Press ENDERROR. The
procedure returns you to the Procedure Editor. Run the procedure again, entering a 1 for Cust
num and press GO:
At this point you are at the UPDATE statement in the procedure. Press ENDERROR. The
procedure returns you to the PROMPTFOR statement and lets you enter another customer
number.
521
5.7.1 Distinguishing ERROR and ENDKEY
Progress treats the same ENDERROR key differently under different circumstances. This is
why:
If you press ENDERROR when you are on the first screen interaction (the first statement
that gives you an opportunity to enter data) during a block iteration, it is probably because
you decided you do not want to complete the task you started. In this case, Progress undoes
whatever you have done in the current iteration of the block and leaves the block. That is,
it acts as an ENDKEY key.
If you press ENDERROR on the second or later interaction of a block iteration, it is
probably because you made a mistake or want to retry the work you have done. In this
case, Progress undoes whatever you have done and retries. That is, it acts as an ERROR key.
522
Run the p-error4.p procedure again. The following figure shows what happens when you
press ENDERROR:
p-error4.p
REPEAT WITH 1 COLUMN DOWN:
PROMPT-FOR customer.cust.num.
UPDATE name address city state postal-code credit-limit.
END.
p-error4.p
Search outward
for the first book.
Does the block
have the ENDKEY
property?
Does the block
have the ERROR
property?
Examine the next
block, searching
outward.
Did the user
press END-
ERROR during
the first
interaction
of the block
iteration being
examined?
Did the user
press END-
ERROR during
the
second or
subsequent
interaction of
the block
iteration being
examined?
Perform the
specified or
default
ENDKEY
processing. In
this example,
the default
ENDKEY
processing of
UNDO, LEAVE
takes place.
Perform the
specified or
default ERROR
processing. In
this example,
the default
ERROR
processing of
UNDO, RETRY
takes place.
END-
ERROR
Yes
Yes
Yes
Yes
No
No
No
No
523
In determining whether the user pressed ENDERROR during the first or subsequent interaction
in a block iteration, Progress does not count any keyboard entries to continue after a pause.
5.7.2 ENABLE/WAITFOR Processing
The ENDERROR key modifies its behavior yet again depending on whether input is blocked by
a WAITFOR statement or any other input blocking statement, such as UPDATE. The
p-error5.p procedure shows the difference:
Within the DO block of UPDATE statements, ENDERROR works as explained earlier. That is,
for an UPDATE statement, ENDERROR on field a acts like ENDKEY (leaving the block) and on
field b acts like ERROR (retrying the block and displaying the RETRY message).
However, in a similar DO block, where input is enabled with the ENABLE statement and
blocked with the WAITFOR statement, ENDERROR always works like ENDKEY. It always
leaves the block when entered for field a or field b. Progress treats ENDERROR differently in
this case, because the WAITFOR statement is designed to control input in a more random and
perror5.p
DEFINE VARIABLE a AS CHARACTER.
DEFINE VARIABLE b AS CHARACTER.
FORM a b WITH FRAME X 2 COLUMNS.
SESSION:APPL-ALERT-BOXES = TRUE.
ON END-ERROR ANYWHERE DO:
MESSAGE KEYFUNCTION(LASTKEY) "raised".
END.
MESSAGE "Entering UPDATE Block".
DO ON ERROR UNDO, RETRY ON ENDKEY UNDO, LEAVE WITH FRAME X:
IF RETRY THEN MESSAGE "Retrying UPDATE Block".
UPDATE a WITH FRAME X.
MESSAGE "After UPDATE a".
UPDATE b WITH FRAME X.
MESSAGE "After UPDATE b".
END.
MESSAGE "Entering ENABLE/WAIT-FOR Block".
DO ON ERROR UNDO, RETRY ON ENDKEY UNDO, LEAVE WITH FRAME X:
IF RETRY THEN MESSAGE "Retrying ENABLE/WAIT-FOR Block".
DISABLE ALL.
ENABLE a.
WAIT-FOR GO OF FRAME X.
MESSAGE "After ENABLE/WAIT-FOR a".
DISABLE ALL.
ENABLE b.
WAIT-FOR GO OF FRAME X.
MESSAGE "After ENABLE/WAIT-FOR b".
END.
524
less modal fashion than the UPDATE statement. In an event-driven interface, the triggers for
each widget are generally responsible for handling error input for that widget. Thus,
ENDERROR as ENDKEY. provides a consistent way to exit the interface from any input widget.
5.8 How Progress Handles System and Software Failures
Following a system hardware or software failure (a crash), Progress undoes partially completed
transactions for all users. This is the fundamental difference between transactions and
subtransactions: Progress undoes a partially completed transaction after a system failure,
including work done in any complete or incomplete subtransactions encompassed within the
transaction.
Also, if the user presses STOP, Progress undoes the current transaction and returns control to
the startup procedure if one is still active, or to the Editor.
If Progress loses a database connection (for example, because a remote server failed), client
processing might continue. In this case, Progress does the following:
Raises the STOP condition. For this special instance of the STOP condition you cannot
change the default processing. Any ON STOP phrases are ignored.
Deletes any persistent procedures that reference the disconnected database.
Progress undoes blocks beginning with the innermost active block and working outward.
It continues to undo blocks until it reaches a level above all references to tables ore
sequences in the lost database.
Progress changes to the normal STOP condition. From this point, any further ON STOP
phrases you have coded are used.
Progress continues to undo blocks until it reaches an ON STOP phrase. If no ON STOP
phrase is reached, it undoes all active blocks and restarts the top level procedure.
525
5.9 Progress Messages
Progress and applications written under Progress display several types of messages to inform
you of both routine and unusual occurrences:
Execution messages inform you of errors encountered while Progress is running a
procedure (for example, a record with a specified index field value could not be found).
Compile messages inform you of errors found while Progress is reading and analyzing a
procedure prior to running it (for example, a reference to a table name that is not defined
in the database).
Startup messages inform you of unusual conditions detected while Progress is getting
ready to execute (for example, an invalid startup parameter was entered).
After it displays a message, Progress proceeds in one of several ways:
Continues execution, subject to the error processing actions which you give, or are
assumed, as part of your procedure. This is the usual action taken following execution
messages.
Returns to the Procedure Editor (or other tool from which you ran the procedure) so that
you can correct an error in a procedure. This is the usual action taken following compiler
messages.
Halts processing of a procedure and returns immediately to the Editor or other tool.
Terminates the current session.
Access Progress Help (press HELP) if you do not understand a message. If you encounter an
error message that terminates Progress, the message ends with a number in parentheses.
Carefully note that number before restarting Progress. In all other cases, Progress keeps track
of messages that it displayed recently.
526
5.10 Application Messages
Within an application you might want to pass a message from one procedure back to the
procedure that called it. For example, if a subprocedure encounters an error, you might want to
pass a message about the error back to the caller. You can pass such as message on the RETURN
statement. For example, p-retstr.p tries to find a customer record in the database and returns
either the customer name or a message indicating why the record is not available:
The calling procedure can read a returned message by using the RETURNVALUE function.
For example, p-retval.p runs p-retstr.p and displays the returned value in a frame:
pretstr.p
DEFINE PARAMETER BUFFER cust-buf FOR customer.
DEFINE INPUT PARAMETER cnum AS INTEGER.
FIND cust-buf WHERE cust-num = cnum NO-ERROR.
IF NOT AVAILABLE cust-buf
THEN DO:
IF LOCKED cust-buf
THEN RETURN "Record is locked.".
ELSE RETURN "Record not found.".
END.
RETURN cust-buf.name.
pretval.p
FORM
customer.cust-num customer.name
WITH FRAME name-frame DOWN.
DISPLAY cust-num name WITH FRAME name-frame.
DO i = cust-num + 1 TO CURRENT-VALUE(next-cust-num):
DOWN WITH FRAME name-frame.
RUN p-retstr.p (BUFFER customer, i).
DISPLAY i @ customer.cust-num
RETURN-VALUE @ customer.name WITH FRAME name-frame.
END.
527
This procedure displays all customer numbers from the first to the current value of the
nextcustnum sequence. For each number it displays either the customer name or a message
indicating the status of that record.
NOTE: If you have a procedure which does not end with the RETURN statement, the value
in RETURNVALUE will be the value of the last executed RETURN statement.
RETURNVALUE is not cleared if there is no RETURN statement. If no value was
reurned by the most recently executed RETURN statement, RETURNVALUE
returns an empty string ().
For more information on the RETURN statement and the RETURNVALUE function, see the
528
6
Handling User Input
This chapter explains how you can monitor user input from the keyboard or mouse. It discusses:
The keys you normally use when running a Progress procedure and how Progress handles
each of those keys.
How you can redefine the functions of different keys.
How Progress handles mouse buttons, and how you can monitor mouse events.
How you can monitor specific keystrokes within a procedure.
This chapter, focuses on data that you enter from the keyboard. Chapter 7, Alternate I/O
Sources, explains how to write procedures that accept input from a file.
62
6.1 The Keyboard and the Mouse
Progress accepts user input from the keyboard and, where available, from the mouse. Although
the keys on different keyboards vary somewhat, Progress defines several hundred standard key
codes that map to common key labels (or sequences). Some of these codes are also mapped to
special functions by Progress or the windowing system. As shown in Figure 61, the F2 key
label maps to key code 302. On most systems, this key code also maps to the Progress GO key
function.
Figure 61: Key Labels, Key Codes, and Key Functions
Progress also defines a four-button mouse model. Each of the four portable buttons maps to a
physical button (possibly with a modifying key) on your mouse. For example, the portable
SELECT button usually maps to the left button on a two- or three-button mouse. The mouse
buttons generate input events that map to key labels. However, the way Progress handles mouse
input is different from the keyboard because of the way the mouse generates eventssending
both press (down) and release (up) signals. Progress provides access either to the down or up
event or to combinations of these inputs as a single event. For more information on mouse
buttons, events, and how to monitor them, see the Using Mouse Buttons and Events section.
6.1.1 Key Mapping
Your environment determines what key sequences on your keyboard map to each Progress key
function. Your environment might reside in the registry (Windows only) or in an initialization
file. Examples of initialization files are the progress.ini file (on Windows) and the
PROTERMCAP file (on UNIX). For more information on environments, see the chapter on
colors and fonts in this book and the chapter on user interface environments in the Progress
Client Deployment Guide.
Key Label
302 GO
Key Code Key Function
F2
Handling User Input
63
6.1.2 Key Monitoring
Often, an application does not need to be aware of specific keystrokes or mouse actions by the
user because the normal functionality provided by Progress and the window system is sufficient.
This is frequently true when you use the procedure-driven programming model. However, you
might want to define a special behavior to occur when the user presses a specific key or mouse
button. For example, every time the user presses a certain key, you might want to display a
message or take some action. This is called monitoring the users keystrokes. Progress provides
a set of language constructs to do this, including user interface triggers. For more information,
see theMonitoring Keystrokes During Data Entry section.
During a session, Progress responds to key code events according to a precedence that depends
on the current user interface and the application design. Table 61 shows the general order of
precedence for Progress key code events.
Thus, when the user presses a key, Progress first checks to see if it corresponds to an active
accelerator in the current window. If not, Progress checks for a user interface trigger for that
key, then whether the key displays a popup menu, and so on. If the key corresponds to no other
function, Progress processes it as data input, with any required character validation.
Table 61: Progress Key Input Precedence
Precedence
(High to Low)
Key Code Event
8 In the accelerator list for the current window
7 In the event list for an active user interface trigger
6 An active popup menu key
5 An active menu mnemonic key
4 An active field-level (button) mnemonic key (Windows only)
3 A special Progress internal key (built-in key function, like GO)
2 A key associated with a key function in the PROTERMCAP file
(UNIX only)
1 A standard input key (A, B, and so on)
64
6.1.3 Key Translation Functions
Progress key codes, key labels, and key functions are interrelated, and Progress provides a set
of built-in functions to convert from one to another. Figure 62 shows how the conversions
work, and which functions to use for each conversion.
Figure 62: Progress Key Translation Functions
You can use the KEYCODE function to determine the key code for a particular key. For
example, the following function returns the value 127, which is the integer code assigned to
DEL. Use the KEYLABEL function to determine the keyboard label for a particular key code.
For example, the following function returns the value CTRLG:
See the Progress Language Reference for more information on the KBLABEL, KEYCODE,
KEYFUNCTION, and KEYLABEL functions.
KEYCODE("del")
KEYLABEL(7).
Key Function
Key Code
Key Label
KEYFUNCTION
Function
KBLABEL
Function
KEYLABEL
Function
KEYCODE
Function
Handling User Input
65
6.2 Key Codes and Key Labels
All Progress keys have both a code and a label. The key code is a Progress internal identifier for
the key. Progress stores all key codes in 16-bit words. The structure of a key code is as follows:
Bits 08 Unique code assigned to the key
Bit 9 The SHIFT key modifier (512)
Bit 10 The ALT or ESC key modifier (1024)
Bit 11 The CTRL key modifier (2048)
Bits 1215 Reserved bits
This structure allows Progress to respond to a wide variety of key combinations. For example,
you can write a trigger that fires when the user presses CTRLSHIFTALTF1. Figure 63 shows
how Progress generates key codes when different keys are pressed.
Figure 63: Key Codes
Key Pressed
F1
SHIFT-F1
ALT-F1
CTRL-F1
SHIFT-ALT-F1
CTRL-ALT-F1
CTRL-SHIFT-ALT-F1
(Decimal) (Binary)
301
813
1325
2349
1837
3373
3385
100101101
1 100101101
10 100101101
100 100101101
11 100101101
110 100101101
111 100101101
Unique Key Code
(bits 0-8)
CTRL Modifier (bit 11)
ALT Modifier (bit 10)
SHIFT Modifier (bit 9)
66
Progress uses this scheme wherever possible. However, some keys are assigned key codes that
do not fit into this scheme. The following rules determine what key codes are outside of this
scheme:
If you press CTRL plus an alphabetic character or the (@, \, ], ^, or _ special characters),
Progress turns the CTRL key modifier off and maps to the appropriate character code. For
example, CTRLA is mapped to keycode 1, which accords with the ASCII standard (and
therefore most 7bit character code pages).
If you press SHIFT plus a code page character, Progress turns off the SHIFT key modifier
and maps to the appropriate character code. For example, SHIFTA is equivalent to A, and
A is mapped to keycode 65, which accords with the ASCII standard (and therefore most
7bit character code pages). Also, many code page characters (for example, the comma)
do not have uppercase equivalents; therefore, the SHIFT key modifier is turned off.
If you press ALT plus an alphabetic character, Progress maps to the uppercase alphabetic
characters. For example, ALTA and ALTa are both mapped to keycode 1089. The
keycode 1089 corresponds to the keycode 65 (A) with the ALT key modifier turned on
(65 + 1024 = 1089).
Progress provides more than one key label for certain key codes. The key labels in Table 62
are the preferred labels, but you can also use the labels in Table 63.
Table 62: Key Codes and Key Labels (1 of 12)
Key Code Key Label
0 CTRL@
1 through 7 CTRLA through CTRLG
8
BACKSPACE
9
TAB
10 through 12 CTRLJ through CTRLL
13 ENTER (Windows)
RETURN (UNIX)
14 through 26 CTRLN through CTRLZ
27
ESC
Handling User Input
67
28 CTRL\
29 CTRL]
30 CTRL^
31 CTRL_
32 through 126 Corresponding character
127
DEL
128 through 255 Corresponding extended character
300 through 399 F0 through F99
400 through 499 PF0 through PF99
501 CURSORUP
502 CURSORDOWN
503 CURSORRIGHT
504 CURSORLEFT
505
HOME
506
END
507 PAGEUP
508 PAGEDOWN
509 BACKTAB
510
INS
511 HELPKEY
512
DELETE
513
EXECUTE
Key Code Key Label
68
514
PAGE
515
FIND
516 INSLINE
517 DELLINE
518 LINEERASE
519 PAGEERASE
520 SHIFTBACKSPACE
521 SHIFTTAB
522
EXIT
535
ERASE
536
WHITE
537
BLUE
538
RED
539
RESET
541 CTRLBREAK
551 through 560 U1 through U10
609 MOUSESELECTUP
610 MOUSEMOVEUP
611 MOUSEMENUUP
612 MOUSEEXTENDUP
617 MOUSESELECTDOWN
618 MOUSEMOVEDOWN
Key Code Key Label
Handling User Input
69
619 MOUSEMENUDOWN
620 MOUSEEXTENDDOWN
625 MOUSESELECTCLICK
626 MOUSEMOVECLICK
627 MOUSEMENUCLICK
628 MOUSEEXTENDCLICK
640 MOUSEMOVE
649 MOUSESELECTDBLCLICK
650 MOUSEMOVEDBLCLICK
651 MOUSEMENUDBLCLICK
652 MOUSEEXTENDDBLCLICK
812 through 911 SHIFTF0 through SHIFTF99
912 through 1011 SHIFT PF0 through SHIFTPF99
1013 SHIFTCURSORUP
1014 SHIFTCURSORDOWN
1015 SHIFTCURSORRIGHT
1016 SHIFTCURSORLEFT
1017 SHIFTHOME
1018 SHIFTEND
1019 SHIFTPAGEUP
1020 SHIFTPAGEDOWN
1021 SHIFTBACKTAB
Key Code Key Label
610
1022 SHIFTINS
1023 SHIFTHELPKEY
1024 ALTCTRL@
1025 through 1031 ALTCTRLA through ALTCTRLG
1032 ALTBACKSPACE
1033 ALTTAB
1034 through 1036 ALTCTRLJ through ALTCTRLL
1037 ALTRETURN
1038 through 1050 ALTCTRLN through ALTCTRLZ
1051 ALTESC
1052 ALTCTRL\
1053 ALTCTRL]
1054 ALTCTRL^
1055 ALTCTRL_
1057 through 1150 ALTplus corresponding character
1151 ALTDEL
1152 through 1279 ALTplus corresponding extended character
1324 through 1423 ALTF0 through ALTF99
1424 through 1523 ALTPF0 through ALTPF99
1525 ALTCURSORUP
1526 ALTCURSORDOWN
1527 ALTCURSORRIGHT
Key Code Key Label
Handling User Input
611
1528 ALTCURSORLEFT
1529 ALTHOME
1530 ALTEND
1531 ALTPAGEUP
1532 ALTPAGEDOWN
1533 ALTBACKTAB
1534 ALTINS
1535 ALTHELPKEY
1536 ALTDELETE
1537 ALTEXECUTE
1538 ALTPAGE
1539 ALTFIND
1540 ALTINSLINE
1541 ALTDELLINE
1542 ALTLINEERASE
1543 ALTPAGEERASE
1544 ALTSHIFTBACKSPACE
1545 ALTSHIFTTAB
1546 ALTEXIT
1549 through 1558 ALTU1 through ALTU10
1559 ALTERASE
1560 ALTWHITE
Key Code Key Label
612
1561 ALTBLUE
1562 ALTRED
1563 ALTRESET
1565 ALTCTRLBREAK
1575 through 1584 ALTU1 through ALTU10
1663 SHIFTALTDEL
1664 through 1791 SHIFTALTplus corresponding extended character
1836 through 1935 SHIFTALTF0 through SHIFTALTF99
1936 through 2035 SHIFTALTPF0 through SHIFTALTPF99
2037 SHIFTALTCURSORUP
2038 SHIFTALTCURSORDOWN
2039 SHIFTALTCURSORRIGHT
2040 SHIFTALTCURSORLEFT
2041 SHIFTALTHOME
2042 SHIFTALTEND
2043 SHIFTALTPAGEUP
2044 SHIFTALTPAGEDOWN
2045 SHIFTALTBACKTAB
2046 SHIFTALTINS
2047 SHIFTALTHELPKEY
2056 CTRLBACKSPACE
2057 CTRLTAB
Key Code Key Label
Handling User Input
613
2075 CTRLESC
2080 through 2111 CTRLplus corresponding character
2171 through 2174 CTRLplus corresponding character
2175 CTRLDEL
2209 through 2303 CTRLplus corresponding extended character
2348 through 2447 CTRLF0 through CTRLF99
2448 through 2547 CTRLPF0 through CTRLPF99
2549 CTRLCURSORUP
2550 CTRLCURSORDOWN
2551 CTRLCURSORRIGHT
2552 CTRLCURSORLEFT
2553 CTRLHOME
2554 CTRLEND
2555 CTRLPAGEUP
2556 CTRLPAGEDOWN
2557 CTRLBACKTAB
2558 CTRLINS
2559 CTRLHELPKEY
2560 CTRLDELETE
2561 CTRLEXECUTE
2562 CTRLPAGE
2563 CTRLFIND
Key Code Key Label
614
2564 CTRLINSLINE
2565 CTRLDELLINE
2566 CTRLLINEERASE
2567 CTRLPAGEERASE
2568 CTRLSHIFTBACKSPACE
2569 CTRLSHIFTTAB
2570 CTRLEXIT
2573 CTRLSHIFTRETURN
2583 CTRLERASE
2584 CTRLWHITE
2585 CTRLBLUE
2586 CTRLRED
2587 CTRLRESET
2559 through 2608 CTRLU1 through CTRLU10
2860 through 2859 CTRLSHIFTF0 through CTRLSHIFTF99
2960 through 3059 CTRLSHIFTPF0 through CTRLSHIFTPF99
3061 CTRLSHIFTCURSORUP
3062 CTRLSHIFTCURSORDOWN
3063 CTRLSHIFTCURSORRIGHT
3064 CTRLSHIFTCURSORLEFT
3065 CTRLSHIFTHOME
3066 CTRLSHIFTEND
Key Code Key Label
Handling User Input
615
3067 CTRLSHIFTPAGEUP
3068 CTRLSHIFTPAGEDOWN
3069 CTRLSHIFTBACKTAB
3070 CTRLSHIFTINS
3071 CTRLSHIFTHELPKEY
3104 through 3135 CTRLALTplus corresponding character
3163 CTRLALT[
3164 CTRLALT\
3165 CTRLALT]
3166 CTRLALT^
3167 CTRLALT_
3168 CTRLALT
3195 through 3198 CTRLALTplus corresponding character
3199 CTRLALTDEL
3233 through 3327 CTRLALTplus corresponding extended character
3372 through 3471 CTRLALTF0 through CTRLALTF10
3472 through 3571 CTRLALTPF0 through CTRLALTPF99
3573 CTRLALTCURSORUP
3574 CTRLALTCURSORDOWN
3575 CTRLALTCURSORRIGHT
3576 CTRLALTCURSORLEFT
3577 CTRLALTHOME
Key Code Key Label
616
3578 CTRLALTEND
3579 CTRLALTPAGEUP
3580 CTRLALTPAGEDOWN
3581 CTRLALTBACKTAB
3582 CTRLALTINS
3583 CTRLALTHELPKEY
3585 CTRLALTEXECUTE
3586 CTRLALTPAGE
3587 CTRLALTFIND
3588 CTRLALTINSLINE
3589 CTRLALTDELLINE
3590 CTRLALTLINEERASE
3591 CTRLALTPAGEERASE
3592 CTRLSHIFTALTBACKSPACE
3593 CTRLSHIFTALTTAB
3594 CTRLALTEXIT
3597 CTRLSHIFTALTRETURN
3607 CTRLALTERASE
3608 CTRLALTWHITE
3609 CTRLALTBLUE
3610 CTRLALTRED
3611 CTRLALTRESET
Key Code Key Label
Handling User Input
617
Table 62 shows the key labels returned for each key code by the KEYLABEL function. In
addition to these key labels, some key codes have alternative labels. Although the KEYLABEL
function does not return these values, if you can pass any of these labels to the KEYCODE
function, the corresponding key code is returned. Table 63 lists the alternate key labels.
3623 through 3632 CTRLALTU1 through CTRLALTU10
3884 through 3983 CTRLSHIFTALTF0 through CTRLSHIFTALTF99
3994 through 4083 CTRLSHIFTALTPF0 through CTRLSHIFTALTPF99
4085 CTRLSHIFTALTCURSORUP
4086 CTRLSHIFTALTCURSORDOWN
4087 CTRLSHIFTALTCURSORRIGHT
4088 CTRLSHIFTALTCURSORLEFT
4089 CTRLSHIFTALTHOME
4090 CTRLSHIFTALTEND
4091 CTRLSHIFTALTPAGEUP
4092 CTRLSHIFTALTPAGEDOWN
4093 CTRLSHIFTALTBACKTAB
4094 CTRLSHIFTALTINS
4095 CTRLSHIFTALTHELPKEY
Table 63: Alternate Key Labels (1 of 2)
Key Code Alternate Key Label
7
BELL
8
BS
Key Code Key Label
618
10
LINEFEED, LF
12
FORMFEED, FF
13 RETURN (Windows)
ENTER (UNIX)
27
ESCAPE
127
CANCEL
501 UP, UPARROW
502 DOWN, DOWNARROW
503 RIGHT, RIGHTARROW
504 LEFT, LEFTARROW
505 ESCH
507 PGUP, PREVPAGE, PREVSCRN
508 PGDN, NEXTPAGE, NEXTSCRN
509 SHIFTTAB (UNIX),
BACKTAB (Windows)
510 INSERT, INSCHAR, INSC, INSERTHERE
512 DELCHAR, DELETECHAR, DELC
516 INSL, LINEINS
517 DELL, LINEDEL
Table 63: Alternate Key Labels (2 of 2)
Key Code Alternate Key Label
Handling User Input
619
6.3 Key Functions
Table 64 shows the keys that Progress maps to each key function in each user interface. Note
that graphical interfaces that have full mouse control do not require as many navigation keys.
Note also that in character interfaces, the precise mapping depends on the terminal type, and that
UNIX in particular provides many terminal types. Table 64 lists possible mappings.
NOTE: If you enter CTRLALTSHIFTF1 from a Windows Progress client, graphical or
character, Progress displays a window that tells what Progress version you are
running.
Table 64: Progress Key Functions (1 of 6)
Key Function
Key Label
Windows Graphical
Interface
UNIX
Character Interface
Windows Character
Interface
ABORT
CTRL\
APPENDLINE
CTRLA CTRLA
BACKTAB
SHIFTTAB CTRLU CTRLU
SHIFTTAB
BACKSPACE BACKSPACE BACKSPACE
CTRLH
DELCHAR
BACKSPACE
CTRLH
BELL
CTRLG
BELL
BELL

BLOCK
CTRLV CTRLV
BOTTOMCOLUMN
ESCCTRLB
BREAKLINE
ESCB
CANCELPICK
ESCCTRLX
CHOICES
ESCBACKSPACE
ESCCTRLH
CLEAR

F8
CTRLZ
F8
CTRLZ
620
CLOSE F8
ESCZ
F8
CTRLALTZ
F8
COMPILE
SHIFTF2 ESCP CTRLALTP
COPY

F11
ESCC
F11
CTRLALTC
CURSORDOWN
CURSORDOWN CURSORDOWN
CTRLJ
CURSORDOWN
CTRLJ
CURSORLEFT
CURSORLEFT CURSORLEFT
CTRLO
CURSORLEFT
CTRLO
CURSORRIGHT
CURSORRIGHT CURSORRIGHT
CTRLL
CURSORRIGHT
CTRLL
CURSORUP
CURSORUP CURSORUP
CTRLK
CURSORUP
CTRLK
CUT
CTRLX
F10
ESCX
F10
CTRLALTX
DEFAULTPOPUP
SHIFTF10 ESCU SHIFTF4
CTRLALTU
DELETECHARACTER DEL DEL
DELETE
DELETE
DELETECOLUMN
ESCCTRLZ
DELETEENDLINE
ESCK CTRLALTK
DELETEFIELD
ESCCTRLD
DELETELINE
CTRLD CTRLD
DELETEWORD
ESCD CTRLALTD
EDITORBACKTAB
CTRLB CTRLB
Key Function
Key Label
Windows Graphical
Interface
UNIX
Character Interface
Windows Character
Interface
Handling User Input
621
EDITORTAB
CTRLG
TAB
CTRLG
TAB
END END END
ESC.
END
ENDERROR ESC F4
CTRLE
F4
ESC
CTRLE
ENTERMENUBAR ALT F3
PF3
ESCM
F3
ALT
EXIT
ESCQ CTRLALTQ
FIND
CTRLF CTRLF CTRLF
FINDNEXT F9
ESCF CTRLALTF
FINDPREVIOUS
SHIFTF9 ESCI CTRLALTI
GET F3 F5
ESCO
F5
CTRLALTO
GO F2 F1
CTRLX
F1
CTRLX
GOTO
CTRLG ESCG CTRLALTG
HELP F1
ESC?
HOME HOME
ESC,
ESCH
HOME
INSERTCOLUMN
ESCCTRLN
INSERTFIELD
ESCCTRLG
INSERTFIELDDATA
ESCCTRLF
Key Function
Key Label
Windows Graphical
Interface
UNIX
Character Interface
Windows Character
Interface
622
INSERTFIELDLABEL
ESCCTRLE
INSERTMODE INSERT F9
CTRLT
INSERT
F9
CTRLT
LEFTEND HOME
ESCCURSORLEFT ALTCURSORLEFT
MAINMENU
ESCRETURN
ESCCTRLM
MOVE
ESCCTRLV
NEW
SHIFTF3 ESCN CTRLALTN
NEWLINE
CTRLN CTRLN
NEXTERROR
ESCE
NEXTFRAME F6
ESCTAB
ESCCTRLI
NEXTWORD
CTRLW
OPENLINEABOVE
ESCL CTRLALTL
OPTIONS
ESCCTRLO
PAGEDOWN
PAGEDOWN
PGDN
NEXTPAGE
NEXTSCRN
ESCCURSOR DOWN PAGEDOWN
PAGELEFT
ESCW
PAGERIGHT
ESCY
Key Function
Key Label
Windows Graphical
Interface
UNIX
Character Interface
Windows Character
Interface
Handling User Input
623
PAGEUP
PAGEUP
PGUP
PREVPAGE
PREVSCRN
ESCCURSORUP PAGEUP
PASTE CTRLV F12
ESCV
F12
CTRLALTV
PICK

ESCCTRLP

PICKAREA

ESCCTRLW

PICKBOTH

ESCCTRLQ

PREVFRAME SHIFTF6 ESCCTRLU CTRLSHIFTTAB
PREVWORD

CTRLP CTRLP
PUT F6 F6
ESCS
F6
RECALL

F7
CTRLR
REPLACE

ESCR

REPORTS

ESCCTRLA

RESUMEDISPLAY

CTRLQ

RETURN ENTER
RETURN
CTRLM
RETURN
CTRLM
ENTER
CTRLM
RIGHTEND

ESCCURSORRIGHT ALTCURSORRIGHT
SAVEAS SHIFTF6 ESCA CTRLALTA
SCROLLLEFT

ESCCTRLL
SCROLLMODE

ESCT CTRLALTT
Key Function
Key Label
Windows Graphical
Interface
UNIX
Character Interface
Windows Character
Interface
624
SCROLLRIGHT

ESCCTRLR

SETTINGS

ESCCTRL@

STOP CTRLBREAK CTRLC CTRLC
STOPDISPLAY

CTRLS

TAB TAB TAB
CTRLI
TAB
CTRLI
TOPCOLUMN

ESCCTRLT

UNIXEND

CTRL\

Key Function
Key Label
Windows Graphical
Interface
UNIX
Character Interface
Windows Character
Interface
Handling User Input
625
6.4 Changing the Function of a Key
You can globally change Progress key functions by modifying your environment. For more
information on modifying your environment, see the chapter on colors and fonts in this book
and the chapter on user interface environments in the Progress Client Deployment Guide.
Although Progress has defined functions for several of the keys on your keyboard, you can
redefine those keys to perform other functions within an application. In addition, you can assign
functions to any of the other keyboard keys.
Suppose the user is accustomed to pressing F2 to get help information and F1 to signal that they
are finished entering data. Although Progress usually treats F2 as GO and F1 as HELP, you can
switch the functions of those keys as demonstrated in the following procedure:
In this procedure, the ON statements redefine the function of F1, F2, and CTRLX. Run this
procedure, then press F1. You can see that F1 now performs the GO function, normally
performed by F2. If you press CTRLX, Progress rings the terminal bell. The new key definitions
are in effect for the duration of the session, unless you redefine them. Also, on UNIX, any key
label you use in an ON statement must have an entry in the PROTERMCAP file for your
terminal.
When you use the ON statement, you use the name of the key whose function you are
redefining, followed by the action you want to take when the user presses that key.
p-action.p
ON F1 GO.
ON F2 HELP.
ON CTRL-X BELL.
FOR EACH customer:
DISPLAY cust-num.
UPDATE Name credit-limit sales-rep.
END.
Syntax:
Meaning:
ON Statement
ON
When the user presses... ...this key... ...takes this action.
Keyboard Key Action
GO F1
626
The p-action.p procedure uses three actions: GO, HELP, and BELL. There are many other
actions you can use when redefining the function of a key. Table 65 lists these actions.
Table 65: Actions You Assign to Keys
Action Default Key
BACKSPACE
BACKSPACE
BACKTAB
SHIFTTAB, CTRLU, CODETAB
BELL
CLEAR
F8, CTRLZ, CODEZ
CURSORUP
, CTRLK
CURSORDOWN
, CTRLJ
CURSORLEFT
?, CTRLH
CURSORRIGHT
?, CTRLL
DELETECHARACTER
DEL
ENDKEY
ENDERROR F4, CTRLE, CODEE, ESC (Windows)
ERROR
GO
F2, CTRLX, CODEX
HELP
F1, HELP, CTRLW, CODEW
HOME HOME, ESCH (UNIX)
INSERTMODE
F3, INSERT, CTRLT, OVERTYPE
RECALL
F7, CTRLR, CODER
RETURN
RETURN
STOP CTRLBREAK (Windows), CTRLC (UNIX)
TAB
TAB, CTRLI
Handling User Input
627
6.5 Using Mouse Buttons and Events
Progress uses a logical (portable) model to reference mouse button input. This ensures that your
application works in whatever operating environment it runs. Progress also provides access to
the physical mouse input of your operating environment if you need it. Both forms of input are
available as events in a manner similar to keyboard events.
6.5.1 Portable and Physical Buttons
Progress supports four portable mouse buttons:
SELECT You can select or choose an object by pointing to it and clicking this mouse
button. Any previously selected object becomes deselected.
EXTEND You can toggle the selection state of an object by pointing to it and clicking
this button. This has no effect on any other object; therefore, you can use the EXTEND
button to toggle selection individually on more than one object.
MENU If an object has an associated pop-up menu, you can activate that menu by
clicking this button.
MOVE By pressing and holding this button you can drag an object on the screen.
Although Progress supports four buttons, the standard mouse used with Windows has only two
buttons. Therefore, some physical mouse buttons have double functions, or, you must use
control keys with one or more buttons. Table 66 shows the mappings between the Progress
portable mouse buttons and the physical mouse buttons on Windows.
Progress supports two main classes of mouse eventsportable and three-button events. You
can use portable mouse events to associate triggers with logical actions of any mouse. You can
use the three-button mouse events to associate triggers with specific physical actions of a
three-button mouse. The names of the portable mouse events come from the mouse key labels
Table 66: Mouse Buttons on Windows
Portable Button Windows
SELECT LEFT mouse button
EXTEND CTRL with LEFT mouse button
MENU RIGHT mouse button
MOVE LEFT mouse button
628
listed in Table 66 (for example, MOUSESELECTCLICK). They also correspond to the
names of the portable mouse buttons used to generate them. The names of the three-button
mouse events correspond to the physical buttons that generate them on a three-button mouse
(for example, LEFTMOUSECLICK). For a complete description of the names and functions
of the portable and three-button mouse events, see the Progress Language Reference.
Both portable and three-button mouse events divide into two subclasseslow-level and
high-level mouse events. Low-level mouse events are generated by the simplest mouse button
actions, while high-level events are generated by more complex actions.
6.5.2 Specifying Mouse Events
When choosing the events to associate with a trigger, use portable mouse events whenever
possible. If you use these events, Progress automatically maps the event to the mouse key the
native window system uses to perform the same event. For example, if Progress supports a
future window system that uses the right button as the selection button, the
MOUSESELECTCLICK event will automatically map to the right button for that system,
while still mapping to the left button for Windows.
Portable and Three-Button Event Priority
If you use three-button mouse events, they take priority over any corresponding portable event.
For example, if you define a MOUSESELECTCLICK and a LEFTMOUSECLICK trigger
for the same widget, Progress only fires the three-button trigger. (In this case, it only fires the
LEFTMOUSECLICK trigger.)
Low-level and High-level Events
The low-level category consists of those events triggered by mouse button motion in a single
direction, such as down or up. The high-level category consists of those events triggered by
more complex mouse button motion, such as click or double-click. For Progress, corresponding
low-level and high-level mouse events are analogous to equivalent key label and key function
events. Like key label and key function events, or three-button and portable mouse events,
low-level mouse events take priority over corresponding high-level mouse events. For example,
if you define a MOUSESELECTUP and MOUSESELECTCLICK trigger on the same
widget, only the MOUSESELECTUP trigger executes.
Like portable events, use high-level mouse events exclusively whenever possible. If you must
use low-level events, do not mix low-level and high-level event triggers on the same widget.
The processing of both classes of events on the same widget can lead to unintended results.
While Progress always recognizes corresponding low-level and high-level events, it executes
only one trigger for both. (The same is true for corresponding key label and key function events,
as well as portable and three-button mouse events). Progress looks first for a trigger on a
Handling User Input
629
low-level event. If there is no trigger on a low-level event, Progress looks for a trigger on a
high-level event. Once it finds and fires a trigger, it waits for the next event. However, each
graphic interface may recognize and pass high-level events to Progress after recognizing a
different combination of low-level events. For example, one system might recognize a
double-click on a down and another system might recognize the double-click on an up mouse
event. This causes mixed event sequences to differ significantly from interface to interface.
Thus, much like using pixels for frame and window layout, the mixing of low- and high-level
mouse events creates portability problems between graphic interfaces. Furthermore, there is no
guarantee that the expected event sequences in the same graphic interface might not change in
future versions of that interface.
6.6 Telling Progress How to Continue Processing
When you modify a field or variable, pressing GO tells Progress to accept the data in all the
modified fields and variables in the current statement and to go on to the next statement in the
procedure.
As the following figure shows, if you press GO while the cursor is in the name, creditlimit, or
salesrep fields, Progress continues on to the next statement in the procedure, which is END.
The procedure then returns to the beginning of the FOR EACH loop.
p-intro.p
Cust num Name Credit-Limit Sales-Rep
1 Lift Line Skiing 66,800 HXM
FOR EACH customer:
DISPLAY cust-num
UPDATE name credit-limit.sales-rep.
END.
GO
Continue on
to the next
Statement (END)
630
You might want to define function keys that tell Progress to continue processing data a certain
way. You can use the GOON phrase with the SET or UPDATE statement to do this, as shown
in the following procedure:
In this example, if the user presses F8, F10, or F12 while updating the customer data, the
procedure immediately goes on to the next statement in the procedure. Lets take a closer look
at this procedure.
Any key you can press while running a Progress procedure has a code, a function, and a label
associated with it. The code of a key is an integer value that Progress uses to identify that key.
For example, the code of F1 is 301. The function of a key is the work that Progress does when
you press the key. For example, the function of the F1 key may be HELP. The label of a key is
the actual label that appears on the keyboard key. The label of the F1 key is F1.
As shown earlier, you can use the KEYLABEL, KEYCODE, KEYFUNCTION, and
KBLABEL functions to convert key labels, key codes, and key functions. In addition to these
functions, the LASTKEY function returns the key code of the last key pressed.
p-gon1.p
DISPLAY "You may update each customer." SKIP
"After making your changes, press one of:" SKIP(1)
KBLABEL("GO") + " - Make the change permanent" FORMAT "x(40)"
SKIP
KBLABEL("END-ERROR") + " - Undo changes and exit" FORMAT "x(40)"
SKIP
"F8 - Undo changes and try again" SKIP
"F10 - Find next customer" SKIP
"F12 - Find previous customer"
WITH CENTERED FRAME ins.
FIND FIRST Customer.upd-loop:
REPEAT:
UPDATE Cust-num Name Address Address2 City St
GO-ON(F8 F10 F12) WITH 1 DOWN CENTERED.
CASE LASTKEY:
WHEN KEYCODE("F8") THEN
UNDO upd-loop, RETRY upd-loop.
FIND NEXT Customer.
FIND PREV Customer.
END CASE.
END.
Handling User Input
631
You can use the functions described in this table to monitor the keys being pressed, as in this
example:
Run procedure p-keys.p to see how the different keys you press translate into key codes, key
labels, and key functions.
p-keys.p
REPEAT:
DISPLAY "Press any key".
READKEY.
DISPLAY LASTKEY LABEL "Key Code"
KEYLABEL(LASTKEY) LABEL "Key Label"
KEYFUNCTION(LASTKEY) LABEL "Key Function"
FORMAT "x(12)".
IF KEYFUNCTION(LASTKEY) = "end-error" THEN LEAVE.
END.
632
Now, run the p-gon1.p procedure. You see a screen similar to the one shown in the following
figure:
Figure 64: The p-gon1.p Procedure
Do next
statement
Continue on CASE
GO F8 F10 F12
Cust-Name
City State
Address Address 2
1 Lift Line Skiing 276 North Street
Boston
MA
Last key pressed
KEYCODE(F8)
KEYCODE(F10)
KEYCODE(F12)
UNDO,
RETRY
FIND PREV
customer
FIND NEXT
customer
You may update each customer.
After making your changes, press one of:
F2 - Make the change permanent
ESC - Undo changes and exit
F8 - Undo changes and try again
F10 - Find next customer
F12 - Find previous customer
Handling User Input
633
While updating the customer information, press F9, F10, F11, or use either of the standard
techniques to signal the end of data entry, Progress goes on to the next statement in the
procedure. If you press any other key, Progress does not continue on to the next statement in the
procedure, but instead performs the data entry operation associated with that key. If you press
ENDERROR, Progress performs the default ENDKEY processing of UNDO, LEAVE. See
Condition Handling and Messages, for more information on ENDKEY processing.
If Progress does continue on to the next statement in the procedure, the CASE statement
determines the action to take by checking the value of the last key pressed.
634
The procedure p-gon2.p shows how you can achieve the same functionality in an event-driven
application:
p-gon2.p (1 of 2)
FORM
Customer.Cust-num Customer.Name Customer.Address
Customer.Address2 Customer.City Customer.State
WITH CENTERED FRAME upd-frame.
DISPLAY "You may update each customer." SKIP
"After making your changes, press one of:" SKIP(1)
KBLABEL("GO") + " - Make the change permanent" FORMAT "x(40)"
SKIP
KBLABEL("END-ERROR") + " - Undo changes and exit" FORMAT "x(40)"
SKIP
"F8 - Undo changes and try again" SKIP
"F10 - Find next customer" SKIP
"F12 - Find previous customer"
WITH CENTERED FRAME ins.
ON F8 ANYWHERE
DO:
DISPLAY Customer.Cust-num Name Address City State
END.
ON F10 ANYWHERE
DO:
APPLY "GO" TO FRAME upd-frame.
FIND NEXT Customer.
DISPLAY Cust-num Name Address Address2 City State
END.
ON F12 ANYWHERE
DO:
APPLY "GO" TO FRAME upd-frame.
FIND PREV Customer.
DISPLAY Cust-num Name Address Address2 City State
END.
Handling User Input
635
Use the ANYWHERE option of the ON statement to set up triggers that execute no matter
which widget has input focus. In p-gon2.p, the ANYWHERE option is used to assign triggers
to function keys.
NOTE: In a larger program, you must be careful of the scope of the ANYWHERE trigger.
6.7 Monitoring Keystrokes During Data Entry
Progress provides two methods to monitor keystrokesediting blocks and user interface
triggers.
6.7.1 Editing Blocks
Prior to Progress Version 7 and user interface triggers, editing blocks were the only method
available to monitor individual keystrokes. An editing block is part of an UPDATE, SET, or
PROMPTFOR statement that allows the programmer to read and process each keystroke
individually. Editing blocks are used for two purposes:
To enable a few special keys in one or more fields while allowing normal data entry.
To disallow normal data entry in one or more fields and instead allow the use of only a few
special keys to change the value.
Each type of editing block can now be replaced with user interface triggers.
6.7.2 User Interface Triggers
Progress allows you to access all keystrokes as events. You can intercept these events using the
ON statement or the trigger phrase of any statement that declares a user interface widget. For
each intercepted event, you can provide a user interface trigger to implement any Progress
action. This action can add to, and often replace, the default action associated with the event.
ON GO OF FRAME upd-frame
ASSIGN FRAME upd-frame Customer.Cust-num Name Address Address2
City State.
ENABLE ALL WITH FRAME upd-frame.
APPLY "F8" TO FRAME upd-frame.
WAIT-FOR END-ERROR OF FRAME upd-frame.
p-gon2.p (2 of 2)
636
All Progress key labels and key functions are valid events. You can specify a keyboard event in
the ON statement or trigger phrase by:
Using the key label name, such as f2.
Using the key function name, such as go.
Key label events take priority over corresponding key function events. For example, if you
specify a trigger for the TAB key function event and another trigger on the same widget for the
CTRLI key label event, only the CTRLI trigger executes.
Where a key label event corresponds to a key function, use the key function event whenever
possible. Key functions are more portable. If you must reference key label events, be sure not
to also reference corresponding key function events for the same widget.
6.7.3 Using Editing Blocks and User Interface Triggers
This procedure uses an editing block to enable a special key while allowing normal data entry:
p-kystka.p
DEFINE FRAME cust-frame
Customer.Cust-num SKIP Customer.name SKIP Customer.address SKIP
Customer.address2 SKIP Customer.city Customer.state SKIP
Customer.sales-rep HELP "To see a list of values, press F6."
WITH DOWN SIDE-LABELS.
REPEAT WITH FRAME cust-frame:
PROMPT-FOR Customer.Cust-num.
FIND Customer USING Cust-num.
UPDATE Name Address Address2 City State Customer.Sales-rep
EDITING:
READKEY.
IF FRAME-FIELD = "sales-rep" AND LASTKEY = KEYCODE("F6")
THEN DO:
FOR EACH Salesrep:
DISPLAY Salesrep.Sales-rep
WITH NO-LABELS 9 DOWN COLUMN 60 ROW 5.
END.
END.
ELSE DO:
APPLY LASTKEY.
END.
END.
END.
Handling User Input
637
This procedure uses an EDITING block on the UPDATE statement. This means that the
EDITING block processes every keystroke the user enters while that UPDATE statement is
executing. Within the EDITING block, the READKEY statement reads a keystroke from the
user. The associated key code is automatically stored as LASTKEY. The procedure uses
LASTKEY and the FRAMEFIELD function to determine whether the key is F6, and whether
it was entered from within the Salesrep field. If so, it displays a list of all known sales reps. If
the key is not F6, or the current field is not the Salesrep field, then the APPLY statement is
executed. This causes Progress to handle the keystroke normally.
This procedure uses a user interface trigger in place of the EDITING block to achieve the same
functionality:
Use a trigger in place of the EDITING block to produce simpler, cleaner code. It would be easier
to rewrite this code to be more event driven. First, replace the UPDATE statement with
ENABLE, WAITFOR, and ASSIGN. You then might remove the REPEAT block and define
a button that the user can select to move to the next Customer record. You might also replace
the display of sales reps with a selection list or browse widget.
p-kystkb.p
Customer.Cust-num SKIP Customer.name SKIP Customer.address SKIP
Customer.address2 SKIP Customer.city Customer.state SKIP
Customer.sales-rep HELP "To see a list of values, press F6."
WITH DOWN SIDE-LABELS.
ON F6 OF Customer.Sales-rep
DO:
FOR EACH salesrep:
DISPLAY Salesrep.Sales-rep
WITH NO-LABELS 9 DOWN COLUMN 60 ROW 5.
END.
END.
UPDATE Name Address Address2 City State Sales-rep.
END.
638
The following procedure uses an EDITING block to disallow normal data entry on a field and
allow only a special key:
Like p-kystka.p, this procedure uses an EDITING block on the UPDATE statement. In the
EDITING block, it uses READKEY, LASTKEY, and FRAMEFIELD to obtain and analyze a
keystroke. If the keystroke is not in the Salesrep field, it is processed normally. Within the
Salesrep field, only the spacebar is treated specially and only the TAB, BACKTAB, GO, and
ENDERROR key functions are treated normally. If the user types any other key within the
field, the terminal bell sounds. When the user presses the spacebar in the Salesrep field, the
value of that field and the Salesregion field change.
p-kystk.p
Customer.Cust-num SKIP Customer.Name SKIP Customer.Address SKIP
Customer.Address2 SKIP Customer.City Customer.State SKIP
Customer.Sales-rep HELP "Use the space bar to scroll the values."
WITH SIDE-LABELS.
UPDATE Name Address City State Sales-rep
EDITING:
READKEY.
IF FRAME-FIELD <> "Sales-rep"
THEN DO:
APPLY LASTKEY.
END.
ELSE DO:
IF LASTKEY = KEYCODE(" ")
THEN DO:
FIND NEXT Salesrep NO-ERROR.
IF NOT AVAILABLE Salesrep
THEN FIND FIRST Salesrep.
DISPLAY Salesrep.Sales-rep @ Customer.Sales-rep.
END.
ELSE IF LOOKUP(KEYFUNCTION(LASTKEY),
"TAB,BACK-TAB,GO,END-ERROR") > 0
THEN APPLY LASTKEY.
ELSE BELL.
END.
END.
END.
Handling User Input
639
The following procedure uses triggers to accomplish the same thing:
Note the use of RETURN NOAPPLY in both the ANYPRINTABLE and spacebar trigger.
This is equivalent to omitting the APPLY LASTKEY statement in an EDITING block. Thus,
the spacebar trigger brings the next Salesrep into view, without also inserting a space character
in the field.
Note also that in p-kystk2.p the ANYPRINTABLE trigger rejects all keys that enter data
characters other than a space. This works together with the spacebar trigger to allow only the
spacebar and navigation keys (TAB, etc.) in the field.
p-kystk2.p
Customer.Address2 SKIP Customer.City SKIP Customer.State SKIP
Customer.Sales-rep HELP "Use the space bar to scroll the values"
WITH SIDE-LABELS.
ON " " OF Customer.Sales-rep
DO:
FIND NEXT Salesrep NO-LOCK NO-ERROR.
IF NOT AVAILABLE Salesrep
THEN FIND FIRST Salesrep NO-LOCK.
DISPLAY Salesrep.Sales-rep @ Customer.Sales-rep
WITH FRAME cust-frame.
RETURN NO-APPLY.
END.
ON ANY-PRINTABLE OF Customer.Sales-rep
DO:
BELL.
RETURN NO-APPLY.
END.
FIND Salesrep OF Customer NO-LOCK.
UPDATE Name Address Address2 City State Customer.Sales-rep.
END.
640
Sometimes an EDITING block defines a special key that applies for all active fields:
In p-kystk3.p, the EDITING block defines a special key, F6, that is available in all fields of the
UPDATE statement. When the user presses this key, the previous Customer record displays.
p-kystk3.p
Customer.Sales-rep WITH SIDE-LABELS.
MESSAGE "Press F6 to see the previous Customer.".
UPDATE Name Address Address2 City State Sales-rep
EDITING:
READKEY.
IF KEYLABEL(LASTKEY) = "F6"
THEN DO:
FIND PREV Customer NO-ERROR.
IF NOT AVAILABLE Customer
THEN FIND FIRST Customer.
DISPLAY Cust-num Name Address City State Sales-rep
END.
ELSE APPLY LASTKEY.
END.
HIDE MESSAGE.
END.
Handling User Input
641
The following procedure uses a trigger to achieve the same result:
If you define a trigger to be active ANYWHERE, then it applies to all widgets. In p-kystk4.p,
the F6 trigger executes whenever the user presses F6 while input is enabled. Within the trigger,
the FRAMEFIELD function determines whether the t rigger executes from the UPDATE or
PROMPTFOR statement. If it is the PROMPTFOR statement, then F6 is ignored; if it is the
UPDATE statement, the previous Customer record displays.
NOTE: In a larger program, be careful of the scope of the ANYWHERE trigger. You are
usually better off listing the specific widgets to which a trigger applies. For example,
you could rewrite the ON statement in p-kystrk4.p as follows:
If you take this approach, you can remove the code that checks whether FRAMEFIELD
is Custnum within the trigger.
p-kystk4.p
Customer.Sales-rep WITH SIDE-LABELS.
ON F6 ANYWHERE
DO:
IF FRAME-FIELD = "Cust-num"
THEN RETURN NO-APPLY.
FIND PREV Customer NO-ERROR.
THEN FIND FIRST Customer.
DISPLAY Cust-num Name Address City State Sales-rep
END.
MESSAGE "Press F6 to see the previous Customer.".
UPDATE Name Address Address2 City State Sales-rep.
HIDE MESSAGE.
END.
ON F6 OF Name, Address, Address2, City, State, Sales-rep
642
7
Alternate I/O Sources
Most of the procedures you have seen so far have used the terminal as the input source (the user
types in data) and as the output destination (data is displayed to the user).
However, youve probably already thought of situations in which you might want to get data
from and send data to locations other than the terminal. For example, you might want to send
reports to your printer or an operating system file.
This chapter describes input/output and then covers the following topics:
Changing the output destination and input source
Defining additional input/output streams and sharing streams
Importing data from a process and piping data to a processes
Performing code page (character set) conversions
Reading the contents of a directory
Converting non-standard input files
Terminal
Get Input
Send Output
Procedure
72
7.1 Understanding Input and Output
When a Progress procedure gets input from the terminal, it uses an input stream. Similarly,
when the procedure sends output to the terminal, it uses an output stream.
Every procedure automatically gets one input stream and one output stream. These are called
the unnamed streams. By default, Progress assigns both of these unnamed streams to the
terminal, as shown in Figure 71.
p-io.p
Figure 71: The Unnamed Streams
This procedure contains no special syntax about where to get and send data so Progress
automatically assigns the input stream and the output stream to the terminal.
7.2 Changing the Output Destination
You use the OUTPUT TO statement to name a new destination for output. All statements that
output data (such as DISPLAY or SET) use the new output destination. The possible
destinations include:
The printer
An operating system file or device
The terminal (by default)
The system clipboard (Windows only)
Terminal
Output
Stream
Input
Stream
DISPLAY name state credit-limit.
END.
REPEAT:
73
7.2.1 Output to Printers
Figure 72 shows the output stream being redirected to a printer using the PRINTER option of
the OUTPUT TO statement.
p-iop2.p
Figure 72: Redirecting the Unnamed Output Stream
If you run the procedure, you do not see anything displayed on your terminal because all the
output from the DISPLAY statement goes to the printer. The STREAMIO Frame phrase
option formats the output especially for character-based destinations. See the section Stream
I/O vs. Screen I/O for more information.
Output
Stream
Terminal
OUTPUT TO PRINTER.
FOR EACH customer:
DISPLAY name address city state postal-code
credit-limit WITH STREAM-IO.
END.
Customer
Report
74
7.2.2 Additional Options for Printing on Windows
On Windows, you can also get a list of printers, change the default printer for the session, and
provide access to the Print dialog box.
Getting a List of Printers
You can use the GET-PRINTERS option of the SESSION statement to obtain a list of the
printers configured for the current system. The following example shows you how to obtain the
list of currently configured printers, select a printer, and print to it:
The following list explains the important elements in the example above:
1. Create two variables: one for the output of SESSION:GETPRINTERS; the other, for the
output of LOOKUP.
2. The SESSION: GETPRINTERS method returns a comma-separated list of printers that
are currently configured on the system.
3. The LOOKUP function obtains an integer that gives the position of SpecialPrinter in the
list. If the printer is not in the list, it returns a 0.
4. The IF statement determines whether the printer SpecialPrinter is available and if so,
prints to it.
p-wgetls.p
/*1*/ DEFINE VARIABLE printer-list AS CHARACTER.
DEFINE VARIABLE printer-idx AS INTEGER.
/*2*/ printer-list = SESSION:GET-PRINTERS().
/*3*/ printer-idx = LOOKUP("SpecialPrinter", printer-list).
/*4*/ IF printer-idx > 0 THEN DO:
MESSAGE "output" VIEW-AS ALERT-BOX.
OUTPUT TO PRINTER "SpecialPrinter".
END.
/*5*/ ELSE DO:
OUTPUT TO PRINTER.
END.
FOR EACH customer WHERE country = "Finland" :
DISPLAY NAME country.
END.
/*6*/ OUTPUT CLOSE.
75
5. If the printer SpecialPrinter is not available, the ELSE DO statement prints to the default
printer.
6. The OUTPUT CLOSE statement stops sending output to the current destination and
redirects output to the destination used prior to OUTPUT TO. See the section Stream I/O
vs. Screen I/O for more information.
Changing the Default Printer
To change the default printer for the session, you can use the PRINTERNAME option of the
SESSION statement as shown in the following example.
1. Create a variable for the output of SESSION:PRINTERNAME.
2. The SESSION:PRINTERNAME attribute returns the name of the default printer.
3. The SESSION:PRINTERNAME attribute sets another printer, \\AB1\hplaser, as the
default printer.
4. The OUTPUT TO PRINTER prints the report on the printer \\AB1\hplaser.
5. The SESSION:PRINTERNAME attribute restores the original default printer.
Providing Access to the Print Dialog Box
You can use the SYSTEMDIALOG PRINTERSETUP statement to provide access to the
Windows print dialog box. This allows the application user to set up the printer or even change
the printer that receives the output.
p-wchpr.p
/*1*/ DEFINE VARIABLE printername AS CHARACTER.
/*2*/ printername = SESSION:PRINTER-NAME
/*3*/ SESSION:PRINTER-NAME = "\\AB1\hplaser".
/*4*/ OUTPUT TO PRINTER.
FOR EACH customer:
DISPLAY name SPACE balance.
END.
/*5*/ SESSION:PRINTER-NAME = printername.
76
7.2.3 Output to Files or Devices
You can direct the report to a standard text file. Replace the PRINTER option of the OUTPUT
TO statement in Figure 72 as follows:
In this OUTPUT TO statement, rpt-out is the name of the file where you direct the output. ON
UNIX, the filename is case sensitive. That is, UNIX treats rpt-out and RPT-OUT as two different
files. However, to most other operating systems, these are the same file.
The PAGED option indicates that you want a page break in the output every 56 lines. PAGED
is automatic for output to a printer. If you do not use the PAGED option, Progress sends the data
to the file continuously without any page break control characters.
You can also use the VALUE option to specify filenames stored in variables or fields. For
information, see the Sending Output to Multiple Destinations section.
Some operating systems (like UNIX) allow you to send output to devices other than printers,
terminals, and disk files using a name (like a filename) to reference them. You redirect output
to these devices exactly like files.
7.2.4 Output to the Clipboard
In general, you use the CLIPBOARD system handle to write output to the system clipboard (in
graphical environments) or Progress clipboard (in character environments). However, on
Windows, you can use the OUTPUT TO statement to redirect output to the system clipboard
using the CLIPBOARD option (quotes required). This allows you to use Progress output
statements (such as DISPLAY) to buffer up to 64K of data to the clipboard. You send the
buffered data to the clipboard by changing or closing the output destination (using the OUTPUT
CLOSE statement). For more information on changing and closing the output destination, see
the Sending Output to Multiple Destinations section. For more information on using the
CLIPBOARD system handle for output (and also input), see the Progress External Program
Interfaces manual.
7.2.5 Resetting Output to the Terminal
You can reset any output destination to the terminal using the TERMINAL option of the
OUTPUT TO statement. For more information, see the Sending Output to Multiple
Destinations section.
OUTPUT TO rpt-out PAGED.
77
7.2.6 Sending Output to Multiple Destinations
At some points in a procedure, you might want to send output to the terminal, but at other points
you might want to send output to a file. Progress does not restrict you to one output destination
per procedure.
p-chgot2.p
Figure 73: Multiple Output Destinations
In the procedure in Figure 73, you supply the name of the file where you want to send a
customer report and then, if that file does not already exist, send the report to that file.
Output
Destinations
Terminal
Operating
System File
DEFINE VARIABLE outfile AS CHARACTER FORMAT "x(8)"
LABEL "Output file name".
getfile:
DO ON ERROR UNDO, RETRY:
SET outfile WITH SIDE-LABELS.
IF SEARCH(outfile) = outfile THEN DO:
MESSAGE "A file named" outfile "already exists".
MESSAGE "Please use another name".
BELL.
UNDO getfile, RETRY getfile.
END.
END.
OUTPUT TO VALUE(outfile).
FOR EACH customer:
DISPLAY name credit-limit
WITH NO-BOX NO-LABELS STREAM-IO.
END.
78
Here are the specific steps the procedure takes:
1. The SET statement prompts you for the filename.
2. The SEARCH function searches for the file, returning the filename if the file is found.
3. If the file is found, the procedure:
Displays a message telling you the file already exists and to use another filename.
Rings the terminal bell.
Undoes the work done in the DO block and retries the block, giving you the
opportunity to supply a different filename.
4. If the file is not found, the procedure uses this statement:
This statement redirects the output to the file you specified. You must use the VALUE
keyword with the OUTPUT TO statement. The VALUE option tells Progress to use the
value of the outfile variable rather than the name outfile itself. If instead you say
OUTPUT TO outfile, Progress assumes that outfile is the name of the text file to which
you want to send output.
You use the OUTPUT CLOSE statement to stop sending output to a destination. Output sent
after the OUTPUT CLOSE statement goes to the destination used prior to the OUTPUT TO
statement.
OUTPUT TO VALUE(outfile).
79
For example, the procedure in Figure 74 uses the OUTPUT CLOSE statement to reset the
output destination from a file to the terminal.
p-out.p
Figure 74: The OUTPUT CLOSE Statement
This procedure sends customer information to a file called cust.dat. Then the procedure
displays the word Finished on your terminal screen. The specific steps in the procedure are as
follows:
1. The OUTPUT TO statement redirects output so all statements that normally send output
to the terminal send output to the cust.dat file.
2. The FOR EACH customer and DISPLAY statements produce a report listing each
customers name, address, city, and state. The procedure sends the report to the cust.dat
file.
3. The OUTPUT CLOSE statement resets the output destination for the procedure from the
cust.dat file to the terminal.
4. The last DISPLAY statement displays the message Finished on the terminal screen.
If the output destination prior to execution of p-out.p was the printer (or any destination other
than the terminal), you must explicitly set the output destination to the terminal between Steps
Terminal
Operating
System File
(cust.dat)
Output
Destinations
p-out.p
OUTPUT TO cust.dat.
FOR EACH customer:
DISPLAY cust-num name address address2 city state
SKIP(2) WITH 1 COLUMN SIDE-LABELS STREAM-IO.
END.
OUTPUT CLOSE.
DISPLAY "Finished".
710
3 and 4 using the OUTPUT TO statement with the TERMINAL option. Otherwise the OUTPUT
CLOSE statement resets the output destination to the printer (or other prior destination).
7.2.7 Stream I/O vs. Screen I/O
When you compile a procedure, Progress automatically lays out the frames as appropriate for
the current screen display. The layout differs across user interfaces because some fields have
special decoration. The font also affects the size, and therefore the layout, of fields.
However, when you are displaying a frame to a file or printer rather than the screen, you do not
want Progress to design the frame for screen display. You want Progress to lay out the field for
a character display using a fixed font and fields without decorations. Otherwise, output written
to a printer or operating system file may be unattractive or even partially unreadable. You also
want Progress to represent all data fields as text, not as graphical widgets such as editors or
sliders.
Progress provides two mechanisms to deal with these issues:
The STREAMIO option of the COMPILE statement
The STREAMIO and SCREENIO options of the Frame phrase
If all output from a procedure is to printers or operating system files, you can use the
STREAMIO option of the COMPILE statement. This forces Progress to lay out all frames
using a standard fixed font and to display all data fields as simple text fields. The following
widget types are converted to text:
Editors
Selection lists
Sliders
Radio sets
Toggle boxes
If you only write a few frames to a printer or file in your procedure, you can use the
STREAMIO frame option to mark those frames. This forces Progress to lay out only those
specific frames for output to a printer or file. If you do not specify STREAMIO in the
COMPILE statement, then all other frames are designed for screen display.
If only a few screens in your procedure are displayed to a screen, you use the SCREENIO
frame option to mark those frames. Then compile with STREAMIO so that all other frames
are laid out for display to a printer or file.
711
7.2.8 A Printing Solution
The Progress ADE toolset provides a portable solution for printing text files. The solution is a
procedure called _osprint.p and it is located in the adecomm directory in the Progress product
directory (DLC). You can also access the source code for this procedure in the src/adecomm
directory located in the Progress product directory.
The _osprint.p procedure sends a specified text file to the default printer as paged output.
Input parameters for the procedure allow you to specify values that configure a print job. On
Windows, you can also direct the _osprint.p procedure to display the Print dialog box and
print the text in a specified font. Use the following syntax to call the _osprint.p procedure from
a Progress procedure:
The parameters of the _osprint.p procedure are as follows:
INPUT parentWindow
A window handle identifying the parent window for Print dialog box and any print status
messages on Windows. The procedure ignores a value specified for this parameter in
character interfaces. If you specify the unknown value (?) or an invalid handle on
Windows, the procedure uses the CURRENTWINDOW handle.
INPUT printFile
A string value representing the name of a text file to print. You can specify an absolute or
relative path for the file. The _osprint.p procedure uses the PROPATH to locate the file.
SYNTAX
RUN adecomm/_osprint.p
( INPUT parentWindow , INPUT printFile ,
INPUT fontNumber , INPUT PrintFlags . INPUT pageSize ,
INPUT pageCount , OUTPUT result
).
712
INPUT fontNumber
An integer value representing an entry in the font table maintained by the FONTTABLE
handle. The _osprint.p procedure uses the specified font to print the text file on
Windows. The procedure ignores a value specified for this parameter in character
interfaces. If you specify the unknown value (?) or an integer value that does not exist in
the font table for Windows, the procedure uses the default system font to print the text file.
INPUT PrintFlags
An integer value that determines which printing options are used for a print job on
Windows (only). You can use the values in Table 71. If you need to use more than one
option, add the values of the options together. In all cases, the _osprint.p procedure sets
the value of the PRINTERCONTROLHANDLE attribute of the SESSION handle to
zero (0).
Table 71: Printing Options for Windows
Printing Option Value Selection
Context 0 Default print context
1 Print dialog box. This allows the user to establish a
print context.
Landscape orientation 2 Landscape orientation
Paper Size 4 Letter
8 Legal
12 A4
Paper Tray 32 Upper tray
64 Middle tray
96 Lower tray
128 Manual
160 Auto
713
INPUT pageSize
An integer value representing the number of lines per page. If you specify zero (0) for this
parameter, the printer determines the page size. Windows ignores this parameter and
calculates the page size based on the Paper Size setting in the Print Setup dialog box and
the font specified with the fontNumber parameter.
NOTE: The maximum number of character per line is 255.
INPUT pageCount
An integer value that determines if _osprint.p prints the entire text file or a range of
pages from the text file on Windows. The procedure ignores a value specified for this
parameter in character interfaces. If the value of this parameter is not zero (0) on Windows,
Progress uses the page range specified for the current print context.
OUTPUT result
A logical value that reports the success or failure of the print job.
To call the _osprint.p procedure from a Progress procedure, you must define a variable for the
result output parameter. Here is an example:
_osprint.p
/*1*/ DEFINE VARIABLE result AS LOGICAL NO-UNDO.
/*2*/ OUTPUT TO tmp.dat.
FOR EACH customer:
DISPLAY Cust-num Name Phone WITH STREAM-IO.
END.
OUTPUT CLOSE.
/*3*/ RUN adecomm/_osprint.p (INPUT ?, INPUT "tmp.dat", INPUT ?, INPUT 1,
INPUT 0, INPUT 0, OUTPUT result).
/*4*/ OS-DELETE "tmp.p".
714
The following list describes the important elements of the previous example:
1. Create a variable for the OUTPUT parameter of the _osprint.p procedure.
2. Generate the temporary text file to be printed. Remember to close the output stream after
generating the text file.
3. Run the _osprint.p procedure to print the generated text file.
4. Delete the temporary text file.
For more information on the language elements referenced in this section, see the Progress
Language Reference.
7.3 Changing a Procedures Input Source
You use the INPUT FROM statement to name a new source for input. The possible sources
include:
An operating system file or device
The contents of an operating system directory
The terminal (by default)
All statements (such as UPDATE or SET) that require data use the new input source.
7.3.1 Input From Files
A data file (not a database table) that contains information on new customers might look like
the following example:
This file is in standard Progress format. That is, blanks separate the field values. Field values
that contain embedded blanks are surrounded by quotation marks ( ). Later sections in this
chapter discuss using alternate formats.
You can write a Progress procedure and tell that procedure to get its input from the p-datf1.d
file. See Figure 75.
p-datf1.d
90 "Wind Chill Hockey" BBB
91 "Low Key Checkers" DKP
92 "Bings Ping Pong" SLS
715
p-chgin.p
Figure 75: Redirecting the Unnamed Input Stream
The SET statement, which normally gets its input from the terminal, gets its input from the
p-datf1.d file. The custnum field uses the first data item, 90. The name field uses the next
quoted data item, Wind Chill Hockey, etc. Each time Progress processes a data entry
statement, it reads one line from the file.
7.3.2 Input from Devices, Directories, and the Terminal
Some operating systems (like UNIX) let you receive input from devices other than terminals
and disk files and let you use a name (like a filename) to reference them. You redirect input from
these devices exactly like files. For more information, see the Input From Files section.
You can read the contents of a directory using the OSDIR option of the INPUT FROM
statement. For more information on reading the contents of a directory, see the Reading the
Contents of a Directory section.
You can reset any input source to the terminal using the TERMINAL option of the INPUT
FROM statement. For more information, see the Receiving Input from Multiple Sources
section.
Terminal
Operating
System File
p-chgin.p
INPUT FROM p-datf1.d.
REPEAT:
CREATE customer.
SET cust-num name sales-rep.
END.
Input
Stream
716
7.3.3 Receiving Input from Multiple Sources
At some points in a procedure you might want to get input from the terminal, but at other points
you might want to get input from a file. A single procedure can use multiple input sources.
For example, suppose you want to create records for the customers in the p-datf1.d data file.
Before creating the records, you probably want to display the customer numbers in the file and
ask if the user wants to create customer records for those numbers. To do this, you need input
from the terminal. If the user wants to create customer records for the customers in the
p-datf1.d file, you also need input from the file.
The p-chgin2.p procedure uses multiple input sources to perform the work described above.
Because p-chgin2.p uses the same data file (p-datf1.d) you used in the previous section to
create customer records, you must delete customers 90, 91, and 92 from your database before
you run p-chgin2.p. Use the following procedure to delete the customers:
p-io3.p
FOR EACH customer WHERE cust-num > 89:
DELETE customer.
END.
717
Figure 76 shows the p-chgin2.p procedure.
p-chgin2.p
Figure 76: Multiple Input Sources
p-chgin2.p
DEFINE VARIABLE cust-num-var LIKE customer.cust-num.
DEFINE VARIABLE name-var LIKE customer.name.
DEFINE VARIABLE sales-rep-var LIKE customer.sales-rep.
DEFINE VARIABLE answer AS LOGICAL.
DISPLAY "The customers in the data file are: " WITH NO-BOX.
REPEAT WITH 10 DOWN COLUMN 38:
SET cust-num-var name-var sales-rep-var WITH NO-BOX.
END.
INPUT FROM TERMINAL.
SET answer LABEL
"Do you want to create database records for these
customers?"
WITH SIDE-LABELS NO-BOX FRAME ans-frame.
IF answer
THEN DO:
DISPLAY "Creating records for..." WITH FRAME ans-frame.
REPEAT:
CREATE customer.
SET cust-num name sales-rep WITH NO-BOX COLUMN 28.
END.
END.
Terminal
Operating
System File
Input
Sources
718
These are the specific steps the procedure follows:
1. The DISPLAY statement displays some text.
2. The first INPUT FROM statement redirects the input source to the p-datf1.d file.
3. The SET statement assigns the values in the p-datf1.d file to the custnumvar,
namevar, and salesrepvar variables. As it assigns the values to these variables, you see
the values on the terminal screen.
4. The INPUT FROM TERMINAL statement redirects the input source to the terminal. The
INPUT CLOSE statement could have been used instead of the INPUT FROM
TERMINAL statement. However, since this procedure might have been called from
another procedure, it is better to be explicit about the input source you want to use.
5. The SET answer statement prompts you to create database records for the customer data
just displayed. If you answer yes, the procedure:
Redirects the input source to come from the beginning of the p-datf1.d file.
Creates a customer record and assigns values to the custnum., name, and salesrep
fields in that record for each iteration of a REPEAT block.
Ends the REPEAT block when the SET statement reaches the end of the input file.
7.3.4 Reading Input with Control Characters
You can use the BINARY option of the INPUT FROM statement to read control characters.
Input sources often contain control characters that affect the format or quantity of data that you
receive. For example, a text file might contain NUL (\0) characters to terminate character
strings. Without the BINARY option, Progress ignores all input on a line after the first NUL
character. The BINARY option allows you to read all the data in the file, including any NUL
and other non-printable control characters without interpretation.
7.4 Defining Additional Input/Output Streams
When you start a procedure, Progress automatically provides that procedure with input and
output streams. As described in the previous sections, the default source for the input stream is
the terminal and the default destination for the output stream is also the terminal. You saw how
to use the INPUT FROM and OUTPUT TO statements to redirect these input and output
streams.
719
You might find that having just one input stream and one output stream is not enough for
particular procedures. That is, you might want to get input from more than one source at the
same time or send output to more than one destination at the same time.
Suppose you want to produce a report of the items you have in inventory and you want to send
the report to a file. You already know how to use the OUTPUT TO statement to redirect the
output stream to a file. Suppose that you also want to produce an exceptions report at the same
time. Any item where the allocated amount is greater than the on-hand amount is an exception.
Figure 77 illustrates this scenario.
Figure 77: Multiple Output Streams Scenario
For items that are exceptions, the procedure needs to send output to a second location. That
means you need two different output streams.
You use the DEFINE STREAM statement to define additional streams for a procedure to get
input from more than one source simultaneously and send output to more than one destination
simultaneously. Streams you name can be operating system files, printers, the terminal, or other
non-terminal devices.
Read each record in
the item file.
Write some data from
the item record to the
file that contains the
Item inventory report.
If the allocated amount
of the item is greater
than the amount on
hand, write some data
to the file that contains
the item exception
report.
Item Inventory
Report
Item Exception
Report
Operating
System File
Operating
System File
1.
2.
3.
720
The procedure p-dfstr.p uses the two report scenarios shown in Figure 77.
p-dfstr.p
DEFINE STREAM rpt.
DEFINE STREAM exceptions.
DEFINE VARIABLE fnr AS CHARACTER FORMAT "x(12)".
DEFINE VARIABLE fne AS CHARACTER FORMAT "x(12)".
DEFINE VARIABLE excount AS INTEGER LABEL "Total Number of
exceptions".
DEFINE VARIABLE exception AS LOGICAL.
/*1*/ SET fnr LABEL "Enter filename for report output" SKIP(1)
fne LABEL "Enter filename for exception output"
WITH SIDE-LABELS FRAME fnames.
/*2*/ OUTPUT STREAM rpt TO VALUE(fnr) PAGED.
OUTPUT STREAM exceptions TO VALUE(fne) PAGED.
/*3*/ DISPLAY STREAM rpt "Item Inventory Report" SKIP(2)
WITH CENTERED NO-BOX FRAME rpt-frame STREAM-IO.
/*4*/ DISPLAY STREAM exceptions "Item Exception Report" SKIP(2)
WITH CENTERED NO-BOX FRAME except-frame STREAM-IO.
/*5*/ FOR EACH item:
/*6*/ IF on-hand < alloc THEN DO:
DISPLAY STREAM exceptions item-num item-name on-hand alloc
WITH FRAME exitem DOWN STREAM-IO.
excount = excount + 1.
exception = TRUE.
END.
/*7*/ DISPLAY STREAM rpt item-num item-name
WITH NO-LABELS NO-BOX STREAM-IO.
/*8*/ IF exception
THEN DISPLAY STREAM rpt "See Exception Report".
exception = FALSE.
END.
/*9*/ DISPLAY STREAM exceptions SKIP(1) excount
WITH FRAME exc SIDE-LABELS STREAM-IO.
/*10*/DISPLAY STREAM rpt WITH FRAME exc STREAM-IO.
/*11*/OUTPUT STREAM rpt CLOSE.
OUTPUT STREAM exceptions CLOSE.
721
The numbers to the left of the procedure correspond to the following step-by-step descriptions:
1. The SET statement prompts you for the filenames you want to use for the Item Inventory
Report and for the Item Exception Report. It stores your answers in the fnr and fne
variables, respectively.
2. The OUTPUT STREAM statements open two output streams, named rpt and exceptions.
These streams were defined at the start of the procedure with the DEFINE STREAM
statement.
The rpt and exceptions streams are directed to the files whose names you supplied:
VALUE(fnr) and VALUE(fne). This means that output can now be sent to either or both
of those files.
3. The DISPLAY statement displays the text Item Inventory Report. But instead of
displaying that text on the terminal, it displays it to the rpt stream. The file you named for
the Item Inventory Report contains the text Item Inventory Report.
4. This DISPLAY statement also displays text but it uses the exceptions stream. The file you
named for the Item Exception Report contains the text Item Exception Report.
5. The FOR EACH block reads a single item record on each iteration of the block.
6. If the allocated amount of an item is larger than the on-hand amount of that item:
The DISPLAY statement displays item data to the exceptions stream. After this
DISPLAY statement finishes, the file you named for the Item Exception Report
contains item data for a single item.
The excount counter variable, defined at the start of the procedure, is incremented
by 1. The value of this variable is displayed at the end of the procedure so that you
know the total number of exception items in inventory.
The exception logical variable, defined at the start of the procedure, is set to TRUE.
7. The DISPLAY statement displays some item data to the rpt stream. After this statement
finishes, the file you named for the Item Inventory Report contains item data for a single
item.
8. If the item is an exception, determined by the value in the exception logical variable, the
DISPLAY statement displays the string See Exception Report to the rpt stream. That
way you know, when looking at the Item Inventory Report, which items are exceptions.
9. The DISPLAY statement displays the value of the excount variable to the exceptions
stream. The value of this variable is the total number of exception items.
722
10. This DISPLAY statement displays the value of the excount variable to the rpt stream.
Although the DISPLAY statement does not explicitly say what is being displayed, it does
name the same frame, exc, as is used to display excount in the previous DISPLAY
statement. That means that the exc frame already contains the excount value. Thus, all this
second DISPLAY statement has to do is name the same frame.
11. The OUTPUT STREAM CLOSE statements close the rpt and exception streams,
redirecting all further output to the default output destination.
7.5 Sharing Streams Among Procedures
In some cases, you might want two or more procedures to share the same input or output
streams. The following procedures, p-sstrm.p and p-dispho.p, share the same output stream,
phonelist. Notice that phonelist is defined as a shared stream in both procedures:
The p-sstrm.p procedure defines a NEW SHARED STREAM called phonelist. The procedure
sends the output from the phonelist stream to a file called phonefile. The procedure also calls
the p-dispho.p procedure:
p-sstrm.p
DEFINE NEW SHARED BUFFER xrep FOR salesrep.
DEFINE NEW SHARED STREAM phonelist.
OUTPUT STREAM phonelist TO phonefile.
PAUSE 2 BEFORE-HIDE.
FOR EACH xrep:
DISPLAY xrep WITH FRAME repname
TITLE "Creating report for " 2 COLUMNS CENTERED ROW 10.
DISPLAY STREAM phonelist xrep WITH 2 COLUMNS STREAM-IO.
RUN p-dispho.p.
END.
p-dispho.p
DEFINE SHARED BUFFER xrep FOR salesrep.
DEFINE SHARED STREAM phonelist.
FOR EACH customer OF xrep BY state:
DISPLAY STREAM phonelist cust-num name city state phone
WITH NO-LABELS STREAM-IO.
END.
723
The p-dispho.p procedure defines the SHARED STREAM phonelist, and displays the
information from that stream on the screen. (It is more efficient to place the FOR EACH and
DISPLAY statements in the p-sstrm.p procedure. They are in a separate procedure here to
illustrate shared streams.)
NOTE: You cannot define or access shared streams in a persistent procedure. If you do,
Progress returns a run-time error when you create the persistent procedure. For more
information, see the sections on persistent procedures in Chapter 3, Block
Properties.
Sharing streams is much like sharing variables:
You use a regular DEFINE STREAM statement to define a stream that is available only
to the current procedure.
To define a shared stream, you define the stream as NEW SHARED in the procedure that
creates the stream, and as SHARED in all other procedures that use that stream. If you do
not explicitly close the stream, Progress closes it automatically at the end of the procedure
in which you defined it.
You define the stream as NEW GLOBAL when you want that stream to remain available
even after the procedure that contains the DEFINE NEW GLOBAL SHARED STREAM
statement ends.
724
7.6 Summary of Opening and Closing Streams
Table 72 describes how you establish, open, use, and close default streams and streams you
name.
Table 72: Using Streams
Action Unnamed Streams Named Streams
Establish the
stream
By default, each procedure gets
one unnamed input stream and
one unnamed output stream.
You define the stream explicitly
by using one of these statements:
DEFINE STREAM, DEFINE
NEW SHARED STREAM,
DEFINE SHARED STREAM,
DEFINE NEW GLOBAL
SHARED STREAM.
Open the stream Automatically opened, using the
output destination to which the
calling procedures unnamed
stream is directed and the input
source from which the calling
procedures input is read. You
can also explicitly name a
destination or source by using
OUTPUT TO or INPUT FROM.
You open the stream explicitly
by using OUTPUT STREAM
name TO or INPUT STREAM
name FROM.
Use the stream All data-handling statements use
the stream by default.
Name the opened stream in the
data-handling statement that will
use the stream.
Close the stream Automatically closed at the end
of the procedure that opened it.
You can also explicitly close it
with the OUTPUT CLOSE or
INPUT CLOSE statement.
Local streams are automatically
closed at the end of the
procedure. Shared streams are
automatically closed when the
procedure that defined the stream
as NEW ends. Global streams are
closed at the end of the Progress
session.
You can also explicitly close
named streams by using the
INPUT CLOSE or OUTPUT
CLOSE statement or by opening
the stream to a new destination or
from a new source.
725
Initially, a default input stream has as its source the most recent source specified in the calling
procedure or, if there is no calling procedure, the terminal. The default output stream has as its
destination the most recent destination specified in the calling procedure or, if there is no calling
procedure, the terminal. If you are running a procedure in batch or background, you must
explicitly indicate a source and/or destination.
When an unnamed stream is closed (either automatically or explicitly), it is automatically
redirected to its previous destination (the destination of the procedure it is in). If the stream is
not in a procedure, the stream is redirected to or from the terminal.
When you close a named stream, you can no longer use that stream until it is reopened. When
you close an input stream associated with a file and then reopen that stream to the same file,
input starts from the beginning of the file.
7.7 Processes as Input and Output Streams (NT and UNIX only)
You can import data into Progress from a process or pipe data from Progress to another process
using one of the following statements:
INPUT THROUGH statement to import data into Progress from another process
OUTPUT THROUGH statement to pipe data from Progress to another process
INPUTOUTPUT THROUGH statement to pipe the output of a process into a Progress
procedure and to pipe data from Progress back to that same process.
This allows two-way communication to a program written in C or any other language. You
might use this capability to do specialized calculations on data stored in a Progress
database or entered during a Progress session.
For more information on these statements, see the Progress Language Reference.
7.8 I/O Redirection for Batch Jobs
You can use the < and > symbols on the Progress command line to redirect I/O for batch jobs.
For details, see the entry for the Batch (b) startup parameter in the Progress Startup Command
and Parameter Reference.
726
7.9 Reading the Contents of a Directory
Sometimes, rather than reading the contents of a file, you want to read a list of the files in a
directory. You can use the OSDIR option of the INPUT FROM statement for this purpose.
Each line read from OSDIR contains three values:
The simple (base) name of the file.
The full pathname of the file.
A string value containing one or more attribute characters. These characters indicate the
type of the file and its status. Every file has one of the following attribute characters:
F Regular file or FIFO pipe
D Directory
S Special device
M Member of a Progress r-code library
X Unknown file type
In addition, the attribute string for each file might contain one or more of the following
attribute characters:
H Hidden file
L Symbolic link
P Pipe file
The tokens are returned in the standard Progress format that can be read by the IMPORT or SET
statements.
727
The following example uses the OSGETENV function to find the path of the DLC directory.
It then uses the OSDIR option of INPUT FROM to read the contents of the directory:
In p-osdir.p, only the base name of the file and attribute string are read from OSDIR. The
caret (^) is used in the SET statement to skip over the pathname of the file.
For more information on the OSDIR option, see the INPUT FROM Statement reference entry
in the Progress Language Reference.
You can find additional information on a single file by using the FILEINFO system handle. To
use the FILEINFO handle, first assign the pathname of an operating system file to the
FILEINFO:FILENAME attribute. You can then read other FILEINFO attributes. For
example, the p-osfile.p procedure prompts for the pathname of a file and then uses the
FILEINFO handle to get information on that file:
p-osdir.p
DEFINE VARIABLE search-dir AS CHARACTER.
DEFINE VARIABLE file-name AS CHARACTER FORMAT "x(16)" LABEL "File".
DEFINE VARIABLE attr-list AS CHARACTER FORMAT "x(4)" LABEL "Attributes".
search-dir = OS-GETENV("DLC").
INPUT FROM OS-DIR(search-dir).
REPEAT:
SET file-name ^ attr-list
WITH WIDTH 70 USE-TEXT TITLE "Contents of " + search-dir.
END.
INPUT CLOSE.
p-osfile.p
DEFINE VARIABLE os-file AS CHARACTER FORMAT "x(60)" LABEL "File".
REPEAT:
SET os-file WITH FRAME osfile-info.
FILE-INFO:FILE-NAME = os-file.
DISPLAY FILE-INFO:FULL-PATHNAME FORMAT "x(60)" LABEL "Full Path"
FILE-INFO:PATHNAME FORMAT "x(60)" LABEL "Path"
FILE-INFO:FILE-TYPE LABEL "Type"
WITH FRAME osfile-info SIDE-LABELS TITLE "OS File Info".
END.
728
For more information, see the FILEINFO System Handle reference entry in the Progress
Language Reference.
7.10 Performing Code-page Conversions
Computer systems store text data using character codes, typically 7 or 8bit numeric codes that
map to specific visual character representations. The series of character codes that make up the
character set that a system uses is referred to as a code page.
Progress provides a character set management facility to automatically convert data between the
code pages of different data sources and destinations (targets). In general, the supported data
sources and targets for code page conversion include memory, streams, and databases. You can
specify default code page conversions for a session using conversion tables and startup
parameters to specify the code page for each data source and target. For more information on
this character set facility, see the Progress Internationalization Guide.
The Progress 4GL also allows you to perform I/O that explicitly converts data from one code
page to another in order to facilitate I/O between data sources and destinations intended for
different computer systems or components. You can specify the name of the code page for a data
source and target as parameters to several statements and functions.
To convert between source and target characters or strings in memory, you can specify code
page parameters in these functions:
ASC
CHR
CODEPAGECONVERT
To convert data input and output, you can specify code page parameters in these statements:
INPUT FROM (input source to memory target)
OUTPUT TO (memory source to output target)
To convert piped input and output, you can specify code page parameters in these statements:
INPUT THROUGH (program source to memory target)
OUTPUT THROUGH (memory source to program target)
INPUTOUTPUT THROUGH (program source to program target)
729
These statements and functions take available code page name parameters as character
expressions (for example, ibm850). The code page names you specify must be defined in your
Progress conversion map file (convmap.cp, by default). Also, the source and target conversion
tables must be defined in the conversion map file for each code page to support the specified
conversions. For more information on building a conversion map file, see the Progress
Internationalization Guide.
For example, this procedure writes to two output streams using two different code pages:
For this example, assume that the internal code page is iso88591. If a customer name from
the sports database is greater than or equal to a prompted name (xname), then the procedure
writes the corresponding customer record to the file, german.txt, using the german7bit
code page. Otherwise, it writes the corresponding customer record to the file, swedish.txt,
using the swedish7bit code page. These conversions are handled by the conversion tables
provided with Progress.
For more information on specifying code page parameters, see the reference entry for each
statement or function that supports code page conversion in the Progress Language Reference.
p-codpag.p
DEFINE VARIABLE xname LIKE customer.name INITIAL ?.
DO WHILE xname <> "":
ASSIGN xname = "".
DISPLAY xname LABEL "Starting Name to German List"
WITH FRAME A SIDE-LABELS.
SET xname WITH FRAME A.
IF xname <> "" THEN DO:
OUTPUT TO german.txt
CONVERT SOURCE "iso8859-1" TARGET "german-7-bit".
FOR EACH customer WHERE customer.name >= xname BY name:
DISPLAY customer WITH STREAM-IO.
END.
OUTPUT CLOSE.
OUTPUT TO swedish.txt
CONVERT SOURCE "iso8859-1" TARGET "swedish-7-bit".
FOR EACH customer WHERE customer.name < xname BY name:
DISPLAY customer WITH STREAM-IO.
END.
OUTPUT CLOSE.
END.
END.
730
7.11 Converting Non-standard Input Files
The input files used in the previous examples contained data that was in a very specific format:
When using a data file as an input source, Progress, by default, expects that file to conform to
the following standards:
One or more spaces must separate each field value.
Character fields that contain embedded blanks must be surrounded by quotes ( ).
Any quotes in the data must be represented by two quotes ( ).
What if you need to deal with an input file that does not conform to these standards? For
example, you might have a file in which each field is on a separate line; or where fields are
separated by commas instead of spaces; or where the fields have no special delimiters, but
appear at specific column locations.
Progress provides two strategies for dealing with such files:
Use the QUOTER utility to convert the file to the standard Progress format. You can then
use the normal Progress frame-based input statements, such as SET, to read data from the
file.
Use the IMPORT statement to read from the file.
Which method you choose depends on your particular circumstances. For example:
The frame-based statements, such as SET, validate the format of the incoming data;
IMPORT does not. In some cases you want this validation and in others you might not
want it.
If you expect to read the same file repeatedly, preprocessing that file once with QUOTER
might be worthwhile. However, if your code reads from different files, or the content of
the file is subject to change, you might want to avoid repeated preprocessing by using
IMPORT instead.
The following section explains how to use QUOTER. For more information on using the
IMPORT statement, see the Importing and Exporting Data section.
p-datf1.d
90 "Wind Chill Hockey" BBB
91 "Low Key Checkers" DKP
92 "Bings Ping Pong" SLS
731
7.11.1 Using QUOTER to Format Data
The QUOTER utility formats character data in a file to the standard format so it can be used by
a Progress procedure. By default, QUOTER does the following:
Takes the name of a file as an argument
Reads input from that file
Places quotes () at the beginning and end of each line in the file.
Replaces any already existing quotes () in the data with two quotes ( ).
You can use the QUOTER utility directly from the operating system using the operating system
statement, as appropriate, to reformat data from a file that is not in the standard Progress input
format:
PARAMETERS
input-file-name
Specifies the file you are using.
> output-file-name
Specifies the file where you want to send the output.
-d character
Identifies a field delimiter. You can specify any punctuation character.
-c startcol-stopcol
Specifies the ranges of column numbers to be read as fields. Do not use any spaces in the
range list.
Operating
System
Syntax
UNIX
Windows
quoter input-file-name
[ > output-file-name
| -d character
| -c startcol-stopcol
] ...
732
Suppose your data file looked like the following example:
You use QUOTER to put this file into standard format. Use commands shown in Table 73 to
run QUOTER from the Procedure Editor:
p-datf12.d
90
Wind Chill Hockey
BBB
91
Low Key Checkers
DKP
92
Bings Ping Pong
SLS
Table 73: Quoter Examples
Operating
System Using QuoterExamples
Windows
DOS quoter p-dat12.d >p-dat12.q
UNIX
UNIX quoter p-datf12.d >p-datf12.q
733
In Figure 78, p-datfl2.d is the name of the data file you supply to QUOTER while
p-datfl2.q is the name of the file in which you want to store QUOTERs output.
Figure 78: How QUOTER Prepares a File
The p-datfl2.q file contains the QUOTER output:
Now this file is in the appropriate format to be used as input to a Progress procedure.
p-datf12.q
"90"
"Wind Chill Hockey"
"BBB"
"91"
"Low Key Checkers"
"DKP"
"92"
"Bings Ping Pong"
"SLS"
Quoter Prepares the File
90"
Wind Chill"
"Hockey
BBB
90
Wind Chill
Hockey
BBB
p-datfl2.d
p-datfl2.q
734
What if each of the field values in your data file is not on a separate line (unlike p-datfl2.d)
and without quotes (unlike p-datf1.d)? That is, your data file looks like p-datfl3.d:
Suppose you wanted to use this file as the input source to create customer records for customers
90, 91, and 92. You need to make each line of the file into a character string and then assign a
substring of this value to each field. The procedure p-chgin3.p does that.
The numbers to the left of the procedure correspond to the following step-by-step descriptions:
1. The QUOTER utility takes the data from the p-datfl3.d file and produces data that looks
like the following example:
2. The INPUT FROM statement redirects the input stream to get input from the p-datfl3.q
file.
3. The CREATE statement creates an empty customer record.
p-datf13.d
90 Wind Chill Hockey BBB
91 Low Key Checkers DKP
92 Bings Ping Pong SLS
p-chgin3.p
DEFINE VARIABLE data AS CHARACTER FORMAT "x(78)".
/*1*/ OS-COMMAND SILENT quoter p-datfl3.d > p-datfl3.q.
/*2*/ INPUT FROM p-datfl3.q NO-ECHO.
REPEAT:
/*3*/ CREATE customer.
/*4*/ SET data WITH NO-BOX NO-LABELS NO-ATTR-SPACE WIDTH 80.
cust-num = INTEGER(SUBSTRING(data,1,2)).
name = SUBSTRING(data,4,17).
/*5*/ sales-rep = SUBSTRING(data,22,3).
END.
/*6*/ INPUT CLOSE.
p-datf13.q
"90 Wind Chill Hockey BBB"
"91 Low Key Checkers DKP"
"92 Bings Ping Pong SLS"
735
4. The SET statement uses the first quoted line in the p-datfl3.q file as input and puts that
line in the data variable. Once that line of data is in the line variable, the next statements
break it up into pieces that get stored in individual customer fields.
5. The SUBSTRING functions take the appropriate pieces of the data in the line variable and
store the data in the custnum, name, and salesrep fields, as shown in Figure 79.
Figure 79: Extracting QUOTER Input with SUBSTRING
Because Progress assumes that all the data in the p-datfl3.q file is character data, you
must use the INTEGER function to convert the custnum data to an integer value.
6. The INPUT CLOSE statement closes the input stream coming from the p-datfl3.q file
and redirects the input stream to the terminal.
NOTE: With this method, all trailing blanks are stored in the database. To avoid this
problem, use the c or d option of QUOTER.
You can use QUOTER to prepare files formatted in other ways as well. For example, suppose
the field values in your data file are separated by a specific character, such as a comma (,), as in
p-datfl4.d:
p-datf14.d
90,Wind Chill Hockey,BBB
91,Low Key Checkers,DKP
92,Bings Ping Pong,SLS
Column
Number of
Characters
1 4 22
2 17 3
cust-num
name
sales-rep
IS
IS
IS
INTEGER (SUBSTRING(line,1,2))
(SUBSTRING(line,4,17))
(SUBSTRING(line,22,3))
736
You can use a special option, d, (on UNIX) to tell QUOTER what character separates fields.
The procedure p-chgin4.p reads the comma-separated data from p-datfl4.d:
Here, the d option or the DELIMITER qualifier tells QUOTER that a comma (,) is the
delimiter between each field in the data file. The output of QUOTER is shown in p-datfl4.q:
This data file is in the standard blank-delimited Progress format. If your data file does not use a
special field delimiter that you can specify with the d QUOTER option or the /DELIMITER
qualifier, but does have each data item in a fixed column position, you can use another special
option, c, on Windows and UNIX.
You use the c option or /COLUMNS to identify the columns in which fields begin and end.
For example, suppose your file looks like p-datfl5.d:
p-chgin4.p
OS-COMMAND SILENT quoter -d , p-datfl4.d >p-datfl4.q.
INPUT FROM p-datfl4.q NO-ECHO.
REPEAT:
CREATE customer.
END.
INPUT CLOSE.
p-datf14.q
"90" "Wind Chill Hockey" "BBB"
"91" "Low Key Checkers" "DKP"
"92" "Bings Ping Pong" "SLS"
p-datf15.d
737
The procedure p-chgin5.p uses this data file to create customer records:
Because you used the c option, this procedure produces a data file without trailing blanks.
You can also use QUOTER interactively to reformat your data. You can access QUOTER
interactively through the Administration Tool or, in character interfaces, the Data Dictionary.
From the main menu, choose Utilities.
7.11.2 Importing and Exporting Data
Sometimes you send data to a file knowing that it will be used later by a Progress procedure. If
so, then you also know that the data file must be in standard format with character fields
surrounded by quotes. Therefore, instead of just redirecting the output to the file and using the
DISPLAY statement to send output to that file, you might use the EXPORT statement.
NOTE: Do not confuse the EXPORT statement with the EXPORT method of the SESSION
handle. The EXPORT statement converts data from one format to another while
redirecting it. The EXPORT method of the SESSION handle adds procedure names
to the export list (list of procedures a requesting procedure can access) of a Progress
AppServer. For more information on Progress AppServers, see Building Distributed
Applications Using the Progress AppServer.
p-chgin5.p
OS-COMMAND SILENT quoter -c 1-2,4-20,22-24 p-datfl5.d >p-datfl5.q.
INPUT FROM p-datfl5.q NO-ECHO.
REPEAT:
CREATE customer.
END.
INPUT CLOSE.
738
Using the EXPORT Statement
The EXPORT statement sends data to a specified output destination, formatting it in a way that
can be easily used by another Progress procedure. For example, p-export.p writes customer
information to a file:
The output from p-export.p is written to p-datfl6.d:
Now this file is ready to be used as an input source by another Progress procedure. There is no
need to process it through QUOTER.
By default, the EXPORT statement uses the space character as a delimiter between fields. You
can use the DELIMITER option of the EXPORT statement to specify a different delimiter.
For example, p-exprt2.p writes to a file in which field values are separated by commas:
p-export.p
OUTPUT TO p-datfl6.d.
FOR EACH customer:
EXPORT cust-num name sales-rep;.
END.
OUTPUT CLOSE.
p-datf16.d
1 "Lift Line Skiing" "HXM"
2 "Urpon Frisbee" "DKP"
3 "Hoops Croquet Comp" "HXM"
4 "Go Fishing Ltd" "SLS"
5 "Match Point Tennis" "JAL"
.
.
.
p-exprt2.p
FOR EACH customer:
EXPORT DELIMITER "," cust-num name sales-rep.
END.
OUTPUT CLOSE.
739
The output from p-exprt2.p is written to p-datfl7.d:
You can read this file by using the DELIMITER option of the IMPORT statement. More likely,
you would prepare a file like this to be read by another application.
For more information on the EXPORT statement, see the Progress Language Reference.
7.11.3 Using the PUT Statement
If you need to prepare a data file in a fixed format, perhaps for use by another system, you can
use the PUT statement. The following procedure uses PUT statement to unite to a file:
The output from p-putdat.p is written to p-datfl8.d:
p-datf17.d
1,"Lift Line Skiing","HXM"
2,"Urpon Frisbee","DKP"
3,"Hoops Croquet Comp","HXM"
4,"Go Fishing Ltd","SLS"
5,"Match Point Tennis","JAL"
.
.
.
p-putdat.p
FOR EACH customer:
PUT cust-num AT 1 name AT 10 sales-rep AT 40 SKIP.
END.
OUTPUT CLOSE.
p-datf18.d
1 Lift Line Skiing HXM
2 Urpon Frisbee DKP
3 Hoops Croquet Comp HXM
4 Go Fishing Ltd SLS
5 Match Point Tennis JAL
.
.
.
740
The PUT statement formats the data into the columns specified with the AT options. Only the
data is output: there are no labels and no box. The SKIP option indicates that you want each
customers data to begin on a new line.
For more information on the PUT statement, see the Progress Language Reference.
7.11.4 Using the IMPORT Statement
The IMPORT statement is the counterpart of the EXPORT statement. It reads an input file into
Progress procedures, one line at a time.
Using IMPORT to Read Standard Data
The following example shows IMPORT reading the file exported by the procedure p-export.p:
This relies on the input being space separated. You can also use the DELIMITER option of the
IMPORT statement to read a file with a different separator.
For example, p-imprt2.p reads the file produced by p-exprt2.p in the previous section:
This example reads one line at a time from p-datfl7.d into the character-string variable data.
It then breaks the line into discrete values and assigns them to the fields of a customer record.
p-import.p
INPUT FROM p-datfl6.d.
REPEAT:
CREATE customer.
IMPORT cust-num name sales-rep.
END.
INPUT CLOSE.
p-imprt2.p
REPEAT:
CREATE customer.
IMPORT DELIMITER "," cust-num name sales-rep.
END.
OUTPUT CLOSE.
741
Using IMPORT to Read Non-standard Data
Although the IMPORT statement is used primarily to read data in the standard format written
by the EXPORT statement. However, you can use the UNFORMATTED and DELIMITER
options of IMPORT to read data in non-standard formats.
When you use the UNFORMATTED option, the IMPORT statement reads one line from the
input file. For example, suppose your input file is formatted as follows:
The lines containing custnum and salesrep values can be read with normal IMPORT
statements. However, if you try to read the customer name values with a normal IMPORT
statement, only the first word of each name is readthe space character is treated as a delimiter.
To prevent this, read the name with the UNFORMATTED option, as in p-impun1.p.
Now, suppose each line of the file contained a custnum, name, and salesrep value, but no
special delimiters are used. Instead, the fields are defined by their position within the line:
p-datf12.d
90
Wind Chill Hockey
BBB
91
Low Key Checkers
DKP
92
Bings Ping Pong
SLS
p-impun1.p
REPEAT:
CREATE customer.
IMPORT customer.cust-num.
IMPORT UNFORMATTED customer.name.
IMPORT customer.sales-rep.
END.
INPUT CLOSE.
p-datf13.d
742
In p-datfl3.d, the first three character positions in each line are reserved for the cust-num
value, the next 17 positions for the name value, and the last three for the sales-rep value. Space
characters may occur between fields, but they may also occur within a field value. To process
this file with the IMPORT statement, use the UNFORMATTED option to read one line at a
time, as shown in p-impun2.p:
After p-impun2.p reads each line, it uses the SUBSTRING function to break the line into field
values. It then assigns these values to the appropriate fields in the customer record.
NOTE: If a line in your input file ends with a tilde (~), Progress interprets that as a
continuation character. This means, that line and the following line are treated as a
single line. Therefore, the IMPORT statement with the UNFORMATTED option
reads both lines into a single variable.
What if fields values are separated by a delimiter other than the space character? For example,
in p-datfl4.d, field values are separated by commas:
p-impun2.p
DEFINE VARIABLE file-line AS CHARACTER.
REPEAT:
CREATE customer.
IMPORT UNFORMATTED file-line.
ASSIGN customer.cust-num = INTEGER(SUBSTRING(file-line, 1, 2))
customer.name = TRIM(SUBSTRING(file-line, 4, 17))
sales-rep = SUBSTRING(file-line, 22, 3).
END.
INPUT CLOSE.
p-datf14.d
90,Wind Chill Hockey,BBB
91,Low Key Checkers,DKP
92,Bings Ping Pong,SLS
743
You could use the UNFORMATTED option of the IMPORT statement to read this file one line
at a time and then use the INDEX function to locate the commas and break the line into field
values. Another solution is to use the DELIMITER option of the IMPORT statement as shown
in p-impun3.p:
In this example, the DELIMITER option specifies that field values are separated by commas
rather than by spaces. Therefore, the IMPORT statement parses each line correctly and assigns
each value to the appropriate field.
NOTE: You can only specify a single character as a delimiter. If the value you give with the
DELIMITER option is longer than one character, then only the first character is used.
For more information on the IMPORT statement, see the Progress Language Reference.
p-impun3.p
REPEAT:
CREATE customer.
IMPORT DELIMITER "," cust-num name sales-rep.
END.
INPUT CLOSE.
744
8
The Preprocessor
This chapter discusses the Progress language preprocessor, a powerful tool that enhances your
programming flexibility. The Progress preprocessor allows you to write applications that are
easy to read, modify, and transport to other operating systems.
The preprocessor is a component of the Progress Compiler. Before the Compiler analyzes your
source code and creates r-code, the preprocessor examines your source code and performs text
substitutions. The preprocessor also conditionally includes blocks of source code to compile.
The preprocessor operates on a compilation unit, which is a group of files compiled together to
produce one completed program. You can think of the preprocessor as a tool that prepares a final
version of your source code just before it is compiled.
You control the preprocessor by placing preprocessor directives throughout your source code.
A preprocessor directive is a statement that begins with an ampersand (&) and is meaningful
only to the preprocessor. These directives are described in this chapter.
82
8.1 &GLOBAL-DEFINE and &SCOPED-DEFINE Directives
The &GLOBAL-DEFINE and &SCOPED-DEFINE directives allow you to define
preprocessor names, which are compile-time constants. Their syntax is as follows:
The preprocessorname is a name that you supply, and definition is a string of characters. If
definition is longer that one line, you can use a tilde (~) to continue onto the next line. You must
place these directives at the beginning of a line, preceded only by blank or tab characters. The
preprocessor trims all leading and trailing spaces from definition. You can abbreviate
&GLOBAL-DEFINE and &SCOPED-DEFINE to &GLOB and &SCOP, respectively.
You can use reserved Progress keywords as preprocessor names. However, unless they are
defined as part of a preprocessor name, reserved Progress keywords cannot be placed in
preprocessor expressions.
8.1.1 Example Using &GLOBAL-DEFINE
After you define a preprocessor name, you can reference it within your source code. Wherever
a reference appears, the preprocessor substitutes the string of characters that you defined:
In this example, MAX-EXPENSE is the preprocessor name. Once it is defined, you can
reference MAX-EXPENSE from anywhere within your compilation unit (including internal
procedures and include files). A reference to a preprocessor name is specified in the form
{&preprocessorname}. (For more information on referencing preprocessor names, see the
Referencing Preprocessor Names section.) Wherever you reference MAX-EXPENSE in your
source code, Progress substitutes the text 5000 at compile time. For example, your source
code might contain a line like this:
SYNTAX
&GLOBAL-DEFINE preprocessor-name definition
SYNTAX
&SCOPED-DEFINE preprocessor-name definition
&GLOBAL-DEFINE MAX-EXPENSE 5000
IF tot-amount <= {&MAX-EXPENSE} THEN DO:
The Preprocessor
83
Before the Compiler analyzes your source code, the preprocessor performs the text substitution.
The line of code that the Progress Compiler analyzes and compiles is as follows:
You can see how the preprocessor makes your source code easier to maintain. A preprocessor
name like MAX-EXPENSE might be referenced many times in your source code. You only
have to change one line of code (the definition of MAX-EXPENSE) to change the value of all
of the references. In addition, you can see how preprocessor references make your code easier
to read: {&MAX-EXPENSE} is more readable and understandable than 5000. Note that the
characters in the name MAX-EXPENSE are all uppercase; this is not required, but it makes your
source code more readable. Preprocessor names are case insensitive.
If you want to use a preprocessor name as a text string within an application, you must put
quotes around it:
8.1.2 Preprocessor Name Scoping
Each preprocessor name that you define has a specific scope. The scope of a name is the area
within its compilation unit where you can access, or reference, the name. You determine the
scope of a preprocessor name by where you define it within the compilation unit and by whether
you define it with the &GLOBAL-DEFINE or &SCOPED-DEFINE directive. A name defined
with the &GLOBAL-DEFINE directive is globally defined; a name defined with the
&SCOPED-DEFINE directive is nonglobally defined.
The scope of a preprocessor name always begins at the directive that defines it; the name is not
accessible before the defining directive.
The scope of a globally defined name extends forward from the point of definition to the end of
the compilation unit. The scope of a nonglobally defined name extends forward from the point
of definition to the end of the file that contains its definition. It does not extend beyond the end
of the file to the rest of the compilation unit. It does, however, extend to any files included
within the defining file.
IF tot-amount <= 5000 THEN DO:
DISPLAY "{&MAX-EXPENSE}".
84
If you define a name in a top-level file of a compilation unit, it makes no difference whether the
name is globally defined or nonglobally defined. In either case, the name is accessible from the
point of definition to the end of the compilation unit. However, if you define a name within an
include file, it does make a difference how the name is defined. Globally defined names are
accessible to the end of the compilation unit; nonglobally defined names are only accessible
within the defining file. See Figure 81.
main.p
include.i
Figure 81: Name Scoping
main.p
Compilation Unit
&GLOB SOURCE-NAME "main.p"
DISPLAY {&SOURCE-NAME}.
&SCOP SOURCE-NAME "include.i"
&SCOP SOURCE-NAME "include.i"
&GLOB SOURCE-NAME "main.p"
{include.i}
include.i
Resolves
To
Resolves
To
DISPLAY "main.p".
DISPLAY "include.i".
DISPLAY "main.p".
Global scope begins
Nonglobal scope begins
Nonglobal scope ends
The Preprocessor
85
In Figure 81, the preprocessor name SOURCE-NAME is defined both globally and
nonglobally. In such a situation, the nonglobally defined name takes precedence over the
globally defined name within its scope. The nonglobally defined names scope begins at the first
line and ends at the last line of the file include.i. Within this scope, all references to
SOURCE-NAME access the defined value include.i.
The innermost name definition always takes precedence within its scope. If you define a name
nonglobally and then redefine the name nonglobally within a nested include file, only the
innermost name definition is accessible within the nested include file.
You can limit the scope of a name with the &UNDEFINE directive. This directive undefines
the name and ends its scope.
8.2 &UNDEFINE Directive
To remove the definition of a preprocessor name, you can undefine the name. This is the syntax
for &UNDEFINE:
The preprocessorname is the name you want to undefine.
When you use the &UNDEFINE directive, Progress warns you if the name you want to
undefine was not previously defined. The &UNDEFINE directive undefines the most recently
defined name within whose scope the &UNDEFINE directive resides. Once you undefine a
name, you can redefine it.
The &UNDEFINE directive also undefines named include file arguments. For more
information, see the Arguments to Include Files section.
SYNTAX
&UNDEFINE preprocessor-name
86
8.3 &IF, &THEN, &ELSEIF, &ELSE, and &ENDIF Directives
You use these directives to set logical conditions when compiling blocks of code. This is the
syntax for these directives:
The expression can contain the following elements: preprocessor name references, the operators
listed in Table 82, the Progress functions listed in Table 83, and the DEFINED( )
preprocessor function. The DEFINED( ) function indicates whether a preprocessor name is
defined. For more information on the DEFINED( ) function, see the DEFINED( ) Preprocessor
Function section.
When the preprocessor evaluates an expression, all arithmetic operations are performed with
32-bit integers. Preprocessor name references used in arithmetic operations must evaluate to
integers.
When encountering an &IF directive, the preprocessor evaluates the expression that
immediately follows. This expression can continue for more than one line; the &THEN
directive indicates the end of the expression. If the expression evaluates to TRUE, then the block
of code between it and the next &ELSEIF, &ELSE, or &ENDIF is compiled. If the expression
evaluates to FALSE, the block of code is not compiled and the preprocessor proceeds to the next
&ELSEIF, &ELSE, or &ENDIF directive. No include files referenced in this uncompiled block
of code are included in the final source. You can nest &IF directives.
SYNTAX
&IF expression &THEN
.
.
.
[ &ELSEIF expression &THEN ] ...
.
.
.
[ &ELSE ]
.
.
.
&ENDIF
.
. = block of source code
.
The Preprocessor
87
Table 81 indicates how preprocessor expressions are evaluated.
The expression that follows the &ELSEIF directive is evaluated only if the &IF expression tests
FALSE. If the &ELSEIF expression tests TRUE, then the block of code between it and the next
&ELSEIF, &ELSE, or &ENDIF directive is compiled. If the &ELSEIF expression tests
FALSE, the preprocessor proceeds to the next &ELSEIF, &ELSE, or &ENDIF directive.
The block of code between the &ELSE and &ENDIF directives is compiled only if the &IF
expression and the &ELSEIF expressions all test FALSE. If there are no &ELSEIF directives,
the block of code is compiled if the &IF expression tests FALSE.
Once any &IF or &ELSEIF expression evaluates to TRUE, no other block of code within the
&IF ... &ENDIF block is compiled.
The &ENDIF directive indicates the end of the conditional tests and the end of the final block
of code to compile.
Table 81: Preprocessor Expressions
Type of Expression TRUE FALSE
LOGICAL TRUE FALSE
CHARACTER Non-empty Empty
INTEGER Non-zero 0
DECIMAL Not supported Not supported
Table 82: Preprocessor Operators (1 of 2)
Operator Description
+ Addition
- Subtraction
* Multiplication
/ Division
= Equality
<> Inequality
88
These operators have the same precedence as the regular Progress 4GL operators.
> Greater than
< Less than
>= Greater than or equal to
<= Less than or equal to
AND Logical and
OR Logical or
NOT Logical not
BEGINS Compares the beginning letters of two expressions
MATCHES Compares two character strings
Table 82: Preprocessor Operators (2 of 2)
Operator Description
The Preprocessor
89
You can use any of these expressions within a preprocessor expression; they are evaluated at
compile time.
Table 83: Functions Allowed in Preprocessor Expressions
ABSOLUTE LC RIGHTTRIM
ASC LENGTH RANDOM
DATE LIBRARY REPLACE
DAY LOG ROUND
DECIMAL LOOKUP SQRT
ENCODE MAXIMUM STRING
ENTRY MEMBER SUBSTITUTE
ETIME MINIMUM SUBSTRING
EXP MODULO TIME
FILL MONTH TODAY
INDEX NUMENTRIES TRIM
INTEGER OPSYS TRUNCATE
KEYWORD PROPATH WEEKDAY
KEYWORDALL PROVERSION YEAR
LEFTTRIM RINDEX
810
8.4 DEFINED( ) Preprocessor Function
The DEFINED( ) preprocessor function takes a preprocessor name or include file parameter as
an argument. The preprocessor name argument is not quoted, does not have an ampersand in
front of it, and is not in the reference form, {&preprocessorname}. For example, if you had
defined the preprocessor name MAXEXPENSE, the argument would appear as follows:
The DEFINED( ) function returns a value of 1 if the argument was a name defined with the
&GLOBALDEFINE directive; a value of 2 if the argument was passed as an include file
parameter; and a value of 3 if the argument was a name defined with the &SCOPEDDEFINE
directive. If the argument was not defined and was not an include file parameter, this function
returns a value of 0. The value returned refers to the definition that is current at the point
of the call.
8.5 The &MESSAGE Directive
The &MESSAGE directive allows you to display a message at compile time. This is the syntax
for &MESSAGE:
The textstring is a string of characters, preprocessor name references, named include file
arguments, or any combination of these that results in a character string to display. The
argument textstring does not have to be quoted.
DEFINED(MAX-EXPENSE)
SYNTAX
&MESSAGE text-string
The Preprocessor
811
8.6 Referencing Preprocessor Names
Use this syntax to reference a preprocessor name:
The preprocessorname is a name defined in a &GLOBALDEFINE or &SCOPEDDEFINE
directive, or is a built-in preprocessor name. (For information on built-in preprocessor names,
see the Using Built-in Preprocessor Names section.) Note that this syntax is identical to the
syntax used for referencing argument names in an include file. For more information on how
the preprocessor handles interactions between preprocessor names and include file argument
names, see the Arguments to Include Files section.
A reference to a preprocessor name can occur anywhere within your Progress source code:
When you reference a preprocessor name in your source code,Progress replaces the reference
with the value that you defined in the &GLOBALDEFINE or &SCOPEDDEFINE directive.
In this example, Progress replaces {&FIELDLIST} with the following code:
8.7 Expanding Preprocessor Names
When Progress encounters a reference to a preprocessor name, Progress replaces the reference
with the value of the preprocessor names definition. This is called expanding the reference:
SYNTAX
{ &preprocess-name }
&GLOBAL-DEFINE FIELD-LIST cust-name cust-num addr city
.
.
.
DISPLAY {&FIELD-LIST}.
cust-name cust-num addr city
&GLOBAL-DEFINE TABLE customer
&GLOBAL-DEFINE FIELD cust-name
&GLOBAL-DEFINE WHERE-CLAUSE WHERE {&FIELD} <> "Als Antiques"
FIND NEXT {&TABLE} {&WHERE-CLAUSE}.
812
The first reference in this example is {&FIELD}. The curly brace ( { ) and ampersand ( & )
direct Progress to expand the reference. By checking the definition of the preprocessor name
FIELD, Progress determines that its value is custname. Progress therefore replaces the
reference with custname. As a result, WHERECLAUSE is defined as follows:
The second reference is {&TABLE}. Progress replaces this reference with customer; customer
is the definition of the preprocessor name TABLE.
The third reference is {&WHERECLAUSE}. Progress replaces WHERECLAUSE with its
definition, which has already been expanded.
After Progress has made all of these evaluations, the preprocessing phase of compilation is
complete. This is the FIND NEXT statement that Progress compiles:
In the previous example, the reference {&FIELD} was evaluated first. Progress also allows you
to defer the evaluation of a reference. By placing a tilde (~) in front of a preprocessor name
reference, you indicate that you do not want to expand the reference when it is first encountered.
(On UNIX, you can also use the backslash character ( \ ) to defer evaluation.):
Progress does not expand the reference {&OTHERFIELDS} in the definition of
FORMLIST, because {&OTHERFIELDS} has a tilde in front of it. In this instance, the curly
brace has no significance to Progress because of the tilde.
This is how Progress defines FORMLIST.
Instead of trying to expand the reference {&OTHERFIELDS}, Progress simply includes it in
the definition of FORMLIST.
WHERE cust-name <> "Als Antiques"
FIND NEXT customer WHERE cust-name <> "Als Antiques".
&GLOBAL-DEFINE FORM-LIST cust-num ~
FORMAT >>>9 ~{&OTHER-FIELDS} WITH FRAME X
&GLOBAL-DEFINE OTHER-FIELDS cust-name SKIP city state
DISPLAY {&FORM-LIST}.
&SCOPED-DEFINE OTHER-FIELDS phone.
DISPLAY {&FORM-LIST}.
cust-num FORMAT >>>9 {&OTHER-FIELDS} WITH FRAME X
The Preprocessor
813
When the preprocessor reaches the first DISPLAY statement, Progress expands the
{&FORMLIST} reference. Since the definition of FORMLIST includes the
{&OTHERFIELDS} reference, Progress recursively expands {&OTHERFIELDS}. As a
result, Progress replaces {&FORMLIST} with this.
The &SCOPEDDEFINE directive changes the value of OTHERFIELDS. As a result, the
second {&FORMLIST} reference expands like this:
When you defer the evaluation of a reference, make sure that the reference will have a value at
the point of expansion. The following example does not do this:
In this example, the mistaken intention was to defer the evaluation of {&field_list} until
{&fields} is expanded. However, since field_list is nonglobally defined, its value does not
extend beyond the end of p-incl.i. As a result, there is no value assigned to field_list at the
point of expansion of {&fields}.
cust-num FORMAT >>>9 cust-name SKIP city state WITH FRAME X
cust-num FORMAT >>>9 phone WITH FRAME X.
p-proc.p
&GLOB file customer
{p-incl.i}
FOR EACH {&file}:
DISPLAY {&fields}.
END.
p-incl.i
&GLOB fields ~{&field_list}
&SCOP field_list name max-credit
814
8.8 Using Built-in Preprocessor Names
Progress automatically provides the following preprocessor names:
BATCHMODE
OPSYS
FILENAME
LINENUMBER
SEQUENCE
WINDOWSYSTEM
You can reference these built-in preprocessor names anywhere within your source code,
including preprocessor expressions. They are read-only; you cannot redefine them with
&GLOBALDEFINE or &SCOPEDDEFINE directives. However, you can pass them as
include file arguments.
8.8.1 Built-in Preprocessor Name References
Table 84 lists the name reference for each built-in preprocessor name, and describes the value
it provides.
Table 84: Built-in Preprocessor Name References (1 of 2)
The Reference . . . Expands to an Unquoted String . . .
{&BATCHMODE} Equal to yes if the Batch (b) startup parameter was used to
start the client session. Otherwise, it expands to no.
{&FILENAME}
That contains the pathname of the file being compiled.
1
If you
want only the name of the file as specified in the {}Include File
Reference, the RUN statement, or the COMPILE statement,
use the argument reference {0}.
{&LINENUMBER} That contains the current line number in the file being
compiled. If you place this reference in an include file, the line
number is calculated from the beginning of the include file.
The Preprocessor
815
{&OPSYS} That contains the name of the operating system on which the
file is being compiled. The OPSYS name can have the same
values as the OPSYS function. The possible values are
"UNIX" and "WIN32".
2
{&SEQUENCE} Representing a unique integer value that is sequentially
generated each time the SEQUENCE preprocessor name is
referenced. When a compilation begins, the value of
{&SEQUENCE} is 0; each time {&SEQUENCE} is
referenced, the value increases by 1. To store the value of a
reference to SEQUENCE, you must define another
preprocessor name as {&SEQUENCE} at the point in your
code you want the value retained.
{&WINDOWSYSTEM} That contains the name of the windowing system in which the
file is being compiled. The possible values include
"MSWIN95","MSWINDOWS", and "TTY".
3
1
When running the source code of a procedure file loaded into the Procedure Editor or the AppBuilder,
{&FILENAME} expands to a temporary filename, not the name of the file under which the source code might
be saved.
2
Progress supports an override option for the &OPSYS preprocessor name that enables applications that need to
return the value of MS-DOS for all Microsoft operating systems to do so. For example, if you do not want the
value WIN32 to be returned when either Windows 95 or Windows NT operating systems are recognized, you
can override this return value by defining the Opsys key in Startup section of the current environment, which can
be in the registry or in an initialization file. If the Opsys key is located, the OPSYS preprocessor name returns
the value associated with the Opsys key on all platforms.
3
Progress supports an override option for the &WINDOWSYSTEM preprocessor name that provides backward
compatibility. This option enables applications that need the WINDOWSYSTEM preprocessor name to return
the value of MSWINDOWS for all Microsoft operating systems to do so. To establish this override value,
define the WindowSystem key in Startup section of the current environment, which can be in the registry or in
an initialization file. If the WindowSystem key is located, the WINDOWSYSTEM preprocessor name returns
the value associated with the WindowSystem key on all platforms.
Table 84: Built-in Preprocessor Name References (2 of 2)
The Reference . . . Expands to an Unquoted String . . .
816
8.8.2 Quoting Built-in Names and Saving {&SEQUENCE}
Values
Note that all built-in name values are returned as unquoted strings. You must quote or not quote
the name reference according to the 4GL or preprocessor context of the reference.
Thus, a first reference to {&SEQUENCE}:
expands to:
A second reference to {&SEQUENCE}:
expands to:
Third through sixth references to {&SEQUENCE}, with a value-saving definition:
expands to:
DEFINE VARIABLE nexti AS INTEGER.
nexti = {&SEQUENCE}.
DEFINE VARIABLE nexti AS INTEGER.
nexti = 0.
DEFINE VARIABLE nextc AS CHARACTER.
nextc = "{&SEQUENCE}".
DEFINE VARIABLE nextc AS CHARACTER.
nextc = "1".
&GLOBAL-DEFINE OCCURENCE {&SEQUENCE} + 1
DEFINE VARIABLE triple AS INTEGER EXTENT 3
INITIAL [{&SEQUENCE}, {&SEQUENCE}, {&SEQUENCE}].
MESSAGE "Definition of triple complete as variable number" {&OCCURENCE}
VIEW-AS ALERT-BOX.
DEFINE VARIABLE triple AS INTEGER EXTENT 3
INITIAL [3, 4, 5].
MESSAGE "Definition of triple complete as variable number" 2 + 1
VIEW-AS ALERT-BOX.
The Preprocessor
817
8.9 Nesting Preprocessor References
During compilation, Progress recursively expands nested references, moving from the
innermost reference to the outermost reference. To see how Progress expands nested references,
look at the following procedure:
Progress expands the nested reference {&{&{&{pinclde.i}}}} by starting with the include file
p-inclde.i. For this example, p-inclde.i is as follows:
Progress replaces {pinclde.i} with the contents of p-inclde.i. After replacing {p-inclde.i}
with X, Progress then has to expand the following nested reference:
Progress expands this reference to the following code:
This expands to the following code:
Finally, this expands to the following code:
This last DISPLAY statement is the one that Progress finally compiles into your r-code.
p-main.p
&GLOBAL-DEFINE X Y
&GLOBAL-DEFINE Y Z
&GLOBAL-DEFINE Z "Hello"
DISPLAY {&{&{&{p-inclde.i}}}}.
p-inclde.i
X
DISPLAY {&{&{&X}}}.
DISPLAY {&{&Y}}.
DISPLAY {&Z}.
DISPLAY "Hello".
818
8.10 Arguments to Include Files
If a named argument to an include file and a preprocessor name are the same, the named include
file argument overrides any previous preprocessor names. However, inside the include file any
preprocessor names override the include file arguments.
You can use the &UNDEFINE directive to undefine a named include file argument. However,
you cannot undefine an include file argument of the form {1}, {2}, etc.
8.11 Sample Application
The following application illustrates the use of preprocessor names. It allows you to update all
or some of the fields in a given database table. By changing a few preprocessor name
definitions, you can compile the application to modify different tables.
The Preprocessor
819
In addition, you can supply different FORM statements to display your data:
p-editrc.p
/* A procedure to illustrate the use of preprocessor names */
/* This procedure includes p-editrc.i, an include file that uses */
/* preprocessor names to allow you to easily access and modify any */
/* file in the demo database. Before you compile this procedure, */
/* you must set the following preprocessor definitions: */
/* */
/* NOTE: This file does NOT set a value to the form_file */
/* preprocessor name. */
/* */
/* PREPROCESSOR DESCRIPTION */
/* NAME */
/* */
/* file_name : The database file to modify. */
/* This name must have a value. */
/* file_fields : The list of fields in the database file to modify. */
/* This name must have a value. */
/* form_file : The name of an external form definition include (.f) */
/* file. This name is optional. */
/* frame_name : The name of the frame to be used in accessing the */
/* database file. */
/* frame_title : The title to be added to the frame upon display. If a */
/* form include file is used, TITLE should not be part of */
/* the form statement. */
/* use-buts : A comma-separated list of actions you may perform */
/* against the database in the browse utility. Available */
/* actions are Next, Prev, Update, Create, and Delete. */
/* banner : An example of deferred evaluation, this name references */
/* the ifile_ver preprocessor definition, which is set */
/* in the include file p-editrc.i. */
&GLOBAL-DEFINE file_name customer
&GLOBAL-DEFINE file_fields customer.cust-num customer.name~
customer.address customer.address2~
customer.city customer.st customer.postal-code~
customer.contact customer.phone
&GLOBAL-DEFINE form_file p-cust.f
&GLOBAL-DEFINE frame_name cust_fr
&GLOBAL-DEFINE frame_title Customer
&GLOBAL-DEFINE Banner File Modification Utility, Version ~{&ifile_ver}
&GLOBAL-DEFINE use-buts Next,Prev,Update,Create,Delete
{p-editrc.i}
820
The p-editrc.p procedure defines form_file to be a reference to p-cust.f. It also includes
p-editrc.i, which references form_file.
p-editrc.i (1 of 6)
/* An include file to illustrate the use of preprocessor names. */
/* PREPROCESSOR DESCRIPTION */
/* NAME */
/* */
/* ifile_ver : The version of this file. The name is used with the */
/* preprocessor name banner defined in the main */
/* procedure through deferred evaluation. */
/* display : Combines the file field list and the frame name to make */
/* a more manageable statement when displaying and updating */
/* database records. */
/* but-list : A list of allowable actions that can be performed */
/* during execution of the browse utility. */
/* but-nums : The number of user-specified actions allowed. */
/* Generated through the use of {&SEQUENCE}. */
/* Displayed during compile time using &MESSAGE. */
DEFINE BUFFER {&file_name} FOR {&file_name}.
DEFINE VARIABLE do_return AS LOGICAL INITIAL FALSE.
/* Do some initial setup work */
&IF "{&frame_name}" = "" &THEN /* Make up a default frame name */
&MESSAGE A frame name was not supplied, using default name
&SCOPED-DEFINE frame_name Default_Frame
&ENDIF
&IF "{&form_file}" <> "" &THEN /* Define a frame for the user */
{{&form_file}} /* This includes the form
definition file if one is given */
&ELSE
&MESSAGE A Form file was not supplied, using default form
FORM {&file_fields}
WITH FRAME {&frame_name} ROW 7 CENTERED.
&ENDIF
&SCOPED-DEFINE ifile_ver 1.1a
&SCOPED-DEFINE display {&file_fields} WITH FRAME {&frame_name}30
The Preprocessor
821
/* Define buttons to use in browse as indicated by developer through */
/* the preprocessor name {&use-buts} */
DEFINE BUTTON next_but LABEL "Next"
TRIGGERS:
ON CHOOSE RUN getrec (INPUT "Next")./* On choose find next record */
END TRIGGERS.
&IF LOOKUP("Next", "{&use-buts}") <> 0 &THEN /* Will enable button
for NEXT */
&SCOPED-DEFINE but-list next_but
&SCOPED-DEFINE but-nums {&SEQUENCE}
&ENDIF
DEFINE BUTTON prev_but LABEL "Prev"
TRIGGERS:
ON CHOOSE RUN getrec (INPUT "Prev"). /* On choose find
prev record */
END TRIGGERS.
&IF LOOKUP("Prev", "{&use-buts}") <> 0 &THEN /* Will enable button
for PREV */
&SCOPED-DEFINE but-list {&but-list} prev_but
&ENDIF
DEFINE BUTTON up_but LABEL "Update" /* On choose update record */
TRIGGERS:
ON CHOOSE UPDATE {&display}.
END TRIGGERS.
&IF LOOKUP("Update", "{&use-buts}") <> 0 &THEN /* Will enable button
for UPDATE */
&SCOPED-DEFINE but-list {&but-list} up_but
&SCOPED-DEFINE but-nums {&SEQUENCE}\
&ENDIF
p-editrc.i (2 of 6)
822
DEFINE BUTTON cr_but LABEL "Create" /* On choose create and update */
TRIGGERS:
ON CHOOSE
DO:
DEFINE BUFFER localbuf FOR {&file_name}.
/* First save current location in the file */
FIND FIRST localbuf WHERE ROWID(localbuf) = ROWID({&file_name}).
/* Make the new record */
CREATE {&file_name}.
UPDATE {&display}.
/* Restore the location in the file */
FIND FIRST {&file_name} WHERE ROWID({&file_name}) = ROWID(localbuf).
END.
ON END-ERROR RETURN NO-APPLY.
/* If end-error, restores current location */
END TRIGGERS.
&IF LOOKUP("Create", "{&use-buts}") <> 0 &THEN
/* Enable button for CREATE */
&SCOPED-DEFINE but-list {&but-list} cr_but
&ENDIF
DEFINE BUTTON del_but LABEL "Delete" /* On choose, delete record */
TRIGGERS:
ON CHOOSE RUN delrec.
END TRIGGERS.
&IF LOOKUP("Delete", "{&use-buts}") <> 0 &THEN
/* Enable button for DELETE */
&SCOPED-DEFINE but-list {&but-list} del_but
&ENDIF
DEFINE BUTTON ret_but LABEL "Return"
TRIGGERS:
ON CHOOSE do_return = TRUE.
END TRIGGERS.
DEFINE BUTTON quit_but LABEL "Quit"
TRIGGERS.
ON CHOOSE QUIT.
END TRIGGERS.
&SCOPED-DEFINE but-list {&but-list} ret_but quit_but
&MESSAGE {&but-nums} Out of 5 user definable buttons are active
p-editrc.i (3 of 6)
The Preprocessor
823
FORM next_but Prev_but up_but cr_but Del_but ret_but quit_but
WITH FRAME but_fr ROW 4 CENTERED
TITLE "Work With {&file_name} Records" .
DISPLAY "{&Banner}" WITH FRAME ban_fr CENTERED .
VIEW FRAME but_fr.
ENABLE {&but-list} WITH FRAME but_fr.
REPEAT: /* Cycle through records, or add one. */
WAIT-FOR CHOOSE OF next_but,Prev_but,up_but,cr_but,Del_but,
ret_but, quit_but IN FRAME but_fr.
IF do_return THEN
RETURN.
DISPLAY {&display}.
END.
p-editrc.i (4 of 6)
824
/**********************************************************************/
/* Procedure to find records in the database file being modified. */
/* It takes one parameter, action, which indicates whether you move */
/* forward or backward in the file. */
/**********************************************************************/
PROCEDURE getrec.
DEFINE INPUT PARAMETER action AS CHARACTER.
IF action = "Next" OR action = "" THEN
DO:
FIND LAST localbuf.
IF ROWID(localbuf) = ROWID({&file_name}) THEN
DO:
BELL.
MESSAGE "You are already at the end of this file.".
RETURN ERROR.
END.
ELSE
FIND NEXT {&file_name} .
END.
ELSE
DO:
FIND FIRST localbuf.
IF ROWID(localbuf) = ROWID({&file_name}) THEN
DO:
BELL.
MESSAGE "You are already at the start of this file.".
RETURN ERROR.
END.
ELSE
DO:
FIND PREV {&file_name} .
END.
END.
END PROCEDURE. /* getrec */
p-editrc.i (5 of 6)
The Preprocessor
825
/************************************************************************/
/* Procedure to delete a record from the file. Cannot delete the last */
/* record from the file if it is the only record in the file. When the */
/* record is deleted, the next record is found. If this is not available*/
/* the previous record is found. */
/************************************************************************/
PROCEDURE delrec.
/* Before delete of record, find another record to display after */
FIND localbuf WHERE ROWID(localbuf) = ROWID({&file_name}).
/* find the next record */
FIND NEXT {&file_name} NO-ERROR.
IF NOT AVAILABLE {&file_name} THEN
DO:
/* reset location in file */
FIND {&file_name} WHERE ROWID({&file_name}) = ROWID(localbuf).
/* find previous record */
FIND PREV {&file_name} NO-ERROR.
END.
IF NOT AVAILABLE {&file_name} THEN
DO:
BELL.
MESSAGE "You may not delete the last record in the file.".
RETURN ERROR.
END.
ELSE
DELETE localbuf.
END PROCEDURE. /* delrec */
p-editrc.i (6 of 6)
826
p-cust.f
/* Form definition for updating the customer file. */
/* Please note that there is no TITLE in the frame phrase. */
FORM
customer.cust-num AT 5
customer.name AT 5
customer.address AT 5
customer.address2 AT 5
customer.city AT 5 customer.st AT 25 customer.postal-code AT 37
SKIP (1)
customer.contact AT 5
customer.phone AT 5
WITH FRAME cust_fr SIDE-LABELS ROW 9 CENTERED.
9
Database Access
This chapter describes how to access records in a Progress database. It includes information on
the following topics:
Connecting and disconnecting databases
Logical database names and aliases
Data-handling statements
Adding and deleting records
Fetching records and field lists
Joining tables
Word indexes
Sequences and how to access them
Database trigger considerations
Using the RAW data type
Multi-database programming techniques
Creating and using a schema cache file
Using query, buffer, and buffer-field objects
92
9.1 Database Connections
A Progress application can access one or more Progress or non-Progress databases
simultaneously. The databases can be located on different operating systems using different
networking protocols. To access non-Progress databases, you must use the appropriate
DataServer, such as ORACLE, or C-ISAM. You must connect to a database before you can
access it. There are four ways to connect to a database:
As an argument when starting Progress
With the CONNECT statement (in the Progress Procedure Editor or in a Progress
procedure)
With the Progress Data Dictionary
Using the auto-connect feature
Note that a multi-user application can simultaneously connect to a database for only as many
times as specified in the Number of Users (n) startup parameter. For information on exceeding
this user count, see the Connection Failures and Disruptions section. For more information on
database connection management, see the Progress Startup Command and Parameter
Reference, the Progress Installation and Configuration Guide Version 9 for Windows or
Progress Installation and Configuration Guide Version 9 for UNIX and the Progress Client
Deployment Guide.
9.1.1 Connection Parameters
All of the database connection techniques let you use connection parameters. For more
information on these parameters, see the Progress Startup Command and Parameter Reference.
For multiple database programming, the most important connection parameter is the Physical
Database Name (db) startup parameter, which allows you to specify multiple databases.
The Number of Databases (h) startup parameter lets you set the number of connected databases
allowed during a Progress session, up to a maximum of 240 (the default is 5).
You can group connection parameters in a text file called a parameter file. The Parameter File
(pf) connection parameter invokes the parameter file when you connect to a database.
Parameter files ordinarily have .pf file extensions. For more information on parameter files, see
the Progress Startup Command and Parameter Reference.
Database Access
93
9.1.2 The CONNECT Statement
The CONNECT statement allows you to connect to a database from a Progress procedure or
directly from the Progress Procedure Editor. The CONNECT statement has the following
syntax:
physical-name
An argument that represents the actual name of the database on a disk. The first
physicalname argument you specify in a CONNECT statement does not require the
Database Name (db) parameter. All subsequent physicalnames must be preceded by the
db parameter.
parameter-file
The name of a parameter file that contains database connection information. See the
Progress Startup Command and Parameter Reference for more information on parameter
files.
parameters
One or more database connection parameters. Each connection parameter applies to the
most recently specified database (db). For the parameters you can specify, see the
information on client connection parameters in the Progress Startup Command and
Parameter Reference.
NO-ERROR
This argument suppresses the error condition, but still displays the error message when an
attempt to CONNECT to a database fails.
SYNTAX
CONNECT { physical-name [ parameters ]
| -db physical-name [ parameters ]
| -pf parameter-file [ parameters ]
}
[
{ -db physical-name [ parameters ]
|-pf parameter-file [ parameters ]
}
] ... [ NO-ERROR ]
94
Although you can connect to several databases within one CONNECT statement, it is a good
idea to connect only one database per CONNECT statement, because a connection failure for
one database causes a termination of the current CONNECT statement. However, databases
already connected when the statement terminates stay connected. In cases like this, it is a good
idea to use the CONNECTED functions to see which databases were connected and which were
not.
Here is an example of using a parameter file with the CONNECT statement:
In this example, the CONNECT statement uses the parm3.pf file to connect to the appldb1
database.
A single procedure cannot connect to and then access a database. The following code fragment
does not run:
By splitting this example into a procedure and a subprocedure, you can connect to the database
in the main procedure, and then access it in the subprocedure:
For more information on the CONNECT statement, see the Progress Language Reference.
CONNECT -pf parm3.pf.
parm3.pf
-db appldb1
/* NOTE: this code does NOT work */
CONNECT sports.
FOR EACH sports.customer:
DISPLAY customer.
END.
topproc.p
CONNECT sports.
RUN p-subproc.p.
subproc.p
FOR EACH sports.customer:
DISPLAY customer.
END.
Database Access
95
9.1.3 Auto-connect
The auto-connect feature uses information stored in one database to connect to a second
database at run time. The database that contains the connect information is the primary
application database; it must be connected before Progress can execute the auto-connect.
Progress executes the auto-connect when a precompiled procedure references data from the
second database. It executes immediately prior to running the precompiled procedure. It does
not work with procedures run from the Editor or otherwise compiled on-the-fly.
If you use a CONNECT statement while you are connected to the primary database, Progress
merges the information in the CONNECT statement with the information in the primary
databases auto-connect list. If there is a conflict, the information in the CONNECT statement
takes precedence. For more information, see the CONNECT Statement reference entry in the
For information on how to set up an auto-connect list in the primary database, see the Progress
9.1.4 Multi-database Connection Considerations
When you develop a multi-database application, keep in mind the following information on
database connections:
Connect all databases accessed by the application at compile time. Once compiled, the
application can run no matter where you store the databases or how you connect to them.
Establish unique logical names for each of the databases you connect. Use these names to
reference the databases within your application. These names are stored in the r-code of
the application at compilation time. For more information on logical database names, see
the Logical Database Names section.
9.1.5 Run-time Connection Considerations
As mentioned in the Database Connections section, there are various ways to connect at run
time. For multi-database applications, you must decide which technique to use.
When connecting in the run-time environment, you must use the same logical database names
that you used during compilation. If you need to use a different logical database name for some
reason, you may add an alias to the database to allow r-code files with other names to run.
96
9.1.6 Connection Failures and Disruptions
Database connections may fail for a number of reasons:
The database server for multi-user database access is not availableperhaps the network
is down or it has not been started or the network parameters are incorrect.
The logical name of the application database already exists for the current session.
The syntax for a connection parameter is wrong.
The connection exceeds the maximum number of users per database (n).
Table 91 lists the default failure behavior for each of the run-time connection techniques
.
Progress displays any connection error messages at the point of failure.
Before running a procedure or subprocedure, Progress checks the procedure for database
references. For each reference, Progress searches through all of the connected databases, trying
to find the corresponding database. If the database is not found, Progress again searches all of
the connected databases for an auto-connect list with an entry for that database. If an entry is
found, Progress connects the database. If no entry is found, Progress does not run the procedure
and raises a stop or break condition in the calling procedure.
Table 91: Connection Failure Behavior
Connection Technique Default Connection Failure Behavior
At Progress startup The Progress session does not run.
CONNECT statement The procedure executes up to the CONNECT
statement where the connection failure occurs. The
connection failure raises the error condition for the
procedure. Progress error processing does not undo
database connections or disconnections. Any
database connected in the procedure before the
failed database connection remains connected. See
Chapter 5, Condition Handling and Messages, for
more information on error handling.
Auto-connect The procedures that contain a reference to the
auto-connect database do not run, and a stop or
break condition results in the calling procedure.
Database Access
97
Server, network, or machine failures can disrupt an application, even after a successful
connection. If a failure occurs while a subprocedure is accessing a database, Progress raises a
stop or break condition in the calling procedure.
The following sections present a number of recommendations to help you manage database
connection failures and disruptions in an application.
Using CONNECT with NOERROR
If you designate a startup procedure with the Startup Procedure (p) parameter, always use the
NOERROR option with the CONNECT statement. If a CONNECT statement fails, the
NOERROR option suppresses the resulting error condition, allowing the procedure to continue
executing. Although the NOERROR option bypasses ordinary error processing, Progress still
displays an error message. For more information on using the NOERROR option, see Chapter
5, Condition Handling and Messages.
After a connection failure, if a subprocedure tries to access the unconnected database, Progress
raises a stop or break condition in the calling procedure. Therefore, before you execute any
subprocedures that access a database, you test whether the database is connected. You can do
this with the CONNECTED function.
Using the CONNECTED Function
The CONNECTED function tests whether a database is connected. This function helps you to
route program control around portions of an application that might be affected by database
connection failures and disruptions. This example tests a database connection with the
CONNECTED function.
If the database is not connected, the above code attempts to connect the database. This example
only runs the procedure if the database is connected. Auto-connect precludes the use of the
CONNECTED function to test for database connections. For more information on the
CONNECTED function, see the Progress Language Reference.
IF NOT CONNECTED(logical-name)
THEN DO:
MESSAGE "CONNECTING logical-name".
CONNECT logical-name ... NO-ERROR.
END.
IF CONNECTED(logical-name)
THEN RUN procedure.
ELSE MESSAGE "DATABASE NOT AVAILABLE".
98
9.1.7 Progress Database Connection Functions
Table 92 lists the Progress functions that allow you to test database connections, get
information on connected databases, and get information on the types of databases that you can
access.
Some of these functions take arguments; for more information on these functions, see the
Table 92: Progress Database Functions
Progress Function Description
CONNECTED Tests whether a given database is connected.
DATASERVERS Returns a character string containing a list of database
types supported by the installed Progress product. For
example, Progress,ORACLE.
DBTYPE Returns the database type of a currently connected
database. For example Progress, ORACLE, etc.
DBRESTRICTIONS Returns a character string that describes the Progress
features that are not supported for a particular database.
For example, if the database is an ORACLE database,
the return string is:
LAST,PREV,RECID,SETUSERID.
DBVERSION Returns a 7 if a connected database is a Version 7
database and an 8 if it is a Version 8 database. For
non-Progress databases, you see the appropriate version
number of your database.
FRAMEDB Returns a character string that contains the logical name
of the database for the field in which the cursor was last
positioned for input.
NUMDBS Returns the number of connected databases.
LDBNAME Returns the logical name of a currently connected
database.
PDBNAME Returns the physical name of a currently connected
database.
SDBNAME Returns the logical name of a schema holder for a
database.
Database Access
99
Use these functions to perform various tasks related to connection, such as determining
connection status. The following procedure displays a status report for all connected databases:
9.1.8 Conserving Connections vs. Minimizing Overhead
As more and more users connect to a database, the number of available connections decreases.
You can conserve the number of connections by connecting temporarily, and then
disconnecting when the application is done accessing the database. This frees up the connection
for another user. If the number of available connections is scarce, an application should release
connections wherever possible.
However, each connect and disconnect generates connection overhead, which is the sum of
operations necessary for an application to connect and disconnect a database. The time used for
connection overhead depends on the nature of the database connections. A connection to a
database over a network generally takes longer than a connection to a local database. While the
application connects to a database, the end user waits.
When there are plenty of available connections, you might want to reduce the number of
connects and disconnects to minimize overhead. The best way to do this is to connect all
application databases only once at application startup. With this technique, all connection
overhead occurs once at application startup and does not occur again throughout the life of the
application.
p-infor.p
DEFINE VARIABLE x AS INTEGER FORMAT "99".
DO x = 1 TO NUM-DBS WITH DOWN:
DISPLAY PDBNAME(x) LABEL "Physical Database"
LDBNAME(x) LABEL "Logical Name"
DBTYPE(x) LABEL "Database Type"
DBRESTRICTIONS(x) LABEL "Restrictions"
SDBNAME(LDBNAME(x)) LABEL "Schema Holder DB".
END.
910
9.2 Disconnecting Databases
By default, Progress disconnects all databases at the end of a session. You can explicitly
disconnect a database with the DISCONNECT statement, which has the following syntax:
The logicaldatabasename represents the logical name of a connected database. It can be an
unquoted string, a quoted string, or a character expression.
A DISCONNECT statement does not execute until all active procedures that reference the
database end or stop.
In these procedures, the mydb database is not disconnected until the end of the p-subproc1.p
procedure.
SYNTAX
DISCONNECT logical-database-name
mainprc1.p
CONNECT -db mydb -1.
RUN p-subproc1.p.
subproc1.p
RUN subproc2.p.
FOR EACH mydb.customer:
UPDATE name address city state postal-code.
END.
subproc2.p
DISCONNECT mydb.
Database Access
911
9.3 Logical Database Names
When you connect to a database, Progress automatically assigns that database a default logical
name for the current Progress session. The default logical name consists of the physical database
name without the .db file extension. For example, if you connect to a database with the physical
name mydb1.db, the default logical database name is mydb1. Progress uses the logical database
name mydb1 to resolve database references, and stores it in the compiled r-code of any
procedures that you compile that reference the mydb1.db database.
The Logical Database Name (ld) connection parameter allows you to specify a logical database
name other than the default.
The example below establishes the logical name firstdb for the physical database mydb1.db
during the current Progress session:
When you develop and compile an application to run on the mydb1.db database, it is the logical
name, not the physical name, that Progress stores in the r-code. You must use the logical name
firstdb in your procedures (.p) to reference the mydb1.db database.
Logical database names allow you to change physical databases without recompiling an
application. To run a compiled application on a new physical database without recompiling, the
new database must have identical structure and time stamp or Cyclic Redundancy Check (CRC)
values for the tables accessed by the application and must be connected with the same logical
name (or alias) used to compile the application:
The example above establishes the logical name firstdb for a new physical database mydb2.db.
NOTE: Progress does not allow you to run the Progress Data Administration tool or character
Data Dictionary against a database connected with the logical name DICTDB.
A database connection fails if the logical database name of the database that you connect to has
the same logical name as an already connected database of the same database type (Progress,
ORACLE, etc.). If you try to do this, Progress assumes that database is already connected and
ignores the request.
For information about the characters allowed in the logical name, see the Progress Startup
pro mydb1 -ld firstdb
pro mydb2 -ld firstdb
912
9.4 Database Aliases
An alias is a synonym for a logical database name. You use an alias as a database reference in
Progress procedures in place of a logical database name.
You establish a logical database name when you connect a Progress session to a physical
database. You create and assign an alias to a logical database name of an already connected
database using the CREATE ALIAS statement. By reassigning an alias to different logical
database names, you can run a compiled procedure on other connected databases that have
identical structure and time stamps or CRC values for the tables referenced by the procedure. A
logical database name can have more than one alias, but each alias refers to only one logical
database name at a time.
The Progress Data Dictionary offers an example of alias usage. The Progress Data Dictionary
is a general-purpose Progress application that works on any database that has DICTDB as an
alias. The first database connected during a Progress session automatically receives the alias
DICTDB. During a Progress session, you can reassign the DICTDB alias to another connected
database with the Select Working Databases option on the Database menu in the Progress Data
Dictionary.
NOTE: Because of the need to reassign of the DICTDB alias, Progress does not allow you to
run the Progress Data Dictionary against a database connected with the logical name
DICTDB.
Use the CREATE ALIAS statement during a Progress session to assign or reassign an alias to
a connected database. You can use this statement from the Progress editor or from an
application procedure. This is the syntax for the CREATE ALIAS statement:
The alias argument can be an unquoted string, a quoted string, or an expression. The
logicalname argument represents the existing logical name of a connected database. It can be
an unquoted string, a quoted string, or an expression. You cannot create an alias that is the same
as the logical database name of a connected database. The named database must be connected
unless you use the NOERROR option.
SYNTAX
CREATE ALIAS alias FOR DATABASE logical-name [ NO-ERROR ]
Database Access
913
When you create an alias, Progress logs the alias assignment in a table that remains in memory
for the current session. If you use the DISCONNECT statement to disconnect a database from
within an application, all existing aliases assigned to the logical database name remain in the
alias table until the end of the Progress session. Later, if you connect to a database with the same
logical database name during the same Progress session, you can use the same aliases to
reference that logical database name. If you create an alias that already exists in the session alias
table, Progress replaces the existing alias with the new alias. This allows you to reassign existing
aliases to new logical database names.
The DELETE ALIAS statement allows you to delete an alias from the alias table of the current
Progress session:
The alias argument represents an alias that exists in the current alias session table.
9.4.1 Creating Aliases in Applications
You cannot assign and reference an alias in the same procedure. You must assign an alias to a
logical database name prior to compiling and running procedures that use that alias. For
example, alias1.p below fails to compile when it reaches the FOR EACH statement, because
you cannot assign and reference the alias myalias in a single procedure:
SYNTAX
DELETE ALIAS alias
alias1.p
/* Note that this procedure does not work */
CREATE ALIAS myalias FOR DATABASE sports.
FOR EACH myalias.customer:
DISPLAY customer.
END.
914
To solve this problem, split alias1.p into two procedures, as in the following examples:
9.4.2 Compiling Procedures with Aliases
As a general rule, you should not compile procedures while using aliases. This potentially leads
to confusion about what database name ends up in the r-code. For example, the Progress
dictionary programs which contain DICTDB as a qualifier must be compiled in a session where
the database concerned has the logical name DICTDB. That way, when the dictionary r-code is
run, it can run for any database name as long as the database uses the DICTDB alias. In
summary, logical names are useful for compiling, aliases are useful at run time.
However, you can still compile procedures using aliases. Suppose you have three databases
called eastdb, centraldb, and westdb, all of which contain customer tables with identical
structure and time stamps or CRC values. Your application requires a general report procedure
that can run against any of these customer tables. To begin developing your general report
procedure, start Progress and connect to the eastdb, centraldb, or westdb database using the
logical name myalias. Develop and compile the customer report procedure using myalias to
prefix table and field references as shown in the previous procedure dispcust.p. All
unqualified table and field references in the report procedure dispcust.p resolve to the myalias
logical name at compilation time. When you finish compiling your procedure, disconnect from
the database represented by the myalias logical database name.
You must assign an alias to the logical database name of a connected database prior to running
any procedure that uses that alias as a database reference. Therefore, you need to develop a
procedure that uses the CREATE ALIAS statement to assign the myalias alias to a logical
database name and run the report procedure (dispcust.p) as a subprocedure. See the alias2.p
procedure above.
alias2.p
CREATE ALIAS myalias FOR DATABASE sports.
RUN dispcust.p.
dispcust.p
FOR EACH myalias.customer: /* myalias.customer */
DISPLAY customer. /* myalias.customer */
END.
Database Access
915
Although it is not recommended because of the possible confusion it can cause, you may need
to compile a procedure with an alias. To do this, you must know how Progress places database
references in the r-code of the procedure at compilation time. Remember, you must assign the
alias to a logical database name prior to compiling the procedure. In general, use only the alias
as a database prefix for all table and field references in the general-purpose procedures, and
always fully qualify every database reference within such a procedure. Use the following
syntax:
If you use this syntax for every table or field reference in your procedure, only the alias will be
represented as the database reference in the procedures r-code after compilation. Note that this
is the only exception to the rule that you should never compile using aliases.
Unqualified table and field references within procedures may cause both the alias and the
logical database name for a particular physical database to be represented in the r-code for the
procedure at compilation time.
SYNTAX
alias.table-name alias.table-name.field-name
916
9.4.3 Using Shared Record Buffers with Aliases
Be careful when using shared buffers with aliases. If you reference a shared buffer after
changing the alias that initially was used in defining it, a run-time error results:
In this example, procedure main2.p calls makebuf.p, which in turn calls disp.p. The alias
myalias is created in main.p, with reference to database sports1. In makebuf.p, the shared buffer
mybuf is defined for the table myalias.customer. Then, in the next line, myalias is changed, so
that it now refers to database sports2. When an attempt is made to reference shared buffer mybuf
in procedure disp.p, a run-time error occurs, with the message disp.p unable to find shared
buffer for mybuf.
9.5 Data-handling Statements
Statements that move data from one location to another are called data-handling statements.
Progress stores data in various locationsa database, a record buffer, a screen buffer, etc. A
database stores application data on disk. A record buffer stores data temporarily while a
procedure accesses the data, and stores the values of variables used in the procedure. A screen
buffer stores data being displayed on the screen or being sent to another output destination; it
also stores data that is being entered from the terminal or other input source.
main2.p
CREATE ALIAS myalias FOR DATABASE sports1.
RUN makebuf.p.
makebuf.p
DEFINE NEW SHARED BUFFER mybuf FOR myalias.customer.
CREATE ALIAS myalias FOR DATABASE sports2.
RUN disp.p
disp.p
DEFINE SHARED BUFFER mybuf FOR myalias.customer.
FOR EACH mybuf:
DISPLAY mybuf.
END.
Database Access
917
Figure 91 shows how the data-handling statements move data.
Figure 91: Data Movement
To use Figure 91, read each statement from top to bottom. The beginning of the first arrow (the
dot) indicates the source of the data. The arrowhead of the last arrow indicates where the data
is finally stored. For example, the DISPLAY statement gets data from a record buffer and moves
it into a screen buffer. Once in the screen buffer, the data is displayed on screen. Also, note that
INSERT creates a new database record, moves it to the record buffer, and then to the screen
buffer where the user enters data, which is then moved back to the record buffer.
ASSIGN
CREATE
DELETE
DISPLAY
ENABLE
FIND
FOR EACH
GET
INSERT
RELEASE
SET
UPDATE
Statement
Database
Record
Record
Buffer
Screen
Buffer User
OPEN QUERY
(with BROWSE)
PROMPT-FOR
REPOSITION
(with BROWSE)
918
Some statements are made up of other statements. For example, the UPDATE statement is made
up of the DISPLAY, PROMPTFOR, and ASSIGN statements, and performs the same steps as
these other statements. First, it copies data from the record buffer to the screen buffer
(DISPLAY). Second, it allows data to be entered into the screen buffer (PROMPTFOR).
Third, it copies the data back to the record buffer (ASSIGN).
You can use statements as building blocks, using only as many as you need to do specific tasks.
For example, the INSERT statement is very powerful and combines several processing steps
into one statement. But in some situations, it is less flexible than using the CREATE, DISPLAY,
and SET statements individually (or the CREATE and UPDATE statements).
Figure 92 shows the primary data-handling statements and shows which statements are
composed of other statements.
Figure 92: The Primary Data-handling Statements
Note that the UPDATE, SET, and ASSIGN statements do not actually write records to the
database. However, at the end of a transaction (or at the end of the record scope or after an
explicit RELEASE), Progress writes all modified records to the database.
If you modify a record using INSERT, UPDATE, or SET, Progress assigns the change to the
record buffer (and, hence, eventually to the database). However, if you use the ENABLE
statement, you must explicitly assign any changes with the ASSIGN statement.
For more information on the statements in Figure 92, see the Progress Language Reference.
UPDATE
SET
PROMPT-FOR
DISABLE
VIEW
DISPLAY
ASSIGN
WAIT-FOR ENABLE
Copy to
Screen Buffer
Refresh Assign Disable Wait Activate Top
Database Access
919
9.6 Adding and Deleting Records
To add records to a database, you can use either the CREATE or INSERT statements. The
CREATE statement places a newly created record in the database, but does not display the
record or request user input. All fields in the record are set to the initial values specified in the
Data Dictionary. The CREATE statement causes any CREATE trigger associated with the table
to execute. This trigger may set fields in the record to new values. The INSERT statement not
only creates the record, but also displays the record and requests input.
The INSERT statement is composed of four other statementsthe CREATE, DISPLAY,
PROMPTFOR and ASSIGN statements. Three of these statements (DISPLAY,
PROMPTFOR, and ASSIGN) comprise the UPDATE statement. You can emulate an INSERT
statement by using the four statements, or by using the CREATE and UPDATE statements. This
is more flexible than using the INSERT statement alone.
For example, the INSERT statement always displays fields in the order they are defined in the
schema. The UPDATE statement lets you specify the order they are displayed. Note that if you
use an INSERT statement, the CREATE trigger is executed before the record is displayed.
To delete records from a database, use the DELETE statement. The DELETE statement causes
any DELETE trigger associated with the table to execute. For more information on database
triggers, see Chapter 11, Database Triggers.
9.7 Defining a Set of Records to Fetch
To fetch records, you must first define the set of records that you want Progress to fetch. For
example, the following statement defines the set of all customer records:
Progress allows you to define a set of records in a variety of ways. You define the set of records
in a Record phrase. For more information on the syntax of Record phrases, see the Progress
Language Reference. You can specify a Record phrase for the following Progress statements:
FIND
FOR [ EACH ]
OPEN QUERY
DO PRESELECT
REPEAT PRESELECT
FOR EACH Customer:
920
The examples given below illustrate some of the flexibility that you have when defining a set
of records. The Record phrases are highlighted. You can build complex Record phrases using
the AND and OR operands.
This example defines a set of one record (customer 11):
This example uses the word-indexed field Comments to define a set of records (all customer
records containing the word ship):
This example creates the subset of all Order records with the Customer number = 11:
This example defines a set of customer records (those between 25 and 50) to be preselected:
FIND Customer WHERE cust-num = 11.
FOR EACH Customer WHERE Comments CONTAINS "ship":
OPEN QUERY ordqry FOR EACH Order WHERE Cust-Order = 11.
REPEAT PRESELECT EACH Customer WHERE cust-num > 25 AND cust-num < 50:
Database Access
921
9.8 Fetching Records
After you define a set of records, Progress must fetch the records. How Progress fetches records
depends in part on which statements you use to fetch the records. Table 93 summarizes the
differences in record fetching between the FIND, FOR EACH, OPEN QUERY, and
PRESELECT statements.
9.8.1 Order of Fetched Records
The FOR EACH statement, OPEN QUERY statement, and PRESELECT option may use
multiple indexes to satisfy a query. When multiple indexes are used, the order of returned
records is not guaranteed. You can enforce an order by using the BY option.
The following example returns the selected customer records in ascending creditlimit order
and within credit limit in name order:
Table 93: Record Fetching
Statement
to Define Set of
Records
Statement
to Fetch
the Records
Structure Used
to Locate Records
FIND FIND Index
FOR EACH FOR EACH Results List or Index
OPEN QUERY GET Results List or Index
DO PRESELECT or
REPEAT PRESELECT
FIND Results List
FOR EACH customer BY Credit-limit BY Name:
922
9.8.2 Sample Record Fetches
The following examples show some of the many ways you can access records. These examples
are not meant to be exhaustive, but merely to show some of the flexibility provided by Progress.
Specify the FIRST, LAST, NEXT, or PREV options to step through all records in a
particular sequence:
Specify boolean expressions to describe the record or records to be fetched:
Specify a constant value of the primary index for the record. This works only if the primary
index is single-component. Also, this technique is not supported for the OPEN QUERY
statement:
Specify one or more field values that are currently in the screen buffer or record buffer:
Specify a previously found related record from another table (The two tables must share a
field with the same name. That field must have a UNIQUE index in at least one of the
tables.):
FOR EACH Customer WHERE Credit-Limit > 5000 AND Balance < 12000:
FIND Item 12.
PROMPT-FOR Customer.Cust-num WITH FRAME abc.
FIND Customer USING FRAME abc Customer.Cust-num.
DISPLAY Customer.Name.
FOR EACH Order OF Customer: /* This uses the cust-num field */
Database Access
923
Specify a CONTAINS clause on a word-indexed field:
You cannot use a CONTAINS clause with the FIND statement. You can use CONTAINS
only with the OPEN QUERY and FOR EACH statements.
9.8.3 ROWID and RECID Data Types
Progress provides two structure types to support record fetches. One structure type, the index,
you define in the schema of your database. The other structure type, a results list, is temporary;
Progress builds it at run time. The results list associated with a DO, REPEAT, or OPEN
QUERY statement with the PRESELECT option is sometimes called a preselect list.
In addition, there are two data types, ROWID and RECID, that allow you to retrieve a pointer
to a fetched record. You can use this pointer to:
Position to and retrieve a record from a results list.
Refetch a record and modify its lock status.
Store as a future record reference.
In addition to the examples in this section, you can see ROWID at work in the chapters that
describe the following Progress features:
Browse interactions Chapter 10, Using the Browse Widget.
Transactions and updates Chapter 12, Transactions.
General lock management Chapter 13, Locks.
ROWID versus RECID
ROWID is supported by all DataServers. Earlier Progress versions provide RECID as the only
way to fetch a record pointer (supported in this version for backward compatibility). RECID is
limited to a 4-byte record address supported by only a few DataServers and standard Progress.
ROWID provides a variable byte string that can represent a record address for any type of
DataServer. For DataServers that use the 4-byte address supported by RECID (including
Progress), ROWID also uses a four-4 value. Thus, there is no loss in performance using the
more portable ROWID instead of RECID.
FOR EACH Customer WHERE Comments CONTAINS "ship":
924
Returning Record ROWID Values
Progress provides a function named after the ROWID data type to return ROWID values. Given
a buffer name, the ROWID function returns the ROWID of the current record in the buffer. This
example fetches the first customer record, and if it has a balance, refetches it to lock it for
update:
Storing and Retrieving ROWID and RECID Values
As shown in the previous example, you can store ROWID values in ROWID variables. You can
also store them in work table fields. Thus, the following are valid ROWID storage definitions:
You cannot store ROWID values in database or temporary tables, but you can store their
hexadecimal string representations using the STRING function. You can then retrieve the string
as a ROWID value using the TOROWID function:
You can store RECID values directly in a database or temporary table.
DEFINE VARIABLE custrid AS ROWID.
FIND FIRST customer NO-LOCK.
custrid = ROWID(customer).
IF balance > 0 THEN DO:
FIND customer WHERE ROWID(customer) = custrid EXCLUSIVE-LOCK.
UPDATE customer.
END.
DEFINE VARIABLE wkrid AS ROWID EXTENT 20.
DEFINE WORK-TABLE wtrid FIELD wkrid AS ROWID.
DEFINE TEMP-TABLE ttrid
FIELD ridfld AS CHARACTER.
FOR EACH customer FIELDS (balance) WHERE balance = 0 NO-LOCK:
CREATE ttrid.
ASSIGN ttrid.ridfld = STRING(ROWID(customer)).
END.
DO TRANSACTION:
FOR EACH ttrid:
FIND customer WHERE ROWID(customer) = TO-ROWID(ttrid.ridfld).
DELETE customer.
END.
END.
Database Access
925
Additional 4GL Support
Several additional statements use ROWID and RECID values directly. For example, the
REPOSITION statement sets the query position to a record given by its ROWID or RECID. For
more information, see the Results Lists section.
Also, because RECID is not supported by all DataServers, Progress provides the
DBRESTRICTIONS function to indicate whether a particular DataServer supports it.
Converting from RECID to ROWID
When changing an application to use ROWID that currently uses RECID, you can complete the
change with only a keyword substitution if your application:
Does not reference RECID values as integers
Does not store RECID values in database or temporary tables
Otherwise, after you change all RECID references to ROWID, you must rewrite your
integer references to use character strings. If you use database or temporary tables, you must
also convert the relevant fields to CHARACTER fields, and use the STRING and TOROWID
functions to store and retrieve ROWID values. However, note that some DataServers build a
string for a single ROWID that can reach up to several hundred bytes (including a complete
WHERE clause).
All DataServer tables support ROWID references except those, such as views, that do not have
unique row identifiers. DataServers from earlier Progress versions also support ROWID
references. Versions 7.3A and later use an internal RECID that transparently converts to a
ROWID in the client.
Writing DataServer-portable Applications
The least portable feature of ROWID references is the scope of a ROWID reference and when
it changes for each DataServer. To maximize portability, follow these rules:
Always assign values to unique keys before returning the ROWID value of a record. Some
DataServers use a unique key to generate the ROWID value.
If you UNDO a DELETE of a record for which you have stored the ROWID value, return
the ROWID value again after the UNDO. It might be different after the record is recreated.
If you update a unique key value for a record, return its ROWID again to replace any prior
value.
Never expect a record to have the same ROWID value between sessions.
926
Note that each DataServer uses a different method to generate a ROWID for a table, and
sometimes for different tables in the same database. Therefore, never expect ROWID values to
be identical, or even compatible, between otherwise duplicate tables from different
DataServers.
For more information on ROWID value construction and scope for your DataServer, see your
Progress DataServer guide.
9.8.4 Results Lists
A results list is a list of ROWIDs that satisfy a query. The results list allows you to quickly
access the records in the record set you define, and allows Progress to make the records
available one at a time, as needed.
When more than one row satisfies a query, Progress doesnt lock all of the records and hold
them until you release them. Instead, when a specific record is needed, Progress uses the
records ID to go directly to the record, locking only that record. By going directly to the record,
Progress also ensures that you have the latest copy of the record.
When you open a query, Progress does not normally build the entire results list. Instead it
initializes the results list and adds to it as needed. The NUMRESULTS function returns the
number of records currently in the results list. This is not necessarily the total number of records
that satisfy the query.
Whether and when Progress builds the results list depends on the type of the query. As shown
in Table 93, the DO or REPEAT PRESELECT statements always use a results list, while the
FOE EACH and OPEN QUERY statements sometimes use a results list.
Queries have the following characteristics:
Scrolling versus non-scrolling A query is scrolling if you specify SCROLLING in the
DEFINE QUERY statement or if you define a browse for the query. You can use the
REPOSITION statement to change your current position within the results list. For a
non-scrolling query, you can only move sequentially through the rows by using the FIRST,
LAST, NEXT, and PREV options of the GET statement. Scrolling queries must use a
results list (often initially empty); non-scrolling queries might not.
Index-sorted If the order of the rows in the query can be determined by using a single
index, the query is index-sorted. For an index-sorted query, Progress can use the index to
order records without a results list. However, if the query requires additional sorting it
must also be presorted.
Presorted If the query requires any sorting without an index or with multiple indexes,
it must be presorted. For a presorted query, Progress must read all the records, sort them,
and build the complete results list before any records are fetched.
Database Access
927
Preselected versus non-preselected You can force Progress to build a preselected
results list by specifying PRESELECT on the OPEN QUERY, DO, or REPEAT
statement.
Table 94 summarizes how the results list is built for each type of query.
There are two cases where Progress has to build the entire results list when you first open the
query:
When you have explicitly used the PRESELECT option. In this case, Progress performs a
preselection phase in which it reads each record of the query. You can specify the lock type
to use during the preselection phase. (For an OPEN QUERY, the lock type you specify in
the OPEN QUERY statement is used for the preselection phase.) These locks are released
immediately unless the preselection occurs within a transaction.
When you have not used the PRESELECT option, but have specified sort criteria that
cannot be performed using an index. In this case, Progress performs a presort phase in
which it reads each record of the query with NOLOCK and builds the results list.
For example, the following statement explicitly uses the PRESELECT option. This forces
Progress to build the entire results list immediately:
If you had used FOR instead of PRESELECT, Progress would not have had to build the entire
results list because it uses the primary index to fetch the records. It could use this index to find
the first or last record for the query; it only needs to search forward or backward through the
index until it finds a record that satisfies the WHERE clause.
Table 94: Results Lists for Specific Query Types
Query Type Results List
Non-scrolling, index-sorted, no preselection None.
Scrolling, no sorting, no preselection
Empty list
1
established when query is
opened. Records are added to the results
list as needed.
Presorted or preselected Complete list built when query is opened.
1
If a browse is defined for the query, the results list initially contains one row.
OPEN QUERY cust-query PRESELECT EACH customer WHERE credit-limit > 1500.
928
You can use the PRESELECT option of the OPEN QUERY statement when you need to know
immediately how many records satisfy the query or you can use it to immediately lock all the
records that satisfy the query.
Progress also builds a complete results list when you open a query with a sort condition that
cannot be resolved using a single index. Suppose you open a query on the customer table as
follows:
Because there is no index for the city field, Progress must retrieve all the records that satisfy the
query (in this case, all the customer records), perform the sort, and build the entire results list
before any records can be fetched. Until it performs this sort, Progress cannot determine the first
or last record for the query. If an index were defined on the city field, Progress could use that
index to fetch the records in sorted order (forwards or backwards) and would not need to build
the results list in advance.
If the sort conditions for a query can be resolved using a single index, you can use the GET
statement with the FIRST, LAST, NEXT, and PREV options on that query. For example, the
following query is sorted using the primary index:
Because the sorting is done with a single index, you can move freely forwards and backwards
within the query.
NOTE: If you want to use the REPOSITION statement on a query, you must make the query
scrolling by specifying the SCROLLING option in a DEFINE QUERY statement.
OPEN QUERY cust-query FOR EACH customer BY city.
OPEN QUERY custqry FOR EACH customer.
GET FIRST custqry.
DISPLAY cust-num name. /* Display first record */
PAUSE.
GET NEXT custqry. /* Display second record */
PAUSE.
GET LAST custqry. /* Display last record */
PAUSE.
GET PREV custqry.
DISPLAY cust-num name. /* Display second-to-last record */
Database Access
929
Navigating a Results List
As shown in Table 93, results lists are associated with the OPEN QUERY and GET statements.
However, Progress only guarantees a results list if you first define the query with the
SCROLLING option:
This option indicates to Progress that you want to use the results list for multi-directional
navigation.
You can use the REPOSITION statement to specify how many places forward or backward you
want to move, so that you can skip over a given number records. It also allows you to move to
a specific ROWID.
The REPOSITION statement changes your location in the results list but does not actually fetch
the record (unless the query is associated with a browse widget). To actually fetch records in a
results list, you use the GET statement. The following example illustrates how the
REPOSITION statement works:
After a record is fetched (with a GET statement), the results list position is on the ROWID, so
that GET NEXT gets the next record, and GET PREV gets the previous record. After a
REPOSITION, the position is always between two records. Thus, REPOSITION
FORWARD 0 repositions the results list immediately after the current record. GET NEXT
fetches the next record; GET PREV fetches the previous record. REPOSITION FORWARD 1
repositions the results list between the next record and the record after it.
DEFINE QUERY custqry FOR customer SCROLLING.
DEFINE QUERY q FOR customer SCROLLING.
DEFINE VARIABLE rid AS ROWID. /* to save the ROWID of cust 4 */
OPEN QUERY q FOR EACH cust.
GET NEXT q. /* gets cust no. 1 */
/* query is positioned ON cust 2 */
GET PREV q. /* gets cust no. 1 */
REPOSITION q FORWARD 0. /* query is positioned BETWEEN cust 1 and 2 */
/* query is positioned ON cust 2 */
REPOSITION q FORWARD 1. /* query is positioned BETWEEN cust 3 and 4 */
rid = ROWID(cust). /* query is positioned ON cust 4 */
REPOSITION q BACKWARD 2. /* query is positioned BETWEEN cust 2 and 3 */
GET PREV q. /* gets cust no. 2 */
REPOSITION q TO ROWID(rid). /* query is positioned BETWEEN cust 3 and 4 */ GET
NEXT q. /* gets cust no. 4 */
930
To find the total number of rows in a results list, you can use the NUMRESULTS function. To
find the current position within a results list, you can use the CURRENTRESULTROW
function.
As Table 93 shows, Progress also creates results lists for FOR EACH statements and for DO
and REPEAT statements with the PRESELECT phrase. However, you cannot navigate freely
through a results list created for the FOR EACH statement. If the results list was created for the
FOR EACH statement, then Progress automatically steps through the results list in sorted order:
Within a PRESELECT block, you can use the FIND statement to move backwards and forwards
through the results list:
NOTE: A powerful way of navigating a record set is with the browse widget. For more
information, see Chapter 10, Using the Browse Widget.
FOR EACH customer BY name:
DISPLAY name city state.
END.
/* This code fragment displays all customers in descending order */
DO PRESELECT EACH customer:
FIND LAST customer. /* last position in list */
DISPLAY cust-num name WITH FRAME a DOWN.
REPEAT:
FIND PREV customer. /* move backward through list */
DOWN WITH FRAME a.
END.
END.
Database Access
931
9.8.5 FIND Repositioning
After executing FOR EACH statements or FIND statements, Progress might reposition
subsequent FIND statements to the last record fetched (except for FIND statements occurring
in PRESELECT blocks). For repositioning to occur, the same record buffer must be used. Also,
repositioning after FOR EACH statements can differ between Version 8.0B and Versions 8.0A
and earlier, depending on the options you use.
NOTE: Repositioning does not occur for a subsequent FIND if the FIND specifies a unique
key (that is, the FIND does not use the NEXT or PREV options).
Repositioning After FIND Fetches
Progress uses index cursors to keep track of what record you last fetched. This is important if
you use the FIND statement to fetch a record. For example, depending on what was the last
record fetched, the following statement returns a different record:
If you had last fetched the first customer record, this statement would fetch the second customer
record. If you had just fetched the fourth customer record, this statement would fetch the fifth
customer record.
A table can have multiple indexes, and the cursor position in each index dictates what the next
record is in that index. For example, the following code fragment fetches customers 1 and 21:
In the countrypost index, the next record after customer 1 is customer 21. Progress uses the
index cursor to establish the correct context.
Sometimes cursor repositioning is tricky. For example, the following code fragment returns
customer 6 and customer 7 (you might expect customer 6 and customer 2):
FIND NEXT customer.
DISPLAY cust-num name country postal-code.
PAUSE.
FIND NEXT customer USE-INDEX country-post.
DISPLAY cust-num name country postal-code.
FIND FIRST customer WHERE cust-num > 5.
PAUSE.
FIND NEXT customer WHERE cust-num > 1.
932
The first FIND statement causes Progress to reposition the custnum index cursor to point to
customer 6. The second FIND statement begins the search from that location, not from the
beginning of the custnum index.
9.9 Fetching Field Lists
When fetching records with a FOR EACH statement or query, Progress typically retrieves all
the fields of a record, whether or not your application needs them. This can have a costly impact
on performance, especially when browsing records over a network.
Progress automatically optimizes preselected and presorted fetches from remote Progress
databases using field lists. A field list is a subset of the fields that define a record and includes
those fields that the client actually requires from the database server. For preselected and
presorted fetches, Progress can deduce this field list at compile time from the code. You can also
specify field lists explicitly for many types of Progress record fetches, including:
Queries
FOR statements
DO PRESELECT statements
REPEAT PRESELECT statements
SQL SELECT statements
This section explains how to use field lists in the Progress 4GL. For information on specifying
field lists in SQL SELECT statements, see the Progress SQL-89 Guide and Reference.
9.9.1 Field List Benefits
Field lists can provide significant performance benefits when:
Browsing over a network With the reduction in network traffic, tests show that field
lists can increase the performance of fetches from both remote Progress and DataServer
databases by factors of from 2 to 10, depending on the record size and number of fields in
the list.
Fetching from local DataServers Some local DataServers can yield significant
improvements in fetch performance when only a portion of the record is read.
Fetching from remote DataServers that send multiple rows at a time DataServers
that package multiple rows per network message show noticeable performance gains using
field list fetches.
Database Access
933
In general, these benefits mean that a multi-user query application can handle more network
clients when fetching field lists than when fetching whole records. For more information on the
availability and benefits of field list fetches with DataServers, see the Progress DataServer
guides.
9.9.2 Specifying Field Lists in the 4GL
You can specify a field list in two different 4GL contexts:
Following each buffer name specified in a DEFINE QUERY statement
Following the buffer name specified for fetching in each Record phrase of a FOR, DO
PRESELECT, or REPEAT PRESELECT statement
This is the syntax for specifying a field list in all cases:
The recordbufname reference specifies the table buffer you are using for the fetch, and a field
reference specifies a field in the table. If field is an array reference, the whole array is fetched.
The FIELDS form lists the fields included in the fetch, and the EXCEPT form lists the fields
excluded from the fetch. FIELDS without field references fetches enough information to return
the ROWID of a record, and EXCEPT without field references or recordbufname alone fetches
a complete record.
Queries versus Record Selection Blocks
For a query, you must specify the field lists in the DEFINE QUERY statement, not the Record
phrase of the OPEN QUERY statement. Thus, the following two procedures, p-fldls1.p and
p-fldls2.p, are functionally equivalent:
SYNTAX
record-bufname
[ FIELDS [ ( [ field ... ] ) ]
| EXCEPT [ ( [ field ... ] ) ]
]
934
Shared Queries
If you specify field lists in a NEW SHARED query, the matching SHARED query definitions
in external procedures only have to include the FIELDS or EXCEPT keyword as a minimum
field list reference. The complete field list is optional in the SHARED query definitions, but
required in the NEW SHARED query definition.
However, Progress raises the ERROR condition when you run a procedure with a SHARED
query if you:
Specify a field list in the SHARED query to match a NEW SHARED query that has no
field list.
Do not specify a field list reference in the SHARED query to match a NEW SHARED
query that has a field list.
p-fldls1.p
DEFINE QUERY custq FOR customer FIELDS (name cust-num balance).
OPEN QUERY custq PRESELECT EACH customer.
REPEAT:
GET NEXT custq.
IF AVAILABLE(customer)
THEN DISPLAY name cust-num balance.
ELSE LEAVE.
END.
p-rldls2.p
REPEAT PRESELECT EACH customer FIELDS (name cust-num balance):
FIND NEXT customer.
DISPLAY name cust-num balance.
END.
Database Access
935
9.9.3 Avoiding Implied Field List Entries
Under certain conditions, Progress adds fields to a specified field list when they are required by
the client to complete the record selection. The most common case is when you specify a join
condition with the OF option and you do not include the join field in the field list.
In this case, Progress adds customer.custnum to the list because the client requires it to
complete the join between the customer and invoice tables.
However, never rely on implied entries in a field list to provide the fields you need. If you
reference an unfetched field, Progress raises the ERROR condition at run time. Future versions
of Progress might change the criteria used to distribute record selection between the client and
server. Thus in the previous example, if the server does not return customer.custnum to the
client to complete the join, the DISPLAY statement executes with ERROR. This might happen,
for example, if the DataServer you use or a future version of Progress actually completes the
specified join on the server.
Therefore, always specify all the fields you plan to reference in your field lists. There is no extra
cost for specifying a field that Progress can also add implicitly.
9.9.4 Updating and Deleting with Field Lists
After fetching a field list, if your procedure updates the fetched record, Progress always rereads
the complete record before completing the update. In fact, if you fetch a field list with
EXCLUSIVELOCK, Progress reads the complete record anyway. This is to ensure proper
operation of updates and the before-image (BI) file. (For information on BI files, see the
Progress Client Deployment Guide.)
Also, if you delete a record after fetching a field list for it, Progress rereads the complete record
for the following cases:
If you delete from a Progress database, Progress always rereads the complete record.
If you delete from a DataServer database, Progress rereads the complete record if the
delete occurs in a subtransaction, in order to create the local before-image (LBI) note. (For
information on LBI files, see the Progress Client Deployment Guide.)
FOR EACH customer FIELDS (name),
EACH invoice FIELDS (invoice-num amount) OF customer:
DISPLAY customer.name customer.cust-num
invoice.invoice-num invoice.amount.
936
Thus, if you fetch with NOLOCK or SHARELOCK, avoid using field lists if you expect to
perform a high ratio of updates or deletes to fetches. For example, this is an inefficient
construction with a Progress database:
This procedure rereads the complete record for each field list that it fetches, and thus fetches
twice per record. Without the field list, the same procedure fetches only once per record.
Updating and Deleting with Query Field Lists
For queries, especially those attached to a browse widget, there is little concern about updates
and deletes, because the complete results list for a query is built before any updates or deletes
take place. In this case, updates and deletes are selective over the entire query. Therefore, field
lists can greatly enhance query performance, no matter how many updates or deletes a browse
user completes. For more information on browse widgets, see Chapter 10, Using the Browse
Widget.
9.9.5 Cursor Repositioning and Field Lists
FOR and relative FIND statements reposition all open index cursors for the same buffer. (For
more information, see the FIND Repositioning section.) However, in order to reposition a
buffers index cursors, Progress must have all the index fields available in the buffer. If you
fetch a field list that excludes some of these fields, Progress marks the relevant indexes as being
incorrectly positioned.
This does not matter for the query or fetch loop that uses the field list, because Progress might
never reference the relevant indexes. However, if you later execute a FIND NEXT or FIND
PREV using one of the badly positioned indexes, Progress raises the ERROR condition and the
FIND fails.
To avoid this error, always specify the fields in your field lists that participate in the indexes you
reference.
FOR EACH customer FIELDS (name balance):
DISPLAY "Deleting customer" name "with balance:" balance.
DELETE customer.
END.
Database Access
937
9.9.6 Field List Handling in Degenerate Cases
When you specify field lists, Progress is very flexible where it cannot make use of them.
Progress either returns complete records automatically or allows you to bypass field list
processing completely for the following cases:
Progress server versions Earlier database servers interpret field list requests as
requests for complete records. Progress sends queries in such a way that earlier servers do
not need to know that the field list requests are included.
DataServers that do not support SHARELOCK If you execute a SHARELOCK
fetch from a DataServer that does not support SHARELOCK, Progress ignores the field
list and retrieves the complete record. In some circumstances, Progress must replace the
fetched record with a new version. Because the SHARELOCK is meaningless, the new
version can be different from the previous one, and Progress requires the complete record
to ensure that the user receives the correct data.
NOTE: You can avoid SHARELOCK fetches with the help of the
CURRENTCHANGED function. For more information, see Chapter 13,
Locks.
Multiple queries returning the same record If you specify two queries that return
two different field lists for the same record, Progress cannot always consolidate the two
lists. In that case, Progress must reread the complete record. Such occurrences are rare, but
they can impose a minor performance penalty with little impact on overall performance.
Deployment problems While programmers must ensure that their field lists are
complete, run-time errors can still occur during application deployment. This is especially
likely when a new database (schema) trigger is defined that references an unfetched field.
To work around this type of problem, Progress provides the Field List Disable (fldisable)
client session parameter. This is a run-time parameter that causes Progress to ignore field
lists in the r-code and fetch complete records. This might degrade performance, but allows
the application to run until a fix can be made.
Thus, while using field lists can lead to difficulties, Progress provides a way around most of
them. And when used optimally, the performance gains can make field lists well worth the extra
attention they might require.
938
9.10 Joining Tables
When you read from multiple tables using a single statement, such as a FOR EACH or OPEN
QUERY statement, Progress returns the results as a join of the tables. A join is a binary
operation that selects and combines the records from multiple tables so that each result in the
results list contains a single record from each table. That is, a single join operation combines the
records of one table with those of another table or combines the records of one table with the
results of a previous join. Figure 93 shows how you can join three tables.
FOR EACH Table1, EACH Table2 WHERE C11 = C21, EACH Table3 WHERE C22 = C31:
DISPLAY C11 C12 C21 C22 C31 C32 WITH TITLE "Join123".
Database Access
939
Figure 93: Inner Joins
A table or prior join can be either on the left- or right-hand side of a join operation. Thus, the
results of joining the three tables in Figure 93 depends on two join operationsone join
between Table1 (left-hand side) and Table2 (right-hand side) and one join between the first join
(left-hand side) and Table3 (right-hand side). The relations C11 = C21 and C22 = C31 represent
join conditions, conditions that determine how one table is related to the other (that is, which
records selected from one table join with the records in the other table). How the records from
joined tables are combined depends on the order of the tables in the join, the type of join
operation used, and the selection criteria applied to each table.
Table2
C21 C22
1 6
2 2
2 5
3 9
Table3
C31 C32
1 3
5 2
6 1
8 7
Table1
C11 C12
1 2
2 4
5 7
6 9
Join12
C11 C12
1 2
2 4
2 4
C21 C22
1 6
2 2
2 5
Join123
C31 C32
6
1
2
5
C11 C12
1 2
2 4
C21 C22
1 6
2 5
Join
Where
C11 = C21
Join
Where
C22 = C31
940
9.10.1 Specifying Joins in the 4GL
Progress supports two types of joins in the 4GL:
Inner join Supported in all statements capable of reading multiple tables, including the
FOR, DO, REPEAT, and OPEN QUERY statements. An inner join returns the records
selected for the table (or join) on the left side combined with the related records selected
from the table on the right. For any records not selected from the right-hand table, the join
returns no records from either the left or right sides of the join. Thus, only related records
that are selected from both sides are returned for an inner join. Table 93 shows an
example of inner joins.
Left outer join Supported only in the OPEN QUERY statement. A left outer join
returns the records selected for an inner join. In addition, for each set of records selected
from the table (or join) on the left side, a left outer join returns unknown values (?) from
the table on the right where there is no record selected or otherwise related to the records
on the left. That is, records from the left-hand table (or join) are preserved for all
unmatched records in the right-hand table. Figure 94 shows an example of left outer joins
using the same tables as in Figure 93.
NOTE: For versions earlier than V8, Progress supports only the inner join.
Specifying the Type of Join
The Record phrase that specifies the right-hand table of a join also indicates the type of join
operation. A Record phrase specifies an inner join by default. To specify a left outer join, you
include the [LEFT] OUTERJOIN option anywhere in the Record phrase. Where you specify
a list of multiple Record phrases in a record-reading statement, the join logic allows you to
specify only one set of contiguous inner joins at the beginning (left side) of the list and one set
of contiguous left outer joins at the end (right side) of the list. Each right-hand Record phrase
of a left outer join must contain the OUTERJOIN option up to and including the last left outer
join in the list. For more information, see the Mixing Inner and Left Outer Joins section.
Database Access
941
Relating and Selecting Tables
You can specify join conditions (table relations) using the OF option or WHERE option of the
Record phrase that specifies the join. The OF option specifies an implicit join condition based
on one or more common field names in the specified tables. The common field names must
participate in a unique index for at least one of the tables. The WHERE option can specify an
explicit join based on any field relations you choose, and you can use this option further to
specify selection criteria for each table in the join. For an inner join, if you do not use either
option, Progress returns a join of all records in the specified tables. For a left outer join, you
must relate tables and select records using the OF option, the WHERE option, or both options.
NOTE: Work tables and temporary tables can also participate in joins. However, work tables
do not have indexes. So, if you specify join conditions using the OF option with a
work table, the other table in the join must be a database or temporary table with a
unique index for the fields in common. For more information on work tables and
temporary tables, see Chapter 15, Work Tables and Temporary Tables.
The following code fragment generates the left outer joins shown in Figure 94. Note that the
Record phrase for the right-hand table of each join specifies the OUTERJOIN option. As
Figure 94 shows, the primary benefit of a left outer join is that it returns every record on the
left-hand side, whether or not related data exists on the right.
DEFINE QUERY q1 FOR Table1, Table2, Table3.
OPEN QUERY q1 FOR EACH Table1, EACH Table2 OUTER-JOIN WHERE C11 = C21,
EACH Table3 OUTER-JOIN WHERE C22 = C31.
GET FIRST q1.
DO WHILE AVAILABLE(Table1):
DISPLAY C11 C12 C21 C22 C31 C32 WITH TITLE "Join123".
GET NEXT q1.
END.
942
Figure 94: Left Outer Joins
5 2
?
?
?
?
2 4
5 7
6 9
2 5
? ?
? ?
Join123
C31 C32
6
1
?
?
C11 C12
1 2
2 4
C21 C22
1 6
2 2
Table2
C21 C22
1 6
2 2
2 5
3 9
Left Outer
Join
Where
C11 = C21
Table1
C11 C12
1 2
2 4
6 9
Table3
C31 C32
1 3
5 2
6 1
8 7 5 7
Join12
C11 C12
1 2
2 4
2 4
C21 C22
1 6
2 2
2 5
6 9
? ?
? ?
Left Outer
Join
Where
C22 = C31
5 7
Database Access
943
Why Use Joins Instead of Nested Reads?
Using joins provides an opportunity for Progress to optimize the retrieval of records from
multiple related tables using the selection criteria you specify. When you perform a nested read,
for example using nested FOR EACH statements for different tables, you are actually
implementing a join in a 4GL procedure. However, by specifying one or more contiguous joins
in a single FOR EACH statement or in the PRESELECT phrase of single DO or REPEAT
statement, you minimize the complexity of your 4GL code and leave the complexity of joining
tables to the Progress interpreter.
For a single 4GL query (OPEN QUERY statement), there is no other way to retrieve data from
multiple tables except by using joins. With both inner and left outer join capability, you can use
the OPEN QUERY statement to implement most queries that are possible using nested FOR
EACH, DO, or REPEAT statements. As such, query joins provide the greatest opportunity for
optimized multi-table record retrieval in the 4GL. Also, because browse widgets read their data
from queries, you must use query joins to display multiple related tables in a browse. (For more
information on browsing records, see Chapter 10, Using the Browse Widget.)
However, use nested FOR EACH, DO, and REPEAT blocks wherever you require much finer
control over how you access and manipulate records from multiple tables.
9.10.2 Using Inner Joins
The inner join is the default join type in a multi-table read or query. Use this type of join where
you are only concerned with the data on the left side of the join for which there is related data
on the right. For example, you might want to see only those customers whose purchase of a
single item comes close to their credit limit.
The query in p-join1.p performs three inner joins on the sports database to return this data.
These three items correspond to the /*1*/, /*2*/, and /*3*/ that label the joins in the
p-join1.p example:
1. To each Customer, join all related Order records.
2. To each Order in the previous join, join each related OrderLine record whose total
purchase is greater than two-thirds the customers credit limit.
3. To each OrderLine in the previous join, join the related Item record to get the item name.
944
When executed, you get the output shown in Figure 95. Thus, the relation of Order to Customer
and the selection criteria on OrderLine reduces the total number of query rows from thousands
of possible rows to four.
Figure 95: Inner Join Example
p-join1.p
DEFINE QUERY q1 FOR Customer, Order, Order-Line, Item.
DEFINE BROWSE b1 QUERY q1
DISPLAY Customer.Name Customer.Credit-Limit Order.Order-num
Item.Item-Name
WITH 10 DOWN.
OPEN QUERY q1 PRESELECT EACH Customer,
EACH Order OF Customer,
EACH Order-Line OF Order
WHERE (Order-Line.Price * Order-Line.Qty) >
(.667 * Customer.Credit-Limit),
EACH Item OF Order-Line.
ENABLE b1 WITH SIZE 68 BY 10.
Database Access
945
9.10.3 Using Left Outer Joins
A left outer join is useful where you want to see all the data on the left side, whether or not there
is related data on the right. For example, you might want to see the proportion of customers who
are ordering close to their credit limit as against those who are not.
The query in p-join2.p is identical to the one in p-join1.p (see the Using Inner Joins
section) except that all the joins are left outer joins instead of inner joins. Thus, you see all
customers, whether or not they order close to their credit limit. These three items correspond to
the /*1*/,/*2*/, and /*3*/ that label the joins in the p-join2.p example:
1. To each Customer, join all related Order records, or join a null Order record if the customer
has no orders.
2. To each Order in the previous join, join each related OrderLine record whose total
purchase is greater than twothirds the customers credit limit, or join a null OrderLine
record if all item purchases are less than or equal to twothirds the customers credit limit.
Also, join a null OrderLine record if the order is null (the customer has no orders).
3. To each OrderLine in the previous join, join the related Item record to get the item name,
or join a null Item record if the the OrderLine is null (no Order or selected purchase for
that customer).
When executed, you get the output shown in Figure 96. In this example, you see the same golf
club order as in Figure 95 along with many other orders that do not meet the selection criteria
and some customers who have no orders at all.
p-join2.p
DEFINE QUERY q1 FOR Customer, Order, Order-Line, Item.
DEFINE BROWSE b1 QUERY q1
DISPLAY Customer.Name Customer.Credit-Limit Order.Order-num
Item.Item-Name
WITH 10 DOWN.
OPEN QUERY q1 PRESELECT EACH Customer,
EACH Order OUTER-JOIN OF Customer,
EACH Order-Line OUTER-JOIN OF Order
WHERE (Order-Line.Price * Order-Line.Qty) >
(.667 * Customer.Credit-Limit),
EACH Item OUTER-JOIN OF Order-Line.
ENABLE b1 WITH SIZE 68 BY 10.
946
Figure 96: Left Outer Join Example
9.10.4 Implementing Other Outer Joins
In addition to left outer joins, there are right and full outer joins. A right outer join reverses the
join order for the same tables joined with a left outer join. In the 4GL, you can implement a right
outer join by doing a left outer join with the tables in reverse order, but leaving the order of
displayed fields the same as for the left outer join. Thus, unknown values from the right side
appear on the left side of each displayed row, as if the tables were joined from right to left.
A full outer join combines the results of a left and right outer join into a single join. This is rarely
used, but you can implement a full outer join by building one temporary table from the results
of both a left and right outer join. For more information on temporary tables, see Chapter 15,
Work Tables and Temporary Tables.
Database Access
947
9.10.5 Mixing Inner and Left Outer Joins
You might want to mix inner and left outer joins in order to filter and reduce the amount of data
you need on the left side of your left outer joins. When mixing these two types of join, keep in
mind that the last inner join in a query forces the results of all prior joins in the query to be inner
joins. This is because any rows that contain unknown values from a prior left outer join are
eliminated by the following inner join. The effect is that the work of the prior left outer joins is
wasted, and the same result is achieved as with contiguous inner joins, but much less efficiently.
Therefore, in any query, keep your inner joins contiguous on the left with any left outer joins
contiguous on the right.
9.11 The CONTAINS Operator, Word Indexes, and Word-break Tables
You can use the CONTAINS operator of the WHERE option of the record phrase to query a
Progress database. For example, the following query displays each item record of the sports
database whose catdescription field contains the string hockey:
Using the CONTAINS operator involves word indexes and word-break tables. This section
explains why and tells you how to use word indexes and word-break tables. Specifically, the
section covers:
Understanding the CONTAINS operator, word indexes, and word-break tables
Using word indexes
Using word-break tables
Using the CONTAINS operator
Word indexing external documents
Word indexing non-Progress databases
NOTE: Word indexes and word-break tables have international implications. To understand
these implications, first read this section, then see the Progress Internationalization
Guide.
FOR EACH item WHERE cat-description CONTAINS "hockey":
DISPLAY item.
END.
948
9.11.1 Understanding the CONTAINS Operator, Word Indexes,
and Word-break Tables
To process queries containing the CONTAINS operator, Progress uses word indexes. Similarly,
to create, maintain, and use word indexes, Progress uses word-break tables. Let us examine this
relationship chain one link at a time.
The CONTAINS Operator and Word Indexes
For Progress to process a query that uses the CONTAINS operator, the field mentioned in the
WHERE option must participate in a word index. For example, to process the following query:
Progress looks for the word indexes associated with the item record and its catdescription field.
If no such word indexes are found, Progress reports a run-time error. Otherwise, Progress uses
the word indexes to retrieve the item records whose catdescription field contains the string
"hockey."
Word Indexes and Word-break Tables
In order for Progress to use word indexes, it must first build and maintain them, which it does
as you add, delete, and modify records that have fields that participate in them. Consider the
sports databases item table, whose catdescription field participates in a word index. Every
time an item record is added, Progress examines the contents of the catdescription field, breaks
it down into individual words, and, for each individual word, creates or modifies a word index.
To break down the contents of a field into individual words, Progress must know which
characters act as word delimiters. To get this information, Progress consults the databases
word-break table, which lists characters and describes the word-delimiting properties of each.
9.11.2 Creating and Viewing Word Indexes
To define a new word index or to view the word indexes already defined on a database table,
use the Progress Data Dictionary utility. For example, you can use this utility to view the word
indexes of the sports database, including the word index associated with the item table and its
catdescription field. For more information on creating and viewing word indexes using the
Progress Data Dictionary utility, see the Progress Basic Development Tools manual or the
Progress Data Dictionary utility online help.
FOR EACH item WHERE cat-description CONTAINS "hockey":
DISPLAY item.
END.
Database Access
949
Word Indexing Very Large Fields
NOTE: If a word index is defined on a CHARACTER field that is extremely large, you might
have to increase the value of the Stash Area (stsh) startup parameter. Doing so
increases the amount of space Progress uses to temporarily storage of modified
indexes. For more information, see the reference entry for the Stash Area (stsh)
startup parameter in the Progress Startup Command and Parameter Reference.
Word Indexing Double-byte and Triple-byte Code Pages
You can use word indexing with double-byte and triple-byte code pages. For more information,
see the Progress Internationalization Guide.
9.11.3 Using Word-break Tables
You can create word-break tables that specify word separators using a rich set of criteria. To
specify and work with word-break tables involves:
Specifying word delimiter attributes
Understanding the syntax of word-break tables
Compiling word-break tables
Associating compiled word-break tables with databases
Rebuilding word indexes
Providing access to compiled word-break tables
Specifying Word Delimiter Attributes
As mentioned previously, to break down the contents of a word-indexed field into individual
words, Progress needs to know which characters delimit words and which do not. The
distinction can be subtle and sometimes depends on context. For example, consider the function
of the dot in the character strings in Table 95.
950
In the first character string, the dot functions as a decimal point and does not divide one word
from another. Thus, you can query on the word $25,125.95. In the second character string, by
contrast, the dot functions as a period, dividing the word received from the word call.
To help define word delimiters systematically while allowing for contextual variation, Progress
provides eight word delimiter attributes, which you can use in word-break tables. The eight
word delimiter attributes appear in Table 96.
Table 95: Is the Dot a Word Delimiter?
Character String Function of the Dot
Is the Dot a Word
Delimiter?
Balance is $25,125.95 Decimal separator No
Shipment not
received.Call customs
broker
Period at end of sentence. Yes
Table 96: Word Delimiter Attributes (1 of 2)
Word Delimiter
Attribute
Description Default
LETTER Always part of a word. Assigned to all characters
that the current attribute
table defines as letters.
In English, these are the
uppercase characters AZ
and the lowercase characters
az.
DIGIT Always part of a word. Assigned to the characters
09.
Database Access
951
USE_IT Always part of a word. Assigned to the following
characters:
Dollar sign ($)
Percent sign (%)
Number sign (#)
At symbol (@)
Underline (_)
BEFORE_LETTER Part of a word only if
followed by a character with
the LETTER attribute.
Else, treated as a word
delimiter.
BEFORE_DIGIT Treated as part of a word

only if followed by a
character with the DIGIT
attribute.
Assigned to the following
characters:
Period (.)
Comma (,)
Hyphen ()
For example, 12.34 is one
word, but ab.cd is two
words.
BEFORE_LET_DIG Treated as part of a word
only if followed by a
character with the LETTER
or DIGIT attribute.
-
IGNORE Ignored. Assigned to the
apostrophe ().
For example, Johns is
equivalent to Johns.
TERMINATOR Word delimiter. Assigned to all other
characters.
Table 96: Word Delimiter Attributes (2 of 2)
Word Delimiter
Attribute
Description Default
952
Understanding the Syntax of Word-break Tables
Word delimiter attributes form the heart of word break tables, and you specify them using the
following syntax:
symbolic-name
The name of a symbol.
For example: DOLLAR-SIGN
symbol-value
The value of the symbol.
For example: $
NOTE: Although some versions of Progress let you compile word-break tables that omit all
items within the second pair of square brackets, Progress Software Corporation
(PSC) recommends that you always include these items. If the source-code version
of a compiled word-break table lacks these items, and the associated database is not
so large as to make this unfeasible, PSC recommends that you add these items to the
table, recompile the table, reassociate the table with the database, and rebuild the
indexes.
SYNTAX
[ #define symbolic-name symbol-value ] ...
[ Version = 9
Codepage = codepage-name
wordrules-name = wordrules-name
type = table-type
]
word_attr =
{
{ char-literal | hex-value | decimal-value } , word-delimiter-attribute
[ , { char-literal | hex-value | decimal-value }
, word-delimiter-attribute ] ...
};
Database Access
953
codepage-name
The name, not surrounded by quotes, of the code page the word-break table is associated
with. The maximum length is 20 characters.
For example: UTF8
wordrules-name
The name, not surrounded by quotes, of the compiled word-break table. The maximum
length is 20 characters.
For example: utf8sample
table-type
The number 2.
NOTE: Some versions of Progress allow a table type of 1. Although this is still supported,
Progress Software Corporation (PSC) recommends, if feasible, that you change
the table type to 2, recompile the word-break table, reassociate it with the
database, and rebuild the indexes.
char-literal
A character within single quotes or a symbolicname, which represents a character in the
code page.
For example: #
hex-literal
A hexadecimal value or a symbolicname, which represents a character in the code page.
For example:0xAC
decimal-literal
A decimal value or a symbolicname, which represents a character in the code page.
For example: 39
954
word-delimiter-attribute
In what context the character is a word delimiter. You can use one of the following:
LETTER
DIGIT
USE_IT
BEFORE_LETTER
BEFORE_DIGIT
BEFORE_LET_DIG
IGNORE
TERMINATOR
Examples of Word-break Tables
The following is an example of a word-break table for Unicode:
/* a word-break table for Unicode */
#define DOLLAR-SIGN $
Version = 9
Codepage = utf-8
wordrules-name = utf8sample
type = 2
word_attr =
{
., BEFORE_DIGIT,
,, BEFORE-DIGIT,
0x2D, BEFORE_DIGIT,
39, IGNORE,
DOLLAR-SIGN, USE-IT,
%, USE-IT,
#, USE_IT,
@, USE-IT,
_, USE_IT,
};
Database Access
955
As the preceding example illustrates, word-break tables can contain comments delimited as
follows:
For more examples, see the word-break tables that Progress provides in source-code form. They
reside in the DLC/prolang/convmap directory and have the file extension .wbt.
NOTE: Progress supplies a word-break table for each code page it supports.
Compiling Word-break Tables
After you create or modify a word-break table, you must compile it with the PROUTIL utility.
The syntax is as follows:
src-file
The name of the word-break table file to be compiled.
rule-num
A number between 1 and 255 inclusive that identifies this word-break table within your
Progress installation.
The PROUTIL utility names the compiled version of the word-break table proword.rulenum.
For example, if rulenum is 34, PROUTIL names the compiled version proword.34.
/* this is a comment */
Operating
System Syntax
UNIX
Windows
proutil -C wbreak-compiler src-file rule-num
956
Associating Compiled Word-break Tables with Databases
After you compile a word-break table, you must associate the compiled version with a database
using the PROUTIL utility. The syntax is as follows:
database
The name of the database.
rule-num
The value of rulenum you specified when you compiled the word-break table.
To associate the database with the default word-break rules, set rulenum to zero.
NOTE: Setting rulenum to zero associates the database with the default word-break
rules for the current code page. For more information on code pages, see the
Progress Internationalization Guide.
Rebuilding Word Indexes
For word indexing to work as expected, the word-break table Progress uses to write the word
indexes (to add, modify, or delete a record that contains a word index) and the word-break table
Progress uses to read word indexes (to process a query that contains the CONTAINS operator)
must be identical. To ensure this, when you associate the compiled version of a word-break table
with a database, Progress writes cyclical redundancy check (CRC) values from the compiled
word-break table into the database. When you connect to the database, Progress compares the
CRC values in the database to the CRC value in the compiled version of the word-break table.
If they do not match, Progress displays an error message and terminates the connection attempt.
If a connection attempt fails and you want to avoid rebuilding the indexes, you can try
associating the database with the default word-break rules.
NOTE: This might invalidate the word indexes and require you to rebuild them anyway.
Operating
System Syntax
UNIX
Windows
proutil database -C word-rules rule-num
Database Access
957
To rebuild the indexes, you can use the PROUTIL utility with the IDXBUILD or IDXFIX
qualifier.
The syntax of PROUTIL with the IDXBUILD qualifier is:
The syntax of PROUTIL with the IDXFIX qualifier is:
For more information on the PROUTIL utility, see the Progress Database Administration
Guide and Reference.
Providing Access to the Compiled Word-break Table
To allow database servers and shared-memory clients to access the compiled version of the
word-break table, it must reside either in the Progress installation directory or in the location
pointed to by the environment variable PROWDrulenum. For example, if the compiled
word-break table has the name proword.34 and resides in the DLC/mydir/mysubdir directory,
set the environment variable PROWD34 to DLC/mydir/mysubdir/proword.34.
NOTE: Although the name of the compiled version of the word-break table has a dot, the
name of the corresponding environment variable does not.
Operating
System Syntax
UNIX
Windows
proutil db-name -C idxbuild [ all ]
[ -T dir-name ] [ -TB blocksize ]
[ -TM n ] [ -B n ]
Operating
System Syntax
UNIX
Windows
proutil db-name -C idxfix
958
9.11.4 Writing Queries Using the CONTAINS Operator
Once you associate a compiled word-break table with a database that has word indexes, if
necessary, populate the database and rebuild the word indexes. You can then write queries that
use the CONTAINS operator.
Syntax of the CONTAINS Operator of the WHERE Option
The CONTAINS operator has the following syntax in the WHERE option of the record phrase:
field
A field or array of type CHARACTER that participates in a word index.
string-expression
An expression of type CHARACTER that represents possible contents of field.
The syntax of stringexpression is as follows:
word
The word to search for.
The ampersand (&) represents logical AND, while the vertical bar (|), the exclamation
point (!), and the caret (^) represent logical OR. AND limits your search to records that
contain all words you specify, while OR enlarges your search to include any word you
specify. You can combine ANDs and ORs within stringexpression . You can also group
items with parentheses to create complex search conditions.
You can use a wild card on the end of a string. For example, the string sales* represents
sales, saleswoman, salesman, salesperson, and similar strings.
You can also define a character variable and assign a value to that variable.
SYNTAX
WHERE field CONTAINS string-expression
SYNTAX
"word [ [ & | | | ! | ^ ] word ] ..."
Database Access
959
Examples of the CONTAINS Operator
Now that you know the syntax of the CONTAINS operator, you can write queries that use it.
The following query, which displays all Item records whose Catdescription field contains the
word hockey, demonstrates the CONTAINS operator in its simplest form:
The following is the equivalent query in SQL-89, which also allows CONTAINS:
A CONTAINS string can contain multiple words connected by the AND operator (AND or &)
and the OR operator (OR, |, or ^), optionally grouped by parentheses. For example:
NOTE: The AND operator takes precedence over the OR operator. To override this default,
use parentheses. Using parentheses can also make the text of a query clearer.
A CONTAINS string containing multiple contiguous words, such as:
is equivalent to a CONTAINS string containing multiple words connected by AND, such as:
If a CONTAINS string contains multiple words, the order of the words is not significant. To
retrieve records in a specific order, use the CONTAINS operator with the MATCHES operator.
The following WHERE clause retrieves records whose comments field contains the words
credit and hold in that order, perhaps with other words in between:
FOR EACH item
WHERE cat-description CONTAINS "hockey":
DISPLAY item.
END.
SELECT * FROM item
WHERE cat-description CONTAINS "hockey".
...CONTAINS "free | gratis | (no & charge)"...
...CONTAINS "credit hold"...
...CONTAINS "credit AND hold"...
...WHERE comments CONTAINS "credit hold"
AND comments MATCHES "*credit*hold*"...
960
Word indexes are case insensitive unless a field participating in the word index is case sensitive.
The following two WHERE clauses are equivalent:
You can combine CONTAINS with other search criteria, as in the following WHERE clause,
which searches for records whose city field is Boston and whose comments field contains the
word credit and either the word hold or watch:
The following example demonstrates the use of a variable with the CONTAINS operator within
the WHERE clause:
...WHERE comments CONTAINS "CREDIT HOLD"...
...WHERE comments CONTAINS "credit hold"...
...WHERE city = "Boston"
AND comments CONTAINS "credit (hold ^ watch)"...
DEFINE VARIABLE search_wrd AS CHARACTER.
ASSIGN search_wrd = "The".
FOR EACH customer WHERE name CONTAINS search_wrd:
END.
Database Access
961
9.11.5 Word Indexing External Documents
To create a word index on an existing document, import the text into a Progress database, then
index the text by line or by paragraph.
Indexing by Line
To index a set of documents by line, you might create a table called line with three fields:
document_name, line_number, and line_text. Define the primary index on document_name and
a word index on line_text. Next, write a text-loading Progress program that reads each
document and creates a line record for each line in the document. To decrease the amount of
storage required by the line table and to normalize the database, you might replace its
document_name field with a document_number field, and create a document table to associate
a document_name with each document_number.
When base documents change, you must update the line index. You can store a document ID as
part of the record for each line. When a document changes, you can delete all lines with that
document ID and reload the document.
The following program queries the line table using the word index:
The example prompts for a string of words, then displays each line that matches the search
criteria.
Indexing by Paragraph
Instead of indexing by line, you can index by paragraph. The technique resembles line indexing,
but the text from a paragraph can be much longer. You can use paragraph indexes the same way
you use line indexes. You can also index by chapter, by page, and by other units of text. The
only difference is how your text-loading program parses the document into character fields.
Otherwise, your word search code, as in the line table example, can be identical.
DEFINE VARIABLE words AS CHAR FORMAT "x(60)"
LABEL "To find document lines, enter search words".
REPEAT:
UPDATE words.
FOR EACH line WHERE line_text CONTAINS words:
DISPLAY line.
END.
END.
962
9.11.6 Word Indexing Non-Progress Databases
With the exception of the Progress/400 DataServer, Progress DataServers do not support word
indexing. To create a word index on text from a non-Progress database accessed by a
DataServer that does not support word indexing, you must write a Progress routine to read
records from the non-Progress database and copy the text into a table in a Progress database.
You might define a Progress table with the fields nonprog_primary_key and nonprog_text.
Define a word index on nonprog_text, then load text and keys from the non-Progress database
into the table. Then, use the word index to find the primary keys for records that contain specific
words.
For more information on the Progress/400 DataServer wording indexing, see the Progress/400
Product Guide.
9.12 Sequences
Sequences are database objects that provide incremental values to an application. They can
generate sequential values within any range of a Progress integer (2,147,483,648 to
2,147,483,647) and with your choice of increment (positive or negative).
You can also define sequences to cycle or terminate when a specified limit is reached. A cycling
sequence restarts after it reaches the specified limit, providing non-unique values for the life of
the sequence. A terminating sequence stops incrementing after it reaches the specified limit,
providing unique values for the life of the sequence as long as you do not explicitly reset it.
Using a sequence, for example, you can generate a unique series of key values automatically.
Progress allows you to guarantee that the key value is unique (for terminating sequences) and
created in a specified order. You can also use a sequence to generate an audit trail that creates
sequential audit records in the same order they are written to the database.
You can also perform the same kinds of operations by using a control table instead of
sequences. A control table is a database table that contains a single record with one or more
fields. Each field holds a piece of control information such as the name of the application, the
company that owns the application, and the last-used value for each unique integer ID in the
database. For example, the control table might have fields that hold the last customer number
used and the last order number used. Each time a new customer record is created, the record is
read from the control table and the last customer number is incremented. This number is then
used in the new customer record.
Database Access
963
The following sections describe how to:
Choose between sequences and control tables for an application.
Define sequences in a database.
Access and increment sequences from the 4GL.
9.12.1 Choosing Between Sequences and Control Tables
Sequences are objects, like fields, that you can create and maintain in any Progress database.
Unlike fields, sequences reside in a separate database block independent of application tables.
Figure 97 shows the basic relationship between database fields and sequences.
Figure 97: Database Fields and Sequences Comparison
Database
Tables
Field
Field
Field
.
.
.
Sequence
Sequence
Sequence
.
.
.
964
Each sequence has a name and a value, similar to a field. But unlike a field, a sequence also has
different schema attributes that determine how the sequence value can change. These include:
Whether the sequence increments or decrements and by what interval
Whether the sequence cycles or terminates
The upper and lower boundaries for sequence values
Progress provides a dedicated set of 4GL functions and statements to access and increment
sequences strictly according to the defined attributes.
Sequences vs. Control Tables
Before Progress Version 7, the only way Progress could generate sequential values was to
maintain integer fields in a table record created specifically for this purpose. This is often done
in a control table, separate from all other application tables.
For example, you might have a control table named syscontrol that contains the field
lastcusnum. This field holds the value of the Custnum field for the last Customer record. The
following code fragment generates a new Customer record with a unique customer number:
Note that access to the syscontrol table must be made within a small transaction to avoid lock
contention problems.
. . .
DEFINE VARIABLE next-cust-num LIKE Customer.Cust-num.
DO FOR syscontrol:
DO TRANSACTION:
FIND FIRST syscontrol EXCLUSIVE-LOCK.
next-cust-num = syscontrol.last-cus-num + 1.
syscontrol.last-cus-num = next-cust-num.
END. /* transaction */
RELEASE syscontrol.
END.
DO TRANSACTION:
CREATE Customer.
Customer.Cust-num = next-cust-num.
DISPLAY Customer.
UPDATE Customer EXCEPT Cust-num.
END. /* transaction */
. . .
Database Access
965
Sequences provide a built-in means for generating incremental values, but they are not suitable
for all applications. In certain situations (described in the following sections), you might need
to use a control table, instead.
Table 97 compares sequences and control tables.
Performance vs. Capabilities
In general, sequences provide a much faster and more automated mechanism to generate
sequential values than control tables. Sequences are faster because their values are all stored
together in a single, table-independent, database block, and they do not participate in
transactions. As a result, the principal limitations of sequences for certain applications include:
Because of transaction independence, sequences do not roll back when transactions are
undone, but maintain their last value for all UNDOs. However, fields defined in control
tables do roll back to their pretransaction values, as long as all updates to control tables
respect transaction boundaries.
You cannot define more than 100 sequence objects at a time in a database; whereas the
number of fields in a control table are limited only by the table size.
Table 97: Comparison of Sequences and Control Tables
Capability Sequences Control Tables
Access speed Fast Slow
Transaction independent Yes No
Guaranteed order Yes No
Auto initializing Yes No
Auto cycling Yes No
Bounds checking Yes No
Database limit 100 Field limit
966
Transaction Independence
Transaction independence guarantees that each subsequent sequence value is incremented
(positively or negatively) beyond its previous value, but does not guarantee the extent of the
increment. In other words, with sequences you can have incremental gaps in the sequential
values actually used in your application. These gaps result when sequences are incremented
during a transaction that is subsequently undone, leaving the sequences set to their latest values.
If the transaction restarts, it uses these latest values, not those generated for the previously
undone transaction. Figure 98 shows how two overlapping transactions with rollback can
create records and commit consecutive sequence values with gaps.
Figure 98: Sequences and Overlapping Transactions
Both transactions start out with the sequence set to 1, which has already been used in the
database. Transaction T1 increments the sequence first, assigns, and then rolls back leaving the
sequence value at 2. Then transaction T2 increments, assigns, and commits the sequence value
3 to a database field. Transaction T1 then increments, assigns, and rolls back a second time,
leaving the sequence value at 4. Finally, transaction T1 increments, assigns, and commits the
sequence value 5 to the same database field in a different record. Thus, the sequence values 2
and 4 are skipped and never used in the database. All subsequent transactions increment and
commit sequence values greater than 5.
NOTE: Transaction independence is provided for standard sequence increment/decrement
operations, but not for operations that set the sequence value directly. Setting the
value directly is a special operation intended only for maintenance purposes. For
more information, see the Using the CURRENTVALUE Statement section.
Time
Sequence Value (S)
Transaction (T2)
Transaction (T1)
1 2 3 4 5
S + 1 Commit 3
S + 1 Rollback S + 1 Rollback S + 1 Commit 5
Database Access
967
Control tables, however, obey the same transaction rules as any other table, and can ensure that
their field values are reset for undone transactions. If it is essential to generate sequence values
without incremental gaps, you must use a control table rather than a sequence.
Storage Limits
If you need to maintain more than 100 sequence objects at a time, you must either add another
database to define more sequences or use a control table to generate incremental values in your
application. The number of incremental fields you can maintain in a control table is limited only
by the number of integer fields you can store in the table.
9.12.2 Creating and Maintaining Sequences
You can create and maintain sequence definitions in a database using Progresss Data
Dictionary. Progress stores all sequence values together in a single database block, and stores
sequence names and their remaining attributes in a metaschema table named _Sequence.
For information on defining, editing, or deleting sequences in your database, see the Progress
Basic Development Tools (Character only) manual and, in graphical interfaces, the on-line help
for the Progress Data Dictionary.
For information on using sequences in the 4GL, see the Accessing and Incrementing
Sequences section in this chapter.
Providing Sequence Security
You can restrict sequence access by assigning user privileges to the _Sequence metaschema
table. The CanRead privilege grants users permission to read the current value of a sequence
with the CURRENTVALUE function or to increment and read the next value of the sequence
with the NEXTVALUE function. The CanWrite privilege grants users permission to change
the current value of a sequence with the CURRENTVALUE statement. Any user privileges
assigned to the _Sequence metaschema table apply to all sequences defined in the database.
For more information on providing security to a database table, see the Progress Database
Administration Guide and Reference.
Dumping and Loading Sequences
You can dump and load sequence definitions and values using the Database Administration
tool. Select the Database Administration item from the Tools menu of the ADE Desktop. For
more information on dumping and loading sequences, see the Progress Database
968
9.12.3 Accessing and Incrementing Sequences
Figure 98 lists Progress statements and functions you can use to access and increment
sequence values from the 4GL.
Whenever a CURRENTVALUE statement or NEXTVALUE function changes the value of
a sequence, the new value persists in the database where the sequence is defined until it is
changed again, or the sequence is deleted from the database.
The sequence statements and functions have the following syntax:
sequence
An identifier that specifies the name of a sequence defined in the Data Dictionary. Note
that a sequence can have the same name as a database field, but they are distinct entities.
logical-dbname
An identifier that specifies the logical name of the database in which the sequence is
defined. The database must be connected. You can omit this parameter only if you have a
single database connected. Otherwise, you must specify the database in which the
sequence is defined.
Table 98: Sequence Statements and Functions
Statement or Function Description
CURRENTVALUE function Returns the current value of a sequence.
NEXTVALUE function Increments and returns the incremented value for a
sequence.
CURRENTVALUE statement Sets a new current value for a sequence.
SYNTAX
CURRENT-VALUE
( sequence [ , logical-dbname ] ) [ = expression ]
SYNTAX
NEXT-VALUE
( sequence [ , logical-dbname ] )
Database Access
969
expression
An expression that evaluates to an integer value. The CURRENTVALUE statement
assigns the value of expression to the specified sequence. The value of expression must be
within the range defined for the specified sequence.
In general, use the CURRENTVALUE and NEXTVALUE functions for mission-critical
applications that depend on access to reliable and orderly sequence values. Use the
CURRENTVALUE statement only for database maintenance and initialization, primarily
during the development cycle.
Using the CURRENTVALUE Function
Use the CURRENTVALUE function in any integer expression to retrieve the current value of
a sequence without incrementing it. The current value of a sequence can be any one of the
following:
The Initial value specified in the Dictionary
The last value set with either the CURRENTVALUE statement or the NEXTVALUE
function
The following example gets the the most recent customer number in the default database
(maintained by the custnum sequence), and displays each order record for that customer:
Using the NEXTVALUE Function
Use the NEXTVALUE function to increment a sequence by its defined positive or negative
increment value. If the sequence cycles and NEXTVALUE increments it beyond its Upper or
Lower limit, the function sets and returns the defined Initial value for the sequence. If the
sequence terminates and NEXTVALUE tries to increment it beyond its Upper or Lower limit,
the function returns the unknown value (?) and leaves the sequence value unchanged.
DEFINE VARIABLE currentcust AS INTEGER.
.
.
.
current-cust = CURRENT-VALUE (cust-num).
FOR EACH order WHERE cust-num = current-cust:
DISPLAY order.
.
.
.
970
The following example creates a new customer record with the next available customer number
generated by the cust-num sequence:
Because this example does not check the cust-num sequence for termination, it implies that
cust-num is a cycling sequence. Because it does check for and ignore existing records
containing the generated cust-num value, the example can reuse previously deleted (or
otherwise skipped) customer numbers after the sequence cycles.
Using the CURRENTVALUE Statement
Use the CURRENTVALUE statement to explicitly set a sequence to a new value. You can
assign the defined initial value of a sequence, its upper or lower limit, or any integer value in
between. Trying to set a value outside these bounds causes an error. Note that you cannot assign
the unknown value (?) to a sequence. Unlike the NEXTVALUE function, the
CURRENTVALUE statement always sets a new sequence value in a transaction, starting one,
if necessary.
CAUTION: Avoid using this statement in mission-critical applications. Use of this statement,
especially in a multi-user context, can compromise the referential integrity of your
database. Any database application designed to rely on the orderly values
provided by sequences cannot reliably reset existing database fields according to
potentially unexpected sequence values.
DEFINE VARIABLE input-cust-num AS INTEGER.
input-cust-num = NEXT-VALUE (cust-num, sports).
FIND sports.customer WHERE cust-num = input-cust-num NO-ERROR.
DO WHILE (AVAILABLE customer):
input-cust-num = NEXT-VALUE (cust-num, sports).
FIND sports.customer WHERE cust-num = input-cust-num
NO-ERROR.
END.
CREATE sports.customer.
customer.cust-num = input-cust-num.
UPDATE sports.customer EXCEPT cust-num.
.
.
.
Database Access
971
The purpose of the CURRENTVALUE statement is to maintain a database off-line, under
program control. Note that the Data Dictionary uses this statement when you create a new
sequence to set the initial value. Possible uses include:
Restarting a terminating sequence that has terminated.
Otherwise, resetting a sequence value for a specific test condition.
Keep in mind that all such uses must respect and might require changes to the _Sequence table.
This table contains one record for each sequence defined in the database. Creating a record in
this table automatically allocates and assigns the data storage for a new sequence. Deleting a
record in this table automatically releases the data storage for the specified sequence.
Progress provides fault detection that prevents a sequence from being created with inconsistent
attribute values in the _Sequence table (such as, the minimum value greater than the maximum
value). It also prevents the assignment of a new current value that is inconsistent with the the
corresponding attribute values in the _Sequence table (such as, a current value outside the
minimum and maximum value boundary).
The following code fragment sets a new current value for sequence used for testing.
Progress also uses this statement in the Data Administration tool to load sequence definitions
and values from dump-formatted text files. You can accomplish the same task implemented in
the code fragment above using this tool. For more information, see the Progress Database
Compiling Procedures That Reference Sequences
When compiling procedures that use sequence statements and functions, do not run Progress
with the Time Stamp (-tstamp) startup parameter. All references to CURRENT-VALUE and
NEXTVALUE statements and functions in the r-code depend on CRC calculations made with
the _Sequence metaschema table, and are not available with time stamping. CRC validation is
now the default data consistency option for Progress.
DEFINE VARIABLE SeqValue AS INTEGER.
DO TRANSACTION ON ERROR UNDO, RETRY:
SET SeqValue LABEL "TEST-Stepper Start" WITH SIDE-LABELS.
CURRENT-VALUE(TEST-Stepper) = SeqValue.
END. /* TRANSACTION */
.
.
.
972
Resetting a Terminating Sequence
When a terminating sequence stops at its upper or lower limit, you can reset it by assigning a
valid sequence value to it with the CURRENTVALUE statement. You can also reset a stopped
terminating sequence by changing it to a cycling sequence. The first use of the NEXTVALUE
function for the new cycling sequence resets the sequence to its initial value.
Referencing Sequences Within a WHERE Clause
You cannot invoke sequence functions from within a WHERE clause. This generates a compiler
error, because sequence expressions do not participate in the index resolution and optimization
phase of the Compiler.
If you want to use a sequence value within a WHERE clause, set a variable or field to the
sequence value, and reference the variable or field in your WHERE clause. See the sections that
describe each sequence function for examples.
9.13 Database Trigger Considerations
You can store a databases trigger procedures in an operating system directory or in a Progress
r-code library. There are advantages and disadvantages with each technique of storage.
Typically, when deploying an application, it is advantageous to store your trigger procedures in
an r-code library. When developing the application, it is usually better to store the procedures
in a directory.
The Trigger Location (trig) startup parameter allows you to specify the directory or r-code
library containing your trigger procedures.
9.13.1 Storing Triggers in an Operating System Directory
In a development environment, it is usually a good idea to store trigger procedures in a
directory. In a directory, you can store compiled procedures (.r files) and source procedures (.p
files). You can modify the source code of the procedures as necessary.
Also, you can run uncompiled procedures against any database that has the appropriate schema.
In contrast, if a procedure is precompiled, the r-code stores the logical name of the database you
compiled the procedure against. The precompiled procedure can only run against a database
with the same logical name.
Database Access
973
9.13.2 Storing Triggers in an R-code Library
When deploying your application, it is usually a good idea to place trigger procedures in an
r-code library. This is usually faster than running the procedures from an operating system
directory, even if the procedures are precompiled. However, procedures run from a library must
be precompiled. Moreover, because they are precompiled, they are necessarily associated with
a logical database name. You can only run them against a database connected with the same
logical name.
9.14 Using the RAW Data Type
Progress supports the RAW data type, which lets you manipulate raw data without converting
it in any way.
You can use the RAW data type to:
Define Progress variables in a 4GL procedure
Define fields in a Progress database
Retrieve and manipulate raw data from non-Progress databases
You can use the RAW data type to import nonProgress data that has no parallel Progress data
type. By using the RAW data type statements and functions, Progress allows you to bring data
from any field into your procedure, manipulate it, and write it back to the non-Progress
database. The functions and statements let you define RAW data type variables, write data into
a raw variable, find the integer value of a byte, change the length of a raw variable, and perform
logical operations.
The following procedure demonstrates how to retrieve raw values from the database, how to put
bytes into variables, and how to write raw values back to the database:
/* You must run this procedure against a non-Progress sports database. */
DEFINE VAR r1 AS RAW.
DEFINE VAR i AS INT.
FIND FIRST cust.
r1 = RAW(name).
PUTBYTE(r1,1) = 115.
RAW(name) = r1.
DISPLAY name.
974
This procedure first creates the variable r1 and defines it as a RAW data type. Next, it finds the
first customer in the database (Lift Line Skiing), and with the RAW function, takes the raw
value of the field name, and writes it into the variable r1. The PUTBYTE statement then puts
the character code value of s (115) into the first byte of r1. The RAW statement takes the raw
value of r1 and writes it back to the database. Finally, the procedure displays the customer name.
Thus, Lift Line Skiing has become sift Line Skiing..
The next procedure shows how you can pull bytes from a field:
This procedure finds the customer with the customer number 27, and then finds the character
code value of each letter in the customer name. To do this, it retrieves the bytes from the name
one at a time, then places them into the variable a. The GETBYTE function returns the
unknown value (?) if the byte number you try to retrieve is greater than the length of the
expression from which you are retrieving it. The next procedure demonstrates how you find the
length of a raw value and how to change length of a raw expression:
DEFINE VAR i AS INT.
DEFINE VAR a AS INT.
FIND cust WHERE cust-num = 27.
i = 1.
REPEAT:
a = GETBYTE(RAW(name),i).
DISPLAY a.
IF a = ? THEN LEAVE.
i = i + 1.
END.
DEFINE VAR r3 AS RAW.
FIND FIRST cust.
r3 = RAW(name).
DISPLAY LENGTH(r3) name WITH DOWN. /* length before change */
DOWN.
LENGTH(r3) = 2.
DISPLAY LENGTH(r3) name. /* length after change */
Database Access
975
This procedure simply finds the number of bytes in the name of the first customer in the
database then truncates the number of bytes to two. The procedure first displays 16 because the
customer name Lift Line Skiing contains 16 bytes. (If you are using a C-ISAM dataserver the
procedure displays a larger value because C-ISAM uses fixed-length strings.) It then displays 2
because you truncated the raw value to two bytes.
NOTE: When you use the STRING function to retrieve a raw value as a string, you must
supply a format for the string as the second function argument.
9.15 Multi-database Programming Techniques
Once youve settled on a design and run-time connection technique for your multi-database
application, you can begin programming. The following sections list a variety of programming
techniques and issues to consider as you develop your multi-database application with Progress.
9.15.1 Referencing Tables and Fields
Unique table and field names do not require fully qualified references within application
procedures. In a single database Progress application, references to non-unique field names
require a table prefix to avoid ambiguous field references. Use the following syntax to reference
a non-unique field in a procedure:
The tablename is the name of the database table that contains the field fieldname.
The ability to connect to several databases from a single Progress session introduces the
possibility of non-unique table names and increases the possibility of non-unique field names.
References to non-unique table names within multi-database Progress applications require
database prefixes to avoid ambiguous table references. Ambiguous table and field references
cause compilation failures. Use the following syntax to include a database prefix in a table or
field reference:
The databasename is the logical name (or an alias for a logical name) that represents the
database that contains the table tablename.
SYNTAX
table-name.field-name
SYNTAX
database-name.table-name
database-name.table-name.field-name
976
For example, suppose you are connected to two databases db1 and db2, both of which contain
a table called customer. The following procedure will not compile due to an ambiguous table
reference:
The procedure below uses fully qualified table references to display customer names from both
connected databases (db1 and db2):
Notice that the two references to the name field do not need to be qualified because they appear
within a FOR EACH block that already contain fully qualified table references.
NOTE: When Progress encounters a statement such as DISPLAY X.Y, it first attempts to
process X.Y as a databasename.tablename. If that fails, Progress then attempts
to process X.Y as tablename.fieldname.
FOR EACH customer: /* In db1 or db2 ? */
DISPLAY name.
END.
FOR EACH db1.customer:
DISPLAY name.
END.
FOR EACH db2.customer:
DISPLAY name.
END.
Database Access
977
9.15.2 Positioning Database References in an Application
If possible, isolate database references within your application to help minimize the effects of a
database connection failure on your application. This allows you to use the CONNECTED
function effectively to test for a particular database connection, prior to passing program control
to a subprocedure that accesses that database.
p-mainproc.p
db1proc.p
db2proc.p
Figure 99: Positioning Database References
p-mainproc.p
db1proc.p db2proc.p
.
.
.
db1 reference
.
.
.
.
.
.
db2 reference
.
.
.
IF NOT CONNECTED("db1")
THEN DO:
MESSAGE "CONNECTING db1".
CONNECT db1 -1 NO-ERROR.
END.
IF CONNECTED("db1")
THEN RUN db1proc.p.
ELSE MESSAGE "db1proc.p NOT AVAILABLE".
IF NOT CONNECTED("db2")
THEN DO:
MESSAGE "CONNECTING db2".
CONNECT db2 -1 NO-ERROR.
END.
IF CONNECTED("db2")
THEN RUN db2proc.p.
ELSE MESSAGE "db2proc.p NOT AVAILABLE".
978
Figure 99 shows a main procedure that connects two databases and runs subprocedures,
depending on whether or not a database is connected. If the CONNECT statement in
mainproc.p fails to connect db2, only db2proc.p subprocedure is effected by the database
connection failure. This technique is useful for applications that run subprocedures from a
menu.
Do not reference a database in your application startup procedure, except possibly to connect it.
Remember, you cannot connect to a database and reference a database in the same procedure.
If you reference a database on an auto-connect list within the startup procedure of your
application and the auto-connect fails for that database, the startup procedure does not run.
9.15.3 Using the LIKE option
The Progress LIKE option in a DEFINE VARIABLE statement, DEFINE WORKFILE
statement, DEFINE WORKTABLE, or Format phrase requires that a database is connected.
Use the LIKE option with caution in procedures that do not otherwise access a database.
9.16 Creating Schema Cache Files
When Progress starts a client application, it loads the schema for each database that the
application requires into memory. Ordinarily, Progress reads the schema from the database,
which can be on a remote server. If the network is slow, or the server, itself, is overloaded, this
can increase startup time significantly.
You can shorten client startup time by building and saving a schema cache file on a disk local
to the client. A schema cache file is a machine-portable binary file containing a complete
schema or subschema for a single Progress database. When you start a client application with
local schema cache files, Progress reads the required schema for each database almost
instantaneously from the local disk rather than waiting for network or server traffic.
9.16.1 Building a Schema Cache File
To build a schema cache file, you use the SAVE CACHE statement together with a connected
database. You must first decide whether you need the entire schema cache or only the schema
cache for selected tables of a database. If your application accesses all the tables in the database,
you need the complete cache. Otherwise, you can build a schema cache file for only the tables
that are accessed by your application.
Database Access
979
In general, you build a schema cache file off-line, after making a schema change in the database.
You can do this in the Procedure Editor directly, or you can write a small maintenance
procedure to generate the file.
This is the syntax of the SAVE CACHE statement:
The databasename can be the literal logical name of any Progress database or the
VALUE(expression) option, where expression is a character expression that evaluates to the
database name.
NOTE: For a DataServer, Progress saves the schema cache for the entire schema holder
database. You cannot save the schema cache for a non-Progress database separately.
For more information on schema cache files for DataServers, see your Progress
DataServer guide.
The pathname can be the literal pathname of an operating system file or the
VALUE(expression) option, where expression is a character expression that evaluates to the
pathname.
Saving the Entire Schema Cache
To save the entire schema cache.
1 Connect to the database.
2 Execute the SAVE CACHE statement using the COMPLETE option.
For an example procedure that saves the entire schema cache for one or more databases, see the
SAVE CACHE Statement reference entry in the Progress Language Reference.
SYNTAX
SAVE CACHE { CURRENT | COMPLETE }
database-name TO pathname
980
Saving a Partial Schema Cache for Selected Tables
To save a partial schema cache for selected tables of a database.
1 Connect to the database.
2 Read each table you want to include in the schema cache with a FIND statement.
3 Execute the SAVE CACHE statement using the CURRENT option.
4 If you want to save a different partial schema cache for the same database, disconnect the
database and repeat Steps 1 through 3.
9.16.2 Example Schema Cache File Creation
The following event-driven application allows you to create partial schema cache files for any
combination of tables in the sports database. The main procedure, p-schcs1.p, presents all the
available sports database tables in a multiple selection list and a field to enter a name for the
schema cache file. When you choose the Save to File button, it connects to the sports database,
and calls p-schcs2.p, which reads the selected tables and saves the resulting schema cache file
in the current working directory. The main procedure then disconnects the sports database to
allow new table selections for a different schema cache file.
Database Access
981
p-schcs1.p
DEFINE VARIABLE filen AS CHARACTER FORMAT "x(8)"
LABEL "Schema Cache Name".
DEFINE VARIABLE icnt AS INTEGER.
DEFINE VARIABLE db-table AS CHARACTER LABEL "Select Tables"
VIEW-AS SELECTION-LIST
MULTIPLE NO-DRAG SIZE 32 BY 7
LIST-ITEMS "customer", "invoice", "item", "local-default",
"order", "order-line", "ref-call", "salesrep",
"state".
DEFINE BUTTON bsave LABEL "Save to File".
DEFINE BUTTON bcancel LABEL "Cancel".
DEFINE FRAME SchemaFrame
SPACE(1)
db-table
VALIDATE(db-table <> "" AND db-table <> ?, "You must select a table.")
filen
VALIDATE(filen <> "" AND filen <> ?, "You must enter filename.")
SKIP(1)
SPACE(20) bsave bcancel
WITH TITLE "Save Schema Cache File" SIDE-LABELS SIZE 80 by 11.
ON CHOOSE OF bcancel IN FRAME SchemaFrame QUIT.
ON CHOOSE OF bsave IN FRAME SchemaFrame DO:
ASSIGN filen db-table.
IF NOT filen:VALIDATE() THEN RETURN NO-APPLY.
IF NOT db-table:VALIDATE() THEN RETURN NO-APPLY.
DO WHILE NOT CONNECTED("sports"):
BELL.
PAUSE MESSAGE "When ready to connect the sports database, press
<RETURN>".
CONNECT sports -1 NO-ERROR.
IF NOT CONNECTED("sports") THEN
DO icnt = 1 to ERROR-STATUS:NUM-MESSAGES:
MESSAGE ERROR-STATUS:GET-MESSAGE(icnt).
END.
ELSE
MESSAGE "Sports database connected.".
END.
RUN p-schcs2.p (INPUT db-table, INPUT filen).
DISCONNECT sports NO-ERROR.
END.
ENABLE ALL WITH FRAME SchemaFrame.
WAIT-FOR CHOOSE OF bcancel IN FRAME SchemaFrame.
982
9.16.3 Using a Schema Cache File
You specify the schema cache file for each database of an application using the Schema Cache
File (cache) startup parameter. If the schema cache file for any database is invalid, Progress
displays a message, ignores the file with a warning, and reads the cache from the database.
The user can notify the database administrator or application developer to provide the correct
schema cache file. For more information on using schema cache files, see the Progress Client
Deployment Guide, and for a description of cache, see the Progress Startup Command and
p-schcs2.p
DEFINE INPUT PARAMETER db-table AS CHARACTER.
DEFINE INPUT PARAMETER filen AS CHARACTER.
DEFINE VARIABLE itab AS INTEGER.
Table-Add: DO itab = 1 to NUM-ENTRIES(db-table):
CASE ENTRY(itab, db-table):
WHEN "customer" THEN FIND FIRST customer NO-ERROR.
WHEN "invoice" THEN FIND FIRST invoice NO-ERROR.
WHEN "item" THEN FIND FIRST item NO-ERROR.
WHEN "local-default" THEN FIND FIRST local-default NO-ERROR.
WHEN "order" THEN FIND FIRST order NO-ERROR.
WHEN "order-line" THEN FIND FIRST order-line NO-ERROR.
WHEN "ref-call" THEN FIND FIRST ref-call NO-ERROR.
WHEN "salesrep" THEN FIND FIRST salesrep NO-ERROR.
WHEN "state" THEN FIND FIRST state NO-ERROR.
OTHERWISE LEAVE Table-Add.
END CASE.
END.
SAVE CACHE CURRENT sports to VALUE(filen + ".csh") NO-ERROR.
IF NOT ERROR-STATUS:ERROR THEN
MESSAGE "Saved partial schema cache for the sports database"
"in" filen + ".csh.".
ELSE DO:
BELL.
DO itab = 1 TO ERROR-STATUS:NUM-MESSAGES:
MESSAGE ERROR-STATUS:GET-MESSAGE(itab) VIEW-AS ALERT-BOX.
END.
END.
The time stamp in the database does not match the time stamp in the
cache file: sports.csh (840)
10
Using the Browse Widget
This chapter describes how to design and interact with static browse widgets and the queries
they represent. For information on the dynamic browse and the dynamic query, see the
Creating and Using Dynamic Queries section of Chapter 20, Using Dynamic Widgets.
This chapter covers browse design and programming topics divided into six general areas:
Understanding browse widgets
Defining queries for browse widgets
Defining browse widgets
Programming with browse widgets
Resizable browse widgets
Using browse widgets in character interfaces
NOTE: The first five sections describe the essential features of static browse programming
and browse appearance and functionality on Windows. Occasional notes call out
differences in character interfaces. The last section focuses on the unique features of
browse widgets in character interfaces.
102
10.1 Understanding Browse Widgets
A browse widget is a representation of a query. A query is the list of database records from one
or more tables that match the supplied selection criteria. A browse is an object that displays data
from the query in rows and columns. A row represents the data of a single record. A column
represents all the values of a particular field. A row and column intersection, called a cell,
represents the value of the field (column name) in that particular record. A user can scroll up
and down the rows, and left and right through the columns, as shown below:
The browse widget comes with a broad range of functionality and design options that can
accommodate many different browse uses. For example, the browse can be a read-only index to
database records from which users launch dialog boxes and windows that let them work with
the selected record. The browse can also be a large spread-sheet-like application with in-line
editing, color and font support, calculated fields, and user input validation.
NOTE: Progress does not support fonts in character interfaces.
103
Whether a single browse widget is the center of your application or just one component, the
browse assumes an important role in event-driven database applications. To use browse widgets
effectively, you need to understand default behavior and functionality, as well as how to hook
browse widgets into the rest of your code. This chapter presents the fundamental design and
programming topics related to browse widgets. For a description of all browse functionality,
including attributes and methods not covered here, see the DEFINE BROWSE Statement
reference entry and the Browse Widget reference entry, both in the Progress Language
Reference.
10.2 Defining a Query for a Browse
By default, a query uses SHARELOCKs and it is not scrollable. Scrollable is the ability to
move backward as well as forward in the query. The optimum query for a browse should use
NOLOCKs and be scrollable. When a browse is associated with a query (by way of the
DEFINE BROWSE statement), Progress automatically changes the query to use the NOLOCK
and SCROLLABLE options.
Locking is an important topic with browse widgets. Since the browse widget is a tool for
displaying data from multiple records, you do not want to tie up these records with
SHARELOCKs. Even when you are working with updatable browse widgets, you will find
that NOLOCK is the best choice for the associated query. Functionality covered later in the
chapter describes how to successfully update browse records that start in the NOLOCK state.
Once you define the query, define the browse, and open the query, the browse and the query
become virtually identical. The currently selected row and the results list cursor are in sync and
remain so. When the user manipulates the browse, the user is also performing the same
manipulation on the cursor of the results list. Many programmatic actions performed on the
results list or the browse automatically update the other, although this is not universally true.
(You could say that learning all the subtleties of the browse involves learning what occurs by
default, what you have to manage, and what behaviors you can override.)
As a rule, a query associated with a browse should be used exclusively by that browse. While
you can use GET statements to manipulate the database cursor, the results list, and the
associated buffers, you run the risk of putting the browse out of sync with the query. If you do
mix browse widgets and GET statements with the same query, you will have to use the
REPOSITION statement to manually keep the browse in sync with the query.
104
10.2.1 Using Field Lists
Using field lists with browse widgets can be an important way to speed up your application and
minimize resource overhead. For example, if your application works with three fields from a
database table with 15 fields, your application reads five times more data than it needs. Instead
of reading the whole record in the query, you can use the field list syntax to list the subset of
fields needed by your application. The subset of fields consists of those required by the browse
and those required by the other parts of your application that get data from the buffers associated
with the query.
The code fragment below shows an example of a field list in an OPEN QUERY statement:
For more information on field lists, see Chapter 9, Database Access and the Record phrase
entry in the Progress Language Reference.
10.2.2 Planning for the Size of the Data Set
The number of records in your results list can have a serious impact on the performance of your
browse. You may want to optimize your query definition to take advantage of features that work
well with small and large data sets.
When a query is opened, it does not necessarily build the entire results list immediately. In
Chapter 9, Database Access, there is a detailed discussion about how results lists are
initialized and built. For small data sets, it may be more advantageous to force the query to build
the complete results list with a PRESELECT option. This technique has the added benefit of
giving the scrollbar access to all the records in the query from the time the browse is initialized.
While the results list is being built, the scrollbar represents the range of records currently in the
results list.
If you have a query to a large data set, using the REPOSITION TO ROWID statement may
significantly affect performance. The INDEXEDREPOSITION option of the OPEN QUERY
statement attempts to optimize REPOSITION statements that use ROWID. To accomplish this,
the query essentially starts over. It begins building the results list from the new position, on each
REPOSITION statement. The results list will only be built as much as necessary to satisfy the
REPOSITION statement. This option can dramatically speed up browse repositions. The option
has side effects, however. Because of the new results list, your view of the query can change.
For example, new records entered into the browse will appear in their correct sorted order when
the results list is initialized.
Using the INDEXREPOSITIONED option on a query associated with a multiple-select
browse is legal, but may have too many drawbacks to be useful. When the results list is restarted,
all selected rows in the browse are deselected. Also, the vertical scrollbar thumb is disabled.
OPEN QUERY my-query FOR EACH customer FIELDS (cust-num name credit-limit).
105
Since PRESELECT forces a complete results list to be created and maintained, you cannot use
the INDEXEDREPOSITION option with a PRESELECT query.
10.3 Defining a Browse Widget
This section describes some of the major functionality and style choices that you have when you
define a browse widget, and the issues involved with those choices.
10.3.1 Defining a Read-only Browse
You can browse database records by defining a browse widget for the query and opening the
query. This is known as a read-only browse. Once the user finds and selects a record, your
application uses the selected record, which the associated query puts in the associated buffer or
buffers. The following code example illustrates a simple read-only browse for the customer
table:
p-br01.p
DEFINE QUERY q1 FOR customer SCROLLING.
DEFINE BROWSE b1 QUERY q1 DISPLAY cust-num name credit-limit balance
WITH 10 DOWN TITLE "Update Credit Limits".
DEFINE FRAME f1
b1
WITH SIDE-LABELS ROW 2 CENTERED NO-BOX.
OPEN QUERY q1 FOR EACH customer NO-LOCK.
ENABLE ALL WITH FRAME f1.
106
When you run this example, the following browse appears:
The DOWN option of the DEFINE BROWSE statement tells Progress how many rows to
display. If the TITLE option is not used, then the title bar above the column labels does not
appear.
107
10.3.2 Defining an Updatable Browse
An updatable browse supports in-line editing of data. The code example below shows the syntax
for enabling a single field in the browse for input:
p-br02.p
ENABLE credit-limit WITH 10 DOWN SEPARATORS
TITLE "Update Credit Limits".
DEFINE FRAME f1
b1
108
Notice that the updatable browse has row markers on the left. In a read-only browse, clicking
anywhere in a row selects the row. In an updatable browse, clicking in a row is interpreted as a
request to edit that field, if the field is enabled. Otherwise, the row is selected. The normal way
to select rows in an updatable browse is to select row markers. (Note that row markers can also
be turned off programmatically with the NOROWMARKERS option of the DEFINE
BROWSE statement.)
NOTE: In character interfaces, a key sequence (ESCR) toggles between two modes, to select
rows or edit cells. By default, the selected row is the highlighted row that you change
with CURSORDOWN and CURSORUP. Character row markers appear as an asterisk
(*).
An instance of a field in a row (the intersection of a row and column) is called a browse cell. An
updatable browse cell behaves in much the same manner as a fill-in field. Tabbing or clicking
moves the user from one updatable cell to the next.
NOTE: In character interfaces, the EDITORTAB and BACKTAB key functions (usually
CTRLG and CTRLU) tab from cell to cell.
One very important fact to remember is that a read-only browse cannot be enabled, or
turned on, by the programmer after it has been defined. If you expect to need any of the
capabilities of the updatable browser, enable the appropriate fields in the definition and then use
the READONLY attribute to temporarily turn them off.
The SEPARATORS option provides dividers between columns and rows. Using separators with
an updatable browse makes the browse look more like a spreadsheet, which might suggest that
it has inline editing capability to the user.
NOTE: The difference in behavior between read-only and updatable multiple-select browse
widgets represents a commitment to backward compatibility on one hand and a
commitment to supporting native standards on the other.
109
10.3.3 Defining a Single- or Multiple-select Browse
A browse can support single and multiple selections. By default, a browse is single select. The
MULTIPLE option sets up a multiple-select browse. Multiple selection allows you to select any
combination of rows from the browse, which you can then access using the appropriate browse
attributes and methods.
In a multiple-select read-only browse, a user clicks each row to select it. Selecting a second row
does not deselect the previous row. In a multiple-select updatable browse, there are two ways
to select multiple records. First, a user can click on one row marker, hold down the mouse button
and drag to select multiple contiguous rows. Second, a user can hold down the CTRL key and
click on any row marker to toggle its selection state. Rows selected in this manner do not have
to be contiguous. Clicking a row marker without holding down CTRL selects that row and
deselects all other selected rows. Note also, that the CTRL click feature only operates on row
markers, not on disabled columns in updatable browse widgets.
NOTE: For a multiple-select browse in character interfaces, selection of each row is toggled
by the space bar. The close angle bracket (>) indicates each selected row. The same
technique applies to both read-only and updatable multiple-select browse widgets.
For a multiple-select browse, the concepts of focus and selection separate. Selection indicates
that the user has selected a record. There can be many selected records. The last selected record
is in the one in the record buffer. Focus indicates that the record has input focus. There can be
only one focused row, and it might or might not be a selected row. In a single-select browse,
selection and focus are one and the same.
NOTE: When a browse is initialized, the buffer contains the first record in the query, since
no record has been selected by the user. To keep the browse in sync with the query,
the buffer contains the first record in the browse viewport while there is no selected
record.
1010
Note that an updatable browse can only have one selected row when it is in edit mode. So, if the
user selects five rows and then an updatable cell, the four rows that do not contain the active cell
are deselected. The code example below shows a simple multiple-select browse:
p-br03.p
ENABLE credit-limit WITH 10 DOWN SEPARATORS MULTIPLE
DEFINE FRAME f1
b1
1011
Browse Selection and Query Interaction
A browse can support either a single selection or multiple selections. The last selected row of
the browse always becomes the current row of the query. In a multiple-select browse, if you
deselect the current row, the query is repositioned to the currently selected row that was last
selected. If no rows are selected, the query is repositioned to the first record in the viewport.
Table 101 summarizes how actions on the browse affect the associated query.
Using the GET statement to navigate within the results list of the query has no effect on the
browse. However, the REPOSITION statement does update the current position of the browse.
If you use GET statements for a query on which a browse is defined, you should use the
REPOSITION statement to keep the browse synchronized with the query. Also, when you open
or reopen the query with the OPEN QUERY statement, the browse is positioned to the first
record.
Table 101: Browse and Query Interaction
Browse Action Effect on Query
Vertical keyboard
navigation
Moves results list cursor for single-select browse widgets.
Select row Put record(s) for that row into the record buffer(s).
Deselect current row If other records are selected in the browse, put record(s) for
the most recently selected of those rows into the record
buffer(s). Otherwise, reposition to the first row in the
viewport.
Deselect non-current row None.
1012
10.3.4 Using Calculated Fields
A browse widget can show a calculated result of browse fields as a separate column. This is
accomplished by adding the expression to the DEFINE BROWSE statement. All valid browse
format phrase options are legal extensions to the expression (for example, a LABEL option).
When the browse is opened, the calculated field is displayed for each row.
For updatable browse widgets, however, you need to refresh the calculation if one of the fields
in the expression changes. The browse will display the appropriate calculations only when the
query refreshes the data. It is more appropriate to programmatically refresh the calculated data
when the user finishes editing the affected row. To accomplish this, use a base field as a
placeholder for the expression. You then can reference the calculation and refresh the result as
needed.
The code example below sets up a calculated field using a base field in the browse widget. The
LEAVE trigger on the browse column forces a refresh of the calculated data as soon as the user
leaves the browse cell:
NOTE: With calculated fields in the DISPLAY phrase, you cannot use the ENABLE ALL
option, unless you use the EXCEPT option to exclude the calculated field, since
calculated fields cannot be edited.
p-br04.p
DEFINE VARIABLE credit-left AS DECIMAL LABEL "Credit Left".
DEFINE QUERY q1 FOR customer SCROLLING.DEFINE BROWSE b1 QUERY q1 DISPLAY
cust-num name credit-limit balance
(credit-limit - balance) @ credit-left
DEFINE FRAME f1
b1
ON LEAVE OF credit-limit IN BROWSE b1 DO:
DISPLAY (INTEGER(customer.credit-limit:SCREEN-VALUE) - balance)
@ credit-left WITH BROWSE b1.
END.
1013
10.3.5 Sizing a Browse and Browse Columns
Normally, the browse calculates its size based on the column width of each field and the number
of display rows requested with the DOWN option. If the resultant browse is too big for the
frame, Progress displays an error message at compile time.
Use the DOWN option to specify the number of rows to display and the WIDTH option to
specify the width of the browse. If the total column width is wider than the specified browse
width, the browse displays a horizontal scrollbar to access the columns that dont display
initially, and you avoid the compilation error.
NOTE: In character interfaces, there is no horizontal scrollbar for a wide browse, but you can
scroll the browse one column at a time, using CURSORLEFT and CURSORRIGHT.
The horizontal scrollbar can work in two different ways. By default, the browse scrolls whole
columns in and out of the viewport. To change this behavior to pixel scrolling, specify the
NOCOLUMNSCROLLING option of the DEFINE BROWSE statement or set the
COLUMNSCROLLING attribute to NO.
1014
You can also use the SIZE phrase to set an absolute outer size of the browse in pixel or character
units and Progress will determine how many rows and columns can be displayed. (Note that the
User Interface Builder uses the SIZE phrase.)
The browse also supports a column WIDTH option. Use this option to set the width of
individual columns. When a column WIDTH option sets the width of an updatable column
smaller than the size specified by the FORMAT string, the browse cell will scroll to
accommodate extra input up to the size specified by FORMAT.
The example below uses the WIDTH option on each column to set the desired column width
and the WIDTH option with the DOWN option to size the browse as a whole:
p-br05.p
DEFINE BROWSE b1 QUERY q1 DISPLAY cust-num WIDTH 10 name WIDTH 23
credit-limit WIDTH 15 balance WIDTH 15
(credit-limit - balance) @ credit-left WIDTH 15
ENABLE credit-limit WITH 10 DOWN WIDTH 70 SEPARATORS
DEFINE FRAME f1
b1
1015
10.3.6 Searching Columns (Windows Only)
When a read-only browse has focus, typing any printable key (an alphanumeric character),
forces Progress to reposition the browse to the first row where the first character of the first
browse column matches the typed character. Thus, the read-only browse allows searching, but
based only on the data in the first column. If the browse finds no match, it wraps to the top of
the column and continues searching.
In an updatable browse, the user can select the column that will be the basis of the character
search. First, the user clicks a column label. The column label depresses. Typing any printable
key searches for the first row in that column that matches and Progress focuses that row.
Column searches also wrap to the top if necessary.
NOTE: A column search on a browse associated with a query with the
INDEXEDREPOSITION option does not wrap to the top of the column if it cannot
find a record to satisfy the search. This behavior is a side effect of the reposition
optimization. To work around this, you can apply HOME to the query before starting
the search.
1016
There are two ways to extend this basic functionality. First, you can configure an updatable
browse to look like a read-only browse. This technique gives you selectable columns and
searching on those columns. Second, you can use the STARTSEARCH and ENDSEARCH
events to trap the beginning and end of search mode. You can use this functionality to write your
own search routines. For example, you can perform incremental searches using multiple keys.
Implementing Column-Searching on a Read-Only Browse
The column-searching feature is exclusive to the updatable browse. The read-only browse can
do one-character deep searches on the initial column of the browse. You can work around this
by defining your browse with one field enabled for input and the NOROWMARKERS option
specified. After the definition, disable the enabled column by using the READONLY attribute.
This provides an updatable browse that looks like a read-only browse. However, the updatable
browse retains the ability for the user to select individual columns and perform searches on
them.
1017
Implementing Incremental Searching
The following code example depicts a multi-character incremental search on the customer name
field. You can modify the basic algorithm to provide this type of search on any column:
p-br06.p (1 of 2)
(credit-limit - balance) @ credit-left ENABLE credit-limit
WITH 10 DOWN SEPARATORS TITLE "Update Credit Limits".
DEFINE VARIABLE method-return AS LOGICAL.
DEFINE VARIABLE wh AS WIDGET-HANDLE.
DEFINE VARIABLE lblflag AS LOGICAL.
DEFINE FRAME f1
b1
WITH SIDE-LABELS ROW 2 CENTERED NO-BOX. ON END-SEARCH OF b1 IN FRAME f1
DO:
IF lblflag THEN
wh:LABEL = "Name".
lblflag = FALSE.
END.
ON START-SEARCH OF b1 IN FRAME f1
DO:
wh = b1:CURRENT-COLUMN.
IF wh:LABEL = "name" THEN DO:
lblflag = TRUE.
wh:label = "SEARCHING...".
MESSAGE "Incremental Search?" VIEW-AS ALERT-BOX QUESTION
BUTTONS YES-NO-CANCEL TITLE "Search Mode"
UPDATE answ AS LOGICAL.
CASE answ:
WHEN TRUE THEN DO:
/* SETTING REPOSITIONED ROW */
method-return = b1:SET-REPOSITIONED-ROW(3,"CONDITIONAL").
RUN inc-src.
RETURN.
END.
WHEN FALSE THEN DO:
MESSAGE "Search mode defaults to the first character."
VIEW-AS ALERT-BOX INFORMATION BUTTONS OK.
RETURN NO-APPLY.
END.
OTHERWISE APPLY "END-SEARCH" TO SELF.
END CASE.
END.
END.
1018
OPEN QUERY q1 FOR EACH customer NO-LOCK BY customer.name.
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.PROCEDURE inc-src: DEFINE VARIABLE
curr-record AS RECID.
DEFINE VARIABLE initial-str AS CHARACTER.APPLY "START-SEARCH" TO BROWSE b1.ON
ANY-PRINTABLE OF b1 IN FRAME f1
DO:
ASSIGN curr-record = RECID(customer)
initial-str = initial-str + LAST-EVENT:LABEL.
match-string:
DO ON ERROR UNDO match-string, LEAVE match-string:
IF RETRY THEN
initial-str = LAST-EVENT:LABEL.
FIND NEXT customer WHERE customer.name BEGINS initial-str
USE-INDEX name NO-LOCK NO-ERROR
IF AVAILABLE customer THEN
curr-record = RECID(customer).
ELSE IF RETRY THEN
DO:
initial-str = "".
BELL.
END.
ELSE
UNDO match-string, RETRY match-string.
END.
REPOSITION q1 TO RECID curr-record.
END. ON VALUE-CHANGED OF b1 IN FRAME f1
DO:
initial-str = "".
END.
WAIT-FOR "END-SEARCH" OF BROWSE b1.
APPLY "ENTRY" TO name IN BROWSE b1.
END PROCEDURE.
p-br06.p (2 of 2)
1019
The screen below shows what happens when you choose the Name column:
In brief, the STARTSEARCH trigger traps the user action and presents the user with choices.
This is good for demonstration purposes, but in practice, you may want your custom search
behavior to override the default behavior.
If the user chooses Yes at the Incremental Search alert box, then the trigger enables search
mode. The search mode is instantiated and maintained entirely by the internal procedure,
incsrc. This procedure executes a trigger when any printable key is typed. While the code can
build up a valid search string, it keeps going. So, if the user types B L U E, the procedure finds
Blue Line Hockey. As soon as the procedure encounters a character that creates a string it cant
match, it assumes it is starting a new search. So if the User types B L U E A, the procedure
focuses Blue Line Hockey, but discards the string and moves to ABC Mountain Bikes when it
encounters the A.
Another way to implement multiple character searches is to provide the user with a Search
button. The Search button would simply apply STARTSEARCH to the correct column, and
the STARTSEARCH trigger and internal procedure would take over.
1020
10.4 Programming with a Browse Widget
The following sections discuss important programming techniques involving browse widgets.
10.4.1 Browse Events
This section covers:
Basic events
Row events
Column events
Basic Events
The basic browse events include:
VALUECHANGED event occurs each time the user selects or deselects a row.
HOME event repositions the browse to the beginning query list.
END event repositions the browse to the end of the query list.
DEFAULTACTION event occurs when you press RETURN or ENTER or when you
double-click a row. DEFAULTACTION also has the side effect of selecting the row that
is currently highlighted.
The SCROLLNOTIFY event occurs when the user adjusts the scrollbar.
Typically, you use the VALUECHANGED and DEFAULTACTION events to link your
browse to other parts of your application, in the code example below, both events are used to
handle displaying data that is not ideally suited for display in the browse. In this case, a
supplemental editor widget is used to display the lengthy text strings found in the customer
comments field.
The trigger on VALUECHANGED refreshes the data in the comments editor as you navigate
through the browse. This type of trigger is often used to keep related data in the same frame or
window in sync with a browse.
1021
The trigger on DEFAULTACTION displays the comments editor in a dialog box that pops up
when you double-click a browse row. One typical use of DEFAULTACTION triggers is to
display a supplementary view of data related to the record, as the following code sample
demonstrates:
p-br07.p
(credit-limit - balance) @ credit-left
DEFINE BUTTON b-ok LABEL "OK" SIZE 20 BY 1.
DEFINE FRAME f1
b1 skip(.5)
customer.comments VIEW-AS EDITOR INNER-LINES 3
INNER-CHARS 62
DEFINE FRAME f2
customer.comments NO-LABEL VIEW-AS EDITOR INNER-LINES 3
INNER-CHARS 62 SKIP(.5)
b-ok to 42 SKIP(.5)
WITH SIDE-LABELS ROW 2 CENTERED
VIEW-AS DIALOG-BOX TITLE "Comments".
ON VALUE-CHANGED OF b1
DO:
DISPLAY customer.comments WITH FRAME f1.
END.
ON DEFAULT-ACTION OF b1
DO:
ASSIGN customer.comments:READ-ONLY IN FRAME f2 = TRUE.
DISPLAY customer.comments WITH FRAME f2.
ENABLE ALL WITH frame f2.
WAIT-FOR CHOOSE OF b-ok.
HIDE FRAME f2.
END.
ASSIGN customer.comments:READ-ONLY IN FRAME f1 = TRUE.
1022
The following screen shows both ways that the comments field is handled in this example:
One use for the HOME and END events might be to force the results list to be built in a
particular direction when working with INDEXEDREPOSITION queries.
The SCROLLNOTIFY event is important if you plan to overlay other widgets on browse cells.
SCROLLNOTIFY gives you the ability to move the overlay widget to keep pace with the
users scrolling. See the Overlaying Widgets on Browse Cells section later in this chapter for
more information on this technique.
1023
Row Events
The browse supports three row-specific events:
ROWENTRY occurs when a user enters edit mode on a selected row.
ROWLEAVE occurs when the user leaves edit mode.
ROWDISPLAY occurs when a row becomes visible in the browse viewport.
You can find examples of how ROWENTRY and ROWLEAVE work in the Updating
Browse Rows and Creating Browse Rows sections later in the chapter.
The ROWDISPLAY event lets you change color and font attributes of a row or individual cells
or to reference field values in the row. On Windows, the ROWDISPLAY event lets you change
the format of a browse-cell (by changing the value of its FORMAT attribute). The
ROWDISPLAY event cannot be used for any other purpose.
For example, you might want color overdue accounts in red. This kind of cell manipulation is
only valid while the cell is in the viewport. For this reason, you need to use ROWDISPLAY
to check each new row as it scrolls into the viewport. The code fragment below shows a sample
trigger:
NOTE:
If you want to use this technique to change the colors of an extent field, you must do
so by directly referencing each member.
In character interfaces, the DCOLOR attribute specifies the color of an individual
cell.
Column Events
The LEAVE and ENTRY events reference the entire browse widget. For example:
ON ROW-DISPLAY OF b1
DO:
IF balance > credit-limit THEN
ASSIGN balance:BGCOLOR IN BROWSE browse1 = white-color
balance:FGCOLOR IN BROWSE browse1 = red-color.
END.
ON ENTRY OF b1 DO:
1024
You can also write triggers for column names. You can use these triggers to change an attribute
of the entire column (change a column background color), or to modify a single cell in that
column. The affected cell is the named column in the focused row. For example:
There are also two events that allow you to interact with search mode. STARTSEARCH
occurs when the user chooses a column label. ENDSEARCH occurs when the user enters edit
mode on a cell or selects a row. See the Searching Columns (Windows Only) section earlier
in this chapter for more information on these events. Note that both of these events can be
applied to columns to force the start and end of search mode.
10.4.2 Refreshing Browse Rows
If you are using a read-only browse and a record is updated through a dialog box or window,
you need a way to refresh the currently focused browse row with the new data. Use the
following statement at the end of the update code to refresh the browse:
See the Using Calculated Fields section earlier in this chapter for information on refreshing
calculated fields.
10.4.3 Repositioning Focus
The browse and the query must remain in sync. At times, you might have to do some
behind-the-scenes manipulation of the results list. To resync, you can use the REPOSITION
statement. The REPOSITION statement:
Moves the database cursor to the specified position
Adjusts the browse viewport to display the new row
To avoid display flashing when doing programmatic repositions, you can set the
REFRESHABLE attribute to FALSE, do the REPOSITION, and then set REFRESHABLE to
TRUE.
The SETREPOSITIONEDROW( ) method gives you control over the position in the
viewport where the browse will display the repositioned row.
ON LEAVE OF customer.credit-limit IN BROWSE b1 DO:
SELF:FONT = bold-font.
END.
SYNTAX
DISPLAY column-name ... WITH BROWSE browse-widget.
1025
The code fragment below demonstrates these techniques:
Note that SETREPOSITIONEDROW( ) is normally set once for the session. You can also
use the GETREPOSITIONEDROW( ) method to find out the current target row for
repositions.
10.4.4 Updating Browse Rows
By default, Progress handles the process of updating data in an updatable browse. Assuming
that the browse starts with the record in NOLOCK state, Progress follows these steps:
On any user action that modifies data in an editable browse cell, Progress re-gets the
record with a SHARELOCK. (No other user can change the data.) If the data has
changed, Progress warns the user and redisplays the row with the new data.
When the user leaves the row and has made changes to the row, Progress starts a
transaction (or subtransaction) and gets the record from the database with
EXCLUSIVELOCK NOWAIT. If no changes were made, Progress does not start a
transaction.
If the GET with EXCLUSIVELOCK is successful, Progress updates the record,
disconnects it (removes the lock), ends the transaction, and downgrades the lock to its
original status.
If the get with EXCLUSIVELOCK fails, Progress backs out the transaction, displays an
error message, keeps the focus on the edited row, and retains the edited data.
method-return = browse1:SET-REPOSITIONED-ROW(3,"CONDITIONAL").
/* Displays the record at row 3 with focus, unless the record
is already in the viewport. In this case, the record receives
focus at its current row. */
.
.
.
ON CHOOSE OF b-find-cust
DO:
FIND FIRST customer WHERE /* your selection criteria */.
ASSIGN temp-rowid = ROWID(customer)
browse1:REFRESHABLE = NO.
REPOSITION query1 TO ROWID temp-rowid.
ASSIGN browse1:REFRESHABLE = YES.
END.
1026
The 4GL programmer also has the option to disable this default behavior and programmatically
commit the changes by way of a trigger on the ROWLEAVE event. First, you must supply the
NOASSIGN option in the DEFINE BROWSE statement.
The following code example shows how to use a ROWLEAVE trigger:
p-br08.p
DEFINE BROWSE b1 QUERY q1 DISPLAY cust-num name credit-limit
ENABLE credit-limit WITH 10 DOWN SEPARATORS NO-ASSIGN
DEFINE FRAME f1
b1
ON ROW-LEAVE OF BROWSE b1 DO:
IF INTEGER(customer.credit-limit:SCREEN-VALUE IN BROWSE b1) > 100000
THEN DO:
MESSAGE "Credit limits over $100,000 need a managers approval."
VIEW-AS ALERT-BOX ERROR BUTTONS OK
TITLE "Invalid Credit Limit".
DISPLAY credit-limit WITH BROWSE b1.
RETURN NO-APPLY.
END.
DO TRANSACTION:
GET CURRENT q1 EXCLUSIVE-LOCK NO-WAIT.
IF CURRENT-CHANGED(customer) THEN DO:
MESSAGE "The record changed while you were working."
VIEW-AS ALERT-BOX ERROR BUTTONS OK TITLE "New Data".
DISPLAY credit-limit WITH BROWSE b1.
RETURN NO-APPLY.
END.
ELSE ASSIGN INPUT BROWSE b1 credit-limit.
END. /* TRANSACTION */
GET CURRENT q1 NO-LOCK.
END.
1027
The ROWLEAVE trigger checks for a special condition where the new data should not be
committed to the database. If it encounters such data, the trigger is canceled without any writes
taking place. If the data is valid, the GET CURRENT statement is used to re-get the current
record with an EXCLUSIVE-LOCK NOWAIT. It also uses the CURRENTCHANGED
function to ensure that another user has not changed the record since the query first retrieved it.
Note that the lock must be downgraded manually at the end of the trigger with another GET
CURRENT statement.
10.4.5 Creating Browse Rows
In an updatable browser, you might want to allow the user to add new records to the database.
Programmatically, this requires three separate steps:
1. Create a blank line in the browse viewport with the INSERTROW() method and populate
it with new data.
NOTE: You can use the INSERTROW() browse method in an empty browser. It places
a new row at the top of the viewport.
2. Use the CREATE statement and ASSIGN statement to update the database.
3. Add a reference to the results list with the CREATERESULTLISTENTRY( ) method.
(This step is only necessary if you do not plan to reopen the query after the update.
However, this method makes reopening the query unnecessary for most applications.)
All three steps are required to create the record and keep the database, query, and browse in
sync. Also, there are several possible side effects to allowing the user to add a record through
an updatable browse. They include placing new records out of order and adding records that do
not match the query. To eliminate these side effects, you can reopen the query after each new
record.
1028
The code example below shows one possible algorithm for creating new records with an
updatable browse:
In this example, the user requests a new record by choosing a button. The button triggers the
INSERTROW( ) browse method. This method takes two possible strings: BEFORE and
AFTER, indicating where to place the new recordbefore or after the current selected row. The
method places a new blank browse row in the browse viewport. The method has no effect on
the database or the results list of the query.
Since you know that you have allowed the user to add new rows, you have to check for them.
A ROWLEAVE trigger provides the perfect vehicle for checking for this special case. Because
the code does not contain the NOASSIGN option of the DEFINE BROWSE statement, the
normal default row assignment occurs for updated existing records.
p-br09.p
DEFINE QUERY q1 FOR item SCROLLING.
DEFINE BROWSE b1 QUERY q1 DISPLAY item-num item-name price
ENABLE item-name price WITH 10 DOWN SEPARATORS
TITLE "Update Inventory".
DEFINE VARIABLE method-status AS LOGICAL.
DEFINE VARIABLE temp-rowid AS ROWID.
DEFINE BUTTON b-new LABEL "Add New Record" SIZE 45 BY 1.5.
DEFINE FRAME f1
b1 skip
b-new
ON CHOOSE OF b-new DO:
method-status = b1:INSERT-ROW("AFTER").
END.
ON ROW-LEAVE OF BROWSE b1 DO:
IF b1:NEW-ROW IN FRAME f1 THEN DO:
DO ON ERROR UNDO, RETURN NO-APPLY:
CREATE item.
ASSIGN item-num = NEXT-VALUE(next-item-num)
INPUT BROWSE b1 item-name price.
method-status = b1:CREATE-RESULT-LIST-ENTRY().
END.
END.
END.
OPEN QUERY q1 FOR EACH item NO-LOCK.
1029
The NEWROW attribute tells you whether the current row is a new one. When you encounter
one, you have to create a new blank database record and populate it with all the necessary data,
which may come exclusively from the browse or from a mixture of sources. In this example, the
item-num is generated by an existing database sequence.
At this point, the browse has correct data, the database has correct data, but the query results list
does not. The CREATERESULTLISTENTRY() method takes care of this task.
The following screen shows a new record being entered into the browse:
1030
10.4.6 Deleting Browse Rows
Deleting a record by way of a browse is a two-step process. When the user indicates a deletion,
you should re-get the records EXCLUSIVELOCK NO-WAIT and then use the DELETE
statement to remove the records from the database. Next, you would use the
DELETESELECTEDROWS( ) (plural) method to delete one or many selected records from
both the browse widget and the query results list. DELETESELECTEDROWS( ) is a newer
and more efficient browse method and supercedes the old technique of using the
DELETESELECTEDROW( ) (singular) and DELETECURRENTROW( ) methods.
The code example below demonstrates an algorithm for deleting many rows from both the
database and the browse. The technique also works for deleting single rows and records:
A button indicates that the user wants to delete the selected rows. Since the record begins with
NOLOCK, you must first re-get the record with EXCLUSIVELOCK NOWAIT. After using
the DELETE statement, to remove the record from the database, the
DELETESELECTEDROWS( ) method updates the query and browse.
p-br11.p
DEFINE BUTTON b-delete LABEL "Delete All Selected Rows".
DEFINE BROWSE b1 QUERY q1 DISPLAY cust-num name ENABLE name
WITH 10 DOWN SEPARATORS MULTIPLE.
DEFINE FRAME f1
b1 SKIP(.5)
b-delete
WITH NO-BOX SIDE-LABELS ROW 2 CENTERED.
ON CHOOSE OF b-delete IN FRAME f1
DO:
DO i = b1:NUM-SELECTED-ROWS TO 1 by -1:
method-return = b1:FETCH-SELECTED-ROW(i).
GET CURRENT q1 EXCLUSIVE-LOCK.
DELETE customer.
END.
method-return = b1:DELETE-SELECTED-ROWS().
END.
OPEN QUERY q1 FOR EACH customer.
ENABLE b1 b-delete WITH FRAME f1.
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW
1031
10.4.7 Locking Columns
You can use the NUMLOCKEDCOLUMNS attribute to prevent one or more browse
columns from scrolling out of the browse viewport when the horizontal scrollbar is used. A
non-horizontal-scrolling column is referred to as a locked column.
Locked columns are always the left-most columns in the browse. In other words, if you set
NUMLOCKEDCOLUMNS to 2, the first two columns listed in the DEFINE BROWSE
statement will be locked. In the example below, the customer number and name never move out
of the browse viewport, no matter which of the remaining fields the user accesses with the
horizontal scrollbar:
p-br12.p
DEFINE BROWSE b1 QUERY q1 DISPLAY cust-num name address address2 city
state postal-code country contact phone sales-rep credit-limit balance
ENABLE ALL WITH 10 DOWN SEPARATORS
TITLE "Update Customer".
DEFINE FRAME f1
b1
WITH SIDE-LABELS AT ROW 2 COLUMN 10 NO-BOX.
ASSIGN b1:NUM-LOCKED-COLUMNS = 2.
1032
10.4.8 Moving Columns
You can use the MOVECOLUMN( ) method to rearrange the columns within a browse. For
example, rather than forcing the user to scroll horizontally to see additional columns, you might
allow them to reorder the columns.
The following example sets up a button that brings the phone column up to the third column
position in the browse from the sixth position:
p-br13.p
DEFINE QUERY q1 FOR customer.
DEFINE BROWSE b1 QUERY q1 DISPLAY cust-num name city
state postal-code phone WITH 10 DOWN WIDTH 70 SEPARATORS.
DEFINE BUTTON b-phone LABEL "Shown Phone Nos.".
DEFINE FRAME f1
b1 SKIP(.5)
b-phone
ON CHOOSE OF b-phone
DO:
method-return = b1:MOVE-COLUMN(6, 3). /* Move the phone column up. */
DISABLE b-phone WITH FRAME f1.
END.
OPEN QUERY q1 FOR EACH customer.
ENABLE b1 b-phone WITH FRAME f1.
1033
When you run this procedure, the following browse appears:
1034
If you choose the button, the phone column moves to the third column, bumping the others back
by one, as the following screen shows:
10.4.9 Overlaying Widgets on Browse Cells
One popular way to extend the functionality of an updatable browse is to overlay an updatable
browse cell with another widget when the user enters the cell to edit it. For example, on ENTRY
of a cell, you could display a combo box or a toggle box. The user selects an entry from the
combo box, or checks the toggle box, and you use those values to update the SCREENVALUE
attribute of the browse cell. The values get committed or undone along with the rest of the row.
NOTE: This technique is especially effective in graphical interfaces.
There are two problems to overcome. The first is in calculating the geometry to let you precisely
position the overlay widget. You do this by adding the X and Y attributes of the browse cell to
the X and Y attributes of the browse and assigning the result to the X and Y attributes of the
overlay widget.
Next, you may need to move the overlay widget if the user accesses the scrollbar. A trigger on
the SCROLLNOTIFY event notifies you when the user scrolls, and you can update the X and
Y positioning accordingly.
1035
The code example below overlays a toggle box on the backorder field of the orderline table of
the sports database.
p-br14.p (1 of 2)
DEFINE VARIABLE wh AS WIDGET-HANDLE.
DEFINE VARIABLE eprice AS DECIMAL.
DEFINE VARIABLE initial-color AS LOGICAL.
DEFINE VARIABLE toggle1 AS LOGICAL LABEL "Check to Back Order"
VIEW-AS TOGGLE-BOX.DEFINE QUERY q1 FOR order-line SCROLLING.
DEFINE BROWSE b1 QUERY q1 DISPLAY order-num backorder line-num item-num
price qty (price * qty) @ eprice COLUMN-LABEL "Extended Price"
ENABLE backorder line-num item-num price qty
WITH 10 DOWN WIDTH 68 SEPARATORS TITLE "Order Detail
Information".DEFINE FRAME f1
b1
toggle1 AT ROW 2 COLUMN 2
WITH THREE-D NO-BOX SIDE-LABELS ROW 2 CENTERED.
ON SCROLL-NOTIFY OF b1 IN FRAME f1
DO:
RUN TOGGLE-PLACEMENT.
END.ON ENTRY OF backorder IN BROWSE b1
DO:
RUN toggle-placement.
END.ON LEAVE OF backorder IN BROWSE b1
DO:
toggle1:VISIBLE IN FRAME f1 = FALSE.
END.ON VALUE-CHANGED OF toggle1 IN FRAME f1
DO:
toggle1:VISIBLE IN FRAME f1 = FALSE.
IF toggle1:CHECKED THEN BACKORDER:SCREEN-VALUE IN BROWSE b1 = "YES".
ELSE BACKORDER:SCREEN-VALUE IN BROWSE b1 = "NO". APPLY "ENTRY" TO
BACKORDER IN BROWSE b1.
END.OPEN QUERY q1 FOR EACH order-line.
ASSIGN toggle1:HIDDEN IN FRAME f1 = TRUE
toggle1:SENSITIVE IN FRAME f1 = TRUE.
ENABLE b1 WITH FRAME f1.
/* Continued on the next page. */
1036
This code also enables the THREED attribute on the parent frame, which provides a better
contrast between the cell and the overlay widget, as the following screen shows:
PROCEDURE toggle-placement:
ASSIGN WH = backorder:HANDLE IN BROWSE b1.
IF wh:X < 0 THEN toggle1:VISIBLE IN FRAME f1 = FALSE.
ELSE toggle1:X IN FRAME f1 = wh:X + b1:X.
IF wh:Y < 0 THEN toggle1:VISIBLE IN FRAME f1 = FALSE.
ELSE toggle1:Y IN FRAME f1 = wh:Y + b1:Y.
IF backorder:SCREEN-VALUE = "" THEN toggle1:CHECKED = FALSE.
ELSE toggle1:SCREEN-VALUE = backorder:SCREEN-VALUE.
IF wh:X >= 0 and wh:Y >= 0 THEN toggle1:VISIBLE IN FRAME f1 = TRUE.
END PROCEDURE.
p-br14.p (2 of 2)
1037
10.4.10 Using Multiple Browse Widgets for Related Tables
This next example shows a multi-table browse (or join) of the orderline and item tables:
The following is the output of this example:
p-br15.p
DEFINE QUERY orders FOR order.
DEFINE BROWSE ord QUERY orders DISPLAY order.cust-num order.order-num
WITH 10 DOWN SEPARATORS.
DEFINE QUERY items FOR order-line, item.
DEFINE BROWSE itm QUERY items
DISPLAY order-line.line-num item.item-name
ENABLE item-name
WITH 10 DOWN SEPARATORS.
DEFINE FRAME f1
ord space(4) itm
WITH NO-BOX SIDE-LABELS ROW 2 CENTERED.ON "VALUE-CHANGED" OF BROWSE ord
DO:
ENABLE itm WITH FRAME f1.
OPEN QUERY items FOR EACH order-line OF order,
EACH item OF order-line.
END.
OPEN QUERY orders FOR EACH order.
ENABLE ord WITH FRAME f1.
APPLY "VALUE-CHANGED" TO BROWSE ord.WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.
1038
Each time you select a row in the ord browse, Progress displays the associated order line
numbers and item descriptions in the itm browse. The itm browse joins the orderline and item
tables.
The APPLY statement causes the order lines for the first order to display before you select a
record.
A one-to-one (orderline item) join is best displayed with a single browse widget, because there
is a single display line for both tables. In a one-to-many join (order and orderline), it is best to
use two separate browse widgets.
10.4.11 Browse Style Options
This section offers a few ideas for changing the look of your browse.
Using Stacked Labels
To use more than one vertical line for your column labels, use the stacked label syntax. Here is
an example:
You must use the COLUMNLABEL option instead of the LABEL option. The exclamation
point character indicates the line breaks.
Justifying Labels
Column labels in the browse are left justified by default. You can use the C, L, and R options
(Center, Left, Right) of the LABEL option to modify the justification of column labels:
Note the colon (:) syntax. To use this option, the justification option has to be attached to the
end of the label option. So, even if you want to use the default labels, you need to re-enter them
here in order to append the justification option.
DEFINE BROWSE b1 QUERY q1 DISPLAY cust-num COLUMN-LABEL "Customer!Number"
name COLUMN-LABEL "Customer!Name" WITH 10 DOWN.
DEFINE BROWSE b1 QUERY q1 DISPLAY cust-num LABEL "Cust. No.":C
name WITH 10 DOWN.
1039
Using Color to Distinguish Updatable Columns
You can make the updatable columns in your browse a different color. For example, you can
make the read-only columns grey with black text and the updatable columns blue with yellow
text. The code fragment that follows assumes you have defined variables to hold the standard
color values:
NOTE: In character interfaces, the COLUMNDCOLOR attribute specifies the column
color.
Using Color and Font to Distinguish Cells
On top of your basic color scheme, you may want individual cells that have key values to
display in a different color or font. For example, you might want to color overdue accounts in
red. This kind of cell manipulation is only valid while the cell is in the viewport. For this reason,
you need to use the special event ROWDISPLAY to check each new row as it is scrolled into
the viewport. See the Browse Events section earlier in this chapter for examples and
implementation notes.
Establishing ToolTip Information
The DEFINE BROWSE statement supports the TOOLTIP option. You can elect to specify
ToolTips, a brief text message string that automatically displays when the mouse pointer pauses
over a browse widget for which a ToolTip value is defined. A ToolTip value can be set for a
variety of field-level widgets. However, they are most commonly defined for button widgets.
For more information on ToolTips and other specific Windows interface design options, see
Chapter 25, Interface Design.
ASSIGN cust-num:COLUMN-BGCOLOR IN BROWSE browse1 = gray-color
cust-num:COLUMN-FGCOLOR IN BROWSE browse1 = black-color
name:COLUMN-BGCOLOR IN BROWSE browse1 = blue-color
name:COLUMN-FGCOLOR IN BROWSE browse1 = yellow-color.
1040
Using a Disabled Updatable Browse as a Read-only Browse
In one sense, the default read-only browse is the precursor to the Version 8 updatable browse.
It might be a good idea to compare the behavior and functionality of a read-only browse with a
disabled updatable browse and decide which is the best standard for you. Using the default
read-only browse guarantees compatibility with Version 7 applications. Using an updatable
browse that has had its enabled columns turned off by way of the READONLY attribute
provides these benefits:
Column searching (Windows only)
Selection behaviors closer to native Windows standards (Windows only)
Row markers
Ability to enable the browse programmatically
10.5 Resizable Browse Widgets
In graphical interfaces, the user and the programmer can:
Resize the browse
Move the browse
Resize a browse-column of a browse
Move a browse-column of a browse
Change the row height of a browse
NOTE: For a complete description of the 4GL elements described in this section, see the
10.5.1 Resizing the Browse
To let the user resize a browse, the programmer sets the browses RESIZABLE and
SELECTABLE attributes to TRUE, as the following code fragment demonstrates:
To resize a browse through direct manipulation, the user clicks on the browse to display the
resize handles, then drags a resize handle as desired.
mybrowse:RESIZABLE = TRUE.
mybrowse:SELECTABLE = TRUE.
1041
To resize a browse programmatically, the programmer sets the browses WIDTHCHARS,
WIDTHPIXELS, HEIGHTCHARS, HEIGHTPIXELS, and DOWN attributes as desired.
The following code fragment programmatically resizes a browse to 50 characters wide by 40
characters high:
10.5.2 Moving the Browse
To let the user move a browse, the programmer sets the browses MOVABLE attribute to
TRUE, as the following code fragment demonstrates:
To move a browse through direct manipulation, the user drags the browse as desired.
To move a browse programmatically, the programmer sets the browses X and Y attributes as
desired.
The following code fragment programmatically moves a browse to the point (50,50) (in pixels)
relative to the parent widget or display:
10.5.3 Resizing the Browse-column
To let the user resize a browse-column, the programmer uses one of the following techniques:
To let the user resize any browse-column of a browse, the programmer sets the browses
COLUMNRESIZABLE attribute to TRUE, as the following code fragment
demonstrates:
ASSIGN mybrowse:WIDTH-CHARS = 50
mybrowse:HEIGHT-CHARS = 40.
mybrowse:MOVABLE = TRUE.
ASSIGN mybrowse:X = 50
mybrowse:Y = 50.
mybrowse:COLUMN-RESIZABLE = TRUE.
1042
To let the user resize a single browse-column of a browse, the programmer sets the
browse-columns RESIZABLE attribute to TRUE, as the following code fragment
demonstrates:
To resize a browse-column through direct manipulation, the user drags a column separator
horizontally as desired.
To resize a browse-column programmatically, the programmer sets the browse-columns
WIDTHCHARS and WIDTHPIXELS attributes as desired.
The following code fragment programmatically changes the width of the Name
browse-column (representing the Name field of the Customer table of the Sports database) to
20 pixels:
10.5.4 Moving the Browse-column
To let the user move the browse-columns of a browse, the programmer uses one of the following
techniques:
To let the user move any browse-column of a browse, the programmer sets the browses
COLUMNMOVABLE attribute to TRUE, as the following code fragment demonstrates:
To let the user move a single browse-column of a browse, the programmer sets the
browse-columns MOVABLE attribute to TRUE, as the following code fragment
demonstrates:
To move a browse-column through direct manipulation, the user drags a column label
horizontally. (If the user drags a column label to either edge of the viewport, Progress scrolls
the viewport.)
NOTE: To move the second browse-column to the left, the user should move the leftmost
browse-column to the right instead, thereby swapping slots.
mybrowsecol:RESIZABLE = TRUE.
customer.name:WIDTH-PIXELS IN BROWSE mybrowse = 20.
mybrowse:COLUMN-MOVABLE = TRUE.
mybrowsecol:MOVABLE = TRUE.
1043
To move a browse-column programmatically, the programmer uses the MOVECOLUMN
method of the browse.
The following code fragment programmatically moves the first browse-column of a browse to
the third position:
10.5.5 Changing the Row Height
To let the user change the row height of a browse, the programmer sets the browses
ROWRESIZABLE attribute to TRUE, as the following code fragment demonstrates:
To change the row height of a browse, the user drags a row separator vertically as desired.
To change the row height programmatically, the programmer sets the browses
ROWHEIGHTCHARS and ROWHEIGHTPIXELS attributes as desired.
The following code fragment programmatically changes the row height to 20 pixels:
10.5.6 Additional Attributes
When the programmer sets up a resizable browse, whether for user or programmatic
manipulation, she can set additional attributes.
User Manipulation
When setting up a browse for user manipulation, the programmer can set the following
attributes:
SEPARATORS attribute of the browse
The SEPARATORS attribute indicates if the browse displays separators between each
row and each column.
SEPARATORFGCOLOR attribute of the browse
The SEPARATORFGCOLOR attribute sets the color of the row and column separators,
if they appear.
mybrowse:MOVE-COLUMN(1,3).
mybrowse:ROW-RESIZABLE = TRUE.
mybrowse:row-height-pixels = 20.
1044
Programmatic Manipulation
When setting up a browse for the programmatic manipulation, the programmer can set the
following attributes:
SEPARATORS attribute of the browse
See above.
SEPARATORFGCOLOR attribute of the browse
See above.
EXPANDABLE attribute of the browse
The EXPANDABLE attribute indicates whether Progress extends the right-most
browse-column to the right edge of the browse, covering any white space that might
appear.
AUTORESIZE attribute of the browse-column
The AUTORESIZE attribute indicates whether Progress automatically resizes the
browse-column if a change occurs in its font or in its labels font or text.
10.5.7 User Manipulation Events
When the user moves or resizes a browse or one of its components, Progress fires one or more
of the following events:
STARTMOVE event
ENDMOVE event
STARTRESIZE event
ENDRESIZE event
STARTROWRESIZE event
ENDROWRESIZE event
SELECTION event
DESELECTION event
1045
These events do not fire when the browse is manipulated programmatically.
The programmer does not have to monitor these events; they appear here only for the
programmers reference. For example, the programmer might want to write trigger code for one
or more of these events.
For more information on these events, see the Events Reference chapter of the Progress
Language Reference.
10.5.8 Code Example
The following program displays a browse that the user can resize and move:
NOTE: The program works in graphical interfaces only.
p-rszbrw.p
/* p-rszbrw.p */
/* demonstrates resizable browse */
/* p-br01.p made resizable, etc. */
WITH 10 DOWN WIDTH 50 TITLE "Resizable Browse".
DEFINE FRAME f1
b1 AT COL 15 ROW 3
WITH SIZE 80 BY 15 SIDE-LABELS ROW 2 CENTERED NO-BOX.
ASSIGN b1:MOVABLE = TRUE
b1:RESIZABLE = TRUE
b1:SELECTABLE = TRUE
b1:ROW-RESIZABLE = TRUE
b1:COLUMN-MOVABLE = TRUE
b1:COLUMN-RESIZABLE = TRUE
b1:SEPARATORS = TRUE
b1:EXPANDABLE = TRUE.
1046
When you run the program and click anywhere except on a separator, column label, or scroll
button, the resize handles appear, as Figure 101 illustrates:
Figure 101: Resizable Browse
10.6 Using Browse Widgets in Character Interfaces
Browse widgets in character interfaces operate in two distinct modes:
Row mode
Edit mode
In row mode, the user can select and change focus among rows, as well as navigate (tab) to
widgets outside the browse. In edit mode, the user can edit and tab between enabled cells within
the browse. A user can only enter edit mode in an updatable browse, but can operate in row
mode in either a read-only or an updatable browse.
1047
10.6.1 Character Browse Modes
Figure 102 and Figure 103 (displayed using procedure p-br03.p) show a character browse in
row mode and edit mode, respectively.
Figure 102: Character Browse in Row Mode
The asterisks (*) are row markers that indicate editable rows in an updatable browse. Row
markers do not appear
In a read-only browse.
In an editable browse defined with the NOROWMARKERS option, which makes the
browse read-only.
In row mode, the highlight indicates the row that has focus and the close angle brackets (>) are
tick marks that indicate selected rows. In a single selection browse, the tick mark follows the
highlight because focus and selection are the same. In a multiple selection browse, focus is
independent of selection, and tick marks indicate the selected rows.
1048
Figure 103: Character Browse in Edit Mode
In edit mode, all rows become deselected except the edited row. The highlight indicates the
edited cell within the edited row. As the user moves from row to row during editing, the tick
mark and highlight both move to indicate the row and cell being edited.
10.6.2 Control Keys
To control operation of a character browse, Progress provides a set of dedicated control keys.
These control keys apply differently in row mode or edit mode. However, in both modes, any
control key that changes (or attempts to change) the selected row fires the VALUECHANGED
event.
These control keys correspond to Progress key functions that you can redefine. On Windows,
you can redefine them in the registry or in an initialization file. On UNIX, you can redefine them
in the PROTERMCAP file. For more information on redefining control key functions, see the
chapter on user interface environments in the Progress Client Deployment Guide.
1049
Table 102 describes the key functions, default key labels, and operation of the row mode
control keys.
Table 102: Row Mode Control Keys (1 of 2)
Key Function
Default
Key Label Description
(Space Bar)
1
" " Fires the VALUECHANGED event. In
multiple selection mode, this also selects and
deselects the row that has focus, alternately
displaying and erasing the tick mark.
CURSORLEFT CURSORLEFT Scrolls the browser widget horizontally one
column to the left.
CURSORRIGHT CURSORRIGHT Scrolls the browser widget horizontally one
column to the right.
CURSORDOWN CURSORDOWN
Moves focus down one row.
1
CURSORUP CURSORUP
Moves focus up one row.
2
END
ESC. Moves focus to the last row in the browse
widget.
2
HOME
ESC, Moves focus to the first row in the browse
widget.
2
PAGEDOWN ESCCURSORDO
WN
Pages down one full page of data.
2
PAGEUP ESCCURSORUP
Pages up one full page of data.
2
REPLACE
ESCR Changes the browser to edit mode, places focus
in the first enabled cell of the currently focused
row, and fires the VALUECHANGED event.
In multiple selection mode, this also selects the
focused row and deselects any other selected
rows. If you specify NOROWMARKERS in
the browse definition or set the
ROWMARKERS attribute to FALSE, REPLACE
has no effect.
1050
Table 103 describes the key functions, default key labels, and operation of the edit mode
control keys.
RETURN RETURN
Fires the DEFAULTACTION event.
TAB TAB
Leaves the browse widget and sets input focus to
the next sibling widget of the browse in the tab
order.
1
Note that Progress has no key function identifier for the space bar. In code, you reference a character string
containing a single space (" ").
2
In single selection mode, this also fires the VALUECHANGED event, because selection follows focus.
Table 103: Edit Mode Control Keys (1 of 2)
Key Function
Default
(Space Bar)
1
" " Enters a space or zeroes numeric data in the
focused cell.
CURSORLEFT CURSORLEFT Moves the cursor one character to the left in the
cell. (Does not leave the cell.)
CURSORRIGHT CURSORRIGHT Moves the cursor one character to the right in the
cell. (Does not leave the cell.)
CURSORDOWN CURSORDOWN Moves focus down to the next cell in the column
and fires the VALUECHANGED event.
CURSORUP CURSORUP Moves focus up to the previous cell in the
column and fires the VALUECHANGED
event.
BACKTAB CTRLU Moves focus to the previous enabled cell in the
browse (right to left; bottom to top).
1
When
focus is on the first cell, BACKTAB does not
function.
Table 102: Row Mode Control Keys (2 of 2)
Key Function
Default
1051
EDITORTAB CTRLG Moves focus to the next enabled cell in the
browse (left to right; top to bottom).
2
When
focus is on the last cell the EDITORTAB does not
function.
END
ESC. Moves focus to the last cell in the current column
and fires the VALUECHANGED event.
HOME
ESC, Moves focus to the first cell in the current
event.
PAGEDOWN ESCCURSORDO
WN
Pages down one full page of data and fires the
VALUECHANGED event.
PAGEUP ESCCURSORUP Pages up one full page of data and fires the
VALUECHANGED event.
REPLACE
ESCR Changes the browser to row mode, with
selection set to the currently focused row.
RETURN RETURN
Moves focus to the next cell in the current
event.
TAB TAB
Leaves the browse widget and sets input focus to
the next sibling widget of the browse in the tab
order.
1
Note that Progress has no key function identifier for the space bar. In code, you reference a character string
containing a single space (" ").
2
If this action changes or attempts to change the selected row, it also fires the VALUECHANGED event.
Table 103: Edit Mode Control Keys (2 of 2)
Key Function
Default
1052
10.6.3 Functional Differences from the Windows Graphical
Browse
The character browse shares most of the same functional capabilities of the Windows graphical
browse, including all methods and most attributes and events. For information on using these
features, see the Chapter 10, Programming with a Browse Widget section.
However, there are differences from the Windows graphical browse in:
Font management
Color management
Row and cell navigation
Font Management
Because there is no font management within character interfaces, all font attributes are inactive
for the character browse.
Color Management
For color terminals, the character browse supports the following attributes to manage its color:
LABELDCOLOR
Specifies the color of a column label (like LABELFGCOLOR for the Windows browse).
COLUMNDCOLOR
Specifies the color of a single column (like COLUMNFGCOLOR for the Windows
browse).
DCOLOR
Specifies the color of an individual cell (like FGCOLOR for the Windows browse). You
can only specify the color of an individual cell as it appears in the view port. For more
information on specifying individual cell color, see the Browse Events section.
1053
COLUMNPFCOLOR
Specifies the color of the enabled (updatable) column with input focus (unsupported for
the Windows browse).
PFCOLOR
Specifies the color of the updatable cell with input focus (handled by default processing
for the Windows browse).
By default, the COLUMNPFCOLOR and PFCOLOR values are both set from the INPUT
color value. On Windows, you can specify this value in the registry or in an initialization file.
On UNIX, you can specify this value in the PROTERMCAP file.
Row and Cell Navigation
Unlike the Windows graphical browse, the character browse does not support column searching
(positioning to a row or cell by typing a character contained in that row or cell).
Unlike the Windows graphical browse, the character browse uses a different set of key functions
to tab between updatable cells than between the browse and other sibling widgets. Tabbing
between cells occurs only in the edit mode of the character browse using the EDITTAB and
BACKTAB key functions.
Tabbing forward from the character browse to a sibling widget occurs in either row mode or edit
mode using the TAB key function. However, tabbing backward from the character browse to a
sibling widget occurs only in row mode using the BACKTAB key function.
For more information on character browse key functions, see the Control Keys section.
1054
11
Database Triggers
A database trigger is a block of 4GL code that executes whenever a specific database event
occurs. A database event is an action performed against a database. For example, when you
write a record to a database, a WRITE event occurs.
Because database triggers execute whenever a database event occurs, they are useful for tasks
such as referential integrity. For example, if you delete a customer record from a database, you
may also want to delete all of the customers order records. The event (deletion of a customer
record) initiates the task (deletion of all associated order records). A database trigger is ideal for
this type of processing, because the same task must always be performed when the specific
event occurs. Other suitable tasks are maintaining database security or writing database audit
trails.
This chapter describes database events and database triggers. It also explains how to implement
trigger-based replication.
112
11.1 Database Events
Database triggers associate a table or field with a database event. When the event occurs, the
trigger executes.
Progress does not provide events for all database actions. For example, although you can dump
database definitions from a database, you cannot write a trigger for a DUMP event, because
Progress does not provide a DUMP event.
However, Progress does provides replication-related triggers in addition to standard triggers for
certain events. Replication-related triggers help you implement database replication.
The database events that Progress supports, along with the standard triggers and
replication-related triggers are:
CREATE When Progress executes a CREATE or INSERT statement for a database
table, Progress creates the record, fires all applicable CREATE triggers, and then fires all
applicable REPLICATIONCREATE triggers.
DELETE When Progress executes a DELETE statement for a database table, Progress
fires all applicable DELETE triggers, fires all applicable REPLICATIONDELETE
triggers, validates the delete, and then performs the delete.
FIND When Progress reads a record in a database table using a FIND or GET statement
or a FOR EACH loop, Progress fires all applicable FIND triggers. FIND triggers fire only
for records that completely satisfy the full search condition, such as a WHERE clause
specifies. FIND triggers do not fire in response to the CANFIND function.
If a FIND trigger fails, Progress behaves as though the record had not met the search
criteria. If the FIND is within a FOR EACH block, Progress simply proceeds to the next
record.
If your application uses the BREAK option of the PRESELECT phrase (which forces
Progress to retrieve two records at a time, so it can find the break), Progress executes the
FIND trigger twice during the first FIND, which is actually two FINDs in succession.
Thereafter, Progress looks one record ahead of the record currently in the record buffer,
and executes the FIND trigger before it places the next record in the buffer.
Database Triggers
113
WRITE When Progress changes the contents of a record and validates it for a database
table, Progress first fires all applicable WRITE triggers and then all applicable
REPLICATIONWRITE triggers. Progress automatically validates a record when
releasing it. You can also use the VALIDATE statement to explicitly validate a record. In
either case, WRITE triggers execute before the validation occurs (so WRITE triggers can
correct values and do more sophisticated validation). Progress might execute the WRITE
triggers for a single record more than once before it writes the record to the database (if it
validates the record more than once and you modify the record between validations).
ASSIGN When Progress updates a field in a database record, Progress fires all
applicable ASSIGN triggers. Unlike the other database events, this trigger monitors a
specific field rather than a table. ASSIGN triggers execute when the contents of the
associated field are modified. The trigger procedure executes at the end of a statement that
assigns a new value to the field and after any necessary re-indexing. If the statement
contains several field assignments (for example, UPDATE name city st), Progress fires
each applicable ASSIGN trigger at the end of the statement. If any trigger fails, Progress
undoes the statement (unless the code specifies NOUNDO).
For more information on replication-related triggers and database replication, see the Progress
Database Administration Guide and Reference.
11.2 Schema and Session Database Triggers
Progress supports two types of database triggers: schema and session. A schema trigger is a .p
procedure that you add, through the Data Dictionary, to the schema of a database. A session
trigger is a section of code that you add to a larger, enclosing procedure.
11.2.1 Differences Between Schema and Session Triggers
Although their syntax is slightly different, schema and session triggers provide similar
functionality. The important difference between them is that schema triggers are independent
procedures; whereas session triggers are contained within a larger procedure. Because of this
difference, schema triggers always execute when a specified event occurs, regardless of what
application initiates the event. Session triggers are defined as part of an application and are only
in effect for that application.
Since session triggers are executed from within an enclosing procedure, they have access to the
frames, widgets, and variables defined in the enclosing procedure. Since schema triggers are
compiled separately from the procedure that initiates their execution, they do not have access to
the procedures frames, widgets, and variables.
114
Use schema triggers for processing that you always want to perform for a specific event. For
example, when an order record is deleted, you may always want to delete the corresponding
order-line records. Use session triggers to perform additional or independent processing when
the event occurs.
Both types of triggers can return ERRORS that cause the associated event to fail. For more
information on the ERROR option of the RETURN statement, see the Progress Language
Reference.
11.2.2 Trigger Interaction
You can define a schema and a session trigger for the same table/event or field/event pair. How
the triggers interact depends on how you define them. Ordinarily, both triggers execute. When
both execute, the session trigger executes first, except for a FIND event. A schema trigger
defined for a FIND executes before a session trigger for the same table. This ensures that any
the schema FIND trigger you define for security reasons applies to the record first. For a
WRITE, DELETE, CREATE, or ASSIGN event, the schema trigger can override the session
trigger. For a FIND event, the schema trigger can preempt the session trigger.
However, the session trigger executes in place of the schema trigger if you do the following:
define the schema trigger as overridable (OVERRIDE=YES)
specify the OVERRIDE option in the session trigger
11.2.3 Schema Triggers
You create schema triggers through the Table or Field Properties dialog box in the Data
Dictionary. When you use the Data Dictionary to define a schema trigger for a table or field, the
trigger is automatically added to the table or fields data definitions. Progress allows you to
define the trigger while you are creating or modifying a table or field. This trigger definition is
stored in a trigger procedure. A trigger procedure is a Progress procedure file that begins with
a trigger header statement. When defining the trigger, you have the option to specify CRC
checking. Thus Progress can verify that the trigger procedure is valid before running it.
When application procedures are compiled against a database, schema triggers are not compiled
into the application r-code, unlike delete or field validation in the Data Dictionary.
For information on using the Data Dictionary to create and delete triggers, see the Progress
Basic Database Tools manual (character only), and for graphical interfaces, the on-line help for
the Data Dictionary. For more information on CRCs and schema triggers, see Appendix A,
R-code Features and Functions.
Database Triggers
115
CREATE, DELETE, and FIND Headers
This is the syntax for the trigger header for a CREATE, DELETE, FIND,
REPLICATIONCREATE, or REPLICATIONDELETE trigger:
References to the record can be made through an automatic buffer defined as part of the trigger
header. Its name is the same as the table name.
WRITE Header
This is the syntax for the trigger header for a WRITE or REPLICATIONWRITE event:
When executing a WRITE trigger, or a REPLICATIONWRITE trigger, Progress makes two
record buffers available to the trigger procedure. The NEW buffer contains the modified record
that is being validated. The OLD buffer contains the most recent version of the record before
the latest set of changes were made (this is the template record if it is a newly created record,
the record from the DB if it is not been validated, or the most recently validated record if it has
been validated). You can modify the contents of the NEW buffer, but the OLD buffer is
read-only. You can compare the contents of these two buffers and perform actions based on the
results.
If you do not specify a NEW buffer, you can use the table name to make any comparisons to the
OLD buffer. If you specify neither OLD or NEW buffers, you may reference the new record via
the automatically created buffer named for the table itself.
You can determine whether the record being written is newly created by using the Progress
NEW function. This function returns TRUE if Progress has not written the record to the
SYNTAX
TRIGGER PROCEDURE FOR
{ FIND
| CREATE
| DELETE
| REPLICATION-CREATE
| REPLICATION-DELETE
} OF table
SYNTAX
TRIGGER PROCEDURE FOR { WRITE | REPLICATION-WRITE } OF table
[ NEW [ BUFFER ] buffer-name1 ]
[ OLD [ BUFFER ] buffer-name2 ]
116
database; otherwise, it returns FALSE. However, the NEW function continues to return TRUE
even if Progress has validated the record but has not written it to the database.
ASSIGN Header
This is the syntax for the trigger header for an ASSIGN event:
You can obtain the newly assigned value from the record buffer if you specify the OF option
(this gives you access to the rest of the record also; whereas NEW and OLD give access to the
fields only), or you can obtain the value from parameter1 if you specify the NEW option. If you
want to access the value stored in the database, use the OLD option. The value of the field before
the assignment is stored in parameter2. You can use the NEW and OLD options to compare the
value being written to the existing value. Progress treats the old value as an input run time
parameter; you can modify it, but this modification has no effect on the triggering procedure.
SYNTAX
TRIGGER PROCEDURE FOR ASSIGN
{ OF table.field
| NEW [ VALUE ]parameter1 { AS data-type | LIKE field
}
[ COLUMN-LABEL label
| FORMAT string
| INITIAL constant
| LABEL string
| NO-UNDO
]
[ OLD [ VALUE ]parameter2 { AS data-type | LIKE field }
]
| FORMAT string
| INITIAL constant
| LABEL string
| NO-UNDO
]
Database Triggers
117
11.2.4 CREATE Schema Trigger Example
The following example CREATE schema trigger procedure uses a sequence called
NextCustNum to generate a unique number for creating a customer record. For more
information on sequences, see Chapter 9, Database Access.
11.2.5 DELETE Schema Trigger Example
This is an example of a DELETE schema trigger procedure:
This DELETE trigger executes whenever you try to delete a customer record. The procedure
finds outstanding invoices of the customer and checks to see if they are paid. If not, the trigger
returns an error and the deletion fails. If so, the trigger deletes all of the customers orders.
The delete trigger executes before Progress evaluates validation criteria, so you can perform any
actions that would allow the delete to pass the validation.
All DELETE triggers execute before Progress actually deletes the record and can therefore refer
to fields in the deleted record.
Even though Progress has not yet deleted the record when the DELETE trigger executes, any
FIND request in the same application for that record fails. Since the record is in the process of
being deleted, Progress treats it as though it is not available.
crcust.p
TRIGGER PROCEDURE FOR Create OF Customer.
/* Automatically Increment Customer Number using Next-Cust-Num Sequence */
ASSIGN Customer.Cust-Num =
NEXT-VALUE(Next-Cust-Num).
p-dltcst.p
TRIGGER PROCEDURE FOR DELETE OF customer.
FOR EACH invoice OF customer:
IF invoice.amount > invoice.total-paid + invoice.adjustment THEN DO:
MESSAGE "Outstanding unpaid invoice exists. Cannot delete.".
RETURN ERROR.
END.
END.
FOR EACH order OF customer:
DELETE order.
END.
118
11.2.6 ASSIGN Schema Trigger Example
ASSIGN triggers execute when you assign a value to a database field (all other database triggers
apply to tables). This is an example of an ASSIGN schema trigger procedure:
This ASSIGN trigger changes the value of the order.custnum field to equal the newly assigned
value of customer.custnum.
NOTE: If you enable a WRITE trigger on a table and an ASSIGN trigger on a field within
that table, the ASSIGN trigger always executes before the WRITE trigger. However,
if the WRITE trigger procedure assigns a value to the trigger field, this re-invokes
the ASSIGN trigger.
11.2.7 REPLICATIONCREATE Schema Trigger Example
REPLICATIONCREATE triggers execute just after Progress fires any applicable CREATE
triggers. Here is an example of one:
This REPLICATIONCREATE trigger captures all the information on a newly-created
Customer record you need in order to replicate the create. For more information, see the section
Implementing Trigger-based Replication.
p-ascust.p
TRIGGER PROCEDURE FOR ASSIGN OF customer.cust-num
OLD VALUE oldcust.
FOR EACH order WHERE order.cust-num = oldcust:
order.cust-num = customer.cust-num.
END.
TRIGGER PROCEDURE FOR REPLICATION-CREATE OF Customer.
CREATE Replication.
ASSIGN
Replication.Entry-Id = NEXT-VALUE(Replication-entry)
Replication.Table-Name = "Customer"
Replication.Task-Id = DBTASKID(LDBNAME(BUFFER Replication))
Replication.Repl-Event = "Create".
RAW-TRANSFER Customer TO Replication.Record.
Database Triggers
119
11.2.8 REPLICATIONDELETE Schema Trigger Example
REPLICATIONDELETE triggers execute just after Progress fires any applicable DELETE
triggers. This is an example of one:
This REPLICATIONDELETE trigger captures all the information on a newly-deleted
Customer record you need in order to replicate the delete. For more information, see the section
Implementing Trigger-based Replication.
11.2.9 REPLICATIONWRITE Schema Trigger Example
REPLICATIONWRITE triggers execute just after Progress fires any applicable DELETE
triggers. Here is an example of one:
This REPLICATIONWRITE trigger captures all the information on a newly-modified
Customer record you need in order to replicate the modify. For more information, see the
section Implementing Trigger-based Replication.
TRIGGER PROCEDURE FOR REPLICATION-DELETE OF Customer.
CREATE Replication.
ASSIGN
Replication.Repl-Event = "Delete"
Replication.Key-Val = STRING(Customer.Cust-num).
/* custwrr.p */
TRIGGER PROCEDURE FOR REPLICATION-WRITE OF Customer OLD BUFFER oldbuf.
CREATE Replication.
ASSIGN
Replication.Repl-Event = "Write"
Replication.Key-Val = STRING(IF NEW(Customer) THEN Customer.Cust-num
ELSE oldbuf.Cust-num).
RAW-TRANSFER Customer TO Replication.Record.
1110
11.3 Implementing Trigger-based Replication
You implement trigger-based replication in Progress by using the 4GL, which provides the
language constructs used to perform data replication. The Data Dictionary Tool also provides
support. It allows defining of schema level replication triggers, as well as storing the replication
procedure name in the Table Properties Window.
Progress also provides logbased replication. For information on logbased replication, see the
Progress Database Administration Guide and Reference.
11.3.1 4GL Support
Table 111 summarizes the Progress core elements supporting replication. For complete
information about statements and functions, see the appropriate entry in the Progress Language
Reference.
Table 111: Replication 4GL Elements
Element Name Type Description
RAW data type Contains the database record to be replicated.
RAWTRANSFER statement Copies a database record buffer to a field
whose data type is RAW, or copies a RAW
field to a buffer.
REPLICATIONCREATE trigger Executes when a record is created.
REPLICATIONDELETE trigger Executes when a record is deleted.
REPLICATIONWRITE trigger Executes when a record is written to the
database.
DISABLE TRIGGERS
FOR LOAD
statement Disables triggers before loading records from
one database to another.
ALLOWREPLICATION phrase Option for the DISABLE TRIGGERS FOR
LOAD statement. It allows replication to
occur.
DBTASKID function Takes a logical database name (or alias) and
returns a unique identifier for the database
identifying a transaction.
Database Triggers
1111
11.3.2 Data Dictionary Support
The Data Dictionary Tool provides support for replication development. The three replication
triggers are included in the standard TRIGGER area of the Table Maintenance screen. In
addition, a Replication field is included in the Table Properties window. This field specifies the
replication procedure for a table. There is no validation or automatic functionality for this field.
It is only a storage area that can be accessed through the Data Dictionary. For more information
about the Data Dictionary, see Progress Basic Development Tools.
11.3.3 Trigger-based Replication Procedure
This section uses a simple one-way replication scheme to illustrate how to implement
replication using Progress 4GL. In the description, the source indicates the database from which
records are being transferred. The target is the database to which records are being transferred.
Depending on the replication scheme, each database (or site) can fill the roles of source and
target. Replication occurs record by record, and the source and target database tables must have
identical field layouts.
Implementation of replication occurs in two stages:
1. Logging changes to tables in a separate log table at the source database.
2. Setting up a process to inspect the log periodically and replicate the data operations on the
appropriate target databases.
1112
Creating the Replication Changes Log
Create a database table to log changes for replication. Follow these steps to create the replication
changes log:
1 Using the Data Dictionary Tool, create a table with the fields shown in Table 112. (For
the remainder of this procedure, this table is called Replog.)
2 Select a table to be replicated.
3 Using the Data Dictionary Tool, register database triggers REPLICATIONCREATE,
REPLICATIONDELETE, and REPLICATIONWRITE for the selected table.
These triggers will execute following the execution of any corresponding CREATE,
DELETE, or WRITE trigger.
Table 112: Replication Changes Log Table Schema
Field Datatype Description
TransactionID integer Represents a unique transaction number. This number
is obtained through the DBTASKID function.
TableName char Identifies the table to be changed.
KeyValue char Represents a unique key value that identifies the
corresponding record in the target database. Applies to
deleted or modified records only.
Event char Indicates that the record was created, deleted, or
modified.
DataRecord RAW Contains the created or modified record.
LogDate date Standard date format.
LogTime char String representing time.
Database Triggers
1113
4 In each of the trigger procedures, do the following to create a record to register the data
change:
Identify the event and table (TableName and Event fields).
Use the DBTASKID function to get the transaction number (TransactionID).
Use the RAWTRANSFER statement to move the record to the DataRecord field.
The following code example shows a generic trigger include file with trigger code:
NOTE: More examples with sample source code can be found in DLC/src/prodict/rplctn.
Replicating the Data
A batch Progress client on the server machine monitors the replication changes log regularly
and carries out replication. The batch Progress client transfers the data to the target database in
a number of ways. In the simplest scenario, the batch client connects to the target database, reads
the log, and executes a RAWTRANSFER statement to transfer the data from the RAW
DataRecord field to the target table on the target database.
If the connection to the target database is not feasible, one alternative is to dump pertinent log
records to a text file and ship the file to the server machine. Then a monitoring batch client
re-creates the log and transfers the data to the target database.
/* Trigger Include File reptrig.i for replication*/
CREATE RepLog
ASSIGN
RepLog.TransactionID = DBTASKID(LDBDNAME(BUFFER {&RepLog}))
RepLog.TableName = {&Table}
RepLog.KeyValue = {&Key}
RepLog.Event = {&Event}
RepLog.LogDate = TODAY
RepLog.LogTime = TIME.
RAW-TRANSFER BUFFER {&Table} TO FIELD RepLog.DataRecord.
TRIGGER PROCEDURE FOR REPLICATION-WRITE OF Customer OLD Buffer oldcust.
{reptrig.i
&Table = Customer
&Key = STRING (oldcust.cust-num)
&Event = WRITE}
1114
RAW-TRANSFER Statement
The RAW-TRANSFER statement allows you to transfer a record from a RAW field to a buffer,
or from a buffer to a RAW field. You can also transfer directly from buffer to buffer. In 4GL
replication, you use RAWTRANSFER to move whole records to the RepLog and to move
records from the log to the target database.
The following code example shows how you can use RAW-TRANSFER:
In this example, the first RAWTRANSFER statement copies a record buffer in the source
database to a variable of type RAW. The second RAWTRANSFER statement copies the RAW
field to the corresponding record buffer in the target database.
This replication could be written more efficiently as a buffer-to-buffer transfer, as shown in the
following example:
For more information, see the entry for the RAWTRANSFER statement in the Progress
Language Reference.
DEFINE VAR rvar AS RAW NO-UNDO.
FOR EACH sourcedb.customer:
RAW-TRANSFER BUFFER sourcedb.customer TO FIELD rvar.
RAW-TRANSFER FIELD rvar TO BUFFER targetdb.customer.
RELEASE targetdb.customer.
END.
FOR EACH sourcedb.customer:
RAW-TRANSFER sourcedb.customer TO targetdb.customer.
RELEASE targetdb.customer.
END.
Database Triggers
1115
DISABLE TRIGGERS FOR LOAD Statement
The DISABLE TRIGGERS FOR LOAD statement allows you to disable database triggers
before replicating data. The following are reasons why you might want to include this statement
in your code before executing the RAWTRANSFER statement:
Replication in Progress is based on the original scope of the transaction. If the database
trigger code in the source database changes data in other tables, those other tables can also
participate in replication. Using DISABLE TRIGGERS FOR LOAD allows the
replication process itself to keep the database records consistent.
In a two-way replication scheme (peer-to-peer model) DISABLE TRIGGERS FOR
LOAD prevents a target database from creating a record of a change generated by the
replication itself. This would result in changes being replicated back and forth between
databases.
ALLOW REPLICATION Phrase
ALLOW-REPLICATION is an optional qualifier on the DISABLE TRIGGERS FOR LOAD
statement. If ALLOW-REPLICATION is indicated, only CREATE, DELETE, ASSIGN, and
WRITE triggers will be disabled. REPLICATION-CREATE, REPLICATION-DELETE, and
REPLICATION-WRITE will execute when necessary.
This qualifier is useful, for example, in a cascading replication, where the target database is
replicated to other targets in a cascading fashion. In this scenario, you might want to disable
standard database triggers but allow replication triggers to fire in the target database table. This
allows you to capture changes in the target replication log table.
1116
Figure 111 shows an example of a cascading scheme. In this example, external data is received
at one database, then replicated in a cascading series to other databases.
Figure 111: Cascading Replication
For more information, see the entry for the DISABLE TRIGGERS FOR LOAD statement in the
Site 1
Site 2
Site 3
New Files
Database Triggers
1117
11.4 Detecting and Capturing Data Collision
Data collision results under the following conditions:
1. User 1 updates a record in database A.
2. User 2 updates the same record in database B.
3. The record is replicated from database A to database B, or from B to A.
Data collision is a crucial issue you must address in replication, particularly in an asynchronous
implementation with peer-to-peer user updating.
To maintain data integrity, data collisions must be addressed transaction by transaction.
Addressing data collision involves detection and resolution. To address data collisions you
might apply the following strategy:
1. Detect collisions by comparing the records in the replication change logs for the respective
sites. When there is a collision, isolate all records associated with the transactions in a
collision log.
2. Analyze records in the collision log. If necessary, determine the differences between
records down to the field level.
3. Resolve the collisions and propagate the results.
11.4.1 Create a Collision Log
The collision log is an important concept in data collision resolution. It is crucial that you isolate
the physical records involved in collisions from the original records, and from the replication
change log. Users are able to change records in the database again before the collisions are
resolved, thereby changing data needed for the resolution. Isolating the data in the physical
records at the point they collided maintains the integrity of your collision resolution process.
To create the collision log, write a procedure that (1) compares the replication change logs
between respective sites to determine changes to identical records, and (2) places these records
in a separate table. This log must contain a sequence number identifying all records involved in
a collision.
NOTE: This sequence number is important. There might be records contained in the
transaction that have not collided, but still need to be included in the log. This is
because replication occurs by transaction. All of the records must be replicated
together, or not at all.
1118
Table 113 shows a sample format for the collision log.
11.4.2 Analyze the Log Records
After you isolate collided records in the collision log, you can use Progress 4GL to analyze
records down to the field level. Follow these steps:
1 Find the records in the collision log that have actually collided (Collision field = Y).
2 Use the RAWTRANSFER statement to move the RAW data fields to expanded buffer
records in a temp table.
3 Use the BUFFERCOMPARE statement to compare the fields within the records.
For more information about these statements, see the Progress Language Reference.
Table 113: Collision Log Table Schema
Field Datatype Description
CollisionID integer A sequence number that identifies all records involved
in a collision. This transaction relates the local and
remote records that collided.
TransactionID integer Identical to the transaction id (see Table 112).
KeyValue char Identical to the value shown in Table 112.
TableName char Identical to the value shown in Table 112.
Event char Identical to the value shown in Table 112.
DataRecord RAW RAW data field shown in Table 112.
CollisionDate date Transaction date shown in Table 112.
CollisionTime char Transaction time shown in Table 112.
Collided logical Logical value that flags whether the record actually
collided with another record. This value is created
when the records are created in this table.
Database Triggers
1119
Resolve Collisions and Propagate Results
After you determine the differences between records that have collided, you can resolve the
collisions in any number of ways. For example:
After determining field differences using BUFFERCOMPARE, you can use Progress
4GL to select the record to replicate based on a hierarchy of key fields, for example, time
or user.
If certain collisions need to be addressed manually by an administrator, you could write
the conflicts to another table for manual resolution or reporting purposes.
The way you resolve collisions depends upon your business requirements. The Progress 4GL
allows you to develop procedures that support all of your requirements.
1120
11.4.3 Replication Process Configuration
After you determine your replication scheme, you need to develop a replication process that is
both reliable and flexible enough to address your business requirements. Figure 112 shows an
example of a replication process configuration, based on the concepts described previously in
this section.
Figure 112: Example Replication Configuration
Figure 112 represents a replication process between a site database on the left (1) where
transactions are shown originating, and the master database on the right (2) where the
transactions are replicated and propagated to all sites. In an actual scheme, more than two sites
might share the functions illustrated.
The large arrows between the boxed items represent the process flow beginning with the data
transaction on the left, and continuing through the replication process on the right. The smaller
arrows represent the flow of data.
Application
Table
Replication
Change Log
Replication
Change Log
Collision
Log
Master Database
T
R
A
N
S
A
C
T
I
O
N
Collision
Manager
Application
Makes Changes
to Data
Standard Write
Trigger Files
Replication Write
Trigger Files
Changed Applied
to Respective
Sites
Replication
Initiated
Both Replication
Changed Logs
Read
Collisions
Written to
Collision log
1
2
Database Triggers
1121
Collision Manager
The collision manager (on the right side in Figure 112) represents a central area where all data
collisions in the database network would be resolved. The collision manager could be located
on a separate machine. The results of data collision resolution could be transferred to the master
database, then propagated to all other sites.
11.4.4 Session Triggers
You define a database session trigger within a Progress procedure. The trigger persists while the
procedure that defined it and any subprocedures are running. A session trigger takes effect when
Progress encounters it at run time. It remains in effect until the defining procedure terminates.
However, if a subprocedure contains another trigger for the same table/event or field/event pair,
the trigger in the subprocedure overrides the original trigger. After the subprocedure returns, the
original trigger goes back into effect.
NOTE: There are no session triggers related to database replication. In other words, Progress
does not support:
A session trigger has access to the defining procedures context, regardless of which procedure
initiates the event that causes it to execute. The session trigger can refer to the defining
procedures variables and other local objects.
ON REPLICATION-WRITE of Customer DO:
/* some action */
END.
/* Progress does not support this */
1122
The following is the syntax for session database triggers.
event
The event parameter is a CREATE, WRITE, DELETE, FIND, or ASSIGN event.
object
The object for table-related events (CREATE, DELETE, FIND, or WRITE) has this
syntax:
The object-reference for a field-related event (ASSIGN) has this syntax:
reference-clause
The reference-clause for a table related event (WRITE triggers only) has this syntax:
Use reference-clause for the WRITE trigger if you want to refer to the values in the
updated record before and after the record changed. The reference-clause uses the same
syntax and rules as the schema database WRITE trigger.
SYNTAX
ON event OF object [ reference-clause ]
[ OVERRIDE ] { trigger-block | REVERT }
SYNTAX
OF table
SYNTAX
OF table.field
SYNTAX
[ NEW [ BUFFER ] buffer1 ] [ OLD [ BUFFER ] buffer2 ]
Database Triggers
1123
The reference clause for a field-related event (ASSIGN) has this syntax:
Session ASSIGN triggers always have access to the tables buffer; the referenceclause
allows access to the old value of the trigger field.
OVERRIDE
The OVERRIDE option causes the session trigger to execute instead of the schema
trigger, if the schema trigger is defined with OVERRIDE=YES. If you attempt to
OVERRIDE a schema trigger defined as OVERRIDE=NO, Progress returns a runtime
error.
trigger-block
A single 4GL statement or a DO block. The trigger block executes whenever the specified
event occurs. The context of the block of 4GL code is similar to that of internal procedures.
In fact, this code executes when the event occurs, almost as if it were an internal procedure.
(See Chapter 3, Block Properties, for information on internal procedures.)
REVERT
The REVERT option cancels the trigger for the given event/table or event/field pair and
reactivates any previously defined trigger for that event/object pair defined in a parent
procedure. If no previously defined trigger exists, the trigger for the event/object pair is
effectively disabled.
SYNTAX
OLD [ VALUE ] parameter
| FORMAT string
| INITIAL constant
| LABEL string
| NO-UNDO
]
1124
11.4.5 FIND Session Trigger Example
The following is an example of a FIND session trigger for the customer table:
This trigger checks the user ID of the current user and compares it to the customers sales
representative. If they are different, then the customer record is not displayed.
If you plan to use a FIND trigger for security reasons, be aware that the user can still check for
the existence of records with the CANFIND function. This function does not fire the FIND
trigger.
11.4.6 WRITE Session Trigger Example
Whenever the contents of a record are changed and the record is validated, Progress executes
the WRITE trigger. After the WRITE trigger executes, Progress writes the modified record to
the record buffer. Note that if the trigger is executed by a VALIDATE statement, the record is
not necessarily written to the record buffer.
During trigger execution, Progress makes two record buffers available to the trigger procedure.
The NEW buffer contains the modified record that is being validated. The OLD buffer contains
the most recent version of the record before the latest changes were made (this will be the
template record if it is a newly created record, the record from the DB if it has not been
validated, of the most recently validated record if it has been validated). You can modify the
contents of the NEW buffer, but the OLD buffer is read-only. You can compare the contents of
these two buffers and perform actions based on the results.
The following is an example of a WRITE session trigger:
ON FIND OF customer DO:
FIND salesrep OF customer.
IF sales-rep NE userid THEN
RETURN ERROR.
END.
p-sestrg.p
ON WRITE OF customer OLD BUFFER ocust DO:
IF customer.sales-rep <> ocust.sales-rep
THEN DO:
FIND salesrep OF customer NO-LOCK.
customer.comments = customer.comments + " Salesrep changed to " +
salesrep.rep-name + " on " + STRING(TODAY).
END.
END.
Database Triggers
1125
This trigger tests whether you modified the Salesrep field. If so, it adds a comment to the
customer record.
The trigger executes before the record is actually written, which means that the trigger can make
modifications to the record before it is released. These modifications do not cause the trigger to
execute again.
NOTE: If you create a record and then write it to the database without updating it (the initial
field values remain the same), the WRITE trigger does not execute; only the
CREATE trigger executes. If you update one or more fields before you write the
record, both the CREATE and WRITE triggers execute. On Embedded SQL
(ESQL), an INSERT statement always executes both the CREATE and WRITE
triggers.
11.5 General Considerations
When you write triggers, there are several general considerations that you should keep in mind.
11.5.1 Metaschema Tables
Progress does not allow any database triggers on events for metaschema tables and fields (tables
or fields named with an initial underscore). You can only intercept database events for an
application database object.
11.5.2 User-interaction Code
Progress allows you to include any type of 4GL statement within a database trigger block,
including those that involve user interaction. However, it is usually not a good idea to include
any statements that call for input from the user. For example, if the user runs your procedure in
batch mode, a trigger with a prompt causes the procedure to stop, waiting for user input. Also,
if an application is written in ESQL, it can not receive user input.
11.5.3 FIND NEXT and FIND PREV
You cannot delete or advance any record in a buffer passed to a database trigger procedure (as
with a FIND NEXT or FIND PREV statement) within the trigger procedure.
1126
11.5.4 Triggers Execute Other Triggers
An action within one trigger procedure may execute another trigger procedure. For example, if
a trigger procedure assigns a value to a field and you defined an ASSIGN trigger for that field,
that ASSIGN trigger executes. You must carefully design your triggers to avoid conflicts. For
example, trigger A could change data, which could cause trigger B to execute. Trigger B could
change the same data, a change you did not anticipate or want.
11.5.5 Triggers Can Start Transactions
By their nature, CREATE, DELETE, WRITE, and ASSIGN triggers execute from within a
transaction. (The triggering event itself must occur within a transaction.) This means that while
you can start a subtransaction within a trigger procedure for these events, you cannot start a new
transaction. However, a FIND may or may not be executed within a transaction. Therefore, you
should not assume that you can start a subtransaction within a FIND trigger; it might turn out to
be a complete transaction.
11.5.6 Default Error Phrase
For all blocks in a database trigger, the default ON ERROR phrase is ON ERROR UNDO,
RETURN ERROR; this is in contrast to the usual Progress default: ON ERROR UNDO,
RETRY. As with any default, you can override this with an explicit ON ERROR phrase.
11.5.7 RETURN ERROR
If you use the NOERROR qualifier on a statement that executes a trigger, and the trigger
returns an error (with RETURN ERROR), the ERRORSTATUS system handle is set to
TRUE. You can check the value of this system handle after the statement executes:
11.5.8 Where Triggers Execute
Database triggers (including replication-related triggers) execute in the application logic, which
consists of Progress AppServers and local 4GL procedures. For more information on Progress
AppServers, see Building Distributed Applications Using the Progress AppServer.
DELETE customer NO-ERROR.
IF ERROR-STATUS:ERROR THEN DO:
/* Add logic to perform when an error occurs */
Database Triggers
1127
11.5.9 Storing Trigger Procedures in Libraries
You can store precompiled schema trigger procedures in a procedure library. When you connect
to the database, you can use the Triggers (trig) startup parameter to specify the procedure
library that contains them. If you do not use this option, Progress searches the PROPATH for
the trigger procedure when the associated event occurs. Note that you can also use the trig
parameter to specify the operating system directory holding your trigger procedures. For more
information on the trig startup parameter, see the Progress Startup Command and Parameter
Reference.
11.5.10 ESQL Access to Database Objects
If you access a Progress database via ESQL, database schema triggers will execute
appropriately: the DELETE statement executes the DELETE trigger; the CREATE statement
executes the CREATE trigger, etc. Note that ESQL applications executing 4GL database
schema triggers cannot compile .p code on the flyall database triggers must be precompiled.
If a database trigger is executed by an ESQL application, any user interface operations within
that trigger (such as UPDATE, PROMPTFOR, etc.) will cause the ESQL request to fail.
11.5.11 Disabling Triggers for Dump/Load
When you dump and load database records, you may want to disable the schema triggers of the
involved databases. If you do not disable them, when you dump records from a database,
Progress executes any of the databases associated FIND schema triggers. Also, when you load
records into a database, Progress executes any of the databases associated CREATE, WRITE,
and ASSIGN schema triggers.
Executing schema triggers can interfere with the dump/load operation and can increase the time
needed for the operation. For more information on how to disable schema triggers, see the
Progress Database Administration Guide and Reference.
NOTE: If your site implements database replication, and the replication scheme involves
cascading replication, you might have to use ALLOWREPLICATION option of the
DISABLE TRIGGERS FOR LOAD statement. This option tells Progress not to
disable replication-related triggers while it loads data from the replication log to the
database.
11.5.12 SQL Considerations
Because of inherent differences between the Progress 4GL and SQL, triggers may not execute
in exactly the same way. For more information on how SQL and database triggers interact, see
the Progress SQL-89 Guide and Reference.
1128
12
Transactions
A transaction is a unit of work that is either completed as a unit or undone as a unit. Proper
transaction processing is critical to maintaining the integrity of your databases.
This chapter covers the following topics:
Transaction basics
Using transactions
For information on Progress blocks, see Chapter 3, Block Properties. For information on
UNDO processing, see Chapter 5, Condition Handling and Messages.
122
12.1 Introduction
Imagine this situation: you are entering new customer records into your database. You entered
98 records and are working on entering the 99th customer record and your machine goes down.
Are the first 98 records you entered lost? No, Progress does just what you want in this situation:
Keeps the first 98 records in the database
Discards the partial 99th record
This is just one simple scenario. Suppose the procedure was updating multiple tables. You want
to make sure that Progress saves any completed changes and discards partial changes in all
tables.
System failures are just one kind of error. There are other kinds of errors that can occur while a
procedure is running. Regardless of the kind of error you are dealing with, data integrity is all
important. Data integrity means that Progress stores completed data and does not store
incomplete data in the database. Progress uses transactions to automatically handle this
processing.
12.2 Transactions Defined
A transaction is a set of changes to the database, which the system either completes or discards,
leaving no modification to the database. The terms physical transaction and commit unit refer
to the same concept as the Progress transaction. For example, in the above scenario where you
are adding customer records, each customer record you add is a transaction.
Each iteration of the REPEAT block is a transaction. The transaction is undone (or backed out)
if:
The system goes down (or crashes).
The user presses STOP (CTRLBREAK on Windows; usually CTRLC on UNIX).
p-trans.p
REPEAT:
INSERT customer WITH 2 COLUMNS.
END.
Transactions
123
In either of these cases, Progress undoes all work it performed since the start of the transaction,
as shown in Figure 121.
Figure 121: Transaction Undo Processing
So far, you have seen how a transaction can be useful in a situation that involves only a single
table. Transactions take on additional importance when you make database changes in multiple
tables or records.
12.3 All-or-nothing Processing
Suppose a customer calls to change an order for four sweat bands to nine sweat bands. This
means you must make two changes to your database:
First, you must look at the customers order and change the quantity field in the
appropriate orderline record.
Second, you must change the value of the allocated field in the record for that item in the
item table.
Progress undoes records that
were written to database
System
Failure
User
Presses
Stop
Second
Transaction
Add
Customer
102
REPEAT:
INSERT customer
WITH 2 COLUMNS.
END.
First
Transaction
Add
Customer
101
Write record to
database at end
of transaction
REPEAT:
INSERT customer
WITH 2 COLUMNS.
END.
124
What if you changed the quantity field in the orderline record and are in the midst of changing
the allocated field in the item record, when the machine goes down? You want to restore the
records to their original state. That is, you want to be sure that Progress changes both records or
neither.
Figure 122 shows this scenario for a database similar to sports (same tables, different data).
Figure 122: Transaction Involving Two Tables
Line-num Qty
1 9 4
Item-num Alloc
00003 84
Line-num Qty
1 4 9
Item-num Alloc
00003 79
Order-Line
File
Item
File
Order-Line
File
Item
File
The customer's order number is 1 and they want five more sweat bands
(item-num = 00003, with 79 allocated for orders). That item appears on
the first order-line of the order.
Find the order-line record so you
can change the quantity-ordered.
Change the quantity to 9.
Find the item record so you
can change the allocated field.
Subtract the old quantity from
the allocated value and add the
new quantity.
If an error occurs, put the
quantity field back to its original
value. Also, change the allocated
field back to its original value.
x
x
Transactions
125
The following procedure, p-txn.p, executes the scenario shown in Figure 122, using the sports
database.
Progress starts a transaction at the beginning of each iteration of the REPEAT block and ends
that transaction at the end of each iteration of the REPEAT block.
Run p-txn.p. Type 1 as the order number and 1 as the line number and press GO:
p-txn1.p
DEFINE VARIABLE newqty LIKE qty LABEL "New Quantity".
REPEAT WITH 2 COLUMNS:
PROMPT-FOR order-line.order-num line-num.
FIND order-line USING order-num AND line-num.
DISPLAY order-line.qty item.item-num
item.item-name item.allocated.
SET newqty.
item.allocated = item.allocated - order-line.qty + newqty.
order-line.qty = newqty.
DISPLAY item.allocated @ new-alloc
LIKE item.allocated LABEL "New Alloc" SKIP(1).
PAUSE.
END.
126
Now type 35 as the New Quantity and press RETURN. The procedure calculates and displays the
new allocated value:
The quantity has been changed to 35 and the amount allocated changed to 187. At this point
control has reached the PAUSE statement at the end of the REPEAT block:
Press SPACEBAR. The procedure prompts you for another order number and line number. Type
1 for the order number and 2 for the line number:
Transactions
127
Change the number of ordered stop watches to 31:
You can see that the quantity has been changed to 31 and the amount allocated has been
increased to 215 (you increased the number ordered by 10). You have once again reached the
PAUSE statement just before the end of the REPEAT block.
What if, for some reason, your machine goes down or you decide to press STOP at this point in
the procedure? Progress undoes any database changes made during the current iteration of the
REPEAT block. Go ahead and press STOP.
Now you are back in the Procedure Editor. Run the p-txn.p procedure again.
Remember that you had changed the quantity to 35 on line 1 of order 1.
Type 1 as the order number and 1 as the line number. The following screen appears:
You can see that the first change you made is safely stored in the database. Both the orderline
table and the item table reflect the new values of 35 and 348. Press GO to continue on until you
reach the PAUSE statement just before the end of the REPEAT block. Then press SPACEBAR to
continue on to the next iteration.
128
Type 1 for the order number and 2 for the line number.
Notice that for line 2 of order number 1, both the quantity field in the order-line record and the
allocated field in the item record have been returned to their original values of 21 and 0,
respectively.
Remember that each iteration of the REPEAT block started a new transaction. Once the first
iteration (the shin pads) completed successfully, Progress ended the transaction and committed
the changed data to the database.
Progress started another transaction on the next iteration of the REPEAT block. When you
pressed STOP during that iteration, Progress backed out the transaction, undoing all database
changes made since the start of the transaction.
12.4 Understanding Where Transactions Begin and End
How does Progress know where to start the transaction and how much work to undo or back
out? The following transaction blocks start a transaction if one is not already active:
Any block that uses the TRANSACTION keyword on the block statement (DO, FOR
EACH, or REPEAT).
A procedure block, trigger block, and each iteration of a DO ON ERROR, FOR EACH, or
REPEAT block that directly updates the database or directly reads records with
EXCLUSIVELOCK. You use EXCLUSIVELOCK to read records in multi-user
applications. See Chapter 13, Locks for more information on locking.
Transactions
129
Directly updating the database means that the block contains at least one statement that can
change the database. CREATE, DELETE, and UPDATE are examples of such statements.
If a block contains FIND or FOR EACH statements that specify EXCLUSIVELOCK, and at
least one of the FIND or FOR EACH statements is not embedded within inner transaction
blocks, then the block is directly reading records with EXCLUSIVELOCK.
Note that DO blocks do not automatically have the transaction property. Also, if the procedure
or transaction you are looking at is run by another procedure, you must check the calling
procedure to determine whether it starts a transaction before the RUN statement.
Once a transaction is started, all database changes are part of that transaction, until it ends. Each
user of the database can have just one active transaction at a time:
This procedure has two blocks: the procedure block and the REPEAT block. The procedure
block has no statements directly in it that are not contained within the REPEAT block. The
REPEAT block contains an INSERT statement that lets you add order records to the database.
Because the REPEAT block is the outermost block that contains direct updates to the database,
it is the transaction block.
At the start of an iteration of the REPEAT block, Progress starts a transaction. If any errors
occur before the END statement, Progress backs out any work done during that transaction.
Note that data-handling statements that cause Progress to automatically start a transaction for a
regular table will not cause Progress to automatically start a transaction for a work table or
temporary table.
p-txn2.p
REPEAT:
END.
1210
Consider another example:
This procedure has four blocks:
Procedure block There are no statements in this block, so Progress does not start a
transaction at the start of the procedure.
Outer REPEAT block The outermost block that directly updates the database
(INSERT order WITH 2 COLUMNS). Therefore, it is a transaction block. On each
iteration of this block, Progress starts a transaction. If an error occurs before the end of the
block, all work done in that iteration is undone.
Inner REPEAT block Directly updates the database but it is not the outermost block
to do so. Therefore, it is not a transaction block. It is, however, a subtransaction block.
Subtransactions are discussed later in this chapter.
p-txn3.p
REPEAT:
REPEAT:
CREATE order-line.
UPDATE line-num order-line.item-num qty price.
END.
END.
FOR EACH salesrep:
DISPLAY sales-rep rep-name.
UPDATE region.
END.
Transactions
1211
FOR EACH block An outermost block that directly updates the database (UPDATE
region). Therefore, it is a transaction block. On each iteration of this block, Progress starts
a transaction. If an error occurs before the end of the block, all work done in that iteration
is undone.
Go ahead and run this procedure. Enter the data shown in the following display:
After you enter the order information, press GO, then enter the data for line number 1 of the order
and press GO. The procedure prompts you for the next orderline. Press ENDERROR to tell the
procedure that you are finished entering orderlines for order 1005. The procedure prompts you
for information on the next order.
1212
Enter the data shown on the following screen:
After you enter the quantity and are prompted for the price, press STOP. Progress returns you to
the Procedure Editor.
Remember that either a system failure or pressing the STOP key causes Progress to back out the
current transaction. Lets retrace our steps to determine which of the order and orderline data
you entered should be in the database.
1. On the first iteration of the REPEAT block, you entered data for order number. Because
Progress automatically starts a transaction for a REPEAT block if it is an outermost block
containing database updates, a transaction was started at the start of that iteration.
2. In the inner REPEAT block, you entered a single orderline for order 1005. Even though
this is a REPEAT block and does directly update the database, a transaction is already
active. Therefore, Progress does not start a transaction for this inner REPEAT block. All
of the updates done in this inner block are part of the transaction that is already active.
3. When you finished entering that first orderline and pressed GO to add the next order,
Progress reached the end of the iteration of the transaction block and ended the transaction.
Therefore, the order and orderline data you entered were written to the database. It should
still be there, right? Run p-check.p to see if order 1005 and its orderline record exist.
Transactions
1213
This procedure displays order 1005 and its single orderline, proving that the data is in the
database.
The following steps trace the second iteration of the REPEAT block.
1. On the second iteration of the REPEAT block, you entered data for order 1010. Because
Progress automatically starts a transaction for a REPEAT block if it is the outermost block
containing database updates, a transaction was started at the start of that iteration.
2. In the inner REPEAT block, you started entering an orderline for order 32. Even though
this is a REPEAT block and does directly update the database, a transaction is already
active. Therefore, Progress does not start a transaction for this inner REPEAT block and
you were still working within the initial transaction. In the middle of the transaction, you
pressed STOP, which backed out the current transaction.
Run the p-check.p procedure again, this time supplying 1010 as the order number. Progress
displays the message order record not on file.
This message confirms that the data for order 1010 was not stored in the database. But
remember the rule about all-or-nothing processing. When working with multiple tables in a
single transaction, it is important that either all the changes to all the tables are completed or
none of the changes to any of the tables are completed.
When you pressed STOP, you were in the middle of adding an orderline record. Just to be sure
that an orderline record corresponding to order 1010 was not stored in the database, run this
procedure (supply 1010 as the order number and 1 as the orderline number).
p-check.p
PROMPT-FOR order.order-num.
FIND order USING order-num.
DISPLAY order WITH 2 COLUMNS.
FOR EACH order-line OF order:
DISPLAY order-line.
END.
1214
The Data Dictionary definition of the orderline field specifies a validation of
CANFIND(order OF orderline). This means that when you supply an ordernumber,
Progress checks to be sure that the order exists. Since you already know the order does not exist
(we checked by running the p-check.p procedure), you can use the NOVALIDATE Frame
phrase option in the PROMPTFOR statement. This option tells Progress to ignore any
validation criteria defined in the Dictionary.
When you run the p-check2.p procedure and supply 1010 as the order number and 1 as the
orderline number, Progress displays the message orderline record not on file.
Not only did Progress undo the order information you had entered for order 1010 but it also
undid the partial orderline information you had entered.
If you did not press STOP but your system crashed, you would have seen exactly the same
behavior.
p-check2.p
PROMPT-FOR order-line.order-num line-num WITH NO-VALIDATE.
FIND order-line USING order-num AND line-num.
DISPLAY order-line.
Transactions
1215
12.5 How Much to Undo
You have seen how, when the system crashes or when you press STOP, Progress undoes the
current transaction. Suppose you want to undo a transaction under program control or want to
undo a smaller amount of work than that done since the beginning of the transaction.
Take a look at a different version of the p-txn3.p procedure. The outer REPEAT block is the
transaction block:
Suppose that you wanted to restrict the maximum amount of an order to $500. In the event that
the value of an order exceeded that amount, you want to undo the current orderline entry and
display a message to the user. For example, look at p-txn5.p:
p-txn3a.p
REPEAT:
REPEAT:
CREATE order-line.
END.
END.
p-txn5.p
DEFINE VARIABLE extension LIKE order-line.price.
DEFINE VARIABLE tot-order LIKE order-line.price.
REPEAT:
tot-order = 0.
o-l-block:
REPEAT:
CREATE order-line.
extension = qty * price.
tot-order = tot-order + extension.
IF tot-order > 500 THEN DO:
MESSAGE "Order has exceeded $500".
MESSAGE "No more order-lines allowed".
UNDO o-l-block.
END.
END.
END.
1216
The outer REPEAT block is still the transaction block; it is the outermost block that contains
direct updates to the database. However, in this example, Progress starts a subtransaction when
it reaches the inner REPEAT block.
If an error occurs during a subtransaction, all the work done since the beginning of the
subtransaction is undone. Subtransactions can be nested within other subtransactions.
A subtransaction is started when a transaction is already active and Progress encounters a
subtransaction block. The following are subtransaction blocks:
A procedure block that is run from a transaction block in another procedure.
Each iteration of a FOR EACH block nested within a transaction block.
Each iteration of a REPEAT block nested within a transaction block.
Each iteration of a DO TRANSACTION, DO ON ERROR, or DO ON ENDKEY block.
(These blocks are discussed later in this chapter.)
Now go ahead and run the p-txn5.p procedure. Enter the data shown in the following display:
Transactions
1217
After you enter the second orderline, the amount of the order is $225. When you try to enter
the third orderline, the following happens:
The MESSAGE statements display messages telling you that the limit has been exceeded.
The UNDO statement undoes the olblock. The UNDO statement can undo only those
blocks that are either transactions or subtransactions within the current transaction. In this
case, the olblock is a subtransaction.
Table 121 shows when transactions and subtransactions are started.
Note that data handling statements that cause Progress to automatically start a transaction for a
database table do not cause Progress to automatically start a transaction for a work table or
temporary table.
Table 121: Starting Transactions and Subtransactions
Type of Block
Transaction Not
Active
Transaction
Active
DO transaction
FOR EACH transaction
REPEAT transaction
Any DO ON ENDKEY, DO ON
ERROR, FOR EACH,
REPEAT, or procedure block
that directly contains statements
that modify database fields or
records or that read records
using an EXCLUSIVELOCK.
Starts a transaction Starts a subtransaction
Any FOR EACH, REPEAT, or
procedure block that does not
directly contain statements that
either modify the database or
read records using an
EXCLUSIVELOCK.
Does not start a
subtransaction or a
transaction
Starts a subtransaction
1218
12.6 Controlling Where Transactions Begin and End
You may find that, because of the kind of work a procedure does, you want to start or end
transactions in locations other than those Progress automatically chooses. You know that
Progress automatically starts a transaction for each iteration of four kinds of blocks:
FOR EACH blocks that directly update the database.
REPEAT blocks that directly update the database.
Procedure blocks that directly update the database.
DO ON ERROR or DO ON ENDKEY blocks that contain statements that update the
database.
A transaction ends at the end of the transaction block or when the transaction is backed out for
any reason.
Sometimes you want a transaction to be larger or smaller depending on the amount of work you
want undone in the event of an error. You can explicitly tell Progress to start a transaction by
using the TRANSACTION option with a DO, FOR EACH, or REPEAT block header:
DO TRANSACTION:
FOR EACH TRANSACTION:
REPEAT TRANSACTION:
When you explicitly tell Progress to start a transaction, it starts a transaction on each iteration
of the block regardless of whether the block contains statements that directly update the
database. Of course, Progress does not start a transaction if one is already active.
You can also give a DO block the TRANSACTION property by using the ON ERROR phrase
(DO ON ERROR:) if it also directly contains statements that update the database. DO ON
ERROR is discussed later in this chapter.
Transactions
1219
12.6.1 Making Transactions Larger
In the p-txn3a.p procedure, the outermost REPEAT block is the transaction block. That means
that when Progress undoes the transaction, it undoes any work performed in the current iteration
of the outer REPEAT block. Only the current order is undone, while all other orders are safely
stored in the database:
Suppose you wanted, in the event of a system crash, to undo all the orders entered since the start
of the procedure. That is, you want to make the transaction block not just one iteration of the
outer REPEAT block but rather you want the transaction block to encompass all iterations of
the outer REPEAT block. To do this, you use a DO block together with the TRANSACTION
option, as in p-txn4.p:
The TRANSACTION option on the DO block overrides the default transaction placement.
Even though an outermost REPEAT, FOR EACH, or procedure block that contains direct
database updates is normally made the transaction block, the TRANSACTION option overrides
that default.
p-txn3a.p
REPEAT:
REPEAT:
CREATE order-line.
END.
END.
p-txn4.p
DO TRANSACTION:
REPEAT:
REPEAT:
CREATE order-line.
END.
END.
END.
1220
Now, Progress starts a transaction at the start of the DO block. That transaction does not end
until the end of the DO block or until the transaction is backed out for any reason. Go ahead and
run this procedure, entering the following data:
After you enter all the information for the first orderline, press GO. The procedure prompts you
for more orderline information. Press ENDERROR to indicate that there are no more
orderlines to enter for this order. The procedure prompts you for the next order.
Enter the following data:
Transactions
1221
Before entering the price for orderline 2, press STOP. Progress backs out the transaction,
returning you to the procedure editor.
Because the transaction encompasses all iterations of the outer REPEAT block, you would
expect that all work done in those iterations would have been backed out. Now, make sure that
happened. Run p-check.p to check on the orders you entered:
Progress displays the message order record not on file for both order number 1020 and 1025.
This proves that all the work you did in the procedure has been backed out.
Note that any activity that occurs within a DO block that has no TRANSACTION or ON
ERROR phrase in the block header is encompassed in an enclosing transaction or subtransaction
and does not result in a transaction or subtransaction being started.
12.6.2 Making Transactions Smaller
Now imagine the reverse situation to the one in the last section. That is, in the event of a system
crash or pressing STOP, you want to undo only the current orderline. Again, you use a DO
block with the TRANSACTION option to tell Progress where to start transactions:
p-check.p
DISPLAY order-line.
END.
p-txn10.p
REPEAT:
DO TRANSACTION:
END.
REPEAT TRANSACTION:
CREATE order-line.
END.
END.
1222
In p-txn10.p, Progress starts a transaction for each order and also for each orderline you enter.
There are two outermost blocks that contain direct updates to the database:
The DO TRANSACTION block is an outermost block that contains direct updates to the
database (INSERT order). The DO TRANSACTION statement and its corresponding
END statement make the insertion of the order record a transaction.
The inner REPEAT block is an outermost block that contains direct updates to the
database.
The outer REPEAT block is not the transaction block because it does not contain any direct
updates to the database. Run p-txn10.p, entering the following data:
Press STOP while entering the second orderline. Progress undoes the current transaction block,
which means that only the work done on the second orderline is undone. Order 1030 and the
first orderline should be in the database. Run p-check.p to find out:
p-check.p
DISPLAY order-line.
END.
Transactions
1223
Note that any activity that occurs within a DO block that has no TRANSACTION or ON
ERROR phrase in the block header is encompassed in an enclosing transaction or subtransaction
and does not result in a transaction or subtransaction being started.
12.7 Transactions and Triggers
If a transaction begins with a trigger, it cannot extend beyond the end of the trigger. If the
transaction is scoped to a block within the trigger, the normal transaction scoping rules apply.
If the trigger is scoped to the trigger block itself, the transaction ends when the trigger ends.
In the procedure p-txn12.p, a transaction occurs within the CHOOSE trigger for the updcust
button and within the CHOOSE trigger for the delcust button:
p-txn12.p (1 of 2)
DEFINE BUTTON upd-cust LABEL "Update Customer".
DEFINE BUTTON del-cust LABEL "Delete Customer".
DEFINE BUTTON exit-app LABEL "Exit".
DEFINE VARIABLE curr-cust AS ROWID.
DEFINE VARIABLE changes-made AS LOGICAL.
DEFINE QUERY seq-cust FOR customer.
DEFINE BROWSE brow-cust
QUERY seq-cust
DISPLAY Cust-num Name
WITH 10 DOWN.
FORM
upd-cust del-cust exit-app SKIP(1)
brow-cust
WITH FRAME main-frame.
OPEN QUERY seq-cust FOR EACH customer.
ON VALUE-CHANGED OF brow-cust
DO:
curr-cust = ROWID(customer).
END.
1224
The transaction for updating a customer is scoped to the trigger block for CHOOSE of updcust.
The transaction begins and ends when the trigger begins and ends. The transaction for deleting
a customer is scoped to a DO block within the CHOOSE trigger for delcust. The transaction
begins and ends when the DO block begins and ends.
If a transaction is started in the main code and is active when a trigger is invoked, the trigger
becomes part of the transaction. You cannot end the transaction within a trigger. For example,
the procedure p-txn13.p begins a transaction for each pass through the DO WHILE loop
(transloop) in the main code. All updates and deletions performed within the loop are part of
a single transaction. When you choose either the trancom or tranundo button, the loop either
iterates or is undone. At that point, all changes made during that iteration are either committed
or backed out.
ON CHOOSE OF upd-cust
DO: /* TRANSACTION */
FIND customer WHERE ROWID(customer) = curr-cust EXCLUSIVE-LOCK.
UPDATE customer WITH FRAME cust-frame VIEW-AS DIALOG-BOX
TITLE "Customer Update".
changes-made = brow-cust:REFRESH().
RELEASE customer.
END.
ON CHOOSE OF del-cust
DO:
MESSAGE "Delete" customer.name + "?" VIEW-AS ALERT-BOX
QUESTION BUTTONS YES-NO UPDATE kill-it AS LOGICAL.
IF kill-it
THEN DO TRANSACTION:
DELETE customer.
END.
END.
ENABLE ALL WITH FRAME main-frame.
WAIT-FOR CHOOSE OF exit-app OR WINDOW-CLOSE OF DEFAULT-WINDOW.
p-txn12.p (2 of 2)
Transactions
1225
p-txn13.p (1 of 4)
DEFINE BUTTON del-cust LABEL "Delete Customer".
DEFINE BUTTON tran-undo LABEL "Undo Transaction".
DEFINE BUTTON tran-com LABEL "Commit Transaction".
DEFINE VARIABLE exit-chosen AS LOGICAL.
DEFINE VARIABLE undo-chosen AS LOGICAL.
DEFINE QUERY seq-cust FOR Customer.
DEFINE BROWSE brow-cust QUERY seq-cust
DISPLAY Cust-num Name WITH 10 DOWN.
FORM
upd-cust del-cust exit-app SKIP(1)
brow-cust SKIP(1)
tran-com tran-undo
OPEN QUERY seq-cust FOR EACH Customer.
DO:
curr-cust = ROWID(Customer).
END.
1226
DO:
FIND Customer WHERE ROWID(Customer) = curr-cust EXCLUSIVE-LOCK.
UPDATE Customer WITH FRAME cust-frame VIEW-AS DIALOG-BOX
END.
ON CHOOSE OF del-cust
DO:
MESSAGE "Delete" Customer.name + "?" VIEW-AS ALERT-BOX
QUESTION BUTTONS OK-CANCEL UPDATE kill-it AS LOGICAL.
IF kill-it
THEN DO:
FIND Customer WHERE ROWID(Customer) = curr-cust EXCLUSIVE-LOCK.
DELETE Customer.
END.
END.
p-txn13.p (2 of 4)
Transactions
1227
ON CHOOSE OF tran-undo
DO:
undo-chosen = TRUE.
END.
ON CHOOSE OF exit-app
DO:
DEFINE BUTTON exit-commit LABEL "Commit" AUTO-GO.
DEFINE BUTTON exit-undo LABEL "Undo" AUTO-GO.
DEFINE BUTTON exit-cancel LABEL "Cancel" AUTO-ENDKEY.
FORM
"Do you want to commit or undo your changes?" SKIP
exit-commit exit-undo exit-cancel
WITH FRAME exit-frame VIEW-AS DIALOG-BOX TITLE "Exit".
ON CHOOSE OF exit-undo
DO:
undo-chosen = TRUE.
END.
exit-chosen = TRUE.
/* If changes have been made during the current transaction,
then ask the user to either commit or undo them (or cancel
the Exit operation). */
IF changes-made
THEN UPDATE exit-commit exit-undo exit-cancel WITH FRAME exit-frame.
END.
p-txn13.p (3 of 4)
1228
When you choose the exitapp button from the main screen, the DO WHILE loop completes
and the last transaction is committed.
NOTE: Generally, you do not want transactions to span triggers. Instead, you should design
your application so that each transaction occurs within a single trigger. Otherwise,
undoing one action might cause other unrelated actions to be undone also.
Transactions are, by nature, modal. This creates conflicts when you try to write a modeless
application. You can handle this is one of two ways:
Make the modal nature of the transactions clear. For example, p-txn12.p uses a dialog
box for the update of the customer record. This prevents the user from performing any
other actions until the update is completed.
Hide modality from the user but enforce it carefully within your code.
exit-chosen = FALSE.
trans-loop:
DO WHILE NOT exit-chosen TRANSACTION ON ENDKEY UNDO, LEAVE
ON ERROR UNDO, LEAVE:
ASSIGN changes-made = FALSE
undo-chosen = FALSE.
WAIT-FOR CHOOSE OF tran-com, tran-undo, exit-app.
/* If the user chose UNDO (either from the main frame
or from the Exit dialog), then undo the current
transaction and either start a new one or exit. */
IF undo-chosen
THEN DO:
IF exit-chosen
THEN UNDO trans-loop, LEAVE trans-loop.
ELSE UNDO trans-loop, RETRY trans-loop.
END.
/* Make sure we dont hold any locks after committing a transaction. */
IF AVAILABLE(Customer)
THEN RELEASE Customer.
END.
p-txn13.p (4 of 4)
Transactions
1229
The procedure p-txn14.p allows what appears to be a modeless update:
p-txn14.p (1 of 5)
DEFINE BUTTON com-cust LABEL "Save Changes".
DEFINE BUTTON rev-cust LABEL "Revert to Saved".
DEFINE VARIABLE exit-chosen AS LOGICAL.
DEFINE VARIABLE rev-chosen AS LOGICAL.
DEFINE VARIABLE temp-hand AS WIDGET-HANDLE.
DEFINE BUFFER this-cust FOR Customer.
DEFINE QUERY seq-cust FOR this-cust SCROLLING.
DEFINE BROWSE brow-cust QUERY seq-cust DISPLAY Cust-num Name WITH 4 DOWN.
FORM
exit-app SKIP
brow-cust
FORM
Customer.Cust-num Customer.Name Customer.Address Customer.Address2
Customer.City Customer.State Customer.Postal-Code Customer.Country
Customer.Phone Customer.Contact Customer.Sales-rep
Customer.Credit-Limit Customer.Balance Customer.Terms
Customer.Discount Customer.Comments
SKIP
com-cust AT 15 rev-cust AT 45
WITH FRAME curr-frame SIDE-LABELS.
OPEN QUERY seq-cust FOR EACH this-cust.
FIND FIRST Customer NO-LOCK.
1230
ON ITERATION-CHANGED OF brow-cust
DO:
THEN DO:
/* Determine whether any updates were made to previous record. */
temp-hand = FRAME curr-frame:CURRENT-ITERATION.
temp-hand = temp-hand:FIRST-CHILD.
search-widgets:
DO WHILE temp-hand <> ?:
IF CAN-QUERY(temp-hand, "MODIFIED")
THEN IF temp-hand:MODIFIED
THEN LEAVE search-widgets.
temp-hand = temp-hand:NEXT-SIBLING.
END.
/* If a modification was made, assign the record. */
IF temp-hand <> ?
THEN DO:
DO WITH FRAME curr-frame TRANSACTION:
ASSIGN Customer.
END.
MESSAGE "Customer record updated.".
END.
END.
/* Set curr-cust to the ROWID of the current query
record. Find that record with NO-LOCK. */
curr-cust = ROWID(this-cust).
FIND Customer WHERE ROWID(Customer) = curr-cust NO-LOCK.
/* Display the current record. We have to disable the update
fields and them re-enable them after the DISPLAY. Otherwise,
the DISPLAY sets all the MODIFIED attributes to TRUE.*/
DISABLE ALL WITH FRAME curr-frame.
DISPLAY Customer WITH FRAME curr-frame.
ENABLE ALL WITH FRAME curr-frame.
END.
ON CHOOSE OF exit-app /* Exit application. */
DO:
/* Set a flag so well know why we exited the WAIT-FOR. */
exit-chosen = TRUE.
END.
p-txn14.p (2 of 5)
Transactions
1231
ON CHOOSE OF com-cust /* Commit changes to Customer record. */
DO:
/* Commit any changes made to the Customer record. */
DO WITH FRAME curr-frame TRANSACTION:
ASSIGN Customer.
RELEASE Customer.
END.
MESSAGE "Customer record updated.".
/* Release the exclusive lock. */
CLOSE QUERY seq-cust.
OPEN QUERY seq-cust FOR EACH this-cust.
REPOSITION seq-cust TO ROWID curr-cust.
/* Restore the MODIFIED attribute to FALSE. */
HIDE FRAME curr-frame.
VIEW FRAME curr-frame.
END.
ON CHOOSE OF rev-cust /* Undo pending changes to Customer record. */
DO:
rev-chosen = TRUE.
/* Undo any changes to the Customer screen buffer
and reset the MODIFIED attributes to FALSE. */
THEN DISPLAY Customer WITH FRAME curr-frame.
END.
p-txn14.p (3 of 5)
1232
ON ENTRY OF FRAME curr-frame
DO:
/* Upgrade from NO-LOCK to EXCLUSIVE-LOCK. */
FIND Customer WHERE ROWID(Customer) = curr-cust EXCLUSIVE-LOCK
NO-WAIT NO-ERROR.
/* If we didnt get the exclusive lock, then give a
message and return focus to previous frame. */
IF LOCKED(Customer)
THEN DO:
MESSAGE "Record is currently locked by another user."
VIEW-AS ALERT-BOX ERROR BUTTONS OK.
END.
IF NOT AVAILABLE(Customer)
THEN DO:
APPLY "CHOOSE" TO rev-cust IN FRAME curr-frame.
RETURN NO-APPLY.
END.
/* Pick up any updates that may have occured. */
DISPLAY Customer WITH FRAME curr-frame.
END.
APPLY "ITERATION-CHANGED" TO brow-cust.
p-txn14.p (4 of 5)
Transactions
1233
When you run this procedure, focus is initially in the mainframe frame. When you move focus
to the currframe, the ON ENTRY trigger applies an EXCLUSIVELOCK to the customer
record. Subsequently, when you either choose the comcust button or change the iteration of the
browse, a small transaction assigns your changes to the customer record. The
EXCLUSIVELOCK on the record is then released.
Although this example appears modeless when you run it, it is really modal. When you move
focus to the currframe frame you enter a mode in which you hold an EXCLUSIVELOCK on
the customer record (previously, you held the record NOLOCK). This mode remains in effect
until you choose either the comcust or revcust button or change the iteration of the browse.
At that point, the EXCLUSIVELOCK is released.
NOTE: While it is possible to present a modeless update, it requires somewhat complex
coding for even a simple example, as in p-txn14.p. In a more realistic example
where the user has more choices of actions, this technique is more difficult and more
dangerous. Using modal updates with dialog boxes is safer and is the preferred
approach.
main-loop:
DO WHILE TRUE ON ENDKEY UNDO, RETURN ON ERROR UNDO, RETRY:
ASSIGN rev-chosen = FALSE
exit-chosen = FALSE.
WAIT-FOR CHOOSE OF exit-app OR WINDOW-CLOSE OF DEFAULT-WINDOW OR
CHOOSE OF com-cust, rev-cust FOCUS brow-cust IN FRAME main-frame.
THEN RELEASE Customer.
IF exit-chosen
THEN LEAVE main-loop.
IF rev-chosen
THEN UNDO main-loop, RETRY main-loop.
END.
p-txn14.p (5 of 5)
1234
12.8 Transactions and Subprocedures
If you start a transaction in a main procedure, that transaction remains active even while the
main procedure runs called procedures. For example, p-txn11.p runs p-txn11a.p within a
transaction:
This procedure lets you update customer information and then asks if you want to process the
customers orders. If you say yes, the procedure runs a second procedure called p-txn11a.p.
p-txn11.p
DEFINE NEW SHARED VARIABLE cust-num-var AS ROWID.
REPEAT WITH 1 DOWN:
DISPLAY name sales-rep.
UPDATE credit-limit balance.
SET answer LABEL "Do you want to do order processing?"
WITH FRAME a NO-HIDE.
IF answer THEN DO:
cust-num-var = ROWID(customer).
RUN p-txn11a.p.
END.
END.
p-txn11a.p
DEFINE SHARED VARIABLE cust-num-var AS ROWID.
HIDE ALL.
FIND customer WHERE ROWID(customer) = cust-num-var.
UPDATE order WITH 2 COLUMNS.
UPDATE order-line.
END.
END.
Transactions
1235
The REPEAT block in the p-txn11.p procedure is the transaction block for that procedure:
it contains a direct update to the database. The transaction begins at the start of each iteration of
the REPEAT block and ends at the end of each iteration. That means that, when the p-txn11.p
procedure calls the p-txn11a.p procedure, the transaction is still active. So all the work done
in the p-txn11a.p subroutine is part of the transaction started by the main procedure,
p-txn11.p. The following figure, illustrates the start and end of the full transaction.
Figure 123: The Transaction Block for the p-txn11.p Procedure
If a system error occurs while you are processing orders for a customer, Progress undoes all the
order processing work you have done for that customer, as well as any changes you made to the
customer record itself.
Transaction Start
p-txn11.p p-txn11a.p
Transaction End
REPEAT:
RUN p-txn11a.p.
END.
FOR EACH
.
.
.
END.
1236
12.9 Transactions with File Input
You must be especially careful when you process transactions that read input from a text file. If
a crash occurs, the active transaction is backed out of the database, but you will not
automatically know how far processing proceeded in the text file. To handle this, you must
either:
Restore the database and rerun the procedures that were running when the system failed.
Run all data input processes as a single transaction (this has record locking implications
as well as implications in terms of the size of the before-image file for the transaction).
Have a way to determine how many of the input data lines were processed and committed
to the database so that you do not rerun lines that were successfully processed by a
procedure.
One technique for doing this is to save the filename and the last line number in a database
table, since changes in this status information can be synchronized with the corresponding
database updates.
12.10 Transactions and Program Variables
You have read quite a bit about how transactions are backed out and how database changes are
undone. But what happens to work done with variables?
Any changes made to variables in a transaction or subtransaction block are undone whenever a
transaction or subtransaction is backed out. The variables are restored to the values they had at
the beginning of the transaction or subtransaction that is undone. Variables specifically defined
as NOUNDO are not undone in this case. However, changes to variables made outside a
transaction are never undone since only transaction and subtransaction blocks can be undone.
Suppose you are creating customer records and using a variable to keep track of how many
records have been created:
p-var.p
DEFINE VARIABLE ctr AS INTEGER INITIAL 0.
REPEAT:
CREATE customer.
ctr = ctr + 1.
UPDATE cust-num name WITH NO-BOX.
END.
DISPLAY ctr "customer records were created"
WITH NO-BOX NO-LABELS COLUMN 35.
Transactions
1237
Run p-var.p and enter the data shown in the following display:
At this point, the following has happened:
On the first iteration of the REPEAT block, the CREATE statement created a customer
record.
The ctr variable was incremented by 1, so its value became 1.
You used the UPDATE statement to put the values of 500 and Fly Away Gliding in the
custnum and name fields of the new customer record.
On the second iteration of the REPEAT block, the CREATE statement creates a second
customer record.
The ctr variable is incremented by 1 again, giving it a new value of 2.
Press ENDERROR. Progress undoes the work done in the current iteration of the REPEAT block
and leaves that block. The customer record created on the second iteration, which had all its
fields set to their initial values, is backed out and the value of ctr is reset from 2 to the value it
had at the beginning of the iteration (transaction), which is 1. The DISPLAY statement tells you
that just one customer has been created, as shown in the following display:
1238
Within a transaction, any changes made to variables or to database fields are undone when that
transaction is undone. However, any changes made to variables prior to the start of the
transaction are not backed out. For example, consider p-tnchp.p.
In this procedure, Progress starts a transaction at the beginning of each iteration of the FOR
EACH block because the block contains an UPDATE statement to modify records. The UNDO
cusloop statement undoes changes made during the current iteration of the FOR EACH block.
When this occurs, Progress undoes the changes to the order being updated and to the variable j.
Variable j is restored to its value at the beginning of the current iteration of the FOR EACH
block (at the beginning of the transaction). However, Progress does not undo changes to the
variable i because those changes were not done within the transaction.
Although backing out of variables is useful in many cases, keep the following in mind:
There is a certain amount of overhead associated with undoing variables in transactions
and subtransactions.
If you are going to be doing extensive calculations involving variables or arrays, then
consider using the NOUNDO option on those variables if you have no need for the undo
services on those variables.
p-tnchp.p
DEFINE VARIABLE j AS INTEGER.
culoop:
REPEAT:
i = i + 1.
DISPLAY name.
j = j + 1.
DISPLAY order-num.
UPDATE odate.
IF odate > TODAY THEN UNDO cusloop, RETRY cusloop.
END.
END.
Transactions
1239
12.10.1 Transactions in Multi-database Applications
In a multi-database application, you generally do not have to code any additional transaction
handling. Multi-database transactions are handled in much the same way that single-database
transactions are handled. The Progress two-phase commit mechanism ensures that any
transaction is either committed to all affected databases or to none. You may, if you wish, check
to see that all necessary databases are connected before you start a transaction.
Two-Phase Commit
During a transaction, Progress writes data to one or more databases as program control passes
through database update statements in the transaction block. At the end of a transaction block,
Progress tries to commit the changes to the databases. Progress uses a two-phase commit
protocol to commit the changes to the databases. In the two-phase commit protocol, Progress
polls all the databases affected by the transaction to see if they are reachable.
In the first phase of the two-phase commit, Progress checks whether it can reach each database
and makes the appropriate validation checks for each database. If any one of the databases is
unreachable or the validation checks fail for a database, Progress backs out the transaction and
returns the databases to their pretransaction states using the before-image files. If all of the
databases are reachable and their validation checks succeeded, Progress commits the changes
to the databases.
For more information on two-phase commit, see the Progress Database Administration Guide
and Reference.
Checking Database Connections
If you want to test database connections prior to entering a transaction, use the CONNECTED
function.
You should connect to all databases affected by a transaction prior to entering a transaction
block. As a general rule, do not execute a database connection in a transaction block. The
database connection overhead could lock records in other databases affected by the transaction
for considerable length of time. A database connection failure also causes a transaction error.
Progress defers DISCONNECT statements in a transaction until the transaction completes or is
undone.
For more information on connecting and disconnecting databases, see Chapter 9, Database
Access.
IF CONNECTED("db1") AND CONNECTED("db2")
THEN RUN txnblk.p. /* transaction block */
ELSE MESSAGE "Unable to perform transaction".
1240
12.10.2 Transactions in Distributed Applications
When a requesting application with an active transaction runs a remote procedure, Progress
does not propagate the transaction to the remote procedure. Rather, the remote procedure acts
as if it is the first procedure of the application, and follows the normal 4GL rules for starting and
terminating transactions. If a requesting application and a remote procedure connect to the same
database, each database connection comprises a separate transaction.
For more information on remote procedures, see Building Distributed Applications Using the
Progress AppServer.
12.11 Determining When Transactions Are Active
You can use the TRANSACTION function to determine whether a transaction is active in a
procedure. The TRANSACTION function can help you identify the transaction and
subtransaction blocks within a procedure.
Run p-nord2.p to see how the TRANSACTION function works:
This procedure displays messages telling you whether a transaction is active or inactive in three
places. You can get more information on transaction activity by using the LISTING option on
the COMPILE statement. See the Progress Language Reference for more information on the
COMPILE statement and the TRANSACTION function.
p-nord2.p
MESSAGE "A transaction" (IF TRANSACTION THEN "is" ELSE "is not")
"active before the REPEAT block.".
ordblock:
REPEAT:
"active in the outer REPEAT block.".
CREATE order.
UPDATE order-num cust-num odate.
olblock:
REPEAT:
"active in the inner REPEAT block.".
CREATE order-line.
SET line-num qty item-num price.
END.
END.
Transactions
1241
12.12 Progress Transaction Mechanics
So far, this chapter has explained the actions Progress takes in the event of different kinds of
errors and how you can override those actions and specify your own. But there is another side
to what Progress is doing during transactions and subtransactions. The next two sections
summarize the mechanics of transactions and subtransactions.
12.12.1 Transaction Mechanics
During a transaction, information on all database activity occurring during that transaction is
written to a before-image (BI) file. Progress maintains one BI file for each database. The
information written to the before-image file is carefully coordinated with the timing of the data
written to the actual database table. That way, if an error occurs during the transaction, Progress
uses this before-image file to restore the database to the condition it was in before the
transaction started. Information written to the before image file is not buffered. It is written to
disk immediately.
Space in the before-image file is allocated in units called clusters. Progress automatically
allocates new clusters as needed. (You can use the PROUTIL TRUNCATE BI utility to set the
cluster size.) After all changes associated with a cluster have been committed and written to
disk, Progress can reuse the cluster. Therefore the disk space used by the before-image file
depends on several factors including the cluster size, the scope of your transactions, and when
physical writes are made to the database (.db) file.
12.12.2 Subtransaction Mechanics
If a transaction is already active and Progress encounters a DO ON ERROR, DO
TRANSACTION, FOR EACH, REPEAT, or procedure block, Progress starts a subtransaction.
All database activity occurring during that subtransaction is written to a local-before-image
(LBI) file. Progress maintains one LBI file for each user. If an error occurs during the
subtransaction, Progress uses this local-before-image file to restore the database to the condition
it was in before the subtransaction started. Progress uses the local-before-image file to back out
variables and to back out subtransactions in all cases when an entire transaction is not being
backed out.
Note that the first time a variable is altered within a subtransaction block, all of the variables in
the procedure are written to the LBI file as a record.
Because the local-before-image information is not needed for crash recovery, it does not have
to be written to disk in a carefully synchronized fashion as does the before-image information.
This minimizes the overhead associated with subtransactions. The local-before-image file is
written using normal, buffered I/O.
1242
The amount of disk space required for each users LBI file depends on the number of
subtransactions started that are subject to being undone.
12.13 Efficient Transaction Processing
Here are a few guidelines to improve the efficiency of transaction processing procedures:
If you are doing extensive calculations with variables, and you do not need to take
advantage of undo processing for those variables, use the NOUNDO option when
defining the variables.
If you are processing array elements, process them in a DO WHILE block rather than in a
REPEAT WHILE block. That way, you will not start a separate transaction or
subtransaction for each array element.
When the logic of your application permits, do as much processing as possible directly at
the transaction level rather than creating subtransactions. This principle should not restrict
the way you implement your application, but you should use it whenever it is convenient.
13
Locks
If you write multi-user applications, there are additional issues and features you should address
during your application development cycle.
This chapter explains:
Sharing database records
Resolving locking issues
The concepts explained in this chapter apply to applications running in a multi-user
environment. If you are developing an application on a single-user system, you can use all the
multi-user statements shown in this chapter. Progress simply disregards those statements when
you run the application in single-user mode.
132
13.1 Applications in a Multi-user Environment
Suppose there are two departments, Shipping and Receiving, that are using the same database.
When they ship an order, the Shipping Department subtracts the number of items shipped from
that items onhand value. When it receives inventory from a vendor, the Receiving Department
adds the number of items received to that items onhand value.
Consider the case where the number of parkas on hand is 67. The Shipping Department ships
20 parkas and the Receiving Department receives 10 parkas. The number of parkas on hand is
now 57 (67 onhand 20 shipped + 10 received = 57).
Figure 131 shows how this simple situation, when performed with no special multi-user
controls, can produce a very different result from the obvious one you expect.
Figure 131: Multi-user Update Scenario Without Locks
Shipping Receiving
Just shipped 20
parkas (item
number 27).
1)
Get the parka
record from the
item table.
2)
Just received 10
parkas (item
number 27).
3)
Get the parka
record from the
item table.
4) 4)
Add 10 to the
on-hand field.
6)
5) Subtract 20 from
the on-hand field.
27 67
item-num on-hand
27 47
item-num on-hand
27 77
item-num on-hand
Starts As
67
Ends As
77
Locks
133
Examine what happens if you do not take any special steps to handle multiple users accessing
the same database. The points below correspond to the numbers in Figure 131.
1. The Shipping Department ships an order for 20 parkas (item number 27).
2. The Shipping Department gets the parka record from the item table. In that record, the
value of the onhand field is 67.
3. The Receiving Department receives 10 parkas (item number 27).
4. The Receiving Department also gets the parka record from the item table. In that record,
the value of the onhand field is 67.
5. The Shipping Department subtracts 20 from the onhand value, and returns the record to
the database. The onhand value of the parka record in the database is now 47.
6. The Receiving Department adds 10 to the onhand value of 67 and returns the record to
the database. That record overwrites the record written by the Shipping Department,
causing the onhand value of the parka record in the database to be 77.
The database indicates that there are 77 parkas on hand instead of 57. It is as if the Receiving
Department never updated the database.
Scenarios like this occur often in a multi-user environment and, for that reason, Progress
supplies services to make sure that the data in your database is accurate.
13.2 Sharing Database Records
The situation described above has to do with multiple users who need access to the same record
at the same time. In the illustration, things did not work as expected because both the Shipping
and Receiving departments were making changes to the same record at the same time. But
neither department could see the other departments changes.
The solution to this record sharing problem is to make sure that:
Multiple users can read, or look at, the same record at the same time.
BUT
Only one user at a time can update, or make changes to, a record.
Progress uses record locks to enforce these rules.
134
13.2.1 Using Locks to Avoid Record Conflicts
Take another look at the Shipping and Receiving scenario. Figure 132 shows how you can use
locks to manage concurrent use of the same database record.
Figure 132: Multi-user Update Scenario with Locks
Just received 10
parkas (item
number 27).
3)
27 57
item-num on-hand
Get the parka
record from the
item table.
Because
Shipping has
EXCLUSIVE-
LOCKed the
record, Receiving
must wait until
Shipping is done.
4)
Shipping Receiving
Just shipped 20
parkas (item
number 27).
1)
5) Subtract 20 from
the on-hand field.
27 67
item-num on-hand
27 47
item-num on-hand
Starts As
67
Ends As
57
Get the parka
record from the
item table, putting
an EXCLUSIVE-
LOCK on the
record.
2)
6) Release the
EXCLUSIVE-
LOCK and write
the record to the
database.
When Shipping
is done, get the
parka record.
7)
27 47
item-num on-hand
Add 10 to the
on-hand field.
8)
Locks
135
Here are the procedures that do this work. The numbers in the margin of the procedures
correspond to the numbers in the list that follows the procedures:
1. The Shipping Department enters and ships an order for 20 parkas (item number 27).
2. The Shipping Department gets the parka record from the item table, placing an
EXCLUSIVELOCK on the record. That means that no other user can look at the record
until Shipping is finished with it. In that record, the value of the onhand field is 67.
NOTE: You can read a locked record if you bypass all record locking using NOLOCK.
For more information, see the Bypassing Progress Lock Protections section.
3. The Receiving Department receives and enters 10 parkas (item number 27) into inventory.
p-lock1.p
/* SHIPPING */
DEFINE VARIABLE qty-shipped AS INTEGER
LABEL "Number Shipped".
REPEAT:
/* 1 */ PROMPT-FOR item.item-num.
/* 2 */ FIND item USING item-num EXCLUSIVE-LOCK.
DISPLAY item-name on-hand.
SET qty-shipped.
/* 5 */ on-hand = on-hand - qty-shipped.
DISPLAY on-hand.
/* 6 */ END.
p-lock2.p
/* SHIPPING */
DEFINE VARIABLE qty-shipped AS INTEGER
LABEL "Number Received".
REPEAT:
/* 3 */ PROMPT-FOR item.item-num.
/* 4, 7 */ FIND item USING item-num.
DISPLAY item-name on-hand.
SET qty-recvd.
/* 8 */ on-hand = on-hand - qty-recvd.
DISPLAY on-hand.
END.
136
4. The Receiving Department tries to get the parka record from the item table but cannot
because Shipping has an EXCLUSIVELOCK on the record.
5. The Shipping Department subtracts 20 from the onhand value, and returns the record to
the database.
6. Once it returns the record to the database, the procedure releases the
EXCLUSIVELOCK.
7. The Receiving Department can now successfully read the record from the database. The
onhand value of the parka record in the database is now 47.
8. The Receiving Department adds 10 to the onhand value of 47 and returns the record to
the database. Therefore, the final onhand value for the parka record is 57exactly what
you would expect!
13.2.2 How Progress Applies Locks
Youve just seen how you can apply a lock on your own. But if you do not apply any locks,
Progress performs default locking. In particular:
Whenever it reads a record, Progress puts a SHARELOCK on that record. (An exception
is the browse widget. See the section Bypassing Progress Lock Protections for more
information.) This means that other users can read the record but cannot update it until the
procedure releases the SHARELOCK. If you try to read a record with a SHARELOCK
when another user has that record EXCLUSIVELOCKed, Progress displays a message
that the record is in use and you must wait to access it.
Whenever Progress updates a record, it puts an EXCLUSIVELOCK on that record. This
means that other users cannot read or update that record until the procedure releases
EXCLUSIVELOCK. If you try to read a record with an EXCLUSIVELOCK, when
another user has that record SHARELOCKed or EXCLUSIVELOCKed, you receive a
message that the record is in use and you must wait to access it.
NOTE: SHARELOCKs and EXCLUSIVELOCKs use up entries in the lock table. The
possible number of entries in the lock table defaults to 500. You can change this with
the Lock Table Entries (L) startup parameter. Progress stops a user program if it
attempts to access a record that overflows the lock table.
Locks
137
In Figure 133, when the FIND statement reads the customer record, Progress puts a
SHARELOCK on that record. Because the UPDATE statement lets you change the record,
Progress upgrades the SHARELOCK to an EXCLUSIVELOCK after the UPDATE
statement executes.
p-lock3.p
Figure 133: How Progress Applies Locks
Other users can read, but
cannot update, this
customer record.
SHARE-LOCK
Other users cannot read
or update this customer
record.
EXCLUSIVE-
LOCK
REPEAT:
UPDATE name credit-limit sales-rep.
END.
138
13.3 Bypassing Progress Lock Protections
In some cases you might want to read a record even though another user holds an
EXCLUSIVELOCK on that record. For example:
You might want to produce a report and you do not want to be held up by locking conflicts.
You might want to browse through a set of records and then select one to update. You do
not want to lock all the records that you are browsing, but only lock the one you select.
For cases such as these, Progress allows you bypass the normal locking mechanism and access
a record with NOLOCK. For example, p-lock6.p produces a simple customer report:
Because the FOR EACH statement in this example uses the NOLOCK option, the procedure
accesses every customer record without error even if another user holds an
EXCLUSIVELOCK on one or more records.
p-lock6.p
FOR EACH customer NO-LOCK:
DISPLAY cust-num name address city state postal-code.
END.
Locks
139
For a browse widget, NOLOCK is the default mode. If you want to update a record, then you
must find that record again to apply a lock. For example, p-lock7.p browses records with
NOLOCK but allows you to select a record to update:
When you run this procedure and choose the updcust button, the trigger finds the current
record again and applies an EXCLUSIVELOCK to it. You can then update the record.
NOTE: If you read a record with NOLOCK before a transaction starts and then read the
same record with EXCLUSIVELOCK within the transaction, the
EXCLUSIVELOCK is automatically downgraded to a SHARELOCK when the
transaction ends. Progress does not automatically return you to NOLOCK status. If
you do not want to hold a lock beyond the end of the transaction, you must execute
a RELEASE statement on the record within the transaction.
p-lock7.p
DEFINE QUERY seq-cust FOR customer.
DEFINE BROWSE brow-cust QUERY seq-cust DISPLAY Cust-num Name WITH 5 DOWN.
FORM
upd-cust exit-app SKIP(1)
brow-cust
OPEN QUERY seq-cust FOR EACH customer.
DO:
curr-cust = ROWID(customer).
END.
DO: /* TRANSACTION */
UPDATE customer WITH FRAME cust-frame VIEW-AS DIALOG-BOX
DISPLAY Cust-num Name WITH BROWSE brow-cust.
RELEASE customer.
END.
WAIT-FOR CHOOSE OF exit-app OR WINDOW-CLOSE OF DEFAULT-WINDOW.
1310
In p-lock7.p, because a RELEASE statement is executed in the transaction, the record lock is
released after the transaction completes.
Because NOLOCK bypasses the normal Progress lock protection, there are risks in using
NOLOCK. For example, in p-lock7.p, the customer names you see in the browse widget
might not be up-to-date. Another user might have updated one or more records since you
retrieved them. You receive no warning that your data is no longer current. However, when you
execute the FIND statement in the updcust trigger, you retrieve the up-to-date record.
13.4 How Long Does Progress Hold a Lock?
Record locks and transactions are closely related. Chapter 12, Transactions explained that
transactions are always related to blocks. To review, the following are transaction blocks:
Any block that uses the TRANSACTION keyword on the block statement (DO, FOR
EACH, or REPEAT).
A procedure block, a trigger block, and each iteration of a DO ON ERROR, FOR EACH,
or REPEAT block that directly updates the database or directly reads records with
EXCLUSIVELOCK.
Locks
1311
13.4.1 Locks and Transactions
To understand the relationship between record locks and transactions, see Figure 134, which
shows a modified version of p-lock3.p.
p-lock4.p
Figure 134: Locks and Transactions
The following hypothetical steps illustrate a common problem with record locks:
1. At the start of the first iteration of the REPEAT block, Progress starts a transaction.
2. You supply customer number 1 to the PROMPTFOR statement.
3. The FIND statement reads the database record for customer 1 and Progress places a
SHARELOCK on that record.
SHARE-LOCK
REPEAT:
SET answer LABEL "Update OK?".
IF NOT answer THEN UNDO, NEXT.
END.
Other users can read,
but cannot update, this
customer record.
Other users cannot
read or update this
customer record.
EXCLUSIVE-
LOCK
Each iteration of
this REPEAT block
is a transaction.
1312
4. The UPDATE statement lets you make changes to the record and Progress places an
EXCLUSIVELOCK on the record.
5. At the end of the UPDATE statement, Progress releases the EXCLUSIVELOCK.
6. Another user running the same procedure finds customer 1 and updates information for
that customer (this user gets the record with the new data you entered in Step 4).
7. You answer no to the Updates OK prompt and Progress undoes your changes.
8. The other user answers yes to the Updates OK prompt and Progress writes the record
back to the database, with the changes that you wanted undone.
Because of this problem and others like it, Progress uses some standards to determine how long
to hold a lock. These standards produce behavior that matches what you want to happen in
situations like the one just described. Table 131 lists the standards Progress uses to determine
when to release record locks.
Locks
1313
Table 131: When Progress Releases Record Locks
Type of
Lock
Acquired
During a
Transaction
1
Acquired
Outside a
Transaction
2
Acquired Outside,
but Held Going into
a Transaction
3
SHARE Held until the
transaction end or
record release,
whichever is later.
4
Held until record
release.
Held until the
transaction end or
record release,
whichever is later.
4
EXCLUSIVE Held until transaction
end. Then converted
to SHARE
5
if record
scope is larger than
transaction and record
is still active in any
buffer.
N/A N/A
1
A record acquires a lock during a transaction if Progress reads or rereads it after the start, and before the end of
a transaction.
2
A record acquires a lock outside a transaction if Progress reads it when a transaction is not active and releases it
before a transaction starts.
3
A record acquires a lock outside a transaction and holds it going into a transaction if Progress reads the record
when a transaction is not active and releases the record when a transaction starts
4
Progress releases a record from a buffer at the end of the record scope, when Progress executes a RELEASE
statement, or when Progress replaces the record in the buffer by a CREATE, FIND, or FOR EACH statement
5
This is true even if Progress read the record with NOLOCK prior to the transaction and rereads it with
EXCLUSIVELOCK during the transaction. By default, Progress converts the lock to SHARELOCK, not
back to NOLOCK. To avoid holding the record SHARELOCK in this case, execute a RELEASE statement
during the transaction. Progress then releases the lock at the end of the transaction. You can then re-read the
record with NOLOCK.
1314
Progress releases locks acquired within a transaction, (or changes them to SHARELOCK if it
locked the record prior to the transaction) if it backs out the transaction. This does not occur
when Progress backs out a subtransaction because Progress does not release the locks a record
acquires within a transaction unless the transaction ends or Progress undoes the entire
transaction.
How do the rules in Table 131 affect the p-lock4.p procedure?
1. At the start of the first iteration of the REPEAT block, Progress starts a transaction.
2. You supply customer number 1 to the PROMPTFOR statement.
3. The FIND statement reads the database record for customer 1 and Progress places a
SHARELOCK on that record. The SHARELOCK remains until the end of the
transaction or until Progress releases the record, whichever occurs later. In this example,
transaction end and record release both happen at the end of the REPEAT block.
4. The UPDATE statement lets you make changes to the record and Progress upgrades the
SHARELOCK to an EXCLUSIVELOCK. This lock remains until the end of the
transaction, which is the end of this iteration of the REPEAT block.
5. Another user running the same procedure tries to find customer 1. However, because the
record for customer 1 is EXCLUSIVELOCKed, the FIND statement waits until the
record is available. The user sees a message that the record is in use.
6. You answer NO to the Updates OK question, Progress undoes the changes you made to
the record, reaches the end of the first iteration of the REPEAT block, the transaction ends
and releases the EXCLUSIVELOCK on the record.
7. The other user is able to find the record and update it.
Because of the duration of the record locks, Progress processes your transactions consistently
in a multi-user environment.
Locks
1315
13.4.2 Locks and Multiple Buffers
Progress also uses default behaviors to prevent the condition known as bleeding record locks
when multiple buffers use the same record. A bleeding record lock occurs when a buffer with
NOLOCK inherits a SHARELOCK from another buffer during a record disconnect.
For example, examine this code:
In this code example, two customer buffers contain copies of the same record. One has it with
a NOLOCK and the other has it with a SHARELOCK. When the second FIND statement
executes, the NOLOCK state of acust is upgraded to SHARELOCK. When Progress executes
the RELEASE statement, the customer record is disconnected from the bcust buffer and its
SHARELOCK is downgraded to a NOLOCK. What happens to the acust buffer lock status?
If acust retains the SHARELOCK, then you can say that the bcust lock bled to acust. This is a
bleeding record lock. Fortunately, Progress does not simply release the specific record and lock.
It checks all other buffers to see what locks they require. In this case, the acust buffer is
downgraded to NOLOCK. Progress does not allow bleeding record locks to occur in any
situation.
NOTE: Progress Version 7.3A and earlier did allow bleeding record locks as described in
this section. To preserve application behavior that depended on bleeding locks, use
the Bleeding Record Lock (brl) startup parameter. You might have to use this
startup parameter if a working Version 7.3A or earlier Progress application generates
the following error messages when compiled under V7.3B or later:
p-lock12.p
DEFINE BUFFER acust FOR customer.
DEFINE BUFFER bcust FOR customer.
FIND acust WHERE acust.cust-num = 1 NO-LOCK.
FIND bcust WHERE bcust.cust-num = 1 SHARE-LOCK.
RELEASE bcust.
table-name record has NO-LOCK status, update to field not allowed
1316
13.5 Resolving Locking Conflicts
You can use the following options to resolve locking conflicts and to describe the way you want
to lock records:
EXCLUSIVELOCK
SHARELOCK
NOLOCK
For example, if you know you are going update a record, you can use the EXCLUSIVELOCK
option with the FIND statement, as shown in the following procedures:
p-lock4.p
/* USER 1 */
REPEAT:
SET answer LABEL "Update OK?".
IF NOT answer THEN UNDO, NEXT.
END.
p-lock5.p
/* USER 2 */
FOR EACH customer:
END.
Locks
1317
Before running either of these procedures, follow these steps to set up the multi-user
environment:
1 Start the multi-user server, using the command appropriate to your operating system.
Here, databasename is the name of the database that you want to run multi-user Progress
against.
2 On one terminal (terminal 1), start multi-user Progress with the appropriate command for
your operating system.
3 On a second terminal (terminal 2), enter the same command to start another multi-user
Progress session for the same database.
You are now running two users in a multi-user environment.
Operating
System Syntax
UNIX
Windows
proserve database-name
Operating
System Syntax
UNIX
Windows
mpro database-name
1318
On terminal 1 run the p-lock4.p procedure. Enter 1 in response to the PROMPTFOR
statement. Make some change to the record for customer 1 and then press GO. The SET statement
prompts you to verify the changes you made.
On terminal 2, run the p-lock5.p procedure. Progress displays a message telling you that the
record is in use by another user.
(This message is system specific; it names the appropriate user and device on each system.)
The UPDATE statement places an EXCLUSIVELOCK on the customer record 1. That lock is
in effect until the end of the transaction, which means Progress locks the record while it prompts
you to verify your updates. Meanwhile, the user on terminal 2 cannot read the record for
customer 1 because the user on terminal 1 has that record EXCLUSIVELOCKed.
At this point, you can press STOP on terminal 2 if you do not want to wait for terminal 1 to release
the record. But do not do that right now. Go to terminal 1 and answer YES. You now see
customer information on terminal 2.
When you answer YES on terminal 1, Progress completes the SET statement and reaches the
end of the REPEAT block, which is also the end of the transaction in the p-lock4.p procedure.
Progress releases EXCLUSIVELOCKs at the end of the transaction, making the record
available to other users.
customer in use by user1 on ttyi13. Wait or press CTRL-C to stop.
Cust-num Name Credit-Limit Sales-Rep Update OK?
1 Lift Line Skiing 66,800 HXM ______
Locks
1319
Imagine that, instead of EXCLUSIVELOCKing the customer record, the user at terminal 1
SHARELOCKed the record. Meanwhile, the user at terminal 2 came along and
SHARELOCKed the record. Now suppose that both users want to update the record. They
both need an EXCLUSIVELOCK on the record. But the user at terminal 1 cannot
EXCLUSIVELOCK the record because the other user has the record SHARELOCKed. And
the user at terminal 2 cannot EXCLUSIVELOCK the record because the other user has it
SHARELOCKed. This situation is known as deadly embrace. One of the two users must press
STOP to resolve the situation.
There are ways to avoid this situation. For example, if you know you are going to update a
record, you can read that record with EXCLUSIVELOCK. Alternatively, where you run a
reporting procedure, such as p-lock5.p, you might not need to see the data that is in flux. You
can use the NOLOCK option to tell Progress to let you see the record even if it is
EXCLUSIVELOCKed:
Try running the p-lock4.p procedure again. Once again, enter 1 as the customer number, make
any change to the customer record, and press GO. Now go to another terminal and run the
p-lock6.p procedure.
This time, Progress lets the p-lock6.p procedure see customer 1 because the NOLOCK option
ignores the EXCLUSIVELOCK placed on that customer record by the p-lock4.p procedure.
There are two functions you can use when working with locking situations: AVAILABLE and
LOCKED. See the Progress Language Reference for information and examples for using these
functions to manage record-locking conflicts.
p-lock6.p
FOR EACH customer NO-LOCK:
END.
1320
13.6 Managing Locks to Improve Concurrency
Rather than rely on default locking behavior, you can use a simple lock management algorithm
to:
Eliminate deadly embrace
Decrease the scope of transactions
Prevent users from tying up records for extended periods of time
Each time you want to present data to the user for inspection and possible update, follow this
procedure:
1. Request and display the record with the NOLOCK option.
2. Let the user manipulate the data until the user signals that they have finished (ON LEAVE
OF field, ON CHOOSE OF okbutton, or similar).
3. Request the same record again using the FIND CURRENT or GET CURRENT statement
with the EXCLUSIVELOCK option.
4. Use the CURRENTCHANGED function to see if the original record has changed since
you first presented it to the user.
5. If the record is the same, commit the change.
6. If the record has changed, inform the user, display the new data, and repeat the process.
Locks
1321
The code example below demonstrates this technique:
The first problem this technique avoids is the classic user at lunch syndrome. If the user
begins work on a SHARELOCK record and does not finish with it immediately, all other users
are prevented from updating the record. The FIND CURRENT technique moves the scope of
the transaction between possible user actions. In other words, no user interface manipulation can
tie up a record.
Making transactions smaller, or atomic, also improves performance and promotes modular code
design that can support many interface styles.
Finally, this technique avoids the deadly embrace problem. Deadly embrace occurs when two
users have the same record with SHARELOCK and both are waiting for the other to release
the record. Although this problem can be avoided by good design, using the FIND CURRENT
technique means that this will never be a problem.
p-lock13.p
FORM customer.name customer.balance WITH FRAME upd.
ON GO OF FRAME upd DO:
DO TRANSACTION:
FIND CURRENT customer EXCLUSIVE-LOCK.
IF CURRENT-CHANGED customer THEN DO:
MESSAGE "This record has been changed by another user"
SKIP
"Please re-enter your changes."
VIEW-AS ALERT-BOX.
DISPLAY customer.name customer.balance with frame upd.
RETURN NO-APPLY.
END.
ASSIGN customer.name customer.balance.
END.
FIND CURRENT customer NO-LOCK.
END.
DISPLAY customer.name customer.balance WITH FRAME upd.
DO ON ENDKEY UNDO, LEAVE:
ENABLE customer.name customer.balance WITH FRAME upd.
WAIT-FOR "GO" OF FRAME upd.
END.
1322
13.7 Changing the Size of a Transaction
Previous chapters showed how the size of a transaction affects how much work is undone or
recovered in the event of a system failure or an error (see Chapter 6, Handling User Input, and
Chapter 12, Transactions for information). Now you know that transactions and record locks
are closely related. Figure 135 shows how changing the size of a transaction affects record
locks.
p-txn3a.p
Figure 135: Transaction Size and Locks
In this procedure, the outer REPEAT block is the transaction block. The INSERT statement
creates an order record and gets an EXCLUSIVELOCK on that record. Progress holds that
lock until the end of the transaction block (the outer REPEAT block).
The UPDATE statement in the inner REPEAT block lets you update orderline records. While
you update orderline records, you still have an EXCLUSIVELOCK on the order record you
created at the start of the REPEAT block. Because of that lock, no other user can access that
order record until you finish updating orderline records and release your EXCLUSIVE lock
(and, in this case, the record as well) at the end of the outer REPEAT block.
REPEAT:
REPEAT:
CREATE order-line.
UPDATE order-line.order-num = order.order-num.
UPDATE line-num order-line.item-num.
END.
END.
Acquire lock
Release lock
EXCLUSIVE-
LOCK
Transaction
Locks
1323
It is also important to note that just prior to the end of each transaction, all of the orderline
records created are EXCLUSIVELOCKed and all of the item records found are
SHARELOCKed.
13.7.1 Making a Transaction Larger
In the last procedure, you EXCLUSIVELOCKed one order record at a time: you got an
EXCLUSIVELOCK when you INSERTed the record at the start of the outer REPEAT block.
At the end of the outer REPEAT block, Progress released that EXCLUSIVELOCK, making
the record available to other users.
Suppose you want to EXCLUSIVELOCK all the order records you create, retaining those
locks until you finish creating order records. You can do this by simply making the transaction
larger, as shown in Figure 136.
p-txn4.p
Figure 136: Making Transactions Larger
DO TRANSACTION:
REPEAT:
REPEAT:
CREATE order-line.
ASSIGN order-line.order-num = order.order-num.
UPDATE line-num order-line.item-num.
END.
END.
END.
Acquire lock
Release lock
EXCLUSIVE-
LOCK
Transaction
1324
The TRANSACTION option on the DO block overrides the default transaction placement.
Even though an outermost REPEAT, FOR EACH, or procedure block that contains direct
database updates normally is made the transaction block, the TRANSACTION option overrides
that default.
Now, you still get an EXCLUSIVELOCK when you INSERT an order record at the start of
the outer REPEAT block. But remember that Progress releases EXCLUSIVELOCKs at the
end of the transaction. When the REPEAT block ends, the transaction is not over, so Progress
retains the EXCLUSIVELOCK. When you INSERT the next record, you get another
EXCLUSIVELOCK on that record.
You can have many order and orderline records EXCLUSIVELOCKed, preventing other
users from accessing those records. You can also have many item records SHARELOCKed,
preventing other users from updating those records.
13.7.2 Making a Transaction Smaller
Now suppose that once you have EXCLUSIVELOCKed the order record at the start of the
outer REPEAT block, you want to release that lock as quickly as possible (before the end of the
block) so that other users can access that order record. You also want to release the
SHARELOCKs on the item records as soon as possible You can do this by simply making the
transaction smaller, as shown in Figure 137.
Locks
1325
p-txn10.p
Figure 137: Making Transactions Smaller
Progress starts a transaction for each order and also for each orderline you enter. When you
insert an order record at the start of the outer DO TRANSACTION block, Progress
EXCLUSIVELOCKs that record. Progress releases that EXCLUSIVELOCK at the end of
the transaction, which is at the end of the DO TRANSACTION block.
Now, other users can access the order record while you update orderline records. Each iteration
of the REPEAT TRANSACTION block is a transaction. That means that the CREATE
statement EXCLUSIVELOCKs the orderline record. Progress releases that lock at the end of
the REPEAT TRANSACTION block, making the orderline record available to other users.
REPEAT:
DO TRANSACTION:
END.
REPEAT TRANSACTION:
CREATE order-line.
ASSIGN order-line.order-num =
order.order-num.
UPDATE line-num
order-line.item-num
qty price.
END.
END.
EXCLUSIVE-
LOCK
Acquire lock Release lock
Transaction
Transaction
1326
14
Providing Data Security
As a developer, you can provide your Progress applications with application security that
prevents unauthorized users from running application procedures or accessing data in a
database.
Progress provides the following levels of application security:
Connection security ensures that only authorized users can connect to the database.
Schema security ensures that only authorized users can modify table, field, and index
definitions.
Compile-time security ensures that only authorized users can compile procedures that
perform specific data accesses.
Run-time security ensures that only authorized users can run specific precompiled
procedures.
The security administrator can define security for the first three levels (connection time,
schema, and compile time) in the Data Dictionary. For more information on security
administration, see the Progress Database Administration Guide and Reference and the
Progress Client Deployment Guide. As the developer, you can provide run-time security as
described in this chapter.
142
14.1 Progress User ID and Password
Each of the four levels of Progress application security requires user IDs and passwords. The
following sections describe the conventions for Progress user IDs and passwords, as well as how
to validate them.
14.1.1 User ID
A user ID is a string of up to 32 characters associated with a particular Progress database
connection. Like table names, user IDs must begin with a character from az or from AZ. The
name can consist of:
Alphabetic characters
Digits
The following special characters: # $ % & _
User IDs are not case sensitive: they can be uppercase, lowercase, or any combination of these.
You can establish the valid user IDs for a database through the Progress Data Dictionary.
A user ID can be blank, written as the string , but it cannot be defined as such through the
Data Dictionary.
14.1.2 Password
A password is a string of up to 16 characters that is associated with a user ID. When you add a
password through the Data Dictionary, the password is encoded with the ENCODE function.
Because ENCODE returns different values for uppercase and lowercase input, all Progress
passwords are case sensitive.
When using ENCODE with passwords, PSC strongly recommends:
Occurrences of the ENCODE function related to the same password run in the same code
page.
In environments with multiple code pages, programs use the CODEPAGECONVERT
function so that occurrences of the ENCODE function related to the same password run in
the same code page.
143
14.2 Validating Progress User IDs and Passwords
If the security administrator establishes a list of valid user IDs, then your application must
prompt the user for a user ID and password at connection time. Typically, an application does
this by running the standard Progress startup procedure, _prostar.p. This procedure, in turn,
runs the standard Progress authentication procedure, _login.p, for each connected database.
(Authentication is the process of verifying a users identity.)
The _prostar.p procedure also prepares _login.p to run appropriately in the current
application environment (character or graphical) and verifies that no connected databases have
the logical name DICTDB. This allows _prostar.p to assign the same alias (DICTDB) to each
connected database before calling _login.p. Then, _login.p can authenticate access as it is
called for each different database using the same database name.
144
This is the _login.p procedure:
_login.p
DEFINE INPUT PARAMETER viewAsDialog AS LOGICAL NO-UNDO.
{ login.i }
DEFINE VARIABLE tries AS INTEGER NO-UNDO.
IF USERID("DICTDB") <> "" OR NOT CAN-FIND(FIRST DICTDB._User) THEN
RETURN.
DO ON ENDKEY UNDO, LEAVE:
currentdb = LDBNAME("DICTDB").
/* reset id and password to blank in case of retry */
ASSIGN id = ""
password = "".
if viewAsDialog then do:
DISPLAY currentdb WITH FRAME logindb_frame view-as dialog-box.
UPDATE id password ok_btn cancel_btn help_btn
WITH FRAME logindb_frame view-as dialog-box.
end.
else do:
DISPLAY currentdb WITH FRAME login_frame.
UPDATE id password ok_btn cancel_btn help_btn
WITH FRAME login_frame.
end.
IF SETUSERID(id,password,"DICTDB") <> TRUE THEN DO:
MESSAGE "Userid/Password is incorrect."
VIEW-AS ALERT-BOX ERROR BUTTONS OK.
IF tries > 1 THEN
QUIT. /* only allow 3 tries*/
tries = tries + 1.
UNDO, RETRY.
END.
END.
HIDE FRAME login_frame.
145
The _login.p procedure uses the Progress SETUSERID function to check the user ID and
password that the user enters. The user has three tries to enter the correct user ID and password
for each database. If the user fails to do so after three tries, Progress exits the user from the
database. If the user ID and password combination is valid for the database, SETUSERID
establishes that user ID for the connection.
The input parameter for _login.p allows it to display the authentication prompts either in a
dialog box (viewAsDialog = TRUE) or in the frame of a separate window (viewAsDialog =
FALSE). The _prostar.p procedure uses a separate window in graphical environments and the
default window in character environments, so it always passes FALSE as an argument to
_login.p.
As explained earlier, the _login.p procedure only works for a database with the DICTDB alias.
(By default, this alias is assigned to the first database you connect to during a session.) If you
want to avoid this restriction, you can create your own procedures, based on _prostar.p and
_login.p, that pass an argument for the database name.
If the application does not run _prostar.p at connection time, or if the user bypasses _login.p
(by pressing ENDERROR when prompted for the user ID and password), then the user is
assigned the blank user ID. While blank user IDs can connect to the database, they cannot access
data protected by compile-time and run-time security.
If you connect to a database dynamically using the CONNECT statement, you can use the User
ID (U) and Password (P) connection parameters in the CONNECT statement, or you can use
the SETUSERID function after the connection.
146
The following procedure connects to the mywork database that has a list of valid users. The user
initially connects to the database with a blank user ID. The code then enters a loop that forces
the user to provide a valid user ID and password for that database:
p-passts.p
DEFINE VARIABLE passwd AS CHARACTER FORMAT "x(16) LABEL "Password".
DEFINE VARIABLE success AS LOGICAL.
DEFINE VARIABLE user-id AS CHARACTER FORMAT "x(32)" LABEL "User ID".
CONNECT mywork.
success = FALSE.
DO WHILE NOT success:
MESSAGE "Enter a user ID and password for the database mywork.".
SET user-id passwd BLANK.
IF SETUSERID(user-id, passwd, "mywork")
THEN success = TRUE.
ELSE DO:
BELL.
MESSAGE "Invalid user ID and password; please try again.".
END.
END.
147
14.3 Run-time Security
To ensure that only authorized users can run certain procedures in your application, you can
provide run-time security to check the user ID of the user attempting to run a procedure.
14.3.1 Checking for User IDs
This sections shows some examples of procedures that you can use to check for user IDs. The
following procedure uses _prostar.p:
p-csmnu3.p
DEFINE VARIABLE selection AS INTEGER FORMAT "9".
RUN _prostar.p.
REPEAT:
FORM SKIP(2) " M A I N M E N U"
SKIP(1) " 1) Add a new customer"
SkIP(1) " 2) Change customer Information"
SkIP(1) " 3) Display orders"
SKIP(1) " 4) Create mailing labels"
SKIP(1) " 5) Delete a customer"
SKIP(1) " 6) EXIT"
WITH CENTERED TITLE "Maintenance and Reporting".
UPDATE SKIP(2) SPACE(1) selection AUTO-RETURN
WITH SIDE LABELS.
HIDE.
IF selection EQ 1 THEN RUN p-adcust.p.
ELSE IF selection EQ 2 THEN RUN p-chcust.p.
ELSE IF selection EQ 3 THEN RUN p-itlist.p.
ELSE IF selection EQ 4 THEN RUN p-rept6.p.
ELSE IF selection EQ 5 THEN RUN p-delcus.p.
ELSE IF selection EQ 6 THEN QUIT.
ELSE MESSAGE "Incorrect selection - please try again".
END.
148
This procedure defines user access by first running the _prostar.p procedure before displaying
the following main menu in a character environment.
Suppose you want to define, on a per procedure basis, the individuals who can run each of the
Maintenance and Reporting menu procedures. You can use the CANDO function to check the
user ID(s) established by _prostar.p. The p-adcust.p procedure allows you to enter customer
information:
If you want to limit the use of this procedure to users with a user ID of manager or salesrep, you
can modify the procedure as follows to include security checking:
p-adcus2.p
p-adcust.p
REPEAT:
END.
Enter data or press F4 to end.
Maintenance and Reporting
M A I N M E N U
1) Add a new Customer
2) Change customer information
3) Display orders
4) Create mailing labels
5) Delete customer
6) EXIT
Selection: __
IF NOT CAN-DO("manager, salesrep")
THEN DO:
MESSAGE "You are not authorized to run this procedure.".
RETURN.
END.
REPEAT:
END.
Security
Checking
p-adcust.p
149
The first part of p-adcus2.p handles security checking that ensures the user is authorized to run
the procedure. The CANDO function compares the values listed in the parentheses against the
user ID attempting to run the procedure. If the user ID does not match any of the values listed,
the procedure displays a message and exits. If the user ID does match one of the values, the
procedure continues executing.
The ID list you provide in the CANDO function is a comma-separated list of user ID tokens.
You can use tokens to indicate specific users who have or do not have access. Table 141 lists
the types of tokens you can specify.
For more information on the CANDO function, see the Progress Language Reference.
You can also use the USERID function to check user IDs in a procedure. Use this function when
you want to allow only one user ID access to a procedure:
p-adcus3.p
If the user ID of the user running the procedure is not manager, the procedure displays a message
and exits. If the user ID is manager, the procedure continues.
Table 141: Values to Use for ID Lists
Value Meaning
* All users are allowed access.
user This user has access.
!user This user does not have access.
string* Users whose IDs begin with string have access
!string* Users whose IDs begin with string do not have access
IF USERID <> "manager"
THEN DO:
RETURN.
END.
REPEAT:
END.
Security
Checking
p-adcust.p
1410
If you use either the CANDO function or the USERID function to compare the user ID of a
user with one or more user IDs you include in a procedure, you must modify and recompile that
procedure whenever you change the user IDs allowed access to it. You can avoid having to
make these changes by building a permissions table for activities in your application.
NOTE: If you connect to more than one database, the USERID function requires a logical
database name and the CANDO function requires a user ID qualification. For more
information on multiple-database considerations, see Chapter 9, Database Access.
14.3.2 Defining Activities-based Security Checking
Applications that you write probably break down into several areas or activities. For example,
you may have one set of procedures that handles customer activities, and another set that
handles inventory activities. For each set of activities, you may want to establish a valid group
of users. To do this, you build a permissions table. To establish and use a permissions table, you
must:
Create a table that defines the kinds of access different users have to application activities.
Include statements in application procedures to check the permissions table at run time.
Write a procedure that can modify access permissions.
Creating an Application Activity Permissions Table
You create a permissions table within the Data Dictionary. This chapter calls the table
permissions, but you can use any name you want. Each record in the permissions table contains
at least two fields: an activity field and a canrun field. The activity field contains the name of
the procedure and the canrun field contains a comma-separated list of the user IDs of those
users who have permission to run the procedure. Normally, the primary index is built on the
activity field.
After you create a permissions table, you must add a record for every application activity for
which you want to provide security.
Adding Records to the Permissions Table
To create records for the permissions table, you must first determine the users and the activities.
The users are identified by their user IDs, and the activities by specific procedures or
subsystems.
1411
In the following example, three user IDsmanager, salesrep, and inventoryare given
permission to perform the following activities:
Add new customers to the database by running p-adcust.p. Manager and salesrep have
permission.
Update records in the database by running p-chcust.p. Manager and salesrep have
permission.
Remove customer records from the database by running p-delcus.p. Manager has
permission.
The order report and mailing label procedures (p-itlist.p and p-rept6.p) are grouped
into a subsystem called print. Manager and inventory have permission.
To add these application activities as records to the permissions table, you can write a simple
Progress procedure:
This procedure lets you add records of activities to the permissions table until you press
ENDERROR.
Figure 141 shows records of application activities that you can add to the permissions table.
Figure 141: Sample Activity Permissions Entries
After you create these records of application activities, you must include statements in your
procedures that check them at run time. After that, the security administrator is responsible for
maintaining these records.
p-prmsn.p
REPEAT:
INSERT permissons.
END.
p-adcust.p
p-chcust.p
p-delcus.p
print
manager, salesrep
manager, salesrep
manager
manager, inventory
Can-Run Activity
1412
Including Security Checking in Procedures
When the user runs a procedure, you can check the permission for the activity associated with
the procedure. Specifically, you:
Find the activity record in the permissions table.
Compare the permissions for the activity with the user ID of the user running the
procedure.
If there is a match for the user ID, allow access. Otherwise, display a message and exit
from the procedure.
Figure 142 shows what happens when the user with user ID manager runs the p-adcust.p
procedure.
Figure 142: User with Permission to Run a Procedure
p-adcust.p
p-adcust.p
Add
Customer
Records
Add
Customer
Records
User: manager
OK to RUN
p-adcust.p
record
Can-Run:
manager
salesrep
Permissions
Table
1413
When the user ID and the permission defined in the p-adcust.p record in the permissions table
match, the manager can run the procedure. Figure 143 shows what happens when the user with
user ID inventory tries to runs p-adcust.p. Because there is no match, the procedure displays
a message and the user cannot run the remaining code.
Figure 143: User Without Permission to Run a Procedure
p-adcust.p
p-adcust.p
Add
Customer
Records
User: inventory
Not OK to RUN
p-adcust.p
record
Can-Run:
manager
salesrep
Permissions
Table
1414
You use the CANDO function to do security checking in your procedure. The procedure
p-adcus4.p is a modified version of the p-adcust.p procedure that includes activity-based
security checking:
p-adcus4.p
The first part of this procedure makes sure the user is authorized to run the procedure. The FIND
statement reads the permission record for the p-adcust.p procedure. The CANDO function
compares the value of the canrun field in the record with the user ID of the user running the
procedure. If the values do not match, the procedure displays a message and exits. If there is a
match, the procedure allows the user to add customer records.
Progress checks privileges within a DO FOR block to ensure that the record read by the FIND
statement is held only during that block, rather than during the entire procedure. In addition, the
NOLOCK option ensures that other users can access or update the permissions table while this
procedure is running.
The part of the p-adcust.p procedure that does security checking is standard. For example, you
could include the same security checking statements in the procedures p-chcust.p and
p-delcus.p, if you change the name of the activity record being read in the permissions table:
p-delcs2.p
DO FOR permission:
FIND permission "p-adcust.p" NO-LOCK.
IF NOT CAN-DO(can-run)
THEN DO:
RETURN.
END.
END.
REPEAT:
END.
Security
Checking
p-adcust.p
DO FOR permission:
FIND permission "p-delcs.p" NO-LOCK.
THEN DO:
RETURN.
END.
END.
PROMPT-FOR customer cust-num.
DELETE customer.
Security
Checking
p-delcus.p
1415
The following procedure shows how you can modify a print procedure, such as p-itlist.p,
and add security checking to it:
p-itlst2.p
Here, the FIND statement reads the print record from the permissions table. The CANDO
function compares the value of the canrun field with the user ID of the user running the
procedure. If there is no match, the procedure displays a message and exits. If there is a match,
the procedure displays order information.
Remember, there is no separate record in the permissions table for the p-itlst2.p procedure.
However, you can use the record for the print activity to handle security for any procedure that
you specify as a print activity. You can include the same security checking statements in any
other procedure that you consider to be a print activity, such as p-rept6.p:
p-rept6.p
OUTPUT TO mail.lst.
FOR EACH customer WHERE curr-bal >= 1400 BY zip:
PUT contact SKIP
name SKIP
address SKIP.
IF address2 NE "" THEN PUT address2 SKIP.
PUT city + ", " + st + " " + STRING(zip," 99999") FORMAT "X(23)"
SKIP(1).
IF address2 EQ "" THEN PUT SKIP(1).
END.
DO FOR permission:
FIND permission "print" NO-LOCK.
THEN DO:
RETURN.
END.
END.
FOR EACH customer WHERE credit-limit > 50000 BY postal-code:
DISPLAY name address city state postal-code credit-limit
WITH SIDE-LABELS.
DISPLAY order WITH SIDE-LABELS.
FOR EACH order-line OF order, item OF order-line:
DISPLAY line-num item.item-num item-name
qtyorder-line.price WITH SIDE-LABELS.
END.
END.
END.
Security
Checking
p-itlist.p
1416
For application maintenance purposes, you might want to put security checking statements into
an include file. Procedures that require security checking can simply include that file, passing
the activity as an argument. The following is an example of a such an include file:
Protecting and Maintaining the Permissions Table
To protect the permissions established in the permissions table, you can provide the security
administrator with the following procedures:
A procedure that defines who can modify the permissions table. Initially, you can run this
procedure and enter the user ID of the security administrator, as well as user IDs of those
authorized to modify the permissions table.
A security update procedure (for example, p-secupd.p) that the security administrator or
other authorized users can run to modify permissions for specific procedures and
functions.
To do security checking, these procedures require a record in the permissions table associated
with the activity of maintaining security. Figure 144 shows an example security record in the
permissions table.
Figure 144: Sample Security Record for Activity Permissions
p-chkprm.i
DO for permissions:
FIND permissions {1} NO-LOCK.
IF NOT CAN-DO (can-run)
THEN DO:
MESSAGE "You are not authorized to run this procedure".
RETURN.
END.
END.
security *
Can-Run Activity
1417
When you create the security record, initialize the canrun field with an asterisk. This means
that, initially, any user can run the security administration procedure (p-secadm.p). However,
after you run it and enter the authorized user IDs, only the authorized users can change the
security record:
p-secadm.p
The authorized users can also run the next procedure, p-secupd.p, which updates permissions
for procedures and activities:
p-secupd.p
The first part of p-secupd.p checks the security record in the permissions table to make sure
that the user is authorized to run the procedure. If the user is not authorized, the procedure
displays a message and exits. Otherwise, the second part of p-secupd.p permits the user to
modify the canrun field for a specified activity.
FIND permission "security".
THEN DO:
RETURN.
END.
DISPLAY "Please enter one or more security ids"
"for the security administrator,"
"separating the ids with commas" SKIP(1).
UPDATE can-run.
Security
Checking
DO FOR permission:
FIND permission "security" NO-LOCK.
THEN DO:
RETURN.
END.
END.
REPEAT FOR permission:
PROMPT-FOR activity.
FIND permission USING activity.
UPDATE can-run.
END.
Security
Checking
1418
Figure 145 summarizes the security process developed for procedures and functions in an
application.
Figure 145: Summary of Run-time Security Process
1. The developer creates a record in the
database for each application activity,
including security administration.
2. The developer assigns one or more
authorized users for each activity,
including security administration.
3. The security administrator maintains
and updates permissions for
procedures and activities.
Activity: security
Can-run: *
Permissions Table
p-secadm.p
p-secupd.p
15
Work Tables and Temporary Tables
The Progress 4GL provides two structures that can be used to manipulate table information:
work tables and temporary tables. Temporary tables can be further sub-divided into static
temporary tables and dynamic temporary tables.
This chapter explains:
Work tables
Temporary tables
A comparison between these two temporary structures and database tables
Dynamic temporary tables
152
15.1 Work Tables
This section explains how to use work tables to do the following:
Produce categorized reports when you do not know the value of each possible category
until you have made a pass through the table.
Collect information from a number of records and then do calculations on that
information.
Do complex sorting on summarized information.
Produce cross-tab reports.
Simplify array manipulation, coding, and the use of dynamic variables.
NOTE: You cannot access work tables using SQL statements.
15.1.1 Characteristics of Work Tables
Work tables are to database tables what variables are to database fields. Like a variable, a work
table:
Must be defined in any procedure that uses it.
Is a temporary structure stored in memory rather than in the database, and can either be
local to a single procedure or shared among multiple procedures.
Can be defined to be LIKE a database table (much like a variable can be defined to be
LIKE a database field). Work tables also have the option to adopt the same dictionary
validation specified for the corresponding database table.
Does not have indexes, therefore you cannot do a FIND work-table. However, you can do
a FIND FIRST work-table.
NOTE: Because Progress stores and processes work tables in memory, the number of work
tables and the number of records in a work table that you can use is limited by the
memory available on your system.
153
15.1.2 Producing Categorized Reports
Control break reports list information broken down into categories. For example, items in the
sports database are assigned to catalog pages. Every item also has an onhand value (how many
items are in inventory) and a price. The p-wrk1.p procedure produces a report that lists the value
of the inventory for each catalog page:
This procedure produces the following report.
p-wrk1.p
FOR EACH item BREAK BY cat-page:
ACCUMULATE price * on-hand (SUB-TOTAL BY cat-page).
IF LAST-OF(cat-page)
THEN DISPLAY cat-page ACCUM SUB-TOTAL BY cat-page (price * on-hand).
END.
Cat-Page TOTAL
---------- ----------
0 21,992.16
1 8,489.92
3 450.00
4 12,377.40
5 10,575.00
6 1,445.52
7 1,615.27
8 1,367.10
11 7,339.40
12 2,250.00
13 854.00
14 2,074.83
15 587.50
16 256.86
17 325.71
154
The control break (BREAK BY catpage) in this procedure logically separates the item table
into catalog pages. However, because you do not know what all the catalog pages are, or even
how many catalog pages there are, the procedure must make two passes through the table:
The BREAK keyword causes the first pass through the table. Progress sorts the item table
and writes a sorted list to a temporary file (called a sort file). Progress determines at what
points in the list the catpage value changes.
The second table pass occurs when Progress goes through the sort file, using the ROWIDs
stored in that file to read item records from the item table. The ROWID is the internal
database identifier that Progress associates with every database record.
Figure 151 shows how the procedure processes the item table.
Figure 151: Processing a Table for a Categorized Report
Item-Num Cat-Page
00001 12
00002 14
00003 11
00004 5
. .
. .
. .
Item Table
Item-Num Cat-Page
00055 0
00039 0
00053 0
00035 0
. .
. .
. .
Item Table
First Pass
Read each record in the
item table and store the
cat-page values for each
record in the sort file.
Then sort the table by
cat-page.
Second Pass
Use the ROWID values
from the sort file to read
the item records in the
appropriate order.
Cat-Page ROWID
0 4932
0 4911
0 4930
0 4907
. .
. .
. .
Sort File
Cat-Page ROWID
0 4932
0 4911
0 4930
0 4907
. .
. .
. .
Sort File
155
The following procedure uses work tables to produce the same report:
The numbers in the margin of the procedure correspond to the following activities:
1. The DEFINE WORKTABLE statement defines a work table, cpage, that contains two
fields, wcatpage and winvvalue. The wcatpage field has the same definition as the
catpage field in the item table.
2. For each of the records in the item table, the procedure checks whether there is a cpage
record for the page to which the item belongs. If there is not, the procedure creates a cpage
record and stores the catpage value in the cpage record.
3. The = (ASSIGNMENT) statement accumulates the value of the inventory for each catalog
page by adding the inventory value of the current item to the existing inventory value for
the page (winvvalue).
4. The FOR EACH block sorts the cpage table and displays the inventory value of each
catalog page.
p-wrk2.p
/* 1 */
DEFINE WORK-TABLE cpage
FIELD w-cat-page LIKE item.cat-page
FIELD w-inv-value AS DECIMAL FORMAT "->>>,>>>,>>9.99"
LABEL "Inventory Value".
/* 2 */
FOR EACH item:
FIND FIRST cpage WHERE cpage.w-cat-page = item.cat-page NO-ERROR.
IF NOT AVAILABLE cpage
THEN DO:
CREATE cpage.
cpage.w-cat-page = item.cat-page.
END.
/* 3 */
cpage.w-inv-value = cpage.w-inv-value + (item.price * item.on-hand).
END.
/* 4 */
FOR EACH cpage BY w-cat-page:
DISPLAY w-cat-page w-inv-value.
END.
156
Figure 152 shows the table processing this procedure performs.
Figure 152: Using Work Tables to Produce a Categorized Report
The work table version of the procedure also makes a pass through the item table. But it does
not need to first sort the entire item table since it can create new work table records for each new
catalog page as it encounters that page. The procedure then makes a pass through the cpage
Item-Num Cat-Page
00001 12
00002 14
00003 11
00004 5
. .
. .
. .
Item Table
w-cat-page
12
14
11
5
.
.
.
cpage Table
w-cat-page
12
14
11
5
.
.
.
cpage Table
First Pass
item table and create a
corresponding record in
the cpage table.
w-cat-Page ROWID
0 -1014
1 -1019
2 -1017
3 -1015
. .
. .
. .
Sort File
w-cat-page
0
1
2
3
.
.
.
cpage Table
Third Pass
Use the ROWID values
from the sort file to read
and display cpage table
records in the appropriate
order.
Second Pass
cpage table and store the
w-cat-page values in the
sort file. Then sort the data
by w-cat-page.
157
work table, building a sort file for that table. (Note that ROWIDs for work tables are always
negative.) Finally, the procedure makes a second pass through the cpage table, retrieving the
cpage records in the appropriate order.
You wonder: If the p-wrk1.p procedure makes two table passes and the p-wrk2.p procedure
makes three table passes, why is the work table procedure any better than the procedure that uses
only database tables? There are two reasons:
The cpage table is far smaller than the item table (in a typical database). Therefore, a pass
through the cpage table takes much less time than a pass through the item table.
Progress performs all processing for work tables in memory so processing is faster than
for database tables.
15.1.3 Using Work Tables to Collect and Manipulate Data
Suppose that you want to add another step to the report shown in the previous section. In the
new report, you want to:
Display the inventory value of each catalog page (as in the previous example).
Display the inventory value for the item with the largest inventory value in each catalog
page.
To prepare this report without using work tables, you have to use variables to keep track of the
item quantities as well as the item inventory values. The number of variables you need depends
on the number of pages in the catalog. You might not know this number when you write the
procedure. When you use work tables, you can store item quantities and inventory values in
fields in the work table.
158
The numbers in the margin of the procedure correspond to the following activities:
1. The DEFINE WORKTABLE statement defines a work table, cpage, which contains four
fields, wcatpage (the work table catalogpage), winvvalue (the work table
inventoryvalue), witemvalue (the inventory value of a particular item), and
witemnum (the item number).
2. For each of the records in the item table, the procedure checks whether there is a cpage
record for the catalog page to which the item belongs. If there is not, the procedure creates
a record and stores the catpage value in the cpage record.
p-wrk3.p
/* 1 */
LABEL "Inventory Value"
FIELD w-item-value AS DECIMAL FORMAT ">>>,>>9.99"
LABEL "Item Inv. Value"
FIELD w-item-num LIKE item.item-num.
/* 2 */
FOR EACH item:
THEN DO:
CREATE cpage.
END.
/* 3 */
IF price * on-hand > w-item-value
THEN DO:
ASSIGN w-item-value = price * on-hand
w-item-num = item.item-num.
END.
/* 4 */
END.
/* 5 */
FOR EACH cpage BY w-cat-page:
DISPLAY w-cat-page w-inv-value w-item-num w-item-value.
END.
159
3. If the value of the current item is greater than the value of any previous item for the same
page, the ASSIGN statement stores the value and number of that item in the corresponding
work table fields.
4. This statement accumulates the inventory value for the catalog page.
5. The FOR EACH block displays the inventory value of each page and the number and value
of the highest value item on that page.
Using work tables allows you to sort on any value. For example, if you want to sort on the
inventory value of the catalog pages, use the BY winvvalue option on the FOR EACH block.
Without work tables, you cannot do this sort as easily.
15.1.4 Using Work Tables for Complex Sorting
Progress uses indexes to order database records. Although work tables have no indexes, you can
position work table records where you want because whenever you create a work table record,
Progress places it after the record that it found last in that work table. This flexibility lets you
keep the work table records in a particular order without having to sort later in the procedure.
For example, p-wrk4.p is a modified version of the p-wrk3.p procedure:
1510
This procedure uses the following logic to maintain the cpage work table in catalog page order:
1. The FIND FIRST statement tries to find a cpage record whose catalog page is the same or
greater than that of the current item.
2. If the catalog page of the cpage record is larger than that of the current item, or if the cpage
record does not exist, Progress finds the previous cpage record (if any) and creates the new
cpage record after that record in the work table. If it finds a cpage record with the same
product line as the item, it does not create a new cpage record, but uses the existing one.
3. The procedure computes the necessary field values for the current cpage record.
p-wrk4.p
LABEL "Inventory Value"
FIELD w-item-value AS DECIMAL FORMAT ">>>,>>9.99"
LABEL "Item Inv. Value"
FIELD w-item-num LIKE item.item-num.

FOR EACH item:
FIND FIRST cpage WHERE cpage.w-cat-page >= item.cat-page NO-ERROR.

IF NOT AVAILABLE cpage OR cpage.w-cat-page > item.cat-page
THEN DO:
FIND PREV cpage NO-ERROR.
CREATE cpage.
END.

IF price * on-hand > w-item-value
THEN DO:
ASSIGN w-item-value = price * on-hand
w-item-num = item.item-num.
END.

END.
FOR EACH cpage:
DISPLAY w-cat-page w-inv-value w-item-num w-item-value.
END.
1511
Figure 153 shows how this procedure keeps the cpage work table in order by product line.
Figure 153: Maintaining Work Tables in Sorted Order
By maintaining the cpage table in catalog page order as the procedure creates new cpage
records, there is no need to sort the table in the final FOR EACH block. When that block
displays the cpage records, they are already sorted by catalog page.
2nd iteration of
FOR EACH item
CREATE cpage
1st iteration of
FOR EACH item
CREATE cpage
3rd iteration of
FOR EACH item
CREATE cpage
4th iteration of
FOR EACH item
CREATE cpage
Item-num cat-page
00001 12
Item Table
Item-num cat-page
00001 12
00002 14
Item Table
Item-num cat-page
00001 12
00002 14
00003 11
Item Table
Item-num cat-page
00001 12
00002 14
00003 11
00004 5
Item Table
cat-page Item-num
12 00001
cpage Table
cat-page Item-num
12 00001
14 00002
cpage Table
cat-page Item-num
11 00003
12 00001
14 00002
cpage Table
cat-page Item-num
5 00004
11 00003
12 00001
14 00002
cpage Table
1512
There is another advantage to using this method of sorting as opposed to the method used in
p-wrk3.p. Figure 154 illustrates this advantage.
p-wrk3.p
p-wrk4.p
Figure 154: Comparing Two Sorting Methods
In Method 2, because the records in the cpage table are already in sorted order, the find is much
more efficient than in Method 1. For an item with a catalog page that already exists in the cpage
table, both methods are equally efficient, on average.
cat-page
12
14
11
5
.
.
.
cpage Table
FOR EACH item:
FIND FIRST cpage WHERE cpage.w-cat-page cat-page NO-ERROR.
.
.
.
p-wrk3.p
=
If item.cat-page = 10, this FIND
statement must read each record in
the cpage table, discover that there is
no cpage record for catalog page 10,
and then create a new cpage record.
Method 1
FOR EACH item:
FIND FIRST cpage WHERE cpage.w-cat-page cat-page NO-ERROR.
.
.
.
p-wrk4.p
If item.cat-page = 10, this FIND
statement reads only the first and
second records before creating a
new cpage record.
Method 2
cat-page
5
11
12
14
.
.
.
cpage Table
>=
1513
15.1.5 Using Work Tables for Cross-tab Reports
A cross-tab report typically lists information in tabular (or spreadsheet) format. For example,
suppose you want a report that breaks down order values by catalog page and sales rep. The
report might look like the following.
This report lists the order value for each of the catalog page for each of three sales reps.
1514
There are two ways to produce this report without using work tables:
Usually, your report has more rows than columns or more columns than rows. If the
number of rows is larger than the number of columns, sort the records represented by each
row (for example, catalog page) and then accumulate values acquired during that sort into
an array whose elements represent each of the columns (for example, the order value for
each sales rep).
Displays results whenever Progress encounters a new catalog page value.
Using work tables simplifies the task of producing cross-tab reports: you do not have to sort the
data and you do not have to be concerned with the dimensions of the table as you do when using
arrays. The p-wrk5.p procedure produces this report using work tables:
p-wrk5.p
FIELD w-cat-page LIKE item.cat-page FORMAT ">9"
FIELD w-ord-value AS DECIMAL FORMAT "->>>,>>9.99" EXTENT 4.
DEFINE VARIABLE rep-code AS INTEGER.
DEFINE VARIABLE rep-names AS CHARACTER INITIAL "BBB,DKP,SLS".

FOR EACH order, customer OF order, EACH order-line OF order,
item OF order-line:


THEN DO:
CREATE cpage.
END.

rep-code = LOOKUP(customer.sales-rep, rep-names).
IF rep-code = 0
THEN rep-code = 4.
w-ord-value[rep-code] = w-ord-value[rep-code] +
(order-line.price * order-line.qty).
END.
FOR EACH cpage BY cpage.w-cat-page:
FORM HEADER "Page" "BBB" AT 15 "DKP" AT 29 "SLS" AT 43 "Others" AT 54
WITH TITLE "Order Value by Catalog Page and Sales Rep" NO-LABELS.
DISPLAY w-cat-page w-ord-value.
END.
1515
15.2 Temporary Tables
This section contains the following information on temporary tables:
Characteristics of temporary tables
Defining temporary tables
Using database tables, temporary tables, and work tables
Comparison of database tables, temporary tables, and work tables
Defining indexes for temporary tables
Shared and global shared temporary tables
Temporary tables as parameters
Example of a procedure that defines a temporary table
15.2.1 Characteristics of Temporary Tables
Temporary tables are database tables that Progress stores in a temporary database. You define
temporary tables as you do work tables. Unlike work tables, temporary tables have indexes and
perform at the speed of regular database tables. Unlike regular database tables, which are
permanent and which multiple users can access simultaneously, temporary tables last only for
the duration of the procedure that defines them (or for the duration of the Progress session, if
you make them GLOBAL), and allow only one user at a time to access them. Finally, temporary
tables are private, visible only to the user (process) that creates them. In short, if you want to
sort, search, and process data for a duration not longer than the Progress session, use temporary
tables.
Progress stores temporary tables and temporary files in the same directoryby default, your
current working directory. You can change this directory by using the Temporary Directory
(T) startup parameter.
Temporary tables require less memory than large work tables. The Buffers for Temporary
Tables (Bt) startup parameter allows you to set the size of the buffer that Progress uses to
control temporary tables. For more information on the Bt parameter, see the Progress Startup
NOTE: You cannot access temporary tables using SQL statements.
1516
15.2.2 Defining a Temporary Table
You define a temporary table by using the DEFINE TEMPTABLE statement. For example,
the following statement defines temporary table TempCust that inherits the field definitions of
table Customer, which must belong to a database that is connected.
Using the DEFINE TEMPTABLE statement, you can define a temporary table that:
Inherits the field definitions of an existing database table, or has the fields you define
explicitly
Inherits the index definitions of an existing table, or has the indexes you define explicitly
Lasts only as long as the procedure that creates it, or as long as the Progress session
Is private to a single procedure, or shared among several procedures
For more information on the DEFINE TEMPTABLE statement, see its reference entry in the
15.2.3 Using Database, Temporary, and Work Tables
Database tables provide data storage in a permanent database and can be accessed by single or
multiple users. However, if you want to process data for the duration of a procedure in complete
privacy, use temporary tables or work tables. Temporary tables have several advantages over
work tables:
Temporary tables perform like database tables.
Because temporary tables have indexes, you can use statements that require indexes, such
as FOR EACH or a simple FIND.
Temporary tables are not limited to the value of the buffer size defined by the Bt
parameter. Progress stores any overflow of temporary table records to disk. Work tables,
however, are limited by the amount of memory available on your system.
DEFINE TEMP-TABLE Temp-Cust LIKE Customer.
1517
You can pass a temporary table as a parameter when you call a procedure. In fact, if you
want to call a Progress AppServer passing it a table of data, you must pass the data as a
temporary table. There is no other way. For more information on Progress AppServers, see
Building Distributed Applications Using the Progress AppServer. For more information
on temporary tables as parameters, see the Temporary Tables As Parameters section in
this chapter.
There are some situations where you might want to use work tables:
If you want to process a small number of records (for example, 50 or less) and you do not
have to order or sort the data.
If your existing applications use work tables and you want to maintain compatibility with
these applications. Note that if you rewrite existing applications (that use work tables) so
that they now use temporary tables, remember that temporary tables inherit index layouts
defined for the LIKE table. If you do not want this result, you must define your own
indexes.
Table 151 compares database tables, temporary tables, and work tables.
Table 151: Database, Temporary, and Work Tables (1 of 2)
Progress
Feature
Database
Table
Temporary
Table
Work
Table
Database manager Progress uses the database
manager in a single- or
multi-user mode when
working with database
tables.
Progress uses the database
manager in single-user
mode to access the
temporary database that
contains the temporary
tables.
Progress does not use the
database manager when
working with work tables.
Work tables are stored in
memory.
Indexes You can define indexes for
database tables.
You can define indexes for
temporary tables.
You cannot define indexes
for work tables.
Record deletion To remove database
records from the database,
you must explicitly delete
them with the DELETE
statement.
If you do not explicitly
delete records in the
temporary table, Progress
discards those records and
the temporary table itself at
the end of the procedure or
session that initially
defined the temporary
table.
If you do not explicitly
delete records in a work
table, Progress discards
those records and the work
table itself at the end of the
procedure that initially
defined the work table.
1518
The following sections describe in greater detail the similarities and differences between
temporary tables and work tables, as well as how to define indexes for temporary tables.
Record movement A database table can move
data between a record
buffer and a database
record.
A temporary table cannot
move data between a
record buffer and a
database record.
Work tables cannot move
data between a record
buffer and a database
record.
Multi-user record
access
Multiple users can access
the same database table at
the same time.
Users do not have access to
each others temporary
tables.
Users do not have access to
each others work tables.
Transactions Progress automatically
starts transactions for
certain blocks and
statements.
Database tables use the
before-image file to roll
back changes.
You must start transactions
explicitly.
Temporary tables use the
local before-image file to
roll back changes.
You must start transactions
explicitly.
Work tables use the local
before-image file to roll
back transactions.
Buffer size Use the B parameter to
specify the database table
buffer size.
Use the Bt parameter to
specify the temporary table
buffer size.
Available memory
determines the work table
buffer size.
Location Database tables are stored
directly in the database.
Temporary tables are
stored in the directory
where Progress stores
temporary files.
Work tables are stored in
memory.
Special data type
support
You can store RAW and
RECID fields, but not
ROWID fields, in a
database table.
You can store RAW,
ROWID, and RECID
fields in a temporary table.
You can store RAW,
ROWID, and RECID
fields in a work table.
Triggers and
Events
Database tables support
triggers and events.
Temporary tables do not
support triggers and
events.
Work tables do not support
triggers and events.
Table 151: Database, Temporary, and Work Tables (2 of 2)
Progress
Feature
Database
Table
Temporary
Table
Work
Table
1519
15.2.4 Similarities Between Temporary and Work Tables
Temporary tables and work tables have the following similarities:
You create temporary tables and work tables with a DEFINE statement, and they are
scoped to the procedures that define them. When you specify the LIKE table option, both
inherit the attributes of the specified database table (table). This optionally includes all
Data Dictionary validation for the table (using the VALIDATE option). However,
temporary tables and work tables do not inherit schema triggers from the database table.
The NEW SHARED and SHARED options allow two or more procedures to access the
same temporary tables and work tables.
Update statements, such as UPDATE, CREATE, and DELETE, that reference a
temporary table or a work table do not require a transaction to be active. If you want a
temporary table or a work table to participate in a transaction, you must explicitly start a
transaction for it.
The UNDO and NOUNDO options allow you to decide whether to incur the overhead
associated with transaction and nested UNDO processing.
Whenever a Progress session ends due to a crash or a QUIT statement, Progress deletes all
records in temporary tables (and the temporary database itself) and all records in work
tables.
15.2.5 Differences Between Temporary and Work Tables
Temporary tables and work tables have the following differences:
When you define temporary tables with the LIKE option and do not explicitly specify
indexes for them, they inherit index information from the database table. Work tables do
not have index support.
While temporary table records are stored in a temporary database on disk, work table
records are stored in memory. Note that for a relatively small application with a
sufficiently large buffer allocation, Progress does not have to perform any disk I/O for
temporary tables. To specify buffer size for temporary tables, use the Bt parameter.
The performance of a temporary table is comparable to the performance of a database
table. If you select the NOUNDO option, UPDATE performance increases for temporary
tables. If you do not use NOUNDO, then changes made to the temporary table during a
transaction are logged to the local before image (LBI) file.
1520
The FIND statement for temporary tables uses the same cursor concept and choose-index
logic that are used for regular database tables. When a temporary table record is created,
its logical position in the table depends on the values of its key fields. Its logical position
in the table can be changed by changing the key values.
Because temporary tables have indexes similar to regular database tables, they can
perform fast sequential and random access to temporary table records using one or more
indexes. Since work tables have no index support, all record access is performed with a
sequential search.
If you use the Record phrase OF option to join a work table, the other table in the join
(database or temporary) must have a unique index for the common fields. For more
information on joins and the OF option, see Chapter 9, Database Access.
You can pass temporary tables (but not work tables) as parameters to procedures. In fact,
if you want to call a Progress AppServer passing it a table of data, you must pass the table
of data as a temporary table. There is no other way. For more information on Progress
AppServers, see Building Distributed Applications Using the Progress AppServer. For
more information on temporary tables as parameters, see the Temporary Tables As
Parameters section in this chapter.
1521
The following program illustrates using a temporary table for non-database data:
p-ttnodb.p
/* p-ttnodb.p - static temp-table with no database */
DEFINE VARIABLE btth AS HANDLE.
DEFINE VARIABLE browseHndl AS WIDGET-HANDLE.
DEFINE TEMP-TABLE t-field NO-UNDO
FIELD fInt AS INTEGER
FIELD fChar AS CHARACTER
FIELD fDec AS DECIMAL
FIELD fLog AS LOGICAL.
DO i=1 TO 10:
CREATE t-field.
ASSIGN fInt = i
fChar = "char" + STRING(i)
fDec = i
fLog = NO.
END.
DEFINE QUERY qt-field FOR t-field SCROLLING.
OPEN QUERY qt-field FOR EACH t-field.
btth = BUFFER t-field:HANDLE.
DEFINE FRAME F1
WITH SIZE 82 BY 29 .
CREATE BROWSE browseHndl
ASSIGN
FRAME = FRAME F1:HANDLE
X = 2
Y = 2
WIDTH = 80
DOWN = 18
TITLE = "Temp Table is not based on DB table"
QUERY = QUERY qt-field:HANDLE
SENSITIVE = YES
VISIBLE = TRUE
READ-ONLY = FALSE
SEPARATORS = YES.
browseHndl:ADD-COLUMNS-FROM(btth).
ENABLE ALL WITH FRAME F1.
WAIT-FOR CLOSE OF CURRENT-WINDOW.
1522
15.2.6 Defining Indexes for Temporary Tables
You can define indexes explicitly for temporary tables or you can inherit indexes from existing
database tables. When you define a temporary table to be LIKE a database table, the temporary
table inherits index layouts from the LIKE table according to these rules:
If you do not specify any index information, the temporary table inherits all the index
layouts defined for the LIKE table.
If you specify one or more USE INDEX options, the temporary table inherits only the
explicitly named index layouts. If one of these indexes is the primary index of the LIKE
table, it becomes the primary index of the temporary table, unless you explicitly specify
AS PRIMARY for another index.
If you specify one or more INDEX options, the temporary table also inherits index layouts
named by a USE INDEX option. If the new index is specified as PRIMARY, it becomes
the primary index of the temporary table.
If you specify any index information, then no more than one primary index can be
specified. If you do not specify a primary index, then the first index specified is treated as
the primary index.
If you do not specify any index information, Progress creates a default primary index
which sorts records in the order they are entered.
The following is a summary of the rules that determine the primary index of a temporary table.
1. If you specify AS PRIMARY or IS PRIMARY for an index, then that is the primary index.
2. If you do not specify AS PRIMARY or IS PRIMARY, but you inherit the primary index
from a database table, that index is the primary index.
3. If neither Rule 1 nor Rule 2 applies, then the first index you specify, if any, is the primary
index, unless it is a word index, in which case it cant be primary.
4. If you have not specified any index information, then Progress creates a default primary
index that sorts the records in entry order.
1523
15.2.7 Tailoring Temporary Table Visibility and Life Span
Depending on how you specify the NEW, GLOBAL, and SHARED options of the DEFINE
TEMPTABLE statement, you can tailor the visibility and life span of the temporary table to
the needs of your application.
You can define a temporary table that is visible to:
Only the procedure that creates it
The procedure that creates it, and the procedures that the creating procedure calls
All procedures in the Progress session
You can define a temporary table to live as long as:
The procedure that creates it
The current Progress session
1524
Table 152 displays the DEFINE TEMPTABLE options you should specify for each type of
temporary table, and the resulting temporary tables visibility and life span.
Table 152: Temporary Table Options, Visibility, and Life Span
Type Options Visibility Life Span
Not Shared
and
Not Global
DEFINE... The creating procedure The creating
procedure
Shared DEFINE NEW SHARED...
(in the creating procedure)
DEFINE SHARED...
(in the procedures that the
creating procedure calls
that want to share the
temporary table)
The creating procedure,
and the procedures that
the creating procedure
calls that want to share
the temporary table
The creating
procedure
Global DEFINE NEW
GLOBAL...
(in the creating procedure,
and in other procedures in
the Progress session that
want to access the
temporary table)
All procedures in the
Progress session
The Progress
session
1525
15.2.8 Temporary Tables As Parameters
Temporary table parameters strongly resemble other parameters, but have a few differences.
This section discusses the similarities and differences.
Similarities
Temporary table parameters resemble other procedure parameters in several ways:
1. In the calling procedure, you define the parameter type as INPUT, OUTPUT, or
INPUTOUTPUT. INPUT is the default. Here is the syntax for a defining a temporary
table parameter in the calling procedures RUN statement.
NOTE: For information on the APPEND option, see the last item in the Differences
section.
2. In the called procedure, you define the parameter type as INPUT, OUTPUT, or
INPUTOUTPUT. INPUT is the default. Here is the syntax for defining a temporary table
parameter in the called procedures DEFINE PARAMETER statement.
NOTE: For information on the APPEND option, see the Differences section.
3. The parameter types (INPUT, OUTPUT, or INPUTOUTPUT) you define in the calling
procedure and the called procedure must match.
SYNTAX
{
[ INPUT ] TABLE name
| { INPUT-OUTPUT | OUTPUT } TABLE name [ APPEND ]
}
SYNTAX
DEFINE
{ { [ INPUT ] | INPUT-OUTPUT | }
PARAMETER TABLE FOR name [ APPEND ]
| OUTPUT PARAMETER TABLE FOR name
}
1526
4. Data moves between the calling procedure and the called procedure depending on the
parameter type. INPUT parameter data moves from the calling procedure to the called
procedure, OUTPUT parameter data moves from the called procedure to the calling
procedure, and INPUTOUTPUT parameter data moves from the calling procedure to the
called procedure, then back to the calling procedure. Some parameters send data, and
others receive data. Table 153 identifies which parameters send data and which receive
data, based on parameter type (INPUT, OUTPUT, or INPUTOUTPUT) and role (calling
procedure or called procedure).
5. Data moves between the parameters of the calling procedure and the parameters of the
called procedure at precise times. INPUT parameter data moves just before the called
procedure begins to execute. OUTPUT parameter data moves just after the called
procedures RETURN statement executes. INPUTOUTPUT parameter data moves like
input parameter data, then like output parameter data.
6. You can only use the APPEND option for an INPUT parameter in the calling procedure
or an OUTPUT parameter in the called procedure.
Differences
The following special rules apply to temporary table parameters:
1. The calling procedure and the called procedure must have separate temporary tables.
NOTE: If the calling procedure and the called procedure use the same shared or global
temporary table as a parameter (which might occur when code is automatically
generated), then no data moves, and using the APPEND option (even when the
compiler allows it) causes a run time error.
2. The signatures of the two temporary tables must match. This means that the calling
procedures temporary table and the called procedures temporary table must match with
respect to the number of columns, the data type of each column, and the number of extents
of each column (for columns with extents).
Table 153: Identifying Sender and Receiver Parameters
Parameter Type Calling Procedure Called Procedure
INPUT Sender Receiver
OUTPUT Receiver Sender
INPUTOUTPUT Sender and Receiver Sender and Receiver
1527
3. The calling procedures temporary table and the called procedures temporary table need
not have matching indexes.
4. Progress does not automatically convert data between similar data types, such as integer
and decimal.
5. At data movement time, Progress overlays any existing data in the receiving temporary
table (OUTPUT and INPUTOUTPUT parameters in the calling procedure, and INPUT
and INPUTOUTPUT parameters in the called procedure) unless you define the
receiving temporary table with the APPEND option. If you use the APPEND option,
Progress appends the incoming data to the existing data.
15.2.9 Temporary Table Example
The following procedure creates a temporary table (tempitem) that stores the total inventory
value (the sum of item.price * item.onhand) for each items catalog page (item.catpage). It
builds a tempitem with two indexes: one that sorts the table in ascending order by catalog page
and a second that sorts the table in descending order by inventory value.
1528
This shows how you can use a temporary table to store a calculated result from the database,
and efficiently report the same result according to different sorting and selection criteria:
p-tmptbl.p
DEFINE TEMP-TABLE temp-item
FIELD cat-page LIKE item.cat-page
FIELD inventory LIKE item.price LABEL "Inventory Value"
INDEX cat-page IS PRIMARY cat-page ASCENDING
INDEX inventory-value inventory DESCENDING.
DEFINE VARIABLE cutoff LIKE item.price.
DEFINE VARIABLE inv-price LIKE item.price.
DEFINE VARIABLE report-type AS INTEGER INITIAL 1.

FORM
cutoff LABEL "Inventory Lower Cutoff for each Catalog Page"
AT ROW 1.25 COLUMN 2
report-type LABEL "Report Sorted ..." AT ROW 2.25 COLUMN 2
VIEW-AS RADIO-SET RADIO-BUTTONS
"By Catalog Page", 1, "By Inventory Value", 2
WITH FRAME select-frame SIDE-LABELS WIDTH 70 TITLE "Specify Report ..."
VIEW-AS DIALOG-BOX.
FOR EACH item BREAK BY item.cat-page:
ACCUMULATE price * on-hand (SUB-TOTAL BY item.cat-page).
IF LAST-OF(item.cat-page) THEN DO:
inv-price = ACCUM SUB-TOTAL BY item.cat-page (price * on-hand).
CREATE temp-item.
temp-item.cat-page = item.cat-page.
inventory = inv-price.
END.
END. /* FOR EACH item */
REPEAT:
UPDATE cutoff report-type WITH FRAME select-frame.
IF report-type = 1 THEN
FOR EACH temp-item USE-INDEX cat-page WITH FRAME rpt1-frame:
IF inventory >= cutoff THEN
DISPLAY temp-item.cat-page inventory.
END.
ELSE
FOR EACH temp-item USE-INDEX inventory-value WITH FRAME rpt2-frame:
IF inventory >= cutoff THEN
DISPLAY temp-item.cat-page inventory.
END.
END. /* REPEAT */
1529
15.3 Dynamic Temporary Tables
It is sometimes difficult to know the exact nature of a temptable that may be needed at runtime,
especially since there are dynamic buffers for ordinary database tables. A dynamic temptable
allows users to create a temptable on the fly at runtime without having to do a compile-time
DEFINE TEMPTABLE.
15.3.1 Static and Dynamic Temp Tables
A static temptable is created with the DEFINE TEMPTABLE statement and configured at
compile time. A dynamic temptable is created with the CREATE TEMPTABLE statement
which creates a dynamic handle to a temptable object whose fields and buffers are configured
at runtime. It is possible to associate a dynamic BUFFER object with a static temptable which
allows a certain amount of runtime manipulation. It is also possible to associate a temptable
object with a static temptable as follows:
Creating a handle to a static temptable is especially useful if you want to pass it as a parameter.
See the Dynamic Temptables as Local and Remote Parameters section for more information
on temptables as parameters
15.3.2 Creating a Dynamic Temptable
There are several steps to creating a dynamic temptable:
Creating the temptable object
Adding fields to the dynamic temptable
Adding indexes to the dynamic temptable
Completing the dynamic temptable
DEFINE VARIABLE tth AS WIDGET-HANDLE.
DEFINE TEMP-TABLE tmptblx LIKE customer.
tth = tmptblx:HANDLE.
1530
Creating the Temptable Object
You can create a dynamic temptable by using the CREATE TEMPTABLE statement which
creates an empty temptable object. You must use the ADD/CREATE type methods to add
fields and indexes to the table. For example, the following statement creates an empty
temptable that can be referred to by its handle, tthandle:
Adding Fields to the Dynamic Temptable
Once you have created the empty temptable object, you must add fields to it to make it useful.
There are four methods you can use to add fields to the temptable:
CREATELIKE( ) copies the field definitions from a source table and establishes all
the indexes of the source table unless specified otherwise.
ADDFIELDSFROM( ) copies the specified fields from a source table. No indexes
are established. This method can be used multiple times on the same temptable and is
especially useful when the rows of the temptable need to represent a join.
ADDLIKEFIELD( ) copies the single field specified from a source table.
ADDNEWFIELD( ) adds a field with the specified properties.
The following code fragment illustrates creating a dynamic temptable and adding fields to it:
CREATE TEMP-TABLE tthandle.
DEFINE VARIABLE tthandle AS HANDLE.
/* create an "empty" undefined temp-table */
/* give it customer tables fields and indexes */
tthandle:CREATE-LIKE("customer").
/* add all fields from salesrep table except for month-quota */
tthandle:ADD-FIELDS-FROM("salesrep","month-quota").
/* give it a single extra integer field */
tthandle:ADD-NEW-FIELD("f1","integer").
. . .
1531
Adding Indexes to the Dynamic Temptable
There are several ways of creating indexes for dynamic temptables. The CREATELIKE( )
method described above creates all the indexes of the source table by default. If you specify a
single index in the CREATELIKE( ) method, however, you will get only that index. In
addition, the following methods also create indexes in the dynamic temptable:
ADDINDEXFIELD( ) adds the named field to the named index
ADDLIKEINDEX( ) copies the specified index from the specified source table
ADDNEWINDEX( ) adds a new index with the specified properties
The following code fragment adds an index to the previous example:
/* add a new index "rep" and add the "rep-name" to the new index */
tthandle:ADD-NEW-INDEX("rep")
tthandle:ADD-INDEX-FIELD("rep","rep-name")
. . .
1532
Completing the Dynamic Temptable
Once you have added all the fields and indexes for your dynamic temptable, you must signal
the 4GL that the temptable definition is complete by using the TEMPTABLEPREPARE( )
method. This method causes the pending list of fields and index definitions to become part of
the actual temptable object, making it ready for use. TEMPTABLEPREPARE( ) must be
called before any nonADD/CREATE method can be called.
The following code fragment completes the previous examples:
/* add an index like the salesrep.sales-rep index and call it "srep" */
tthandle:ADD-LIKE-INDEX("srep","sales-rep","salesrep").
/* the definition of temp-table, "newcust", is complete */
tthandle:TEMP-TABLE-PREPARE("newcust").
. . .
1533
15.3.3 Dynamic Buffers for Dynamic Temptables
All dynamic buffer attributes and methods are available to dynamic temptables. For more
information on dynamic buffers, see Chapter 11, Database Triggers and the Progress
Language Reference manual sections on Buffer Object Handle and Bufferfield Object Handle.
Every dynamic temptable is created with at least one buffer, just like a static temptable. This
default buffers object handle is returned by the DEFAULTBUFFERHANDLE( ) method. It
is through this buffer handle that you have access to the records and fields in the temptable
object as follows:
The DEFAULTBUFFERHANDLE( ) method may not be called until the
TEMPTABLEPREPARE( ) method has been called, since the default buffer is not created
until then.
In addition, several new methods have been created to enhance the use of dynamic buffers for
dynamic temptables:
BUFFERCOPY copies any common fields from one buffer to another, excluding
specified fields and excluding fields not present in both tables.
BUFFERCOMPARE compares common fields in two buffers, excluding specified
fields and excluding fields not present in both tables.
The CREATE BUFFER statement will now support both temptables and buffer handles, as
follows:
dyn-buff-hdl = dyn-tt-hdl:DEFAULT-BUFFER-HANDLE.
dyn-buff-hdl:BUFFER-CREATE.
buff-fld = dyn-buff-hdl:BUFFER-FIELD(3).
CREATE BUFFER dyn-buff-hdl FOR TABLE dyn-tt-hdl.
1534
The following program illustrates the use of buffers and bufferfields in dynamic temptables.
It uses a dynamic query which is described in Chapter 20, Using Dynamic Widgets:
p-ttdyn2.p
/* p-ttdyn2.p - a join of 2 tables */
DEFINE VARIABLE tth4 AS HANDLE.
DEFINE VARIABLE btth4 AS HANDLE.
DEFINE VARIABLE qh4 AS HANDLE.
DEFINE VARIABLE bCust AS HANDLE.
DEFINE VARIABLE bOrder AS HANDLE.
DEFINE VARIABLE fldh AS HANDLE EXTENT 15.
bCust = BUFFER customer:HANDLE.
bOrder = BUFFER order:HANDLE.
CREATE TEMP-TABLE tth4.
tth4:ADD-FIELDS-FROM(bCust,"address,address2,phone,city,comments").
tth4:ADD-FIELDS-FROM(bOrder,"cust-num,carrier,instructions,PO,terms").
tth4:TEMP-TABLE-PREPARE("CustOrdJoinTT").
btth4 = tth4:DEFAULT-BUFFER-HANDLE.
FOR EACH customer WHERE cust.cust-num < 6, EACH order OF customer:
btth4:BUFFER-CREATE.
btth4:BUFFER-COPY(bCust).
btth4:BUFFER-COPY(bOrder).
END.
/* Create Query */
CREATE QUERY qh4.
qh4:SET-BUFFERS(btth4).
qh4:QUERY-PREPARE("for each CustOrdJoinTT").
qh4:QUERY-OPEN.
REPEAT WITH FRAME zz DOWN:
qh4:GET-NEXT.
IF qh4:QUERY-OFF-END THEN LEAVE.
REPEAT i = 1 TO 15:
fldh[i] = btth4:BUFFER-FIELD(i).
DISPLAY fldh[i]:NAME FORMAT "x(15)"
fldh[i]:BUFFER-VALUE FORMAT "x(20)".
END.
END.
btth4:BUFFER-RELEASE.
DELETE OBJECT tth4.
DELETE OBJECT qh4.
1535
15.3.4 Dynamic Temptables as Local and Remote Parameters
Using a temptable as a parameter requires the ability to send the template of the temptable,
its indexinformation, and its field information locally to a local procedure or remotely to an
AppServer.
The DEFINE PARAMETER and RUN statements support sending the tablehandle as a
parameter as shown below:
For more information on parameter syntax, see the DEFINE PARAMETER statement and the
RUN statement in the Progress Language Reference manual.
INPUT
If the parameter is INPUT TABLEHANDLE, the definition behind the handle plus the
contents of the temptable are sent from the caller to the called routine. The called routine can
have either a dynamic INPUT TABLEHANDLE or a static INPUT TABLE as a matching
parameter.
In the called routine, a new instance of the temptable is created along with its handle,
completely separate from the callers table and populated with the contents from the callers
table. This instance is used during the called routine. If the called routine has a static table as the
matching parameter, the caller temptable data will be loaded into this table. In no case is the
callers table affected by the called procedure.
OUTPUT
If the parameter is OUTPUT TABLEHANDLE, the handle plus the definition behind the
handle are sent from the caller to the called routine. If the handle is NULL, then no definition is
sent. The called routine can have either a table handle for a static OUTPUT parameter or a
dynamic OUTPUT TABLEHANDLE as a matching parameter. The called routine returns the
definition behind the handle along with the contents of the output temptable. In the caller, a
new instance of the table is created if the original handle was NULL and populated with the
returned temptable contents. This new table replaces any pre-existing table in the caller, either
static or dynamic. If the APPEND keyword was used, the returned contents are appended to the
pre-existing table, rather than replacing it.
/* calling program */
RUN myprog.p(INPUT TABLE-HANDLE newhdl).
/* called program */
DEFINE INPUT PARAMETER TABLE-HANDLE newhdl.
1536
NOTE: For local cases, there is usually no need to use anything more than a simple
HANDLE type parameter to allow routines to share a temptable. The
TABLEHANDLE parameter is only for cases where either one or both sides of a
remote communication lack a static definition of the temptable.
INPUTOUTPUT
If the parameter is INPUTOUTPUT TABLEHANDLE, a combination of the above will
occur.
The following programs illustrate using a temptable handle as a parameter. The called
program, getdbtable.p, is used to create a temptable from any database table whose name is
passed to it and to pass back the handle to this temptable. The calling program, passdbname.p,
passes the database table name and receives back the temptable handle which it uses to access
the created temptable.
These programs use dynamic queries which are described in Chapter 20, Using Dynamic
Widgets:
p-passdb.p
DEFINE VARIABLE tth AS HANDLE.
DEFINE VARIABLE dbtabname AS CHARACTER.
DEFINE VARIABLE q AS HANDLE.
DEFINE VARIABLE bh AS HANDLE.
DEFINE VARIABLE fh1 AS HANDLE.
DEFINE VARIABLE fh2 AS HANDLE.
dbtabname = "item".
RUN p-getdb.p (INPUT dbtabname ,OUTPUT TABLE-HANDLE tth).
IF tth = ? THEN RETURN.
bh = tth:DEFAULT-BUFFER-HANDLE.
fh1 = bh:BUFFER-FIELD(1).
fh2 = bh:BUFFER-FIELD(2).
CREATE QUERY q.
q:SET-BUFFERS(bh).
q:QUERY-PREPARE("FOR EACH " + dbtabname).
q:QUERY-OPEN.
REPEAT:
q:GET-NEXT.
IF q:QUERY-OFF-END THEN LEAVE.
MESSAGE fh1:STRING-VALUE fh2:STRING-VALUE.
END.
1537
15.3.5 Error Handling and Messages
Errors for dynamic objects do not automatically raise Progress 4GL errors since they occur
inside a widget expression. Rather, all the methods that can have errors return FALSE if an error
occurs, so they must be tested. If NOERROR is in effect in the statement containing the widget
reference, no messages display, but they can be retrieved from the ERRORSTATUS system
handle.
p-getdb.p
DEFINE INPUT PARAMETER tabname AS CHARACTER.
DEFINE OUTPUT PARAMETER TABLE-HANDLE tth.
DEFINE VARIABLE bh AS HANDLE.
DEFINE VARIABLE fh AS HANDLE.
DEFINE VARIABLE q AS HANDLE.
DEFINE VARIABLE dbh AS HANDLE.
CREATE BUFFER dbh FOR TABLE tabname.
CREATE TEMP-TABLE tth.
tth:ADD-FIELDS-FROM(tabname).
tth:TEMP-TABLE-PREPARE(tabname).
bh = tth:DEFAULT-BUFFER-HANDLE.
CREATE QUERY q.
q:SET-BUFFERS(dbh).
q:QUERY-PREPARE("FOR EACH " + tabname).
q:QUERY-OPEN.
REPEAT i = 1 TO 5:
q:GET-NEXT.
bh:BUFFER-CREATE.
bh:BUFFER-COPY(dbh).
END.
DELETE OBJECT dbh.
DELETE OBJECT q.
DELETE OBJECT tth. /* delete is delayed until the parameter is passed */
1538
16
Widgets and Handles
A widget is a visual element of a user interface. For example, a widget might be an image, a
menu, a frame, a window, or a fill-in field. Widgets are often called user interface components
(UICs) or controls.
Progress supports the following types of widgets:
Windows
Frames
Dialog boxes
Browse
Fill-in fields, text, sliders, selection lists, combo boxes, toggle boxes, radio sets, and
editors for data representation
Buttons, images, rectangles, and literals
Menus, submenus, menu bars, and menu items
Progress provides handle and widget-handle variables that you can use to reference widgets or
the context of procedures. Progress also supports system handles. A system handle is a built-in
handle that references a particular UIC (such as the current window), a Progress procedure
context, session information (such as error status), or a special Progress or system function
(such as the system clipboard).
162
You can also specify triggers for widgets and procedures. Triggers are blocks of code that
execute in response to a user-specified or program-generated event.
This chapter explains the functions and inter-relationships of user-interface widgets, triggers,
widget handles, and system handles, and describes how to use them.
Widgets and Handles
163
16.1 Overview
Widgets exist in a hierarchy consisting of container and atomic widgets. A container widget can
contain one or more other widgets. An atomic widget represents data or other visual information
but does not contain any other widgets. Most container and atomic widgets can have a menu
widget (a type of container widget) associated with them, and many atomic widgets can have
an associated literal widget that represents a side label.
16.1.1 Widget Types
The basic container widget of a user interface is the window. In a character environment, the
screen itself is the only window. In a graphical environment, the screen can contain many
windows.
In Progress, a window can contain one or more frames. A frame can contain one or more
field-level widgets and child frames organized into field groups. Field-level widgets are atomic
widgets that can represent variables, database fields and records, or visual objects such as
buttons, images and rectangles. Figure 161 shows a simple user-interface display. The display
contains two windows labeled Window 1 and Window 2. Window 1 contains two frames
labeled Frame A and Frame B. Each of these frames contains two field-level widgets. Window
2 contains one frame, which contains a text widget and a slider widget.
Figure 161: User-interface Display
164
Figure 162: A Widget Hierarchy
As shown in Figure 162, a window can contain frames, dialog boxes, a menu bar, and an alert
box. A frame or dialog box contains field groups. A field group can contain one or more
field-level widgets and child frames, creating frame families. Alert boxes are special widgets for
displaying messages only. A window can also parent (own) another window, creating a window
family. For more information on windows and window families, see Chapter 21, Windows,
For information on frames, frame families, field groups, and dialog boxes, see Chapter 19,
Frames. For more information on windows, frames, and dialog boxes, see Chapter 25,
Interface Design.
Some field-level widgets are data-representation widgets. Data-representation widgets, such as
fill-ins, sliders, and selection lists, can represent database fields or variables. The browse widget
can represent multiple records in a database. Other field-level widgets, such as buttons, images,
and rectangles represent visual objects and perform special functions. For more information on
field-level widgets, see Chapter 10, Using the Browse Widget, Chapter 17, Representing
Data (for other data-representation widgets), and Chapter 18, Buttons, Images, and
Rectangles.
Window
Frames
and
Dialog Boxes
Menu Bars Alert Boxes
Field Groups
Field-level and
Frame Widgets
Submenus
Submenus Menu Items
Menu Items
Windows
Widgets and Handles
165
It is important to distinguish between a data-representation widget and its underlying data
storage. For example, a fill-in widget and the variable it represents each exist independently of
the other. In fact, you can have a data-representation widget that represents different data
storage at different times or does not represent any storage at all.
A menu widget is a special type of container widget that contains only submenu and menu item
widgets. Progress supports two types of menus. As shown in Figure 162, a window can contain
a menu bar, which can contain pull-down submenus. The second type of menu (not shown in
Figure 162) is a pop-up menu. A pop-up menu can be associated with a data-representation
widget, a button, a frame, a dialog box, or a window. For more information on menus, see
Chapter 22, Menus.
Progress lets you specify triggers for all user-interface widgets. For more information, see the
User-interface Triggers section.
Progress also supports a special type of field-level widget, the controlframe, that provides both
a design-time and run-time interface to ActiveX controls. ActiveX controls offer a rich set of
user interface extensions to Progress. Many of the most popular ActiveX controls are also
available through the Crescent Division of Progress Software Corporation. For more
information on controlframes and ActiveX controls, see the Progress External Program
Interfaces manual.
The next section describes the basic types of widgets and how you can create them.
16.2 Static Versus Dynamic Widgets
Most widgets are either static or dynamic. Static widgets are defined when a procedure is
compiled. They are created when the procedure is invoked and remain available until the
procedure terminates or for the scope of their definition, whichever is longer. Dynamic widgets
can be created and deleted during execution of a procedure and are globally scoped. (Scope is
the duration that an object is available to the application.)
NOTE: All windows, except the static default window created by Progress, are dynamic. For
more information on creating dynamic Windows, see Chapter 21, Windows, and
the Dynamic Widgets section in this chapter. Alert boxes and field groups are
neither static nor dynamic but are created automatically by Progress. Progress creates
an alert box for a window when you invoke the MESSAGE statement with the
VIEWAS ALERTBOX option. For more information on using alert boxes, see
Chapter 25, Interface Design. Progress automatically creates field groups when
you create and use a frame or dialog box. For more information on working with field
groups, see Chapter 19, Frames.
166
16.2.1 Creating Widgets
Creating any widget, static or dynamic, involves two actionsdescribing and then instantiating
the widget. You describe a widget when you define its visual and behavioral characteristics.
You instantiate a widget when you actually create an instance of the widget that you describe.
Thus, instantiation makes a widget handle available to reference the widget. The process of
describing and instantiating a widget differs depending on whether the widget is static or
dynamic.
16.2.2 Using Widget Handles
To allow you to reference instantiated widgets within an application, Progress assigns each
widget a unique widget handle. A widget handle is a pointer to the widget. Progress provides
the WIDGETHANDLE data type to support widget-handle variables and fields (in temporary
tables and work tables).
NOTE: Progress also provides handles to procedures with the HANDLE data type. For more
informatigon, see Chapter 3, Block Properties.
You can find the handle for a specific widget using the HANDLE attribute. An attribute is a
named widget characteristic. You can reference a handle attribute for a widget using this syntax:
For a static widget, the initial widgetreference is the name you use to describe the widget,
possibly qualified by the widget type. For a dynamic widget, it is the widget-handle variable you
use to describe the widget. The handleattribute is any attribute that returns a widget handle
value. The containerwidget parameter specifies the container widget for widgetreference, if
there is more than one. (For more information on referencing and using attributes, see the
Widget Attributes section.)
SYNTAX
widget-reference :handle-attribute [ IN container-widget ]
Widgets and Handles
167
For example, if you want to find the widget handle for a database field displayed in a named
frame, you can use a code fragment like the following to retrieve the value of the HANDLE
attribute for the widget used to display the field.
Many other attributes, such as PARENT or FRAME, return widget-handle values. For more
information on the HANDLE attribute and other widget-handle attributes, see the Progress
Language Reference.
You can obtain the handle for any widget that is instantiated. For information on describing and
instantiating static widgets, see the Static Widgets section. For information on dynamic
widgets, see the Dynamic Widgets section.
16.2.3 Static Widgets
You can describe and instantiate a static widget in one or two statements, depending on the
widget type.
Describing a Static Widget
You can describe a static widget in several ways, depending on the widget:
Frame You can use the Frame phrase as part of many other statements, including a
FORM, DEFINE FRAME, I/O (DISPLAY, UPDATE, ENABLE, etc.), or block header
(FOR, REPEAT, etc.) statement.
Dialog box You specify the VIEWAS DIALOG-BOX option in the Frame phrase.
Field-level data-representation widget (EDITOR, SELECTIONLIST, etc.) You
can use the VIEWAS phrase as part of some other phrase or statementin a Format
phrase for variables and in the Data Dictionary ViewAs phrase dialog for fields.
Browse, menu, submenu, menu-item, or a field-level widget not used for data
representation, such as a button, image, or rectangle You can use the DEFINE
widgettype statement. Note that you describe menu-item widgets directly in a static menu
or submenu description. You can also use this statement to define frames, as noted above.
DEFINE VARIABLE myhand AS WIDGET-HANDLE.
DISPLAY customer.name WITH FRAME name-frame.
myhand = customer.name:HANDLE IN FRAME name-frame.
168
Instantiating a Static Widget
Progress automatically instantiates any static widget whose unique identity is known when you
describe or use it. Thus:
When you start a non-batch-mode client session, Progress instantiates the default window.
When you describe or use any static frame or dialog box widget, Progress instantiates that
frame or dialog box, unless it has already been instantiated by a previous description or
use. You use a named or unnamed frame when you execute a frame-oriented I/O statement
(DISPLAY, UPDATE, etc.) with or without a frame name. For more information on
named and unnamed frames, see Chapter 19, Frames.
When you describe any static menu widget, Progress instantiates that menu, including its
menu-items, submenus, and descendents.
Name references to some widgets specify a unique widget. These include static frame, dialog
box, menu, or menu-item of menu widgets. Progress creates only one such widget in a
procedure at a time. Thus, Progress can instantiate the widget when you first describe it.
However, to instantiate the description for any other static widget type, including a field-level,
browse, submenu, or menu-item of a submenu widget, you must instantiate a static widget that
contains it. The reason for this is that when you describe a widget that requires a container, you
are only specifying the qualifying attributes of the widget. You can only establish a unique
identity (widget handle) for a contained widget by associating it with an instantiated container
widget. For example, this code fragment describes an editor widget associated with the variable
xvar, and creates an instance of the editor in frame a.
Also, the widget description for a static field-level, submenu, or submenu menu-item widget
might specify more than one instance of that widget. When you include a reference to a
field-level widget in the descriptions of more than one frame or dialog box, you instantiate a
different, but identical, field-level widget for each frame or dialog box in which it appears.
This code fragment describes a button, b1, and creates two instances of itone in frame x and
one in frame y.
DEFINE VARIABLE xvar AS CHARACTER VIEW-AS EDITOR SIZE 40 BY 10.
ENABLE xvar WITH FRAME a.
DEFINE BUTTON b1.
ENABLE b1 WITH FRAME x.
ENABLE b1 WITH FRAME y.
Widgets and Handles
169
Similarly, when you include a reference to a submenu widget in the descriptions of more than
one instantiated menu or submenu, you instantiate a different, but identical, submenu widget for
each menu and submenu in which it appears.
This code fragment describes a submenu, sub1, and creates two instances of itone in menu
m1 and one in menu m2.
Thus:
When you specify a static browse or field-level widget within the description of a static
frame or dialog box, Progress creates a unique instance of that browse or field-level
widget. Although a browse widget requires a container to be instantiated, you can only
instantiate a single browse from a single browse description. Also, you can reference a
single browse widget in only one frame description at a time.
On the other hand, all instantiations of a static field-level data-representation widget
represent the same underlying variable or database field. This example shows two fill-in
fieldsone in frame x and the other in frame yeach for the same custnum field in the
current customer record.
For more information on browse widgets, see Chapter 10, Using the Browse Widget.
For more information on data-representation widgets, see Chapter 17, Representing
Data.
When you specify a static submenu widget within a static menu description, Progress
creates a unique instance of that submenu widget and each descendent submenu and
menu-item widget.
DEFINE SUB-MENU sub1
MENU-ITEM sub-item1
MENU-ITEM sub-item2.

DEFINE MENU m1
MENU-ITEM item1
SUB-MENU sub1.

DEFINE MENU m2
MENU-ITEM item1
SUB-MENU sub1.
DEFINE FRAME x customer.cust-num.
DEFINE FRAME y customer.cust-num.
1610
When you specify a static menu-item widget within a static menu description, Progress
creates a unique instance of that menu-item.
When you specify a static submenu or menu-item widget within another static submenu
description, Progress creates a unique instance of the named submenu or menu item only
when the containing submenu is instantiated by a succeeding menu description.
Working with Static Widgets
The VIEWAS phrase for describing static data-representation widgets has the following
general syntax:
The widgettype parameter is the name of the widget type, such as FILLIN, TOGGLEBOX,
or SLIDER. The options parameter is a set of options that further describe the widget.
The DEFINE statement for describing other static widgets (buttons, images, rectangles, menus,
submenus, and frames) has the following general syntax:
The name parameter specifies a name for the widget, much like a variable name for
data-representation widgets.
Again, frames and dialog boxes are described using the Frame phrase in many statements. Some
of these statements, such as the FORM, I/O, and block header statements can describe a named
or unnamed frame and apply scoping to the frame. The DEFINE FRAME statement, however,
describes a named, unscoped frame. For more information on frame scoping, see Chapter 19,
Frames.
NOTE: The VIEWAS DIALOGBOX option is a special case of VIEWAS applied to the
Frame phrase only.
SYNTAX
VIEW-AS widget-type [ options ]
SYNTAX
DEFINE widget-type name [ options ]
Widgets and Handles
1611
For example, this code fragment describes an editor widget and a frame. It instantiates the frame
and editor widget in the frame description.
You can also specify triggers for all static widgets when they are defined using the Trigger
phrase, except the browse, frame, menu, and submenu widgets. For more information, see the
User-interface Triggers section.
Referencing Static Widgets
In general, you can reference static widgets using either the widget name or a widget-handle
variable to which its handle has been assigned. For more information on widget handles, see the
Widget Handles section. The widget name for data-representation widgets is the field or
variable name. For frames, it is the frame name; and for all other static widgets, it is the name
used in the DEFINE widgettype statement.
The following widgets also require that you qualify name references with the widgettype:
Frames and dialog boxes
NOTE: A dialog box is a type of frame. Therefore, you qualify all name references to it
as a FRAME widget.
Menus
Submenus
Menu items
For example, this code fragment shows name references to menu and menu-item widgets:
DEFINE VARIABLE e AS CHARACTER VIEW-AS EDITOR INNER-LINES 5
INNER-CHARS 30.
DEFINE FRAME main-frame
e
WITH NO-LABELS.
DEFINE MENU medit1
MENU-ITEM icut LABEL "Cut"
MENU-ITEM icopy LABLE "Copy"
MENU-ITEM ipaste LABLE "Paste".
DEFINE MENU medit2 LIKE MENU medit1.
ON CHOOSE OF MENU-ITEM icopy IN MENU medit2 RUN copy2.
1612
This code fragment shows name references to field-level and frame widgets, including the
browse widget, custbrow; the fill-in field, order.ordernum; and the frame, x:
16.2.4 Dynamic Widgets
You can describe and immediately instantiate any dynamic widget with a CREATE Widget
statement, which has the following general syntax:
The widgettype parameter is the name of the widget type, such as WINDOW, FRAME, or
BUTTON, and the handlevariable parameter is the name of a variable of type
WIDGETHANDLE that receives the widget handle value for the widget.
The poolname parameter specifies a previously created widget pool. A widget pool allows you
to manage a set of dynamic widgets as a group. For more information on creating and using
widget pools, see Chapter 20, Using Dynamic Widgets.
The attribute parameter is the name of a widget attribute that is valid for the widget. Unlike
static widgets, which you describe using compile-time options, you must describe a dynamic
widget by setting its attributes at run time. You can set attributes when or after you create the
widget. For more information on setting widget attributes, see the Widget Attributes section.
The triggerphrase specifies one or more triggers for the widget. Note that the ON statement
provides a more flexible technique for specifying triggers. The scoping is more reliable and
allows the CREATE Widget statement to be shorter and more readable. For more information,
see the User-interface Triggers section.
DEFINE QUERY q FOR customer.
DEFINE BROWSE custbrow QUERY q DISPLAY cust-num name WITH SIZE 25 by10.
DEFINE FRAME x custbrow order.order-num.
ON VALUE-CHANGED OF custbrow IN FRAME x DO: END.
ON RETURN OF order.order-num IN FRAME x DO: END.
SYNTAX
CREATE widget-type handle-variable
[ IN WIDGET-POOL pool-name ]
[ ASSIGN attribute = value [ attribute = value ] ... ]
{ [ trigger-phrase ] }
Widgets and Handles
1613
You can use this syntax to create any dynamic widget. You can create any type of widget
dynamically except literal, down frame, and browse widgets. Literal widgets are created only
by Progress to hold side labels for static data-representation widgets. Down frames and browse
widgets provide different techniques for displaying multiple iterations of data. Progress requires
compile-item information to create these widgets. For more information on down frames, see
Chapter 19, Frames. For more information on browse widgets, see Chapter 10, Using the
Browse Widget.
Referencing Dynamic Widgets
Note that unlike static widgets, a dynamic widgets are created and referenced only with
widget-handle variables. This is because you are describing an actual instance of the widget,
independent of any other widget. A dynamic widget stands on its own, whether or not it requires
a container widget to be part of the user interface. Note also that dynamic data-representation
widgets, such as fill-in fields, have no underlying field or variable for data storage. You must
explicitly associate a dynamic widget with a field or variable by assigning data between the
widgets SCREENVALUE attribute and any appropriate field or variable.
Deleting Dynamic Widgets
You can explicitly delete a dynamic widget with the DELETE WIDGET statement:
If you do not explicitly delete a widget, it remains allocated until the end of the session or until
the widget pool that contains it is deleted. If you delete a dynamic container widget, such as a
frame or window, any dynamic widgets that it contains are deleted also.
An advantage of dynamic widgets is that you can determine the number of widgets to create at
run time. For example, you might create a button for each table in a database or each record in
a table. A disadvantage is that you must do more of the work for dynamic widgets. For example,
Progress can automatically lay out static widgets in a frame, but you must explicitly position
dynamic widgets.
NOTE: The Procedure Editor optionally deletes all dynamic widgets that you create in a
session each time you return to the Editor after running an application. For more
information, see the on-line help for the Procedure Editor, and Progress Basic
Development Tools manual (Character only).
You can also delete groups of dynamic widgets in a widget pool using the DELETE
WIDGETPOOL statement. For more information, see Chapter 20, Using Dynamic Widgets.
SYNTAX
DELETE WIDGET widget-handle
1614
The following procedure creates a dynamic button for each record in the salesrep table:
Note that within the CREATE BUTTON statement, the procedure assigns the button to
buttframe, then calculates a ROW and COLUMN value within that frame. The procedure must
explicitly set the width of the frame in the DEFINE FRAME statement and set the height of the
frame after all the buttons are created. By contrast, Progress automatically positions the static
widgets within repframe and makes that frame the proper size.
For more information on creating and using dynamic widgets, see Chapter 20, Using Dynamic
Widgets.
p-dybuts.p
DEFINE VARIABLE num-buts AS INTEGER.
DEFINE FRAME butt-frame
WITH WIDTH 60 CENTERED TITLE "Sales Representatives".
FORM
salesrep
WITH FRAME rep-frame.
num-buts = 0.
FOR EACH salesrep:
CREATE BUTTON temp-hand
ASSIGN LABEL = salesrep.sales-rep
FRAME = FRAME butt-frame:HANDLE
ROW = TRUNC(num-buts / 3, 0) + 1
COLUMN = ((num-buts MOD 3) * 20) + 1
SENSITIVE = TRUE
TRIGGERS:
ON CHOOSE
DO:
FIND salesrep WHERE salesrep.sales-rep = SELF:LABEL.
DISPLAY salesrep WITH FRAME rep-frame.
END.
END TRIGGERS.
num-buts = num-buts + 1.
END.
FRAME butt-frame:HEIGHT-CHARS = (num-buts / 3) + 2.
VIEW FRAME butt-frame.
Widgets and Handles
1615
16.3 Handles
Handles are pointers to Progress objects. You generally define variables or fields to hold handle
values with the HANDLE, WIDGETHANDLE, or COMHANDLE data type. Note that
HANDLE and WIDGETHANDLE have a weak type relationship; that is, one can be assigned
directly to the other. The COMHANDLE data type provides ActiveX support. Progress
supports following types of handle, depending on the object referenced:
Widget
Procedure
Query, buffer, and buffer-field
Server
Component
Transaction
System
16.3.1 Widget Handles
Progress assigns every static or dynamic widget a handle value once it is created. This handle
serves a different purpose, depending on whether the widget is static or dynamic:
For a static widget, the handle provides a unique reference to the widget besides the widget
name. The widget name, by itself, can be ambiguous if the widget is specified in more than
one container widget. Progress resolves this ambiguity differently depending on the
widget. However, the handle to a widget is always unambiguous.
For a dynamic widget, it provides the only means to reference and manage the widget that
you create.
You generally store widget handle values in variables or fields defined with the
WIDGETHANDLE data type. For more information on widget handles and how to use them,
see the Static Versus Dynamic Widgets section.
1616
16.3.2 Procedure Handles
Every external procedure that is in scope within an application has a handle that identifies the
context of the procedure. Using a valid procedure handle, you can execute the internal
procedures and procedure triggers of the specified external procedure from any other procedure
in your application. This capability is especially useful with persistent procedures. Thus, you
can encapsulate related functionality and make it available to your entire application.
You generally store procedure handle values in variables or fields defined with the HANDLE
data type. For more on procedure handles and how to use them, see the information on
procedures in Chapter 3, Block Properties.
16.3.3 Query, Buffer, and Buffer-field Handles
Query, buffer, and buffer-field object handles let you manipulate static and dynamic versions of
these objects. For more information, see the section on query, buffer, and buffer-field objects"
in section of Chapter 9, Database Access.
16.3.4 Server Handles
A server handle references the connection that you create to a Progress AppServer using the
CREATE SERVER statement. You generally store server handle values in variables or fields
defined with the HANDLE data type. For more information on server handles and how to use
them, see the Building Distributed Applications Using the Progress AppServer manual.
16.3.5 Component Handles
A component handle references a COM object (ActiveX Automation object or ActiveX
control). Unlike all other handles, you store component handle values in variables defined with
the COMHANDLE data type. For more information on component handles and how to use
them, see the Progress External Program Interfaces manual.
16.3.6 Transaction Handles
A transaction object handle provide access to the current transaction object. For more
information, see the Transaction Object Handle reference entry in the Handle Reference
chapter of the Progress Language Reference.
Widgets and Handles
1617
16.3.7 System Handles
Progress maintains several global handles that describe the current context of an application.
Some system handles reference the widget handle of a context-determined user-interface
widget. Others reference data and facilities available for and about the current session. Table
161 lists the Progress system handles.
Table 161: System Handles (1 of 2)
System Handle Description
ACTIVEWINDOW A handle to the Progress window that has most recently
received input focus during the session.
CLIPBOARD A handle to the system clipboard.
COLORTABLE A handle to information on the current color table.
COMPILER A handle to information on the most recently executed
COMPILE statement.
COMSELF A component handle to the ActiveX control that
generates an OCX event. Accessible within the OCX
event procedure that handles the event.
CURRENTWINDOW A setable handle to the default window for the Progress
session.
1,2
DEBUGGER A handle to the Progress Application Debugger.
DEFAULTWINDOW A handle to the static window created by Progress for the
session. Every session has one static window.
1
ERRORSTATUS A handle to information on the last statement executed
with the NOERROR option.
FILEINFO A handle to information on an operating system file.
FOCUS A handle to the field-level widget that currently has
keyboard focus (that is, the current field).
FONTTABLE A handle to information on the current font table.
LASTEVENT A handle to the last event received by the program.
RCODEINFO A handle to information on a Progress r-code file.
1618
The pointer specified by a system handle has a data type appropriate to the object to which it
points. Thus, the THISPROCEDURE handle and most other system handles return a
HANDLE data type. System handles that reference widgets, such as CURRENTWINDOW,
return a WIDGETHANDLE data type.
You can change some system handles within an application. For example, you can change the
current window by assigning another handle value to the system CURRENTWINDOW
handle. You can establish a menu bar for the default window by assigning a menu bar handle to
the DEFAULTWINDOW:MENUBAR attribute.
SELF A handle for the widget associated with the currently
executing user-interface trigger.
SESSION A handle to information on the current Progress session.
SOURCEPROCEDURE A handle to the procedure file that contains the original
invocation (RUN statement or function invocation) of the
current internal procedure or user-defined function.
TARGETPROCEDURE From within an internal procedure: a handle to the
procedure file mentioned, explicitly or implicitly, by the
original RUN statement that invoked (perhaps through a
chain of super procedures) the current internal procedure.
From within a user-defined function: a handle to the
procedure file mentioned, explicitly or implicitly, by the
original function invocation that invoked (perhaps
through a chain of super versions of functions) the current
user-defined function.
THISPROCEDURE A handle to the executing external procedure in which the
handle is referenced.
WEBCONTEXT Provides access to information on the current connection
to the Web server.
1
The initial setting of the CURRENTWINDOW handle is the Progress static window. CURRENTWINDOW
can also be set to the handle of any dynamic window.
2
If the THISPROCEDURE:CURRENTWINDOW attribute is set to the handle of a valid window, this
window becomes the default window for the executing procedure (overriding the setting of the
CURRENTWINDOW handle). The setting of THISPROCEDURE:CURRENTWINDOW changes the
default window only for the current external procedure block
Table 161: System Handles (2 of 2)
System Handle Description
Widgets and Handles
1619
For more information on each system handle, see the appropriate reference entry in the Progress
Language Reference.
16.3.8 Handle Management
In general, handles allow you to pass around references to widget, procedure, server, ActiveX,
and system objects both within procedures (using variables) and between procedures (using
parameters). Depending on the object and what you do with it, a handle might or might not be
valid at different points in your application. To ensure that the handle you reference is valid, you
can test it using the VALIDHANDLE function. This function returns TRUE if the specified
handle points to a valid object that is still available to your application.
Progress also reuses handle values. For example, if you delete a dynamic button, Progress might
reuse the widget handle for the deleted button to point to another widget, procedure, or system
object. To ensure that a valid handle you have stored still points to a widget of a particular type,
you can check the value of the TYPE attribute for the handle. For example, if the handle points
to a window, the TYPE attribute is set to WINDOW. For more information on referencing
attributes, see the Widget Methods section.
There are occasions where you might want to store a handle value as a string. Thus, you can
convert any widget handle value to an integer string using the STRING function. To convert this
string to its original handle value, use the WIDGETHANDLE function. This function converts
handle values for all types of handles. (Progress automatically converts values between
component handles and any other data type.) For more information on the WIDGETHANDLE
function, see the Progress Language Reference.
CAUTION: The WIDGETHANDLE function can only convert a string to a handle value that
was originally converted from a handle value. Any other string causes a system
error.
1620
16.4 Widget Attributes
Every widget or handle has certain attributes. Each attribute stores a value associated with the
widget or handle. This value represents an aspect, state, or capability of the widget. For
example, most widgets have a VISIBLE attribute that is either TRUE or FALSE (that is, the
widget is either visible or invisible).
Widget attributes fall into several basic categories:
Geometry (that is, the size and location of the widget)
Appearance (color, font, and cursor)
I/O related
Relationships to other widgets (such as parent, siblings, or owner)
Each type of widget has its own attributes. For example, the attributes supported for a button are
different than those supported for a frame. For a list of the attributes supported by each widget,
see the reference entry for the widget in the Progress Language Reference.
Handle attributes correspond to the type of object the handle references:
Widget
Procedure
Pseudo-widget or system function
Some attributes are set when the widget or object is created and are inaccessible to the Progress
programmer. Other attributes can be read and, in some cases, updated within the application.
For example, you can enable or disable input on a menu item by changing the value of its
SENSITIVE attribute.
Widgets and Handles
1621
16.4.1 Attribute References
You reference an attribute the same way, whether for reading or setting, and this is the syntax
for an attribute reference:
The widget parameter is the name of a widget (UIC), or a widget, procedure, or system handle.
The attribute parameter specifies the name of the widget or handle attribute. You must leave no
space between the colon (:) and its parameters.
The name parameter specifies the name of a container widget appropriate for the static UIC
specified by widget. If the widget appears in more than one frame or menu, the default frame or
menu is the most recently defined container whose description includes the widget. If the widget
appears in more than one submenu, the default submenu is the first submenu in the menu tree
whose description includes the widget.
Note that specifying a container name is only appropriate where widget specifies a name
reference to a static widget. Handles are unique by definition and take no container name as part
of the attribute reference.
Whenever possible, use unique names for your static widgets. Otherwise, specify the container
widget in the attribute reference. Thus, if you add widget definitions later, you can avoid bugs
caused by referencing the wrong default widget in your current attribute references.
16.4.2 Referencing Attribute Values
To reference the value of an attribute, you can either assign the attribute reference directly to a
field or variable or include the attribute reference in an expression or statement option, like a
function. For example, this is the syntax to assign an attribute value to a field or variable (field):
The attributereference includes the syntax specified in the Attribute References section. For
information on referencing attribute values in expressions, see the Attributes in Expressions
section.
SYNTAX
widget:attribute [ IN { FRAME | MENU | SUB-MENU } name ]
SYNTAX
field = attribute-reference
1622
16.4.3 Setting Attribute Values
This is the syntax to set an attribute value:
The attributereference includes the syntax specified in the Attribute References section. The
expression must produce a value compatible with the data type of the attribute.
16.4.4 Attributes in Expressions
An attribute reference can appear in an expression to yield an attribute value only. The attribute
separator (:) is not an expression operator. It can only separate an attribute name from the name
of the widget or handle variable to which it applies. Thus, it cannot reference an attribute of a
widget handle value that is, itself, the result of an expression. This example shows a valid
attribute reference in an expression.
This example shows an invalid attribute reference.
You cannot use the widget handle value returned by bChoose:FRAME to directly reference the
WIDTHCHARS attribute. You can, however, assign bChoose:FRAME to a widget-handle
variable and use that variable for your attribute reference. For more information on
widget-handle variables, see the Handles section.
SYNTAX
attribute-reference = expression
DEFINE VARIABLE WidthTotal AS DECIMAL.
DEFINE BUTTON bChoose LABEL "Choose Me".
DEFINE FRAME Aframe bChoose.
WidthTotal = 5 * (bChoose:WIDTH-CHARS + 1) + 2.
WidthTotal = (bChoose:FRAME):WIDTH-CHARS.
Widgets and Handles
1623
16.4.5 Attribute Example
The following code fragment sets an attribute based on the Progress user ID, tests a logical
expression that includes the result, and displays a message that includes a value assigned from
another attribute.
16.5 Widget Methods
In addition to attributes, some widgets have methods. A method is an operation that performs a
specific action related to a widget. It might modify or return information on a specific widget,
change a widgets relationship to other widgets, or affect other system resources related to the
widget. Methods also return a value, like a function.
16.5.1 Method References
The syntax for a method reference is similar to the syntax for an attribute reference:
The widget parameter is the name of a widget (UIC), or a widget or system handle. The method
parameter specifies the name of the widget or handle method. You must leave no space between
the colon (:) and its parameters.
Methods typically take one or more arguments. For example, the method
ADDFIRST(newitem) adds newitem as the first value in a selection list or combo box. Note
that if a method takes no arguments, you must include an empty set of parentheses in the method
reference.
DEFINE VARIABLE SecurityCode AS INTEGER.
DEFINE VARIABLE LastCodeDisplay AS CHARACTER.
DEFINE FRAME SecurityFrame SecurityCode WITH SIDE-LABELS.
.
.
.
IF USERID ("sports") <> "SUPERVISOR" THEN
SecurityCode:VISIBLE = FALSE.
IF NOT SecurityCode:VISIBLE THEN DO:
LastCodeDisplay = SecurityCode:SCREEN-VALUE.
MESSAGE "You cannot continue with security code " LastCodeDisplay.
QUIT.
END.
SYNTAX
widget:method ( [ arg [ , arg ] ... ] ) [ IN FRAME frame ]
1624
Methods exist for windows, frames, and many widgets contained in frames. There are also
specific methods for certain system handles. For more information on a specific method, see the
16.5.2 Invoking Methods
You can invoke a method in two ways:
Indirectly, by returning its value in an expression
Directly as a statement, ignoring its value
Thus, the syntax to invoke a method is similar to the syntax for invoking a user-defined
function:
The methodreference includes the syntax specified in the Method References section. You
can return its value by assigning the method reference to a field or variable (field) or include the
method reference in an expression, like a function.
16.5.3 Methods in Expressions
A method reference can appear in an expression to yield the method result only. The method
separator (:) is not an expression operator. It can only separate a method name from the name
of a widget or handle variable to which it applies. Thus, it cannot reference a method for a
widget handle value that is, itself, the result of an expression. This example shows a valid
method reference in an expression.
This example shows an invalid method reference.
SYNTAX
[ field = ] method-reference
WidthTotal = 5 * (FONT-TABLE:GET-TEXT-WIDTH-CHARS(bChoose:LABEL) + 1) + 2.
WidthTotal = 5 * ((FRAME Aframe:GET-TAB-ITEM(1)):WIDTH-CHARS + 1) + 2.
Widgets and Handles
1625
You cannot use the widget handle value returned from the GETTABITEM( ) method to
directly reference the WIDTHCHARS attribute. For more information on widget-handle
variables, see theHandles section.
16.5.4 Method Example
The following procedure assigns an editor widget to the contents of a file using the
INSERTFILE( ) method. It writes the contents back to the file using the SAVEFILE( )
method after the user has a chance to change it. Messages are displayed depending on users
input and the success or failure of the methods, which return TRUE if they succeed:
p-method.p
DEFINE VARIABLE To-Do AS CHARACTER VIEW-AS EDITOR SIZE 60 BY 10.
DEFINE FRAME DoFrame SPACE(3) To-Do WITH SIDE-LABELS SIZE 76 BY 12.
ON GO OF To-Do IN FRAME DoFrame DO:
IF To-Do:SAVE-FILE("to-do.lst") THEN
MESSAGE "TO DO list saved."
ELSE DO:
BELL.
MESSAGE "TO DO list NOT saved!!"
VIEW-AS ALERT-BOX WARNING BUTTONS OK.
END.
END.
ON END-ERROR OF To-Do IN FRAME DoFrame
MESSAGE "TO DO list NOT changed."
ENABLE ALL WITH FRAME DoFrame.
IF To-Do:INSERT-FILE("to-do.lst") THEN
WAIT-FOR GO OF To-Do IN Frame DoFrame.
ELSE DO:
BELL.
MESSAGE "TO DO list NOT available."
VIEW-AS ALERT-BOX MESSAGE BUTTONS OK.
END.
1626
16.6 Widget Realization
When you create or define a widget, Progress creates an internal data structure associated with
that widget. Before the widget can be displayed on the screen, the window system must also
create a data structure for the widget. When this second data structure exists, the widget is
realized.
You can modify some widget attributes at any time. Other attributes are initially modifiable, but
become fixed while the widget is realized. This means that you cannot modify these attributes
again unless the widget is derealized. A widget becomes derealized when the associated data
structure within the windowing system is deleted.
There are two reasons it is important for you to understand when realization and derealization
occur. First, because you cannot change some attributes while the widget is realized and,
second, because some attributes must be set to a valid value before realization takes place.
16.6.1 Becoming Realized
In general, a widget becomes realized when the application needs to make it visible on the
screen. This happens, for example, when a field-level widget is referenced in a screen I/O
statement such as DISPLAY or UPDATE, or when the VISIBLE attribute of a frame is set to
TRUE. Also, widgets typically become realized when a parent, owner, or child widget becomes
realized. References to specific attributes and methods can also cause realization.
Table 162 lists the specific actions that cause realization for each type of widget.
Table 162: Realizing Widgets (1 of 3)
Widget Type
Action that
Causes Realization
Browse The browse becomes visible on the screen.
Button The button becomes visible on the screen.
The frame that contains the button becomes visible on the screen.
Combo box The combo box becomes visible on the screen.
The frame that contains the combo box becomes visible on the screen.
An application references any method of the combo box.
Dialog box See the information for frames.
Widgets and Handles
1627
Editor The editor becomes visible on the screen.
The frame that contains the editor becomes visible on the screen.
An application references any method of the editor.
An application queries any of the following attributes: CURSORCHAR,
CURSORLINE, CURSOROFFSET, MODIFIED, LENGTH,
SELECTIONEND, SELECTIONSTART, SELECTIONTEXT.
Field group The frame that contains the field group becomes realized.
Fill-in field The fill-in becomes visible on the screen.
The frame that contains the fill-in becomes visible on the screen.
Frame
1
The frame becomes visible on the screen. (This happens anytime the
frames VISIBLE attribute is set to TRUE.)
Any field-level widget within the frame becomes realized.
An UPDATE or CHOOSE statement is executed that references the frame
or any field in the frame.
An application reads any of the following attributes:
BORDERBOTTOM, BORDERLEFT, BORDERRIGHT,
BORDERTOP, MAXCOLUMNS, MAXHEIGHT, MAXROWS,
MAXWIDTH.
Image The image becomes visible on the screen.
Menu bar The window that owns the menu bar becomes realized.
The menu bar is attached to a window that is already realized.
Menu item The parent menu becomes realized.
The menu item is added to a menu that is already realized.
Pop-up menu The owner of the pop-up menu becomes realized.
The pop-up menu is attached to a widget that is already realized.
Widget Type
Action that
Causes Realization
1628
Radio set The radio set becomes visible on the screen.
The frame that contains the radio set becomes visible on the screen.
An application sets any of the following attributes: HEIGHT,
HEIGHTROWS, WIDTH, WIDTHCOLUMNS.
Rectangle The rectangle becomes visible on the screen.
The frame that contains the rectangle becomes visible on the screen.
Selection list The selection list becomes visible on the screen.
The frame that contains the selection list becomes visible on the screen.
An application references any method of the selection list.
An application reads the selection lists MULTIPLE or VALUE attribute.
An application reads or sets the selection lists INNERCHARS or
INNERLINES attribute.
Slider The slider becomes visible on the screen.
The frame that contains the slider becomes visible on the screen.
Submenu The parent menu is realized.
The submenu is attached to a parent menu that is already realized.
Text The text widget becomes visible on the screen.
The frame that contains the text widget becomes visible on the screen.
Toggle box The toggle box becomes visible on the screen.
The frame that contains the toggle box becomes visible on the screen.
Window
2
Any frame in the window is realized.
1
If a frame is shared, it is realized in all procedures as soon as it is realized in any procedure.
2
In batch mode, the window is realized as soon as it is created.
Widget Type
Action that
Causes Realization
Widgets and Handles
1629
16.6.2 Becoming Derealized
Realization is not a permanent state. Under conditions listed in Table 163, a previously
realized widget becomes derealized.
Table 163: Derealizing Widgets
Widget
Type
Action that
Causes Derealization
All dynamic widgets The widget is deleted.
All static widgets The widget goes out of scope
Any field-level widget The containing field group is derealized.
Field group The containing frame is derealized.
The associated iteration is scrolled off the screen.
Frame The containing window is deleted.
Menu bar The window that owns the menu bar is deleted.
The menu bar is detached from the window.
Menu item The parent menu is derealized.
Pop-up menu The widget that owns the pop-up menu is derealized.
The pop-up menu is detached from its owner.
Submenu The parent menu is derealized.
1630
16.7 Resizing Widgets Dynamically
Certain run-time conditions can make the size of a widget inappropriate:
The font of a button, combo box, editor, fill-in, frame, radio button, selection list, slider,
toggle box, or window changes.
The format of the text displayed within a fill-in changes.
The label of a button, toggle box, or radio button changes.
The size of the image displayed within a button changes.
A selection lists or editors INNERCHARS or INNERLINES attribute changes.
By default, Progress resizes the widget if any of the above conditions occur. It determines the
size that is most appropriate under the new conditions. This automatic resizing is governed by
the value of the the Boolean AUTORESIZE attribute, which by default is on, or TRUE. If
AUTORESIZE is on for a particular widget, then the widget will resize based on its physical
characteristics (for example, font, label, and format).
Any of the following actions will stop Progress from automatically resizing widgets at run time:
You explicitly turn AUTORESIZE off, either at widget definition or at run time.
You explicitly specify the size of a widget, either at widget definition or at run time, by
changing any of the following characteristics:
Width
Height
Columns
Rows
INNERCHARS
INNERLINES
Note that if you turn AUTORESIZE on for a widget whose size you have been controlling,
Progress will compute a new size immediately; it will not wait until one of the previously
mentioned conditions, such as a font change, occurs.
For a programming example that demonstrates the AUTORESIZE attribute, see the
information on fill-ins in Chapter 17, Representing Data.
Widgets and Handles
1631
16.8 User-interface Triggers
For each widget you define or create, you can establish one or more user-interface triggers. A
user-interface trigger is a block of code associated with an event-widget pair (that is, with a
specific event and a specific widget). The trigger executes whenever that event is applied to that
widget. User interface triggers allow you to write event-driven applications.
NOTE: Progress also provides procedure triggers that allow you to apply events to a
procedure handle to execute code in the specified procedure. For more information,
see Chapter 3, Block Properties.
16.8.1 User-interface Events
Progress supports the following types of events:
Keystrokes
Mouse events
Direct manipulation events
Other, widget-specific events
Each type of widget supports a set of user-interface events. You can define triggers only on
those events supported by the widget.
Keystrokes
You can set up triggers for raw keystrokes or for key functions. Raw keystroke events include
all the characters in the character set, including control sequences such as CTRLX and key
labels such as F1 and DELCHAR. Key functions include GO, HELP, ENDERROR, and
DELETE, among others.
For more information on Progress key labels, key functions, and key codes, see Chapter 6,
Handling User Input. In the same chapter, see the the section on monitoring keystrokes during
data entry for examples of triggers on specific keystrokes.
Mouse Events
Progress supports a conceptual portable mouse model (that is, SELECT, MENU, and EXTEND
buttons) and a physical two-button mouse model (that is, LEFT, and RIGHT buttons). The
portable model provides better portability. However, using any mouse events may cause
problems when porting to a system that does not have a mouse. Consider using functional events
such as CHOOSE, ENTRY, and MENUDROP instead.
1632
To map the portable model to a two-button mouse, a physical button may have two meanings,
or a modifier key, such as CTRL, may be used with a physical button. For example, with a
two-button mouse on Windows, the LEFT button maps to the SELECT and MOVE buttons, the
RIGHT button maps to the MENU button, and the RIGHT button with CTRL maps to the
EXTEND button.
Table 164 lists the portable and two-button mouse events supported by Progress.
Table 164: Mouse Events
Portable Mouse Events Two-button Mouse Events
MOUSESELECTUP LEFTMOUSEUP
MOUSESELECTDOWN LEFTMOUSEDOWN
MOUSESELECTCLICK LEFTMOUSECLICK
MOUSESELECTDBLCLICK LEFTMOUSEDBLCLICK
MOUSEMENUUP RIGHTMOUSEUP
MOUSEMENUDOWN RIGHTMOUSEDOWN
MOUSEMENUCLICK RIGHTMOUSECLICK
MOUSEMENUDBLCLICK RIGHTMOUSEDBLCLICK
MOUSEMOVEUP N/A
MOUSEMOVEDOWN N/A
MOUSEMOVECLICK N/A
MOUSEMOVEDBLCLICK N/A
MOUSEEXTENDUP N/A
MOUSEEXTENDDOWN N/A
MOUSEEXTENDCLICK N/A
MOUSEEXTENDDBLCLICK N/A
Widgets and Handles
1633
Direct Manipulation Events
Progress supports events related to marking, moving, and resizing widgets on the screen. For
more information on these events, see Chapter 24, Direct Manipulation.
Other Events
In addition to normal keystrokes, mouse events, and direct manipulation events, Progress
supports the additional events listed in Table 165.
Table 165: Other Progress Events
Event Description
CHOOSE Occurs when the user chooses a widget, such as a button or
most menu items.
ENTRY Occurs when the user moves focus into a frame or field-level
widget.
DEFAULTACTION Occurs when the user executes the environment-specific
action for completing a selection list.
ITERATIONCHANGED Occurs when the user changes the current iteration of a
browse widget.
LEAVE Occurs when the user moves focus out of a frame or
field-level widget.
MENUDROP Occurs when the user selects a pull-down menu from a menu
bar.
VALUECHANGED Occurs when the user changes the value of a combo box,
toggle box, selection list, radio set, or toggle box menu item.
WINDOWCLOSE Occurs when the user closes a window.
WINDOWMAXIMIZED Occurs when the user maximizes a window.
WINDOWMINIMIZED Occurs when the user minimizes a window.
WINDOWRESTORED Occurs when the user restores the size of a window.
1634
16.8.2 Trigger Definition
You can set up a user-interface trigger when you define or create the widget or subsequently in
an ON statement.
For static widgets, triggers can be either of two types: definitional or run-time. A definitional
trigger is specified in the statement that defines the widget and is set up at compile time. A
run-time trigger is specified in an ON statement and is set up at run time when that statement is
executed.
The following procedure defines two static buttons. It sets up a definitional trigger for the Quit
button and a run-time trigger for the Next button:
p-trig1.p
DEFINE BUTTON quit-button LABEL "QUIT"
TRIGGERS:
ON CHOOSE
QUIT.
END TRIGGERS.

DEFINE BUTTON next-button LABEL "NEXT".
FORM
next-button quit-button
WITH FRAME butt-frame.

FORM
Customer.Cust-num Customer.Name
WITH FRAME cframe 10 DOWN USE-TEXT.
OPEN QUERY all-cust FOR EACH Customer.
ON CHOOSE OF next-button
DO:
GET NEXT all-cust.

DOWN WITH FRAME cframe.
DISPLAY Customer.Cust-num Customer.Name WITH FRAME cframe.
END.
ENABLE ALL WITH FRAME butt-frame.

GET FIRST all-cust.
DISPLAY Customer.Cust-num Customer.Name WITH FRAME cframe.
Widgets and Handles
1635
In an ON statement, you can specify more than one event-widget pair for the same trigger code.
In the following example, the items in the sounds menu all share the same trigger:
Note that, by using SELF within the trigger, the behavior is customized for each widget. The
trigger displays the value of the PRIVATEDATA attribute for the selected widget and then
disables that widget.
If you use the LIKE option in defining a variable or widget, the widget you are defining inherits
any triggers defined on that other widget. If triggers are inherited in this way, you cannot
specify additional definitional triggers. However, if there are no triggers to inherit, you may
specify definitional triggers.
p-says.p
DEFINE SUB-MENU sounds
MENU-ITEM sound-cat LABEL "Cat"
MENU-ITEM sound-cow LABEL "Cow"
MENU-ITEM sound-dog LABEL "Dog".

DEFINE SUB-MENU exit-all
MENU-ITEM exit-confirm LABEL "Really?".

DEFINE MENU mainbar MENUBAR
SUB-MENU sounds LABEL "Sounds"
SUB-MENU exit-all LABEL "Exit".
ASSIGN MENU-ITEM sound-cat:PRIVATE-DATA = "Meow"
MENU-ITEM sound-cow:PRIVATE-DATA = "Mooo"
MENU-ITEM sound-dog:PRIVATE-DATA = "Bow-wow".

ON CHOOSE OF MENU-ITEM sound-cat, MENU-ITEM sound-cow,
MENU-ITEM sound-dog
DO:
MESSAGE SELF:PRIVATE-DATA.
ASSIGN SELF:SENSITIVE = FALSE.
END.

ON CHOOSE OF MENU-ITEM exit-confirm
DO:
QUIT.
END.
CURRENT-WINDOW:MENUBAR = MENU mainbar:HANDLE.
DISPLAY "BARNYARD FUN" WITH FRAME title-frame CENTERED.
1636
For dynamic widgets, triggers are always run-time triggers. You can specify the run-time trigger
in the statement that creates the widget or in a subsequent ON statement.
16.8.3 Trigger Execution
A trigger is executed only if all of the following are true:
The widget is enabled for input.
The trigger is currently active.
The user performs the action associated with the trigger, or the application executes an
APPLY statement that applies the trigger event to the widget.
If the APPLY statement is not used, one of the following must also be true:
Execution is blocked for input (for example, by a WAITFOR or UPDATE
statement).
The PROCESS EVENTS statement is executed.
16.8.4 Trigger Scope
The scope of a trigger is that part of an application during which the trigger can be executed.
The scope of a definitional trigger is the same as the scope of the widget.
By default, the scope of a run-time trigger is the nearest containing procedure, subprocedure, or
trigger block in which it is defined. You might want a run-time trigger to remain active beyond
the procedure or trigger that defines it. You can do this by setting up a persistent trigger. Like a
definitional trigger, a persistent trigger remains active as long as the widget exists. A persistent
trigger allows you to create the equivalent of a definitional trigger for a dynamic widget.
Table 166 summarizes the scope for each type of trigger.
Table 166: Trigger Scopes
Trigger Type Scope
Definitional The same as the widget for which it is defined.
Run-time, nonpersistent The procedure, subprocedure, or trigger block in which it is
defined.
Run-time, persistent The same as the widget for which it is defined.
Widgets and Handles
1637
A persistent trigger must consist only of a single RUN statement. The RUN statement can
invoke an internal or external procedure. The procedure can have one or more input parameters,
but must not have any output or input/output parameters. You must ensure that the specified
procedure is available whenever the trigger is invoked. For example, if you use an internal
procedure, you must ensure that the trigger is not invoked from another external procedure.
NOTE: If you pass parameters to a persistent trigger procedure, the parameter values are
evaluated once when the trigger is defined. They are not reevaluated each time the
trigger executes. You cannot, for example, pass the SELF system handle as a
parameter to the persistent trigger.
The following procedure creates a button within the CHOOSE trigger for makebutt. Normally,
any trigger assigned to the new button remains active only until execution of the CHOOSE
trigger ends. To maintain the new trigger beyond the CHOOSE trigger, you must use a
persistent trigger:
1638
p-pers1.p
DEFINE VARIABLE num-butts AS INTEGER INITIAL 0.
DEFINE BUTTON make-butt LABEL "Make new button".
DEFINE FRAME butt-frame WITH WIDTH 44.

ENABLE make-butt WITH FRAME make-frame.
ON CHOOSE OF make-butt
DO:
if num-butts >= 100
THEN DO:
MESSAGE "Too many buttons.".
RETURN NO-APPLY.
END.
num-butts = num-butts + 1.
ASSIGN FRAME butt-frame:HEIGHT-CHARS =
TRUNC(((num-butts - 1) / 10), 0) + 2.

CREATE BUTTON temp-hand
ASSIGN FRAME = FRAME butt-frame:HANDLE
ROW = TRUNCATE((num-butts - 1) / 10, 0) + 1
COLUMN = (((num-butts - 1) * 4) MODULO 40) + 1
LABEL = STRING(num-butts)
SENSITIVE = TRUE
VISIBLE = TRUE
TRIGGERS:
ON CHOOSE
PERSISTENT RUN but-mess.
END TRIGGERS.
END.


PROCEDURE but-mess.

MESSAGE "You have selected button number" SELF:LABEL
"of" num-butts.

END PROCEDURE.
Widgets and Handles
1639
The example allows the user to create up to 100 dynamic buttons. Each time the user chooses
makebutt, the value of numbutts is incremented, the height of the frame is recalculated to
ensure the new button will fit, and the new button is created. When the user chooses one of the
dynamic buttons, the procedure displays a message.
If after defining a persistent trigger for an event-widget pair you define a nonpersistent trigger
for that same pair, the nonpersistent trigger overrides the persistent trigger. However, after the
nonpersistent trigger goes out of scope (or is reverted), the persistent trigger becomes active
again.
NOTE: Because persistent triggers remain active beyond the scope of the defining
procedure, you must ensure that any variables, frames, or buffers referenced by the
trigger are available whenever it is active.
16.8.5 Reverting Triggers
To cancel a trigger definition before it goes out of scope, use the REVERT option of the ON
statement. The REVERT option cancels any trigger for the event-widget pair defined in the
current procedure or trigger.
In the following procedure, p-rev.p, two triggers are defined for the selection of hellobutton:
one in the outer procedure and one in the internal procedure, inner. At the first WAITFOR
statement within inner, the local trigger is active. Therefore, when the user selects the button,
Inner message is displayed. Before the second WAITFOR, this trigger is reverted. The
trigger from the outer procedure becomes active again. Therefore, when the user selects the
button again, Outer message is displayed.
1640
NOTE: You cannot use REVERT to cancel a persistent trigger. Instead, you must set up a
replacement persistent trigger where the procedure consists only of a RETURN
statement.
16.8.6 Universal Triggers
You can use the ANYWHERE option of the ON statement to set up a trigger that applies to all
widgets in an application. This is equivalent to listing every widget in the ON statement.
The p-utrig.p procedure sets up a universal ENTRY trigger. This trigger is executed every
time the user moves the focus to a new widget. If the Verbose menu item is off, the trigger does
nothing. If Verbose is on, the trigger displays a message about the widget that receives focus:
p-rev.p
DEFINE BUTTON hello-button LABEL "Greeting".
DEFINE BUTTON revert-button LABEL "Revert".
FORM
hello-button revert-button
WITH FRAME butt-frame.
ON CHOOSE OF hello-button IN FRAME butt-frame
DO:
MESSAGE "Outer message".
END.
ENABLE hello-button WITH FRAME butt-frame.
RUN inner.
PROCEDURE inner:
DO:
MESSAGE "Inner message".
END.
ENABLE revert-button WITH FRAME butt-frame.

WAIT-FOR CHOOSE OF revert-button.

REVERT.
DISABLE revert-button WITH FRAME butt-frame.
END PROCEDURE.
Widgets and Handles
1641
p-utrig.p
DEFINE VARIABLE mess-string AS CHARACTER.
DEFINE VARIABLE text-str AS CHARACTER FORMAT "x(12)" LABEL "String".
DEFINE VARIABLE verb-mode AS LOGICAL.
DEFINE VARIABLE widget-type AS CHARACTER.
DEFINE BUTTON ok-butt LABEL "OK".
DEFINE BUTTON cancel-butt LABEL "CANCEL" AUTO-ENDKEY.
DEFINE SUB-MENU opt-menu
MENU-ITEM opt-verbose TOGGLE-BOX LABEL "Verbose".
SUB-MENU opt-menu LABEL "Options".

ENABLE ok-butt cancel-butt WITH FRAME x TITLE "Frame 1".
ENABLE text-str WITH FRAME y TITLE "Frame 2".
ON VALUE-CHANGED OF MENU-ITEM opt-verbose
verb-mode = NOT verb-mode.
ON ENTRY ANYWHERE
DO:
IF verb-mode
THEN DO:
widget-type = SELF:TYPE.
mess-string = "You are entering a " + widget-type + " (".
IF CAN-QUERY(SELF, "TITLE")
THEN mess-string = mess-string +
(IF SELF:TITLE <> ? THEN SELF:TITLE ELSE " ") + ")".
ELSE IF CAN-QUERY(SELF, "LABEL")
THEN mess-string = mess-string +
(IF SELF:LABEL <> ? THEN SELF:LABEL ELSE " ") + ")".
ELSE mess-string = mess-string + ")".
MESSAGE mess-string.
END.
END.
1642
16.8.7 Applying Events
You can use the APPLY statement to explicitly send an event to any widget from within a
program, including insensitive widgets. If a trigger is currently active for that event-widget pair,
the trigger executes. Progress handles the event as if it came from the user (provides default
handling) or not, depending on the event-widget pair and whether the trigger returns
NOAPPLY.
The following example applies the VALUECHANGED event to a browse widget:
Without the APPLY statement in p-apply.p, the first customer record would not initially
appear in frame y.
NOTE: In an APPLY statement, the event name must be enclosed in quotes ( ).
Default Processing of Events
In addition to executing any trigger you have defined for an event, the APPLY statement might
also cause the default processing for the event-widget pair by Progress. For example, applying
A to a fill-in field inserts the letter A at the cursor position in the field. However, some
event-widget pairs do not get Progress default processing using the APPLY statement. For
example, applying the CHOOSE event to a button executes any trigger on that button, but does
not give focus to the button.
p-apply.p
DEFINE QUERY custq FOR customer.
DEFINE BROWSE custb QUERY custq DISPLAY cust-num name WITH 15 DOWN.
FORM
customer EXCEPT comments
WITH FRAME y SIDE-LABELS.
ON VALUE-CHANGED OF BROWSE custb
DO:
DISPLAY customer EXCEPT comments WITH FRAME y.
END.
OPEN QUERY custq FOR EACH Customer.
ENABLE custb WITH FRAME x.
APPLY "VALUE-CHANGED" TO BROWSE custb.
ENABLE ALL WITH FRAME y.
Widgets and Handles
1643
Triggers Versus Internal Procedures
If you only want your trigger to execute, consider making that trigger code an internal procedure
and running the procedure rather than using the APPLY statement. For example, in the
following procedure, the CHOOSE trigger for the foreone button fetches the next customer
record (or refetches the current record if there are no more records). This same action is required
within several other triggers and within the main code:
p-repos3.p (1 of 2)
DEFINE BUTTON back-one LABEL "<".
DEFINE BUTTON back-fast LABEL "<<".
DEFINE BUTTON fore-one LABEL ">".
DEFINE BUTTON fore-fast LABEL ">>".
DEFINE QUERY scroll-cust FOR Customer SCROLLING.
FORM
Customer.Cust-num Customer.Name SKIP
back-fast back-one fore-one fore-fast

OPEN QUERY scroll-cust FOR EACH Customer NO-LOCK.
ENABLE back-fast back-one fore-one fore-fast WITH FRAME cust-frame.
ON CHOOSE OF back-fast
DO:
/* Position back 10 records (or to beginning) and
fetch the next record from there. */
REPOSITION scroll-cust BACKWARD 10.
RUN next-one.
END.

ON CHOOSE OF back-one
DO:
/* Position to previous record and fetch it. */
REPOSITION scroll-cust BACKWARD 2.
RUN next-one.
END.
ON CHOOSE OF fore-one
DO:
RUN next-one.
END.
1644
However, rather than applying CHOOSE to foreone to execute the action, the fetch code has
been moved to an internal procedure (nextone). That procedure is then run from within triggers
and the main code as needed. Running an internal procedure is more efficient than applying an
event because you avoid the overhead of event handling.
EventWidget Independence
With the APPLY statement, you can actually send any event to any widget for which you have
defined a trigger for that event. Progress executes the trigger even if there is no default handling
for that event associated with the widget. Thus, you can use this feature to extend the repertoire
of developer events (U1 to U10) to include any event (non-standard event) not normally
associated with a widget.
NOTE: If you use a nonstandard event-widget association, remember that future Progress
versions might make that event-widget association standard and thus introduce
unexpected default handling.
For more information on the APPLY statement, see the Progress Language Reference.
ON CHOOSE OF fore-fast
DO:
/* Position forward 10 records (or to last record) and fetch. */
REPOSITION scroll-cust FORWARD 9.
RUN next-one.

END.
/* Fetch the first record. */
RUN next-one.
PROCEDURE next-one:
/* Fetch the next record. */
GET NEXT scroll-cust.
IF QUERY-OFF-END("scroll-cust") THEN
GET PREV scroll-cust.
DISPLAY Customer.Cust-num Customer.Name WITH FRAME cust-frame.
END PROCEDURE.
p-repos3.p (2 of 2)
17
Representing Data
Database fields and Progress procedure variables can be represented on the display in a variety
of ways: as text, fill-ins, sliders, selection lists, combo boxes, toggle boxes, radio sets, and
editors. To choose a representation for a variable or a database field, you should consider the
following factors:
The data type and extent of the value
The graphical representation that best conveys information to end users and most easily
allows them to update the value
172
17.1 Using the VIEWAS Phrase
You specify a representation for a database field or variable with the VIEWAS phrase:
Database fields You use the VIEWAS phrase as a modifier to a screen I/O statement,
such as an UPDATE or DISPLAY.
Variables You can use the VIEWAS phrase as a modifier to a screen I/O statement,
or you can use it as a modifier to the DEFINE VARIABLE statement. In many cases, it is
preferable to use the VIEWAS phrase when defining the variable; this means that code
that manipulates the variable, such as an UPDATE statement, does not have to specify the
representation. It also allows you to isolate your user-interface code, which can make your
applications easier to port to different user-interface environments.
17.1.1 Multiple Representations for a Single Value
Both procedure logic and your deployment strategy determine whether you need more than one
representation for a single value. Two common scenarios are:
A value needs just one representation within a single user interface, but you need to alter
the data representation when deploying the same application in a different environment
with a different user interface. For example, you view a database character field as a fill-in
in one interface, but as an editor in another.
A value needs more than one representation within a single interface. For example, the
user chooses a file to delete from a selection list, and the application displays a dialog that
asks them if they really want to delete the file, giving them the opportunity to change the
file in a fill-in. Note that two representations of the same underlying value cannot appear
in the same frame; if a single interface has more than one representation for a value, they
must appear in different frames.
17.1.2 A Values Default Representation
If you do not use a VIEWAS phrase with a variable or database field, Progress displays it as a
fill-in that can be made into a CHOOSE field and that, when disabled, loses the border
decoration typical of fill-ins in the Windows graphical environment. The same is true if you
specify simply VIEWAS FILLIN.
However, if you specify VIEWAS FILLIN NATIVE, Progress displays a fill-in that is more
characteristic of graphical environments: the fill-in cannot be made into a CHOOSE field, and
it does not lose its border decoration when it is disabled.
Representing Data
173
17.2 Fill-ins
A fill-in is a rectangular field that contains a character representation of a value of any data type,
with or without extents. The user enters new characters to update the value. The number of
characters the user can enter, and hence the size of the fill-in, is usually governed by the format
you specify. You can also specify an external size for the field or you can let Progress determine
the size based on the format. The default formats are:
Eight alphanumeric characters for character fields.
Seven digits and an optional sign for integer and decimal values. For decimal values, two
of the digits follow the decimal point.
Three characters for logical values. By default, the value must be either yes or no.
A format of 99/99/99 for date values.
Because a fill-in is the default representation for fields, variables, and expressions, you usually
do not have to specify it. However, you can use the following syntax to explicitly view a value
as a fill-in:
Progress supports two subtypes of fill-ins: default Progress fill-ins and native graphical fill-ins.
For full backwards compatibility, default Progress fill-ins provide support for the CHOOSE
FIELD statement. Native graphical fill-ins look and behave like other fill-ins within the
Windows environment.
When a nonNATIVE (Progress 4GL) fillin is disabled, the border disappears but the text does
not gray out. When a NATIVE fillin is disabled, the text grays out.
If you want a native fill-in, you can specify VIEWAS FILLIN NATIVE for the field or set
the widgets SUBTYPE attribute to NATIVE (the default is PROGRESS). You cannot
change this attribute after the fill-in is realized.
17.2.1 Format and Size
By default the size of a fill-in on the screen is determined by its format and the font used when
the code is compiled. For example, if a fill-in has a format of x(8) then 8 characters are visible
on the screen. The external width of the fill-in might be 9 or 10 characters to allow for the side
borders.
SYNTAX
VIEW-AS FILL-IN [ NATIVE ] [ size-phrase ]
[ TOOLTIP tooltip ]
174
For proportional fonts on Windows, Progress considers the width of the widest character in the
font (maxcharwidth) and the average width of all characters in the font (avecharwidth) to
determine the width of a fill-in. Also, the rules differ for the default system font versus any other
font.
The rules for the default system font are as follows:
If the value is 3 characters or less, Progress multiples the length of the string times the
width of the widest character in the font: stringlength * maxcharwidth
If the value is more than 3 characters, but less than 13, Progress uses the widest character
in the font for 3 characters and the average character for the remaining characters: (3 *
maxcharwidth) + ((stringlength 3) * avecharwidth)
If the value is 13 characters or more, Progress multiplies the length of the string times the
average character width for the font: stringlength * avecharwidth.
For all other fonts than the default system font, Progress multiplies the length of the string (for
all string lengths) times the average character width for the font: stringlength *
avecharwidth.
Sometimes you want to explicitly set the size of the widget regardless of format. To prevent
Progress from resizing the field to fit the format, either set the AUTORESIZE attribute to
FALSE or explicitly specify a size within the VIEWAS FILLIN phrase or by setting the fields
WIDTH and HEIGHT attributes.
The following example defines two variables that are viewed as fill-ins. For the first, filename,
the procedure specifies a large format but a smaller size. For the second, no_scroll, the default
format, x( 8 ), and size are used:
Because the procedure specifies a width of 42 character for filename, only about 40 characters
are visible on the screen (the other character positions are used for side borders). Because the
format is greater than the number of visible characters, filename becomes a horizontally
scrolling field. When updating the field, when you type past the right edge of the field, the value
automatically scrolls so that you can enter more characters.
p-fillin.p
DEFINE VARIABLE filename AS CHARACTER FORMAT "X(80)"
VIEW-AS FILL-IN SIZE 42 BY 1.
DEFINE VARIABLE no-scroll AS CHARACTER.
DEFINE FRAME f
filename no-scroll.
UPDATE filename no-scroll WITH FRAME f.
Representing Data
175
For more information, see Chapter 16, Widgets and Handles.
17.2.2 Fill-in Attributes
At run time, a procedure can query or set fill-in specific attributes in these ways:
Set AUTOZAP to TRUE to allow the initial screen value of the fill-in to be erased when
the user begins typing in the field. The fill-in must have input focus to set AUTOZAP.
Query or set the FORMAT attribute. The format determines the number of spaces and
special characters (such as dollar signs and decimal points) Progress uses when displaying
the fill-in. Note that the format also establishes a constraint on the data that the user can
enter. However, changing the format has no effect on the data type of the field. For more
information, see Applying Formats When Displaying Widgets later in this chapter.
Enable or disable automatic tabbing with the AUTORETURN attribute. If this attribute
is true, Progress tabs to the next widget when the fill-in is full. If you set AUTORETURN
to true for the last widget in a frame, then when the field is full, Progress issues a GO event
for the frame.
Enable or disable character-echo during data entry with the BLANK attribute.
Query the FRAMENAME attribute to find the name of the frame that contains the field.
This is equivalent to using the FRAMENAME function and is useful for
context-sensitive help.
Query the DBNAME, INDEX, and TABLE attributes to find the name and index of the
corresponding database field and the table in which that database field resides.
NOTE: The value of the SESSION handles DATAENTRYRETURN attribute
determines the meaning of the RETURN key in a fill-in. If the attribute is TRUE,
Progress interprets a RETURN as a TAB event for most fill-ins and as a GO event for
a fill-in if that fill-in is the last tab item in a frame family (Version 6 behavior). In
this case, the GO event is propagated to all frames of the frame family. If the attribute
is FALSE, the window system determines the meaning of the RETURN key. The
default value is TRUE for character interfaces and FALSE for graphical interfaces.
For more information on frame families, see Chapter 19, Frames. For more
information on tab order, tab items, and DATAENTRYRETURN, see Chapter 25,
Interface Design.
176
17.2.3 Fill-in Fonts on Windows in Graphical Interfaces
On Windows, in graphical interfaces, if no font is specified for the fill-in, Progress uses two
default fonts:
A fixed font for date fields, numeric fields, and for character fields that contain fill
characters (such as the parentheses surrounding the area code of a telephone number).
A proportional font for character fields that do not contain fill characters.
Progress looks for definitions of these fonts in the current environment, which might be the
registry or an initialization file. If the current environment does not define these fonts, Progress
uses the system default fixed and proportional fonts. For more information on environments, see
the Chapter 23, Colors and Fonts. In this book and the chapter on user interface environments
in the Progress Client Deployment Guide.
17.3 Text
On Windows, fill-in fields use extra space on the screen for border decorations. To save space
for read-only text, you can view the value as a text widget rather than a fill-in. (If you want to
preserve the native look, you can view it as a native fill-in but set the SENSITIVE attribute to
FALSE.)
NOTE: You cannot update a field that is displayed as a text widget. Use the text widget only
for read-only data (for example, report data or field labels).
You can use the following form of the VIEWAS phrase to view a value as text:
The following code displays customer names as fill-ins.
SYNTAX
VIEW-AS TEXT [ size-phrase ] [ TOOLTIP tooltip ]
FOR EACH customer:
DISPLAY customer.name.
END.
Representing Data
177
Notice the spacing between customer names in the resulting screen:
To eliminate this space, view the customer name as text.
FOR EACH customer:
DISPLAY customer.name VIEW-AS TEXT.
END.
178
When you run this code, the screen appears as follows:
You can specify that all fields in a frame be displayed as text rather than as fill-ins by specifying
USETEXT in the frame phrase. This is especially useful for reports.
Representing Data
179
17.4 Sliders
A slider is a rectangular scale that represents a range of INTEGER values. A pointer that resides
on the trackbar within the scale indicates the current value. The current value is also displayed
in character format near the scale. Only values of type INTEGER can be viewed as sliders.
In a graphical interface, a slider takes on the native look of the windowing system. In a character
interface, the location of the pointer on the slider is indicated by reverse video; if the slider has
focus, and the current value option is set, square brackets appear around the current value.
The following form of the VIEWAS phrase defines a slider:
NOTE: The options TICMARKS, FREQUENCY, and TOOLTIP presented in the the slider
syntax box are supported on Windows only.
In both character and graphical interfaces, the slider can be oriented horizontally (with low
values to the left and high values to the right) or vertically (with low values at the bottom and
high values at the top). The default orientation is horizontal. You can set the orientation by
specifying HORIZONTAL or VERTICAL within the VIEWAS phrase or by setting the
HORIZONTAL attribute to TRUE or FALSE before the slider is realized.
Also, in both character and graphical interfaces, you can change the default numeric range from
small (minimum) to large (maximum) in addition to changing the default horizontal orientation
of the slider. Using the LARGETOSMALL option, you can override the default numeric
range as follows:
When the slider is positioned horizontally, the left-most position on the trackbar displays
the maximum value and the right-most position displays the minimum value.
When the slider is positioned vertically, the bottom-most position on the trackbar displays
the maximum value and the top-most position displays the minimum value.
SYNTAX
VIEW-AS SLIDER
MAX-VALUE max-value MIN-VALUE min-value
[ HORIZONTAL | VERTICAL ]
[ NO-CURRENT-VALUE ]
[ LARGE-TO-SMALL ]
[ TIC-MARKS { NONE | TOP | BOTTOM | LEFT | RIGHT | BOTH }
[ FREQUENCY n ] ]
[ TOOLTIP tooltip ]
[ size-phrase ]
1710
In both interfaces, the NOCURRENTVALUE option provides additional flexibility in terms
of the sliders presentation. By default, the current value for a given position on the trackbar
displays. However, if you use the NOCURRENTVALUE option, you can override this
default behavior to indicate that the slider will not automatically display the current value as the
pointer moves along the trackbar.
17.4.1 Manipulating a Slider
In a character interface, you can change the value of a slider by using the left and right arrow
keys (for a horizontal slider) or the up and down arrow keys (for a vertical slider).
To change a slider value when a slider displays on Windows:
Point to the pointer, press the SELECT or EXTEND mouse button, and drag or slide the
pointer.
Use the left and right arrow keys (for a horizontal slider) or the up and down arrow keys
(for a vertical slider).
Click on the trackbar, but not on the pointer. The pointer will move in larger increments
in the direction in which you clicked.
17.4.2 Range and Size
When defining a slider, you must minimally specify the sliders range. That is, you must specify
a minimum and maximum value for the widget. Specify the range using the MINVALUE and
MAXVALUE options, each of which takes an integer constant. You can change these values
by setting the MINVALUE and MAXVALUE attributes of the slider before the slider is
realized. Depending on the windowing system in use, the minimum value, maximum value, or
both may be displayed with the slider.
The range you specify for a slider has no effect on the size of the slider. For example, a
horizontal slider with range from 0 to 100 has the same default width as a slider with a range for
0 to 10. If a slider has a very wide range, you might want to increase its size so that you can
precisely position the marker with the mouse. Also, in a graphical interface, you might consider
using the TICMARKS option to display short hash marks on the outside of the slider. Used
with the FREQUENCY option, TICMARKS help reference specific increments for these hash
marks along the trackbar to provide a more precise indication of the value selected on your
slider.
In a character interface, a horizontal slider is only 6 positions wide by default and a vertical
slider slider is only 3 positions high. If you want the marker to accurately reflect the current
value for a slider with a large range, you must make the slider bigger.
Representing Data
1711
You can set the size of a slider by using the SIZECHARS or SIZEPIXELS option of the
VIEWAS phrase. Each of these options take a width and height value. You can also adjust the
size by setting the HEIGHTCHARS and WIDTHCHARS or HEIGHTPIXELS and
WIDTHPIXELS attributes.
NOTE: In a character interface, specify a SIZE that is a multiple of the range
(MAXVALUE MINVALUE) to ensure that the marker moves in even
increments.
When adjusting the size of a slider you are most concerned with the width for a horizontal slider
and the height for a vertical slider. However, you should be careful about changing the other
dimension. For example, if you make the height of a horizontal slider too small, the value
displayed with the slider may be partially obscured.
1712
17.4.3 Example Procedure
The following example procedure, p-slider.p, defines an INTEGER variable, numrows,
which is viewed as a slider. The sliders range is initially set as 1 to 20. However, before the
widget is realized, the maximum value is adjusted based on the current window size.
When you choose the Show Customers buttons, the size of the custframe is adjusted based on
the current value of the slider. The customer records are then displayed in that frame.
p-slider.p
DEFINE VARIABLE num-rows AS INTEGER LABEL "Number of Rows"
VIEW-AS SLIDER MIN-VALUE 1 MAX-VALUE 20
TIC-MARKS BOTTOM FREQUENCY 1.
DEFINE BUTTON show-custs LABEL "Show Customers".
FORM
num-rows HELP "Choose the number of customers per screen."
show-custs
WITH FRAME main-frame THREE-D.

WITH DOWN THREE-D.
ON CHOOSE OF show-custs
DO:
CLEAR FRAME cust-frame ALL.
FRAME cust-frame:DOWN =
INTEGER(num-rows:SCREEN-VALUE IN FRAME main-frame).
FOR EACH customer:
DISPLAY cust-num name WITH FRAME cust-frame.
DOWN WITH FRAME cust-frame.
END.

HIDE FRAME cust-frame.
END.
num-rows:MAX-VALUE IN FRAME main-frame = SCREEN-LINES - 2.

Representing Data
1713
For example, if you set the slider to 10 and press GO, the screen appears as follows:
1714
17.5 Toggle Boxes
A toggle box, sometimes called a check box, represents a logical value. The presence (true) or
absence (false) of filling in the toggle box indicates the current value. In a graphical interface,
a toggle box and its filling style take on the native look of the windowing system. You can
change a toggle value by positioning to it and pressing SPACEBAR. In a graphical interface, you
can point to the box and click the mouse SELECT button.
In a character interface, a toggle box is represented by a pair of square brackets ([ ]) that are
either empty (False) or contain an X (True).
Note that setting the FORMAT option or attribute does not affect the the toggle box widget. You
see the effects of the FORMAT change only if you display the value as a fill-in or text.
The following form of the VIEWAS phrase defines a toggle box:
There are no required options to use with the VIEWAS phrase when defining a toggle box.
You can optionally specify a label for the toggle box. Specify the label as a quoted character
string.
If you do not use the LABEL option, the field or variable name is used. For an array, the default
label includes the subscript in brackets ([ ]).
SYNTAX
VIEW-AS TOGGLE-BOX [ size-phrase ] [ TOOLTIP tooltip ]
Representing Data
1715
The following example, p-tbox.p, uses toggle boxes to represent an array of extent 3:
p-tbox.p (1 of 2)
DEFINE VARIABLE choices AS LOGICAL EXTENT 3
LABEL "Name", "Address", "Other"
INITIAL [yes, yes, no]
VIEW-AS TOGGLE-BOX.
DEFINE VARIABLE curcust AS INTEGER.
FORM
curcust LABEL "Customer Number" SKIP
"Information to Show:" SKIP
choices SKIP
WITH SIDE-LABELS FRAME choice-frame TITLE "Show Customer Information".

FORM
customer.name
WITH FRAME name-frame NO-LABELS TITLE "Customer Name".FORM
customer.address SKIP customer.address2 SKIP
customer.city customer.state SKIP
customer.country customer.postal-code
WITH FRAME addr-frame NO-LABELS USE-TEXT TITLE "Customer Address".
FORM
customer
EXCEPT name cust-num address address2 city state country postal-code
WITH FRAME oth-frame SIDE-LABELS USE-TEXT TITLE "Other Customer Data".
1716
When you run the example, you are prompted for a customer number. You can also set the three
toggle boxes labeled custnum, address, and other. You can set the toggle boxes to choose what
information to display about the customer. When you press GO, the trigger finds the customer
record and displays the information you specified.
ON GO OF FRAME choice-frame OR RETURN OF curcust
DO:
HIDE FRAME name-frame FRAME addr-frame FRAME oth-frame.

FIND customer WHERE cust-num = INPUT curcust NO-ERROR.
IF AMBIGUOUS customer OR NOT AVAILABLE customer
IF INPUT choices[1] /* name */
THEN DISPLAY customer.name WITH FRAME name-frame.
IF INPUT choices[2] /* address */
THEN DISPLAY customer.address customer.address2
customer.city customer.state country postal-code
WITH FRAME addr-frame.
IF INPUT choices[3] /* other */
THEN DISPLAY customer EXCEPT name cust-num address
address2 city state country postal-code
WITH FRAME oth-frame.
RETURN NO-APPLY.
END.
DISPLAY choices WITH FRAME choice-frame.
ENABLE ALL WITH FRAME choice-frame.
STATUS INPUT "Enter customer number and GO.".
p-tbox.p (2 of 2)
Representing Data
1717
For example, if you accept the default values for choices and press GO, the screen appears as
follows:
In p-tbox.p, changing the value of a toggle box has no immediate effect. The toggle boxes are
used to set a state that is then read when you press GO. By writing a trigger for the the
VALUECHANGED event, you can also use a toggle box to trigger an immediate action.
The following example, p-tbox2.p, displays three toggle boxes that specify search criteria for
customers. It displays the number of customers that meet the current criteria. Each time you
change the value of a toggle box, the procedure recalculates the number of customers that meet
the specified criteria.
1718
p-tbox2.p
DEFINE VARIABLE cnt AS INTEGER FORMAT ">>9".
DEFINE VARIABLE must-have-balance AS LOGICAL INITIAL no
VIEW-AS TOGGLE-BOX LABEL "Only if Balance Due".
DEFINE VARIABLE must-be-local AS LOGICAL INITIAL no
VIEW-AS TOGGLE-BOX LABEL "Only if in Local Country".
DEFINE VARIABLE must-get-discount AS LOGICAL INITIAL no
VIEW-AS TOGGLE-BOX LABEL "Only if Discount".
DEFINE VARIABLE local-country AS CHARACTER INITIAL "USA".
FORM
must-have-balance SKIP
must-be-local SKIP
must-get-discount SKIP(1)
"There are" cnt "customers that meet these criteria."
WITH FRAME count-frame TITLE "Counting Customers" NO-LABELS.
ON VALUE-CHANGED OF must-have-balance, must-be-local, must-get-discount
DO:
DEFINE VARIABLE meets-criteria AS LOGICAL.
cnt = 0.
FOR EACH customer:
meets-criteria = yes.
IF INPUT must-have-balance AND customer.balance <= 0
THEN meets-criteria = no.
ELSE IF INPUT must-be-local AND customer.country <> local-country
ELSE IF INPUT must-get-discount AND customer.discount = 0
IF meets-criteria
THEN cnt = cnt + 1.
END.
DISPLAY cnt WITH FRAME count-frame.
END.
cnt = 0.
FOR EACH customer:
cnt = cnt + 1.
END.
DISPLAY must-have-balance must-be-local must-get-discount cnt
WITH FRAME count-frame.
ENABLE must-have-balance must-be-local must-get-discount
WITH FRAME count-frame.
Representing Data
1719
The VALUECHANGED event occurs every time you alter the value of a toggle box. In
p-tbox2.p, each time you change the value of one of the toggle boxes, the procedure
recalculates the number of customers that meet the criteria specified.
17.6 Radio Sets
A radio set is a series of buttons (radio items) that represent a single field or variable. The term
radio set derives from the preset tuning buttons on many car radios. When one button is pressed,
any previously selected button pops out. Each of the buttons represents a different value for the
field or variable. At any one time, exactly one of the buttons is chosen. If the user chooses a
different button, the previously chosen button is automatically deselected.
In a graphical interface, a radio set takes on the native look of the windowing system. In the
character interface, each radio item is represented by a set of parentheses. The parentheses either
contain a space character (FALSE) or the letter X (TRUE).
A radio set can represent a LOGICAL, CHARACTER, INTEGER, DECIMAL, or DATE
value. Radio sets are appropriate for fields that can have only one of a limited number of values.
1720
17.6.1 Defining a Radio Set
The following form of the VIEWAS phrase defines a radio set:
When viewing a value as a radio set, you must minimally specify one label/value pair for each
possible value of the underlying variable or field (the label is the label that appears with the
button). You can optionally specify an orientation for the set (the default is vertical) and a size.
For a horizontal radio set, you can also specify the EXPAND option. This option spaces the
buttons uniformly based on the length of the longest button label. If you do not give this option,
the spacing between buttons varies depending on the size of the labels.
SYNTAX
VIEW-AS RADIO-SET
[ HORIZONTAL [ EXPAND ] | VERTICAL ]
[ size-phrase ] RADIO-BUTTONS label , value
[ , label , value ] ...
[ TOOLTIP tooltip ]
Representing Data
1721
17.6.2 Example Procedures
The following example defines an integer variable, paystat, that can have a value of 1, 2, or 3.
It prompts the user to update the variable by displaying it as a radio set. It then redisplays the
variable as a fill-in.
By viewing the variable as a radio set, the user is constrained to selecting one and only one of
the meaningful values for the variable. Since each integer value represents a different state for
an outstanding invoice, the procedure defines meaningful labels that describe these states and
displays these in each button, rather than displaying the integer values:
NOTE: When you view a field or variable as a radio set, if it is not set to a valid value, it
defaults to the first radio button. In the example, paystat is explicitly initialized to 1.
When you run this procedure, because paystat is initialized to 1, the first radio button is
initially chosen. You can either accept that value or choose another button. When you press GO,
the value is assigned to paystat and then viewed as a text widget.
p-radio1.p
DEFINE VARIABLE pay-stat AS INTEGER INITIAL 1 LABEL "Pay Status"
VIEW-AS RADIO-SET RADIO-BUTTONS "Unpaid", 1,
"Partially paid", 2,
"Paid in full", 3.
FORM
pay-stat
WITH FRAME in-frame.FORM
pay-stat VIEW-AS TEXT
WITH FRAME out-frame.

ON GO OF FRAME in-frame
DO:
ASSIGN pay-stat.
DISPLAY pay-stat WITH FRAME out-frame.
END.
DISPLAY pay-stat WITH FRAME in-frame.
ENABLE pay-stat WITH FRAME in-frame.
STATUS INPUT "Select a pay status and GO".
1722
For example, if you select the second radio button and press GO, the screen appears as follows:
Note that when you select the second button, the first button is automatically deselected.
As with toggle boxes, you can also use the VALUECHANGED event with a radio set. This
gives the user instant feedback when a new radio button is chosen, as in the following example:
p-radio2.p
DEFINE VARIABLE math-const AS DECIMAL FORMAT "9.999"
VIEW-AS RADIO-SET RADIO-BUTTONS "e", 2.72,
"pi", 3.14,
"square root of 2", 1.41
INITIAL 2.72.
FORM
math-const SKIP
description AS CHARACTER FORMAT "x(50)"
WITH FRAME const-frame NO-LABELS TITLE "Common Constants".

ON VALUE-CHANGED OF math-const
DO:
DISPLAY "The value of this constant is approximately " +
SELF:SCREEN-VALUE @ description WITH FRAME const-frame.
END.

DISPLAY math-const WITH FRAME const-frame.
ENABLE math-const WITH FRAME const-frame.
APPLY "VALUE-CHANGED" TO math-const.
Representing Data
1723
When you run this procedure, the description message changes immediately each time you
choose a different radio button.
For example, if you select the second radio button, the screen appears as follows:
1724
17.7 Editors
An editor allows full editing of large character fields. The editor widget supports features such
as cut, copy, paste, and word-wrap.
17.7.1 Defining an Editor
The following form of the VIEWAS phrase defines an editor:
When viewing a character string as an editor, you must specify a size for the editor in one of
two ways:
Specify a width and height for the editor using the SIZE phrase.
Specify the number of lines visible within the editor using the INNERLINES option and
the number of characters visible in each line using the INNERCHARS option.
You can optionally limit the number of characters that the user can enter or that can be displayed
within the editor by specifying the MAXCHARS option or setting the MAXCHARS
attribute. You can also enable horizontal scrolling (thereby disabling word-wrap) and display
scroll bars.
On Windows, you can specify an editor that handles larger quantities of text than normal using
the LARGE option. For more information, see the Using an Editor section.
SYNTAX
VIEW-AS EDITOR
{ size-phrase
| INNER-CHARS char INNER-LINES lines
}
[ BUFFER-CHARS chars ]
[ BUFFER-LINES lines ]
[ LARGE ]
[ MAX-CHARS characters ]
[ NO-WORD-WRAP ]
[ SCROLLBAR-HORIZONTAL ]
[ SCROLLBAR-VERTICAL ]
[ TOOLTIP tooltip ]
Representing Data
1725
The p-edit.p procedure displays the catdescription field of the item table as an editor that is
30 characters wide and 5 characters long:
When you run p-edit.p, the screen appears as follows:
p-edit.p
FORM
item.item-num item-name item.price on-hand
allocated re-order on-order cat-page
item.cat-description
VIEW-AS EDITOR SIZE-CHARS 30 BY 5
WITH FRAME x SIDE-LABELS.

FOR EACH item:
UPDATE item WITH FRAME x.
END.
1726
17.7.2 Using an Editor
By default, editors support vertical scrolling with the up and down arrow keys, whether or not
you specify scroll bars for the editor. Therefore, in the example, the user can type more than four
lines of text within the editor. When the user moves beyond the last line shown, the first line
scrolls up and out of the visible editing area; a new line scrolls into bottom of the visible area.
If the user later moves the cursor up to the first line, the last line scrolls down and out of the
visible editing area and the first line becomes visible again. To allow the user to scroll vertically
using a scroll bar, specify the SCROLLBARVERTICAL option in the VIEWAS phrase.
Word Wrap
By default, the editor also supports word-wrap. This means that when you reach the end of a
line within the editor, text wraps to the next line rather than scrolling to the right. You can
choose to enable horizontal scrolling instead by specifying the NOWORDWRAP option in
the VIEWAS phrase. You can also specify SCROLLBARHORIZONTAL along with
NOWORDWRAP to add a horizontal scroll bar to the editor. If you specify
NOWORDWRAP, but not SCROLLBARHORIZONTAL, the user can scroll horizontally
by using the left and right arrow keys at the edge of the displayed text.
Graphical Editors
Within an editor in a graphical environment, the user can select a range of text by holding down
the SELECT mouse button and dragging the cursor. The user can delete the selected text by
pressing DELETE. You can program further functionality for the editor by manipulating the
editors attributes and methods.
Also, when a graphical editor is disabled (made insensitive to input), Progress grays out the
contents and restores it when the editor is re-enabled.
Windows Editors
On Windows, editor widgets are limited to 20K of data, by default. To support more data, you
must specify the LARGE option in the VIEWAS phrase or set the LARGE attribute to TRUE.
This raises the limit according to available system resources. If you try to enter more than 20K
of data into a normal editor widget on Windows, or set MAXCHARS greater than 20K,
Progress displays a warning message.
NOTE: The LARGE option of the VIEWAS phrase and the LARGE attribute apply only to
graphical interfaces on Windows.
Representing Data
1727
Character Editors
In a character interface, the user can move to the beginning or end of an editor by using the
TOPCOLUMN or BOTTOMCOLUMN keys. The DELETEFIELD key deletes a word to the right
of the cursor. The DELETECOLUMN keys deletes to the end of the current line. The
INSERTCOLUMN key inserts a new line above the current line. The RETURN key creates a new
line after the current line. The user can toggle between inserting and overtyping text using the
INSERTMODE key.
NOTE: In character interfaces, the editor does not support the tab character. When Progress
reads a file that contains tabs into a character editor widget, it replaces the tabs with
eight space characters. When it writes out the file, the tabs are not restored, and the
file is permanently changed.
17.7.3 Attributes and Methods
At run time, you can query or set editor-specific attributes to accomplish the following:
Enable automatic indentation when the user presses RETURN
Select text or place the text cursor
Determine where the user has placed the text cursor
Determine whether the user has selected text and the location of the selection
Determine whether the user has modified the contents of the editor and find the length
Change the compile-time specifications of INNERCHARS, INNERLINES,
MAXCHARS, WORDWRAP, SCROLLBARHORIZONTAL, and
SCROLLBARVERTICAL
NOTE: Although you can store a large amount of data in an editor widget, the
SCREENVALUE attribute might not work as expected for values longer than 32K.
In addition to attributes, the editor also supports methods that allow a procedure to:
Delete individual characters, text selections, or entire lines
Insert strings or files at the current cursor position
Search for, search-and-replace, or select text
Convert a row and column position to a character offset
Save the contents of the editor to a file
1728
For more information on each attribute and method, see the Progress Language Reference.
17.7.4 Adding Functionality to an Editor
The following example, p-edit2.p, provides a more functional editor than p-edit1.p. This
example lets you read an operating system file into the editor, make modifications to it, and then
save the results. To do this, the example uses a menu bar and the READFILE and SAVEFILE
methods of the editor widget:
p-edit2.p (1 of 2)
DEFINE VARIABLE e AS CHARACTER VIEW-AS EDITOR
INNER-CHARS 70 INNER-LINES 15 SCROLLBAR-VERTICAL.
DEFINE VARIABLE filename AS CHARACTER FORMAT "x(60)".
DEFINE VARIABLE status-ok AS LOGICAL.
DEFINE SUB-MENU filemenu
MENU-ITEM fopen LABEL "Open..."
MENU-ITEM fsave LABEL "Save As..."
MENU-ITEM fexit LABEL "E&xit".

SUB-MENU filemenu LABEL "File".
FORM
e
WITH FRAME edit-frame.
FORM
"Enter Filename:" SKIP
filename
WITH FRAME file-spec NO-LABELS VIEW-AS DIALOG-BOX.
ON RETURN OF filename IN FRAME file-spec
APPLY "GO" TO filename.
ON CHOOSE OF MENU-ITEM fopen
DO:
FRAME file-spec:TITLE = "Open File".
UPDATE filename WITH FRAME file-spec.
status-ok = e:READ-FILE(filename) IN FRAME edit-frame.
IF NOT status-ok
THEN MESSAGE "Could not read" filename.
END.
Representing Data
1729
When you run this example, you can use the menu items to read from a file or type text directly
into the editor.
You can increase the functionality of this editor further by adding additional options to the menu
bar and using additional editor methods. For example, you can add an Edit submenu that
includes a searchandreplace option using the REPLACE method.
ON CHOOSE OF MENU-ITEM fsave
DO:
FRAME file-spec:TITLE = "Save File".
UPDATE filename WITH FRAME file-spec.
status-ok = e:SAVE-FILE(filename) IN FRAME edit-frame.
IF NOT status-ok
THEN MESSAGE "Could not write to" filename.
END.


ENABLE e WITH FRAME edit-frame NO-LABELS.
WAIT-FOR CHOOSE OF MENU-ITEM fexit OR
WINDOW-CLOSE OF CURRENT-WINDOW.
p-edit2.p (2 of 2)
1730
NOTE: When you save the editor text to a file, some characters save differently, depending
on your operating system. For example, RETURN key input writes out on Windows
as x0d0d0a. On UNIX, this writes out as x0d0a. Similarly, the end-of-line on
Windows writes out as <CR><LF>. On UNIX, this writes out as <CR> alone. Future
versions of Progress might address these issues, allowing for improved portability
among platforms.
17.8 Selection Lists
A selection list is a scrollable list of values for a CHARACTER field or variable. You can use
a selection list to allow an end user to select one or more items from a finite list of character
values. You can move within a selection list using the up and down arrow keys. In graphical and
character interfaces, you can position to a value in the list by typing the first letter of the value.
On Windows, the user can select a value by pointing at it and clicking the SELECT mouse
button. In a character interface, the user can select a value by positioning to it and pressing either
RETURN or SPACEBAR. When an item is selected, the VALUECHANGED event occurs.
Typically, after the user selects one or more items from the list, you want to perform some
action. For example, if a selection list contains a list of tasks, you might want to run a procedure
to perform the selected task. Running the associated procedure is the default action for that
selection list. You establish the default action by coding a trigger for the DEFAULTACTION
event. This event occurs when the user:
Double-clicks the SELECT mouse button on an item or positions to the item and presses
RETURN on Windows.
Presses the ENTER key in character mode.
Representing Data
1731
17.8.1 Defining a Selection List
The following form of the VIEWAS phrase defines a selection list.
When viewing a value as a selection list, you must minimally specify the size of the selection
list in one of the following ways:
Using the SIZE, SIZECHARS, or SIZEPIXELS option
Using the INNERCHARS and INNERLINES options
Using the LIKE option of the DEFINE VARIABLE statement to define a variable similar
to another variable or field defined as a selection list
You can optionally specify:
The LISTITEMS option to populate the list with items.
The SINGLE option to indicate that the user can select only one of the values or the
MULTIPLE option to indicate that the user can select more than one value. If more than
one item is selected, then the field or variable value is a comma-separated list of the
selected items.
The NODRAG option to indicate that the user cannot select items by simultaneously
holding down the mouse SELECT button and dragging the mouse through the list.
SYNTAX
VIEW-AS SELECTION-LIST
[ SINGLE | MULTIPLE ]
[ NO-DRAG ]
[ LIST-ITEMS item-list ]
[ SCROLLBAR-HORIZONTAL ]
[ SCROLLBAR-VERTICAL ]
{ size-phrase | INNER-CHARS cols INNER-LINES rows }
[ SORT ]
[ TOOLTIP tooltip ]
1732
17.8.2 Scrolling
If a list is not long enough to display all the values on the screen, you can scroll up and down
within the list by positioning with the arrow keys. Optionally, you can establish a vertical scroll
bar for the selection list. You can do this by specifying the SCROLLBARVERTICAL option
in the VIEWAS phrase or by setting the SCROLLBARVERTICAL attribute to TRUE.
Similarly, the selection list may not be as wide as some values in the list. You can establish a
horizontal scroll bar by specifying the SCROLLBARHORIZONTAL option in the VIEWAS
phrase or setting the SCROLLBARHORIZONTAL attribute to TRUE.
By default, no scroll bars are displayed with a selection list. After the selection list is realized,
you cannot add or remove scroll bars.
17.8.3 Character Mode
If you use a selection list in a character interface, you need to be aware of several considerations:
You can select or deselect an item in a selection list by pressing the SPACE BAR. This
causes the VALUECHANGED event.
In a single selection list, the ENTER key performs the default action. In a multiple selection
list, the ENTER key first toggles the selection of the current item (causing a
VALUECHANGED event) and then performs the default action. Therefore, to perform
the default action on a multiple selection list, select all but one value with the SPACE BAR,
position to the remaining value, and then press ENTER.
If drag is enabled for a selection list, then each time you move to a new item within the
list, the new item is selected. This means that the VALUECHANGED event might occur
many times as you navigate through the list. If drag is disabled, then an item is selected
only when you press the SPACE BAR or ENTERKEY.
For a single selection list, drag is enabled by default in the character interface. You can
optionally specify NODRAG or change the DRAGENABLED attribute value. A
multiple selection list in the character interface always behaves as though drag is disabled.
Representing Data
1733
The following example defines a variable, position, to be viewed as a selection list:
p-sel1.p
DEFINE VARIABLE position AS CHARACTER LABEL "Position" INITIAL "Pitcher"
VIEW-AS SELECTION-LIST INNER-CHARS 18 INNER-LINES 10
LIST-ITEMS "Pitcher", "Catcher", "First Base", "Second Base",
"Third Base", "Shortstop", "Left Field",
"Center Field", "Right Field", "Designated Hitter".
FORM
position
WITH FRAME sel-frame.
FORM
position FORMAT "x(18)" VIEW-AS TEXT
WITH FRAME text-frame.
ON GO OF FRAME sel-frame
DO:
ASSIGN position.
DISPLAY position WITH FRAME text-frame.
END.
DISPLAY position WITH FRAME sel-frame.
ENABLE position WITH FRAME sel-frame.
STATUS INPUT "Select a position and GO.".
1734
The INNERCHARS option specifies that items in the selection list are 18 characters wide. The
INNERLINES option specifies that 10 of the values are visible at a time. In this example,
position has 10 possible values, so all values are always visible. When you press GO, the second
frame displays position as a text field, as in the following example:
Representing Data
1735
At run time, a procedure can set or query selection list attributes to accomplish the following:
Change the delimiter Progress uses in a multiple selection list to separate the values stored
in the SCREENVALUE attribute. Do this with the DELIMITER attribute.
Display all list items in sorted order by setting the SORT attribute.
Change the size of the list with the INNERCHARS or INNERLINES attributes.
Change the contents of the list with the LISTITEMS attribute.
Change the selection policy of the list with the MULTIPLE attribute, but only before the
selection list is realized.
Change the DRAGENABLED attribute to allow or disallow the user selecting items by
dragging over them with the mouse. You can change this attribute only before realization.
Query the total number of items in the list with the NUMITEMS attribute.
In addition to attributes, the selection list also supports methods that allow a procedure to:
Add an item to the beginning or end of the list with the ADDFIRST( ) or ADDLAST(
) methods.
Delete an item (by value or index) with the DELETE( ) method.
Insert an item or delimiter-separated item list (by value or index) with the INSERT( )
method.
Replace an existing item (by value or index) with a new item (or delimiter-separated item
list) with the REPLACE( ) method.
Retrieve the item specified by an index with the ENTRY( ) method.
Return the index of a specified item with the LOOKUP( ) method.
Query whether an item is currently selected with the ISSELECTED( ) method.
Scroll an item to the top of the list with the SCROLLTOITEM( ) method.
1736
For example, the following procedure reads filenames into a selection list and uses the
LISTITEMS attribute to change the contents of the list dynamically. To compare it with a
similar procedure using a combo box, see the p-combo2.p procedure in the Combo Boxes
section:
p-sel2.p (1 of 2)
DEFINE STREAM dirlist.
DEFINE VARIABLE ok-status AS LOGICAL.
DEFINE VARIABLE f-name AS CHARACTER FORMAT "x(14)".
DEFINE VARIABLE list-contents AS CHARACTER FORMAT "x(200)".
DEFINE VARIABLE dir AS CHARACTER FORMAT "x(40)".
DEFINE VARIABLE sl AS CHARACTER VIEW-AS SELECTION-LIST
INNER-CHARS 15 INNER-LINES 10 SORT SCROLLBAR-VERTICAL.
FORM
"Directory Pathname:" SKIP
dir AT 3 SKIP
"Filename:" SKIP
sl AT 3
WITH FRAME sel-frame NO-LABELS TITLE "File Selector".
FORM
Readable AS LOGICAL Writable AS LOGICAL
WITH FRAME file-status SIDE-LABELS.

ON GO, MOUSE-SELECT-DBLCLICK OF dir
DO:
ASSIGN dir.
RUN build-list.
END.
ON DEFAULT-ACTION OF sl
DO:
FILE-INFO:FILENAME = dir + "/" + SELF:SCREEN-VALUE.
IF INDEX(FILE-INFO:FILE-TYPE, "D") > 0
THEN DO:
HIDE FRAME file-status.
dir = FILE-INFO:PATHNAME.
RUN build-list.
DISPLAY dir WITH FRAME sel-frame.
END.
Representing Data
1737
ELSE DO:
ASSIGN Readable = (INDEX(FILE-INFO:FILE-TYPE, "R") > 0)
Writable = (INDEX(FILE-INFO:FILE-TYPE, "W") > 0)

FRAME file-status:TITLE = "Attributes of " + SELF:SCREEN-VALUE.
DISPLAY Readable Writable WITH FRAME file-status.
END.
END.
dir = OS-GETENV("DLC").
RUN build-list.
ENABLE dir sl WITH FRAME sel-frame.
PROCEDURE build-list:
ok-status = SESSION:SET-WAIT-STATE("General").
INPUT STREAM dirlist FROM OS-DIR (dir).
IMPORT STREAM dirlist f-name.
list-contents = f-name.
REPEAT:
list-contents = list-contents + "," + f-name.
END.
INPUT CLOSE.
sl:LIST-ITEMS IN FRAME sel-frame = list-contents.
ok-status = SESSION:SET-WAIT-STATE("").
END PROCEDURE.
p-sel2.p (2 of 2)
1738
This code allows you to select from a selection list of all the files and subdirectories within the
specified directory. The DLC directory is the initial directory. The following screen appears:
When you double-click on an item in the list (or press RETURN in character mode), the
DEFAULTACTION trigger executes. If the item is a file, the trigger displays your access to
that file. If the item is a directory, the trigger rebuilds the selection list with the contents of that
directory.
Note that within the internal procedure, buildlist, the list of file and directory names is built
first, and then the LISTITEMS method is used to change the contents of the selection list. You
could use the ADDLAST( ) method within the REPEAT loop to add items to the selection list
one at a time, but using LISTITEMS once is more efficient.
Representing Data
1739
17.9 Combo Boxes
A combo box consists of a fill-in field or variable, a button, and a selection list. A combo box
can display any single value from the selection list in the fill-in field. This single value can also
be assigned to the underlying field or variable.
Progress provides the following types of combo-box widgets:
A SIMPLE combo-box widget with a read/write edit control and a selection list that is
always visible. This widget is supported in graphical interfaces only, and only in
Windows. If you specify a SIMPLE combobox widget in a character interface, Progress
treats it as a DROPDOWNLIST combobox widget.
A DROPDOWN combo-box widget with a read/write edit control and a selection list that
appears when you click the drop-down button. This option is supported in graphical
interfaces only, and only in Windows. If you specify a DROPDOWN combobox widget
in a character interface, Progress treats it as a DROPDOWNLIST combobox widget.
A DROPDOWNLIST combobox widget with a read-only edit control and a selection
list that appears when you click the drop-down button. This is the default.
You can use the combobox widget with a CHARACTER, INTEGER, DECIMAL, LOGICAL,
or DATE field or variable. The value representations in the drop-down list conform to the data
type of the underlying field or variable. Like radio sets and selection lists, combo boxes are
useful for representing fields or variables that have a limited number of possible values. One
advantage of combo boxes is that they take up less screen space than radio sets and selection
lists.
The end user can position to a value in the drop-down list by using the arrow keys in all
interfaces, or in graphical interfaces by using the scroll bar.
To select a value in the character interface, the end user can position to the value in the
drop-down list using the arrow keys and press SPACEBAR or RETURN to confirm the selection.
To select a value in the graphical interface, the end user can apply the following techniques:
Position to the value in the drop-down list using the scroll bar and click on the value in the
drop-down list using the SELECT mouse button.
Enter text in the fill-in and allow the edit control to complete keyboard input to the
combo-box, based on a potential or unique match, by searching through the items in the
drop-down list.
Position to the value in the drop-down list using the arrow keys and press SPACEBAR or
RETURN to confirm the selection.
1740
When the user selects an item, it triggers the VALUECHANGED event.
Thus, a combo box combines the functionality of a fill-in field, selection list, and radio set. It
uses a fill-in field to display the selected item, and like a selection list displays a list of available
values. Like a radio set, it supports sets of values for any Progress data type and allows selection
of any one value at a time.
17.9.1 Defining a Combo Box
The following form of the VIEWAS phrase defines a combo box:
When viewing a value as a combo box, only the fill-in field displaying the value appears in a
box along with a button to indicate that it is combo box. The drop-down list appears only when
you choose the fill-in or button in the box. The definition options have these effects:
The LISTITEMS option specifies a comma-separated list of values for the drop-down
list. The representation for each value must conform to the data type and format of the
underlying field or variable. In Windows, there is no default selected value for the combo
box; the fill-in is empty. The combo box fillin remains empty until you assign an item in
the list to the screen value of the widget.
The LISTITEMPAIRS option specifies a list of label-value pairs. Each pair represents
the label and value of a field or variable. When the drop-down list appears, it displays each
pairs label. When the user selects a label, Progress assigns the corresponding value to the
field or variable.
The INNERLINES option specifies the number of lines (items) displayed in the
drop-down list at one time.
In Windows, the size-phrase option specifies the outside width of the combo box. This
includes the drop-down list width. The fill-in height is always the height of one character
unit for a fill-in. This option also has no effect on the drop-down list height or the format
of data in the list.
SYNTAX
VIEW-AS COMBO-BOX
[ LIST-ITEMS item-list | LIST-ITEM-PAIRS item-pair-list ]
[ INNER-LINES lines ] [ size-phrase ] [ SORT ]
[ TOOLTIP tooltip ]
[ SIMPLE | DROP-DOWN | DROP-DOWN-LIST ]
[ MAX-CHARS characters ]
[ AUTO-COMPLETION [ UNIQUE-MATCH ] ]
Representing Data
1741
The SORT option causes items in the drop-down list (LISTITEMS) to be displayed in
sorted order no matter what order they are assigned. This option is supported in character
interfaces only, and only in Windows.
The TOOLTIP option allows you to define a help text message for a text field or text
variable. Progress automatically displays this text when the user pauses the mouse button
over a text field or text variable for which a tooltip is defined. No tooltip is the default.
This option is supported in Windows only.
The SIMPLE option specifies a combobox widget with a read/write edit control and a
selection list that is always visible. This option is supported in graphical interfaces only,
and only in Windows.
The DROPDOWN option specifies a combobox widget with a read/write edit control
and a selection list that appears when you click the drop-down button. This option is
supported in graphical interfaces only, and only in Windows.
The DROPDOWNLIST option specifies a combobox widget with a read-only edit
control and a selection list that appears when you click the drop-down button. This is the
default.
The MAXCHARS option specifies the maximum number of characters the edit control
can hold. Use MAXCHARS with only SIMPLE and DROPDOWN comboboxes. It is
ignored for DROPDOWNLIST comboboxes. This option is supported in graphical
interfaces only, and only in Windows.
The AUTOCOMPLETION option specifies that the edit control automatically complete
keyboard input to the combobox, based on a potential match, by searching through the
items in the drop-down list. This option is supported in graphical interfaces only, and only
in Windows.
The UNIQUEMATCH option specifies that the edit control complete keyboard input to
the combobox, based on a unique match, by searching through the items in the
drop-down list. This option is supported in graphical interfaces only, and only in
Windows.
1742
17.9.2 Working with Combo Boxes
In general, it is important to keep in mind that a combo box maintains three types of data:
The drop-down list, which is the available set of input values in character string form
The screen buffer value displayed in the fill-in, which is the currently selected character
string from the drop-down list
The record buffer value, which is the current value of the underlying field or variable
stored according to the field or variable data type
For an end user, it is only possible to select a value for the combo box from the available
drop-down list. As with any data-representation widget, the application must assign the combo
box with the ASSIGN statement to move this value into the record buffer.
It is possible for the application to assign any value to the underlying field or variable consistent
with its data type. However, the application can only display a value from the field or variable
(move the record buffer value to the screen buffer) that is also available in the combo box
drop-down list.
NOTE: If you set an initial value for the underlying field or variable (through assignment or
the INITIAL option), you must explicitly display as well as enable the combo box
widget in order to move the initial value to the screen buffer for display in the fill-in.
Otherwise when you enable the widget, nothing is displayed.
Representing Data
1743
The procedure p-combo1.p illustrates several ways to interact with a combo box. It displays a
frame containing a combo box labeled Finish and several buttons. Each button modifies the
combo box and displays the current value of the underlying variable, finishvar, in the message
area.
p-combo1.p (1 of 2)
DEFINE VARIABLE finish-var AS CHARACTER INITIAL "Medium"
FORMAT "x(10)" LABEL "Finish" VIEW-AS COMBO-BOX INNER-LINES 3
LIST-ITEMS "Fine", "Medium", "Coarse".

DEFINE BUTTON bGrain LABEL "Grain List".
DEFINE BUTTON bColor LABEL "Color List".
DEFINE BUTTON bCancel LABEL "Cancel".
DEFINE BUTTON bAdd LABEL "Add".
DEFINE BUTTON bNow LABEL "Now".
DEFINE VARIABLE stat AS LOGICAL.
DEFINE VARIABLE cnt AS INTEGER.
DEFINE VARIABLE type-var AS INTEGER INITIAL 2.
DEFINE VARIABLE type-char AS CHARACTER FORMAT "x(10)".
DEFINE FRAME a finish-var SKIP(1) bGrain bColor bAdd bNow bCancel
WITH SIDE-LABELS.
ON CHOOSE OF bNow IN FRAME a
DO:
MESSAGE "finish-var value is" finish-var.
END.
ON CHOOSE OF bAdd IN FRAME a
DO:
REPEAT cnt = 1 to 3:
type-char = ENTRY(cnt, finish-var:LIST-ITEMS) + STRING(type-var).
stat = finish-var:ADD-LAST(type-char).
END.
type-var = type-var + 1.
END.
ON CHOOSE OF bGrain IN FRAME a
DO:
finish-var:LIST-ITEMS = "Fine,Medium,Coarse".
type-var = 2.
APPLY "VALUE-CHANGED" TO finish-var.
END.
1744
When you choose the combo box at startup, it displays the drop-down list with the initial value
selected, as in the following screen:
Note that the procedure explicitly displays the combo box to show the initial assigned value.
Each time you change the value (either directly with the drop-down list or indirectly with a
button), the VALUECHANGED event is triggered to force assignment of the new value.
The procedure also illustrates the combo box LISTITEMS attribute and ADDLAST( )
method. Progress provides additional attributes and methods to increase the usability of combo
boxes.
ON CHOOSE OF bColor IN FRAME a
DO:
finish-var:LIST-ITEMS = "Light,Neutral,Dark".
type-var = 2.
APPLY "VALUE-CHANGED" TO finish-var.
END.
ON VALUE-CHANGED OF finish-var IN FRAME a
DO:
ASSIGN finish-var.
MESSAGE "Assigning" finish-var.
END.
ENABLE ALL WITH FRAME a.
DISPLAY finish-var WITH FRAME a.
WAIT-FOR CHOOSE OF bCancel IN FRAME a.
p-combo1.p (2 of 2)
Representing Data
1745
At run time, a procedure can set or query combo box attributes to accomplish the following:
Change the size of the list by setting the INNERLINES attribute (Windows and character
interfaces only). The value must be at least 3.
Display all list items in sorted order by setting the SORT attribute (Windows and character
interfaces only).
Change the contents of the list with the LISTITEMS attribute, and change the delimiter
that Progress uses to separate items in the list using the DELIMITER attribute.
Change the format of combo box fill-in and list data with the FORMAT attribute. If you
change the format after realization, then all items in the list are converted to the new
format.
Query or set the item currently selected in the list with the SCREENVALUE attribute. If
nothing is selected, this attribute returns the null string (" "). If you set the attribute to an
item not in the list, Progress ignores the setting and displays a warning message.
Query the total number of items in the list with the NUMITEMS attribute.
Query the data type of the combo box with the DATATYPE attribute. You can set this
attribute before realization, but you lose all items currently in the list.
In addition to attributes, the combo box also supports list manipulation methods that allow a
procedure to:
Add an item to the beginning or end of the list with the ADDFIRST( ) or ADDLAST( )
methods.
Delete an item (by value or index) with the DELETE( ) method.
Insert an item or delimiter-separated item list (by value or index) with the INSERT( )
method.
Replace an existing item (by value or index) with a new item (or delimiter-separated item
list) with the REPLACE( ) method.
Retrieve the item specified by an index with the ENTRY( ) method.
Return the index of a specified item with the LOOKUP( ) method.
1746
For example, the following procedure reads filenames into a combo box and uses the
LISTITEMS attribute to change the contents of the list dynamically. To compare it with a
similar procedure using a selection list, see the p-sel2.p procedure in the Selection Lists
section.
p-combo2.p (1 of 2)
DEFINE STREAM dirlist.
DEFINE VARIABLE ok-status AS LOGICAL.
DEFINE VARIABLE f-name AS CHARACTER FORMAT "x(14)".
DEFINE VARIABLE list-contents AS CHARACTER FORMAT "x(200)".
DEFINE VARIABLE dir AS CHARACTER FORMAT "x(40)".
DEFINE VARIABLE flcombo AS CHARACTER FORMAT "x(15)"
VIEW-AS COMBO-BOX INNER-LINES 10 SORT.
FORM
"Directory Pathname:" SKIP
dir AT 3 SKIP
"Filename:" SKIP
flcombo AT 3
WITH FRAME sel-frame NO-LABELS TITLE "File Selector".
FORM
Readable AS LOGICAL Writable AS LOGICAL
WITH FRAME file-status SIDE-LABELS.

ON GO, MOUSE-SELECT-DBLCLICK, RETURN OF dir
DO:
ASSIGN dir.
RUN build-list.
END.
ON VALUE-CHANGED OF flcombo
DO:
FILE-INFO:FILENAME = dir + "/" + SELF:SCREEN-VALUE.
IF INDEX(FILE-INFO:FILE-TYPE, "D") > 0
THEN DO:
HIDE FRAME file-status.
dir = FILE-INFO:PATHNAME.
RUN build-list.
END.
ELSE DO:
ASSIGN Readable = (INDEX(FILE-INFO:FILE-TYPE, "R") > 0)
Writable = (INDEX(FILE-INFO:FILE-TYPE, "W") > 0)

FRAME file-status:TITLE = "Attributes of " + SELF:SCREEN-VALUE.
DISPLAY Readable Writable WITH FRAME file-status.
END.
END.
Representing Data
1747
dir = OS-GETENV("DLC").
ENABLE dir flcombo WITH FRAME sel-frame.
PROCEDURE build-list:
ok-status = SESSION:SET-WAIT-STATE("General").
INPUT STREAM dirlist FROM OS-DIR (dir).
list-contents = f-name.
REPEAT:
list-contents = list-contents + flcombo:DELIMITER IN FRAME sel-frame
+ f-name.
END.
INPUT CLOSE.
flcombo:LIST-ITEMS IN FRAME sel-frame = list-contents.
ok-status = SESSION:SET-WAIT-STATE("").
END PROCEDURE.
p-combo2.p (2 of 2)
1748
This code allows you to select from a combo box of all the files and subdirectories within the
specified directory. The DLC directory is the initial directory.
When you double click, press RETURN, or press GO on the Directory Pathname field, the
procedure builds a list of the files in the combo box from the specified directory. When you
select a new item in the list, the VALUECHANGED trigger executes. If the item is a file, the
trigger displays your access to that file. If the item is a directory, the trigger rebuilds the combo
box with the contents of that directory.
Note that within the internal procedure, buildlist, the list of file and directory names is built
first, and then the LISTITEMS attribute is used to change the contents of the combo box. You
could use the ADDLAST( ) method within the REPEAT loop to add items to the combo box
one at a time, but using LISTITEMS once is more efficient. Note, also, the use of the
DELIMITER attribute to ensure that the list is built using the current list delimiter.
Representing Data
1749
17.10 Applying Formats When Displaying Widgets
When you view a value as text, a fill-in, a toggle box, combo box, or a radio set, you can specify
a format. Progress supports character, numeric, logical, and date formats for these widgets:
Character, numeric, and date formats determine how many spaces and special characters
(such as dollar signs and decimal points) Progress uses when displaying the text that
appears in text widgets, fill-ins and radio sets. For the fill-in, the format also establishes a
constraint on the data that the user can enter.
A logical format determines the strings that Progress uses when it displays the logical
values TRUE and FALSE. Logical formats are used with text, fill-ins, and toggle boxes.
For fill-ins, the format also establishes a constraint on the data the user can enter.
You can specify more than one format for a widget as long as you display the widget in a new
frame each time you introduce a new format.
This section explains how to specify a display format within a Progress procedure. See the
Progress Database Design Guide for information on specifying a format in the database.
17.10.1 Using the FORMAT Option
You can use the FORMAT option in two ways:
With a screen I/O statement, such as an UPDATE or DISPLAY to specify a format for a
database field
With either a screen I/O statement or the DEFINE VARIABLE statement to specify a
format for a variable
The following example introduces some of the formatting syntax explained in the remaining
sections. It also demonstrates the flexibility you have in defining multiple formats for a single
widget:
p-ftchp2.p
DEFINE VARIABLE test AS CHARACTER FORMAT "x(10)" VIEW-AS FILL-IN.
REPEAT:
SET test FORMAT "x(20)".
DISPLAY test WITH FRAME aaa.
DISPLAY test FORMAT "X(20)" WITH FRAME bbb.
END.
1750
The code first defines a variable named test, then displays it three times using two different
character formats:
The DEFINE VARIABLE statement specifies a format of x(10). This means that
subsequent screen I/O statements that do not specify a format will allow I/O of up to ten
characters.
The SET statement specifies a format of x(20), allowing the user to supply up to 20
characters.
The first DISPLAY statement does not specify a format, so Progress uses the FORMAT
specified in the DEFINE VARIABLE statement. This means that if the previous SET
statement inputs more than 10 characters, this DISPLAY statement displays only the first
10.
The second DISPLAY statement specifies a format of x(20), allowing the display of all
the characters input by the SET statement.
For example, if the user supplies 15 characters when the SET statement executes, the first
DISPLAY statement makes it appear as if only 10 of those are stored, but the second DISPLAY
statement shows that Progress has stored all 15 characters.
From the preceding example, we can see that a format does not affect a value already in a
variable or database field; a format can only constrain the type of data the user enters into a field.
Once in the field, the data can be displayed in any format, regardless of the original format.
Representing Data
1751
If neither the Progress procedure nor the database specifies a format, Progress uses a default
format based on the data type of the variable or field. Table 171 shows these default formats.
The following sections explain the syntax to use when specifying a format for each of these data
types.
17.10.2 Character Formats
Table 172 shows some examples of how Progress displays a character value using different
formats. Following the table is a description of the syntax.
Table 171: Default Display Formats
Data Type Data Format
Example
Stored Value Displayed Value
CHARACTER x(8) Now is the time Now is t
DATE 99/99/99 3/10/199 03/10/93
DECIMAL >>,>>9.99 12345 12,345.00
INTEGER >,>>>,>>9 12345 12,345
LOGICAL yes/no on yes
Table 172: Character Display Format Examples (1 of 2)
Format Value in Field Display
xxxxxxx These are characters These a
x(9) These are characters These are
x(20) These are characters These are characters
xxx These are characters The
AAA9999 abc1234 abc1234
1752
The symbols used to construct character formats have the following definitions. In the
definitions, the word digit means 0 through 9. The word letter means az, AZ, and foreign
alphabetic characters.
X
Represents any character.
N
Represents a digit or a letter. A blank (space) is not allowed.
A
Represents a letter. A blank is not allowed.
!
Represents a letter that is converted to uppercase during input. A blank is not allowed.
9
Represents a digit. A blank is not allowed.
(n)
A number that indicates how many times to repeat the previous format character. For
example, !(5) is the same as !!!!! and represents five characters that are to be converted to
uppercase when entered.
fillchar
You can use any character or characters you want to fill a display. For example, if you
display the value abc with a format of x(3)***, the displayed value is abc***.
NOTE: To use X, N, A, !, or 9 as a fill character, you must precede that character with a
tilde (~). To use a left parenthesis ( ( ) as a fill character after a nonfill character,
! ! ! 9999 abc1234 ABC1234
(999) 9999999 6176635000 (617) 6635000
Table 172: Character Display Format Examples (2 of 2)
Format Value in Field Display
Representing Data
1753
you must precede it with a tilde. If you use these five characters as fill characters
in a format specification in a procedure, then enter two tildes (~~) so that the
Progress Procedure Editor interprets the tilde literally and not as an escape
lead-in for the following character (for example, you specify a format of x999,
where the x is a fill character, as FORMAT ~~x999").
The database does not store fill characters; Progress supplies them when it
formats the field for display. This allows you to display a field with different fill
characters in different contexts.
Progress truncates the trailing blanks (spaces) in character fields. If a character field contains
only one blank, the value is truncated to the null string. You can use the LEFTTRIM,
RIGHTTRIM, or TRIM functions to truncate leading blanks, trailing blanks, or both.
17.10.3 Integer and Decimal Formats
The following is the syntax you can use when specifying the format of an integer or decimal
value.
( )
Parentheses are displayed if the number is negative. If you use one parenthesis (left or
right), you must use the other.
string1
A string made up of any characters except plus (+), minus (), greater than (>), less than
(<), comma (,), digits (09), letter z (z or Z), asterisk (*) or period (.).
SYNTAX
[ ( ] [ string1 ]
[ + | - | ( ]
[ > | , ] ...
[ 9 | Z | * | , ] ...
[ . ]
[ 9 | < | , ] ...
[ + | - | ) | DR | CR | DB ]
[ string2 ]
1754
+
Progress replaces this character with a plus sign (+) if the number is positive and a minus
() sign if the number is negative. You can use only one plus or minus sign or CR, DR, or
DB or one set of parentheses in a numeric data format.

When you use this character to the left of the decimal point, Progress replaces it with a
minus sign if the number is negative and a blank or null if the number is positive. When
you use this character to the right of the decimal point, Progress replaces this character
with a minus sign if the number is negative and a blank if the number is positive.
>
This character is replaced with a digit if that digit is not a leading zero. If the digit is a
leading zero, this character is replaced with a null and any characters to the left are moved
one space to the right if you are using top labels. They are left justified if you are using
side labels. See also <.
,
This character is displayed as a comma unless it is preceded by >, Z, or *. If the comma is
preceded by >, and the > is replaced by a leading zero, the comma is replaced with a null.
If the comma is preceded by Z, and the Z is replaced by a blank, the comma is replaced
with a blank. If the comma is preceded by *, and the * replaces a leading zero, the comma
is replaced by *.
9
Progress replaces this character with a digit, including cases where the digit is a leading
zero.
Z or z
This character is replaced with a digit. If the digit is a leading zero, Z suppresses that digit,
putting a blank in its place.
*
This character is replaced with a digit. If the digit being replaced is a leading zero, that zero
is replaced with an asterisk.
.
This character represents a decimal point and is displayed as a period.
Representing Data
1755
<
Used in conjunction with > to implement floating decimal format. The < symbol (up to
10) must appear to the right of the decimal and be balanced by an equal or greater number
of > symbols left of the decimal. A digit is displayed in a position formatted with < when
the corresponding > is a leading zero (and the stored value has the required precision). See
Table 173.
DR, CR, DB
These characters are displayed if the number is negative. If the number is positive,
Progress displays blanks in place of these characters. Progress does not treat these
characters as sign indicators when you specify string2; Progress considers them part of
string2.
string2
A string made up of any characters except plus (+), minus/hyphen (), greater than (>),
comma (,), any digit (09), letter z (z or Z), or asterisk (*).
When specifying a numeric data format, you must use at least one of the following characters:
9, z, *, or >.
Table 173 shows some examples of how Progress displays numeric values using different
formats.
Table 173: Numeric Display Format Examples (1 of 2)
Format Value Display
9999 123 0123
9,999 1234 1,234
$zzz9 123 $ 123
$ > > >9 123
$123
1
$>, > > 9.99 1234 $1,234.00
$>, > > 9.99 1234 $1,234.00
#zzz9.999 12.34 # 12.340
Tot= > > >9Units 12 Tot=12Units
1756
NOTE: If you use the European Numeric Format (E) startup parameter, Progress interprets
commas as decimal points and decimal points as commas when displaying or
prompting for numeric values. However, you must enter data in procedures and the
Data Dictionary as described above.
$>, >>9.99 12.34
?????????
2
$>,>>9.99 1234567
???????
3
>>,>99.99<<<
4
12,345.6789 12,345.68
>>,>99.99<<< 1,234.5678 1,234.568
>>,>99.99<<< 123.45 123.45
>>,>99.99<<< 12.45678 12.45678
HH:MM:SS
5
123456 12:34:56
HH:MM AM
5
123456 12:34 AM
1
This display value is right justified if it has a column label, left justified is it has a side label.
2
In this example, there is a negative sign in the value 12.34, but the display format of $>,>>9.99 does not
accommodate that sign. The result is a string of question marks.
3
In this example, the value 1234567 is too large to fit in the display format of $>,>>9.99. The result is a string of
question marks.
4
This is a floating-decimal display format. The < symbols must follow the decimal point and be balanced by an
equal or greater number of > symbols.
5
The time format is used with the STRING function. For more information, see the STRING function in the
Progress Language Reference manual.
Table 173: Numeric Display Format Examples (2 of 2)
Representing Data
1757
17.10.4 Logical Formats
A logical format specifies the strings you want to use to represent the values true and false. To
specify a logical format, specify the true string, followed by a forward slash (/), followed by the
false string. For example, to specify the strings on and off for TRUE and FALSE, respectively,
use the following format option.
If input is coming from a file and you have defined a format for a logical field or variable that
is something other than TRUE/FALSE or yes/no, you can still use TRUE/FALSE or yes/no as
input to that logical field or variable.
Table 174 shows some examples of how Progress displays a logical value with different
formats.
NOTE: You cannot use no, n, false, or f to represent true, and you cannot use yes,
y, true, or t to represent false.
NOTE: If you use the MESSAGE statement to display a logical value, Progress always uses
the default format yes/no and disregards any format you may have specified.
FORMAT "on/off"
Table 174: Logical Display Format Examples
Format TRUE FALSE
yes/no yes no
Yes/no Yes no
true/false true false
shipped/waiting shipped waiting
1758
17.10.5 Date Formats
The default format for a date field or variable is99/99/99. Here is the syntax for specifying a
date format.
Progress determines where to put the month, day, and year values based on any Date Format
(d) startup parameter you may have used. That startup parameter lets you specify a date format
for your application. The default format is mm/dd/yy. Table 175 shows some examples of how
Progress displays a date value using different formats. When you want the user to enter a date
in an application, it is best to use the default date display format.
9_/9_/9_ | 9_-9_-9_ | 9_.9_.9_ | 999999 | 99999999
Table 175: Date Display Format Examples
99/99/99 3/10/1990 03/10/90
99/99/9999 3/10/2090 03/10/2090
999999 3/10/1990 031090
999999 3/10/2090
????????
(1)
999999 3/10/1990 031090
999999 03/10/90 031090
99999999 03/10/1990 03101990
1
In this example, the value of 3/10/2090 is too large to fit into the display format. The year part of the display
format is 99", while the value being displayed is 2090, which requires a year format of 9999".
18
Buttons, Images, and Rectangles
In addition to representations of fields and variables, frames can also contain buttons, images,
and rectangles. Buttons can be enabled for input; rectangles and images are display-only.
Because these widgets occur in the widget hierarchy at the same level as field representations,
Progress refers to them as field-level widgets.
182
18.1 Buttons
A button is a field-level widget that can be chosen by the user. Typically, you define a trigger
to execute when the button is chosen. You can specify a text label for the button. You can also
specify an image to be displayed in the button. Optionally, you can specify a second image to
be displayed when the button is pressed down, and a third image to be displayed when the button
is insensitive.
Also, in a graphical interface such as Windows, you can optionally specify ToolTips, a brief text
message string that automatically displays when the mouse pointer pauses over a button widget
for which a ToolTip value is defined. Although ToolTips can be defined for a variety of
field-level widgets, including images and rectangles discussed later in this chapter, they are
most commonly defined for button widgets. For more information on ToolTips and other
Windows interface design options, see Chapter 25, Interface Design.
In a character interface, a button appears as the label enclosed in angle brackets (< >). Any
image you specify for the button is ignored in a character interface.
The user chooses a button by clicking on it with the mouse SELECT button or by positioning
to it with the TAB or ARROWKEYS and pressing either SPACEBAR or ENTER.
The following procedure defines two buttons:
p-but1.p
DEFINE BUTTON count-button LABEL "Show Count".
DEFINE BUTTON quit-button LABEL "Quit".
FORM
count-button quit-button
WITH FRAME button-frame.
FORM
cnt VIEW-AS TEXT LABEL "Customer count"
WITH FRAME cnt-frame SIDE-LABELS.
ON CHOOSE OF count-button DO:
HIDE FRAME cnt-frame.
cnt = 0.
FOR EACH customer:
cnt = cnt + 1.
END.
DISPLAY cnt WITH FRAME cnt-frame.
END.
ENABLE count-button quit-button WITH FRAME button-frame.
WAIT-FOR CHOOSE OF quit-button
OR WINDOW-CLOSE OF CURRENT-WINDOW.
183
The example defines two buttons, puts them in a frame, and defines a trigger to execute when
the first button is chosen. The second button is referenced in the WAITFOR statement. When
you run this code and choose countbutton, the trigger counts the number of customers.
When you choose QUIT, the WAITFOR statement completes terminating the procedure.
At run time, you can use attributes such as AUTOENDKEY, AUTOGO, and LABEL to query
or change the buttons characteristics.
18.1.1 Button Images
In a graphical interface, you can specify one, two, or three images to be displayed in a button.
The primary image for a button is called the up image. It is displayed when the button is in the
up or unpressed state. You can also specify a down image to be displayed when the button is in
the down or pressed state. Progress displays the down image only momentarily when you press
the button. Typically, the down image is similar to the up image but with a different color or
shading. If you specify an up image but not a down image, Progress continues to display the up
image when you press the button. Finally, you can specify an insensitive image to be displayed
in place of the up image when the button is disabled.
NOTE: In a graphical interface the label is ignored and the image is used instead. In a
character interface, the image is ignored and the label is used. Specifying both a label
and an image makes your code portable between graphical and character interfaces.
For a button, you can use any image that is supported for the image widget. See the section
Images later in this chapter.
184
NOFOCUS Option
In addition to the types of images that a button can display, you can specify an attribute to
indicate that a button with an image will not accept focus. The purpose of providing the
NOFOCUS attribute is to simulate in Progress the standard Windows toolbar button behavior;
it is supported on Windows only. Therefore, a button for which the NOFOCUS attribute is
defined will not take focus when the mouse is clicked on it, and it will not accept keyboard input.
Also, Progress will not generate ENTRY or LEAVE events for the button.
The status of the NOFOCUS option of a button is a factor in determining the thickness of a
buttons border when no button size is defined. See the section Specifying Button Size later
in this chapter.
For more information on the NOFOCUS attribute, see the DEFINE BUTTON Statement
reference entry and the NOFOCUS Attribute reference entry in the Progress Language
Reference.
Pre-defined Built-in Button Images
Frequently, you want to use an arrow as an image on a button. Therefore, Progress provides the
following predefined built-in button images:
BTNUPARROW
BTNDOWNARROW
BTNLEFTARROW
BTNRIGHTARROW
185
The p-arrows.p procedure allows you to scroll forward and backward through the customer
records until you choose the QUIT button. The example enables three buttons and uses built-in
images for two of them:
p-arrows.p
DEFINE BUTTON next-but LABEL "Next" IMAGE-UP FILE "BTN-DOWN-ARROW"
SIZE-CHARS 6 BY 1.
DEFINE BUTTON prev-but LABEL "Prev" IMAGE-UP FILE "BTN-UP-ARROW"
SIZE-CHARS 6 BY 1.
DEFINE BUTTON quit-but LABEL "Quit".
DEFINE VARIABLE title-string AS CHARACTER INITIAL "Customer Browser".
FORM
next-but prev-but quit-but
FORM
WITH FRAME name-frame.
ON CHOOSE OF next-but DO:
IF NOT AVAILABLE(customer)
THEN DO:
MESSAGE "This is the last customer."
TITLE title-string.
FIND LAST customer.
END.
DISPLAY customer.cust-num customer.name
END.
ON CHOOSE OF prev-but DO:
IF NOT AVAILABLE(customer) THEN DO:
MESSAGE "This is the first customer."
TITLE title-string.
END.
END.
ENABLE next-but prev-but quit-but WITH FRAME button-frame.
WAIT-FOR CHOOSE OF quit-but OR WINDOW-CLOSE OF CURRENT-WINDOW.
186
When you run this procedure in a graphical environment, arrow images appear on nextbut and
prevbut. In a character environment, the labels NEXT and PREV appear instead. The
SIZECHARS option on nextbut and prevbut ensure that they are the same size as quitbut.
Specifying Button Size
When you assign an image to a button, you can specify two sizes: the size of the button and the
size of the image. To size the image, use the IMAGESIZE, IMAGESIZECHARS, or
IMAGESIZEPIXELS option of the Image phrase. See the section Images later in this
chapter.
To size the button, you can specify the outside dimensions of the button widget using the
sizephrase. If no size is specified, Progress calculates a default size for the button. This
calculation adds the buttons border thickness (that is, the combination of 3D shadows and
highlights, and the focus rectangle) to the up image size defined by the IMAGE | IMAGEUP
imagephrase option. However, the thickness of the border depends on whether the button has
dual images (up and down images) and whether it is a NOFOCUS button. For detailed
information on how button image and the NOFOCUS status of a button determine the buttons
border thickness, see the section on the DEFINE BUTTON statement in the Progress Language
Reference.
You can also change the images for a button at run time by using the LOADIMAGEUP,
LOADIMAGEDOWN, and LOADIMAGEINSENSITIVE methods.
187
The following code example lets you enter the name of an image file. When you enter a name
and press GO, the contents of the image file are loaded as the up image for the button. If you do
not enter the image file extension, Progress will only search for .bmp or .ico files. You must
include the file extension if you wish to use a different type of image file:
p-but2.p
DEFINE BUTTON quit-button LABEL "Quit".
DEFINE VARIABLE image-file AS CHARACTER FORMAT "x(60)" LABEL "Image File".
FORM
image-file SKIP
quit-button SKIP(13)
WITH FRAME choices-frame SIDE-LABELS.

ON GO OF image-file OR RETURN OF image-file
DO:
ASSIGN image-file.
status-ok = quit-button:LOAD-IMAGE-UP(image-file).
IF status-ok = NO
THEN MESSAGE "Cannot load this image." VIEW-AS ALERT-BOX
MESSAGE BUTTONS OK.
STATUS INPUT "Enter another filename or press the button to quit.".
END.
ENABLE image-file quit-button WITH FRAME choices-frame.
STATUS INPUT "Enter filename of image for Quit button.".
WAIT-FOR CHOOSE OF quit-button OR WINDOW-CLOSE OF CURRENT-WINDOW.
188
If you run this example on Windows and load the Progress adeicon\next.bmp file, the
following screen appears:
NOTE: The adeicon\next.bmp file resides in the Progress distribution in the library
gui\adeicon.pl. For more information on unloading files from libraries, see the
preface.
The size of the button changes depending on the size of the image you load. If the image is very
large, the button might not fit in the frame. When this happens, Progress displays a warning
message.
Preserving Original Color Specifications for Button Images
In a graphical interface such as Windows, you can specify colors for the various areas of a
button. To ensure that colors associated with the buttons images (that is, up, down, and
insensitive) are not converted to the system 3D colors, you can use the
NOCONVERT3DCOLORS option. By default, Progress converts shades of grey in an
image to the corresponding system 3D color. Using this option allows you to override the
default behavior to preserve your original color selections for the image on a button.
For detailed information on color conversions for 3D colors, see the DEFINE BUTTON
Statement reference entry in the Progress Language Reference.
189
18.1.2 Default Buttons in Dialog Boxes
In a graphical interface, dialog boxes typically have a default button. The default button receives
RETURN key events whether or not it has focus, thereby allowing the user to execute the buttons
action without having to tab to it or move the mouse to it. However, if the widget that currently
has focus normally takes a RETURN press event, that widget, and not the default button, will
receive the RETURN event. For example, another button in the frame can still receive the
RETURN event.
A default button is recognizable to the user by an extra border. For example, in many editors, a
dialog box appears if the user attempts to close a file without saving it, prompting the user to
either save the file or close the file and lose any changes. When programming this type of
application, the Save button is typically the default button in the dialog.
When defining a button, specify the DEFAULT option to indicate that it can be a default button.
To make it the default button for the frame, specify the button in the frames
DEFAULTBUTTON option.
If you need to change a frames default button at run time, make sure that you specify the
DEFAULT option for each button that potentially may become the default button. Then, at run
time, change the frames DEFAULTBUTTON attribute.
Note that if you define a default button in a frame that contains fill-ins, pressing RETURN does
not move the cursor to the next field even if the SESSION:DATAENTRYRETURN attribute
is true.
18.2 Images
An image widget is a container in which you can display an image from a bitmap file. You
create a static image widget at compile time with the DEFINE IMAGE statement.
The DEFINE IMAGE statement creates an image widget and optionally makes an association
between the widget and an operating system image file. The DEFINE IMAGE statement takes
an Image phrase, which has the following options:
FILE A character expression that specifies the name of the image file to associate with
the image widget.
FROM Two integer values that specify position of the upper-left corner of the image
within the image file. Use X and Y to specify pixel offsets and ROW and COLUMN to
specify character offsets.
IMAGESIZE | IMAGESIZECHARS Two integer values, separated by the
keyword BY, that specify the width and height of the image in character units.
1810
IMAGESIZEPIXELS Two integer values, separated by the keyword BY, that
specify the width and height of the image in pixel units.
STRETCHTOFIT This option/attribute forces the image to expand or contract to
fit within the image widgets boundaries.
RETAINSHAPE This option/attribute is used only when the STRETCHTOFIT
option/attribute is TRUE. It indicates that the image should retain its aspect ratio.
TRANSPARENT This option/attribute indicates that the images background color
should become transparent.
When you use one of the image-size options in conjunction with the FILE options, Progress
simply makes a compile-time association between the image file and the image widget; the
image file does not have to exist at this point.
If you leave out the file extension when referencing an image file from within a procedure,
Progress looks through your PROPATH for files that have the .bmp extension and then for files
that have the .ico extension. You must supply the file extension if you reference an image file
that does not have the the .bmp or .ico extension.
NOTE: Progress supports the display of many image file formats, including JPEG (.jpg) and
Graphics Interchange Format (.gif). See the Progress Language Reference for a
complete list of supported image file formats.
Omit the FILE option if you want to create an image widget that is not associated with an image
file at compile time, but instead want to make the association at run time.
Use the FILE option without one of the image-size options if you do not know the size of the
image and want Progress to determine the size at compile time. If you do this, Progress uses the
entire image. Also note that the image file must exist at compile time or a compiler error will
occur.
The following code fragment uses the DEFINE IMAGE statement to create an image widget.
The FILE option makes an association between the image widget and the pro bitmap file. The
FROM and the IMAGESIZEPIXELS options instruct Progress to read a 64x64 pixel portion
of the file beginning at pixel location 5, 5. The code fragment then displays the image.
DEFINE IMAGE myicon
FILE "images\pro.gif"
FROM X 5 Y 5
IMAGE-SIZE-PIXELS 64 BY 64.
DISPLAY myicon WITH FRAME icon-frame.
1811
To associate an image file with an image widget at run time, use the LOADIMAGE method.
You can do this either to change an existing association or to create an association if you did not
use the FILE option when defining the image widget. The LOADIMAGE method returns a
logical value and has the following parameters:
filename
A character-string expression of a full or relative pathname of a file that contains an image.
x-offset
An integer that specifies the pixel along the x-axis at which to begin reading from the
image file.
y-offset
An integer that specifies the pixel along the y-axis at which to begin reading from the
image file.
width
An integer that specifies the number of pixels along the x-axis to read from the image file.
height
An integer that specifies the number of pixels along the y-axis to read from the image file.
NOTE: When you use the LOADIMAGE method, Progress uses pixels as the unit of
measurement for the x-offset, y-offset, width, and height; you cannot specify
character units.
1812
The following code fragment creates a dynamic image widget and lets you choose an image file
to load into the widget:
p-ldimg.p (1 of 2)
DEFINE VARIABLE filename AS CHARACTER.
DEFINE VARIABLE filter-string AS CHARACTER.
DEFINE VARIABLE got-file AS LOGICAL.
DEFINE VARIABLE myimage AS WIDGET-HANDLE.
DEFINE BUTTON get-image LABEL "Get Image...".
FORM
WITH FRAME img-frame TITLE "IMAGE" WIDTH 40.
FORM
get-image WITH FRAME but-frame.
ON CHOOSE OF get-image
DO:
SYSTEM-DIALOG GET-FILE filename
TITLE "Choose an Image to Display"
FILTERS "Image files" filter-string
MUST-EXIST
UPDATE got-file.

IF got-file
THEN DO:
status-ok = myimage:LOAD-IMAGE(filename).
ASSIGN FRAME img-frame:HEIGHT-CHARS = myimage:HEIGHT-CHARS + 1
FRAME img-frame:WIDTH-CHARS =
MAX(myimage:WIDTH-CHARS + 2, 15).
VIEW FRAME img-frame.
END.
END.
1813
Because images are supported only for Windows, this procedure determines whether you are
running in a character interface. If so, it displays a message and returns. Otherwise, you can
choose the Get Image button and select an image to load.
For example, if you load the admin.bmp image shipped with Progress, the following screen
appears:
NOTE: Each time you load a new image, the procedure adjusts the size of the frame to ensure
the image widget still fits in the frame.
CREATE IMAGE myimage
ASSIGN FRAME = FRAME img-frame:HANDLE.

CASE SESSION:WINDOW-SYSTEM:
WHEN "TTY"
THEN MESSAGE "Images are not supported for this interface.".
OTHERWISE
ASSIGN filter-string = "*.ico, *.bmp".
END CASE.
IF filter-string = ""
THEN RETURN.

ENABLE get-image WITH FRAME but-frame.
p-ldimg.p (2 of 2)
1814
Converting Original Color Specifications for Images to System 3-D Colors
The CONVERT-3D-COLORS option enables colors that are associated with an image to be
converted to system 3-D colors when the image is loaded. The color conversion process is based
on mapping white, grey, and black colors to their original red-green-blue color values.
Subsequently, these original color values are converted to the new corresponding system colors.
During a session, if Windows notifies Progress that the system colors are changed, all images
that have the CONVERT-3D-COLORS option are reloaded and converted to the new system
colors.
For detailed information on color conversion for 3D colors, see the DEFINE IMAGE
Statement reference entry in the Progress Language Reference.
Transparency
If you set the TRANSPARENT attribute of an image to TRUE, portions of one image can show
through another image. The background color of an image which is TRANSPARENT becomes
transparent, allowing any image beneath it to show through. This feature does not apply to icon
images since they can be drawn with transparent backgrounds.
The TRANSPARENT attribute overrides the CONVERT3DCOLORS attribute. If both
TRANSPARENT and CONVERT3DCOLORS are set to TRUE, the latter will be ignored.
Specifying Tooltip Information for Images
On Windows, you can optionally specify ToolTips, a brief text message string that
automatically displays when the mouse pointer pauses over a widget for which a ToolTip value
is defined. Although ToolTips can be set up for a variety of field-level widgets, including
buttons, images and rectangles discussed in this chapter, they are most commonly defined for
button widgets. For more information on ToolTips and other Windows interface design options,
see Chapter 25, Interface Design.
1815
18.3 Rectangles
Rectangles serve as decoration and can be displayed in a frame or in a frame background.
Rectangles are display-only, and you cannot tab to a rectangle. Rectangles can receive user
input only if they are movable or resizable. See Chapter 24, Direct Manipulation, for more
information on moving and resizing widgets. Also, as previously mentioned, you can define
ToolTip values for rectangles.
In a rectangle, the foreground color (FGCOLOR) is used for the edge and the background color
(BGCOLOR) is used to fill the interior. In a character interface, the display color (DCOLOR)
is used to fill the interior. The default values for unspecified colors are the owning frames
foreground and background colors. You can use the EDGEPIXELS or EDGECHARS
attributes to set the thickness of the rectangles edge. The default edge is 1 pixel in graphical
interfaces and 1 character in character interfaces. Use the NOFILL option to create a hollow,
transparent rectangle.
NOTE: The minimum size for a rectangle is character mode is 1 character high and 1
character wide. If you specify the size in pixels, Progress rounds down to a lower
character. If the result is a dimension of less than 1 character, Progress does not
display the rectangle.
If you specify an edge width of 0 and you do not specify a background color, you will not see
the rectangle because it inherits the background color from its frame. To see the rectangle, you
must either set the background color or specify an edge width that is greater than 0.
Table 181 shows the various effects that you can achieve by using different combinations of
the FGCOLOR, BGCOLOR, and NOFILL options in a graphical interface. The table assumes
that the applications color table contains red in the first location and blue in the second.
Table 181: Using NOFILL and Color with Rectangles (1 of 2)
Options Resulting Rectangle
No options A rectangle filled with the frames background color
and bordered in the frames foreground color.
FGCOLOR 0 A rectangle with a red border filled with the frames
background color.
NOFILL A hollow rectangle bordered with the frames
foreground color.
FGCOLOR 0 NOFILL A hollow rectangle with a red border.
1816
For example, the following code fragment defines a hollow rectangle with a border that is either
one pixel (in graphical interfaces) or one character (in character interfaces) thick. The border is
drawn in the frames foreground color. If you want a solid fill rectangle without a border,
specify 0 for the EDGEPIXELS or EDGECHARS attribute.
NOTE: In a character interface, a rectangles proportions are determined by the proportions
of the character set. For example, if a character sets height is two times the width,
specify a SIZE option of 2 BY 1 if you want a square.
Some character interfaces support line graphics characters. If you want Progress to use these
characters when drawing a rectangle, specify the GRAPHICEDGE option in the DEFINE
RECTANGLE statement or set the GRAPHICEDGE attribute to TRUE. The
GRAPHICEDGE attribute is ignored for a minimum-sized character rectangle (1 character by
1 character). In a graphical interface, Progress ignores the GRAPHICEDGE option and
attribute setting.
At run time, an application can query or set the rectangles fill or edge width using the FILLED
and EDGEPIXELS or EDGECHARS attributes.
Usually, you should put any rectangles into the frame background. If you put a rectangle in the
foreground in character mode, you should display the rectangle before displaying anything else
in the frame. This prevents the rectangle from overlaying other widgets.
FGCOLOR 0 BGCOLOR 1 A rectangle with a red border filled with blue.
BGCOLOR 1 A rectangle filled with blue and bordered with the
frames foreground color.
DEFINE RECTANGLE poly
SIZE-CHARS 30 BY 3
NO-FILL
DISPLAY poly.
Table 181: Using NOFILL and Color with Rectangles (2 of 2)
Options Resulting Rectangle
19
Frames
This chapter describes frames, and how Progress allocates and manages frames. It also describes
the major 4GL components used to control frames. For more information on frame design
options, see Chapter 25, Interface Design.
This chapter includes the following topics:
What is a frame?
Why Progress uses frames
Static and dynamic frames
Frame allocation
Types of frames
Frame scope
Triggers and frames
Frame flashing
Frame families
Frame services
192
Using shared frames
Field-group widgets
Validation of user input and records
Frames
193
19.1 What Is a Frame?
A frame is a rectangular display area within a window that Progress uses to display field-level
widgets and other frames. To see a frame, run this procedure:
Figure 191 shows the output of this procedure.
Figure 191: Frame
p-frm1.p
FOR EACH customer:
DISPLAY name address credit-limit.
END.
Frame
194
Progress allocates frames automatically to hold field-level widgets referenced by screen display
and input statements. Except for the PUT statement, all statements that display data or require
user interaction place widgets in frames. Two or more statements can use the same frame.
You can also define and reference frames explicitly and contain frames within other frames. For
more information on containing frames within frames, see the Frame Families section.
19.2 Why Progress Uses Frames
Progress uses frames to ease the task of laying out your data, so you do not have to individually
position every field-level widget that you want to display. Progress automatically lays out
frames according to predetermined rules, or defaults. One default is to display a label for each
field in the frame. Another is to place a solid box around every frame. You must become
familiar with these defaults to use frames effectively. Once you know the defaults, you can
override them to change the appearance and placement of your data.
19.3 Static and Dynamic Frames
Progress supports static frames and dynamic frames. Static frames are allocated at compile time.
Dynamic frames are created at run time.
Progress can produce frames in three ways:
By allocating a default static frame
By allocating an explicitly defined static frame
By creating a dynamic frame
The sections in this chapter focus on static frames. For more information on dynamic frames,
see Chapter 20, Using Dynamic Widgets.
Frames
195
19.4 Frame Allocation
This section describes how Progress allocates static frames and how you can control their
allocation.
19.4.1 How Progress Allocates Frames
Progress automatically allocates frames to a selected group of blocks. In general, the following
blocks receive default frames:
REPEAT blocks
FOR EACH blocks
DO WITH FRAME blocks
Procedure blocks
However, Progress does not always allocate a frame to these blocks. For example, if a block
displays no widgets, Progress doesnt allocate a frame. Progress recognizes when frames are
needed and when they are not.
196
The Progress Compiler, in a top-to-bottom pass of a procedure, determines which frames to
allocate. In Figure 192, there are three blocks. Block A and the procedure block both contain
statements that display data, so Progress allocates a frame for each of those blocks. Block B
does not display data, so Progress does not allocate a frame to it.
p-frm2.p
Figure 192: Frame Allocation
The allocated frames are all unnamed frames. An unnamed frame is a frame that Progress
allocates by default, but that you do not explicitly name.
DEFINE VARIABLE count AS INTEGER.
DISPLAY "Daily Report".
FOR EACH customer:
count = 0
DISPLAY name.
DISPLAY cust-num.
count = count + 1.
END.
DISPLAY count LABEL "Total Orders".
END.
Procedure
Block
Block A
Block B
Procedure Block:
Block A:
Unnamed Frame
Unnamed Frame
Block B:
No Frame Allocated
Frames
197
19.4.2 Default Frames
Progress allocates default frames when you display field-level widgets without naming a frame.
For example, in Figure 192, this statement appears in the procedure block.
This statement displays a text string, but does not name a frame. Progress therefore allocates a
default unnamed frame, using it to display the text string Daily Report. You can replace the
above statement with the statement shown below.
This statement explicitly names a frame (frame a), causing Progress to allocate that frame
instead of a default frame. A default frame is not necessary, because no other statements in the
procedure block display data (frame a displays the text string Daily Report). Progress
allocates a default frame only for field-level widgets that are not explicitly placed in another
frame.
19.4.3 Specifying Default Frames
Whenever you name a frame within a blocks header statement, the frame that you name
becomes the default frame for that block.
For example, the header statement in the following FOR EACH block names a frame, so
Progress allocates that frame instead of an unnamed frame. Frame a is the default frame for the
block. Because the DISPLAY statement does not explicitly name another frame, it uses frame a:
The header statement in the following FOR EACH block doesnt name a frame, so Progress
allocates a default unnamed frame:
DISPLAY "Daily Report".
DISPLAY "Daily Report" WITH FRAME a.
p-frm3.p
FOR EACH customer WITH FRAME a:
END.
p-frm4.p
FOR EACH customer:
END.
198
In these two examples, naming the frame does not affect the appearance of the output, which is
the same for both procedures. However, in many cases, naming the default frame can affect the
appearance of the output. Whether it does or not depends on the scope of the frame, the type of
frame, where you reference the frame, and how you reference it. These issues are described in
detail later in this chapter. However, the following two procedures illustrate how naming the
default frame can affect the appearance of your output.
These procedures are identical, except that the first uses a FORM statement and the second uses
a DEFINE FRAME statement to describe the frame. For more information on the FORM and
DEFINE FRAME statements, see Chapter 25, Interface Design.
When you run the p-form.p procedure, all of the customer records flash on screen. For more
information, see the Frame Flashing section. When you run the p-deffrm.p procedure, 15
records are displayed at a time, and there is no flashing.
Flashing occurs in the first procedure because of how the frame is scoped. The scope of a frame
is the range or extent of the frames availability within a procedure. For more information on
frame scope, see the Frame Scope section.
The FORM statement scopes the frame to the procedure block; the DEFINE FRAME statement
does not scope the frame. In both procedures, the frame is the default frame for the FOR EACH
block. However, Progress provides different frames services, depending on whether the frame
is scoped to an iterating block. If it is scoped to an iterating block, Progress advances and clears
the frame (avoiding any flashing). If it is not scoped to an iterating block, Progress does not
advance for each iteration.
p-form.p
FORM
WITH FRAME a 15 DOWN USE-TEXT.
END.
p-deffrm.p
DEFINE FRAME a
WITH 15 DOWN USE-TEXT.
END.
Frames
199
19.4.4 Controlling Frame Allocation
By explicitly naming a frame, you can direct Progress to allocate a new frame, or you can direct
Progress to use a named frame as the default frame for a block. The example procedure in Figure
193 performs these actions.
p-frm5.p
Figure 193: Controlling Frame Allocation
In Figure 193, Progress allocates four frames.
DISPLAY "Daily Report" WITH FRAME p-frame CENTERED
FOR EACH customer:
DISPLAY phone WITH FRAME aaa.
FOR EACH order OF customer WITH FRAME bbb:
DISPLAY order-num order-date.
DISPLAY item-name WITH FRAME bbb.
DOWN WITH FRAME bbb.
END.
END.
END.
Procedure Block:
Block A:
Frame p-frame
Unnamed Frame
Frame aaa
No Frame Allocated.
Frame bbb is already
allocated.
Block B:
Block C:
Frame bbb
Procedure
Block
Block A
Block B
Block C
1910
19.4.5 The Procedure Block
The DISPLAY statement in the procedure block creates one frame (pframe).
Progress uses this frame to display the text string Daily Report. No other statements in the
procedure block display data, so Progress does not allocate a default unnamed frame.
If you add the following statement to this block, Progress allocates a default unnamed frame
(because the statement does not explicitly name a frame).
19.4.6 Block A
Progress allocates two frames (an unnamed frame and frame aaa) to Block A. The first
DISPLAY statement doesnt explicitly name a frame, so Progress creates a default unnamed
frame. The second DISPLAY statement explicitly names frame aaa.
19.4.7 Block B
The header statement in Block B names a frame (frame bbb), so Progress does not allocate a
default unnamed frame. Frame bbb is the default frame for the block.
19.4.8 Block C
No frame is allocated to Block C. The lone DISPLAY statement explicitly names frame bbb, so
Progress uses that frame to display the item description.
DISPLAY "Daily Report" WITH FRAME p-frame CENTERED.
DISPLAY "This statement uses a default frame".
DISPLAY phone WITH FRAME aaa.
FOR EACH order OF customer WITH FRAME bbb.
DISPLAY item-name WITH FRAME bbb.
Frames
1911
19.5 Types of Frames
In addition to controlling which frames Progress allocates, you can also control the type of
frames that Progress allocates. There are two types of frame: down and one-down. A down
frame displays multiple iterations of data. A one-down frame displays single iterations of data.
Static frames can be down or one-down. Dynamic frames can be one-down only.
p-frm6.p
Figure 194: Types of Frames
Down Frame
DISPLAY "Daily Report"

FOR EACH customer:
DISPLAY name.
DISPLAY cust-num.
DISPLAY order-date.
DISPLAY item-name.
END.
END.
END.
Procedure Block:
Block A:
One-down Frame
One-down Frame
One-down Frame
Block C:
Procedure
Block
Block A
Block B
Block C
Block B:
1912
Progress allocates four frames to the procedure in Figure 194. Three of the frames are
one-down; the remaining frame is a down frame. The Progress compiler examines each block
in the procedure and tests the following conditions to determine what type of frame to allocate
to each block.
1. Is the block an iterating block?
2. Is the default frame for the block scoped to the block?
3. Does the block contain a nested block that has a frame scoped to it?
To determine the types of frames that the Progress Compiler allocates, see Table 191.
Table 191: Determining Frame Type
Is the Block
an Iterating
Block?
Is the Default
Frame Scoped
to the
Block?
Does the Block
Contain a Nested
Block with a
Frame Scoped to
It?
Frame
Type
Yes Yes No Down
All other combinations One-down
Frames
1913
The following examples show how Progress allocates different kinds of frames to different
kinds of blocks.
In the procedure p-frm7.p, Progress allocates a down frame to the outer FOR EACH block. The
inner FOR EACH block does not display data, so Progress does not allocate a frame to it, and
therefore no frame is scoped to it:
In the procedure p-frm8.p, Progress allocates a one-down frame to the outer FOR EACH block,
a one-down frame to inner FOR EACH block, and a one-down frame to the DO WITH FRAME
block. The DO WITH FRAME block has a frame scoped to it, so the inner FOR EACH block
does not receive a down frame:
p-frm7.p
DEFINE VARIABLE cnt AS INTEGER INITIAL 0.
FOR EACH customer:
cnt = cnt + 1.
END.
DISPLAY cnt LABEL "Total Orders".
cnt = 0.
END.
p-frm8.p
FOR EACH customer:
FOR EACH order of customer:
DISPLAY order-num.
DO WITH FRAME a:
FIND FIRST order-line OF order.
DISPLAY item-num.
END.
END.
END.
1914
In the procedure p-frm9.p, Progress allocates two one-down frames to the procedure block (an
unnamed frame and frame aaa). Although frame aaa is the default frame for the REPEAT block,
it is not scoped to the REPEAT block. Therefore, it is a one-down frame:
p-frm9.p
DISPLAY "Customer Report".
FORM customer.cust-num customer.name WITH FRAME aaa.
REPEAT WITH FRAME aaa:
FIND NEXT customer.
UPDATE cust-num name.
END.
Frames
1915
19.6 Frame Scope
The scope of a static frame is the range or extent of the frames availability within a procedure,
which is equivalent to the area within a particular block. (This includes any and all nested blocks
within the block.) For example, if a frame is scoped to the procedure block, it means that the
frame is available throughout the entire procedure. You can display data in the frame from
anywhere within the procedure. Figure 195 shows another example of frame scope.
Figure 195: Frame Scope
The scope of a static frame is the first REPEAT, FOR EACH, procedure, or DO WITH FRAME
block that references the frame. In this context, HIDE and VIEW statements do not count as
frame references.
The DEFINE FRAME statement defines a frame but does not scope it. The scope of the frame
is the next REPEAT, FOR EACH, procedure, or DO WITH FRAME block that references the
frame.
NOTE: Dynamic frames are globally scoped. For more information, see Chapter 20, Using
Dynamic Widgets.
FOR EACH customer:
Display order-num order-date.
END.
END.
Frame 1 Frame 2
Frame 1 is an unnamed
frame. It is the default
frame scoped to the outer
FOR EACH block.
If you explicitly name a
default frame for this
block, you can access the
frame from the inner FOR
EACH block.
Frame 2 is an unnamed
frame. It is the default
frame scoped to the inner
FOR EACH block.
You cannot access this
frame from the outer FOR
EACH block.
1916
The following examples show different ways that Progress scopes frames.
In the procedure p-frm10.p, the scope of frame aaa is the procedure block because that is the
first block that references frame aaa. The scope of frame bbb is the REPEAT block. The
DISPLAY statement in the REPEAT block uses frame bbb because it is the default frame for
the REPEAT block. (The DISPLAY statement could override this by explicitly naming a frame:
DISPLAY WITH FRAME.)
In the procedure p-frm11.p, the scope of frame bbb is the procedure block because that is where
it is first referenced. The FORM statement counts as a use of a frame. The default frame of the
REPEAT block is bbb, since bbb is specified in the blocks header statement. However, frame
bbb is not scoped to the REPEAT block:
Progress can scope a frame to only one block. You cannot reference or use a frame outside its
scope except in HIDE and VIEW statements.
p-frm10.p
REPEAT WITH FRAME bbb.
END.
p-frm11.p
FORM WITH FRAME bbb.
END.
Frames
1917
In the procedure p-frm12.p, the scope of frame a is the REPEAT block, since that is the first
block that references frame a. If you try to run this procedure, Progress displays as error saying
that you cannot reference a frame outside its scope. The FOR EACH block names frame a, but
the FOR EACH block is outside the scope of frame a. You could explicitly scope frame a to the
procedure and use it in both the REPEAT and FOR EACH blocks. To do this, you could add a
DO WITH FRAME block that encompasses both the REPEAT and FOR EACH blocks:
19.7 Triggers and Frames
User-interface and session triggers can reference frames in the procedure that defines them and
can use these frames to display widgets or character strings. In addition, triggers can use default
frames to display data (if no frames are named within the trigger), and can name frames that do
not exist within the defining procedure.
If a trigger displays data without specifying a frame, the trigger receives a default frame. Each
time the trigger executes, Progress creates a new default frame. The trigger does not reuse a
frame created during a previous execution.
If the trigger names a frame not named in the defining procedure, the new frame is created when
the trigger executes.
Whenever a trigger creates a frame, the frame is local to the trigger and its scope ends when the
trigger finishes executing. Each time the trigger executes, a new frame is created.
p-frm12.p
/* This procedure will not run */
REPEAT WITH FRAME a:
DISPLAY name.
END.
DISPLAY name.
END.
1918
19.8 Frame Flashing
A phenomenon called frame flashing occurs when an iterating block displays to a frame that is
scoped to an enclosing block. To see frame flashing, run this procedure:
Iterating blocks repeatedly display data to the screen. If the data is displayed to a down frame
that iterates and advances for each pass through the block, no frame flashing occurs. However,
since custframe is not scoped to the iterating block, Progress does not provide the appropriate
frame services. (For more information on frame services, see the Frame Services section.)
Therefore, each iteration of the block overwrites the data from the previous iteration, which
produces flashing.
You must take two steps to correct frame flashing. First, make the flashing frame a down frame
with the DOWN frame phrase (for more information on frame phrases, see the Frame phrase
reference entry in the Progress Language Reference). Second, use a DOWN statement to
advance the cursor to the next iteration of the frame. When you apply these steps to the previous
procedure, frame flashing no longer occurs:
p-frm13.p
/* This procedure produces flashing */
FORM customer.cust-num customer.name
customer.credit-limit
FOR EACH customer:
DISPLAY cust-num name credit-limit
END.
p-frm14.p
FORM customer.cust-num customer.name
customer.credit-limit
WITH FRAME cust-frame DOWN.
FOR EACH customer:
DISPLAY cust-num name credit-limit
END.
Frames
1919
19.9 Frame Families
By default, when Progress allocates a frame or when you display and accept input from an
explicitly defined frame, Progress parents that frame to either the current window or the window
you specify.
NOTE: In character interfaces Progress provides only the current window. You cannot create
additional windows.
For example, the following procedure parents frame custframe to the current window with the
first DISPLAY statement. It then parents custframe to the window specified by hwin with the
second DISPLAY statement:
Note that a frame can be parented to only one window at a time. So, when the second DISPLAY
statement parents custframe to the new window, it is removed from the current window. For
more information on window management, see Chapter 21, Windows.
Frame Relationships
You can also parent a frame (child frame) to another frame (parent frame). This causes Progress
to view the child frame within the display area of the parent frame. Frames that are parented by
a frame, which in turn is parented by a window, form a frame family. The frame parented by the
window is the root frame of the frame family. Frames parented by any child frame, in turn, form
a child frame family. All frames in a frame family are viewed within the display area of the root
frame, and all frames of a child frame family are displayed within the display area of the
parenting child frame. As with root frames and their parent windows, a child frame can have
only one parent frame at a time.
p-frmwin.p
DEFINE VARIABLE hwin AS WIDGET-HANDLE.
CREATE WINDOW hwin
ASSIGN TITLE = "New Window".
CURRENT-WINDOW:TITLE = "Current Window".
DISPLAY name balance WITH FRAME cust-frame.
DISPLAY name balance WITH FRAME cust-frame IN WINDOW hwin.
PAUSE.
1920
Figure 196 and Figure 197 show a typical frame family with three child frames. The root
frame is the Customer Data frame, which is contained by the Update window.
Figure 196: Frame Family (Windows Graphical Interface)
Frames
1921
Figure 197: Frame Family (Character Interface)
The three child frames include the Contact Information, Account Information, and Find and
Update Customer frames. Note how these three frames are nested between the top and bottom
fields of the parent Customer Data frame.
Frame Family Behavior
Child frames behave like field-level widgets in a frame, as the remaining sections in this chapter
explain. In fact, a frame is parented to a frame in exactly the same way that a field-level widget
is parented to a frame, using a field group. For more information on field groups, see the
Field-group Widgets section.
1922
19.9.1 Defining a Frame Family
The first step in defining a frame family is to define a child frame of a root frame. To define a
child frame of any frame, you set the child frames FRAME attribute to the widget handle of the
parent frame, as shown in the following procedure (p-fof1.p):
By default, Progress positions a child frame at row 1, column 1 (the upperleft corner) of the
parent frames display area. Thus, when you specify position options for a child frame, they are
relative to the parent frames display area, not the windows. In this way, you can define and
position child frames of child frames (descendant frames) to any practical depth.
19.9.2 Using Frame Families
Child frames help to organize the display area of the parent frame. They can contain their own
field-level widgets, and like any frame parented to a window, they can be referenced in frame
I/O statements. Child frames can be viewed and hidden like field-level widgets and also
participate in the tab order of the parent frame.
You can choose a default button or Cancel button from a child frame. If a child frame does not
have the chosen button, invoking that button in the child frame will cause the first default or
Cancel button found in the frame family (and in no special order) to be chosen.
You can also parent child frames to a dialog box, which can serve as a root frame for a frame
family. However, child frames cannot be viewed as dialog boxes, themselves. For more
information on dialog boxes, see Chapter 25, Interface Design.
p-fof1.p
DEFINE FRAME fparent WITH SIZE 60 by 10 TITLE "Parent".
DEFINE FRAME fchild WITH SIZE 40 by 5 TITLE "Child".
FRAME fchild:FRAME = FRAME fparent:HANDLE.
DISPLAY WITH FRAME fparent.
ENABLE ALL WITH FRAME fparent.
ENABLE ALL WITH FRAME fchild.
Frames
1923
Child frames have some additional restrictions:
You cannot use them as down frames; they can only be 1 down.
They must fit at least partially within the virtual display area of their parent frame.
They do not inherit the attributes of their parent frame.
If you set SESSION:DATAENTRYRETURN to TRUE, the last fill-in of a child frame
can trigger a GO event for the frame if it is the last fill-in field in the frame family tab order.
For more information, see the section on fillin fields in Chapter 17, Representing Data.
You must display, enable, and disable the field-level widgets of child frames explicitly.
Doing so for a parent frame has no effect on the fields displayed in its child frames.
The following procedure (p-fof2.p) uses a frame family to organize a window for updating
customer records. It displays the Update window shown previously in Figure 196 and Figure
197.
1924
p-fof2.p (1 of 3)
DEFINE BUTTON bprev LABEL "<".
DEFINE BUTTON bnext LABEL ">".
DEFINE BUTTON bupdate LABEL "Update".
DEFINE BUTTON bcommit LABEL "Commit".
DEFINE FRAME cust-fr SKIP(.5)
SPACE(8) customer.name customer.cust-num customer.sales-rep
customer.comments AT COLUMN 6 ROW 13.5
WITH SIDE-LABELS TITLE "Customer Data" KEEP-TAB-ORDER
&IF "{&WINDOW-SYSTEM}" <> "TTY" &THEN
SIZE 80 BY 15.
&ELSE
SIZE 80 BY 16.
&ENDIF
DEFINE FRAME cont-fr SKIP(.5)
customer.address COLON 17 SKIP
customer.address2 COLON 17 SKIP
customer.city COLON 17 SKIP
customer.state COLON 17 SKIP
customer.postal-code COLON 17 SKIP
customer.country COLON 17 SKIP
customer.contact COLON 17 SKIP
customer.phone COLON 17
WITH SIDE-LABELS TITLE "Contact Informaion"
SIZE 40 BY 10 AT COLUMN 1 ROW 3.
DEFINE FRAME ctrl-fr SKIP(.12)
SPACE(.5) bprev bnext bupdate bcommit
WITH TITLE "Find and Update Customer"
&IF "{&WINDOW-SYSTEM}" <> "TTY" &THEN
SIZE 27.5 BY 2 AT COLUMN 46 ROW 10.5.
&ELSE
&ENDIF
DEFINE FRAME acct-fr SKIP(.5)
customer.balance COLON 15 SKIP
customer.credit-limit COLON 15 SKIP
customer.discount COLON 15 SKIP
customer.terms COLON 15
WITH SIDE-LABELS TITLE "Account Information"
SIZE 39.8 BY 6 AT COLUMN 41 ROW 3.
ON CHOOSE OF bnext IN FRAME ctrl-fr DO:
GET NEXT custq.
IF NOT AVAILABLE customer THEN GET FIRST custq.
RUN display-proc IN THIS-PROCEDURE.
END.
Frames
1925
ON CHOOSE OF bupdate IN FRAME ctrl-fr DO:
DISABLE ALL WITH FRAME ctrl-fr.
ENABLE bcommit WITH FRAME ctrl-fr.
ENABLE ALL EXCEPT customer.cust-num WITH FRAME cust-fr.
ENABLE ALL WITH FRAME cont-fr.
ENABLE ALL EXCEPT customer.balance WITH FRAME acct-fr.
END.
ON CHOOSE OF bcommit IN FRAME ctrl-fr DO:
DISABLE ALL WITH FRAME cust-fr.
DISABLE ALL WITH FRAME cont-fr.
DISABLE ALL WITH FRAME acct-fr.
ENABLE ALL WITH FRAME ctrl-fr.
DISABLE bcommit WITH FRAME ctrl-fr.
GET CURRENT custq EXCLUSIVE-LOCK.
IF NOT CURRENT-CHANGED(customer) THEN DO:
ASSIGN customer EXCEPT customer.cust-num customer.balance.
RELEASE customer.
END.
ELSE DO:
GET CURRENT custq NO-LOCK.
DO cnt = 1 TO 12: BELL. END.
MESSAGE "Customer" customer.name SKIP
"was changed by another user." SKIP
"Please try again..." VIEW-AS ALERT-BOX.
END.
END.
FRAME cont-fr:FRAME = FRAME cust-fr:HANDLE.
FRAME acct-fr:FRAME = FRAME cust-fr:HANDLE.
FRAME ctrl-fr:FRAME = FRAME cust-fr:HANDLE.
IF NOT SESSION:WINDOW-SYSTEM = "TTY" THEN CURRENT-WINDOW:TITLE = "Update
...".
OPEN QUERY custq PRESELECT EACH customer NO-LOCK BY customer.name.
GET FIRST custq.
ENABLE ALL WITH FRAME ctrl-fr.
DISABLE bcommit WITH FRAME ctrl-fr.
WAIT-FOR WINDOW-CLOSE OF FRAME cust-fr.
p-fof2.p (2 of 3)
1926
Note how each frame is managed individually for input and output. Displaying frame custfr
displays its child frames, but not their field values. Likewise, enabling the fields of custfr for
input has no effect on the fields in contfr, acctfr, or ctrlfr. Each of these child frames must
have their field-level widgets enabled and disabled individually.
When enabled, you can tab among all the field-level widgets in the custfr frame family. For
more information on frame family layout and tabbing behavior, see the remaining sections of
this chapter and Chapter 25, Interface Design.
19.10 Frame Services
Progress provides the following services for each frame in a block:
Viewing and hiding
Advancing and clearing
Retaining previously entered data during RETRY of a block
Creating field-group widgets
PROCEDURE display-proc:
DISPLAY
customer.name customer.cust-num customer.sales-rep
customer.comments WITH FRAME cust-fr.
DISPLAY
customer.address customer.address2 customer.city customer.state
customer.postal-code customer.country customer.contact
customer.phone WITH FRAME cont-fr.
DISPLAY
customer.balance customer.credit-limit
customer.discount customer.terms WITH FRAME acct-fr.
END.
p-fof2.p (3 of 3)
Frames
1927
19.10.1 Viewing and Hiding Frames
Progress brings a frame into view when you display data in that frame. You can also use the
VIEW statement (or you can set the frames VISIBLE attribute to TRUE) to explicitly bring a
frame into view. You can use the HIDE statement to explicitly hide a frame (or you can set the
frames VISIBLE attribute to FALSE).
NOTE: If a parent or ancestor window of a frame has its HIDDEN attribute set to TRUE, you
can set the frames attributes (directly or indirectly with VIEW and data display
statements) to display the frame, but Progress does not display the frame until all
ancestor windows have their HIDDEN attributes set to FALSE.
When displaying frames within a window, Progress tiles the frames, starting at the top of the
window and proceeding to the bottom until the window is full. By default, every frame begins
at column 1. If there are more frames than fit in the window, Progress hides (erases) the frames
closest to the bottom of the window until enough space is cleared to display the next frame. If
ready to hide a frame, Progress pauses, by default, and displays the message Press space bar to
continue.
Within a window, you can display one frame over another using the OVERLAY option, and you
can make a frame fit in a display area that is smaller than the frame itself, using the SIZE option
of the Frame phrase. For more information on the SIZE option, see Chapter 25, Interface
Design.
Bringing Frames into View
You can bring a frame into view by displaying data in that frame, using the VIEW statement, or
setting the frames VISIBLE attribute to true. In the following procedure, the DISPLAY
statement brings the frame into view:
p-form1.p
FORM customer.name contact AT 40 SKIP
customer.address credit-limit AT 40 SKIP
customer.city customer.state NO-LABEL
customer.postal-code NO-LABEL balance AT 40 SKIP(1)
phone
HEADER "Customer Maintenance" AT 25 SKIP(1)
WITH SIDE-LABELS NO-UNDERLINE FRAME a.
DISPLAY curr-bal.
UPDATE name address city state postal-code phone contact credit-limit.
END.
1928
The FORM statement describes frame a. To bring the frame into view before the DISPLAY
statement, you can use the VIEW statement. In the next example, the VIEW statement brings
frame b into view.
In the next example, Progress automatically removes frames from the screen by hiding them:
The output of this procedure is as follows:
p-form2.p
DEFINE FRAME b WITH ROW 7 CENTERED SIDE-LABELS
TITLE "Customer Info".
VIEW FRAME b.
REPEAT:
PROMPT-FOR customer.cust-num WITH FRAME a ROW 1.
FIND customer USING cust-num NO-LOCK.
DISPLAY customer EXCEPT comments WITH FRAME b.
END.
p-hide.p
FOR EACH customer:
DISPLAY name WITH FRAME f1 DOWN.
DISPLAY credit-limit WITH FRAME f2.
FOR EACH order OF customer WITH FRAME f3:
DISPLAY order-num.
END.
END.
Frames
1929
At this point, the procedure has displayed the customer name. But there is no more vertical
space on the screen in which to display the maxcredit and order numbers. Press SPACEBAR.
You can see that Progress automatically hides frame f1 to make room for frames f2 and f3.
When Progress runs out of space, it hides frames starting from the bottom of the window.
1930
Using Overlay Frames
Progress allows you to create a frame that overlays another frame. To display one frame over
another, set the top frames OVERLAY attribute to true (or use the OVERLAY frame phrase
option). Also, make sure that the bottom frames TOPONLY attribute is set to false. Progress
displays a message before it displays the overlay frame.
For example, you might want to display all the information for a customer, then see that
customers orders one at a time while keeping at least some of the customer information in view.
The following procedure uses an overlay frame to accomplish this:
This procedure produces the following output:
p-ovrlay.p
FOR EACH customer:
DISPLAY customer WITH 2 COLUMNS TITLE "CUSTOMER INFORMATION".
DISPLAY order-num order-date ship-date promise-date carrier
instructions WITH 2 COLUMNS 1 DOWN OVERLAY
TITLE "CUSTOMERS ORDERS" ROW 7 COLUMN 10.
END.
END.
Frames
1931
When you press SPACEBAR, if the customer has orders, you see the customers first order in a
frame that overlays the first frame on your screen, as shown in the following figure:
When you press SPACEBAR, the next customer appears, the order frame clears, and the next
order for the customer appears. Progress automatically refreshes a covered frame when an
overlay frame clears.
The p-ovrlay.p procedure displays the frame with the order information over the frame with
the customer information because the frame phrase for the order frame includes the OVERLAY
option. You can use the ROW and COLUMN options to control where the overlay frame is
placed on the screen. If you do not include the ROW and COLUMN options, the overlay frame
displays with the upper left corner in row 1, column 1 (unless you use some other option to
affect its placement, such as the CENTERED option).
1932
Working with Multiple Overlay Frames
If every frame is an overlay frame and no frame has its TOPONLY attribute set to TRUE, you
can bring any overlay frame to the top by giving focus to one of its field-level widgets. You can
also prevent all overlay frames from changing their current overlay position (Z order) by
setting the windows KEEPFRAMEZORDER attribute to TRUE. No matter how this
attribute is set, you can always change the Z order of an overlay frame using these methods:
MOVETOTOP( ) Moves the frame to the top of the Z order.
MOVETOBOTTOM( ) Moves the frame to the bottom of the Z order.
The default Z order of multiple overlay frames is the order in which they are enabled.
Child frames are actually permanent overlay frames of their parent frame. When you overlay
several child frames, they maintain their collective Z order on top of the parent frame. However,
you can change the relative Z order of the child frames within the parent using these methods.
For more information on the OVERLAY option of the Frame phrase and the methods changing
frame Z order, see the Progress Language Reference.
NOTE: Dialog boxes also appear on top of other frames and may be preferable to overlay
frames. For more information on dialog boxes, see Chapter 25, Interface Design,
and the Progress Language Reference.
Viewing and Hiding Frame Families
When you view and hide a parent frame, all of its child frames and field-level widgets whose
HIDDEN attributes are set to FALSE are viewed and hidden with it. The viewing and hiding of
child frames also works as it does for field-level widgets.
When you use the VIEW statement to view a child frame, Progress views the child frame and
all of its ancestor frames, even if their HIDDEN attributes are set to TRUE. If necessary,
Progress resets their HIDDEN attributes to FALSE. However, if you use the DISPLAY or
ENABLE statement to view a child frame, Progress sets the attributes appropriately to display
the child frame, but only displays it on the screen if none of its ancestor frames have their
HIDDEN attributes set to TRUE. In this case, when all ancestor frames have their HIDDEN
attributes set to FALSE, the previously displayed or enabled child frame is then displayed on
the screen.
When you hide a child frame, like a field-level widget, its HIDDEN attribute is set to TRUE.
Thus, if you later hide and redisplay an ancestor frame, the hidden child frame stays hidden until
you explicitly view or display it.
Frames
1933
When you run the sample procedure p-fof3.p, the following window appears, which lets you
view and hide frame families:
Figure 198: Frame Family Viewing Demo
You can hide and view each frame and fill-in, displaying the HIDDEN and VISIBLE attribute
values in the message area as appropriate.
1934
19.10.2 Advancing and Clearing Frames
When a block iterates, Progress advances any down frames scoped to the block to the next
iteration. Progress also clears the field values in the screen buffer for all one-down frames
scoped to the block. These actions take place only if you displayed or entered data into at least
one of the fields in the frame during the iteration.
When a down frame is full, Progress clears the entire frame before displaying more data. You
can use the RETAIN frame phrase option to specify a number of iterations of data that you do
not want Progress to clear.
19.10.3 Retaining Data During Retry of a Block
When the procedure retries a block, either because of an implicit or explicit UNDO or RETRY,
Progress does not clear the frame scoped to that block. That way, the data are still available
when the user enters new data or changes the data entered on the first try.
19.10.4 Creating Field-group Widgets
For each frame, Progress automatically creates one or more field-group widgets to hold the
field-level widgets. For more information on field groups, see the Field-group Widgets
section.
Frames
1935
19.11 Using Shared Frames
Sometimes you want several procedures to use the same frame. You might use the same frame
throughout an application or with a few different procedures in an application. Progress lets you
define a frame as shared, so that many procedures can use it. You use the DEFINE SHARED
FRAME statement to define a shared frame. You must describe the shared frame in a FORM
statement.
You can write a procedure to display customer information, another procedure to update order
information, and you can display all the information in the same frame. One way to do this is to
define a shared frame.
Figure 199 shows how two procedures can use the same frame.
p-dicust.p
p-updord.p
p-dicust.i
Figure 199: Shared Frames
DEFINE SHARED FRAME cust-frame
{p-dicust.i}
DEFINE NEW SHARED FRAME cust-frame
{p-dicust.i}
p-dicust.p p-updord.p
p-dicust.i
FORM
WITH FRAME cust-frame
Menu
Screen
Display
1936
The FORM statement in this example is in an include file, p-dicust.i. This file sets up and
names the custframe:
Although you cannot run the p-dicust.i file by itself because it is only a FORM statement, the
file describes the following frame:
p-dicust.i
FORM
xcust.cust-num COLON 10 LABEL "Cust #"
xcust.name COLON 10 xcust.phone COLON 50
xcust.address COLON 10 xcust.sales-rep COLON 50
csz NO-LABEL COLON 12 xcust.credit-limit COLON 50
SKIP (2)
order.order-num COLON 10 order.order-date COLON 30
order.ship-date COLON 30
order.promise-date COLON 30 WITH SIDE-LABELS 1 DOWN CENTERED ROW 5
TITLE " CUSTOMER/ORDER FORM " FRAME cust-frame.
Frames
1937
The p-dicust.p procedure displays customer information in this frame:
The p-dicust.p procedure displays customer information in the shared frame custframe and
lets the user update the order information for the customer on the screen. The procedure defines
the new shared frame named custframe and a new shared buffer, xcust, to store customer
information. (You can use only one DEFINE SHARED FRAME statement per frame in a
procedure.) The name custframe corresponds to the frame in the FORM statement in the
p-dicust.i include file.
p-dicust.p
DEFINE NEW SHARED FRAME cust-frame.
DEFINE NEW SHARED VARIABLE csz AS CHARACTER FORMAT "x(22)".
DEFINE NEW SHARED BUFFER xcust FOR customer.
REPEAT:
{p-dicust.i} /* include file for layout of shared frame */
PROMPT-FOR xcust.cust-num WITH 1 DOWN FRAME cust-frame.
FIND xcust USING xcust.cust-num NO-ERROR.
IF NOT AVAILABLE(xcust)
THEN DO:
MESSAGE "Customer not found".
NEXT.
END.
DISPLAY
name phone address sales-rep
city + ", " + state + " " + STRING(postal-code) @ csz
credit-limit WITH FRAME cust-frame.
RUN p-updord.p. /* External procedure to update customers orders */
END.
1938
The procedure prompts the user for a customer number and displays the customer information
for that customer using the frame defined in the p-dicust.i file. Then the procedure calls the
p-updord.p procedure, shown below:
The p-updord.p procedure defines the shared frame custframe and the shared variable csz,
which was first defined in the p-dicust.p procedure. It also defines the shared buffer to store
customer information. You must use the DEFINE SHARED VARIABLE statement for the csz
variable because variables named in a shared frame are not automatically shared variables. You
must also use the DEFINE SHARED FRAME statement for the custframe so that Progress can
recognize the frame.
The p-updord.p procedure finds the customer that the p-dicust.p procedure is using in the
shared buffer, xcust. The procedure then displays the information for each order of the customer
in the shared frame called custframe. Finally, the procedure allows the user to update the order
information.
When you use shared frames, remember these important points:
In the first procedure where you reference a shared frame, use the DEFINE NEW
SHARED FRAME statement. In subsequent procedures where you reference the shared
frame, use the DEFINE SHARED FRAME statement.
You must completely describe the shared frame in the initial DEFINE NEW SHARED
FRAME statement or an additional FORM statement. Procedures that share this frame
only have to define fields that correspond to the fields in the initial definition plus any
specified ACCUM option. Other Frame phrase options for the SHARED frames are
allowed but are ignored, except for the ACCUM option. This allows you to make use of
the same FORM statement in an include file for both the NEW SHARED and matching
SHARED frames.
p-updord.p
DEFINE SHARED FRAME cust-frame.
DEFINE SHARED VARIABLE csz AS CHARACTER FORMAT "x(22)".
DEFINE SHARED BUFFER xcust FOR customer.
FOR EACH order OF xcust:
{p-dicust.i} /* include file for layout of shared frame */
DISPLAY order.order-num WITH FRAME cust-frame.
UPDATE order.order-date order.ship-date
order.promise-date WITH FRAME cust-frame.
END.
Frames
1939
A shared frame is scoped to the procedure or the block within the procedure that defines
it as NEW. For example, in the p-updord.p procedure above, the p-dicust.i include file
has no effect on scope.
A shared frame is scoped only once, and the scope is in the procedure where the frame is
defined as NEW.
If you want to share a frame family, you must make all parent and child frames in the
family shared frames.
See the Progress Language Reference for more information on the DEFINE FRAME statement.
19.12 Field-group Widgets
When you display field-level widgets in a frame or assign a child frame to a parent frame,
Progress creates one or more field-group widgets to hold the field-level widgets and child
frames. (For information on assigning a child frame to a parent frame, see the Frame Families
section.)
Progress uses field groups to collect field-level widgets and child frames. You might find it
helpful to think of a field group as a kind of geometrical representation of a record (or an
iteration). For example, this code fragment displays five records, each contained in a field
group.
The output of this fragment is shown below.
All field-level widgets, such as buttons, are placed in field groups. A field group is a collector
of field-level widgets and child frames. However, Progress also allocates empty field groups.
For example, Progress allocates a field group to the background of a frame, whether or not the
field group contains any widgets.
FOR EACH customer WITH 5 DOWN.
END.
Field Group
1940
Field groups are the children of frames and the real parents of field-level widgets and child
frames. This makes frames the grandparents of field-level widgets and child frames. Thus, if
you want an application to perform an operation on field-level widgets in a frame without
knowing beforehand what widgets are in the frame, the application must access them by going
through their respective field groups. For more information on accessing field groups, see the
Accessing Field Groups section.
Field groups widget are unique in that Progress, not the application, is completely responsible
for their creation and deletion. An application can access the field groups, but cannot create or
delete them.
In most cases, it is not necessary to access field groups from within an application. Like child
frames, you can move individual field-level widgets in and out of frames by setting their
FRAME attribute.
Finally, field groups organize the tab order of the field-level widgets and child frames that they
contain. For more information, see Chapter 25, Interface Design.
Frames
1941
19.12.1 Field-group Types
Progress allocates two types of field groups:
Foreground
Background
Progress can allocate multiple foreground field groups per frame but only one background field
group. Figure 1910 shows the different field groups.
Figure 1910: Field-Group Allocation
Background
Field Group
Foreground
Field Groups Frame
X-Axis
Z-Axis
Y-Axis
Spare Field Group
1942
For a one-down frame, Progress allocates one foreground field group and one background field
group. For a down frame, Progress allocates one foreground field group for each iteration (plus
one extra if the number of visible iterations in the down frame is less than the number of records
that need to be displayed) and one background field group.
19.12.2 Field-group Characteristics
Field groups have the following characteristics:
They have geometric attributes (an x and y position, width, and height).
They have no visible representation (color, bounding box, or font).
They take no events.
They are created implicitly by Progress (you cannot create or define a field group).
Once Progress has created a field group, you can access it from within an application. For more
information, see the Accessing Field Groups section.
19.12.3 Field-group Size
Foreground field groups are as wide as the interior of the frame. The background field group is
also as wide as the interior of the frame.
Foreground field groups vary in height. In a dynamic one-down frame (and a static one-down
frame without column labels), the foreground field group is as high as the interior of the frame.
In a static one-down frame with column labels, the foreground field group starts below the
column headers; as a result, its height is less than the interior of the frame. In a down frame, the
foreground field groups are high enough to contain the field-level widgets displayed in one
iteration.
You can display dynamic field-level widgets within a field group. However, it is not
recommended that you place dynamic widgets in the foreground field groups of a down frame.
Not only is the height of these field groups determined by Progress (the application cannot
control the height), but the field group may also scroll off the screen (either in a scrolling frame
or if the frame retains a number of iterations). After it reappears, the field group will still contain
the dynamic widget, but also may contain a new record. For more information, see the
Field-group Visibility and Scrolling section.
You cannot mark, move, or resize field groups directly. However, if you resize a frame,
Progress automatically resizes the field groups by default.
Frames
1943
19.12.4 Field-group Position Relative to Frame
Frames contain field groups, which contain field-level widgets. Field groups are therefore
positioned relative to frames, while field-level widgets are positioned relative to field groups.
Consistent with this, the X, Y, ROW, and COLUMN attributes of a field group return values
relative to the frame. The X, Y, ROW, and COLUMN attributes of a field-level widget
(including radio buttons) return values relative to the parent field group.
To access the location of a field-level widget relative to its frame, query the field-level widgets
FRAMEX and FRAMEY attributes (for pixel values), or FRAMECOL and FRAMEROW
attributes (for character unit values).
For a list of field-group attributes, see the FIELD-GROUP Widget reference entry in the
19.12.5 Z order and Field Groups
If you overlap widgets in an application, Progress must determine which widget to place on top.
Within a frame, there are three layers:
The foreground layer, with all the nondrawable field-level widgets in the foreground field
group. This is the topmost layer. (A drawable field-level widget is a rectangle or image.)
The background layer, with all the nondrawable field-level widgets in the background
field group. This is the next topmost layer.
The drawable layer, with all the drawable field-level widgets from all of the field groups.
This is the bottommost layer.
Within each z layer, widgets also have a z order (that is, one foreground button may be on top
of another foreground button). However, Progress places all nondrawable foreground widgets
on top of all nondrawable background widgets, and places all drawable widgets on the bottom
layer. For example, if you have a text widget in the background and an image in the foreground,
the text widget appears on top of the image.
NOTE: Figure 1910 shows the relative z-order positions of the foreground and background
field groups (ZAxis), but does not show the separate drawable layer derived from
both of these field groups. The drawable layer is not a field group, itself, but a z-order
layer under the background field group (extreme left of Figure 1910) containing
drawable widgets from both field group layers.
If you want an application to be portable to character displays, you should avoid using
overlapping widgets. In a character display, if two field-level widgets overlap, one of the
widgets may appear, both may appear, or some part of each may appear.
1944
19.12.6 Field-group Visibility and Scrolling
Figure 1910 shows a spare field group. Progress allocates a spare field group if the number of
visible iterations is less than the number of records that need to be displayed. At any given time,
one of the foreground field groups in a down frame can be the spare. That is, the foreground
field group can scroll off the screen.
The frames FIRSTCHILD/NEXTSIBLING chain includes all of the field groups in the
frame (including the spare). Its order is not affected by scrolling (see the Accessing Field
Groups section).
However, the frame also has an GETITERATION( ) method, which along with the
NUMITERATIONS attribute, simulates an array of all of the visible foreground field groups.
Thus, if you want to find only the visible foreground field groups at any instant, you can use the
GETITERATION( ) method with the NUMITERATIONS attribute.
The GETITERATION( ) method takes an integer argument n and, starting at the top of the
frame, returns the widget handle of the field group that displays the nth visible iteration. You
can access all of these field groups by using a loop that starts at one (GETITERATION(1)) and
runs through the total number of visible iterations.
If the frame is named X, you can access the last visible iteration as follows:
If you have a widget handle variable named X, you can access the last visible iteration as
follows:
As the frame scrolls, these attributes return different values. Thus, if an application wants to
cycle through the visible iterations using the iteration loop, it should not do anything during the
cycle that would scroll the frame.
This code fragment produces a frame with five visible iterations.
GET-ITERATION(FRAME X:NUM-ITERATIONS)
GET-ITERATION(X:NUM-ITERATIONS)
FOR EACH customer WITH 5 DOWN.
END.
Frames
1945
Before Progress executes the FOR EACH loop, NUMITERATIONS equals 0 (because
Progress hasnt created any field groups yet). The first time through the loop, after Progress
displays the first custnum and name, NUMITERATIONS equals 1. The second time through,
NUMITERATIONS equals 2. Once Progress has displayed the fifth custnum and name,
NUMITERATIONS equals 5. The count will remain 5 until the frame is terminated. Note that
after Progress starts scrolling, there will be 6 field groups5 plus 1 spare (the spare will be
different as the frame scrolls). The NUMITERATIONS attribute will stay at 5, but there will
actually be 6 field groups.
Progress does not create new field groups (and all their underlying field-level widgets) as they
are scrolled off the screen. Instead, it clears the existing field groups and then reuses them.
If an application uses the UNDERLINE statement, Progress uses one foreground field group to
underline the fields in the field group directly above it. Also, if the application uses a DOWN
statement to advance one or more iterations in the frame without displaying any data, Progress
uses one of the foreground field groups to display a blank iteration. For example, this code
fragment uses a DOWN statement to display a blank iterations.
If you insert dynamic field-level widgets in a foreground field group of a down frame, you
should be aware of the following defaults:
As a frame scrolls, Progress moves the foreground field groups around in the frame. Thus,
if an application places a dynamic widget in a field group, the dynamic widget will jump
around in the frame as the field group moves.
Any foreground field group may become the spare field group as the field groups are
moved around in the frame. When a field group becomes the spare, it will not be visible
on screen.
If Progress uses a field group to display a blank iteration or uses an underline field group,
it hides all of the field groups children (including any dynamic widgets).
When a field group scrolls off the top or bottom of the frame, Progress clears the field
group. All fill-in widgets are reset to blanks, including any dynamic fill-in widgets.
NOTE: Because of the complex nature of these defaults, PSC recommends that you do not
place dynamic widgets in a foreground field group of a down frame.
REPEAT WITH FRAME a DOWN:
FIND NEXT customer.
DOWN 1 WITH FRAME a.
END.
1946
19.12.7 Accessing Field Groups
Different applications may want to access all of the field groups in a frame, the foreground field
groups, or the visible foreground field groups. The following examples show how an
application can access these different field groups.
Example 1
This example shows how an application might access all of the field groups (and their field-level
widgets and child frames) in a frame.
This example uses the frames FIRSTCHILD/NEXTSIBLING chain to access all of the field
groups, field-level widgets, and child frames in frame FRX (including the spare field group, if
one exists). FLW is set to each sibling field-level widget and child frame of the frame. Note that
the order in which this loop accesses the field groups is not connected with the order in which
the field groups are displayed on screen.
NOTE: This example does not access any widgets parented by child frames. To accomplish
that requires a recursive version of this procedure.
DEFINE VARIABLE GRP AS WIDGET-HANDLE. /* the field group */
DEFINE VARIABLE FLW AS WIDGET-HANDLE. /* the field-level widget */
GRP = FRAME FRX:FIRST-CHILD.
DO WHILE (GRP <> ?).
FLW = GRP:FIRST-CHILD.
DO WHILE (FLW <> ?). /* loop through field-level widgets in
field-group */
/* insert code here to access the widget */

FLW = FLW:NEXT-SIBLING.
END.
GRP = GRP:NEXT-SIBLING.
END.
Frames
1947
Example 2
This example shows how an application might access all of the foreground field groups (and
their field-level widgets and child frames) in a frame.
This example uses the frames FIRSTCHILD/NEXTSIBLING chain and the
FOREGROUND attribute to access all of the foreground field groups, field-level widgets, and
child frames in frame FRX (including the spare field group, if one exists).
NOTE: This example does not access any widgets parented by child frames. To accomplish
that requires a recursive version of this procedure.
DEFINE VARIABLE GRP AS WIDGET-HANDLE. /* the field group */
DEFINE VARIABLE FLW AS WIDGET-HANDLE. /* the field-level widget */
GRP = FRAME FRX:FIRST-CHILD.
DO WHILE (GRP <> ?).
IF (GRP:FOREGROUND) THEN DO:
field-group */
/* insert code here to access the widget */
END.
END.
GRP = GRP:NEXT-SIBLING.
END.
1948
Example 3
This example shows how an application might access all of the visible foreground field groups
(and their field-level widgets) in a down frame.
This example uses the frames FIRSTCHILD/NEXTSIBLING chain and the
GETITERATION( ) method to access all of the foreground widgets in the visible field groups
frame FRX.
DEFINE VARIABLE IDX AS INTEGER. /* index of visible iterations */
DEFINE VARIABLE GRP AS WIDGET-HANDLE. /* the field-group */
DEFINE VARIABLE FLW AS WIDGET-HANDLE /* the field-level widget */
DO IDX = 1 TO FRAME FRX:NUM-ITERATIONS:
GRP = FRAME FRX:GET-ITERATION(IDX).
field-group */
/* insert code to access the widget */
END.
END.
Frames
1949
19.13 Validation of User Input
Progress allows you to define validation expressions and user validation messages directly in
the Data Dictionary or programmatically with the VALIDATE option of the Format phrase and
the Browse Format phrase. The validation expression establishes the Boolean condition that
defines valid data. Progress displays the validation message to the user (in the message area or
in an alert box, depending on the configuration) if the new data fails the validation expression.
Progress executes validation expressions when the user attempts to leave a field. Once the user
begins to enter new data in, the user cannot leave the field without entering valid data or
cancelling the input.
Validation of user input is fundamental to guaranteeing the integrity of your database. Progress
provides all the language and system options you require to provide seamless validation of all
user input. First, this section outlines the most efficient and straightforward way to provide
complete validation. Then, it discusses the role of each language and system option that
contribute to the validation story and scenarios that can lead to validation holes.
19.13.1 Recommended Validation Techniques
Follow the short list of recommendations below for complete validation of user input:
Put as much of your validation expressions in the database schema with the Data
Dictionary.
For custom validation, add the VALIDATE option to the field reference in the DEFINE
FRAME, FORM, or DEFINE BROWSE statements. While the VALIDATE option can
legally be added in many places, placing it in one of these statements guarantees that it will
be compiled into the frame or browse definition.
Do not add fields to a frame after the initial definition (not possible for a browse). Or, if
you do, use programmatic validation.
Do not use the field:SENSITIVE = YES syntax to enable fields for input. Data Dictionary
validation is not compiled into a frame when this syntax is used.
1950
19.13.2 The Rules of Frame-based Validation
In Progress, validation of user input is a frame-based activity. The compiler adds validation
expressions to a frame from the Data Dictionary the first time a field is referenced in that frame
in an input statement (ENABLE, PROMPTFOR, SET, UPDATE). The compiler adds
programmatic validation (VALIDATE option) to the frame when it is encountered, as long as
it has not already compiled in Data Dictionary validation. So, if you want programmatic
validation to override existing Data Dictionary validation it is safest to place it in the DEFINE
FRAME, FORM, or DEFINE BROWSE statement. After the compiler adds initial validation
for a field in a frame, all other validation for that field in that frame is ignored.
To take advantage of this default behavior, add all of your default validation to database schema
and use the VALIDATE option for special cases. Since the default behavior is frame-based, you
can use different validation for the same field in different frames.
The ENABLE statement with the ALL option poses a special problem for the compiler, since it
cannot know syntactically which fields in the frame require Data Dictionary validation. To
avoid possible validation holes, the compiler adds Data Dictionary validation for all fields in the
frame, even if they are defined as non-sensitive widgets. If you add a field to a frame after the
compiler encounters the first ENABLE ALL statement, Data Dictionary validation will not be
added to the frame for this field. To avoid creating a possible validation hole, do not add new
fields to frames, or use the VALIDATE option to provide programmatic validation.
If you use the EXCEPT option with ENABLE ALL, the compiler will not add Data Dictionary
validation to the frame for the fields listed with EXCEPT.
Finally, note that Progress does not have any default validation behavior for the
widget:SENSITIVE = YES syntax. Using this backdoor technique for enabling fields for input
creates a validation hole. If you use this technique, then you will have to force frame-wide
validation to close any possible validation holes. The next section discusses frame-wide
validation techniques.
19.13.3 Forcing Frame-wide Validation
To make sure that your application does not have any validation holes, you have three options:
Add the USEDICTEXPS option on the Frame phrase for each affected frame.
Use the Dictionary Expressions startup parameter to apply the USEDICTEXPS option
to every frame in the application.
Use the frame VALIDATE( ) method to check all the fields in a frame before committing
the changes.
Frames
1951
Using the USEDICTEXPS Frame Phrase Option
The USEDICTEXPS option of the frame phrase forces all Data Dictionary validation and
help strings to be compiled into the frame on the first reference of a field in the frame. Note that
this is different from the normal behavior. Data dictionary validation is compiled in on the first
reference of the field in an input statement. For this reason, programmatic VALIDATE or HELP
options must be added to the DEFINE FRAME, FORM, or DEFINE BROWSE statements to
override existing Data Dictionary expressions. (The first reference of a field in the frame is
normally the reference in one of these statements, unless the field is added later.)
This option may add a lot of non-essential code to a frame, so its use should be restricted to
where necessary. The option is intended to be used with frames that might have fields enabled
with the widget:SENSITIVE = YES syntax. It is not necessary in any other case.
Using the Dictionary Expressions (dictexps) Startup Parameter
The Dictionary Expressions (dictexps) startup parameter is intended to be used as a temporary
step to close possible validation holes in existing applications. It has the effect of adding a
USEDICTEXPS option to every frame in the application, including those that are not used
for input. While this parameter quickly closes all possible validation holes, it is a highly
inefficient way of doing it.
For best long-term results, search for and replace widget:SENSITIVE = YES constructs, or use
the USEDICTEXPS option on effected frames.
For more information on the dictexps parameter, see the Progress Startup Command and
1952
Using the Frame VALIDATE( ) Method
However, you can force Progress to perform all established variable and field validations at any
time by executing the VALIDATE( ) method for the frame. The method returns TRUE if all
validate checks in the frame succeed. It returns FALSE for the first validate check that fails in
the order that data representation widgets are specified in the frame definition. A typical
application of this method is in a trigger for an event that accepts the current updates in the
frame. If the method fails, Progress gives input focus to the widget that failed the test after the
trigger returns to the blocking WAITFOR statement.
NOTE: You can also apply the VALIDATE( ) method to a single data representation widget
to perform any validate check for the underlying field or variable of that widget. If
the test fails, focus returns to the specified widget.
The following procedure shows the VALIDATE( ) method applied to a frame that is used to
update existing item records in the sports database. Enter an item number and press RETURN.
The procedure displays and enables fields from the selected record, if it is available. To update
the record in the database and enter a new item number, choose the bContinue button.
Note that once an item record is enabled for update, the procedure does not allow the record to
be written back to the database unless all the relevant fields pass the specified validate checks.
This is true even if no input fields have been entered and no data has changed from the original
record.
Frames
1953
p-frmval.p
DEFINE BUTTON bContinue LABEL "Continue".
DEFINE BUTTON bQuit LABEL "Quit".
DEFINE FRAME ItemFrame
item.item-num
item.item-name
VALIDATE(item-name BEGINS "B",
"Must enter item-name starting with B")
item.on-hand
VALIDATE(on-hand > 0, "Must enter items on-hand > 0.")
item.allocated
VALIDATE(allocated <= on-hand,
"Allocated cannot be greater than on-hand items.")
bContinue
bQuit
WITH SIDE-LABELS.
ON RETURN OF item.item-num IN FRAME ItemFrame DO:
FIND FIRST item
WHERE item-num = INTEGER(item-num:SCREEN-VALUE) NO-ERROR.
IF AVAILABLE(item) THEN DO:
DISABLE item-num WITH FRAME ItemFrame.
DISPLAY item-name on-hand allocated WITH FRAME ItemFrame.
ENABLE ALL EXCEPT item-num WITH FRAME ItemFrame.
END.
ELSE DO:
MESSAGE "Item not on file. Enter another.".
RETURN NO-APPLY.
END.
END.
ON CHOOSE OF bContinue IN FRAME ItemFrame DO:
IF NOT FRAME ItemFrame:VALIDATE() THEN
RETURN NO-APPLY.
ASSIGN item.item-name item.on-hand item.allocated.
DISABLE ALL EXCEPT bQuit WITH FRAME ItemFrame.
ENABLE item.item-num WITH FRAME ItemFrame.
END.
FIND FIRST item NO-ERROR.
DISPLAY
item.item-num item.item-name item.on-hand item.allocated
bContinue bQuit
WITH FRAME ItemFrame.
ENABLE item.item-num bQuit WITH FRAME ItemFrame.
WAIT-FOR CHOOSE OF bQuit IN FRAME ItemFrame.
1954
19.13.4 Disabling Data Dictionary Validation on a Frame or Field
To disable all Data Dictionary validation for the fields in a frame, add the NOVALIDATE
option to the Frame phrase. NOVALIDATE only disables Data Dictionary validationit has
no effect on programmatic validation.
To disable Data Dictionary validation for a field, use the VALIDATE option as shown in the
code fragment below.
customer.credit-limit VALIDATE(TRUE, "")
20
Using Dynamic Widgets
Most applications do not require dynamic widgets other than windows, because widget
definitions can be determined statically, at compile time. However, sometimes an application
does not have all the information it needs to define a widget until run time. One example is an
application that allows the user to add and remove buttons that duplicate menu functions.
Another is an application that designs user interfaces for other applications, such as the Progress
AppBuilder. All such applications require that you create and delete widget definitions at run
time. For applications like these, you must use dynamic widgets.
This chapter describes the basic requirements and techniques for creating and managing
dynamic widgets in a user interface, and how they differ from static widgets. These include
techniques for managing dynamic widgets individually and as a group. For an introduction to
defining static and dynamic widgets, see Chapter 16, Widgets and Handles.
Some dynamic widgets require a more focused explanation than the general information
described here. For information on dynamic menus and submenus, see Chapter 22, Menus.
For information on dynamic windows (all windows are dynamic except for the static default
window), see Chapter 21, Windows.
This chapter describes techniques for:
Managing dynamic widgets
Managing dynamic widget pools
Creating and using dynamic queries
Creating and using a dynamic browse
202
20.1 Managing Dynamic Widgets
Although you can create and delete a dynamic widget at run time, you must specify the
attributes and environment of a dynamic widget much more explicitly than for a static widget.
Progress provides attributes that allow you to specify for dynamic widgets at run time most of
the options that you specify for static widgets at compile time. While Progress automatically
sets read-only attributes for dynamic widgets just as it does for static widgets, Progress provides
fewer defaults for the attributes that you can set. In addition, you must use different 4GL
statements to work with dynamic widgets than you typically do with static widgets.
Note that dynamic widgets do not adhere to scoping rules. That is, they exist until you delete
them or the session ends. Thus, if you create a dynamic button in the FOR EACH loop of a
subprocedure, that button continues to exist after the subprocedure returns. However, note that
any widget handle variables are locally or globally scoped as you define them. Also, while
dynamic widgets are not scoped, trigger definitions are scoped. Thus, for dynamic widgets,
define persistent triggers or put your trigger definitions in a persistent procedure.
20.1.1 Static Versus Dynamic Widget Management
Table 201 compares the major 4GL actions involving static and dynamic widgets and
summarizes their differences.
Table 201: Static Versus Dynamic Widget Management (1 of 2)
4GL
Widget Action
Accomplished for
Static Widgets by . . .
Accomplished for
Dynamic Widgets by . . .
Create DEFINE widget statement,
VIEWAS phrase, FORM
statement (for frames), and
default scoping (for frames).
CREATE widget statement
Delete N/A DELETE WIDGET or DELETE
WIDGETPOOL statement
1
Reference Definition name at compile time
and run time; widget handle at
run time
Widget handle at run time
View on Display Frame I/O statements, including
ENABLE, DISPLAY, INSERT,
UPDATE, SET, or
PROMPTFOR; VIEW
statement
VIEW statement or setting the
VISIBLE attribute of each
widget to TRUE
2,3
203
Hide from Display HIDE statement HIDE statement or setting the
VISIBLE attribute of each
widget to FALSE
2
Make Sensitive to
Input
ENABLE, INSERT, UPDATE,
SET, or PROMPTFOR
statement
Setting the SENSITIVE
attribute of each widget to
TRUE
2
Make Insensitive to
Input
DISABLE statement Setting the SENSITIVE
attribute of each widget to
FALSE
2
Block for Input WAITFOR, INSERT,
UPDATE, SET or
PROMPTFOR statement
WAITFOR statement
Move Data from
Screen to Record
Buffer
ASSIGN, SET, INSERT, or
UPDATE statement applied to
corresponding field or variable
Explicit assignment from the
SCREENVALUE attribute of
the widget to a specified field or
variable
2
Move Data from
Record to Screen
Buffer
DISPLAY, INSERT, or
UPDATE statement applied to
corresponding field or variable
Explicit assignment from a
specified field, variable, or
constant to the
SCREENVALUE attribute of
the widget
2
1
For more information on widget pools, see the Managing Dynamic Widget Pools section.
2
You can also use these techniques with static widgets.
3
The behavior of the VISIBLE attribute also depends on the setting of the HIDDEN attribute.
Table 201: Static Versus Dynamic Widget Management (2 of 2)
4GL
Widget Action
Accomplished for
Static Widgets by . . .
Accomplished for
Dynamic Widgets by . . .
204
20.1.2 Setting Up Dynamic Field-level Widgets
When setting up dynamic field-level widgets, it helps to keep these points in mind:
Frame parenting You can place a dynamic field-level widget in either a static or
dynamic frame (see the Setting Up Dynamic Frames section). Assign the frame handle
to the FRAME attribute of the field-level widget. For a field-level widget, the PARENT
attribute points to the field group, not the frame, of the widget. Progress automatically puts
the widget in a field group when you set its frame, and also assigns the widget a default
tab position if it is an input widget.
Widget positioning To space them out in a frame, you must explicitly position all
dynamic widgets by setting the appropriate vertical (ROW or Y) and horizontal
(COLUMN or X) placement attributes. However, Progress does assume the top-most and
left-most position in the frame if you do not set a placement attribute for the widget.
Widget sizing You can size a widget, depending on its widget type and data type, using
either the various height and width attributes or the FORMAT attribute. For example, a
fill-in field with its FORMAT attribute set to "x(20)" is exactly the same size as one with
its WIDTHCHARS attribute set to 20.
Label handling Not every field-level widget gets its label by setting the LABEL
attribute. You must provide separate text widgets as labels for some data representation
widgets. For side labels, you set the SIDELABELHANDLE attribute of the specified
data representation widget to the handle of the text widget containing the label in its
SCREENVALUE attribute. For any other type of label, such as for vertical columns, you
must create and manage the text widget completely separately. You must also position text
widgets used as labels explicitly, even for side labels. Progress assigns no positioning
information for dynamic side labels, as it does for button or toggle box labels.
205
Data handling Unlike static data representation widgets, dynamic widgets have no
field or variable implicitly associated with them. You must explicitly assign data between
a widgets SCREENVALUE attribute and the field or variable that you choose for data
storage. Thus, you can use a single widget to represent several fields and variables at
different times, depending on the widget and data type.
Data typing Some dynamic widgets support entry and display data types other than
CHARACTER, and some, such as fill-in fields and combo boxes support the full range of
Progress entry and display data types. Note that for dynamic widgets this support is for
entry and display purposes only. The SCREENVALUE attribute always stores the data
in character format, no matter what the widget data type. You must make all necessary data
type conversions using the appropriate functions (STRING, INTEGER, etc.) when
assigning data between the widget SCREENVALUE attribute and the field or variable
that you choose for data storage.
206
The following procedure creates a dynamic fill-in with the INTEGER data type when you
choose the Customer Number button. You can then enter a value according to the >>>>9"
format. The entered integer value is stored as a character string in the screen buffer. Pressing
RETURN displays this value in the message area. Choosing the Delete Field button deletes the
fill-in, removing it from the display:
p-dynfl1.p (1 of 2)
DEFINE BUTTON bCustNumber LABEL "Customer Number".
DEFINE BUTTON bDelete LABEL "Delete Field".
DEFINE VARIABLE fCustHandle AS WIDGET-HANDLE.
DEFINE VARIABLE lCustHandle AS WIDGET-HANDLE.
SKIP(3)
SPACE (1) bCustNumber bDelete
WITH SIZE 40 BY 5 SIDE-LABELS.
ON CHOOSE OF bCustNumber IN FRAME CustFrame
DO:
IF fCustHandle <> ? THEN
DO:
MESSAGE bCustNumber:LABEL "field already exists.".
RETURN.
END.
CREATE TEXT lCustHandle
ASSIGN
FRAME = FRAME CustFrame:HANDLE
DATA-TYPE = "CHARACTER"
FORMAT = "x(16)"
SCREEN-VALUE = "Customer Number:"
ROW = 2
COLUMN = 2
.
CREATE FILL-IN fCustHandle
ASSIGN
FRAME = FRAME CustFrame:HANDLE
DATA-TYPE = "INTEGER"
FORMAT = ">>>>9"
SIDE-LABEL-HANDLE = lCustHandle
ROW = 2
COLUMN = lCustHandle:COLUMN + lCustHandle:WIDTH-CHARS + 1
SENSITIVE = TRUE
VISIBLE = TRUE
TRIGGERS:
ON RETURN PERSISTENT RUN SetFieldTrig.
END TRIGGERS
.
END.
207
20.1.3 Setting Up Dynamic Frames
Progress allows you to create dynamic one-down frames. You cannot create dynamic down
frames. You can populate a dynamic frame only with dynamic field-level widgets and you must
explicitly specify their position within that frame. When Progress builds a static frame and
populates it with static widgets, it creates an intelligent default size for the frame and intelligent
default placement for the widgets. Progress does not do this with dynamic frames. You must
explicitly define frame size and widget placement.
ON CHOOSE OF bDelete IN FRAME CustFrame
DO:
IF fCustHandle <> ? THEN
DO:
DELETE WIDGET fCustHandle.
fCustHandle = ?.
DELETE WIDGET lCustHandle.
END.
END.
WAIT-FOR GO OF FRAME CustFrame.
PROCEDURE SetFieldTrig:
MESSAGE "You entered" lCustHandle:SCREEN-VALUE
fCustHandle:SCREEN-VALUE.
END PROCEDURE.
p-dynfl1.p (2 of 2)
208
The following code creates a dynamic frame, then populates it with an editor widget and a quit
button:
By default, Progress places the dynamic frame in the current window. To place the frame in a
different window, set the PARENT attribute to the widget handle of that window.
p-dynfrm.p
DEFINE VARIABLE ed AS WIDGET-HANDLE.
DEFINE VARIABLE frame1 AS WIDGET-HANDLE.
DEFINE VARIABLE button1 AS WIDGET-HANDLE.
CREATE FRAME frame1
ASSIGN
WIDTH-CHARS = 50
HEIGHT-CHARS = 28
SENSITIVE = YES.
VIEW frame1.
CREATE BUTTON button1
ASSIGN
X = 20
Y = 20
LABEL = "quit"
FRAME = frame1
SENSITIVE = YES
TRIGGERS:
ON CHOOSE STOP.
END TRIGGERS.
VIEW button1.
CREATE EDITOR ed
ASSIGN
WIDTH-CHARS = 20
HEIGHT-CHARS = 7
X = 70
Y = 0
FRAME = frame1
SENSITIVE = YES.
VIEW ed.
WAIT-FOR GO OF frame1.
209
This is the output of p-dynfrm.p:
20.2 Managing Dynamic Widget Pools
Every dynamic widget you create is assigned to a widget pool. A widget pool is a group of
widgets that are scoped together and can be deleted as a group.
Progress creates a single unnamed widget pool for each client session. The session pool is
initially the default pool for all dynamic widgets created during the session. It is automatically
deleted when the session ends.
You can also create your own named or unnamed widget pools with the
CREATE WIDGETPOOL statement:
You can delete a widget pool with the DELETE WIDGETPOOL statement:
SYNTAX
CREATE WIDGET-POOL [ pool-name [ PERSISTENT ] ]
[ NO-ERROR ]
SYNTAX
DELETE WIDGET-POOL [ pool-name ] [ NO-ERROR ]
2010
In general, when you create a dynamic widget, Progress assigns it to the most recently created
unnamed widget pool by default. You can explicitly assign a dynamic widget only to a named
widget pool. When you delete a widget pool, all dynamic widgets assigned to that pool are
deleted as well.
20.2.1 Named Widget Pools
Progress supports two types of named widget pools: persistent and nonpersistent. A persistent
widget pool remains allocated until it is explicitly deleted or the session ends. A nonpersistent
widget pool remains allocated until it is explicitly deleted or the procedure block that creates it
goes out of scope. When execution of a procedure or trigger ends or goes out of scope, Progress
automatically deletes any nonpersistent widget pool defined in that routine.
NOTE: A persistent procedure goes out of scope only when it is explicitly deleted. Thus,
non-persistent widget pools created in it can persist as long as the procedure persists.
When you create a dynamic widget, you can assign it to a named pool by using the
IN WIDGETPOOL option.
2011
The following procedure creates a named widget pool and creates a series of buttons in it:
The widget pool in this example is nonpersistent. Therefore, if you omit the DELETE
WIDGETPOOL statement at the end of the procedure, the widget pool is automatically deleted
when the procedure ends.
p-dybut2.p
DEFINE FRAME butt-frame
WITH WIDTH 60 CENTERED TITLE "Sales Representatives".
FORM
salesrep
CREATE WIDGET-POOL "rep-buttons".
num-buts = 0.
FOR EACH salesrep:
CREATE BUTTON temp-hand IN WIDGET-POOL "rep-buttons"
ASSIGN LABEL = salesrep.sales-rep
SENSITIVE = TRUE
TRIGGERS:
ON CHOOSE
DO:
FIND salesrep WHERE salesrep.sales-rep = SELF:LABEL.
END.
END TRIGGERS.
END.
FRAME butt-frame:HEIGHT-CHARS = (num-buts / 3) + 2.
DELETE WIDGET-POOL "rep-buttons".
2012
Because all the widgets in p-dybut2.p are created in the main procedure and are deleted at the
end of the procedure, the widget pool does not need to be persistent. However, the following
procedure requires a persistent widget pool. The following procedure, p-dybut3.p, accepts a
month and year and then creates a button for each order entered during that month:
p-dybut3.p (1 of 2)
DEFINE VARIABLE report-month AS INTEGER LABEL "Month" FORMAT ">9".
DEFINE VARIABLE report-year AS INTEGER LABEL "Year" FORMAT "9999".
FORM
report-month report-year
WITH FRAME prompt-frame SIDE-LABELS.
DEFINE FRAME butt-frame WITH WIDTH 80.
ON GO OF FRAME prompt-frame
DO:
IF report-month:MODIFIED or report-year:MODIFIED
THEN DO:
ASSIGN report-month report-year.
DELETE WIDGET-POOL "order-pool".
RUN make-buttons.
END.
END.
ASSIGN report-month = MONTH(TODAY)
report-year = YEAR(TODAY).
DISPLAY report-month report-year WITH FRAME prompt-frame.
RUN make-buttons.
ENABLE report-month report-year WITH FRAME prompt-frame.
DO ON ERROR UNDO, LEAVE ON ENDKEY UNDO, LEAVE ON STOP UNDO, LEAVE:
END.
DELETE WIDGET-POOL "order-pool".
2013
PROCEDURE make-buttons:
CREATE WIDGET-POOL "order-pool" PERSISTENT.
num-buts = 0.
FRAME butt-frame:HIDDEN = TRUE.
FOR EACH order WHERE MONTH(order-date) = report-month AND
YEAR(order-date) = report-year:
FRAME butt-frame:HEIGHT-CHARS = TRUNC(num-buts / 5, 0) + 3.
CREATE BUTTON temp-hand IN WIDGET-POOL "order-pool"
ASSIGN LABEL = STRING(order-num) + "/" + STRING(cust-num)
SENSITIVE = TRUE
TRIGGERS:
ON CHOOSE
PERSISTENT RUN disp-order.
END TRIGGERS.
END.
FRAME butt-frame:HIDDEN = FALSE.
IF num-buts = 0
THEN MESSAGE "No orders found for" STRING(report-month) + "/" +
STRING(report-year) VIEW-AS ALERT-BOX INFORMATION BUTTONS OK.
END PROCEDURE.
PROCEDURE disp-order:
FORM
order
WITH FRAME order-frame SIDE-LABELS.
FIND order WHERE order-num =
INTEGER(SUBSTRING(SELF:LABEL, 1, INDEX(SELF:LABEL, "/") - 1)).
CREATE WINDOW temp-hand IN WIDGET-POOL "order-pool"
ASSIGN TITLE = "Order Detail"
VIRTUAL-HEIGHT-CHARS = FRAME order-frame:HEIGHT-CHARS.
CURRENT-WINDOW = temp-hand.
DISPLAY order WITH FRAME order-frame.
CURRENT-WINDOW = DEFAULT-WINDOW.
END PROCEDURE.
p-dybut3.p (2 of 2)
2014
In this example, the widget pool is created within the internal procedure makebuttons. Because
the buttons must be available outside the internal procedure, the widget pool must be persistent;
otherwise the pool would be deleted at the end of the internal procedure. When you change the
month or year value, the GO trigger deletes the widget pool (and therefore deletes all the buttons
as well). It then runs makebuttons to create a new widget pool and a new set of buttons.
Note that the internal procedure, disp-order, creates a window in the persistent widget pool.
When you change the month or year, any windows so created are deleted along with the buttons.
When you use a persistent widget pool you must make sure the pool is deleted. In p-dybut3.p
the DO group surrounding the WAITFOR statement ensures that control will pass to the
DELETE WIDGETPOOL statement no matter how you exit the procedure.
20.2.2 Unnamed Widget Pools
Any unnamed widget pool you create becomes the default pool until it is deleted or until you
create another unnamed widget pool. Any unnamed pools you create are scoped to the routine
in which they are created. Also, any subprocedure or trigger inherits, as its default pool, the most
recent unnamed widget pool created in a calling procedure until (and unless) it creates an
unnamed widget pool of its own. When execution of a routine ends, or it goes out of scope, any
unnamed pools created in the routine (and therefore, all widgets in them) are automatically
deleted.
NOTE: A persistent procedure goes out of scope only when it is explicitly deleted. Thus,
unnamed widget pools created in it can persist as long as the procedure persists.
If you omit the IN WIDGETPOOL option in the statement that creates the widget, the widget
is automatically assigned to the most recently created unnamed widget pool that has not been
deleted.
You can delete the current default widget pool by using the DELETE WIDGETPOOL
statement without a pool name. You can delete the default widget pool only within the routine
that defined it. For example, if you define an unnamed widget pool in a procedure, you cannot
delete it in a subprocedure or trigger called by that procedure. If you attempt to do so, Progress
ignores the DELETE WIDGETPOOL statement.
You cannot specify the PERSISTENT option when you create an unnamed widget pool. All
unnamed pools, except the session pool and pools created in persistent procedures, are
nonpersistent.
2015
You might use an unnamed widget pool, for example, to ensure that all widgets created in the
default pool in a run procedure are deleted when that procedure returns or goes out of scope. For
example, the following procedure calls p-dybuts.p (see Chapter 16, Widgets and Handles):
In this example, the CREATE WIDGETPOOL statement creates a new default widget pool.
Any widgets created in the default pool within p-dybuts.p are placed in this pool. After
p-dybuts.p completes, the DELETE WIDGETPOOL statement deletes that widget pool.
On the other hand, in a persistent procedure, you can use an unnamed widget pool to ensure that
its dynamic widgets are not deleted after it returns from instantiating its persistent context.
Otherwise, if the calling procedure deletes the widget pool that was current when it created the
persistent procedure, any dynamic widgets created for the persistent context are deleted as well.
Thus, if you ran p-dybuts.p persistently in p-unname.p, creating an unnamed widget pool in
p-dybuts.p prevents p-unname.p from deleting the dynamic widgets created in the persistent
context of p-dybuts.p. For a working example, see the section on multiple-window
applications with persistent procedures in Chapter 21, Windows.
20.3 Creating and Using Dynamic Queries
The static query is one of the basic methods of fetching database records. For more information
on static queries, see Defining a Set of Records to Fetch in Chapter 9, Database Access.
This section describes programming and using the dynamic querya query whose elements are
resolved at runtime.
Progress supports creating and using dynamic queries by providing query, buffer, and
buffer-field objects.
p-unname.p
CREATE WIDGET-POOL.
RUN p-dybuts.p.
DELETE WIDGET-POOL.
2016
20.3.1 Creating a Query Object
The query object corresponds to an underlying Progress query, which can be static or dynamic.
A static query is one you define at compile time using the DEFINE QUERY statement. A
dynamic query is one you create at run time using the QUERY option of the CREATE Widget
statement.
The query object, like other Progress objects, is represented by a variable of type HANDLE.
You can use a HANDLE variable to acquire a new query object for a dynamically-created
query, as the following code fragment demonstrates:
You can also use a HANDLE variable to acquire the query object of an existing
statically-created query, as the following code fragment demonstrates:
DEFINE VARIABLE my-query-handle AS HANDLE.
CREATE QUERY my-query-handle.
...
DEFINE VARIABLE my-query-handle AS HANDLE.
DEFINE QUERY q1 FOR customer.
my-query-handle = QUERY q1:HANDLE.
...
2017
20.3.2 Using a Query Object
Using a dynamic query requires using several methods in addition to the CREATE QUERY
statement. The CREATE QUERY statement does not define what database table or buffer you
wish to access or what subset of records you want to fetch. The SETBUFFERS( ) method and
the QUERYPREPARE( ) method specify this information and the QUERYOPEN( ) method
opens the query.
The following code fragment depicts one way of creating and using a dynamic query:
For a list of the attributes and methods of the query object, see the Query Object Handle
reference entry in the Progress Language Reference. For a complete description of the attributes
and methods, see the Attributes and Methods Reference chapter of the same book.
DEFINE VARIABLE qh8 AS WIDGET-HANDLE.
CREATE QUERY qh8.
qh8:SET-BUFFERS(BUFFER invoice:HANDLE).
qh8:QUERY-PREPARE("FOR EACH invoice BY invoice-date").
qh8:QUERY-OPEN().
REPEAT WITH FRAME fr1:
qh8:GET-NEXT.
IF qh8:QUERY-OFF-END THEN LEAVE.
. . .
END.
.
.
.
DELETE OBJECT qh8.
2018
20.3.3 The Buffer Object
The buffer object corresponds to an underlying Progress buffer, which can be static or dynamic.
A static buffer is one you define at compile time by using the DEFINE BUFFER statement, or
by implicitly referencing a table in a 4GL construct such as customer.cust-num. A dynamic
buffer is one you create at run time using the BUFFER option of the CREATE Widget
statement.
The buffer object, like the query object and other Progress objects, is represented by a variable
of type HANDLE. You can use a HANDLE variable to acquire a new buffer object as the
following code fragment demonstrates:
You can also use a HANDLE variable to acquire a buffer object for an existing statically-created
buffer, as the following code fragment demonstrates:
With the buffer object you can:
Create a dynamic buffer for a dynamic query
Manipulate an existing static buffer
Write generic 4GL code without knowing at compile time the precise names of the
databases, buffers, and fields
Determine schema properties, such as the names and values of individual buffer-fields, by
using dynamic buffer-fields and their methods
DEFINE VARIABLE my-buffer-handle AS HANDLE.
CREATE BUFFER my-buffer-handle FOR TABLE "mycusttab".
...
DEFINE VARIABLE my-buffer-handle AS HANDLE.
my-buffer-handle = BUFFER customer:HANDLE.
...
2019
The following program example demonstrates the use of buffer objects in a dynamic query.
Note the use of the dynamic predicate (WHERE and BY clauses) in the query:
When the program pauses, press the GO key (usually F2) to continue.
p-qryob1.p
/* p-qryob1.p - demonstrates buffer and query objects */
DEFINE VARIABLE qry1 AS HANDLE.
DEFINE VARIABLE wherev AS CHARACTER INITIAL "WHERE cust-num < 10".
DEFINE VARIABLE sortv AS CHARACTER INITIAL "BY sales-rep".
DEFINE VARIABLE bval AS LOGICAL.
DEFINE VARIABLE bh AS WIDGET-HANDLE EXTENT 4.
CREATE QUERY qry1.
REPEAT:
UPDATE wherev FORMAT "x(70)"
LABEL "Enter WHERE and BY information." SKIP
sortv FORMAT "x(70)" NO-LABEL.
qry1:SET-BUFFERS(BUFFER customer:HANDLE, BUFFER order:HANDLE).
bval = qry1:QUERY-PREPARE("FOR EACH customer " + wherev +
", EACH order OF customer " + sortv).
REPEAT i = 1 TO qry1:NUM-BUFFERS:
bh[i] = qry1:GET-BUFFER-HANDLE(i).
DISPLAY bh[i]:NAME. /* display the buffer names */
END.
IF (bval = FALSE) THEN NEXT.
qry1:QUERY-OPEN.
REPEAT WITH FRAME fr1 ROW 8:
qry1:GET-NEXT.
IF (qry1:QUERY-OFF-END) THEN LEAVE.
DISPLAY cust.cust-num cust.name cust.sales-rep
cust.state order.order-num.
END.
qry1:QUERY-CLOSE.
END.
DELETE OBJECT qry1.
2020
Notes on Dynamic Buffers
Since the dynamic buffer lets you manipulate database records at run time without the
benefit of the compilers security checking, Progress ensures that when you use a dynamic
buffer, you have the necessary read, write, create, and delete permissions. In addition, if
the table corresponding to a dynamic buffer specifies delete validation, Progress does not
let you delete instances of the table dynamically.
When you have finished using the buffer object, it is important to apply the
BUFFERRELEASE method, since Progress does not automatically release the object
until the underlying buffer object is deleted.
A dynamic buffer has the same scope as the widgetpool in which it was created. This
means that Progress automatically deletes a dynamic buffer object only when it deletes its
widgetpool. To delete a dynamic buffer object manually, you must use the DELETE
OBJECT statement.
If you place the phrase BUFFER name anywhere in a procedure file, where name
represents the name of a table, not necessarily the name of a buffer you defined using the
DEFINE statement, Progress scopes name as it would a free reference.
For a list of the attributes and methods of the buffer object, see the Buffer Object Handle
reference entry in the Progress Language Reference. For a complete description of the
attributes and methods, see the Attributes and Methods Reference chapter of the same
book.
20.3.4 The Buffer-field Object
The buffer-field object represents a field of a buffer. You do not create buffer-field objects.
Progress creates them automatically when you reference any field of a buffer object.
Using buffer-field objects lets you examine and modify the fields of a buffer and examine the
schema properties of the fields.
When your code accesses buffer-fields, Progress checks security permissions at run time.
2021
You can use HANDLE variables to retrieve the handle of a buffer-field object, as the following
code fragments demonstrate:
The following program example demonstrates using bufferfield objects and their
BUFFERVALUE, NAME and EXTENT attributes. Note that bufferfield objects can be used
without using query or buffer objects:
DEFINE VARIABLE my-buffer-handle as HANDLE.
DEFINE VARIABLE my-buffer-field-handle as HANDLE.
...
my-buffer-handle = BUFFER custx:HANDLE.
my-buffer-field-handle = my-buffer-handle:BUFFER-FIELD(3).
DEFINE VARIABLE my-buffer-field-handle as HANDLE.
...
my-buffer-field-handle = BUFFER customer:BUFFER-FIELD("cust-num").
p-qryob2.p
/* p-qryob2.p - demonstrates buffer and buffer-field objects */
DEFINE VARIABLE arrayi AS INTEGER.
DEFINE VARIABLE bh AS WIDGET-HANDLE.
DEFINE VARIABLE fh AS WIDGET-HANDLE EXTENT 100.
DEFINE VARIABLE fhc AS HANDLE.
DEFINE BUFFER custx FOR customer.
FIND FIRST custx.
bh = BUFFER custx:HANDLE.
MESSAGE "Value of City field is: " city:BUFFER-VALUE IN BUFFER custx.
fhc = bh:BUFFER-FIELD("city").
MESSAGE "Name of City field is: " fhc:NAME.
DISPLAY bh:NAME.
REPEAT i = 1 TO bh:NUM-FIELDS TRANSACTION:
fh[i] = bh:BUFFER-FIELD(i).
IF i = 5 THEN fh[i]:BUFFER-VALUE = "new addr2".
DISPLAY fh[i]:NAME fh[i]:EXTENT.
arrayi = 0.
IF fh[i]:EXTENT > 0 THEN arrayi = 2.
DISPLAY STRING(fh[i]:BUFFER-VALUE(arrayi)) FORMAT "x(20)".
END.
2022
Notes on Dynamic BufferFields
If you assign the UNKNOWN value (?) to the BUFFERVALUE attribute of a
bufferfield object, the value of BUFFERVALUE becomes the UNKNOWN value.
Similarly, if you assign the empty string to the BUFFERVALUE attribute of a
buffer-field object, the value of BUFFERVALUE becomes the UNKNOWN
valueunless the buffer-field object is CHARACTER, in which case the value becomes
the empty string. Conversely, if you assign the UNKNOWN value to the
BUFFERVALUE attribute of a buffer-field object, the value of its STRINGVALUE
attribute becomes the empty string.
For a list of the attributes and methods of the buffer-field object, see the Buffer-field
Object Handle reference entry in the Progress Language Reference. For a complete
description of the attributes and methods, see the Attributes and Methods Reference
chapter of the same book.
20.3.5 Error Handling
Each method of the query object, buffer object, and buffer-field object that can have errors
returns a value of type LOGICAL that you can test. If an error occurs, the method returns
FALSE, but does not automatically raise the error condition. Progress Software Corporation
(PSC) recommends that you test the return value of methods like QUERYPREPARE, where
an error causes subsequent OPENs, GETNEXTs, etc. to fail.
The following code fragments demonstrates checking the return value after the
QUERYPREPARE method:
The following code fragment demonstrates checking the return value after the QUERYOPEN
method:
DEFINE VARIABLE retval AS LOGICAL.
retval = q:QUERY-PREPARE("FOR EACH customer...").
IF retval = FALSE THEN.../* error exit */
DEFINE VARIABLE retval AS LOGICAL.
retval = q:QUERY-OPEN().
IF retval = FALSE, THEN.../* error exit */
2023
20.3.6 Dynamic Query Code Example
The following program example demonstrates how you can change the predicate of a dynamic
query using radio-set input and populate a dynamic browse (covered in the next section) with
varying results-lists:
p-fnlqry.p (1 of 3)
CURRENT-WINDOW:ROW = 1.
CURRENT-WINDOW:HEIGHT-CHARS = 18.
CURRENT-WINDOW:WIDTH-CHARS = 132.
CURRENT-WINDOW:TITLE = "Dynamic Browse With Dynamic Query".
CURRENT-WINDOW:KEEP-FRAME-Z-ORDER = TRUE.
/* Test controls */
DEFINE BUTTON Make LABEL "CreateDynBrowse".
DEFINE BUTTON AddCols LABEL "Add Columns".
DEFINE BUTTON btn-delete LABEL "DeleteDynBrowse".
DEFINE BUTTON btn-quit LABEL "&Quit" AUTO-ENDKEY.
DEFINE VARIABLE query-criteria AS CHARACTER
VIEW-AS RADIO-SET VERTICAL
RADIO-BUTTONS
"All customers", "FOR EACH customer NO-LOCK", "USA customers",
"FOR EACH customer WHERE customer.country EQ USA NO-LOCK BY
customer.state ",
"Non-USA customers",
"FOR EACH customer WHERE customer.country NE USA NO-LOCK BY
customer.country "
SIZE 25 BY 3 TOOLTIP "Choose the customers you want to see"
INITIAL "FOR EACH customer NO-LOCK" NO-UNDO.
/* Widget and other Handles */
DEFINE VARIABLE Browse-Hndl AS WIDGET-HANDLE.
DEFINE VARIABLE bufFieldHandle AS WIDGET-HANDLE.
DEFINE VARIABLE qh AS WIDGET-HANDLE.
DEFINE VARIABLE bh AS WIDGET-HANDLE.
bh = BUFFER customer:HANDLE.
/* Create Query */
CREATE QUERY qh.
qh:SET-BUFFERS(bh).
DEFINE FRAME F1
skip(13)
make AddCols btn-delete btn-quit query-criteria
WITH SIZE 132 BY 18 THREE-D NO-LABELS.
2024
ON CHOOSE OF make DO: /* LABEL "CreateDynBrowse". */
CREATE BROWSE Browse-Hndl
ASSIGN
FRAME = FRAME F1:HANDLE
QUERY = qh
TITLE = " "
X = 2
Y = 2
WIDTH = 130
DOWN = 12
VISIBLE = TRUE
SENSITIVE = TRUE
READ-ONLY = NO
COLUMN-SCROLLING = TRUE
SEPARATORS = YES.
END.
ON CHOOSE OF AddCols DO: /* LABEL "Add Columns" */
ASSIGN query-criteria.
qh:QUERY-PREPARE(query-criteria).
qh:QUERY-OPEN.
Browse-Hndl:ADD-LIKE-COLUMN(bh:BUFFER-FIELD(1),1).
Browse-Hndl:ADD-LIKE-COLUMN(bh:BUFFER-FIELD(3),2).
Browse-Hndl:ADD-LIKE-COLUMN(bh:BUFFER-FIELD("city"),3).
CASE query-criteria:
WHEN "for each customer NO-LOCK" THEN
DO:
Browse-Hndl:ADD-LIKE-COLUMN(bh:BUFFER-FIELD("state")).
Browse-Hndl:ADD-LIKE-COLUMN(bh:BUFFER-FIELD("country")).
Browse-Hndl:ADD-LIKE-COLUMN(bh:BUFFER-FIELD("postal-code")).
Browse-Hndl:TITLE = "All Customers".
END.
WHEN "FOR EACH customer WHERE customer.country EQ USA NO-LOCK BY
customer.state " THEN
DO:
Browse-Hndl:ADD-LIKE-COLUMN(bh:BUFFER-FIELD("state")).
Browse-Hndl:TITLE = "All US Customers".
END.
WHEN "FOR EACH customer WHERE customer.country NE USA NO-LOCK BY
customer.country " THEN
DO:
Browse-Hndl:ADD-LIKE-COLUMN(bh:BUFFER-FIELD("country")).
Browse-Hndl:TITLE = "All non-US Customers".
END.
END CASE.
p-fnlqry.p (2 of 3)
2025
20.4 Creating and Using a Dynamic Browse
The design and programming of the static browse was described in Chapter 10, Using the
Browse Widget. This section describes programming and using a dynamic browse, that is, a
browse whose elements are resolved at runtime.
The dynamic browse can be either a read-only or an updateable browse. If the dynamic browse
is updateable, it is a NOASSIGN browse and you must do all database updating manually. The
dynamic browse can be used with either a static or a dynamic query.
bufFieldHandle = bh:BUFFER-FIELD("balance").
Browse-Hndl:ADD-LIKE-COLUMN(bufFieldHandle).
AddCols:SENSITIVE = FALSE.
query-criteria:SENSITIVE = FALSE.
make:SENSITIVE = FALSE.
END.
ON CHOOSE OF btn-delete /* LABEL "DeleteDynBrowse". */
DO:
DELETE WIDGET Browse-Hndl.
AddCols:SENSITIVE = TRUE.
query-criteria:SENSITIVE = TRUE.
make:SENSITIVE = TRUE.
END.
ON CHOOSE OF btn-quit
DO:
APPLY "window-close" TO CURRENT-WINDOW.
END.
p-fnlqry.p (3 of 3)
2026
20.4.1 Creating the Dynamic Browse
A dynamic browse is one you create at runtime using the BROWSE option of the CREATE
Widget statement. Within the CREATE BROWSE statement, you can assign attributes to the
browse and specify its associated query.
The following code fragment depicts creating a dynamic browse:
DEFINE VARIABLE br1 AS HANDLE.
. . .
/* define query and define frame here */
CREATE BROWSE br1
ASSIGN FRAME = FRAME f1:HANDLE
X = 2
Y = 2
WIDTH = 80
DOWN = 10
QUERY = QUERY q1:HANDLE
TITLE = "Dynamic Browse"
SENSITIVE = TRUE
VISIBLE = TRUE
READ-ONLY = FALSE
SEPARATORS = TRUE.
. . .
2027
20.4.2 Creating Dynamic Browse Columns
The dynamic browse that you create with the CREATE BROWSE statement is an empty
browse. You must add the browse columns using the following methods:
ADDCOLUMNSFROM( )
ADDLIKECOLUMN( )
ADDCALCCOLUMN( )
ADDCOLUMNSFROM( ) Method
The ADDCOLUMNSFROM( ) method creates a browse column for every field in the
specified table or buffer except for any fields specified in an except-list. The specified table or
buffer must be in the associated query. Use this method when you want the browse to contain
all or most of the fields in a table or buffer.
The following program creates a browse which displays all the fields in the customer table
except for terms and comments:
p-dybrw1.p
DEFINE VARIABLE b1 AS HANDLE.
DEFINE QUERY q1 FOR customer EXCEPT (terms comments) SCROLLING.
OPEN QUERY q1 FOR EACH customer WHERE customer.cust-num < 10.
DEFINE FRAME f1
WITH SIZE 82 BY 29.
CREATE BROWSE b1
ASSIGN
FRAME = FRAME f1:HANDLE
X = 2
Y = 2
WIDTH = 80
DOWN = 10
TITLE = "Dynamic Browse with static query"
SENSITIVE = TRUE
VISIBLE = TRUE
READ-ONLY = FALSE
SEPARATORS = TRUE.
b1:ADD-COLUMNS-FROM("customer","terms,comments").
2028
ADDLIKECOLUMN( ) Method
The ADDLIKECOLUMN method creates a single browse column from the specified field
name or buffer field handle. You can also define the position of this column within the browse.
The specified field must be a field in one of the buffers of the associated query. Use this method
when you want the browse to contain only a few fields in a table or buffer.
The following program creates a browse containing only four fields from the customer table:
For other examples of the ADDLIKECOLUMN( ) method, see the program, p-fnlqry.p, in
section Dynamic Query Code Example.
p-dybrw2.p
DEFINE QUERY q1 FOR customer
FIELDS (cust-num name phone contact) SCROLLING.
DEFINE FRAME f1
WITH SIZE 82 BY 29.
CREATE BROWSE b1
ASSIGN
X = 2
Y = 2
WIDTH = 80
DOWN = 10
SENSITIVE = TRUE
VISIBLE = TRUE
READ-ONLY = FALSE
SEPARATORS = TRUE.
b1:ADD-LIKE-COLUMN("customer.cust-num").
b1:ADD-LIKE-COLUMN("customer.name").
b1:ADD-LIKE-COLUMN("customer.phone").
b1:ADD-LIKE-COLUMN("customer.contact").
2029
ADDCALCCOLUMN( ) Method
The ADDCALCCOLUMN( ) method creates a single browse column with the specified
properties rather than from a table or buffer field. This is typically used as a placeholder column
for a calculated value.
The following program creates a browse containing four fields from the customer table plus a
fifth field containing the calculated current credit limit:
p-dybrw3.p
DEFINE VARIABLE calch AS HANDLE.
DEFINE QUERY q1 FOR customer
FIELDS (cust-num name phone contact credit-limit balance) SCROLLING.
DEFINE FRAME f1
WITH SIZE 78 BY 18.
CREATE BROWSE b1
ASSIGN
X = 2
Y = 2
WIDTH = 76
DOWN = 15
SENSITIVE = TRUE
VISIBLE = FALSE
READ-ONLY = FALSE
SEPARATORS = TRUE.
ON ROW-DISPLAY OF b1 DO:
IF VALID-HANDLE(calch) THEN
calch:SCREEN-VALUE=STRING(customer.credit-limit - customer.balance).
END.
b1:ADD-LIKE-COLUMN("customer.cust-num").
b1:ADD-LIKE-COLUMN("customer.name").
b1:ADD-LIKE-COLUMN("customer.phone").
b1:ADD-LIKE-COLUMN("customer.contact").
calch=b1:ADD-CALC-COLUMN("DECIMAL","->,>>>,>>9.99","0","CurrentLimit").
b1:VISIBLE = TRUE.
2030
Notes on Dynamic Browse Columns
You cannot specify the CANFIND function in the validation expression for a dynamic
browse-column. Since Progress compiles validation expressions at runtime for dynamic
browse-columns, CANFIND produces an error and the validation will not run for that
column. You can still use the CANFIND function for a static-browse column.
You can set the VISIBLE attribute for a browse-column as well as a browse.
You can change the SCREENVALUE attribute for a browse-column within the browses
ROWDISPLAY trigger as well as outside the trigger.
You must define the ROWDISPLAY trigger where the value of the calculated column is
set prior to using the ADDCALCCOLUMN( ) method so that the trigger is already set
before the column is added. This is to ensure that the initial viewport of the calculated
column is populated.
20.4.3 Dynamic Enhancements to the Static Browse
You can now dynamically create some or all of the columns for a static browse by using the
ADDCOLUMNSFROM( ), ADDLIKECOLUMN( ) and ADDCALCCOLUMN( )
methods. If you use the ADDCOLUMNSFROM( ) or ADDLIKECOLUMNS( ) methods
on a static browse, the browse becomes a NOASSIGN browse and you will have to manage
the database updates manually. See Chapter 10, Using the Browse Widget, for more
information on the static browse.
In addition, you can now change the query of a static browse even if the underlying fields are
not the same as those of the original query. However, if the new underlying fields are not the
same as the original, all browse columns will be removed and you will have to specify new
columns using the new ADDCOLUMNSFROM( ), ADDLIKECOLUMN( ) and
ADDCALCCOLUMN( ) methods. If the QUERY attribute is set to the UNKNOWN value
(?), all browsecolumns are removed.
2031
The following code example depicts an updateable static browse with all dynamic columns:
p-stbrw1.p
DEFINE BUTTON btn-quit LABEL "&Quit" AUTO-ENDKEY.
DEFINE VARIABLE ColHandle AS HANDLE.
DEFINE BROWSE StaticBrowse
QUERY q1
WITH TITLE "A Static Browse with Dynamic Columns"
MULTIPLE
SEPARATORS
SIZE 104 BY 10.
DEFINE FRAME f1
StaticBrowse SKIP(2)
btn-quit AT ROW 13 COLUMN 3
WITH THREE-D SIZE 105 BY 15 .
CURRENT-WINDOW:ROW = 1.
CURRENT-WINDOW:TITLE = "A Static Browse with All Dynamic Columns".
CURRENT-WINDOW:KEEP-FRAME-Z-ORDER = TRUE.
StaticBrowse:READ-ONLY = FALSE.
StaticBrowse:ROW-MARKERS = TRUE.
StaticBrowse:ADD-LIKE-COLUMN("customer.state").
StaticBrowse:ADD-LIKE-COLUMN("customer.postal-code").
StaticBrowse:ADD-LIKE-COLUMN("customer.address").
StaticBrowse:ADD-LIKE-COLUMN("customer.address2").
StaticBrowse:ADD-LIKE-COLUMN("customer.terms").
REPEAT i=2 TO StaticBrowse:NUM-COLUMNS:
ColHandle = StaticBrowse:GET-BROWSE-COLUMN(i).
ColHandle:READ-ONLY = FALSE.
END.
ON CHOOSE OF btn-quit DO:
APPLY "window-close" TO CURRENT-WINDOW.
END.
2032
21
Windows
When you start a session, Progress automatically creates a static window for the session. You
can access this static window by using the DEFAULTWINDOW system handle. This static
window is also your initial current window, which you can access and reset using the
CURRENTWINDOW system handle.
The current window is the default session window for parenting frames, dialog boxes, and
messages. Depending on your user interface, you can create one or more dynamic windows,
using each one in turn as the current window. You can also specify a default window for the
current external procedure by assigning the widget handle of any window to the
CURRENTWINDOW attribute of the THISPROCEDURE handle. The setting of this
attribute overrides the setting of the CURRENTWINDOW handle for the context of the
current external procedure only. It has no effect on other external procedures in the session.
In a character interface, you can use only the static window for the entire session. In a graphical
interface, you can create multiple windows dynamically within an application and create parent
and child relationships between them. You can also change the appearance of any window,
including (with some restrictions) the static window.
Multiple window pros and cons
Window attributes and methods
Window events
Creating and managing windows
Window-based applications
212
21.1 Multiple-window Pros and Cons
There are several reasons why you might want to use more than one window in an application:
Maximizing use of screen space The simplest reason for using an additional window
is to get more screen space. In some cases, you can avoid using a new window by enlarging
the existing window or overlaying frames.
Grouping functionality You can use multiple windows to group widgets that are
logically related. Each window can have its own menu bar with submenus related to those
specific widgets. You can also group related windows into window families, hierarchies
of parent and child windows.
Providing greater user control By placing information in multiple windows, you can
provide greater access to application functions. This also gives the user the ability to move
the windows (functionality) around the screen. The user can choose to put one window in
front of another or to minimize a window that is not currently needed.
Displaying multiple copies of the same frame You can only display a specific frame
once in a window. This can be a limitation, for example, if you want to show all the order
items associated with an order. You can define the frame once (in a subprocedure or
trigger) and view it in several windows simultaneously, populating each copy with
different data.
NOTE: You cannot enable fields for update in more than one copy of the same
frameeven if the copies are in different windows. If you want to be able to
update multiple copies of the frame, you must create separate frames for each
window.
There are several disadvantages to using multiple windows in an application:
Window management You must manage the windows yourself. Specifically, you
must ensure that windows are deleted when appropriate, usually when the controlling
procedure goes out of scope.
Widget access In a multi-window interface, one window may become concealed
behind another or inadvertently minimized, losing immediate access to application
widgets. This may cause confusion for the user.
Windows
213
Lack of interface portability Since Progress supports only a single window in
character interfaces, you cannot directly port a multi-window application to a character
interface.
Transaction management Even though you may have several windows on the screen,
you can only have one transaction active at a time. Undoing work in one window might
cause work in another window to be undone also.
21.1.1 Windows Versus Dialog Boxes
A dialog box is a type of frame that shares some of the visual characteristics of a separate
window. For example, the user can move a dialog box around the display outside its parent
window. However, a dialog box is always modal. That means that when the dialog box is
displayed, the user must react to that dialog box and cannot work in any other window until the
dialog box has been dismissed.
Windows are non-modal by default, and are not easily made modal. Thus, the user can move
freely from one window to another to enter input. If you want to enforce modality, use a dialog
box. For more information on dialog boxes, see Chapter 25, Interface Design.
21.1.2 Multiple Windows and Transactions
When an application uses multiple windows, the user may tend to assume that actions in one
window are totally independent of actions in another window. However, regardless of how
many windows are on the screen, only one transaction is active at any time. This means that you
cannot undo or commit work in one window without undoing or committing the work pending
in all other windows. You must design your application so that transaction scoping is clear and
intuitive to the user.
In multi-window applications, it simplifies transaction management if you can ensure that a
transaction started in one window is committed before the user gives focus to another window.
Thus, multi-window applications work more naturally with atomic transactions (those opened
and committed by a single user action or dialog box). However, your application must
ultimately determine your transaction management requirements.
214
21.2 Window Attributes and Methods
You can set attributes for both the static window created by Progress and windows that you
create. You can, for example:
Specify the window title (TITLE attribute).
Set the normal, minimum, and maximum sizes of the window. You can do this in either of
two units:
In pixels (HEIGHTPIXELS, WIDTHPIXELS, MINHEIGHTPIXELS,
MINWIDTHPIXELS, MAXHEIGHTPIXELS, MAXWIDTHPIXELS
attributes).
In character units (HEIGHTROWSCHARS, WIDTHCOLUMNSCHARS,
MINHEIGHTCHARS, MINWIDTHCHARS, MAXHEIGHTCHARS,
MAXWIDTHCHARS attributes).
Specify the maximum display area within the window (VIRTUALHEIGHTCHARS,
VIRTUALWIDTHCHARS, VIRTUALHEIGHTPIXELS,
VIRTUALWIDTHPIXELS).
Allow or prevent the user resizing the window by setting the RESIZE attribute.
Specify the presence or absence of a window component or its appearance, such as
message area (MESSAGEAREA, MESSAGEAREAFONT), status area
(STATUSAREA, STATUSAREAFONT), or scroll bars (SCROLLBARS).
Change the state (minimized, maximized, restored) of a window within a program
(WINDOWSTATE attribute).
Associate a menu bar or pop-up menu with the window (MENUBAR or POPUPMENU
attribute).
Find all frames within the window (FIRSTCHILD or LASTCHILD attribute of the
window; NEXTSIBLING or PREVSIBLING attribute of frames).
Set up parent and child relationships between windows (PARENT attribute).
Windows
215
There are also several methods available on a window widget. The most common of these
methods that apply to windows are the LOADICON() and LOADSMALLICON() methods.
These methods allow you to associate icons with windows. The icon displays to reference a
window in one of its states such as minimized or maximized. For example, using the
LOADICON() method allows you to specify an icon to display in the title bar of a window
(maximized), in the task bar (minimized), and when selecting a program using ALTTAB. The
LOAD-SMALLICON() method allows you to specify an icon to display in the title bar of a
window and in the task bar only. The value you assign with either the LOADICON() or the
LOADSMALLICON() methods must be the name of an icon (.ico) file. Both of these
methods accommodate icons formatted as small size (16x16), regular size (32x32), or both.
For more information on these and other window attributes and methods, see the Progress
Language Reference.
216
The following procedure uses attributes of the static window to make the window wide and
short and to change its title:
p-wina.p
OPEN QUERY custq FOR EACH customer.
FORM
custb
WITH FRAME x.
FORM
customer
WITH FRAME y SIDE-LABELS COLUMN 40 ROW 3 WIDTH 75.
ASSIGN DEFAULT-WINDOW:VIRTUAL-WIDTH-CHARS = 120
DEFAULT-WINDOW:VIRTUAL-HEIGHT-CHARS = 15
DEFAULT-WINDOW:WIDTH-CHARS = 120
DEFAULT-WINDOW:HEIGHT-CHARS = 15
DEFAULT-WINDOW:TITLE = "Customer Browser".
ON ITERATION-CHANGED OF BROWSE custb
DO:
DISPLAY customer WITH FRAME y.
END.
ON WINDOW-CLOSE OF CURRENT-WINDOW
QUIT.
ENABLE custb WITH FRAME x.

APPLY "ITERATION-CHANGED" TO BROWSE custb.
ENABLE ALL WITH FRAME y.
Windows
217
When you run this code, the following window appears:
218
21.3 Window Events
In addition to several standard events, windows respond to unique events of their own.
Several events indicate window state changes, including WINDOWMINIMIZED,
WINDOWMAXIMIZED, and WINDOWRESTORED.
The WINDOWRESIZED event occurs any time a keyboard or mouse action starts to change
the windows vertical or horizontal dimensions. Note that the window RESIZE attribute must
be set to TRUE for this event to occur.
The WINDOWCLOSE event occurs when the user tries to close a window. By default,
Progress takes no action when the WINDOWCLOSE event occursit does not close the
window. If you want your application to react to the WINDOWCLOSE event, you must code
a trigger for it or reference it in a WAITFOR statement. In fact, this is a typical termination
condition.
For more information on window events, see the Progress Language Reference.
21.4 Creating and Managing Windows
You can create a new window dynamically with the CREATE Widget statement.
This is the syntax for creating a window:
NOTE: Character interfaces support only a single window. If you attempt to create additional
windows, Progress raises the ERROR condition.
You must define handle as a WIDGETHANDLE variable, field, or parameter before creating
the window. Likewise, you must create the widget pool specified by poolname using a
CREATE WIDGETPOOL statement before you reference the widget pool in the CREATE
WINDOW statement. In some applications, you might prefer to use unnamed widget pools to
contain your windows. This is especially useful with windows created by persistent procedures,
where a single unnamed widget pool can encompass the entire dynamic context of the
procedure.
SYNTAX
CREATE WINDOW handle
[ IN WIDGET-POOL pool-name ]
[ ASSIGN attribute = value [ attribute = value ] ... ]
{ [ trigger-phrase ] }
Windows
219
One of the advantages of creating your own window is the ability to specify all of its attributes.
The ASSIGN option allows you to specify any window attribute you want, including those that
must be specified before realization. These include sizing and component attributes, such as
RESIZE and MESSAGEAREA.
You can specify user interface triggers for a window using either the triggerphrase or the ON
statement. The triggerphrase offers the convenience of a single window context, while the ON
statement offers the flexibility to define your triggers conditionally, after the window is created.
For more information on handles, attributes, and user interface triggers, see Chapter 16,
Widgets and Handles. For more information on widget pools, see Chapter 20, Using
Dynamic Widgets.
21.4.1 Creating Window Families
By default, when you create a window, Progress parents that window transparently to the
window system. In this way, windows are siblings of each other. You must manage these
windows individually.
You can also parent a window (child window) to another window (parent window) by setting
the child windows PARENT attribute to the widget handle of the parent window. Windows that
are parented by a window, which in turn is parented by the window system, form a window
family. The window parented by the window system is the root window of the window family.
Windows parented by any child window, in turn, form a child window family. A child window
can only be parented by one window at a time.
2110
Window Families vs. Individual Windows
Each window in a window family, by itself, functions much the same as an individual window.
That is, you can individually move, resize, and interact with a member of a window family like
an individual window.
However, window families share a number of additional properties that make them convenient
for both applications and users to manage:
Coordinated viewing and hiding When you view any member of a window family,
the whole window family is viewed, unless the HIDDEN attribute is TRUE for at least one
other member. If HIDDEN is TRUE for a parent or ancestor window, no windows in the
window family are viewed, however any HIDDEN attribute setting for the explicitly
viewed window is set to FALSE. If HIDDEN is TRUE for a descendant window, all
windows in the family are viewed except the hidden descendant window and all of its
descendants. When you hide a member of a window family (set VISIBLE to FALSE), that
window and all of its descendant windows are hidden (VISIBLE set to FALSE), but none
of their HIDDEN attributes are affected.
Coordinated minimizing and restoring When you minimize (iconify) a window, all
of its descendants disappear from view, unless they are already minimized. Any
minimized descendants remain minimized and can be restored individually. When you
restore a parent window, any of its hidden descendants are redisplayed. Note that when
you hide a window (set VISIBLE to FALSE), any minimized descendants are hidden also,
and when you redisplay that window, its minimized descendants reappear minimized.
Coordinated close events If a parent window receives a WINDOWCLOSE event, it
propagates a PARENTWINDOWCLOSE event to all of its descendant windows.
However, any action on these events is trigger-dependant. The WINDOWCLOSE does
not propagate any events upward to ancestor windows.
For more information on window family properties, see the WINDOW Widget, HIDDEN
Attribute, and VISIBLE Attribute reference entries in the Progress Language Reference.
Windows
2111
Window Family Example
The following procedure creates a window family with three windowsa parent, child, and
grandchild window. By choosing the buttons in the default window (Control Panel), you can
visualize most of the properties described in the previous list.
p-wow1.p (1 of 2)
DEFINE VARIABLE whandle1 AS HANDLE.
DEFINE BUTTON bviewp LABEL "VIEW".
DEFINE BUTTON bviewc LABEL "VIEW".
DEFINE BUTTON bviewgc LABEL "VIEW".
DEFINE BUTTON bhidep LABEL "HIDE".
DEFINE BUTTON bhidec LABEL "HIDE".
DEFINE BUTTON bhidegc LABEL "HIDE".
DEFINE BUTTON bhiddp LABEL "HIDDEN".
DEFINE BUTTON bhiddc LABEL "HIDDEN".
DEFINE BUTTON bhiddgc LABEL "HIDDEN".
DEFINE FRAME alpha SKIP
"Parent" AT 11 "Child" AT 37 "Grand Child" AT 64 SKIP
bviewp AT 11 bviewc AT 37 bviewgc AT 64 SKIP(.5)
bhidep AT 11 bhidec AT 37 bhidegc AT 64 SKIP(.5)
bhiddp AT 11 bhiddc AT 37 bhiddgc AT 64
WITH SIZE 80 BY 6.
CREATE WINDOW whandle1
ASSIGN TITLE = "Parent Window"
HEIGHT-CHARS = 5
WIDTH-CHARS = 27
PARENT = CURRENT-WINDOW.
ASSIGN TITLE = "Child Window"
HEIGHT-CHARS = 5
WIDTH-CHARS = 27
PARENT = whandle1.
ASSIGN TITLE = "Grand Child Window"
HEIGHT-CHARS = 5
WIDTH-CHARS = 27
PARENT = whandle2.

ON CHOOSE OF bviewp DO: /* View Parent */
VIEW whandle1.
RUN win-status IN THIS-PROCEDURE.
END.
2112
ON CHOOSE OF bhidep DO: /* Hide Parent */
HIDE whandle1.
END.
ON CHOOSE OF bhiddp DO: /* Hidden Parent */
whandle1:HIDDEN = TRUE.
END.
ON CHOOSE OF bviewc DO: /* View Child */
VIEW whandle2.
END.
ON CHOOSE OF bhidec DO: /* Hide Child */
HIDE whandle2.
END.
ON CHOOSE OF bhiddc DO: /* Hidden Child */
END.
ON CHOOSE OF bviewgc DO: /* View Grand Child */
VIEW whandle3.
END.
ON CHOOSE OF bhidegc DO: /* Hide Grand Child */
HIDE whandle3.
END.
ON CHOOSE OF bhiddgc DO: /* Hidden Grand Child */
END.
CURRENT-WINDOW:TITLE = "Control Panel".
ENABLE ALL IN WINDOW CURRENT-WINDOW WITH FRAME alpha.

PROCEDURE win-status:
MESSAGE "Parent HIDDEN:" whandle1:HIDDEN
"/ Parent VISIBLE:" whandle1:VISIBLE
"/ Child HIDDEN:" whandle2:HIDDEN
"/ Child VISIBLE:" whandle2:VISIBLE.
MESSAGE "Grand Child HIDDEN:" whandle3:HIDDEN
"/ Grand Child VISIBLE:" whandle3:VISIBLE.
END.
p-wow1.p (2 of 2)
Windows
2113
Figure 211 shows the Control Panel window and the example window family.
Figure 211: Window Family
Combine the VIEW, HIDE, and HIDDEN button events with the WINDOWMINIMIZE and
WINDOWRESTORE events using the window controls to see how window hiding and
viewing work together with window minimizing and restoring.
For an example that uses a window family in a database application, see the Persistent
Multi-window Management section.
2114
21.5 Window-based Applications
Progress supports three types of interactive application:
Single-window Every interactive Progress application uses at least a single window.
Typically, you use the static window provided by Progress, although you can create your
own, instead, if you want to change any attributes set prior to realization. You can change
any attributes of the static window that can be set after realization.
Multi-window with non-persistent management You can create additional windows
for viewing or updating specific information using non-persistent procedures. In
non-persistent procedures, you can use multiple windows to group related information or
just to provide greater flexibility and more screen space. In a non-persistent environment,
you must manage each window explicitly throughout the application. Also, you cannot
easily manage multiple windows as copies or iterations of a single window. No matter how
similar the definition of each window is to another, each window requires separate
management code that must be integrated with the rest at every point in the application.
Multi-window with persistent management You can also create additional windows
using persistent procedures. This technique allows you to have more than one copy of a
like-defined window on the screen simultaneously, managed by the same application
code. Managing multiple windows with persistent procedures affords far greater
flexibility than using only non-persistent procedures.
Typically, a persistent procedure creates the window it controls when it executes. This
window then remains on screen and available for input after the procedure returns from
execution. Unlike windows created by non-persistent procedures, windows created in
persistent procedures require little or no management by the main line of your application.
The essential management code for each window is contained in the persistent procedure
that created it. Also, each time you execute a persistent procedure, it can create a
completely new window that is a copy of others created by the same procedure. Each copy
is managed by the same application code in its own procedure context. If you so design,
your main-line application can interact with the windows of these persistent procedures
through standard procedure triggers or internal procedures provided to the application by
the persistent procedures.
NOTE: You can also create multiple windows using persistent triggers in a
non-persistent procedure, but this is a less robust technique with more
complicated window management requirements.
As the single-window application is the default application style used throughout this manual,
the following sections describe the two basic techniques of managing multi-window
applications: non-persistent and persistent.
Windows
2115
21.5.1 Non-persistent Multi-window Management
The following procedure creates a concurrent window and stores its handle in the newwin
variable. It then preforms I/O to both the new window and the static window:
p-win1.p
DEFINE VARIABLE new-win AS WIDGET-HANDLE.
FORM
customer

FORM
salesrep
CREATE WINDOW new-win
ASSIGN TITLE = "Sales Representative".
ASSIGN DEFAULT-WINDOW:TITLE = "Customer".
VIEW new-win.
MESSAGE "This is the default window.".
MESSAGE "This is the newly created window." IN WINDOW new-win.
FOR EACH customer, salesrep OF customer ON ERROR UNDO, LEAVE
ON ENDKEY UNDO, LEAVE ON STOP UNDO, LEAVE:
DISPLAY customer WITH FRAME cust-frame.
ENABLE ALL WITH FRAME cust-frame.

CURRENT-WINDOW = new-win.
ENABLE ALL WITH FRAME rep-frame.
CURRENT-WINDOW = DEFAULT-WINDOW.

WAIT-FOR GO OF FRAME cust-frame, FRAME rep-frame.

ASSIGN customer.
ASSIGN salesrep.
END.
DELETE WIDGET new-win.
2116
The p-win1.p procedure demonstrates two ways to direct I/O to a specific window: the IN
WINDOW option and the CURRENTWINDOW handle. Because the first MESSAGE
statement does not reference a window, it writes to the current window, which is initially the
static window for the session. The second message uses the IN WINDOW option to direct the
output to the newly created window. Within the FOR EACH group, the first DISPLAY
statement writes to the static window. Before the second DISPLAY statement, the
CURRENTWINDOW value is reset to the new window. Therefore, that DISPLAY statement
writes to the new window. The value of CURRENTWINDOW is then reset to the static
window. Note that the DISPLAY statements must use separate frames, because a frame can
only appear in one window at a time.
21.5.2 Persistent Multi-window Management
An application that uses persistent multi-window management generally provides its basic
application options in the default application window. These options then open one or more
windows under persistent procedure control to provide functionality in addition to the default
application window. All of these windows, while visible, remain available to the user in
non-modal fashion. You can also provide modal capabilities anywhere in the non-modal
interface using alert boxes and dialog boxes.
Creating Windows in Persistent Procedures
In general, you create and manage each persistent window using a persistent procedure. Each
time you run a procedure persistently, it instantiates (creates) a context for itself. This context
can include any windows that you create during instantiation. However, each persistent
procedure can maintain its own current window by setting the CURRENTWINDOW attribute
of the THISPROCEDURE handle. This attribute overrides (but does not change) the setting of
the CURRENTWINDOW handle. If set to the widget handle of a valid window, all frames and
dialog boxes defined in the procedure parent, by default, to the window specified by this
attribute. Thus, a persistent procedure instance usually manages a single window in the
multi-window application. For more information on procedure handles and persistent
procedures, see Chapter 3, Block Properties.
Managing Windows in Persistent Procedures
It is also often helpful to create a separate dynamic widget pool for the window you create in
the persistent procedure. Usually, you want the window to exist for the life of the persistent
procedure that manages it. The simplest way to guarantee this is by creating a single unnamed
widget pool for the procedure. When you delete a persistent procedure that maintains its own
widget pool, its persistent window is automatically deleted also. For more information on
dynamic widget pools, see Chapter 20, Using Dynamic Widgets.
Windows
2117
Example Persistent Multi-window Management
The following three procedures, p-perwn1.p, p-perwn2.p, and p-perwn3.p implement a small
application for updating customer orders in the sports database using multiple windows. The
main procedure (p-perwn1.p) displays a browse of the customer table in the default application
window. You can browse the order table for a selected customer by choosing the bOpenorders
button. This creates a persistent procedure (p-perwn2.p) that opens a child window for the order
browse (p-perwn1.p (1)):
p-perwn1.p (1 of 2)
DEFINE BROWSE custb QUERY custq
DISPLAY name cust-num balance credit-limit phone sales-rep
WITH 10 DOWN.
DEFINE BUTTON bExit LABEL "Exit".
DEFINE BUTTON bOpenorders LABEL "Open Orders".
DEFINE VARIABLE lcust-redundant AS LOGICAL.
custb SKIP bExit bOpenorders
WITH SIZE-CHARS 96.5 by 11.

ON CHOOSE OF bExit IN FRAME CustFrame DO:
RUN exit-proc.
END.
ON CHOOSE OF bOpenorders IN FRAME CustFrame DO:
IF custb:NUM-SELECTED-ROWS >= 1 THEN DO:
RUN check-redundant(OUTPUT lcust-redundant).
IF NOT lcust-redundant THEN DO:
MESSAGE "Opening orders for" customer.name + ".".
(1) RUN p-perwn2.p PERSISTENT
(BUFFER customer, INPUT whand:TITLE,
INPUT whand) NO-ERROR.
END.
ELSE DO:
BELL.
MESSAGE "Orders already open for" customer.name + ".".
END.
END.
ELSE DO:
BELL.
MESSAGE "Select a customer to open orders ...".
END.
END.
2118
(2) CREATE WINDOW whand
ASSIGN
TITLE = "Customer Order Maintenance"
SCROLL-BARS = FALSE
RESIZE = FALSE
HEIGHT-CHARS = FRAME CustFrame:HEIGHT-CHARS
WIDTH-CHARS = FRAME CustFrame:WIDTH-CHARS.
CURRENT-WINDOW = whand.
OPEN QUERY custq PRESELECT EACH customer BY name.
WAIT-FOR CHOOSE OF bExit IN FRAME CustFrame.
PROCEDURE exit-proc:
DEFINE VARIABLE phand AS HANDLE.
DEFINE VARIABLE nhand AS HANDLE.
MESSAGE "Exiting application ...".
(3) phand = SESSION:FIRST-PROCEDURE.
DO WHILE VALID-HANDLE(phand):
nhand = phand:NEXT-SIBLING.
IF LOOKUP(whand:TITLE, phand:PRIVATE-DATA) > 0 THEN
RUN destroy-query IN phand NO-ERROR.
phand = nhand.
END.
END PROCEDURE.
PROCEDURE check-redundant:
DEFINE OUTPUT PARAMETER lcust-redundant AS LOGICAL INITIAL FALSE.

IF LOOKUP(whand:TITLE, phand:PRIVATE-DATA) > 0 AND
LOOKUP(customer.name, phand:PRIVATE-DATA) > 0 THEN DO:
lcust-redundant = TRUE.
RETURN.
END.
phand = nhand.
END.
END PROCEDURE.
p-perwn1.p (2 of 2)
Windows
2119
You can repeatedly select another customer and choose the bOpenorders button to browse
orders for as many customers as you want. The customer and order browses displayed for every
customer all remain available to the user for input simultaneously.
This application makes ample use of procedure and SESSION handle attributes to help manage
the persistent windows of the application. The main procedure uses them in two ways:
To delete all persistent procedures (and their windows) when you terminate the application
To identify whether an order window has already been created for a selected customer so
that only one order browse is enabled for a customer at a time
When you terminate the application by choosing the bExit button, p-perwn1.p calls a local
internal procedure, exitproc. After locating the first persistent procedure instance, exitproc
loops through all persistent procedures in the session and deletes each one created by the
application as specified by the PRIVATEDATA procedure handle attribute (p-perwn1.p (3)).
Note that exitproc deletes each persistent procedure by calling the destroyquery procedure
owned by the persistent procedure. This ensures that each persistent procedure manages its own
resource clean-up and deletion.
When you attempt to open the order browse for a customer, p-perwn1.p also checks to see if
there is already an order browse open for that customer. It does this by looking for a persistent
procedure with the customer name as part of its private data (p-perwn1.p (4)).
Note also that p-perwn1.p creates its own default application window instead of using the static
window (p-perwn1.p (2)). This allows the setting of the SCROLLBARS and RESIZE window
attributes.
The persistent procedure, p-perwn2.p, displays a browse of all orders for the selected customer.
Like the customer browse, you can repeatedly select orders and choose the bOpenlines button
(which runs p-perwn3.p) to browse order lines in a child window of a selected order for as many
orders as you want (p-perwn2.p (1)). In p-perwn2.p, you can also update each order by
choosing the bUpdate button and close all orders for a customer by choosing the bClose button.
Note that as persistent procedures, both p-perwn2.p and p-perwn3.p are written to be run
non-persistently for testing or other application purposes. This is accomplished by making some
of the code conditionally executable based on the value of the PERSISTENT attribute of the
THISPROCEDURE system handle. For example, the bClose button in p-perwn2.p runs the
destroyquery procedure or just exits p-perwn2.p, depending on how it is run (p-perwn2.p (4)).
You can devise many variations on this approach. One possible variation includes using the
preprocessor to conditionally compile the PERSISTENT attribute tests based on whether you
are compiling for a development or production environment.
2120
Each persistent procedure easily maintains the current window that it creates by setting the
CURRENTWINDOW attribute of the THISPROCEDURE handle (p-perwn2.p (3) and
p-perwn3.p (2)). Thus, there is no need to set and reset the CURRENTWINDOW handle:
p-perwn2.p (1 of 5)
DEFINE PARAMETER BUFFER custbuf FOR customer.
DEFINE INPUT PARAMETER appdata AS CHARACTER.
DEFINE INPUT PARAMETER wparent AS WIDGET-HANDLE.
DEFINE QUERY orderq FOR order.
DEFINE BROWSE orderb QUERY orderq
DISPLAY
order.order-num order.order-date
order.ship-date order.promise-date order.carrier
WITH 5 DOWN.
DEFINE BUTTON bClose LABEL "Close Orders".
DEFINE BUTTON bOpenlines LABEL "Open Order Lines".
DEFINE BUTTON bUpdate LABEL "Update Order".
DEFINE VARIABLE lorder-redundant AS LOGICAL.
DEFINE FRAME OrderFrame SKIP(.5)
custbuf.name COLON 11 VIEW-AS TEXT SKIP
custbuf.cust-num COLON 11 VIEW-AS TEXT SKIP(.5)
orderb SKIP
bClose bOpenlines bUpdate
WITH SIDE-LABELS SIZE-CHARS 65.8 by 9.

ON CHOOSE OF bOpenlines IN FRAME OrderFrame DO:
IF orderb:NUM-SELECTED-ROWS >= 1 THEN DO:
RUN check-redundant(OUTPUT lorder-redundant).
IF NOT lorder-redundant THEN DO:
MESSAGE "Opening order lines for order"
STRING(order.order-num) + ".".
(1) RUN p-perwn3.p PERSISTENT
(BUFFER order, INPUT THIS-PROCEDURE:PRIVATE-DATA,
INPUT whand) NO-ERROR.
END.
ELSE DO:
BELL.
MESSAGE "Order lines already open for order"
STRING(order.order-num) + ".".
END.
END.
ELSE DO:
BELL.
MESSAGE "Select an order to open order lines ...".
END.
END.
Windows
2121
ON CHOOSE OF bUpdate IN FRAME OrderFrame DO:
IF orderb:NUM-SELECTED-ROWS >= 1 THEN DO:
RUN update-order.
END.
ELSE DO:
BELL.
MESSAGE "Select an order to update ...".
END.
END.
(2) IF THIS-PROCEDURE:PERSISTENT THEN DO:
THIS-PROCEDURE:PRIVATE-DATA = appdata + "," + custbuf.name.
CREATE WIDGET-POOL.
END.
ASSIGN
TITLE = "Orders for Customer ..."
PARENT = wparent
RESIZE = FALSE
SCROLL-BARS = FALSE
HEIGHT-CHARS = FRAME OrderFrame:HEIGHT-CHARS
WIDTH-CHARS = FRAME OrderFrame:WIDTH-CHARS.

THIS-PROCEDURE:CURRENT-WINDOW = whand.
OPEN QUERY orderq PRESELECT EACH order
WHERE order.cust-num = custbuf.cust-num BY order-num.
DISPLAY custbuf.cust-num custbuf.name WITH FRAME OrderFrame.
ENABLE ALL WITH FRAME OrderFrame.
ON CHOOSE OF bClose IN FRAME OrderFrame DO:
RUN destroy-query.
END.
END.
ELSE DO:
WAIT-FOR CHOOSE OF bClose IN FRAME OrderFrame.
END.
p-perwn2.p (2 of 5)
2122
PROCEDURE destroy-query:

(5) MESSAGE "Exiting orders for" custbuf.name "...".
phand = SESSION:FIRST-PROCEDURE.
IF LOOKUP(custbuf.name, phand:PRIVATE-DATA) > 0 AND
phand <> THIS-PROCEDURE THEN
RUN destroy-query IN phand NO-ERROR.
phand = nhand.
END.
DELETE PROCEDURE THIS-PROCEDURE NO-ERROR.
DELETE WIDGET-POOL.
END.
PROCEDURE check-redundant:
DEFINE OUTPUT PARAMETER lorder-redundant AS LOGICAL INITIAL FALSE.

IF LOOKUP(appdata, phand:PRIVATE-DATA) > 0 AND
LOOKUP(STRING(order.order-num),
phand:PRIVATE-DATA) > 0 THEN DO:
lorder-redundant = TRUE.
RETURN.
END.
phand = nhand.
END.
END PROCEDURE.
PROCEDURE update-order:
DEFINE VARIABLE rid AS ROWID.
DEFINE VARIABLE choice AS LOGICAL.
DEFINE BUTTON bSave LABEL "Save Changes".
p-perwn2.p (3 of 5)
Windows
2123
(7) DEFINE FRAME UpdateFrame SKIP(.5)
order.order-num COLON 12 VIEW-AS TEXT
order.sales-rep VIEW-AS TEXT "For..." VIEW-AS TEXT
custbuf.name VIEW-AS TEXT SKIP
custbuf.cust-num COLON 48 VIEW-AS TEXT SKIP(1) SPACE(1)
order.order-date order.ship-date order.promise-date
SKIP SPACE(1)
order.carrier order.instructions SKIP SPACE(1)
order.PO order.terms SKIP(1)
bSave bCancel
WITH TITLE "Update Order" SIDE-LABELS VIEW-AS DIALOG-BOX.
ON CHOOSE OF bSave IN FRAME UpdateFrame
OR GO OF FRAME UpdateFrame DO:
MESSAGE "Are you sure you want to save your changes?"
UPDATE choice AS LOGICAL.
CASE choice:
(8) WHEN TRUE THEN DO TRANSACTION ON ERROR UNDO, RETRY:
rid = ROWID(order).
FIND order WHERE ROWID(order) = rid EXCLUSIVE-LOCK.
ASSIGN
order.order-date
order.ship-date
order.promise-date
order.carrier
order.instructions
order.PO order.terms.
DISPLAY
order.order-num order.order-date
order.ship-date order.promise-date order.carrier
WITH BROWSE orderb.
APPLY "WINDOW-CLOSE" TO FRAME UpdateFrame.
END.
WHEN FALSE THEN DO:
MESSAGE "Changes not saved."
RETURN NO-APPLY.
END.
END CASE.
END.
p-perwn2.p (4 of 5)
2124
Two other important features of persistent management include setting the PRIVATEDATA
attribute and creating a widget pool so that the context of each persistent procedure can be more
easily managed as a unit (p-perwn2.p (2) and p-perwn3.p (1)).
Like p-perwn1.p, p-perwn2.p uses procedure and SESSION handle attributes:
To delete all persistent procedures (and their windows) created for customer orders when
you exit a customer order browse (p-perwn2.p (5))
To identify whether an orderline window has already been created for a selected order so
that only one orderline browse is enabled for an order at a time (p-perwn2.p (6))
ON CHOOSE OF bCancel DO:
MESSAGE
"Are you sure you want to cancel your current updates?"
CASE choice:
WHEN TRUE THEN DO:
MESSAGE "Current updates cancelled."
END.
WHEN FALSE THEN DO:
MESSAGE "Current update is continuing ..."
END.
END CASE.
END.
DISPLAY
order.order-num order.sales-rep custbuf.name custbuf.cust-num
order.carrier order.instructions order.PO order.terms
WITH FRAME UpdateFrame IN WINDOW ACTIVE-WINDOW.
ENABLE
order.carrier order.instructions order.PO order.terms
bSave bCancel

WAIT-FOR WINDOW-CLOSE OF FRAME UpdateFrame.
END PROCEDURE.
p-perwn2.p (5 of 5)
Windows
2125
Note that each persistent procedure has a unique destroyquery procedure. This allows any
other procedure to delete the persistent procedures under its control while allowing each
persistent procedure to manage its own area of control appropriately.
The persistent procedure, p-perwn3.p, browses and updates order lines very much like
p-perwn2.p browses and updates orders, except that it is at the bottom of the hierarchy of
persistent management. When you choose the bClose button in p-perwn3.p, destroyquery only
has to delete the current instance of p-perwn3.p (p-perwn3.p (3)). Depending on your
application, you can also use a management model that is more or less hierarchical. Because
Progress procedures are recursive, you can even create persistent procedures and windows
recursively. However, there is no necessary connection between a persistent context and its
recursive instance unless you establish it, for example, using the PRIVATEDATA attribute or
a shared temporary table.
2126
p-perwn3.p (1 of 4)
DEFINE PARAMETER BUFFER orderbuf FOR order.
DEFINE INPUT PARAMETER appdata AS CHARACTER.
DEFINE INPUT PARAMETER wparent AS WIDGET-HANDLE.
DEFINE QUERY ordlineq FOR order-line, item.
DEFINE BROWSE ordlineb QUERY ordlineq
DISPLAY
order-line.line-num order-line.item-num item.item-name
order-line.price order-line.qty order-line.extended-price
order-line.discount order-line.backorder
WITH 5 DOWN.
DEFINE BUTTON bClose LABEL "Close Order Lines".
DEFINE BUTTON bUpdate LABEL "Update Order Line".
DEFINE FRAME OrdlineFrame SKIP(.5)
orderbuf.order-num COLON 12 VIEW-AS TEXT SKIP(.5)
ordlineb SKIP
bClose bUpdate
WITH SIDE-LABELS SIZE-CHARS 98.8 by 8.5.

ON CHOOSE OF bUpdate IN FRAME OrdlineFrame DO:
IF ordlineb:NUM-SELECTED-ROWS >= 1 THEN DO:
RUN update-order-line.
END.
ELSE DO:
BELL.
MESSAGE "Select an order line to update ...".
END.
END.
THIS-PROCEDURE:PRIVATE-DATA = appdata + ","
+ STRING(orderbuf.order-num).
CREATE WIDGET-POOL.
END.
Windows
2127
ASSIGN
TITLE = "Order Lines for Order ..."
PARENT = wparent
RESIZE = FALSE
SCROLL-BARS = FALSE
HEIGHT-CHARS = FRAME OrdlineFrame:HEIGHT-CHARS
WIDTH-CHARS = FRAME OrdlineFrame:WIDTH-CHARS.
THIS-PROCEDURE:CURRENT-WINDOW = whand.
OPEN QUERY ordlineq PRESELECT EACH order-line
WHERE order-line.order-num = orderbuf.order-num, EACH item
WHERE item.item-num = order-line.item-num
BY order-line.line-num.
DISPLAY orderbuf.order-num WITH FRAME OrdlineFrame.
ENABLE ALL WITH FRAME OrdlineFrame.
IF THIS-PROCEDURE:PERSISTENT THEN DO:
ON CHOOSE OF bClose IN FRAME OrdlineFrame DO:
RUN destroy-query.
END.
END.
ELSE DO:
WAIT-FOR CHOOSE OF bClose IN FRAME OrdlineFrame.
END.
PROCEDURE destroy-query:
MESSAGE "Exiting order lines for order"
STRING(orderbuf.order-num) "...".
(3) DELETE PROCEDURE THIS-PROCEDURE NO-ERROR.
DELETE WIDGET-POOL.
END.
PROCEDURE update-order-line:
DEFINE VARIABLE rid AS ROWID.
DEFINE VARIABLE choice AS LOGICAL.
DEFINE BUTTON bSave LABEL "Save Changes".

(4) DEFINE FRAME UpdateFrame SKIP(.5)
orderbuf.order-num COLON 12 VIEW-AS TEXT
order-line.line-num VIEW-AS TEXT SKIP(1) SPACE(1)
order-line.qty order-line.discount order-line.backorder
SKIP(1)
bSave bCancel
WITH TITLE "Update Order Line" SIDE-LABELS VIEW-AS DIALOG-BOX.
p-perwn3.p (2 of 4)
2128
ON CHOOSE OF bSave IN FRAME UpdateFrame
OR GO OF FRAME UpdateFrame DO:
MESSAGE "Are you sure you want to save your changes?"
CASE choice:
(5) WHEN TRUE THEN DO TRANSACTION ON ERROR UNDO, RETRY:
rid = ROWID(order-line).
FIND order-line WHERE ROWID(order-line)
= rid EXCLUSIVE-LOCK.
ASSIGN
order-line.qty
order-line.discount
order-line.backorder
order-line.extended-price = INPUT order-line.qty
* order-line.price
* (1 - (INPUT order-line.discount * 0.01))
.
DISPLAY
order-line.qty order-line.discount
order-line.backorder order-line.extended-price
WITH BROWSE ordlineb.
END.
WHEN FALSE THEN DO:
MESSAGE "Changes not saved."
RETURN NO-APPLY.
END.
END CASE.
END.
p-perwn3.p (3 of 4)
Windows
2129
To help the user manage their screen, the application organizes the windows for orders and
order lines into a window family, with the customer browse window as the root
(p-perwn1.p (1), p-perwn2.p (3), p-perwn2.p (1), and p-perwn3.p (2)). Thus, the user can
minimize the entire application or any order along with all of its child windows for order lines.
Another feature of this application is the use of dialog boxes to provide modal functionality in
an otherwise non-modal, multi-window application (p-perwn2.p (7) and p-perwn3.p (4)). The
p-perwn2.p and p-perwn3.p procedures each use a dialog box to update the order and
orderlines table, respectively. This can help to control transaction size during an update. In
these examples, the transaction size is limited to a single trigger block (p-perwn2.p (8) or
p-perwn3.p (5)). So, the update windows in this case could also be persistently managed
non-modal windows without affecting the scope of transactions.
ON CHOOSE OF bCancel DO:
MESSAGE
"Are you sure you want to cancel your current updates?"
CASE choice:
WHEN TRUE THEN DO:
MESSAGE "Current updates cancelled."
END.
WHEN FALSE THEN DO:
MESSAGE "Current update is continuing ..."
END.
END CASE.
END.

(6) DISPLAY
orderbuf.order-num order-line.line-num order-line.qty
order-line.discount order-line.backorder
ENABLE
order-line.qty order-line.discount order-line.backorder
bSave bCancel

WAIT-FOR WINDOW-CLOSE OF FRAME UpdateFrame.
END PROCEDURE.
p-perwn3.p (4 of 4)
2130
Note also that these dialog boxes are parented to the window specified by the
ACTIVEWINDOW system handle (for example, p-perwn3.p (6)). This handle specifies the
window that has received the most recent input focus in the application. Using this handle
guarantees that the dialog box appears in the Progress window where the user is working, even
if it is not the current window of the procedure that displays the dialog box. For more
information on the ACTIVEWINDOW handle, see Chapter 25, Interface Design.
NOTE: This example updates the qty and extendedprice field in the orderline table.
However, it does not update the corresponding balance field in the customer table,
or the onhand and allocated fields in the item table. You might want to add the
necessary update code to maintain your working sports database. For example, you
could update the customer balance field by passing the procedure handle of
p-perwn1.p down to p-perwn3.p and calling an internal procedure in p-perwn1.p
that updates the balance field in the customer record specified by orderbuf.custnum
(in p-perwn3.p). Calling an internal procedure in p-perwn1.p keeps the customer
table and browse management all together in p-perwn1.p.
22
Menus
Progress supports two kinds of menusmenu bars and pop-up menus. You can define either
type of menu statically or create them dynamically.
A menu bar is a horizontal bar displayed at the top of a window. The menu bar contains menu
titles (submenus) arranged horizontally. When you select a menu title, a pull-down menu
containing a vertically arranged list of items is displayed.
A pop-up menu is a menu that contains items arranged vertically and it is associated with a
widget. The pop-up menu is context sensitive and appears only when the user performs a
particular mouse or keyboard action while the widget has focus.
222
22.1 Menu Types
A menu is a widget that contains a list of commands or functions that users frequently use. The
two kinds of static and dynamic menu widgets available are menu bars and pop-up menus.
22.1.1 Menu Bar
A menu bar is associated with a window. Each Progress window can have only one menu bar,
and that menu bar contains menu items know as menu titles. When the user selects a menu title,
a pull-down menu with one or more items may appear directly below the menu bar. Depending
on the application, nested pull-down menus may appear to the sides of menu items when you
select them.
Figure 221 shows a menu bar with two menu titles. When you select Edit, a pull-down menu
with three menu items appears below Edit. When you further choose the menu item Add, a
nested submenu with four menu items appears to the side of Add. The Static Menu section
describes how to select menu items using the mouse and the keyboard.
Figure 221: Window with a Menu Bar
Pull-down
Menu with
Menu Items
Nested
Submenu
Menu Bar
Menu Titles
Menus
223
In a graphical interface, you can use the mouse to pull down menus from the menu bar and
choose menu items. In a character interface, use the ENTERMENUBAR key function (usually
mapped to F3) to give focus to the menu bar. You can then use the left and right arrow keys to
position to a menu title. Press RETURN to pull down the menu and the up and down arrow keys
to position to a menu item. Press RETURN again to choose the menu item.
22.1.2 Pop-up Menu
A pop-up menu is associated with a widget. The pop-up menu can contain one or more items as
well as nested submenus. Figure 222 shows two button widgets. When you choose the button
Hi, a pop-up menu that contains five choosable menu items appears.
Figure 222: Button with a Pop-up Menu
In a graphical interface, you can press and hold the mouse MENU button to pop up a menu by
default or use SHIFTF10. To choose an item, move the mouse pointer to the item and click the
SELECT button. You can define a different mouse button to use by setting the MENUMOUSE
attribute of the menu.
In a character interface, use the key associated with the DEFAULTPOPUP key function
(usually ESCU; F4 on Windows). Use the up and down arrow keys to move within the menu,
and press RETURN to choose a menu item. You can use this keyboard method in both character
and graphical interfaces.
Pop-up Menu
with Items
224
22.2 Menu Hierarchy
Progress allows you to generate static and dynamic menus according to the requirements of your
application. If you know up-front the kinds of menus you need and the exact number of menu
items and submenus in your menus, you can generate static menus. Conversely, if you dont
know how many menus you need or the number of items your menu will contain, or even what
is in your menus, you can create dynamic menus.
Whether you generate static or dynamic menus, the relationships remain the same between
menus, their owners, and their child widgets. Figure 223 shows the menu hierarchy.
Figure 223: Menu Hierarchy
At the top of the menu hierarchy is the menu bar or pop-up menu. Menus are the parents of
menu items and/or submenus. Each child submenu can, in turn, be the parent of menu items and
submenus. Your application can have multiple levels of nested submenus.
Note that menus themselves do not have parents; instead, they have owners. All widgets, except
images, rectangles, text, labels, menus, menu-items, and submenus, can be menu owners.
Windows are the only widgets that can own a menu bar. All the other widgets can own only a
pop-up menu.
Menu
Item
Menu
Item
Menu
Item
Menu
Item
Menu
Item
Menu
Item
Menu
Item
Menu
Item
Submenu
Menu
Item
Submenu Submenu Submenu
Menu
Item
Menu
Item
Menu
Item
Menu
Item
Menu
Item
Submenu
Menu
Item
Submenu Submenu Submenu
Owner Widget
(e.g., window)
Menu Bar
Pop-up Menu
Menus
225
22.3 Features for Menu Widgets
You can add the following features to your static and dynamic menus:
Nested submenus
Duplicate menus
Accelerators
Menu mnemonics
Enabling and disabling characteristics
Toggle-box items
Detailed descriptions of these features appear later in this chapter.
22.4 Defining Menus
This section describes static menus, how to define them, and how to add features (such as
accelerators, mnemonics, etc.) to them.
22.4.1 Static Menu Bars
The following sections describe how to set up a menu bar. They contain sample code that
generates the following menu bar.
226
Setting Up a Static Menu Bar
Setting up a static menu bar is a three-part process:
1. Define the pull-down submenus.
2. Define the menu bar itself.
3. Assign the menu bar to a window.
The following sections describe this process in greater detail.
Defining Pull-down Submenus
To generate a submenu, you use the DEFINE SUBMENU statement. Each submenu must have
a unique name. Use the MENUITEM phrase to specify menu items, and use the LABEL option
to define the text for the menu item. If you omit LABEL, Progress displays the item handle
name by default. Progress lays out the menu items consecutively in a top-to-bottom order. The
following code fragment defines three submenus and their menu items.
The ACCELERATOR option specifies a key or key combination that the user can use to select
a menu item without having to pull down the menu. For more information on accelerators, see
the Menu Item Accelerators section.
The ampersand (&) before the letter x in "E&xit" causes x to be underlined when the menu is
displayed. The letter x is called a mnemonic. A mnemonic provides a way to access menu items
from the keyboard. For more information on mnemonics, see the Menu Mnemonics section.
DEFINE SUB-MENU topic
MENU-ITEM numbr LABEL "Cust-num"
MENU-ITEM addr LABEL "Address"
MENU-ITEM othrinfo LABEL "Other".
DEFINE SUB-MENU move
MENU-ITEM forward LABEL "Next" ACCELERATOR "PAGE-DOWN"
MENU-ITEM backward LABEL "Prev" ACCELERATOR "UP".
DEFINE SUB-MENU quitit
MENU-ITEM quit LABEL "E&xit".
Menus
227
To generate a help submenu, add the SUBMENUHELP phrase to the DEFINE SUBMENU
statement, as shown below.
For more information on the DEFINE SUBMENU statement, see the Progress Language
Reference.
Defining a Menu Bar
To generate a menu bar, you use the DEFINE MENU statement. You must explicitly specify
the MENUBAR phrase. You can add menu items and submenus to the menu bar.
In the following code, you assign the three previously defined submenus to the menu bar with
the SUBMENU phrase. You use the LABEL option to define the text for the submenu.
Progress lays out the submenus consecutively in left-to-right order on the menu bar.
NOTE: You can add submenus or menu items to existing dynamic menu structures at any
time. Progress appends the newly added widgets to the end of the list. See the
Dynamic Menus section.
For more information on the DEFINE MENU statement, see the Progress Language Reference.
DEFINE SUB-MENU userhelp SUB-MENU-HELP
MENU-ITEM message LABEL "Recent Messages"
MENU-ITEM keybd LABEL "Keyboard"
MENU-ITEM command LABEL "Menu Commands".
DEFINE MENU mbar MENUBAR
SUB-MENU topic LABEL "Topic"
SUB-MENU move LABEL "Move"
SUB-MENU quitit LABEL "E&xit"
SUB-MENU userhelp LABEL "Help".
228
Assigning a Menu Bar to a Window
Now that you have set up a menu bar, you need to assign it to a window. You do so by setting
the windows MENUBAR attribute equal to the handle of the menu. For example, if you are
using the current window or default window, you can refer to it by using the
CURRENTWINDOW or DEFAULTWINDOW system handle.
If you are using a window that your application has created, you can refer to the windows
widget handle. See the following code fragment. At the end of the code, delete the window with
the DELETE WIDGET statement.
ASSIGN DEFAULT-WINDOW:MENUBAR = MENU mbar:HANDLE.
DEFINE VARIABLE mwin AS WIDGET-HANDLE.
.
.
.
CREATE WINDOW mwin
ASSIGN MENUBAR = MENUmbar:HANDLE.
.
.
.
DELETE WIDGET mwin.
Menus
229
Example of a Menu Bar with Pull-down Submenus
The p-bar.p procedure that follows contains most of the sample definition codes used in the
previous sections. The procedure defines a menu bar, mbar, which contains three pull-down
submenus. The handle of mbar is assigned to the current window. The ON statements define
triggers that execute when you select the corresponding menu items.
p-bar.p (1 of 2)
DEFINE SUB-MENU topic
MENU-ITEM numbr LABEL "Cust. Number"
MENU-ITEM addr LABEL "Address"
MENU-ITEM othrinfo LABEL "Other".

MENU-ITEM forward LABEL "NextRec" ACCELERATOR "PAGE-DOWN"
MENU-ITEM backward LABEL "PrevRec" ACCELERATOR "PAGE-UP".

DEFINE SUB-MENU quitit
MENU-ITEM quititem LABEL "E&xit".

DEFINE MENU mbar MENUBAR
SUB-MENU topic LABEL "Topic"
SUB-MENU move LABEL "Move"
SUB-MENU quitit LABEL "E&xit".
DISPLAY customer.name LABEL "Customer Name" WITH FRAME name-frame.
ON CHOOSE OF MENU-ITEM numbr
DISPLAY customer.cust-num WITH FRAME num-frame ROW 6.
ON CHOOSE OF MENU-ITEM addr
DISPLAY customer.address customer.address2 customer.city
customer.state customer.country customer.postal-code
WITH FRAME addr-frame NO-LABELS COLUMN 25 ROW 6.
ON CHOOSE OF MENU-ITEM othrinfo
DISPLAY customer EXCEPT name cust-num address
address2 city state country postal-code
WITH FRAME oth-frame SIDE-LABELS ROW 11.
2210
When you run this code, you see a menu bar at the top of the window and a frame that displays
the name of the first customer. The menu bar contains three titles: Topic, Move, and Exit. You
can select each title, one at a time, and pull down its menu to select a menu item.
The Exit menu has only one item. When you choose that item, the procedure ends.
ON CHOOSE OF MENU-ITEM forward
DO:
HIDE ALL NO-PAUSE.
CLEAR FRAME name-frame.
END.

ON CHOOSE OF MENU-ITEM backward
DO:
HIDE ALL NO-PAUSE.
CLEAR FRAME name-frame.
END.

ASSIGN CURRENT-WINDOW:MENUBAR = MENU mbar:HANDLE.
WAIT-FOR CHOOSE OF MENU-ITEM quititem.
p-bar.p (2 of 2)
Menus
2211
22.4.2 Static Pop-up Menus
You set up a static pop-up menu by using the DEFINE MENU statement. By default, if you
dont specify the MENUBAR phrase, Progress treats this widget as a pop-up menu. To associate
a pop-up menu with a widget, you assign the handle of the menu to the widgets
POPUPMENU attribute.
The p-popup.p procedure displays a button that has an associated pop-up menu:
p-popup.p
DEFINE BUTTON hi LABEL "Hello".
DEFINE MENU popmenu TITLE "Button State"
MENU-ITEM ve LABEL "Hello"
MENU-ITEM vd LABEL "Howdy"
MENU-ITEM iv LABEL "Hey"
RULE
MENU-ITEM ep LABEL "Exclamation point" TOGGLE-BOX
RULE
MENU-ITEM ex LABEL "Exit".
FORM
hi AT ROW 4 COLUMN 5
/* Set popmenu to be the pop-up menu for hi. */
ASSIGN hi:POPUP-MENU = MENU popmenu:HANDLE.
/* Define action for menu selections. */
ON CHOOSE OF MENU-ITEM ve, MENU-ITEM vd, MENU-ITEM iv
ASSIGN hi:LABEL IN FRAME button-frame = SELF:LABEL.
/* Define action for button selection. When the button is
selected, display the current button label as a message.
If Exclamation Point is checked, add an exclamation point
to the message; otherwise, add a period. */
ON CHOOSE OF hi
MESSAGE hi:LABEL IN FRAME button-frame +
(IF MENU-ITEM ep:CHECKED IN MENU popmenu THEN "!" ELSE ".").

/* Enable input on the button and wait for the
user to select Exit from menu. */
ENABLE hi WITH FRAME button-frame.
WAIT-FOR CHOOSE OF MENU-ITEM ex.
2212
When you run this code, a button with a label Hello appears on the screen. When you pop up
the associated menu and choose any of the first three menu itemsHello, Howdy, or Heythe
label of the button changes accordingly to the value of the chosen item. Subsequently, when you
choose the button itself, the current value of the buttons label displays as a message at the
bottom of the window. The message ends in either a period or an exclamation point, depending
on the current state of the ep toggle-box menu item. See the Menu Toggle Boxes section for
more information.
22.5 Nested Submenus
When the user selects a menu item assigned with nested submenus, a pull-down submenu
appears next to it. Although your pull-down and pop-up menus can contain many levels of
nested submenus, you should limit them to three or less. Multiple levels of nested submenus
tend to clutter up the screen and can make it difficult for the user to access menu items.
The following screen shows a nested submenu. When you select the Add item (in the pull-down
menu of Edit), you can, while holding down the mouse SELECT button, pull another submenu
to the side. On Windows, submenus appear automatically as you drag down in the containing
menu.
Menus
2213
The following code fragment defines the menus shown in the previous screen. The code defines
a menu bar, mybar, that contains three submenus: myfile, mycolors, and myedit. The submenu
mycolors (1) is nested within the myedit submenu (2).
22.6 Enabling and Disabling Menu Items
You can selectively enable and disable menu items in your menus. When an item is enabled, it
is a valid selection. However, when an item is disabled, it appears grayed out and it cannot be
selected. For example, in the following code, when you select button b1 labeled Text Mode,
the first three items (which correspond to graphic commands) are disabled; the only item
enabled is the Text command. Conversely, when you select button b2 labeled Graphics Mode,
only the items for the graphic commands are enabled.
NOTE: The p-menu.p example produces a run-time warning in character interfaces because
it cannot create a dynamic window.
DEFINE SUB-MENU myfile
MENU-ITEM m1 LABEL "Save"
MENU-ITEM m2 LABEL "Save &As"
MENU-ITEM m3 LABEL "E&xit".
DEFINE SUB-MENU mycolors
MENU-ITEM m1 LABEL "Red"
MENU-ITEM m2 LABEL "Green"
MENU-ITEM m3 LABEL "Blue"
MENU-ITEM m4 LABEL "Black".
DEFINE SUB-MENU myedit
SUB-MENU mycolors LABEL "Add"
MENU-ITEM e1 LABEL "Delete"
MENU-ITEM e2 LABEL "Copy".
DEFINE MENU mybar MENUBAR
SUB-MENU myfile LABEL "File"
SUB-MENU myedit LABEL "Edit".
Submenu mycolors
nested in submenu
myedit
2214
p-menu.p
DEFINE VARIABLE mywin AS WIDGET-HANDLE.
DEFINE SUB-MENU myfile
MENU-ITEM m1 LABEL "Save"
MENU-ITEM m2 LABEL "Save &As"
MENU-ITEM m3 LABEL "E&xit".
DEFINE SUB-MENU mycolors
MENU-ITEM m1 LABEL "Red"
MENU-ITEM m2 LABEL "Green"
MENU-ITEM m3 LABEL "Blue"
MENU-ITEM m4 LABEL "Black".
DEFINE SUB-MENU myedit
SUB-MENU mycolors LABEL "Add"
MENU-ITEM e1 LABEL "Delete"
MENU-ITEM e2 LABEL "Copy".
DEFINE MENU mybar MENUBAR
SUB-MENU myfile LABEL "File"
SUB-MENU myedit LABEL "Edit".
DEFINE BUTTON b1 LABEL "Text Mode".
DEFINE BUTTON b2 LABEL "Graphics Mode".
FORM
b1 at X 10 Y 120
b2 at x 120 Y 120
WITH FRAME x.
ON CHOOSE OF b1 IN FRAME x DO:
MENU-ITEM m1:SENSITIVE IN MENU mycolors = NO.
MENU-ITEM m4:SENSITIVE IN MENU mycolors = YES.
END.
ON CHOOSE OF b2 IN FRAME x DO:
END.
CREATE WINDOW mywin
ASSIGN MENUBAR = MENU mybar:HANDLE.
CURRENT-WINDOW = mywin.
ENABLE b1 b2 WITH FRAME x.
APPLY "CHOOSE" TO b1.
WAIT-FOR CHOOSE OF MENU-ITEM m3 IN MENU myfile.
DELETE WIDGET mywin.
Menu item names can
be identical in
different submenus
All menu items are
disabled except the
last one
If menu item names
are non-unique, use
IN MENU clause
to identify the
parent menu
Menus
2215
Note that the items in myfile and mycolors have identical names. Progress allows you to use
non-unique names for menu items as long as they belong to different submenus. To avoid
ambiguity when you subsequently refer to these items, use the IN MENU clause to identify the
parent menu of the item or the IN SUBMENU clause to identify the parent submenu of the
item. The IN MENU or IN SUBMENU clause is not necessary if the name of the menu item
is unique.
When you run this procedure, a window containing a menu bar and two buttons appears. If you
choose the Text Mode button and subsequently pull down the Edit menu, you see that only the
last item in the menu, Black, is enabled. The rest of the items (Red, Green, and Blue) associated
with the Graphics Mode button are grayed out. They are enabled when you select the Graphics
Mode button prior to accessing the Edit menu.
NOTE: There are situations where Progress cannot disambiguate a menu item. One is where
the same menu item occurs in a submenu that itself is duplicated in two menus, and
where the second menu also contains the same menu item. In that case Progress can
only reference the menu item in the first copy of the submenu. This is because
Progress cannot distinguish the three identical menu items contained in the first and
second copies of the submenu and also in the second menu.
22.7 Menu Toggle Boxes
You can specify the TOGGLEBOX option for selectable menu items in your pull-down menus
and pop-up menus. When you use this option, the user can alternately check and uncheck the
associated menu item by choosing it. The application can examine the CHECKED attribute for
the item to determine whether the item is currently checked or unchecked. You can also
initialize or change the condition of the menu item by setting the CHECKED attribute in the
program.
2216
Depending on the interface, the state of the menu item may be shown visually to the user. For
example, on Windows, when you select the item Exclamation Point in p-popup.p, a check mark
appears, as shown in the following screen. When you subsequently choose the button, the
message ends with either an exclamation point or a period, depending on whether the
Exclamation Point item is highlighted.
When the user toggles a toggle-box item, Progress sends the VALUECHANGED event to the
menu item. Therefore, by defining a trigger on that event, you can take immediate action when
the user toggles the value.
22.8 Duplicating Menus
Once a menu or submenu is defined, you can make a duplicate of it and use it in another
submenu that you are defining with the LIKE phrase. This duplicate inherits all the properties
of the original menusuch as name, menu items, and definitional triggers. To avoid ambiguity
when you subsequently refer to menu items either in the original menu or in its duplicate, use
the IN MENU clause.
Menus
2217
The following code defines two buttons, each with a pop-up menu. The second pop-up menu is
defined to be like the first one and thereby inherits the formers characteristics.
p-popup2.p
DEFINE BUTTON hi1 LABEL "Hello".
DEFINE BUTTON hi2 LABEL "Hi".
DEFINE MENU popmenu1 TITLE "Button1 State"
MENU-ITEM ve LABEL "Hello"
MENU-ITEM vd LABEL "Howdy"
MENU-ITEM iv LABEL "Hey"
RULE
MENU-ITEM ep LABEL "Exclamation point" TOGGLE-BOX
RULE
MENU-ITEM ex LABEL "Exit".
DEFINE MENU popmenu2 TITLE "Button2 State" LIKE popmenu1.
FORM
hi1 AT x 30 Y 70
hi2 AT x 130 Y 70
WITH FRAME button-frame WIDTH 30.
/*Set popmenu1 and popmenu2 to be the pop-up menus for hi1 and hi2.*/
ASSIGN hi1:POPUP-MENU = MENU popmenu1:HANDLE
hi2:POPUP-MENU = MENU popmenu2:HANDLE.
/* Define action for menu selections. */
ON CHOOSE OF MENU-ITEM ve IN MENU popmenu1, MENU-ITEM vd IN MENU
popmenu1, MENU-ITEM iv IN MENU popmenu1
ASSIGN hi1:LABEL IN FRAME button-frame = SELF:LABEL.
ON CHOOSE OF MENU-ITEM ve IN MENU popmenu2, MENU-ITEM vd IN MENU
popmenu2, MENU-ITEM iv IN MENU popmenu2
ASSIGN hi2:LABEL IN FRAME button-frame = SELF:LABEL.
ON CHOOSE OF hi1
MESSAGE hi1:LABEL IN FRAME button-frame +
(IF MENU-ITEM ep:CHECKED IN MENU popmenu1 THEN "!" ELSE ".").
ON CHOOSE OF hi2
MESSAGE hi2:LABEL IN FRAME button-frame +
(IF MENU-ITEM ep:CHECKED IN MENU popmenu2 THEN "!" ELSE ".").
/* Enable input on the button and wait
for the user to select Exit from menu. */
ENABLE hi1 hi2 WITH FRAME button-frame.
WAIT-FOR CHOOSE OF MENU-ITEM ex IN MENU popmenu1,
MENU-ITEM ex IN MENU popmenu2.
The IN MENU phrase
identifies the parent
menu of the item
The LIKE phrase
specifies the name
of the submenu you
want to duplicate
2218
22.9 The MENUDROP Event
The MENUDROP event occurs every time you bring a pull-down menu or pop-up menu into
view. You can write a trigger on the MENUDROP event to enable or disable specific items
within the menu.
NOTE: To trigger this event for a menu widget, the menu widget must be a pop-up menu.
Otherwise, you can only trigger this event for a submenu widget.
CAUTION: Do not interact with the window manager from within a MENUDROP trigger.
Doing so causes the window manager to lose control of the system, forcing you to
reboot or restart the window manager. Actions to avoid include any window
system input or output. These include actions that can generate a warning or error
message, forcing window system output. Use the NOERROR option on
supported statements to help avoid this situation. Otherwise, check valid values,
especially for run-time resources like widget handles, to prevent Progress from
displaying unexpected messages.
22.10 Menu Item Accelerators
In both graphical and character interfaces, you can define an accelerator key for menu item. An
accelerator is a key or key combination that executes an item from a pull-down menu without
the user having to pull down the menu. Progress recognizes menu accelerators for the active
window, except during modal interactionsthat is, when the user is prompted by any type of
alert box or dialog box.
When the user presses an accelerator to invoke a menu item, Progress generates the
MENUDROP event for the menu, but does not display the menu. Also, for a standard menu
item Progress generates a CHOOSE event, and for a toggle box menu item Progress generates
a VALUECHANGED event.
22.10.1 Defining Accelerators
You can define an accelerator for a menu item by adding the ACCELERATOR option to the
menu item description.
This is the syntax for a menu accelerator:
In this syntax, the value keylabel must be a character-string constant that evaluates to a valid
Progress key label. You can modify the keylabel by specifying one or more of these
SYNTAX
ACCELERATOR keylabel
Menus
2219
keysSHIFT, CTRL, or ALT. For example, you can specify ALTF8", PAGEUP, etc. When
the user presses the specified key(s), the menu item is selected.
Note that Progress automatically adds the specified accelerator key to the menu item after the
label. You should not put the accelerator into the label. For example, if you specify "CTRLP,"
Progress adds CTRL+P to the menu item (CTRLP in character interfaces).
The following code fragment specifies two accelerator keys, CNTLN and CNTLP.
Progress displays the menu items as follows:
NOTE: Progress does not support accelerators for pop-up menu items. If you define them,
Progress ignores them.
MENU-ITEM forward LABEL "NextRec" ACCELERATOR "CNTL-N"
MENU-ITEM backward LABEL "PrevRec" ACCELERATOR "CNTL-P".
2220
22.10.2 Accelerators in Character Interfaces
For character interfaces, the choice of key labels is limited by those keys available on your
keyboard. Thus, key labels are not necessarily portable between terminal types. For example,
some terminals have no F2 key, but might have a PF2 key or require a CTRL key combination to
emulate common F2 key functionality.
Specifying Portable Accelerators
For portability, you can use the KBLABEL function to specify the accelerator key label.
This allows you to use a portable Progress key function (such as HELP) to identify a valid key
label for the current keyboard (terminal type). The key label is one that is associated with the
key function for the terminal type in the current environment. On Windows, the current
environment might reside in the registry or in an initialization file. On UNIX, the current
environment resides in the PROTERMCAP file.
However, note that the current environment can (and often does) define more than one key label
for a given Progress key function. The KBLABEL function returns the first such definition
specified for the terminal type. For example, some terminal types define F2 and also ESC? as
the HELP key function. In this case, using KBLABEL(HELP) changes F2 to a menu item
accelerator (losing its HELP key function), but leaves ESC? as the one remaining HELP key
function.
Handling Invalid Accelerators
There are two types of invalid menu accelerators:
Those specified by using a key label that is unsupported by the terminal.
Those specified with supported key labels, but when invoked, generate unrecognized
keyboard codes.
If you specify an unsupported key label, say ALT in ALTF9, Progress substitutes a supported
key label in its place. Thus, Progress might substitute ESCF9 for ALTF9 as the accelerator
definition.
However, an accelerator like ESCF9 might not work at run time. In this case, ESCF9 generates
unrecognizable keyboard code sequences that fail to fire the appropriate Progress event. The
terminal might also indicate the failure with a beep or other warning signal.
When in doubt, specify the menu accelerator using the terminal-portable KBLABEL function
described earlier.
MENU-ITEM miHelp LABEL "Help Menu" ACCELERATOR KBLABEL("HELP").
Menus
2221
22.11 Menu Mnemonics
For quick access, the user can select an item from a pull-down menu or menu bar by pressing
ALT and one mnemonic character. Progress indicates the mnemonic character by underlining it
within the menu. For example, a menu bar might contain the entries File, Edit, and Exit. This
means that you can access the File menu by pressing ALTF, the Edit menu by pressing ALTE,
and the Exit menu by pressing ALTX.
NOTE: If you define a menu mnemonic key combination as an accelerator, the accelerator
takes precedence. For more information on key precedence, see Chapter 6,
Handling User Input.
In Progress, you can define mnemonics for items in a menu bar, pull-down menu, or pop-up
menu. To specify a mnemonic, insert an ampersand (&) before that letter in the label. For
example, to make x the mnemonic for Exit, you specify LABEL "E&xit". Note that in graphical
and character interfaces, the first character in an items label is the default mnemonic. You can
only specify one mnemonic for each label; do not precede more than one letter with an
ampersand.
To include a literal ampersand within a menu label, use two ampersands. For example, the label
"Undo && Restart" is displayed as Undo & Restart.
22.12 Dynamic Menus
Dynamic menus are similar to static menus in several ways:
They both share the same hierarchy of relationship to owners and descendents.
You can also add features such as toggle boxes, accelerators, mnemonicsall of which
were discussed in the Static Menu sectionto dynamic menus.
Dynamic menus are different from static menus in the following ways:
Dynamic menus are created during run time. Your application can create as many menu
items as needed or can add menu items to existing static or dynamic menus. In contrast,
static menus and menu items are fixed in quantity at compile time.
The syntax you use to generate dynamic menus, as well as to assign characteristics, are
different. Recall that to generate static menus, you use the DEFINE MENU and DEFINE
SUBMENU statements. For dynamic menus, you use the CREATE MENU, CREATE
SUBMENU, and CREATE MENUITEM statements.
To delete a dynamic widget, you use the DELETE WIDGET statement. When the
application deletes a dynamic widget, Progress automatically deletes all its children or
descendents.
2222
22.12.1 Properties of Dynamic Menus
As discussed in the first part of this chapter, a menu bar has a window for an owner, while a
pop-up menu has an associated widget. The owner widget has a readable and setable
MENUBAR or POPUPMENU attribute that allows you to set or query the ownership status of
a widget. The menu widget has a read-only OWNER attribute that returns the widget handle of
the owner widget. You can reset the MENUBAR or POPUPMENU attribute to a different
menu widget handle at any point in your application. Progress automatically replaces the first
menu with the second after you reset that attribute.
If your application deletes a menu widget, Progress finds the owner widget that refers to it and
sets its ownership attribute to unknown (?). Progress then automatically deletes all the children
or descendents of that menu widget.
Like all dynamic widgets, the menu widgets go into a widget pool. You can specify a widget
pool with the IN WIDGETPOOL clause of the CREATE statement. If you do not specify a
widget pool, the menu widget is created in the default unnamed widget pool. Should you,
however, specify a widget pool that does not exist, Progress stops its execution of the procedure.
The menu widget exists until you explicitly delete it with the DELETE WIDGET statement or
until the widget pool is deleted.
You cannot set the geometry of menu, submenu, and menu item widgets; that is, you cannot set
characteristics such as X, Y, ROW, COLUMN, WIDTH, HEIGHT, HEIGHTROWS, and
WIDTHCOLUMNS. These characteristics are all fixed and set by Progress.
Menus
2223
22.12.2 Dynamic Menu Bar
The following sections contain steps on how to set up a dynamic menu bar, as well as a sample
code that generates the following menu bar and pull-down menu.
Setting Up a Dynamic Menu Bar
Setting up a dynamic menu bar is a three-part process:
1. Create the menu bar and assign it to a window.
2. Create submenus and attach them as children to the parent menu or to another submenu.
3. Create menu items and attach them to the submenu(s).
The following sections describe this process in detail.
2224
Creating the Menu Bar
Recall that when you define a static menu widget (for example, a menu bar) you use the
DEFINE MENU statement and you must specify the MENUBAR attribute. Without the
MENUBAR attribute, Progress automatically treats the widget as a pop-up menu. For a
dynamic menu, the POPUPONLY attribute determines whether it is a menu bar or a pop-up
menu. To create a dynamic menu bar, you must do the following:
1 Define a variable for the menu as a widgethandle.
2 Use the CREATE MENU statement to create a menu widget. The POPUPONLY
attribute defaults to FALSE, so the menu is treated as a menu bar.
3 To display the menu bar, attach it to a window. Set the MENUBAR attribute of the
window equal to the widget handle of the menu.
The following code fragment defines a widget-handle variable, creates a dynamic menu, and
sets the MENUBAR attribute of the current window to mainbarptr.
Creating Submenus
To create a submenu, you use the CREATE SUBMENU statement. Each submenu must have
a unique label. Use the ASSIGN clause of the CREATE SUBMENU statement to set the
PARENT attribute equal to the widget handle of the menu or another submenu. You cannot
change the parent of submenus or menu items once you make the assignment. The only way you
can change the parent/child relationship is by deleting the child. Use the LABEL option to
define the text for the submenu.
Progress lays out dynamic menu widgets the same way it does static menu widgets. Submenus
are laid out consecutively in a left-to-right order on the menu bar; menu items are laid out
consecutively in a top-to-bottom order. If the application deletes a dynamic submenu or menu
item widget, Progress automatically shifts remaining widgets up or to the left. For example,
when a menu item is deleted, the remaining items are shifted up to fill the previously occupied
space. You can add submenus or menu items to existing menu structures at any time. Progress
appends the newly added widgets to the end of the list.
DEFINE VARIABLE main-bar-ptr AS WIDGET-HANDLE.
.
.
.
CREATE MENU main-bar-ptr.
CURRENT-WINDOW:MENUBAR = main-bar-ptr.
Menus
2225
The following code fragment creates a submenu srepmenptr and sets the parent attribute to
mainbarptr. The label of the submenu is Reps.
Creating Menu Items
Recall that when you create a menu item for a static menu widget, you use the MENUITEM
phrase to specify the menu item. However, for a dynamic menu, you must first define the
widget-handle variables, then use the CREATE MENUITEM statement to create each
individual menu item. Each menu item can be used in only one menu or submenu. Use the
ASSIGN clause of the CREATE MENUITEM statement to set the PARENT attribute of the
menu item equal to the widget handle of the menu or submenu. Use the LABEL option to define
the text for the menu item.
The following code fragment creates a menu item temphandptr, which is set to the parent
attribute of a previously defined submenu srepmenuptr. The label of the menu item is
salesrep.repname.
Each MENUITEM widget can be one of four different subtypes:
NORMAL A choosable menu item or toggle box item
READONLY A read-only menu item
SKIP A skip menu item
RULE A rule menu item
CREATE SUB-MENU srep-men-ptr
ASSIGN PARENT = main-bar-ptr
LABEL = "Reps".
CREATE MENU-ITEM temp-hand-ptr
ASSIGN PARENT = srep-men-ptr
LABEL = salesrep.rep-name
2226
The default subtype is NORMAL, and only the first two subtypesNORMAL and
READONLYhave labels.
You must set the subtype before Progress realizes the menu item. Enter the subtype in uppercase
and in quotes, as shown in the following code fragment.
22.12.3 Querying Sibling Attributes
For both menus and submenus, your code can traverse all the menu items and nested submenus.
You query the FIRSTCHILD attribute of a menu or submenu, which returns the widget handle
of the first menu item or child submenu. The code then follows the NEXTSIBLING attribute
to the right, etc. You can achieve the same result by starting with the LASTCHILD attribute
and follow the PREVSIBLING attribute to the left. All these four attributes are read-only,
while the PARENT attribute is read-write. The p-dymenu.p procedure traverses the
FIRSTCHILD and NEXTSIBLING attributes of the Reps menu and disables the menu item
for each sales rep in the West region.
ASSIGN SUBTYPE = "RULE"
PARENT = srep-men-ptr.
Menus
2227
22.12.4 Example of a Dynamic Menu
The following procedure creates a menu bar with a pull-down menu that contains dynamically
created menu items of sales representatives names in the salesrep table:
p-dymenu.p (1 of 2)
DEFINE VARIABLE exit-item-ptr AS WIDGET-HANDLE.
DEFINE VARIABLE srep-menu-ptr AS WIDGET-HANDLE.
DEFINE VARIABLE main-bar-ptr AS WIDGET-HANDLE.
DEFINE VARIABLE temp-hand-ptr AS WIDGET-HANDLE.
FORM
salesrep.sales-rep rep-name salesrep.region month-quota
WITH FRAME x WITH SIDE-LABELS ROW 5 CENTERED.
VIEW FRAME x.
/* Create the main menu bar. */
CREATE MENU main-bar-ptr.

/* Create a pull-down menu to list all sales reps. */
CREATE SUB-MENU srep-menu-ptr
ASSIGN PARENT = main-bar-ptr
LABEL = "Reps".
/* Create a menu item for each record in the Salesrep table. */
FOR EACH Salesrep BY rep-name:
ASSIGN PARENT = srep-menu-ptr
LABEL = salesrep.rep-name
TRIGGERS:
ON CHOOSE
DO:
FIND FIRST salesrep WHERE rep-name = SELF:LABEL.
DISPLAY salesrep WITH FRAME x.
END.
END TRIGGERS.
END.
/* Add a rule to the srep-menu-ptr. */
ASSIGN SUBTYPE = "RULE"
PARENT = srep-menu-ptr.
2228
When you run this procedure, a window containing a menu bar and a frame (to hold information
on the sales rep) appears. When you pull down the Reps menu, it displays menu items that are
created dynamically for each record in the salesrep table. The sales rep who services the West
region is grayed out. When you select one of the enabled sales reps, information on the sales rep
appears in the frame.
/* Add an exit item to the srep-menu-ptr. */
CREATE MENU-ITEM exit-item-ptr
ASSIGN PARENT = srep-menu-ptr
LABEL = "E&xit"
SENSITIVE = TRUE.
/* Set up the menu bar. */
CURRENT-WINDOW:MENUBAR = main-bar-ptr.
/* Disable menu items for all west coast sales reps.
To begin, find the first item in srep-men-ptr. */
temp-hand-ptr = srep-menu-ptr:FIRST-CHILD.test-items:
DO WHILE temp-hand-ptr <> ?:
/* Find the Salesrep record for this item (if any). */
IF temp-hand-ptr:SUBTYPE = "NORMAL"
THEN DO:
FIND FIRST salesrep WHERE salesrep.rep-name =
temp-hand-ptr:LABEL NO-ERROR.

/* Check if this rep is in the West region.
If so, disable the menu item. */
IF AVAILABLE(salesrep)
THEN IF salesrep.region = "West"
THEN temp-hand-ptr:SENSITIVE = FALSE.
END.

/* Find the next item in srep-men. */
temp-hand-ptr = temp-hand-ptr:NEXT-SIBLING.
END.
/* Wait for the user to select Exit. */
WAIT-FOR CHOOSE OF exit-item-ptr.
p-dymenu.p (2 of 2)
Menus
2229
22.12.5 Dynamic Pop-up Menus
Dynamic pop-up menus are associated with widgets. You set up a pop-up menu by using the
CREATE MENU statement. You must set the POPUPONLY attribute to TRUE. To associate
a pop-up menu with a widget, you assign the menu to the widgets POPUPMENU attribute.
The following procedure displays a button with a pop-up menu that is similar to the one seen in
the Static Pop-up Menus section. You can compare the two procedures to see the different
syntax used to create the dynamic pop-up menu:
p-dypop.p (1 of 2)
DEFINE BUTTON hi LABEL "Hello".
DEFINE VARIABLE pop-menu AS WIDGET-HANDLE.
DEFINE VARIABLE ve AS WIDGET-HANDLE.
DEFINE VARIABLE vd AS WIDGET-HANDLE.
DEFINE VARIABLE iv AS WIDGET-HANDLE.
DEFINE VARIABLE ep AS WIDGET-HANDLE.
DEFINE VARIABLE ex AS WIDGET-HANDLE.
DEFINE VARIABLE dummy-rule AS WIDGET-HANDLE.
FORM
hi AT x 30 y 70
CREATE MENU pop-menu
ASSIGN POPUP-ONLY = TRUE
TITLE = "Button State".
CREATE MENU-ITEM ve
ASSIGN
PARENT = pop-menu
LABEL = "Hello".
CREATE MENU-ITEM vd
ASSIGN
PARENT = pop-menu
LABEL = "Howdy".
CREATE MENU-ITEM iv
ASSIGN
PARENT = pop-menu
LABEL = "Hey".
2230
CREATE MENU-ITEM dummy-rule
ASSIGN
PARENT = pop-menu
SUBTYPE = "RULE".
CREATE MENU-ITEM ep
ASSIGN
PARENT = pop-menu
LABEL = "Exclamation point"
TOGGLE-BOX = yes.
/* Create another rule--okay to re-use same widget-handle,
because we arent going to ever refer to the first rule again. */
CREATE MENU-ITEM dummy-rule
ASSIGN
PARENT = pop-menu
SUBTYPE = "RULE".
CREATE MENU-ITEM ex
ASSIGN
PARENT = pop-menu
LABEL = "Exit".
/* Set pop-menu to be the popup menu for hi-but */
ASSIGN hi:POPUP-MENU = pop-menu.
/* Define action for menu selections */
ON CHOOSE OF ve, vd, iv
ASSIGN hi:LABEL IN FRAME button-frame = SELF:LABEL.
ON CHOOSE of hi
MESSAGE hi:LABEL IN FRAME button-frame +
(IF ep:CHECKED THEN "!" ELSE ".").
/* Enable input on the button and wait
for the user to choose Exit from menu. */
ENABLE hi WITH FRAME button-frame.
WAIT-FOR CHOOSE of ex.
p-dypop.p (2 of 2)
23
Colors and Fonts
Progress allows you to control the colors and fonts that are displayed in a widget. The extent of
this control depends on your user interface and how you manage colors and fonts in your
application.
Making colors and fonts available to an application
Assigning colors and fonts to a widget
Color and font inheritance
Color in character interfaces
Color on Windows
Managing colors and fonts in graphical applications
Allowing the user to change colors and fonts
Accessing the current color and font tables
Retrieving and changing color and font definitions
Managing application environments
232
23.1 Making Colors and Fonts Available to an Application
Progress applications typically access a subset of the systems colors and fonts. This subset is
specified in the following places:
On Windows, in the registry or in an initialization file
On UNIX, in the PROTERMCAP file.
These environment settings establish a one-to-one mapping between a range of integers and the
systems colors and fonts. These integers, in turn, correspond to entries in internal color and font
tables. For example, on Windows, Progress, as installed, maps the color red to the integer 4. To
assign red to a widget, an application assigns the value 4 to the appropriate widget attribute.
Thus, the widget is assigned the fourth color from the internal color table.
For graphical interfaces, you can specify up to 256 colors and 256 fonts. However, it is also
possible to define an arbitrary color, expanding beyond the 256 colors defined in the color table,
using the RGBVALUE function. The font for an ActiveX control is set through standard font
properties and has no programmatic relationship to the font table. For information about using
colors and fonts for ActiveX controls, see the chapter that discusses Active X controls in the
Progress External Program Interfaces manual.
For character interfaces, you can specify up to 128 colors. When Progress starts up, it loads the
color and font definitions from the specified environment into internal color and font tables. The
numbers for both your color and font definitions must increase by 1, starting from 0. Progress
stops loading its color or font table at the first skipped value.
For example, if colors 0, 1, 2, and 4 are defined, Progress loads only colors 0 through 2 because
color 3 is missing. If colors 1, 2, and 3 are defined, Progress loads no colors because the
definitions start after 0. The order of color and font definition does not matter; it is only
important that a complete sequence of color and font numbers is defined.
For more information on specifying and editing environments for graphical and character
interfaces, see the Progress Client Deployment Guide.
Colors and Fonts
233
23.1.1 Progress Default Colors
The environment that comes with your Progress installation specifies 16 colors. Table 231
shows these colors and the integers you use to reference them in an application. Note that for
backward compatibility, the 16 colors are the same as those available in Version 6 of Progress.
CAUTION: The Progress Application Development Environment (ADE) reserves these 16
colors (0 through 15) defined in your environment. If you change the mappings of
these colors, the ADE tools might not function properly. You can add your own
application colors beginning with number 16.
Table 231: Progress Default Colors
Color Number Windows RGB Values Actual Color Defined
0 0, 0, 0 Black
1 0, 0, 128 Dark blue
2 0, 128, 0 Dark green
3 0, 128, 128 Blue green
4 128, 0, 0 Red
5 128, 0, 128 Purple
6 128, 128, 0 Olive
7 128, 128, 128 Gray
8 192, 192, 192 Light gray
9 0, 0, 255 Blue
10 0, 255, 0 Green
11 0, 255, 255 Turquoise
12 255, 0, 0 Red
13 255, 0, 255 Pink
14 255, 255, 0 Yellow
15 255, 255, 255 White
234
23.1.2 Progress Default Fonts
The default Progress environment specifies a set of fonts to be used with the Progress Tools. On
Windows, these fonts are MS Sans Serif (a proportional font) and Courier New (a fixed-space
font). If you have not added custom fonts to your environment, Progress uses these default fonts
for your application. Progress uses the default proportional font for alphanumeric data, and the
default fixed font for integer fields and for fields with format strings containing fill characters
(such as 9 or X).
CAUTION: The Progress ADE reserves the 8 fonts (0 through 7) defined in your environment.
If you change the mappings of these fonts, the ADE tools might not function
properly. You can add your own application fonts, beginning with number 8.
23.1.3 Application Colors and Fonts
For an example of application color and font definitions, see the environment installed with the
Progress Test Drive.
23.2 Assigning Colors and Fonts to a Widget
You can assign colors and fonts to a widget either in the widget definition statement or at run
time after the widget is displayed. Use the FGCOLOR, BGCOLOR, DCOLOR, PFCOLOR,
and FONT options at definition time and the FGCOLOR, BGCOLOR, DCOLOR, PFCOLOR,
and FONT attributes at run time.
Progress uses the foreground color you specify for any values that appear in the widget;
Progress uses the background color for the area around the widget values.
NOTE: For rectangle widgets, Progress uses the foreground color for the edge and the
background color to fill the interior.
Progress uses the font you specify for any text that appears within the widget.
Note that FGCOLOR, BGCOLOR, and FONT apply to graphical interfaces only, and
DCOLOR and PFCOLOR apply to character interfaces only. For more information on
specifying color in character interfaces, see theColor in Character Interfaces section.
Colors and Fonts
235
The p-clrfnt.p procedure demonstrates how to initialize colors and fonts at widget definition
and how to change them dynamically at run time:
p-clrfnt.p
DEFINE BUTTON quitbtn LABEL "QUIT" BGCOLOR 4 FGCOLOR 15.
DEFINE VARIABLE fgc_frm AS INTEGER BGCOLOR 15 FGCOLOR 0
VIEW-AS SLIDER MAX-VALUE 15 MIN-VALUE 0.
DEFINE VARIABLE bgc_frm AS INTEGER BGCOLOR 15 FGCOLOR 0
DEFINE VARIABLE font_frm AS INTEGER FONT 1 VIEW-AS SLIDER
MAX-VALUE 15 MIN-VALUE 0.
FORM
SKIP (1) "Form Foreground" AT 7 SKIP
fgc_frm AT 6 SKIP (1)
"Form Background" AT 7 SKIP
bgc_frm AT 6 SKIP (1)
"Form Font" AT 10 skip
font_frm AT 6 SKIP (2)
quitbtn AT 12 SKIP (1)
WITH FRAME x TITLE "Color and Font Test"
NO-LABELS CENTERED ROW 2 WIDTH 50.

ASSIGN FRAME x:RULE-Y = 282
fgc_frm:MAX-VALUE = COLOR-TABLE:NUM-ENTRIES - 1
bgc_frm:MAX-VALUE = COLOR-TABLE:NUM-ENTRIES - 1
font_frm:MAX-VALUE = FONT-TABLE:NUM-ENTRIES - 1.

ON VALUE-CHANGED OF fgc_frm
FRAME x:FGCOLOR = INPUT FRAME x fgc_frm.
ON VALUE-CHANGED OF bgc_frm
FRAME x:BGCOLOR = INPUT FRAME x bgc_frm.

ON VALUE-CHANGED OF font_frm
FRAME x:FONT = INPUT FRAME x font_frm.
ENABLE ALL WITH FRAME x .
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW OR CHOOSE OF quitbtn.
236
This procedure creates three sliders representing foreground color, background color, and font.
The maximum value of each slider is determined by examining the NUMENTRIES attributes
of the COLORTABLE and FONTTABLE system handles. As you move the appropriate
trackbar, the foreground color, background color, or font of the interface changes. Note that,
because the procedure does not explicitly set the size of any of the sliders, Progress resizes them
at run time as you change the font.
You can assign colors and fonts to all widgets, with the following exceptions:
On Windows, to assign colors to buttons, menus, and window titles, you must use the
Display Properties dialog box in the Control Panel. You cannot change these colors in your
Progress application.
In all environments, images and rectangles have no text and, therefore, cannot take a font
assignment.
For more information on the COLORTABLE and FONTTABLE handles, and on the
FGCOLOR, BGCOLOR, DCOLOR, PFCOLOR, and FONT options and attributes, see the
Progress Language Reference. For more information on using the COLORTABLE and
FONTTABLE handles for run-time color and font management, see the Accessing the
Current Color and Font Tables section in this chapter.
Colors and Fonts
237
23.3 Assigning Colors and Fonts to ActiveX Automation Objects and ActiveX
Controls
Properties associated with ActiveX Automation objects and ActiveX controls allow you to
define unique characteristics, such as color and font, for each object. For example, to set colors
for an ActiveX control, you need to set one or more of the color properties of the control to some
RGB value. There are three ways to obtain an RGB value. You can use the RGBVALUE
function, use the COLOR-TABLE:GET-RGB-VALUE( ) method, or you can get the value
from some color property of an ActiveX control or an ActiveXAutomation object. For fonts, an
ActiveX Automation Server or ActiveX control generally provide a Font object that allows you
to specify font properties.
For further information about assigning colors and fonts to ActiveX controls and ActiveX
Automation objects, see the Progress External Program Interfaces manual.
23.4 Color and Font Inheritance
If you do not specify colors or a font for a widget, Progress assigns colors and a font using the
following rules of precedence:
1. Field-level widgets take the colors and font of the containing frame.
2. Frame-level widgets take the default colors and fonts specified in the environment.
NOTE: In the environment, you can specify two default fonts but you cannot specify
default widget colors.
3. Otherwise, frame-level widgets take the default colors and fonts specified for the operating
system.
NOTE: On Windows, the default foreground color is color Window Text. For
two-dimensional widgets, the default background color is color Window. For
three-dimensional widgets, the default background color is color Button Face.
These colors are configurable using the Control Panel.
Note that frames do not inherit colors and fonts from the containing window. If you do not
specify the font for a frame, Progress uses the default font, not the font of the window. This is
because Progress determines the frame layout at compile time when the windows colors and
fonts (determined at run time) are not yet available.
238
23.5 Color in Character Interfaces
Color in a character interface differs from color in a graphical interface in these ways:
In character interfaces, the BGCOLOR and FGCOLOR attributes have the unknown value
(?).
Each location in the color table contains a foreground/background color pair.
DCOLOR specifies a foreground/background color pair that a widget uses when it
displays data.
PFCOLOR specifies a foreground/background color pair that a widget uses when it
prompts for data.
When designing your interface, make sure that you specify different color pairs for DCOLOR
and PFCOLOR.
23.5.1 Widget States and Color
Frames, dialog boxes, and rectangles use only DCOLOR. For all other widgets, Progress
considers the widgets category and its state to determine when to use the display colors
(DCOLOR) and when to use the prompt-for colors (PFCOLOR). The categories are text input
widgets (fill-ins and editors) and selectable widgets (all other widgets). The widget states are
insensitive, sensitive, and focus.
Table 232 shows how Progress assigns colors based on the state and category of widget.
Note that for repaint, look, and usability reasons, text input widgets have the same colors for the
sensitive and focus states but different colors for the insensitive state. This is in contrast to
selectable widgets, which must change colors when they receive focus.
Table 232: Colors Used in Character Interfaces
Widget State Text Input Widget Selectable Widget
Insensitive DCOLOR DCOLOR
Sensitive PFCOLOR DCOLOR
Focus PFCOLOR PFCOLOR
Colors and Fonts
239
23.5.2 Color Specification
In character interfaces, Progress reserves color table locations 0 through 4 for the following
foreground/background color pairs:
Color 0 holds colors used as the NORMAL color by Progress.
Color 1 holds the colors used as the INPUT color by Progress. As installed, this is
underline mode.
Color 2 holds the colors used as the MESSAGE color by Progress. As installed, this is
reverse video.
Color 3 holds the colors used for high-intensity mode. This mode is not available for all
terminals.
Color 4 holds the colors used for blink mode. This mode is not available for all terminals.
By default, text-input widgets use the INPUT colors when in prompt-for mode. Note, however,
that when displaying an editor widget with scroll bars to display read-only text, using
NORMAL rather than INPUT for prompt-for mode might make more visual sense to the user.
In the PROTERMCAP file, you can specify additional application color pairs from color 5 to
127. For more information, see the Progress Client Deployment Guide.
23.6 Colors on Windows in Graphical Interfaces
On Windows in graphical interfaces, your system handles color differently depending on
whether it supports the Palette Manager.
23.6.1 Systems with the Palette Manager
If your system supports the Palette Manager, you can define a palette with some number of
simultaneous colors (usually 256). Of these colors, 20 are normally reserved for standard system
colors. The others are custom colors that you can define and modify. The exact numbers of color
definitions and reservations by the system depend on your display driver.
Managing Colors for Multiple Windows
Although you can define a separate palette for each window, sharing a single palette among
several windows maximizes environment efficiency and eliminates any color contention
between the sharing windows. For more information, see the Managing Application
Environments section.
2310
Managing Colors for Bitmap Images
If you use bitmap images saved in 256color mode, Windows tries to create an individual color
map for the image each time it is realized in Progress. This has the following effects:
The background flashes as the color palette is loaded for each 256color image, unless the
color map is identical to the one previously loaded.
Performance degrades.
To reduce or eliminate these effects, convert your images from 256 colors to 16 colors or
recreate them with 16 colors at a time.
23.6.2 Systems without the Palette Manager
On systems that do not support the Palette Manager, Windows can only display 16 standard
colors. However, if you request another color, Windows tries to create that color by dithering;
that is, by filling a space with dots of different hues. This might work well, for example, in a
frame background. However, if a field-level widget, such as a fill-in or radio set, inherits a
dithered color, only one hue is used. The result might be undesirable. Therefore, avoid using
dithered colors for field-level widgets.
23.7 Managing Colors and Fonts in Graphical Applications
Graphical interfaces provide a variety of techniques to help manage color and font definitions
for an application. Using these techniques, Progress allows a graphical application to manage
colors and fonts at four levels of run-time operation:
1. User Access to the Color and Font Tables Allowing the user to change the definitions
for current dynamic color and font table entries using the SYSTEMDIALOG COLOR
and SYSTEMDIALOG FONT statements. For more information, see theAllowing the
User to Change Colors and Fonts section.
2. Procedure Access to the Color and Font Tables Examining and changing the
definitions for color table entries in the current environment using the COLORTABLE
handle, and examining height and width characteristics of font table entries in the current
environment using the FONTTABLE handle. Also, this section addresses setting the
definition for arbitrary colors using the RGBVALUE function. For more information, see
the Accessing the Current Color and Font Tables section.
Colors and Fonts
2311
3. Procedure Access to Color and Font Definitions Reading and writing color and font
definitions for the current environment using the GETKEYVALUE and
PUTKEYVALUE statements. For more information, see the Retrieving and Changing
Color and Font Definitions section.
4. Procedure Replacement of the Current Environment Replacing the applications
current color and font tables with tables from a different environment using the LOAD,
USE, and UNLOAD statements. For more information, see the Managing Application
Environments section.
23.8 Allowing the User to Change Colors and Fonts
In graphical interfaces, Progress allows you to invoke native common dialogs for color and font
selection in the 4GL using the SYSTEMDIALOG COLOR and the SYSTEMDIALOG
FONT statements. Using these dialogs, you can allow the user to choose a new value for a color
or font number. Once the user chooses a value, Progress stores the choice in the color or font
table location specified by the number. All visible widgets defined with the specified color or
font number immediately redisplay according to the user selection.
23.8.1 Establishing Dynamic Colors
You can use the SYSTEMDIALOG FONT statement to change any font in the font table.
However, you can use the SYSTEMDIALOG COLOR statement to update only those colors
that are dynamic. To make a color dynamic, use the COLORTABLE system handle.
In this example, n is the color table entry you want to make dynamic. For more information on
the COLORTABLE handle, see the Progress Language Reference and theAccessing the
Current Color and Font Tables section in this chapter.
status-ok = COLOR-TABLE:SET-DYNAMIC(n, yes).
2312
23.8.2 Color Dialog Box
Figure 231 shows the Windows system color dialog box.
Figure 231: Windows Color Dialog Box
The Windows color dialog provides several ways to specify a new color:
Custom Colors You can create a palette of 16 custom colors. To specify a color, you
select the color box from the 16 available custom colors. The specified color appears in
the ColorSolid box. To change a custom color, select one of the Basic Colors, or specify
a color by using the Numeric Colors or Visual Colors technique. Each change replaces an
existing color in the Custom Colors list.
Numeric Colors You can enter either the Hue, Sat (Saturation), and Lum (Luminosity)
values, or the RedGreenBlue (RGB) values in the fields provided. The specified color
appears in the Color|Solid box as you change each number.
Visual Colors You can visually choose the Hue and Sat values by pressing and holding
the mouse SELECT button and moving the mouse pointer in the large rainbow square to
the color you want. You can visually choose the Lum value by moving the luminosity
slider (at right) up or down. For each choice, the specified color appears in the Color|Solid
box as you move the mouse.
Colors and Fonts
2313
Clicking the OK button assigns the color that currently appears in the Color|Solid box of the
Windows dialog to the dynamic color number specified in your SYSTEMDIALOG COLOR
statement.
23.8.3 Color Dialog Example
The p-cdial1.p procedure opens the dialog box that allows you to change its own foreground
or background colors:
p-cdial1.p (1 of 2)
DEFINE VARIABLE FrontColor AS INTEGER INITIAL 16.
DEFINE VARIABLE BackColor AS INTEGER INITIAL 17.
DEFINE VARIABLE ColorSelect AS INTEGER INITIAL 16 VIEW-AS RADIO-SET
RADIO-BUTTONS "Foreground", 16, "Background", 17
HORIZONTAL.
DEFINE BUTTON bCANCEL LABEL "CANCEL".
IF COLOR-TABLE:NUM-ENTRIES < 18 THEN
COLOR-TABLE:NUM-ENTRIES = 18.
status-ok = COLOR-TABLE:SET-DYNAMIC(16, TRUE).
IF NOT status-ok
THEN DO:
MESSAGE "Cannot make color 16 dynamic.".
RETURN.
END.
status-ok = COLOR-TABLE:SET-DYNAMIC(17, TRUE).
IF NOT status-ok
THEN DO:
MESSAGE "Cannot make color 17 dynamic.".
RETURN.
END.
2314
When you run this procedure on Windows, the following frame appears:
If you choose or click the OK button, a color dialog box appears (see Figure 231) to assign a
new system color to the specified color number. Choosing CANCEL terminates the procedure
without any further color changes.
COLOR-TABLE:SET-RGB-VALUE(16,RGB-VALUE(0,0,0)).
COLOR-TABLE:SET-RGB-VALUE(17,RGB-VALUE(128,128,128)).
FORM
SKIP(0.5) SPACE(0.5)
ColorSelect SPACE(2) bOK SPACE(2) bCANCEL
SPACE(0.5) SKIP(0.5)
WITH FRAME fColor TITLE "Choose frame colors ..." FGCOLOR FrontColor
BGCOLOR BackColor VIEW-AS DIALOG-BOX.
ON CHOOSE OF bOK IN FRAME fColor
DO:
ASSIGN ColorSelect.
SYSTEM-DIALOG COLOR ColorSelect.
END.
ON CHOOSE OF bCANCEL IN FRAME fColor
STOP.

ENABLE ColorSelect bOK bCANCEL WITH FRAME fColor.
WAIT-FOR WINDOW-CLOSE OF FRAME fColor.
p-cdial1.p (2 of 2)
Colors and Fonts
2315
23.8.4 Saving a Modified Color
If you want to save any color definitions changed by the user, you can use the UPDATE option
of the SYSTEMDIALOG COLOR statement. This option sets a logical value to indicate
whether the user has changed the specified color. If the value is TRUE, you can then save the
new color definition using the PUTKEYVALUE statement.
23.8.5 Font Dialog
Figure 232 shows the native Windows system font dialog.
Figure 232: Windows Font Dialog Box
The Windows dialog box allows you to choose a single font by name and specify a style, size,
script, and optional cosmetic effect. A sample of each choice appears in the Sample box.
2316
23.8.6 Font Dialog Example
The p-fdial1.p procedure opens the dialog box that allows you to separately change the font
of either its radio set or buttons to a custom font:
p-fdial1.p
IF FONT-TABLE:NUM-ENTRIES < 13 THEN
FONT-TABLE:NUM-ENTRIES = 13.
DEFINE VARIABLE RadioFont AS INTEGER INITIAL 11.
DEFINE VARIABLE ButtonFont AS INTEGER INITIAL 12.
DEFINE VARIABLE FontSelect AS INTEGER INITIAL 11
VIEW-AS RADIO-SET
RADIO-BUTTONS "Radio Font", 11, "Button Font", 12
FONT RadioFont.
DEFINE BUTTON bOK LABEL "OK" FONT ButtonFont.
DEFINE BUTTON bCANCEL LABEL "CANCEL" FONT ButtonFont.
FORM
SKIP(0.5) SPACE(0.5)
FontSelect SPACE(2) bOK SPACE(2) bCANCEL
SPACE(0.5) SKIP(0.5)
WITH FRAME fFont TITLE "Choose frame fonts ..."
VIEW-AS DIALOG-BOX.
ON CHOOSE OF bOK IN FRAME fFont
DO:
ASSIGN FontSelect.
SYSTEM-DIALOG FONT FontSelect.
END.
ON CHOOSE OF bCANCEL IN FRAME fFont STOP.
ENABLE FontSelect bOK bCANCEL WITH FRAME fFont.
WAIT-FOR WINDOW-CLOSE OF FRAME fFont.
Colors and Fonts
2317
When you run this procedure on Windows, the following dialog box appears.
When you run the procedure, the radio set displays in the default MS Sans Serif font and buttons
display in the default Courier New font. To change a font, choose the Radio Font (font 11) or
Button Font (font 12) radio item, then choose or click the OK button to open the font dialog box
shown in Figure 232. Choosing (or clicking) CANCEL terminates the procedure without any
further font changes.
To change the radio-set font selected in Figure 232 to bold 8-point Arial, set up the font dialog
as shown in Figure 233.
Figure 233: Changing Font 11 to Bold 8-Point Arial
2318
After you choose OK, the Choose frame fonts dialog box reappears with the radio set in the new
font:
23.8.7 Saving a Modified Font
If you want to save any font definitions changed by the user, you can use the UPDATE option
of the SYSTEMDIALOG FONT statement. This option sets a logical value to indicate whether
the user has changed the specified font. If the value is TRUE, you can then save the new font
definition using the PUTKEYVALUE statement.
23.9 Accessing the Current Color and Font Tables
In graphical interfaces, you can get information about colors and fonts defined for the current
environment by querying attributes and methods of the COLORTABLE and FONTTABLE
system handles. You can also change the color configuration of the current environment using
additional methods of the COLORTABLE handle.
23.9.1 COLORTABLE Handle
The NUMENTRIES attribute sets and returns the number of colors available in the color table.
The following methods allow you to read existing color definitions and to set new definitions
for dynamic colors:
The GETREDVALUE(n), GETGREENVALUE(n), and GETBLUEVALUE(n)
methods let you read the red, blue, and green values for a specified color number. This
example gets the red value of the 16th color in the color table.
DEFINE VARIABLE red-val AS INTEGER.
red-val = COLOR-TABLE:GET-RED-VALUE(16)
Colors and Fonts
2319
You can determine whether a color is dynamic by reading the GETDYNAMIC(n)
method. You can make a color dynamic or nondynamic by using the
SETDYNAMIC(n, logical) method. This example makes color 16 dynamic if it is not
already set.
You can change the red, blue, and green values of a dynamic color by using the
SETREDVALUE(n, integer), SETGREENVALUE(n, integer), and
SETBLUEVALUE(n, integer) methods. Note that these methods change the effective
color values of a color number in the current color table. Thus, every visible widget set to
the specified color number changes to the corresponding colors immediately. However,
this does not change the color definitions originally specified in the current environment.
If you restart the application with the current environment, the original colors reappear.
This example sets color 16 to a blue value of 192.
There is an efficient alternative to calling the SETREDVALUE(n, integer),
SETGREENVALUE(n, integer), and SETBLUEVALUE(n, integer) methods to
change the RGB values of a dynamic color. You can specify the SETRGBVALUE()
method to substitute for all three of these methods. You can determine a combined RGB
value using the RGBVALUE function or by accessing a color property from an ActiveX
control.
The GETRGBVALUE() method returns an integer that represents a combination of the
red, green, and blue values associated with the nth entry. This combined RGB value is
most useful for setting colors in an ActiveX control.
For more information on the COLORTABLE handle, see the Progress Language Reference.
IF NOT COLOR-TABLE:GET-DYNAMIC(16) THEN
COLOR-TABLE:SET-DYNAMIC(16, TRUE).
COLOR-TABLE:SET-BLUE-VALUE(16, 192).
COLOR-TABLE:SET-RGB-VALUE (16, RGB-VALUE (128, 0, 128)).
2320
23.9.2 FONTTABLE Handle
The NUMENTRIES attribute sets and returns the number of fonts available in the font table.
The FONTTABLE methods return information about font sizes. Each method takes an
optional font number as an argument:
GETTEXTHEIGHTCHARS( ) and GETTEXTHEIGHTPIXELS( ) return the
height of the default font in either character units or pixels. You can pass a font number to
these methods to get the height of a specific font. This example looks for the first font from
the start of the font table with a height of at least two character units.
GETTEXTWIDTHCHARS(string) and GETTEXTWIDTHPIXELS(string)
return the width of the passed string expression in the default font in either character units
or pixels. You can optionally pass a font number to these methods to get the width of the
string in a specific font. This example tests whether a title for a new window will fit based
on the font of the current window.
For more information on the FONTTABLE handle, see the Progress Language Reference.
DEFINE VARIABLE font-number AS INTEGER.
DEFINE VARIABLE max-count AS INTEGER.
max-count = FONT-TABLE:NUM-ENTRIES + 1.
REPEAT font-number = 1 to max-count:
IF font-number = max-count THEN LEAVE.
IF FONT-TABLE:GET-TEXT-HEIGHT-CHARS(font-number) >= 2 THEN LEAVE.
END.
DEFINE VARIABLE font-number AS INTEGER.
DEFINE VARIABLE in-title AS CHARACTER.
font-number = CURRENT-WINDOW:FONT.
SET in-title.
IF FONT-TABLE:GET-TEXT-WIDTH-CHARS(font-number, in-title) > 80 THEN
MESSAGE "Title" in-title "cannot fit in new window.".
Colors and Fonts
2321
23.10 Retrieving and Changing Color and Font Definitions
In graphical interfaces, you can retrieve and change the color and font definitions for your
current environment using the GETKEYVALUE and PUTKEYVALUE statements. These
statements read and write to the current environment.
23.10.1 Changing Resource Definitions
The GETKEYVALUE statement can read and the PUTKEYVALUE statement can change
the definition of any environment resource, including the definitions of colors and fonts stored
in the current environment. However, these statements by themselves do not affect the current
Progress environment and its color and font tables. To have any definitions that are created
using the PUTKEYVALUE statement take effect, you must replace the current environment
by reloading the current environment (see the Managing Application Environments section).
Portable Color and Font Definitions
The portable and most effective way to change color and font definitions is to first change the
definitions in the color and font tables, then use the PUTKEYVALUE statement to write the
new definitions from the modified tables. You can affect the color and font tables in the current
environment using the COLORTABLE and FONTTABLE handles (see the Accessing the
Current Color and Font Tables section), and you can allow the user to affect the current color
and font tables using the SYSTEMDIALOG COLOR and SYSTEMDIALOG FONT
statements (see the Allowing the User to Change Colors and Fonts section).
23.10.2 Using GETKEYVALUE and PUTKEYVALUE
The GETKEYVALUE and PUTKEYVALUE statements allow you to read or write a
specified value for any resource by accessing the registry or an initialization file. The registry
consists of sections called keys and subkeys arranged in a hierarchy. Keys and subkeys contain
value entries, each of which consists of a value name and value data. Initialization files, by
contrast, consist of a single level of sections. Sections contain entries, each of which consists of
a name, an equals sign (=), and a value.
For example, to retrieve the Windows definition for font 8 from the current environment, which
might be the registry or an initialization file, you might enter this statement. It returns the initial
environment definition for font 8 in the FontString variable.
DEFINE VARIABLE FontString AS CHARACTER FORMAT "x(128)".
GET-KEY-VALUE SECTION "Fonts" KEY "Font8" VALUE FontString.
2322
To specify Times New Roman as the new definition for font 8 on Windows, you might enter
this statement. It sets the font8 parameter in the current environment.
Writing Portable Color and Font Definitions
To write portable color and font definitions directly from the current color and font tables, use
the PUTKEYVALUE statement with the COLOR or FONT option. For example, if you
allow the user to change color 8 during a session through the color common dialog
(SYSTEMDIALOG COLOR statement), you can save the new color definition in the current
environment using this statement.
You can save all current color definitions from the color table using this statement.
PUT-KEY-VALUE SECTION "fonts" KEY "font8" VALUE "Times New Roman".
PUT-KEY-VALUE COLOR 8.
PUT-KEY-VALUE COLOR ALL.
Colors and Fonts
2323
23.11 Managing Application Environments
For some graphical applications, you might want to replace whole Progress environments. This
applies especially to applications that build other applications, where you want to provide the
ability to test run each application in a separate environment. The Progress AppBuilder is an
example of such an application. You might also want to write a single application that has
greater flexibility to change its own environment (for example, changing the number of color
definitions available to the application).
23.11.1 Understanding Environment Management
When Progress starts up, it loads a default environment from the registry (Windows only) or
from an initialization file. This default environment is the initial current environment. The
initial current environment provides resources to the default window and any windows
subsequently created in that environment. At any point, you can replace the current environment
by loading and making a specified environment current.
23.11.2 Using Environment Management Statements
To replace the current environment with another application environment, Progress provides
these statements:
LOAD Loads a previously defined application environment into Progress memory, or
creates and loads an empty application environment to be defined. Generally, an
application environment resides in the Registry or in an initialization file with a
meaningful filename. You can load as many application environments as memory allows,
but only one environment can be current at a time.
USE Makes a previously loaded environment available as the current environment. The
new current environment has no effect on the default window or any previously created
windows. The resources of the new current environment are available only for windows
created after the new environment is made current.
UNLOAD Removes a loaded environment from Progress memory. Environments take
up very little memory and generally do not have to be unloaded. However, if you are
writing an application builder, this statement provides good housekeeping when you save
and remove an application from memory. This allows you to remove all memory
associated with a purged application.
Note that you must delete all windows created in an environment before you can unload
that environment, whether or not it is the current environment. If the unloaded
environment is the current environment, you must set a new current environment with the
USE statement before continuing operation.
2324
For more information on these statements, see their reference entries in the Progress Language
Reference.
23.11.3 Managing Multiple Environments
If you are writing an application builder, you might want to maintain separate environments for
each application.
Typical Scenario
You can follow these steps to separate application environments:
1 Have the user select an existing application or create a new one.
2 Load the existing application environment, or create and load a new one using the LOAD
statement.
3 Execute the USE statement to make the selected application environment current.
4 If the application exists, run it according to user input.
If the application is new:
a) Allocate the number of available color and font table entries for the new application
by setting the NUMENTRIES attribute of the COLORTABLE and
FONTTABLE handles.
b) Set internal colors and fonts from user input using the SYSTEMDIALOG COLOR
and FONT statements, or set internal colors using the COLORTABLE handle.
c) Create application widgets and code from user input using the current color and font
definitions.
5 Test and revise application resources and widgets according to user input.
6 Repeat Steps 1 through 5 for as many applications as you need to work on simultaneously.
Colors and Fonts
2325
7 When the user terminates all work on an application and wants to save it:
a) Save the color and font table entries to the current environment using the
PUTKEYVALUE statement with the COLOR and FONT options.
b) Save the application code to procedure files.
c) Delete all widgets for the application from Progress memory using the DELETE
WIDGET statement.
d) Remove the current application environment from Progress memory using the
UNLOAD statement.
8 Execute the USE statement according to user input to set a new current environment, then
repeat Steps 4 through 8 until all work is done.
Helpful Hints for Environment Management
Many variations in the typical scenario are possible, but this is a summary of important tasks to
consider in any application that uses multiple environments:
Before defining colors and fonts for immediate use at run time, set or adjust the size of the
current color and font tables as required using the NUMENTRIES attribute of the
COLORTABLE and FONTTABLE handles.
Use the PUTKEYVALUE statement with the COLOR and FONT options to save newly
created and newly modified color and font definitions from the current color and font
tables to the current environment.
Always set a current environment with the USE statement before or after executing the
UNLOAD statement for the current environment, even if the current environment you set
is the default environment. Otherwise, Progress returns an error when you attempt to
display or enable a widget.
2326
23.12 Managing Color Display Limitations
Although Progress allows up to 256 colors to be defined in an environment, whether and how
the widgets in each environment display these colors is system dependent. For example, if you
have 256-color widgets displayed from three separate environments, and each environment
defines an entirely different set of 256 colors, some of the widgets might not be displayed with
the correct colors. If your display (driver and hardware) supports a maximum of 256 colors at
one time, the 256-color widgets from only one of your environments can be displayed exactly
as specified. All other widgets must be displayed incorrectly to allow the widgets from one
environment to display correctly.
In general, no matter what your display limitations, Progress tries to ensure that the current
window (the window that has focus) displays correct colors at the expense of one or more other
windows that are displayed, but do not have focus. You can also do the following to ensure that
all of your widgets display with correct colors:
Do not define more colors for all loaded and used environments than your display can
simultaneously support.
Hide any widgets, especially images, that you no longer need to display and whose color
content exceeds the color capacity of your system.
24
Direct Manipulation
Progress lets you write applications that allow the user to directly manipulate (move and resize)
frames and field-level widgets using a mouse. For each widget that is to be manipulated, you
must set the appropriate attributes. For example, to allow the user to move a frame, you must
set the frames MOVABLE attribute to TRUE. The user can then use a mouse to move the frame
when running the application.
Progress also supports grids. A grid is a framework of crisscrossed bars appearing within a
frame that helps the user align widgets within the frame.
242
24.1 Attributes
The following attributes are the main attributes associated with the direct manipulation of
widgets. Other attributes are also associated with direct manipulation but apply solely to grids.
For more information on these other attributes, see the Grids section.
Table 241: Direct-manipulation Attributes
Attribute Description
SELECTABLE Set this attribute to TRUE if you want to allow the user
to highlight a widget before moving or resizing it. This
attribute applies to frames and to all field-level widgets.
MOVABLE Set this attribute to TRUE to allow the user to move a
widget. This attribute applies to frames and to all
field-level widgets.
RESIZABLE Set this attribute to TRUE to allow the user to resize a
widget. This attribute applies to frames and to all
field-level widgets.
BOXSELECTABLE Set this attribute to TRUE if you want to allow the user
to use selection boxes to select and deselect widgets
within a frame. (For more information on selection
boxes, see the Box Selecting section.) This attribute
applies only to frames.
SELECTED When the user marks a widget with a mouse, Progress
sets this attribute to TRUE. You can also explicitly set
this attribute within your code. Progress sets this
attribute to FALSE when the user unmarks the widget.
This attribute applies to frames and to all field-level
widgets.
MANUALHIGHLIGHT Set this attribute to TRUE if you want to use a custom
highlight graphic design. When the user selects a
widget, Progress highlights the widget by placing a box
around that widget by default. By setting this attribute
to TRUE, you can override the Progress default and
highlighting the widget yourself.
NUMSELECTEDWIDGETS Use this read-only attribute to determine how many
frames and dialog boxes are selected in a window, or
how many field-level widgets are selected in a frame or
dialog box.
Direct Manipulation
243
By default, all of these attributes are set to FALSE, except for NUMSELECTEDWIDGETS,
which is an integer and read-only. In addition to the attributes listed in Table 241, the
GETSELECTEDWIDGET( ) method allows you to access the widget handle of all selected
widgets in a window, dialog box, or frame. For more information on this method, see the
244
The following procedure illustrates how you might use some of these attributes.
p-dirman.p
DEFINE VARIABLE tmp AS INTEGER.
DEFINE RECTANGLE rect1 size-pixels 39 by 39 edge-pixels 3 no-fill.
DEFINE BUTTON manipulable LABEL "Manipulable".
FORM SKIP (1) SPACE (2) rect1 SPACE(9) manipulable
rect2 SPACE(2) SKIP (1)
SPACE(9) rect3 SPACE(10)
rect4 SPACE(7) SKIP(3)
"Cust-Num: " tmp SKIP(1)
WITH FRAME a ROW 3 CENTERED NO-LABELS TITLE "Manipulable Widgets".
FRAME a:BOX-SELECTABLE = YES.
rect1:SENSITIVE IN FRAME A = YES. /* All Properties sensitive */
rect1:SELECTABLE IN FRAME A = YES.
rect1:MOVABLE IN FRAME A = YES.
rect1:RESIZABLE IN FRAME A = YES.
manipulable:SENSITIVE IN FRAME A = YES. /* All Properties sensitive */
manipulable:SELECTABLE IN FRAME A = YES.
manipulable:MOVABLE IN FRAME A = YES.
manipulable:RESIZABLE IN FRAME A = YES.
rect2:SENSITIVE IN FRAME A = YES. /* Movable, but not resizable */
rect2:MOVABLE IN FRAME A = YES.
rect2:RESIZABLE IN FRAME A = NO.
rect3:SENSITIVE IN FRAME A = YES. /* Resizable but not Movable */
rect3:MOVABLE IN FRAME A = NO.
rect3:RESIZABLE IN FRAME A = YES.
rect4:SENSITIVE IN FRAME A = YES. /* Not resizable or Movable */
rect4:SELECTABLE IN FRAME A = YES. /* but selectable */
rect4:MOVABLE IN FRAME A = NO.
rect4:RESIZABLE IN FRAME A = NO.
ENABLE ALL WITH FRAME a.
WAIT-FOR GO OF FRAME a.
Direct Manipulation
245
If you set any of the writable attributes in Table 241 to TRUE, Progress assumes that you want
the user to be able to perform direct manipulation on the widget. As a result, Progress interprets
user mouse actions differently and gives higher priority to those mouse events that are
associated with direct manipulation (see Table 242). For example, if you set a buttons
SELECTABLE attribute to TRUE, the user cannot choose the button with a mouse. To choose
the widget, the user must use the keyboard instead.
24.2 Mouse Buttons on Windows
On Windows, Progress maps the two logical buttons, MOVE and SELECT, to the left mouse
button. Every time the user presses the left mouse button, Progress must decide whether to
interpret it as either a MOVE or a SELECT. If the button is clicked (while pointing to a widget),
Progress interprets it as a SELECT. If the button is held down and dragged, Progress interprets
it according to the following rules:
If the mouse was pointing to an empty space in a frame, or to a nonmovable object,
Progress interprets it as a SELECT. Progress creates a selection box that the user can use
to select widgets (given that the frames BOXSELECTABLE attribute is set to TRUE).
All widgets contained within the selection box are selected; the widgets outside of the box
are deselected. For more information on selection boxes, see the Selecting Widgets
section.
If the mouse was pointing to a widget, Progress interprets it as a MOVE (given that the
widgets MOVABLE attribute is set to TRUE). If the widget is selected, Progress moves
the widget and all other widgets that were selected. If the widget is not selected, Progress
deselects all other selected widgets, selects the remaining widget, then moves the widget.
For more information on Progress logical mouse buttons, see Chapter 6, Handling User Input.
Table 242: Direct-manipulation Mouse Events
SELECTION STARTRESIZE
DESELECTION ENDRESIZE
EMPTYSELECTION STARTBOXSELECTION
STARTMOVE ENDBOXSELECTION
ENDMOVE
246
24.3 Selecting Widgets
When the user selects a widget, Progress, by default, surrounds the widget with a highlight box.
If the widgets RESIZABLE attribute is set to TRUE, the widgets highlight box also has small
boxes, called resize handles, along its edges. The user can use these handles to resize the widget.
Figure 241 shows the different highlight boxes.
Figure 241: Highlight Boxes
When the user selects a widget, Progress sets its SELECTED attribute to TRUE. You can
override this behavior by writing a trigger for the SELECTION event and having that trigger
return a NOAPPLY. You can prevent Progress from changing a widgets SELECTED
attribute to FALSE by writing a trigger for the DESELECTION event. You can also set the
SELECTED attribute to TRUE or FALSE from within your application. When a widget is
deselected, Progress sets its SELECTED attribute to FALSE by default.
A user must select a widget before resizing it. The user has two ways to select a widget:
Pointing and clicking
Box selecting
24.3.1 Selecting by Pointing and Clicking
When the user points to a field-level widget and clicks the SELECT button, Progress selects the
widget by default (given that the widgets SELECTABLE attribute is set to TRUE). Progress
also draws a highlight box around the widget and deselects all previously selected widgets. If
the user points at an empty space within a frame and clicks the SELECT button, Progress
deselects all previously selected object within the frame, and selects the frame if it is selectable.
To select a frame, the user must point to an empty space in the frame, the frames border, or the
frames title, and click the SELECT button.
Resize
Handles
Highlight Boxes
Direct Manipulation
247
When the user points to a field-level widget and clicks the EXTEND button (CTRL plus the
SELECT button), Progress toggles the selected state of the widget. If the widget was selected,
Progress deselects it. If the widget was not selected, Progress selects it. Progress draws or erases
highlight boxes according to the selected state of the widget. If the user points at an empty space
within a frame and clicks the EXTEND button, Progress toggles the frame selection.
You can override the Progress default behavior by writing triggers for the SELECTION and
DESELECTION events and having the triggers return a NOAPPLY.
24.3.2 Box Selecting
If the user holds down the SELECT or EXTEND button and drags the mouse, Progress draws
a selection box if the frames BOXSELECTABLE attribute is set to TRUE. Figure 242 shows
a selection box.
Figure 242: Selection Box
The appearance of the selection box is the same for both the SELECT and EXTEND buttons.
But the effect of the selection boxes is different depending on which button the user presses. If
the SELECT button is pressed, Progress selects all widgets completely contained within the
box. Progress deselects all other previously selected widgets outside of the box. Deselection
occurs on mouse down. If the EXTEND button is pressed, Progress toggles the selected state of
the widgets within the box. All widgets outside of the box remain unaffected.
The user can create and use selection boxes only on field-level widgets within a frame. If the
user moves the mouse pointer outside of the frame where the selection box was started, the
selection box is confined to the frame. When the user reenters the frame, Progress redraws the
selection box to the current mouse position.
Current
Mouse
Position
Selection Box Original Mouse-down Point
248
24.3.3 Sets of Selected Widgets
Within a frame, the user can simultaneously select multiple field-level widgets. The group of
selected widgets within a frame is called the set of selected widgets. Move operations that the
user performs on one selected widget also apply to the set of selected widgets. It is impossible,
however, for the user to perform a move operation against a widget whose attribute settings
dont allow for it. If a widgets MOVABLE attribute is set to FALSE, then the user cannot move
the widget, regardless of whether it is in the set of selected widgets.
24.4 Moving and Resizing Field-level Widgets
Follow these steps to move a widget or set of selected widgets:
1 To move more than one widget, select all widgets to move.
To move a single widget, put the mouse pointer inside the widget, press the MOVE button,
and drag the mouse.
2 Place the mouse pointer inside one of the selected widgets.
3 Press down the MOVE button and drag the mouse.
Progress draws a drag box (Figure 243) around each of the selected widgets; these drag boxes
move along with the mouse across the frame. A drag box is identical in appearance to a selection
box. When the user moves widgets, drag boxes hold their relative position as the user moves
them. A move operation only works for widgets whose MOVABLE attribute is set to TRUE.
Figure 243: Drag Boxes
Drag Boxes
Direct Manipulation
249
To resize a widget, the user must perform the following steps:
1 Select the widget to resize.
2 Place the mouse pointer on a resize handle of the selected widget.
3 Press down the SELECT button and drag the mouse.
Progress draws a drag box around the selected widget. The drag box changes in size as the user
moves the mouse across the frame. A resize operation only works for widgets whose
RESIZABLE attribute is set to TRUE.
Each resize handle allows the user to size a widget in a different direction. For example, if the
user chooses the top-middle resize handle, Progress resizes the widget vertically. If the user
chooses a corner resize handle, Progress resizes the widget diagonally in the direction of that
corner. See Figure 244.
Figure 244: Resize Operation
If the user resizes a fill-in field, Progress does not change the format of the field to accommodate
the greater amount of available space. You can, however, provide triggers for ENDRESIZE
events to modify the formats. You can use this feature to provide scrolling fill-ins. Set the
format to a large value, then set the widgets size to a small value. Progress will scroll the text
when the screen limit is reached.
During Resize
Operation
After Resize
Operation
Resize Handle Used
for Operation
Point Where User
Released Mouse Button
2410
24.5 Moving and Resizing Frames
To move a frame, the user must point the mouse pointer to the frames border (the title is
included in the border) when pressing down the MOVE button. Or the user can press SHIFT plus
the MOVE button. To resize a frame, the user must first select the frame.
24.6 Custom Highlights
To customize a design for widget highlighting, you can set the MANUALHIGHLIGHT
attribute to TRUE. When you set this attribute to TRUE, you override Progresss default
highlight style. For an example of how you might design your own highlighting style, look at
the following procedure.
This procedure displays two rectangles that the user can highlight. One of the rectangles uses a
customized style; the other rectangle uses the default highlight style. If the user selects both
rectangles, the output of the procedure appears as follows.
The rectangle on the left, rect1, uses the customized highlight style of filling in the rectangle;
the rectangle on the right, rect2, uses the default Progress highlight style.
p-manual.p
DEFINE RECTANGLE rect1 SIZE-PIXELS 40 BY 40 EDGE-PIXELS 3 NO-FILL.
DEFINE RECTANGLE rect2 SIZE-PIXELS 40 BY 40 EDGE-PIXELS 3 NO-FILL.
FORM SKIP(1) SPACE (1) rect1 SPACE(8) rect2 WITH FRAME a NO-LABELS.
rect1:SELECTABLE IN FRAME a = yes.
rect1:SENSITIVE IN FRAME a = yes.
rect1:MANUAL-HIGHLIGHT IN FRAME a = yes.
rect1:BGCOLOR = 1.
rect2:SELECTABLE IN FRAME a = yes.
rect2:SENSITIVE IN FRAME a = yes.
ON SELECTION OF rect1 IN FRAME a SELF:FILLED = yes.
ON DESELECTION OF rect1 IN FRAME a SELF:FILLED = no.
ENABLE rect1 rect2 WITH FRAME a.
WAIT-FOR GO OF FRAME a.
Direct Manipulation
2411
24.7 Interaction Modes
There are three modes that Progress can enter during a direct-manipulation session:
Move mode
Resize mode
Box-selecting mode
The user directs Progress to enter one of these modes by pressing the SELECT, EXTEND, or
MOVE button and holding it down. The mode entered is determined by where the users mouse
pointer is pointing and by what button the user pressed. For example, if the user presses down
the SELECT button while pointing to an empty space and drags the mouse, Progress enters
box-selecting mode (given that the frames BOXSELECTABLE attribute is set to TRUE). But
if the user presses the SELECT button when pointing at a resize handle, Progress enters resize
mode. If the user presses the MOVE button, Progress always enter move mode. You can direct
Progress not to enter a mode by writing a trigger for the event that causes Progress to enter the
mode; you can have that trigger return a NOAPPLY.
The mode Progress is in affects how Progress interprets mouse-move events and
mouse-button-release events. When the user releases the mouse button, Progress exits the mode
it is in. If the user is in move mode, Progress generates an ENDMOVE event. If the user is in
resize mode, Progress generates an ENDRESIZE event.
24.8 Direct-manipulation Events
Direct-manipulation events have general characteristics that you must know to use them
effectively. For example, some events only apply to frames while others apply to both frames
and field-level widgets. In addition, you need to know the order in which Progress generates
these events during mouse operations. The following sections describe both aspects of
direct-manipulation events.
24.8.1 General Characteristics
Before you can write a program that takes advantage of direct-manipulation events, you need to
know:
Which widgets Progress can send the event to in response to user actions
Which user actions initiate the event
How Progress responds to the event by default
2412
This information is described for each event in the following list. Additional comments are
added where necessary. Note that you can override the Progress default actions by writing a
trigger for the event and having that trigger return a NOAPPLY.
SELECT
Widgets: Frames and field-level widgets.
User actions: (1) The user clicks the SELECT button on a widget; (2) the user clicks the
EXTEND button on an widget that is not already selected; (3) the user uses the SELECT button
to draw a selection box around a widget; (4) the user uses the EXTEND button to draw a
selection box around a deselected widget.
Progress default actions: Progress draws a highlight box around the widget and sets its
SELECTED attribute to TRUE.
DESELECT
User actions: (1) The user clicks the SELECT button on another unselected widget; (2) the user
clicks the EXTEND button on a widget that is already selected; (3) the user clicks the SELECT
button on empty space in the frame; (4) the user starts a box-selecting operation with the
SELECT button.
Progress default actions: Progress erases the highlight box around the widget and sets its
SELECTED attribute to FALSE.
EMPTYSELECTION
Widgets: Frames and windows.
User actions: The user clicks the SELECT button on empty space in the frame or window (or
performs a box-selecting operation that does not include any widgets).
Progress default actions: None.
Comment: If the user clicks on an empty space, Progress deselects all selected widgets before
it sends the EMPTYSELECTION event to the frame or window.
Direct Manipulation
2413
STARTMOVE
User actions: The user presses down the MOVE button to start a move operation. For frames,
the user presses SHIFT plus the MOVE button.
Progress default actions: Progress selects the widget if its SELECTABLE attribute is set to
TRUE; if it is not already selected, Progress draws a drag box around the widget and enters
move mode. If there are selected widgets outside the frame being moved or outside of the frame
containing the field-level widgets being moved, Progress also sends DESELECTION events to
those widgets outside the frame. Deselection occurs on mouse down.
Comments: When the user clicks the MOVE button, Progress sends a STARTMOVE event
to every widget that is selected. If your application puts a trigger on STARTMOVE, and the
trigger returns NOAPPLY, then Progress does not enter move mode, and does not generate
subsequent ENDMOVE events.
ENDMOVE
User actions: The user releases the MOVE mouse button while Progress is in move mode (that
is, during a move operation).
Progress default actions: Progress moves the widget to its new location, redraws it there, and
exits move mode.
Comment: Progress generates an ENDMOVE event for each widget that the user moves.
STARTRESIZE
User actions: The user clicks the SELECT button on a resize handle of a widget (the widget
must be selected).
Progress default actions: Progress draws a drag box around the widget and enters resize mode.
ENDRESIZE
User actions: The user releases the SELECT mouse button while Progress is in resize mode
(that is, during a resize operation).
Progress default actions: Progress resizes the widget to correspond to the new size and
location of its drag box and exits resize mode.
2414
STARTBOXSELECTION
Widgets: Frames only.
User actions: The user starts to move the mouse button after having pressed the SELECT
mouse button.
Progress default actions: Progress draws a selection box, which initially appears quite small
but expands into a recognizable box when the user moves the mouse and enters box-selecting
mode.
Comment: If your application puts a trigger on STARTBOXSELECTION, and the trigger
returns NOAPPLY, then Progress does not enter box-selecting mode and does not generate
subsequent and ENDBOXSELECTION events.
ENDBOXSELECTION
Widgets: Frames only
User actions: The user releases the SELECT mouse button while Progress is in box-selecting
mode (that is, during a box-selecting operation).
Progress default actions: Progress normally erases the selection box and then sends a
SELECTION or DESELECTION event to each widget that is completely contained inside the
selection box. If the user starts the box-selecting operation by pressing the SELECT mouse
button, then Progress generates SELECTION events for all the widgets. If the user pressed
EXTEND instead, then Progress generates SELECTION events for the unselected widgets and
DESELECTION events for the selected widgets. Progress also exits box-selecting mode.
Direct Manipulation
2415
24.8.2 Order of Direct-manipulation Events
A few mouse actions may initiate a several events. The order in which Progress generates these
event depends on the type of operation the user performs.
The Box-selecting Operation
The following steps describe the order of events that Progress generates during a box-selecting
operation:
1 The user presses down and holds the SELECT or EXTEND button.
When the user presses SELECT, Progress generates an EMPTYSELECTION event.
Progress then generates a DESELECT event for all widgets that were selected. If the user
presses EXTEND, Progress generates a MOUSEEXTENDDOWN event.
2 The user begins to move the mouse.
Progress generates a STARTBOXSELECTION event for the frame.
3 The user releases the mouse button.
When the user releases SELECT, Progress generates DESELECTION events for all
selected widgets and SELECTION events for all of the widgets the user included in the
box-selecting operation. Then Progress generates an ENDBOXSELECTION event for
the frame. The key code that the mouse sends to Progress is MOUSESELECTUP.
When the user releases EXTEND, Progress generates SELECTION and DESELECTION
events for the widgets included in the box-selecting operation. Then Progress generates an
ENDBOXSELECTION event for the frame. The key code that the mouse sends to
Progress is MOUSEEXTENDUP.
2416
The Move Operation
The following steps describe the order of events that Progress generates during a move
operation:
1 The user presses down the MOVE button while the graphics pointer is pointed at a widget.
Progress generates a MOUSESELECTDOWN event.
Progress generates a STARTMOVE event for the widgets the user moves.
3 The user releases the mouse.
Progress generates an ENDMOVE event for each widget moved.
The Resize Operation
The following steps describe the order of events that Progress generates during a move
operation:
1 The user presses down the SELECT button while the graphics pointer is pointed at a
widgets resize handle.
Progress generates a MOUSESELECTDOWN event and then a STARTRESIZE
event.
Progress generates a STARTRESIZE event for the widget the user resizes.
3 The user releases the mouse.
Progress generates an ENDRESIZE event for the widget the user resized.
Direct Manipulation
2417
24.9 Grids
Progress allows the user to use grids to align widgets within frames. A grid is a framework of
crisscrossed bars whose width and height you can control by setting the appropriate attributes.
Figure 245 shows how a grid appears on screen.
Figure 245: Grid
The dots in Figure 245 are called visible grid points. The distance between two of these small
dots is called a minor grid unit. The distance between one grid line and another grid line is called
a major grid unit. Inside each of the squares on the grid there are invisible grid points (see
Figure 246).
Figure 246: Grid Enlargement
You can control the appearance of grids with the following attributes (these attributes apply to
frames only):
GRIDVISIBLE Determines whether the grid is visible or not.
GRIDFACTORHORIZONTAL Determines the number of horizontal minor grid
units per major unit.
GRIDFACTORVERTICAL Determines the number of vertical minor grid units
per major unit.
Invisible Grid Point
2418
GRIDSNAP Determines whether objects align to (snap to) the grid when the user
moves or resizes them.
GRIDUNITWIDTHCHARS Determines the width in character units of a minor
grid unit (that is, the distance in character units between adjacent horizontal grid points).
GRIDUNITWIDTHPIXELS Determines the width in pixels of a minor grid unit
(that is, the distance in pixels between adjacent horizontal grid points).
GRIDUNITHEIGHTCHARS Determines the height in characters of a minor grid
unit (that is, the distance in character units between adjacent vertical grid points).
GRIDUNITHEIGHTPIXELS Determines the height in pixels of a minor grid
unit (that is, the distance in pixels between adjacent vertical grid points).
When the user moves a widget and the frames GRIDSNAP attribute is set to TRUE, the
widgets upper left corner snaps to the nearest grid point. This is true even if the
GRIDVISIBLE attribute is set to FALSE. Note that widgets that are already placed in the
frame are not affected when you set GRIDSNAP to TRUE. However, if you move or resize a
widget in the frame, it then snaps to the nearest grid point.
25
Interface Design
This chapter describes issues that relate to the layout of your application interface. The topics
discussed include:
Progress windows
Frame characteristics
Frame design issues
Tab order
Active window display
Three-dimensional effects (Windows only)
Windows interface design options
252
25.1 Progress Windows
The user interface of a Progress application consists of one or more windows whose size and
number affect the space available for frames. Depending on your environment (character or
graphical), there are different factors to consider when you lay out frames. The following
sections describe these factors.
25.1.1 Character-based Environment
A character-based application can use only one window (the default window), which maps
directly to the terminal screen. Progress can accommodate character-based terminal screens of
different sizes. The space within the terminal screen, except for the bottom three lines, is
available to frames. Progress reserves two of these lines for error messages and messages
produced with the MESSAGE statement. Progress reserves the remaining line for status and
help messages.
Figure 251 shows the basic layout of a character-based Progress window.
Figure 251: Character-based Window
Message Area
Display Area
Space available for frames-- 21 or 22
lines, depending on terminal.
Space reserved by Progress-- two lines
for error messages and messages
produced by a MESSAGE statement,
one line for status and help messages.
Interface Design
253
Screen Variations
Most character-based terminal screens have 24 display lines, leaving 21 lines for frames. Some
have 25 display lines, leaving 22 lines for frames. Other systems might have more display lines.
To see how many lines are available, use the SCREENLINES function.
Character Display Height
You must size your frames to fit the display area. If you think some users might run your
application on terminals that have 24 lines while others might run on terminals with more lines,
design your frames to fit in the smaller display area. This way, you can be sure that your frames
display in either situation.
Character Display Width
You must also size your frames to fit the width of the terminal screen. Most terminal screens are
80 characters wide, although some are wider. You can take advantage of the entire width of your
terminal screen (up to 255 characters) when developing an application. However, if you take
advantage of screen width greater than 80 characters, your frames do not fit or look the same on
a screen with a smaller width.
Multi-window Simulation
Although character-based applications can only work with the terminal screen as a single
window, you can simulate multiple windows by providing a menu bar and changing that menu
bar for each simulated window context.
For example, suppose you want to simulate two windows with the following menu bars:
p-wbars.p
DEFINE MENU BasicWindow MENUBAR
MENU-ITEM mfile LABEL "File"
MENU-ITEM medit LABEL "Edit"
MENU-ITEM moptions LABEL "Options"
MENU-ITEM madvance LABEL "Advanced..."
MENU-ITEM mexit LABEL "E&xit".
DEFINE MENU AdvancedWindow MENUBAR
MENU-ITEM mspec LABEL "Special"
MENU-ITEM medit LABEL "Edit"
MENU-ITEM moptions LABEL "Calculations"
MENU-ITEM madvance LABEL "Basic...".
254
You can change between windows with code like this, used to complete p-wbars.p.
Of course, a real application likely has submenus in place of most of the menuitem entries
shown in this example.
For more information on creating menu bars and submenus, see Chapter 22, Menus.
25.1.2 Graphical Environment
A graphical application can create and use multiple windows, including the default static
window. Unlike character-based environments, where the window size is identical to the
terminal screen, applications in graphical environments can create windows with any
dimensions smaller, equal to, or larger than the terminal screen (with scroll bars, if necessary).
Also, whereas characters in character-based windows typically have a fixed size and font
(which is sometimes selectable), a graphical window can support many character sizes and
styles, depending on the application and user interface. Graphical windows can also support a
wide variety of frame sizes both smaller and larger than the window dimensions (with scroll
bars, if necessary).
Character Units and Pixels
In a graphical environment, window layouts are generally measured in pixels, not characters.
However, Progress lets you plan your window layout either in pixels or in character units. A
character unit is equal in height to a fill-in widget using the default system font; it is equal in
width to the average width of the characters in the default system font. Since the default system
font determines the size of a character unit, you must consider what system font will be used
when your application is running.
If you want your application to be portable across different platforms (or across different display
resolutions within a single platform), use character units to lay out your screen displays. This
way, you do not have to calculate your application layout in pixels, adjusting your calculations
for different screen resolutions or different platforms.
ON CHOOSE OF MENU-ITEM madvance
CURRENT-WINDOW:MENUBAR = MENU AdvancedWindow:HANDLE.
ON CHOOSE OF MENU-ITEM mbasic
CURRENT-WINDOW:MENUBAR = MENU BasicWindow:HANDLE.
CURRENT-WINDOW:MENUBAR = MENU BasicWindow:HANDLE.
WAIT-FOR CHOOSE OF MENU-ITEM mexit.
Interface Design
255
Character Unit and Pixel Conversion
Note that character units are decimal values and pixels are integer values in Progress. If you set
a pixel attribute to a decimal value, it is rounded to the nearest whole integer. This also means
that if you set a character unit attribute (such as HEIGHTCHARS) and then read it back,
Progress can return a different value than the one you set based on the actual corresponding
pixel value. This is a necessary rounding error because all graphic dimensions are ultimately
stored as pixels, and the nearest whole pixel dimension might not exactly match the character
units you specify.
For example, depending on the resolution and default system font of your interface, if you set
the HEIGHTCHARS attribute to 2.5, Progress might store and return its value as 2.51. This is
because 2.51 most closely matches the number of pixels corresponding to 2.5 character units.
Thus, if your application uses character units to track widget size and location, be sure to reset
your initial values to the values that Progress actually stores and returns.
Window Size
The window attributes in Table 251 let you query the interior size of a maximized window.
When a window is maximized, it fills the entire terminal screen. The values returned by these
attributes are the same whether or not the window is maximized.
The values returned by these attributes exclude the title bar, menu bar, message area, and status
area. The interior of a window cannot exceed the area returned by these attributes. For more
information on using graphical windows, Chapter 21, Windows.
Table 251: Maximized Window Attributes
FULLHEIGHTCHARS The interior height of the window in character units.
FULLHEIGHTPIXELS The interior height of the window in pixels.
FULLWIDTHCHARS The interior width of the window in character units.
FULLWIDTHPIXELS The interior width of the window in pixels.
256
Frame Borders
The frame attributes in Table 252 let you query the border widths of your frames.
The values returned by these attributes change depending on whether the frame is selectable or
movable. The BORDERTOP and BORDERTOPCHARS attributes also change if the frame
has a title.
Table 252: Frame Border Attributes
BORDERBOTTOMCHARS The height of the bottom frame border in character units.
BORDERBOTTOMPIXELS The height of the bottom frame border in pixels.
BORDERTOPCHARS The height of the top frame border in character units.
BORDERTOPPIXELS The height of the top frame border in pixels.
BORDERLEFTCHARS The width of the left frame border in character units.
BORDERLEFTPIXELS The width of the left frame border in pixels.
BORDERRIGHTCHARS The width of the right frame border in character units.
BORDERRIGHTPIXELS The width of the right frame border in pixels.
Interface Design
257
25.1.3 Alert Boxes
An alert box is a special dialog box for displaying Progress messages instead of displaying them
in the window message area. Alert boxes have no handles, attributes, or methods that you can
access, and they do not respond to trigger events. They exist only to display messages. For
information on defining and using dialog boxes for other purposes, see the Dialog Boxes
section.
You can have Progress display both application and system messages in an alert box using these
techniques:
To put application messages in an alert box, invoke the MESSAGE statement with the
VIEWAS ALERTBOX option.
To have all Progress system messages displayed in an alert box, set the
SYSTEMALERTBOXES attribute of the SESSION system handle to TRUE.
25.2 Frame Characteristics
You can change the overall characteristics of a frame by using Frame phrase options or by
setting frame attributes. The following sections describe these options and attributes and the
rules for setting them.
25.2.1 Using Frame Phrase Options
You can use a Frame phrase to describe the overall characteristics of a frame. A Frame phrase
always begins with the word WITH and is followed by one or more options. The following
procedure shows how you can use Frame phrases to control the appearance of your frames:
p-frm15.p
DISPLAY "Customer Credit Status Report"
WITH TITLE "Report Type" CENTERED.
FOR EACH customer:
DISPLAY name address credit-limit
WITH NO-BOX 10 DOWN CENTERED RETAIN 2.
END.
258
This procedure produces the the following output:
In this example, the first DISPLAY statement uses the Frame phrase WITH TITLE Report
Type CENTERED:
The CENTERED option centers the frame on the display screen.
The TITLE option names a title to use with the DISPLAY. Progress always places the title
in the center of the top line of the box that surrounds the frame being displayed.
The second DISPLAY statement displays customer information:
The 10 DOWN option displays only 10 customers on the screen at a time.
The RETAIN 2 option redisplays the last two customersat the top of the screen after
clearing the screen to make room for the next set of customers.
The CENTERED option centers the display of customer records.
Interface Design
259
For more information on Frame phrase options, see the Progress Language Reference.
25.2.2 Setting Frame Attributes
The following procedure shows how you can set frame attributes to control the appearance of
frames:
This procedure adjusts the height of frame using the HEIGHTCHARS attribute so that both a
and b fit on the screen. In each iteration of the FOR EACH loop, the procedure resets the title
of frame b to include the name of the current customer using the TITLE attribute.
p-frm16.p
DEFINE FRAME a
WITH DOWN USE-TEXT WIDTH 40 TITLE "Customers".
DEFINE FRAME b
salesrep
WITH USE-TEXT TITLE "Sales Rep".

FRAME a:HEIGHT-CHARS = SCREEN-LINES - (FRAME b:HEIGHT-CHARS + 1).
FOR EACH customer, salesrep OF customer WITH FRAME a:
FRAME b:TITLE = "Sales Rep for " + customer.name.
DISPLAY salesrep WITH FRAME b.
END.
2510
Many frame attributes correspond in name and function to the options of the Frame phrase. For
more information on frame attributes, see the reference entries for the FRAME Widget and for
the frame attributes in the Progress Language Reference.
Interface Design
2511
25.2.3 Rules for Frame Phrases and Attributes
When you use a Frame phrase or frame attribute, the phrase or attribute applies to the entire
frame regardless of the statements that use that frame. Different Frame phrases that apply to the
same frame cannot conflict. For example:
conflicts with:
You cannot simultaneously display the same frame at column 15 and column 30.
25.3 Frame Design Issues
There are several issues that you must consider when you design frames. For example, you
might want to use a certain background image for a frame. This section describes this and other
frame design issues.
25.3.1 Frame-level Design
The following procedure shows how Progress designs a frame:
DISPLAY name WITH FRAME a COLUMN 15.
DISPLAY address WITH FRAME a COLUMN 30.
p-frm17.p
DEFINE BUTTON del-button LABEL "Delete Customer"
TRIGGERS:
ON CHOOSE
DELETE customer.
END.
DEFINE BUTTON next-button LABEL "Find Another Customer" AUTO-GO.
DEFINE BUTTON quit-button LABEL "Quit" AUTO-ENDKEY.
REPEAT:
PROMPT-FOR customer.cust-num quit-button WITH FRAME a.
DISPLAY name.
UPDATE del-button next-button quit-button WITH FRAME a.
END.
2512
Every data-handling statement in a procedure serves two purposes:
To specify frame contents and layout at compile time
To cause frame activity at run time
When Progress compiles this procedure, it designs frames as follows:
The REPEAT block, since it displays data, automatically receives a frame. This frame is
an unnamed frame and is the default frame for the block.
The PROMPTFOR statement uses frame a, not the default frame for the REPEAT block
(because frame a is named explicitly). Progress sets up a frame that is large enough to hold
the custnum field and the quitbutton.
The DISPLAY statement does not name a specific frame, so it uses the default frame for
the REPEAT block. Progress allocates enough room in that frame for the name field.
The UPDATE statement also names frame a. Progress allocates more room in that frame
to hold the buttons delbutton and nextbutton (the frame initially was only big enough to
hold the custnum field).
To summarize, there are two frames used in this procedure. One frame, the default frame for the
REPEAT block, displays the customer name. The second frame, frame a, holds the custnum
field and three buttons.
These are the defaults Progress uses when designing a frame:
Start the frame in column 1, at the first free row on the screen.
Enclose the frame in a box.
Display field labels above fields (that is, use column labels).
Underline the column labels.
Make the frame as wide as necessary to accommodate all the items in the frame, adding
more lines if everything does not fit on one line.
Interface Design
2513
25.3.2 Field- and Variable-level Design
Progress designs frames at compile time. In a top-to-bottom pass of your procedure, the
Progress Compiler encounters fields, variables, and expressions and their related format
specifications. The Compiler adds these fields and expressions to the layout of the appropriate
frame. Progress always designs for all possible cases. That is, if there are several fields that
might be displayed in a frame, Progress makes room for all of them.
As Progress designs each frame, it makes some decisions regarding the individual fields and
variables in the frame:
All references to the same field or variable map to the same frame position.
If labels are above the data (column labels), each field or variable is allocated a column.
The width of the column is either the width of the format or the width of the label,
whichever is larger.
Array frame field labels are followed by a subscript number in square brackets. Progress
determines the labels at compile time. It omits subscripts if the array subscript is variable
or if you specify a label in the frame definition by using the LABEL keyword in a format
phrase.
Constants used in DISPLAY are treated as expressions, each occupying a separate frame
field.
For more information on field and variable display formats, see the DISPLAY Statement
reference entry in the Progress Language Reference. Also see Chapter 17, Representing Data.
in this manual.
25.3.3 FORM and DEFINE FRAME Statements
Often, you want to describe characteristics of a frame but do not want to include that description
in the Frame phrase of a data-handling statement. This is especially true if the frame
characteristics are very complex. You can use the FORM or DEFINE FRAME statements to
describe the layout and processing properties of a certain frame. Specifically, you use these
statements to:
Lay out frame fields in one order when you are going to process them in another order.
Describe frame headers and backgrounds.
2514
The FORM and DEFINE FRAME statements only describe the layout of a frame. They do not
actually bring the frame into view. To see the frame, you must use either a data-handling
statement that uses that frame or the VIEW statement, or set the frame VISIBLE attribute to
TRUE.
The location of the FORM statement affects the scope of your frame, so you must place any
FORM statements you use within the appropriate block or blocks of a procedure.
Normally, the first reference to a frame scopes the frame to the current block. However, the
DEFINE FRAME statement does not scope the frame. The FORM statement, like data handling
statements, does scope the frame. For more information on these statements, see the Progress
Language Reference.
Laying Out Frame Fields
When you are using a frame that has a very complex layout or when you want to use the same
frame layout many times in a single procedure, you can use the FORM or DEFINE FRAME
statements to describe the frame. That way, the frame description is in only one place, not
scattered throughout the procedure.
In the following procedure, the DEFINE FRAME statement describes the layout of frame a. By
default, Progress displays the fields in the order they appear in the DEFINE FRAME statement.
You can use the AT phrase to explicitly position a field. When you run the procedure and update
the fields, you move through them in the order they appear in the UPDATE statement. That is,
the order of the fields in the DEFINE FRAME (or FORM) statement affects the positions of the
fields, not their tab (or processing) order.
Interface Design
2515
When you run p-form4.p, press TAB to move through the fields. Notice that the cursor moves
among the fields in the order they are listed in the UPDATE statement:
NOTE: The AT n option, where n is an integer, specifies the column position of the field.
Progress chooses the row based on the previous widget and form item layout of the
frame. Form items include SKIP and SPACE. For more information on form items,
see the reference entries for the DEFINE FRAME statement and the FORM
statement in the Progress Language Reference.
p-form4.p
DEFINE FRAME a
name contact AT 40 SKIP
address credit-limit AT 40 SKIP
city customer.state NO-LABEL SKIP
postal-code AT COLUMN-OF customer.state ROW-OF city + 1 NO-LABEL
SKIP
phone balance AT COLUMN 40 ROW-OF city SKIP(1)
WITH SIDE-LABELS TITLE "Customer Maintenance".
ASSIGN customer.state:WIDTH-CHARS IN FRAME a = postal-code:WIDTH-CHARS.
DISPLAY balance.
UPDATE name address city state postal-code phone
contact credit-limit.
END.
2516
Note that because the DEFINE FRAME statement is used, the frame is scoped to the FOR
EACH block. It, therefore, becomes a down frame. A FORM statement would have scoped the
frame to the procedure block, making it a one-down frame. For more information on frame
scoping, see Chapter 19, Frames.
The syntax of the AT phrase of the FORM and DEFINE FRAME statements can specify either
the absolute column and row, or the X and Y coordinates of the display field. You can also
position a field relative to a previously positioned field.
For more information on this syntax, see the AT Phrase reference entry in the Progress
Language Reference.
SYNTAX
AT
{ n
| { COLUMN column | COLUMN-OF relative position }
{ROW row | ROW-OF relative-position }
|
{ X x | X-OF relative-position }
{Y y | Y-OF relative-position }
}
[ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ]
Interface Design
2517
The following sample fragment specifies X and Y coordinates for two fields in a frame:
If you position a field with X and Y coordinates, the position of the field depends on the
resolution of the terminal on which the procedure is compiled and run. For example, if the
resolution is 640 by 480 and you specify X 320, the field is displayed at the midpoint of the
display. If you run the same procedure on a display with a resolution of 1280 by 960, the field
is displayed at the one-quarter point of the screen.
Most interfaces provide a font that is compatible with the screen resolution. An 80-column
display width is common across most platforms. Therefore, if you use character (ROW and
COLUMN) coordinates rather than pixel (X and Y) coordinates, your code is more portable.
Because Progress allows you to specify fractional character units, you can still specify very
precise locations for a graphical environment. In a character environment, the ROW and
COLUMN values are truncated to integer values.
Describing Frame Headers
You can use the FORM or DEFINE FRAME statement to describe a header that appears at the
top of a frame. For example, the FORM statement in this procedure defines a frame that consists
of only a header. The VIEW statement brings that frame into view. The DISPLAY statement
uses a separate frame (the default frame for the FOR EACH block).
p-frm19.p
FORM
customer.cust-num AT X 50 Y 14
customer.name AT X 200 Y 50
WITH SIDE-LABELS FRAME xcust.
DISPLAY cust-num name WITH FRAME xcust.
p-form3.p
FORM HEADER "Customer Credit Status Report" WITH CENTERED.
VIEW.
FOR EACH customer WITH CENTERED:
DISPLAY name credit-limit.
END.
2518
Interface Design
2519
Form Backgrounds
The BACKGROUND option of the FORM and DEFINE FRAME statements allow you to
specify a rectangle or image to display in the background for a frame. The contents of the frame
(both header and data) are displayed on top of the background.
For example, the following procedure displays a rectangle in the background of a frame:
p-back.p
DEFINE RECTANGLE back-rect SIZE 50 BY 4 NO-FILL EDGE-PIXELS 1.
DEFINE FRAME x
customer.cust-num SKIP(2)
customer.name AT 5 SKIP
customer.address AT 5 SKIP
customer.address2 AT 5 SKIP
customer.city AT 5 customer.state customer.postal-code SKIP(2)
customer.phone customer.balance customer.sales-rep
BACKGROUND back-rect AT COLUMN 2 ROW 8
WITH USE-TEXT.
FOR EACH customer:
DISPLAY cust-num name address address2 city state postal-code
phone balance sales-rep WITH FRAME x.
END.
2520
Note that you must define a rectangle or image before referencing it in the DEFINE FRAME or
FORM statement.
25.3.4 FRAMEROW and FRAMECOL Options
When you design an application, you can control where a frame appears on the screen and where
one frame overlays another. Progress has several functions that let you control the position of
frames in relation to the screen and in relation to other frames.
In the following procedure, the FRAMEROW and FRAMECOL functions indicate the
location of the order-information frame on the customer-information frame.
NOTE: The FRAMEROW and FRAMECOL attributes have no relation to the
FRAMEROW and FRAMECOL functions. These attributes return the position of
a child field-level widget relative to the upper left-hand corner of the parent frame.
However, for child frames, the ROW and COLUMN attributes return the position
relative to the upper left-hand corner of the parent frame. For more information on
child frames, see Chapter 19, Frames.
Interface Design
2521
The FRAMEROW and FRAMECOL functions each return an integer value that represents
the row or column position of the upper-left corner of the named frame. In the example, the
FRAMEROW function returns the value of the row position of the uppermost corner of the
custframe. Then the procedure adds 8 to that value and displays the overlay frame at that row
position. The column position is calculated to be 1 to the right of the right edge of custframe.
p-frrow.p
cust-loop:
FOR EACH customer:
DISPLAY customer WITH FRAME cust-frame
2 COLUMNS TITLE "CUSTOMER INFORMATION".
FOR EACH order OF customer
ON ENDKEY UNDO cust-loop, LEAVE cust-loop:
DISPLAY order-num order-date ship-date promise-date
carrier instructions po
WITH 2 COLUMNS 1 DOWN OVERLAY TITLE "CUSTOMERS ORDERS"
ROW FRAME-ROW(cust-frame) + 8
COLUMN FRAME-COL(cust-frame) + 1.
END.
END.
2522
If you move custframe to the third row on the screen, the FRAMEROW and FRAMECOL
functions place the order information frame in the same position relative to the customer
information framebelow the eighth row and next to the first column of custframe. The
following procedure shows this adjustment.
p-frrow1.p
cust-loop:
FOR EACH customer:
DISPLAY customer WITH FRAME cust-frame ROW 3
carrier instructions po
COLUMN FRAME-COL(cust-frame) + 1.
END.
END.
Interface Design
2523
See the Progress Language Reference for more information on the FRAMEROW and
FRAMECOL functions.
In most cases, a dialog box is better than an overlay frame. For example, p-frrow2.p is similar
to p-frrow1.p, but uses a simple dialog box instead of the overlay frame:
When you run this code in a graphical interface, you can move the dialog box to see all the data
in both frames. For more information, see the discussion of dialog boxes later in this chapter.
p-frrow2.p
DEFINE BUTTON ok-button LABEL "OK" AUTO-GO.
DEFINE BUTTON cancel-button LABEL "CANCEL" AUTO-ENDKEY.
cust-loop:
FOR EACH customer:
DISPLAY customer WITH FRAME cust-frame ROW 3
carrier instructions po SKIP
ok-button AT 25 cancel-button AT 50
COLUMN FRAME-COL(cust-frame) + 1
VIEW-AS DIALOG-BOX.
SET ok-button cancel-button.
END.
END.
2524
25.3.5 Positioning Frames with FRAMELINE
The FRAMELINE function gives you information on the position of the current display line
in a frame. The following procedure uses this information to determine how to display other
information in the frame:
The p-frline.p procedure lets the user update a customers number, name, and credit limit.
The procedure displays information in the frame for one customer at a time. You can press
CTRLG at any time to see a prompt to delete the customer. The prompt always appears in its
own frame, below the last customer displayed.
p-frline.p
DEFINE VARIABLE ans AS LOGICAL LABEL
"Do you want to delete this customer?".
DEFINE FRAME a customer.cust-num customer.name customer.credit-limit.
STATUS INPUT "Enter data, or press CTRL-G to delete the customer".
ON CTRL-G OF customer.cust-num, customer.name, credit-limit
DO:
UPDATE ans WITH ROW FRAME-ROW(a) + 2 + FRAME-LINE(a) COLUMN 10
SIDE-LABELS OVERLAY FRAME del-frame.
IF ans THEN DELETE customer.
HIDE FRAME del-frame.
END.
REPEAT WITH FRAME a 10 DOWN:
FIND NEXT cust.
UPDATE cust-num name credit-limit.
END.
Interface Design
2525
The FRAMELINE function in this procedure controls where the ans variable is displayed. The
position of the prompt is calculated from the upper-right corner of frame a and the current line
within the frame. That is, FRAMEROW + 1 + FRAMELINE gives the position of the current
line in the frame, taking into account the lines for the frame box and the labels. The prompt is
placed below the current line.
See the Progress Language Reference for more information on the FRAMELINE function.
25.3.6 Positioning Frames with FRAMEDOWN
The FRAMEDOWN function returns the number of iterations that can fit in a frame. You can
use this function to determine if a down frame is full. Then Progress can perform an action based
on the value of FRAMEDOWN.
For example, you can display all the customers in the database, which takes several screens. If
the customer you want to see is on the first screen, it is time-consuming to press RETURN until
every customer in the database is listed and the procedure ends. The following procedure uses
the FRAMEDOWN function to solve this problem:
p-frdown.p
DEFINE VARIABLE ans AS LOGICAL.
FOR EACH customer:
DISPLAY cust-num name credit-limit.
IF FRAME-LINE = FRAME-DOWN
THEN DO:
MESSAGE "Do you want to see the next page?" VIEW-AS ALERT-BOX
QUESTION BUTTONS YES-NO TITLE "Screen Full"
UPDATE ans.
IF NOT ans
THEN LEAVE.
END.
END.
2526
Each time the frame becomes full, the question Do you want to see the next page? appears in
a dialog box. If you answer No, the procedure ends.
In this procedure, the FRAMEDOWN function returns the number of iterations that can fit in
a frame, and the FRAMELINE function returns the current logical line in a frame. When the
current logical line equals the number of lines in the frame, the procedure displays the message
Do you want to see the next page? and gives the user the option to continue or to end the
procedure.
Interface Design
2527
Note that the DOWN and LINE attributes are analogous to the FRAMEDOWN and
FRAMELINE functions.
See the Progress Language Reference for more information on these functions and attributes.
25.3.7 Scrolling Frames
Scrolling frames are specialized down or one-down frames that allow the user to move a
highlight bar through multiple iterations of data. Most often, scrolling frames are down frames.
You use the SCROLL Frame phrase option together with the CHOOSE statement to create this
type of frame.
NOTE: This feature is supported for backward compatibility. You can usually use either a
browse widget or selection list instead of CHOOSE and SCROLL. For more
information on browse widgets, see Chapter 9, Database Access. For information
on selection lists, see Chapter 17, Representing Data.
The SCROLL statement opens a row and moves data in a frame with multiple rows. You can
use the SCROLL statement to scroll data up or down to display another line in a frame. The
following procedure shows how you might use this statement:
p-scroll.p (1 of 3)
DEFINE VARIABLE current_line AS INTEGER.
FORM customer.cust-num customer.name customer.address
customer.city customer.postal-code
WITH FRAME cust-frame SCROLL 1 5 DOWN WIDTH 90.
2528
REPEAT current_line = 1 TO 5:
DISPLAY cust-num name address city postal-code
IF NOT AVAILABLE customer
THEN LEAVE.
END.
UP 5 WITH FRAME cust-frame.
REPEAT:
STATUS DEFAULT
"Use up and down arrows. Enter C to create, D to delete".
CHOOSE ROW customer.cust-num NO-ERROR GO-ON(CURSOR-RIGHT)
FIND customer WHERE cust-num = INTEGER(INPUT cust-num).

/* React to moving cursor off the screen */
IF LASTKEY = KEYCODE("CURSOR-DOWN")
THEN DO:
THEN FIND FIRST customer.
NEXT.
END.
IF LASTKEY = KEYCODE("CURSOR-UP")
THEN DO:
THEN FIND LAST customer.
UP WITH FRAME cust-frame.
NEXT.
END.
p-scroll.p (2 of 3)
Interface Design
2529
/* CHOOSE selected a valid key. Check which key. */
IF KEYLABEL(LASTKEY) = "c"
THEN DO:
/* Open a space in the frame */
SCROLL FROM-CURRENT DOWN WITH FRAME cust-frame.
CREATE customer.
UPDATE cust-num name address city postal-code
NEXT.
END.
IF KEYLABEL(LASTKEY) = "d"
THEN DO:
/* Delete a customer from the database */
DELETE customer.
SCROLL FROM-CURRENT WITH FRAME cust-frame.
current_line = FRAME-LINE(cust-frame).
DOWN FRAME-DOWN(cust-frame) - FRAME-LINE(cust-frame) - 1
/* Place cursor on last active line in frame */
FIND customer WHERE cust-num = INTEGER(INPUT cust-num).
THEN FIND FIRST customer.
UP FRAME-LINE(cust-frame) - current_line
/* Move cursor back to where it was at start of block */
END.
END.
STATUS DEFAULT.
p-scroll.p (3 of 3)
2530
Use the arrow keys to move the highlighted bar to the fifth customer. Type C for create.
Interface Design
2531
At this point, you can add a new customer to the database by typing the customer information
on the open line. The p-scroll.p procedure uses SCROLL and CHOOSE to allow the user to
browse through information, then perform actions with the information.
The p-scroll.p procedure creates a scrolling frame of five fields. The frame displays the
custnum, name, address, city, and postalcode for each customer. The status default message
displays Enter C to create, D to delete as long as the procedure runs. You use arrow keys to
move the highlighted cursor bar through lines of the scrolling frame, and you can add or delete
customers from the database. The CHOOSE statement allows you to move the highlight bar.
The SCROLL statement controls the scrolling action in the frame when you create and delete
customers. You add a customer to the database by typing C. Create opens a line in the frame
and the SCROLL statement moves data below the line down. Then you type the new customer
information into the frame. You type D to delete a customer from the database. When you delete
a customer, SCROLL moves the rows below the deleted customer row up into the empty line.
The p-scroll.p procedure works as follows:
The SCROLL option on the Frame phrase creates a scrolling frame for the customer
information.
The CHOOSE statement allows the user to scroll through the list of customer numbers
with a highlighted bar, and it also allows the user to select a location to insert or delete an
item from the list.
When the user types C for create, the SCROLL FROMCURRENT DOWN statement
opens a space for another customer above the highlighted customer.
When the user types D for delete, the SCROLL FROMCURRENT statement closes the
space left by the deleted customer. However, when you use a SCROLL
FROMCURRENT statement, Progress opens a line at the bottom of the scrolling frame.
The remaining statements in this block fill in the opened frame line with record
information.
The p-scroll.p procedure uses UP and DOWN statements to control the current cursor
position. These statements behave differently with scrolling frames than with regular down
frames. If the cursor is on the top line of a frame, the UP statement opens a line at the top of the
screen and moves the remaining frames lines down one line. This is also what happens if you
use the SCROLL DOWN statement. Similarly, if the cursor is on the bottom line of a frame, the
DOWN statement opens a line at the bottom of the screen and moves the remaining frame lines
down one line.
2532
25.3.8 Scrollable Frames
You can define a scrollable frame that is bigger than the display space allotted for it. The user
can then use scroll bars to view the entire frame.
You can explicitly set the maximum dimensions of a frame with the
VIRTUALWIDTHPIXELS, VIRTUALHEIGHTPIXELS,
VIRTUALHEIGHTCHARS, and VIRTUALWIDTHCHARS attributes. You can specify
the display size of the frame with the SIZE option of the Frame phrase, as shown below.
If the SCROLLABLE attribute is FALSE, the frame is forced to fit into the display space. If
SCROLLABLE is TRUE, then if the size as specified by the SIZE phrase does not fit within the
display area, only a portion of the frame is displayed and scroll bars appear.
The SCROLLABLE option defaults to TRUE if you use the SIZE option; otherwise, it defaults
to FALSE.
For example, the following code defines a frame, chooseframe, that is bigger than its display
size:
SYNTAX
{ SIZE | SIZE-CHARS | SIZE-PIXELS } width BY height
p-scrlab.p
FORM
Customer.name Customer.address Customer.address2
Customer.city Customer.st
WITH FRAME choose-frame 33 DOWN SIZE 40 BY 5.
FOR EACH customer BREAK BY Customer.name:
DISPLAY name address address2 city st
WITH FRAME choose-frame.
IF NOT LAST(customer.name)
THEN DOWN WITH FRAME choose-frame.
END.
REPEAT:
CHOOSE ROW Customer.name WITH FRAME choose-frame.
FIND customer WHERE Customer.name = FRAME-VALUE.
DISPLAY customer WITH SIDE-LABELS.
END.
Interface Design
2533
If you run this code and select Urpon Frisbee, the following screen appears:
You can use scroll bars to move within chooseframe (in the upper-left corner of the display)
to see basic information on each customer. You can then choose to see more information on an
individual customer.
In character interfaces, you can scroll a frame by pressing SCROLLMODE (ESCT on most
terminals). This enters a separate scroll mode in which you can scroll the frame one row or
column at a time with the cursor keys. You can page up and down with the PAGEUP,
PAGEDOWN, END, HOME, RIGHTEND, and LEFTEND keys. No other frame input is possible
in scroll mode. To exit scroll mode, press SCROLLMODE or ENDERROR.
2534
25.3.9 Strip Menus
A strip menu is a one-down frame that allows you to move a highlight bar between fields in an
array or among fields in a table.
NOTE: Strip menus are supported for backwards compatibility. You can use buttons or menu
widgets instead.
The following procedure sets up a simple strip menu:
p-strip.p
DEFINE VARIABLE abc AS character EXTENT 3
INITIAL ["Add", "Update", "Delete"].
DISPLAY abc NO-LABELS WITH ROW 8 CENTERED
TITLE "Customer Maintenance".

CHOOSE FIELD abc AUTO-RETURN.
IF FRAME-VALUE = "add" THEN MESSAGE "Add customer".
IF FRAME-VALUE = "update" THEN MESSAGE "Update customer".
IF FRAME-VALUE = "delete" THEN MESSAGE "Delete customer".
Interface Design
2535
The p-strip.p procedure defines the array abc with an extent of 3 to display the selections on
the menu. The CHOOSE statement allows you to move the highlight bar among the three fields
in the array and to select a highlighted item by pressing RETURN. Progress displays a message
based on the item CHOOSE holds in the frame. In your own application you can have Progress
perform an action based on the item the user selects.
2536
You can also use the CHOOSE statement to create a strip menu that appears at the bottom of
the screen. The following procedure shows how you might do this:
p-chsmnu.p
DEFINE VARIABLE menu AS CHARACTER EXTENT 4 FORMAT "x(7)"
INITIAL [ "Browse", "Create" , "Update", "Exit" ].
DEFINE VARIABLE proglist AS CHARACTER EXTENT 4
INITIAL [ "brws.p", "cre.p", "upd.p", "exit.p"].
FORM "Use the sample strip menu to select an action."
WITH FRAME instruc CENTERED ROW 5.
REPEAT:
VIEW FRAME instruc.
DISPLAY menu
WITH NO-LABELS ROW SCREEN-LINES - 2 NO-BOX FRAME f-menu CENTERED.
HIDE MESSAGE.
CHOOSE FIELD menu AUTO-RETURN WITH FRAME f-menu.
IF SEARCH(proglist[FRAME-INDEX]) = ?
THEN DO:
MESSAGE "The program" proglist[FRAME-INDEX] "does not exist.".
MESSAGE "Please make another choice.".
END.
ELSE RUN VALUE(proglist[FRAME-INDEX]).
END.
Interface Design
2537
2538
Use the arrow keys to move the highlight bar through the available selections and press RETURN
when the bar highlights the selection you want. Because this is a sample procedure, none of the
items perform actions other than returning messages.
Now look back at the p-chsmnu.p procedure. The procedure defines two arrays with an extent
of four. The menu array holds the items for selection on the menu, and the proglist array holds
the names of the programs associated with the menu selections. The CHOOSE statement allows
the user to select an item from the strip menu. Progress finds the number in the menu array
associated with the item, and then finds the program associated with the number in the proglist
array. Progress runs the program if it exists. If it does not exist, Progress displays a message and
allows the user to select another item from the strip menu.
In most cases, you use the SCROLL statement with the CHOOSE ROW statement to perform
the actual work of selecting an item from a scrolling menu and taking an action based on that
item.
25.3.10 Dialog Boxes
You can choose to display a frame as a dialog box. A dialog box appears in its own window
overlaying the current window. The window manager allows the user to move the dialog box
around the screen.
Interface Design
2539
To display a frame as a dialog box, specify the VIEWAS DIALOGBOX option within the
Frame phrase. For example, the following procedure defines a dialog box.
p-diagbx.p
DEFINE BUTTON update-cust LABEL "Update Customer".
DEFINE BUTTON ok-button LABEL "OK" AUTO-GO SIZE 8 BY 1.
DEFINE BUTTON cancel-button LABEL "Cancel" AUTO-ENDKEY SIZE 8 BY 1.
DEFINE VARIABLE curr-rec AS ROWID.
FORM
custb SKIP(1)
update-cust AT 3 cancel-button AT 25
SKIP(1)
WITH FRAME main-frame CENTERED.

FORM
country name address address2 city state postal-code contact
phone sales-rep credit-limit balance terms discount comments SKIP(1)
ok-button AT 15 cancel-button AT 50
WITH FRAME upd-frame TITLE "Customer Update" VIEW-AS DIALOG-BOX.
FRAME upd-frame:HIDDEN = TRUE.
ENABLE ok-button cancel-button WITH FRAME upd-frame.

ON CHOOSE OF update-cust OR MOUSE-SELECT-DBLCLICK OF custb
DO: /* Transaction */
curr-rec = ROWID(customer).
FIND customer WHERE ROWID(customer) = curr-rec EXCLUSIVE-LOCK.
UPDATE customer EXCEPT cust-num WITH FRAME upd-frame.
END.

OPEN QUERY custq FOR EACH customer.
2540
When you run p-diagbx.p, you get the following output:
Interface Design
2541
25.3.11 Frames for Nonterminal Devices
Progress designs frames independently of the output destination of the frame, which is not
determined when the procedure runs, but when it is compiled. However, there are special
considerations when you design frames for display on something other than a terminal screen.
If you display frames to nonterminal devices, the following rules apply:
Unless you use the NOBOX Frame phrase option, Progress omits the bottom line of the
box and converts the top line to blanks. In addition, Progress does not print or reserve
space for the sides of the box.
Progress does not output a frame until it executes a data-handling statement that uses
another frame or until it executes a PUT statement. It collects all the changes to the frame
and sends only one copy of the frame to the output destination.
Progress ignores the ROW Frame phrase option. See the PUT statement in the Progress
Language Reference for more information on controlling the format of output to
nonterminal devices.
25.3.12 Multiple Active Frames
You can enable input for several frames simultaneously. In a graphical environment, the user
can move among the active frames with the mouseselecting any enabled field in a frame
makes that the current frame.
In a character or graphical interface, the user can move to the next or previous frame with the
NEXTFRAME and PREVFRAME keys. However, this moves focus between root frames
parented by the same window, not between child frames in the same frame family.
You can adjust the spacing between frames in a window by setting the FRAMESPACING
attribute of the SESSION system handle. Its value specifies the number of display units between
frames (pixels in graphical interfaces and character cells in character interfaces). By default, the
value of FRAMESPACING is the height of one row in the default system font.
The following procedure uses two frames to update the customer and salesrep records. They are
spaced according to the default value for FRAMESPACING:
2542
p-frm18.p
FORM
customer
WITH FRAME cust-frame TITLE "Customer".

FORM
salesrep WITH FRAME rep-frame TITLE "Salesrep".

ON LEAVE, GO OF customer.cust-num
DO:
FIND customer USING customer.cust-num.
FIND salesrep OF customer.
DISPLAY customer WITH FRAME cust-frame.

ENABLE ALL WITH FRAME rep-frame.
DISABLE customer.cust-num WITH FRAME cust-frame.
END.
ON GO OF FRAME cust-frame, FRAME rep-frame
DO:
IF FOCUS <> customer.cust-num:HANDLE IN FRAME cust-frame
THEN DO:
ASSIGN customer.
ASSIGN salesrep.
RUN reset-frames.
END.
END.
ON END-ERROR OF FRAME cust-frame, FRAME rep-frame
DO:
IF FOCUS <> customer.cust-num:HANDLE IN FRAME cust-frame
THEN DO:
RUN reset-frames.
RETURN NO-APPLY.
END.
END.

PROCEDURE reset-frames:
CLEAR FRAME cust-frame.
CLEAR FRAME rep-frame.
DISABLE ALL WITH FRAME rep-frame.
APPLY "ENTRY" TO customer.cust-num IN FRAME cust-frame.
END PROCEDURE.
Interface Design
2543
The procedure initially prompts for a customer number. It then displays the customer record in
frame custframe and the associated salesrep record in frame repframe. Fields in both frames
are enabled for input. The cursor is initially placed in the custframe frame, but you can move
to repframe to modify the salesrep information. Note that the ASSIGN statements within the
GO trigger are necessary to preserve any changes you make to either record.
25.4 Tab Order
Tab order is the order in which field-level widgets receive TAB events in a frame family. Each
frame in a frame family has a separate tab order for the widgets that it owns, and each child
frame participates in the tab order of the field-level widgets owned by its parent frame. That is,
child frames are tab-order siblings of the field-level widgets owned by the same parent frame.
Thus, the tab order of field-level widgets in a frame family depends on how the individual tab
orders of the member child frames are organized.
25.4.1 Tab Order for a Frame
The tab order of widgets in a frame is affected by four factors:
1. The order in which you place widgets within the frame definition.
When Progress compiles a procedure, it lays out all the field-level widgets in static frames
used by the procedure, and assigns the default tab order in the order the widgets appear in
the frame definition. For a dynamic frame, Progress makes the default tab order the order
in which you assign the widgets to the frame. When parenting a child frame or dynamic
field-level widget to a static or dynamic frame, the parented widget assumes the last
position in the current tab order of the frame, by default.
2. The statements you use to enable the widgets for input in a static frame.
The PROMPTFOR, SET, and UPDATE statements explicitly enable widgets and change
their tab order. The ENABLE statement also establishes tab order if you explicitly enable
widgets by name. However, if you ENABLE ALL widgets for a frame, the tab order is not
affected.
2544
3. Whether a static frame is defined with, or its definition is modified by, the
KEEPTABORDER option.
This option tells Progress that all statements that enable widgets for input, including the
ENABLE, PROMPTFOR, SET, and UPDATE statements will have no effect on the
frames tab order.
4. Whether you use methods or attributes to change the tab order.
The MOVEAFTERTABITEM( ) and MOVEBEFORETABITEM( ) methods
allow you to change the tab order of field-level widgets and child frames, overriding the
above considerations. At the fieldgroup level, you can also change the tab order of
field-level widgets and child frames using the FIRSTTABITEM and
LASTTABITEM attributes.
You can return the current tab order (relative to 1) of any field-level widget or child frame by
reading its TABPOSITION attribute. The NUMTABS attribute for the field group returns the
number of field-level widgets and child frames that have tab positions, and the
GETTABITEM( ) method for the field group returns the widget handle of the widget with the
specified tab position. You can also obtain the widget handle of the previous or next widget in
the tab order by reading its PREVTABITEM or NEXTTABITEM attribute, respectively.
25.4.2 Tab Order for a Frame Family
Once you have established the tab orders for the widgets of each frame in a frame family, the
tab order proceeds according to these definitions:
Tab-order widget A tab-order widget is a widget in a frames tab order, and can be
either a field-level widget or a child frame.
Tab item A tab item can only be a field-level widget that receives focus. If a child
frame occupies a tab item position, the actual first tab item in the child frame is the first
field-level widget descending in the tab order of the widgets owned by the child frame; the
actual last tab item in the child frame is the last field-level widget descending in the tab
order of the widgets owned by the child frame.
Interface Design
2545
Next tab item If the current tab item is the last field-level widget in the frame family
tab order, the next tab item is the first field-level widget in the frame family tab order. If
the current tab item is the last tab-order widget of a child frame, the next tab item is the
next widget in the tab order of the parent frame. If the next widget in the tab order of the
parent frame is a field-level widget, the next tab item is that field-level widget. If the next
widget in the tab order of the parent frame is a child frame, the next tab item is the first
descendant tab item of the child frame. If the current tab item is not the last tab-order
widget of a frame, the next tab item is determined from the next tab-order widget of the
frame.
Previous tab item If the current tab item is the first field-level widget in the frame
family tab order, the previous tab item is the last field-level widget in the frame family tab
order. If the current tab item is the first tab-order widget of a child frame, the previous tab
item is the previous widget in the tab order of the parent frame. If the previous widget in
the tab order of the parent frame is a field-level widget, the previous tab item is that
field-level widget. If the previous widget in the tab order of the parent frame is a child
frame, the previous tab item is the last descendant tab item of the child frame. If the current
tab item is not the first tab-order widget of a frame, the previous tab item is determined
from the previous tab-order widget of the frame.
Note that you cannot tab between frame families, only within a single frame family.
Figure 252 shows a frame family with four frames. Thus, the tab-order widgets in frame
FRAME 1 include:
Buttons RED, GREEN, and BLUE
Fill-in Field1
Frame FRAME 2
Frame FRAME 3
The tab-order widgets in frame FRAME 2 include:
Buttons RED, GREEN, and BLUE
Fill-in Field2
Frame Frame 4
2546
The tab-order widgets in frame Frame 4 include only fill-in Field4, and in frame FRAME 3
include buttons RED, GREEN, and BLUE, and fill-in Field3.
Figure 252: Frame Family Tab Order
However, the actual tab items include the respective RED, GREEN, and BLUE buttons and the
Field1, Field2, Field3, and Field4 fill-ins.
Interface Design
2547
The following procedure (p-foftab.p) displays the frames in Figure 252. Note that because
FRAME f4 is assigned to the frame family before FRAME f3, f4 comes before f3 in the default
tab order:
p-foftab.p (1 of 2)
DEFINE BUTTON bred1 LABEL "RED".
DEFINE BUTTON bgreen1 LABEL "GREEN".
DEFINE BUTTON bblue1 LABEL "BLUE".
DEFINE VARIABLE field1 AS CHARACTER LABEL "Field1".
DEFINE FRAME f1 SKIP(.5)
SPACE(18) bred1 bgreen1 bblue1 field1
WITH SIDE-LABELS TITLE "FRAME 1" KEEP-TAB-ORDER
SIZE 80 BY 11.5.
SPACE(3) bred2 bgreen2 bblue2 SKIP(.5) SPACE(1) field2
SPACE(3) bred3 bgreen3 bblue3 SKIP(.5) SPACE(1) field3
SPACE(1) field4
WITH SIDE-LABELS TITLE "Frame 4" KEEP-TAB-ORDER
SIZE 26 BY 3 AT COLUMN 2.5 ROW 4.5.
2548
25.4.3 Tabbing and DATAENTRYRETURN
When you set the DATAENTRYRETURN attribute of the SESSION handle to TRUE, focus
changes to the next tab item for any fill-in that receives a RETURN event. However, if the fill-in
is the last tab item in the frame family, instead of tabbing back to the first tab item, focus remains
in the fill-in and a GO event is applied to all frames of the frame family. Thus, in p-foftab.p,
pressing the RETURN key in field3 causes a GO event to be applied to each of frames f1, f2, f3,
and f4. The GO event is also applied in order from the innermost child frame to the root. As
indicated in Figure 252, the event fires in order of frame f4, f2, f3, and then f1.
FRAME f2:FRAME = FRAME f1:HANDLE.
CURRENT-WINDOW:TITLE = "Frame Family Tab Behavior".
ON MOUSE-SELECT-CLICK, GO, TAB, RETURN ANYWHERE DO:
MESSAGE LAST-EVENT:FUNCTION "of" SELF:TYPE
IF SELF:TYPE = "FRAME" OR SELF:TYPE = "WINDOW"
THEN SELF:TITLE ELSE SELF:LABEL.
END.
SESSION:DATA-ENTRY-RETURN = TRUE.
p-foftab.p (2 of 2)
Interface Design
2549
25.5 Active Window Display
When you display a message, alert box, or dialog box, you generally want the message or widget
displayed in or near the window where the user is working. In multi-window applications,
especially those managed by persistent procedures, it is possible for the user to be working in
one window and have a persistent procedure display a dialog box in another. This can occur
because the current window of the persistent procedure that displays the dialog box might not
be the window where the user is working. The procedure controlling the users window might
be calling an internal procedure whose parent persistent procedure has a different current
window.
To ensure that your messages, alert boxes, and dialog boxes get displayed in the window the
user is working in, you can specify the ACTIVEWINDOW system handle for the IN
WINDOW option of the appropriate I/O statement. The ACTIVEWINDOW handle always
references the session window that has most recently received input focus. For an example using
the ACTIVEWINDOW handle and more information on managing multi-window
applications, see Chapter 21, Windows.
25.6 Three-dimensional Effects (Windows only; Graphical interfaces only)
On Windows, in graphical interfaces, you can specify that all widgets in a particular frame or
dialog box have a three-dimensional look and feel. (In character interfaces, this specification is
ignored.) By default, buttons, sliders, and browses already display with a three-dimensional
appearance. By specifying the THREED Frame phrase option or by setting the THREED
frame or dialog box option to TRUE, most other widgets in the specified frame or dialog box
display with a three-dimensional appearance, including the toggle box, radio set, editor,
selection list, and combo box widgets. This also means that the frame background color
becomes color Button Face rather than color Window. Note that you can only set the THREED
attribute before the frame or dialog box is realized.
NOTE: The THREED look and feel is the preferred style on Windows 95 and Windows NT
4.0 platforms. The THREED style provides an overall consistent look to the user
interface, thereby accommodating such widgets as the combo box, radio set, toggle
box, and LARGE editor, which cannot be displayed in two dimensions on these
platforms.
2550
The following procedure, p-threed.p, displays two frames that are identical, except that one is
two-dimensional and the other is three-dimensional.
p-threed.p
DEFINE VARIABLE vSlide AS INTEGER LABEL "Slider"
DEFINE VARIABLE vToggle AS LOGICAL LABEL "Toggle"
VIEW-AS TOGGLE-BOX.
DEFINE VARIABLE vRadio AS INTEGER LABEL "Radio Set"
VIEW-AS RADIO-SET RADIO-BUTTONS "First", 1, "Middle", 2, "Last", 3.
DEFINE VARIABLE vEdit AS CHARACTER LABEL "Editor"
VIEW-AS EDITOR SIZE 60 by 2.
DEFINE VARIABLE vCombo AS CHARACTER LABEL "Combo Box"
VIEW-AS COMBO-BOX LIST-ITEMS "Red", "White", "Blue", "Purple".
DEFINE FRAME D2-Frame
vSlide vToggle vRadio SKIP vEdit SKIP vCombo SKIP bOK
WITH AT COLUMN 8 ROW 1.1 SIDE-LABELS
TITLE "Two Dimensional Frame".
DEFINE FRAME D3-Frame
vSlide vToggle vRadio SKIP vEdit SKIP vCombo SKIP bOK
WITH AT COLUMN 8 ROW 9 THREE-D SIDE-LABELS
TITLE "Three Dimensional Frame".

CURRENT-WINDOW:TITLE = "".
ENABLE ALL WITH FRAME D2-Frame.
ENABLE ALL WITH FRAME D3-Frame.
WAIT-FOR CHOOSE OF bOK IN FRAME D2-Frame OR
CHOOSE OF bOK IN FRAME D3-Frame.
Interface Design
2551
When you run p-threed.p, the following window appears:
25.6.1 THREED, Rectangles, and Images
Rectangles and images do not automatically acquire three-dimensional characteristics when you
specify THREED for a frame. Rectangles must have border widths of two or more pixels to
display in a three-dimensional style. Images are completely unaffected by THREED. This
avoids any indication that you can interact with them. If you want, you can achieve
three-dimensional effects for an image by displaying it on an appropriate rectangle or by
including the effects within the image itself.
2552
25.6.2 THREED and Window Widgets
You can also set the THREED attribute of the window to change the window background to
color Button Face, which matches three-dimensional frames. However, this is the only effect of
changing the THREED attribute for windows. Frame and dialog boxes do not inherit this
attribute value from windows. You must set this attribute before the window is realized.
25.6.3 2D and 3D Widget Size Compatibility
Three-dimensional widgets are different widgets and have different sizes than corresponding
two-dimensional widgets. This means that you must adjust your layouts to accommodate them.
Note that the height of a three-dimensional fill-in is larger than that of a character unit.
However, the height of a two-dimensional fill-in is, by default, the same as that of a
three-dimensional fill-in to provide layout compatibility between them.
If you want two-dimensional fill-ins to equal the height of a character unit, you must set the
Use3DSize key to No in the current environment, which might be the registry or an
initialization file. However, where two standard fill-in fields fit neatly on ROW 1 COLUMN 1
and ROW 2 COLUMN 1, two three-dimensional fill-in fields do not. For more information on
the Use3DSize key, see the section on specifying three-dimensional size in the chapter on
user interface environments in the Progress Client Deployment Guide. For more information on
setting keys in the current environment, see the reference entry for the PUTKEYVALUE
statement in the Progress Language Reference.
25.7 Windows Interface Design Options
When developing Progress applications in the Windows environment, you can incorporate
various elements that Progress supports to update the look and feel of your user interface. These
elements include:
ToolTip information
Windows system help
Small icon size
25.7.1 Incorporating Tooltip Details
ToolTips allow you to define a help text message for a text field or text variable. A ToolTip is
a runtime attribute that can be defined for the following widgets: browse, button, combo box,
editor, fill-in, image, radio-set, rectangle, selection-list, slider, text, and toggle box. However,
they are typically used with a button widget. Progress automatically displays this text when the
user pauses the mouse pointer over a widget for which a ToolTip value is defined.
Interface Design
2553
You can define ToolTip values using the TOOLTIP option available for the DEFINE family of
statements, the VIEW-AS phrase, or setting the TOOLTIP attribute of a widget. You can add
or change the TOOLTIP value at any time. If a ToolTip value is set to either or ? (the
unknown value), then the ToolTip is removed. The default is no ToolTip.
For more information on setting ToolTip values, see the specific DEFINE statement, VIEW-AS
phrase, or widget reference entry in the Progress Language Reference.
25.7.2 Accessing the Windows Help Engine
On Windows, Progress supports the SYSTEMHELP statement, which calls the Windows Help
engine, winhlp32.exe. The Windows Help engine displays a Help viewer, which displays Help
topics and lets the user navigate them. The SYSTEMHELP statement lets you, the developer,
integrate Windows help into your Progress application.
For more information on the SYSTEM-HELP statement, see the SYSTEMHELP Statement
reference entry in the Progress Language Reference. For a complete discussion of how to
provide on-line help for Progress applications, see the Progress Help Development Guide.
25.7.3 Displaying the Small Icon Size
The LOAD-ICON() and the LOAD-SMALL-ICON() methods allow you to associate icons
with windows. The LOADICON() method allows you to specify an icon to display in the title
bar of a window (maximized), in the task bar (minimized), and when selecting a program using
ALTTAB . The LOADSMALLICON() method allows you to specify an icon to display in the
title bar of a window and in the task bar only.
The value you assign with either the LOADICON() or the LOADSMALLICON() methods
must be the name of an icon (.ico) file. Both of these methods accommodate icons formatted
as small size (16x16), regular size (32x32), or both. However, their treatment of the small and
regular size icons differ.
The LOADICON() method looks for an icon defined as 32x32 pixels by default and will shrink
it down to 16x16 pixels if necessary. The resolution of an icon that is changed in this manner
may not be suitable for all icon images. Therefore, the alternative LOADSMALLICON()
method that looks for icons defined as 16x16 pixels by default when there are multiple icons in
an icon file may be more suitable for your icon style and presentation.
2554
A
R-code Features and Functions
R-code is the intermediate binary code that Progress generates when it compiles 4GL source
files. This is the code that Progress actually runs when it executes a procedure, whether from
session compiles or from permanently generated r-code (.r) files.
Progress provides a dynamic r-code execution environment, as well as integrity and security
mechanisms to ensure that your r-code is running in a compatible environment.
This appendix provides information about the following topics:
R-code structure
R-code libraries
R-code libraries and PROPATH
R-code execution
R-code portability
Code page compatibility
Database CRCs and time stamps
R-code CRCs and procedure integrity
A2
A.1 R-code Structure
R-code is divided into multiple segments of varying length. Each r-code file contains an object
header and segment location table followed by the actual r-code segments. The object header is
a fixed-length descriptor that identifies the file as an r-code file and contains information about
the version and size of the r-code file. The segment location table is a variable-length descriptor
that contains the size and location of each r-code segment in the file. The maximum size for
most segment types is 62K.
Table A1 describes and lists the types, maximum size, and maximum number of segments in
an r-code file.
Table A1: R-code Segments (1 of 2)
Segment
Type
Max.
Size
Max.
Number Description
Action code 62K 1 per
procedure
Holds the actual executable code in the form of
action cells. Action cells drive the Progress
interpreter and contain the executable code for
4GL verbs. There is a separate action code
segment for the main procedure and each
internal procedure.
Expression code 62K 4 Holds the executable expressions in Reverse
Polish Notation (RPN) for the main procedure,
all internal procedures, and all trigger blocks. An
r-code file can have up to 248K of executable
expressions.
Text 62K 1 per
language
Holds all literal character strings for the r-code
file. There is one text segment for the default
language and one for each language specified in
the COMPILE statement. Duplicate literals are
removed. Only one text segment is loaded into
memory at run time.
Initial value 62K 1 Contains information required to initialize an
r-code file for execution, including database and
table references, variable definitions,
TEMPTABLE and WORKTABLE
definitions, a list of defined frames, time stamps,
and CRCs. There is one initial value segment per
r-code file.
A3
A.1.1 Factors that Affect R-code Size
You can affect r-code size by how you write your 4GL, depending on the r-code segment. The
action code and initial value segments are among the most tunable.
Action Code Segment
You can reduce the size of the action code segment by consolidating multiple 4GL statements
into one. This also can increase the speed of execution, because the interpreter executes only
one action instead of several.
For example, you can reduce action code size by combining several consecutive assignment
statements into one ASSIGN statement.
NOTE: Both of these examples require the same amount of expression code.
Frame 32K 1 per
frame
Contains layout information for a frame,
including frame fields, attributes, and all RPN
expression code from the frame phrase. There is
one frame segment for each named and unnamed
frame in the r-code file. Each frame segment has
a 32K limit.
Debugger 62K 1 Used by the Application Debugger to maintain
the debugger context for the procedure. There is
one debugger segment per r-code file. This
segment is loaded into memory on demand only
when the Debugger is active. For information
about the Debugger, see the Progress Debugger
Guide.
a = 1.
b = 2.
c = 3.
ASSIGN a = 1
b = 2
c = 3.
Table A1: R-code Segments (2 of 2)
Segment
Type
Max.
Size
Max.
Number Description
A4
Initial Value Segment
You can reduce the size of the initial value segment by limiting the number of SHARED
variables that are accessed in a procedure. The r-code required to support a SHARED variable
is larger than the r-code to support a NEW SHARED variable. Progress uses approximately 36
additional bytes in the initial value segment to resolve each SHARED variable at run time. This
value can change depending on the environment.
A.1.2 R-code File Segment Layout
Figure A1 shows the segment layout in an r-code file. A compiled procedure requires one
initial value segment, one action code segment, one expression code segment, one text segment,
and one debugger segment. There can be more action and expression code segments, up to the
limit, as required by your procedure. There can be multiple frame segments, one segment for
each frame in your procedure. The maximum number of frame segments is virtually unlimited.
There can also be multiple text segments, one segment for the default language and each
language that you choose for translation. The default language segment contains the literal
character strings defined in the original 4GL source file. You can create additional text segments
by using the Translation Manager. Although multiple text segments are possible, only one text
segment is available per language. Thus, the literal character strings for a given language cannot
exceed 62K. For more information about natural language translation for 4GL procedures, see
the Progress Translation Manager Guide.
A5
Figure A1: R-code File Segment Layout
A.2 R-code Libraries
You can organize and store r-code files in a Progress r-code library. A Progress r-code library
is a collection of r-code procedures combined in a single file. R-code libraries allow you to
manage and execute r-code procedures more efficiently. You create r-code libraries by using the
PROLIB utility.
Progress provides two types of r-code libraries: standard and memory-mapped. A standard
library contains r-code procedures that execute in local memory. A memory-mapped library
contains r-code procedures that execute in shared memory.
Object Header
Segment Location Table
Initial Value Segment
Action Code Segment (Main Procedure)
Expression Code Segment
Up to Four
Action Code Segment (Internal Procedure)
One per Internal Procedure
Frame Segment
One per Frame
Text Segment
One per Language
Debugger Segment
A6
For information about using the PROLIB utility to create r-code libraries, see the Progress
A.3 R-code Libraries and PROPATH
The following rules govern how standard and memory-mapped libraries interact with
PROPATH during a Progress session:
The first time you run a member procedure from a standard or memory-mapped library
that is specified in the PROPATH, Progress locates the procedure by searching through
each directory and library in the PROPATH until it finds the procedure. To search a library
for a member procedure, Progress must open the library. When Progress opens a standard
library, it loads the procedure into local memory. When Progress opens a memory-mapped
library, it maps the library in shared memory.
When searching through directories and libraries in the PROPATH, Progress starts at the
beginning of the PROPATH and searches each directory and library, in defined order, until
it finds the procedure. Thus, placing the library at the beginning of the PROPATH
improves performance.
A library remains open until the end of your Progress session or until you remove the
library from the PROPATH. If you remove a library from the PROPATH while a member
procedure is still active (either running, or waiting for a subprocedure to return), Progress
displays an error message and the library remains open until you end your Progress
session. Otherwise, Progress closes a standard library and unmaps a memory-mapped
library.
If you use a SEARCH or RUN statement to open a library that is not in the PROPATH,
the library remains open until you end your Progress session.
If you use libraries, Progress accesses r-code files as if you had specified the Quick
Request (q) startup parameter. That is, Progress searches the PROPATH only on the first
reference to a procedure. Thereafter, if the procedure still resides in memory, in the local
session compile file, or in an r-code library, Progress reuses the procedure instead of
searching the PROPATH again. For more information about the Quick Request (q)
startup parameter, see the Progress Startup Command and Parameter Reference.
A7
A.4 R-code Execution
Progress executes r-code procedures in different ways, depending on whether you store the
r-code files in an r-code library and the type of library.
When executing an r-code procedure from an operating system file in a directory, or from a
standard r-code library, Progress accesses and executes the r-code file segments in an execution
buffer in local memory. For more information about the standard r-code execution environment,
see the Standard R-code Execution Environment section later in this appendix.
When executing an r-code procedure from a memory-mapped r-code library, Progress accesses
and executes the r-code file segments in shared memory. For more information about the
memory-mapped r-code execution environment, see the Memory-mapped R-code Execution
Environment section later in this appendix.
For information about monitoring execution environment activity during a Progress client
session, see the R-code Execution Environment Statistics section later in this appendix.
For information about monitoring and optimizing r-code performance, see the Progress Client
Deployment Guide.
A.4.1 Standard R-code Execution Environment
At run-time, Progress manages the execution of a standard r-code procedure from either an
operating system file or a standard procedure library using the following components:
Execution buffer The portion of local memory that Progress allocates and uses to store
the chain of loaded r-code segments for all procedures executing in local memory.
Session sort file (.srt) A file that Progress uses to dynamically swap r-code segments
in and out of the execution buffer.
Segment descriptor table An in-memory table that references the r-code segments
required by all executing procedures, including the location of each r-code segment in the
execution buffer and usage count information.
R-code directory An in-memory table that contains information about each executing
r-code procedure, including r-code size, usage count, segment descriptions, and a
reference to the segment descriptor table for each segment.
Progress uses the segment descriptor table and the r-code directory to manage r-code procedures
from operating system files, standard libraries, and memory-mapped libraries.
A8
Figure A2 shows the layout for the standard r-code execution environment.
Figure A2: Standard R-code Execution Environment
In Figure A2, Progress located and loaded the cust.r and orders.r files into local memory
from either operating system files or standard libraries. The execution buffer is shown with three
cust.r segments and two orders.r segments. Note that one orders.r segment is located in the
execution buffer, while the other segment is swapped to the session sort file. When space in the
execution buffer is needed for new r-code segments, Progress uses the session sort file to swap
out the least-recently used segments. When Progress needs a segment that has been swapped to
the session sort file, it reloads the segment from the session sort file into the execution buffer.
orders.r
Segment Descriptor Table
.srt
File
R-code Directory
R-code
Segment
R-code
Segment
R-code
Segment
R-code
Segment
R-code
Segment
R-code
Segment
cust.r cust.r Main Action Code
cust.r Text
orders.r Initial Value
cust.r Initial Value
orders.r Main Action Code
Execution Buffer
A9
Standard Execution Sequence
When you run a standard r-code procedure for the first time, from either an operating system
file or a standard library, Progress loads and executes the procedure as follows:
1. Opens the procedure file (.p or .r) or procedure library (.pl), if the library is not already
open.
2. Reads the r-code procedure into memory and creates an r-code directory entry for the
procedure. Progress first compiles a procedure into r-code, if necessary.
3. Registers each required r-code segment in the execution environment as follows:
a. Loads the r-code segment at the head of the segment chain in the execution buffer
b. Adds an r-code segment entry to the segment descriptor table that references the
segment in the execution buffer
c. Inserts a segment descriptor reference in the r-code directory entry for the procedure
If all the required r-code segments do not fit in the execution buffer, Progress attempts to
free space by swapping r-code segments already in the buffer to the session sort file. If
Progress cannot free enough space by swapping segments, it increases the execution buffer
ceiling and allocates more space for the execution buffer.
NOTE: When accessing r-code procedures stored in a standard library, Progress does not
swap r-code segments to the session sort file unless you specify the PROLIB
Swap (pls) startup parameter. By default, if Progress needs an r-code segment
in a standard library, it reloads the segment into the execution buffer from the
library in local memory.
4. Once the required r-code segments in the procedure are registered in the execution
environment, the interpreter begins executing the r-code procedure at the start of the main
action code segment and accesses the remaining segments directly from local memory as
required.
A10
Standard Execution Environment Limits
The number of standard r-code procedures that you can run at one time and the memory used
are determined by the following factors:
R-code directory size The default is 100 entries, the minimum is 5 entries, and the
maximum is 500. You can set the initial number of entries using the Directory Size (D)
startup parameter. Progress dynamically increases the directory size up to the maximum,
as required. Use the Hardlimit (hardlimit) startup parameter to force Progress to adhere
to the limit specified by the Directory Size (D) startup parameter. .
Execution buffer ceiling The default is 3096K. You can set the initial ceiling for this
buffer up to 65,534K using the Maximum Memory (mmax) startup parameter. Progress
dynamically increases the execution buffer size up to the maximum, as required. Use the
Hardlimit (hardlimit) startup parameter to force Progress to adhere to the limit specified
by the Maximum Memory (mmax) startup parameter.
Available memory Available memory is a factor only if it is smaller than the execution
buffer ceiling or Progress needs to allocate memory beyond that ceiling.
Standard R-code Segment Management
While Progress loads an r-code file, all of its segments are locked in memory. After all required
segments are loaded for the procedure, Progress unlocks all segments except its main action
code and text segment. These two segments stay locked in memory until execution of the r-code
file terminates. Internal procedure action code segments stay locked only until they return to the
invoking procedure and are relocked each time they execute.
When a standard r-code segment does not fit in the execution buffer, Progress attempts to free
space by swapping r-code segments already in the buffer to the session sort file. Progress can
swap out any unlocked segments. Progress removes these segments from the tail end of the
execution buffer chain, in least recently used (LRU) order.
If Progress cannot free enough memory for a newly loaded segment by swapping out older
segments, it dynamically increases the maximum execution buffer size (execution buffer
ceiling) and allocates the required memory up to the memory available.
When Progress needs a segment that has been swapped to the sort file, it reloads the segment
from the sort file into the execution buffer. However, Progress keeps the reloaded segments in
the sort file.
NOTE: When accessing r-code procedures stored in a standard library, Progress does not
swap r-code segments to the session sort file unless you specify the PROLIB Swap
(pls) startup parameter. By default, if Progress needs an r-code segment in a
A11
standard library, it reloads the segment into the execution buffer from the library in
local memory.
A.4.2 Memory-mapped R-code Execution Environment
At run time, Progress manages the execution of memory-mapped r-code procedures using the
following components:
Shared memory buffer The portion of shared memory that the operating system
allocates and uses to store r-code segments for procedures in a memory-mapped procedure
library.
Segment descriptor table An in-memory table that references the r-code segments
required by all executing procedures, including the location of each r-code segment in
memory and usage count information.
R-code directory An in-memory table that contains information about each executing
r-code procedure, including r-code size, usage count, segment descriptions, and a
reference to the segment descriptor table for each segment.
Progress uses the segment descriptor table and the r-code directory to manage r-code procedures
from operating system files, standard libraries, and memory-mapped libraries.
A12
Figure A3 shows the layout for the memory-mapped r-code execution environment.
Figure A3: Memory-mapped R-code Execution Environment
In Figure A3, Progress located the cust.r and orders.r files in a memory-mapped library.
Note that all r-code segments in a memory-mapped library are located in shared memory. When
Progress needs a segment, it executes the segment directly from shared memory.
Memory-Mapped Execution Sequence
When you run a memory-mapped r-code procedure for the first time, Progress loads and
executes the procedure as follows:
1. Opens the procedure library, if not already open, and memory-maps the library in shared
memory.
2. Reads the r-code procedure and creates an r-code directory entry for the procedure.
R-code
Segment
R-code
Segment
R-code
Segment
R-code
Segment
R-code
Segment
Segment Descriptor Table

R-code
Directory
cust.r
orders.r
cust.r Main Action Code
cust.r Text
orders.r Initial Value
cust.r Initial Value
orders.r Main Action Code
Shared Memory
Buffer
A13
3. Registers each required r-code segment in the execution environment as follows:
a. Adds an r-code segment entry to the segment descriptor table that references the
segment in shared memory
b. Inserts a segment descriptor reference in the r-code directory entry for the procedure
4. Once the required r-code segments in the procedure are registered in the execution
environment, the interpreter begins executing the r-code procedure at the start of the main
action code segment and accesses the remaining segments directly from shared memory
as required.
Memory-Mapped Execution Environment Limits
The number of memory-mapped r-code procedures that you can run at one time and the shared
memory used are determined by the following factors:
R-code directory size The default is 100 entries, the minimum is 5 entries, and the
maximum is 500. You can set the initial number of entries using the Directory Size (D)
startup parameter. Progress dynamically increases the directory size up to the maximum,
as required. Use the Hardlimit (hardlimit) startup parameter to force Progress to adhere
to the limit specified by the Directory Size (D) startup parameter.
Available memory The number of memory-mapped r-code libraries you can have
open is limited by the amount of shared memory available on the system.
Memory-Mapped R-code Segment Management
When Progress needs a memory-mapped r-code segment, it executes the segment directly from
shared memory. Progress does not store active memory-mapped r-code segments in the
execution buffer. Nor does it swap non-active segments to the session sort file. Progress relies
on the operating system to manage the swapping of r-code segments in and out of shared
memory.
A.4.3 R-code Directory Management
If the r-code directory is full when loading a new standard or memory-mapped r-code file,
Progress can reuse existing directory entries for any r-code files no longer in use.
To reuse an r-code directory entry, Progress performs the following steps:
1. Identifies the least recently used (LRU) r-code file.
2. Frees the r-code directory entry for the LRU r-code file.
A14
3. Frees all of the segment descriptor entries in the segment descriptor table for the LRU
r-code file.
4. When reusing a standard r-code directory entry, Progress removes all r-code segments for
the LRU r-code file from both the execution buffer and the session sort file. When reusing
a memory-mapped r-code directory entry, the memory-mapped r-code file remains
mapped in shared memory.
When Progress needs to reload a standard r-code file, it follows the standard execution
sequence. When Progress needs to reload a memory-mapped r-code file, it follows the
memory-mapped execution sequence.
A.4.4 R-code Execution Environment Statistics
You can monitor execution environment activity using the Statistics (y) and Segment Statistics
(yd) startup parameters. These parameters cause Progress to write memory statistics to the
client.mon file. The yd parameter provides all of the information about memory usage
available with y plus additional information about r-code segments loaded during a client
session. For more information about the yd and y startup parameters, see the Progress Startup
For information about monitoring and optimizing r-code performance, see the Progress Client
Deployment Guide.
Figure A4 through Figure A8 show sections of client.mon output generated with the yd
startup parameter.
In Figure A4, the Progress client startup options section shows the r-code directory size
(D), in this case, set to the default of 100 entries. The y startup parameter also generates this
information.
Figure A4: Progress Client Startup Options for yd
Wed Mar 23 10:38:04 1994
Progress client startup options:
-A = 0 | -d = mdy | -D = 100 | -h = 7
.
.
.
R-code Directory Size
A15
In Figure A5, the Execution buffer map section shows the order and size of procedures
loaded into the execution buffer.
Figure A5: Execution Buffer Map for yd
In Figure A6, the Per procedure temp file access statistics section lists each r-code segment
that has been read or written to the session sort file (.srt). Each segment is listed under its r-code
file by segment type (IntProc Action), number (5), and size (1364 bytes).
Figure A6: Accessing the Session Sort File for yd
In this example, all segments shown have been read and written once. A large number of
segments read or written a large number of times indicates a likely need for more memory.
Execution buffer map: 11:27:28
Size Name
---- ----
3813 _edit.r
182871 adeedit/_proedit.r
1321 adecomm/_setcurs.r
R-code files listed in

order of execution with
sizes in bytes
Per procedure temp file access statistics:
Segment Read/Write Times Bytes
------- ---------- ----- -----
_edit.r
E-code seg: 1 Read 1 508
E-code seg: 1 Write 1 508
adeedit/_proedit.r
E-code seg: 1 Read 1 44476
E-code seg: 1 Write 1 44476
Int-Proc Action: 5 Read 1 1364
Int-Proc Action: 5 Write 1 1364

R-code files listed in
order of execution
showing segments
read and written to
the session sort file
A16
In Figure A7, the Per procedure segment information section lists all the r-code segments
loaded during the session. Each segment is listed under its r-code file by segment type
(IntProc), number (2), and size (816 bytes).
Figure A7: Procedure Segment Information for yd (Part 1)
Thus, if there are five internal procedure action segments in adeedit/_prodedit.r, they are
listed in order (1 through 5). The number of segments for each entry is always 1. Note that the
Initial and main Action segments have no segment number, because there is never more
than one of these segment types per r-code file.
Per procedure segment information
---------------------------------
File Segment #Segments Total-Size
---- ------- --------- ----------
_edit.r
Initial 1 1556
Action 1 736
E-Code: 1 1 508
Text: 1 1 273
adeedit/_proedit.r
Initial 1 4368
Action 1 21708
E-Code: 1 1 44476
Int-Proc: 1 1 496
Int-Proc: 2 1 816
.
.
.
R-code files listed in order
of execution showing all
segments loaded during
the session
A17
In Figure A8, the listed sections provide memory and segment usage summaries. The y
startup parameter also generates this information.
Figure A8: Procedure Segment Information for yd (Part 2)
The R-code Execution Buffer statistics show how far your application pushes the execution
buffer ceiling. The Segment Descriptors Usage statistics shows how close your application is
to running out of segment descriptors, and thus, whether you need to optimize the number of
r-code segments in your application.
A.5 R-code Portability
R-code is portable between any two environments if the following are true:
The user interface is the same graphics mode or character mode.
NOTE: If a procedure contains no user interface code, its r-code can run across user
interfaces without change. This is typical, for example, of database schema
trigger procedures.
The DataServer or combination of DataServers connected during compilation is the same.
The machine classes are compatible.
All machines that require four-byte alignment or less are compatible. Thus, r-code compiled on
one of these machines (for example, a Sun SPARCstation) can run on most other machines. One
of the few machines not compatible with this class is the AS/400, which requires greater than
four-byte alignment.
-----------------------------------------
Program access statistics: Times Bytes
.
.
.
Memory usage summary: Current Max Used Limit (Bytes)
Stack usage (-s): 60 7248 40960
Local buffer usage: 864 14704
R-code Execution Buffer: 530025 710609 710656
Segment Descriptors Usage: (numbers)
Max Used: 508 Limit: 720
------------------------------------------------
A18
Thus, you can use the same r-code compiled for Windows on any DataServer-compatible
Windows system, and you can use the same r-code compiled in character mode on any
DataServer-compatible character-mode system.
A.6 Code Page Compatibility
The Internal Code Page (-cpinternal) startup parameter determines the internal code page that
Progress uses in memory. The code page in which r-code is compiled and the internal code page
of the session in which the r-code runs must be compatible. That is, the r-code code page must
be either the internal code page, undefined, or convertible to the internal code page.
If the code page for a standard r-code procedure, from either an operating system file or a
standard library, is not the same as the sessions internal code page, Progress performs an
in-memory conversion of the r-code text segments to the sessions internal code page.
NOTE: If you use the R-code In Code Page (cprcodein) startup parameter to specify a code
page for reading r-code text segments, Progress reads the text segments as if they
were written in that code page, even if the text segments were written in a different
code page.
Since r-code procedures in memory-mapped procedure libraries are read-only, Progress cannot
perform an in-memory code page conversion of r-code text segments. If the code page of a
memory-mapped r-code procedure is not compatible, Progress will not execute the r-code. It
will report an error and stop execution.
For more information about the Internal Code Page (cpinternal) and R-code In Code Page
(cprcodein) startup parameters, see the Progress Startup Command and Parameter Reference.
A.7 Database CRCs and Time Stamps
At run time, Progress must ensure that r-code files and the database(s) that they access are
compatible. Otherwise, if the schema has changed since the code was compiled, running the
code might damage the database. Progress supports two techniques for checking this
compatibilitytime stamp validation and cyclic redundancy check (CRC) validation. Each
technique prevents you from running unauthorized or data-incompatible procedures against a
particular database environment.
A19
A.7.1 Time Stamp Validation
For each table, Progress maintains a time stamp indicating when the schema was last changed.
When compiling a procedure, Progress inserts the time stamp into the r-code for each database
table accessed by the procedure. This time stamp is the value of the _Lastchange field in the
metaschema _File record for each table. Note that sequence changes have no effect on time
stamp validation.
R-code Execution with Time Stamps
When executing a procedure using time stamp validation, Progress checks to make sure that the
time stamps for all accessed tables match those contained in the r-code. If a time stamp does not
match, the procedure does not execute.
To use time stamp validation, compile the procedure with each database connected using the
Time Stamp (tstamp) connection parameter. Otherwise, Progress uses CRC validation.
NOTE: The Time Stamp (tstamp) parameter is obsolete, and is supported only for backward
compatibility.
A.7.2 CRC Validation
For each table, Progress computes a CRC value (database CRC) from selected elements of the
table metaschema. When compiling a procedure, Progress inserts the database CRC for each
database table the procedure accesses. The database CRC for each table is stored in the
metaschema _File record _CRC field for the table. A matching CRC ensures that the schema
referenced by the r-code is compatible with the table schema, regardless of its time stamp.
Time Stamps and CRCs
Time stamps and CRCs both help maintain database integrity, but they do it differently. Time
stamps change whenever a table schema is updated or recreated at another time or place; CRCs
change only when certain schema elements critical to field or record definitions change. As long
as a table is structurally compatible with the r-code that references it, the CRCs match and the
r-code can execute. It does not matter when or where the tables schema was created or updated.
R-code Execution with CRCs
When executing a procedure using CRC validation, Progress follows these steps:
1. For each table accessed by the r-code, check the time stamp. If it matches, execute the
procedure. Otherwise, go to Step 2.
2. If the table is in a database that was not connected using the Time Stamp (tstamp)
parameter when the procedure was compiled, check the CRC. If it matches, execute the
procedure. Otherwise, reject the procedure.
A20
Thus, if the time stamps match, Progress assumes that the database schema and r-code must be
compatible. Otherwise, the CRCs determine the outcome.
compatibility.
A.7.3 CRC Calculation
Table A2 lists the metaschema fields that are involved in each CRC calculation.
CRC Calculation for Tables
All of the listed metaschema fields, participate in the CRC calculation for each database table.
The resulting CRC is stored in the _CRC field of the _File record for each table. A change to
any of these fields automatically changes the value of _CRC.
Table A2: Metaschema Fields in CRC Calculation
Metaschema Table
_File _Field _Index _IndexField
_FileName
_DBlang
_FieldName
_DataType
_dtype
_sysfield
_fieldrpos
_Decimals
_Order
_Extent
_Fldstdtype
_Fldstlen
_Fldstoff
_Fldcase
_IndexName
_Unique
_numcomp
(_FieldName)
1
_Ascending
_Abbreviate
_Unsorted
1
The _FieldName for index fields is referenced in the _Field table using _Fieldrecid in _IndexField.
A21
A.7.4 CRC Versus Time Stamp Validation
The main advantage of using CRC validation is that you can run the same r-code against
different databases as long as the databases have sufficiently similar schemas. This allows you
to deploy code and database updates while avoiding either of the following effects:
Forcing the user to dump and reload their data into a new database that you supply with
new r-code
Forcing the user to compile new source code (possibly encrypted) that you supply with
new data definitions to update their database schema
Depending on the schema changes, the user still might have to dump and reload some data, but
you can always supply r-code for their updated database.
Database Changes that Affect Time Stamps
You must recompile procedures that reference a database table in which you have made any of
the following changes:
Deleted the table
Changed the table name
Changed the database language or authorization key
Added or deleted a field in the table
Changed the name or order of a field
Added or deleted an index
Modified an index by changing its name, uniqueness, field components, collation order,
or the abbreviation option
Although you do not have to recompile procedures when you make other schema changes, such
changes do not apply to procedures that you do not recompile. For example, changes to the
following features appear only when you recompile:
Field appearance format, label, column label, and decimal
Data entry initial value, mandatory value, case sensitivity, validation expression, delete
validation, and security
User information help messages, validation messages, and description
A22
Database Changes that Affect CRCs
You must recompile procedures using CRC-based deployment for the same schema changes
that change a time stamp. In addition, you must recompile procedures that reference a database
table in which you have made these changes to a field:
The data type or extent (array size)
The number of decimals
The case sensitivity
Table A2 lists all the metaschema fields involved in database CRC calculation.
NOTE: The order in which indexes are defined has no effect on database CRCs.
Time Stamp-based Deployment
Using time stamp validation, if you deploy r-code, you must compile the procedures against a
schema-updated version of the users database and send both the r-code and the new database
to the user. Otherwise, the r-code cannot run, and you must deploy source code for the user to
compile along with new database definitions to update their schema.
CRC-based Deployment
Using CRC validation, if you deploy r-code, you only have to compile the procedures against a
database with the same basic structure as the end-user database. It does not matter when or
where the database was created. If you make schema changes to an existing database, you can
distribute the newly compiled r-code to end users, along with a data definition files to install the
schema changes.
The flexibility of CRC-based deployment makes it easier to distribute a new version of an
existing application. To deploy an application update based on CRC validation, follow these
steps:
1 Install a copy of the production database from the target site in your development
environment.
2 Create an incremental data definition file that captures the difference between your
development database and the production copy. For information about creating an
incremental data definition file, see the Progress Database Administration Guide and
Reference.
3 Apply the incremental data definition file to your copy of the production database.
A23
4 Recompile all procedures affected by the schema changes against your copy of the
production database.
5 Apply the incremental data definition file to the original production database (on site). The
CRC for the original production database should now be identical to the production copy,
but probably not identical to your development database.
6 Distribute the new r-code files (from Step 4) to the updated production site.
The steps for CRC-based deployment are essentially the same as those for time stamp-based
deployment, but you gain these advantages:
You are not required to encrypt and give end users source code.
End users do not have to compile your source code.
You do not have to send a copy of a new database to end users.
End users do not have to dump and reload all their data into your new database.
Differences in R-code Access Authorization
One possible drawback of using CRC validation is that anyone having a Progress development
environment can create a counterfeit database (a database with the same structure as your
database). The user can then write a program, compile it, and run it against your database. Using
time stamp validation prevents this because the time stamps in the counterfeit code do not match
those in your database.
However, you can also combine CRC validation with additional security to prevent
unauthorized r-code access. The DBAUTHKEY option of the PROUTIL utility allows you to
set an authorization key for your database. When you compile your source code, Progress
includes the value of this authorization key in your r-code. You can also use the RCODEKEY
option of PROUTIL to insert the authorization key in existing r-code. Any r-code that does not
include the correct authorization key cannot run against your database. For more information
about using PROUTIL to create and set database authorization keys, see the Progress Database
A24
CRC and Time Stamp Availability
During compilation, Progress always inserts both database time stamps and CRCs in the r-code.
If a database is not connected with the Time Stamp (tstamp) parameter during procedure
compilation, Progress turns on a bit in the r-code. This bit tells the run-time interpreter to check
the CRC if the time stamp check fails.
compatibility.
A.8 R-code CRCs and Procedure Integrity
When Progress compiles a procedure, it calculates a special CRC based on the procedure name
and code content, and stores it in the r-code. This r-code CRC (as distinguished from database
CRC) is useful to ensure the integrity and security of Progress procedures, especially for schema
triggers.
If you choose to have CRCs checked for a schema trigger, the r-code CRC of the trigger
procedure definition is stored in the trigger schema. The trigger procedure cannot run unless it
has a matching r-code CRC. This prevents a trigger procedure with the same name, but different
4GL code, from being improperly substituted for the original trigger procedure. Such a
substitution can cause damage to your database or override your security.
For other application r-code files, you can use the RCODEINFO handle to build a procedure
security table that contains the name and r-code CRC of each r-code file in your application
(except the startup procedure). Before running a procedure, your application can use the
RCODEINFO handle to validate the r-code CRC of its r-code file against the entry established
for it in the procedure security table.
NOTE: If there is no r-code for the procedure, any source (.p) procedure returns an unknown
(?) CRC value.
A.8.1 Assigning CRCs to Schema Triggers
When you create a schema trigger in the Data Dictionary, you can specify CRC checking. Then,
when you save the trigger procedure, the Data Dictionary calculates its r-code CRC and stores
it in the trigger metaschema record (_FileTrig for table triggers and _FieldTrig for field
triggers).
If you want CRC checking for all your schema triggers, you must specify it for each schema
trigger in your database. For more information, see the Progress Basic Development Tools
manual (Character only) and, in graphical interfaces, the on-line help for the Data Dictionary.
A25
A.8.2 Validating CRCs for Schema Triggers
When a database event occurs in your application (such as creating a record or assigning a field),
Progress checks whether the CRC of the corresponding trigger procedure matches the CRC in
the trigger metaschema record. If it matches, Progress executes the procedure. Otherwise,
Progress returns a run-time error.
Trigger CRC validation works for both r-code and source versions of a trigger procedure. For
source versions, Progress calculates the CRC during the session compile.
A.8.3 RCODEINFO Handle
The RCODEINFO handle allows you to read the r-code CRC from an r-code file. You can use
this value to build a procedure security table, and then to verify the integrity of your application
r-code against it. You can also use this value in a deployment procedure that you run in a secure
context to automatically install database schema trigger definitions.
Getting the R-code CRC
To read the r-code CRC from an r-code file, first set the FILENAME attribute of the
RCODEINFO handle to the pathname of your r-code file. Then read the value of the
CRCVALUE attribute.
NOTE: The RCODEINFO handle cannot read the r-code CRC from a session compile. For
source (.p) procedures, the CRCVALUE attribute returns the unknown value (?).
Example Verifying Application R-code Integrity
This example shows how you might provide r-code integrity and security in your application.
1 Build the procedure security table, RcodeSecurity, with these fields:
Filename CHARACTER field for the pathname of each r-code file.
CRC INTEGER field for the r-code CRC of the specified r-code file.
2 Construct a text file, crctable.dat, that contains a list of the relative pathnames for all
the secure procedures called by your application.
3 Compile and save the r-code for all the secure procedures in your application.
DEFINE VARIABLE rCRC AS INTEGER.
RCODE-INFO:FILE-NAME = "sports/crcust.r".
rCRC = RCODE-INFO:CRC-VALUE.
A26
4 Run a procedure that contains code like this to build the RcodeSecurity table.
5 At each point where you call a secure procedure in your application, insert this code.
DEFINE VARIABLE proc-name AS CHARACTER FORMAT "x(32)".
INPUT FROM "crctable.dat". /* List of r-code file pathnames */
i = 0.
REPEAT:
SET proc-name.
FIND RcodeSecurity WHERE Filename = proc-name NO-ERROR.
IF NOT AVAILABLE(RcodeSecurity) THEN
CREATE RcodeSecurity.
RCODE-INFO:FILE-NAME = proc-name.
SET RcodeSecurity.Filename = proc-name
RcodeSecurity.Crc = RCODE-INFO:CRC-VALUE.
i = i + 1.
END.
INPUT CLOSE.
MESSAGE i "procedure security records created".
FIND RcodeSecurity WHERE Filename = "secret.r".
RCODE-INFO:FILE-NAME = "secret.r".
IF RcodeSecurity.Crc = RCODE-INFO:CRC-VALUE THEN
RUN secret.
ELSE DO:
MESSAGE "Procedure secret.r is invalid.".
QUIT.
END.
A27
Example Deploying Schema Triggers
The following procedure installs new schema trigger definitions in an existing database. It reads
dump files that contain the new data for table and field metaschema trigger records and updates
these records with the new trigger procedure names and CRCs.
p-trload.p (1 of 2)
/* p-trload.p */
DEFINE VARIABLE event AS CHARACTER FORMAT "x(6)".
DEFINE VARIABLE proc-name AS CHARACTER FORMAT "x(32)".
DEFINE VARIABLE table-name AS CHARACTER FORMAT "x(32)".
DEFINE VARIABLE field-name AS CHARACTER FORMAT "x(32)".
INPUT FROM "_file-tr.dat". /* Table trigger data */
i = 0.
_fl-loop:
REPEAT:
SET table-name event proc-name.
FIND _file WHERE _file-name = table-name.
FIND _file-trig WHERE _file-recid = RECID(_file) AND
_event = event NO-ERROR.
IF AVAILABLE _file-trig THEN DO:
IF _File-trig._Proc-name = proc-name
AND _File-trig._Trig-CRC = rCRC THEN
NEXT _fl-loop.
ELSE DO:
/* Progress doesnt let you modify a trigger record, so delete and
recreate. */
DELETE _File-trig.
CREATE _File-trig.
ASSIGN _File-trig._File-recid = RECID(_File)
_File-trig._Event = event
_File-trig._Override = TRUE
_File-trig._Proc-Name = proc-Name
_File-trig._Trig-CRC = rCRC
i = i + 1.
END.
END.
END.
A28
NOTE: As this example shows, you must use the RECID function rather than the ROWID
function to reference metschema table record locations.
INPUT CLOSE.
MESSAGE i "_file-trig records updated.".
INPUT FROM "_field-t.dat". /* Field trigger data */
i = 0.
_fld-loop:
REPEAT:
SET table-name field-name event proc-name.
FIND _file WHERE _file-name = table-name.
FIND _field WHERE _file-recid = RECID(_file) AND
_field-name = field-name.
FIND _field-trig WHERE _field-trig._file-recid = RECID(_file) AND
_field-trig._field-recid = RECID(_field) AND
_event = event NO-ERROR.
IF AVAILABLE _Field-trig
AND _Field-trig._Proc-name = proc-name
AND _Field-trig._Trig-CRC = rCRC THEN NEXT _fld-loop.
ELSE DO:
DELETE _Field-trig.
CREATE _Field-trig.
ASSIGN
_Field-trig._File-recid = RECID(_File)
_Field-trig._Field-recid = RECID(_Field)
_Field-trig._Event = event
_Field-trig._Override = TRUE
_Field-trig._Proc-Name = proc-Name
_Field-trig._Trig-CRC = rCRC
i = i + 1.
END.
END.
INPUT CLOSE.
MESSAGE i "_field-trig records updated.".
p-trload.p (2 of 2)
Index
Symbols
! (exclamation point)
format character 1752
user ID lists 149
& (ampersand), menu mnemonics
226
( ) (parentheses) 1753
- (minus sign) 1754
* (asterisk) 1754
user ID lists 149
+ (plus sign) 1754
, (comma) 1754
. (period) 1754
< (less-than sign) 1755
<> (angle brackets) 182
> (greater-than sign) 1754
^ (caret), I/O statements 727
~ (tilde), input files 742
Numbers
9, format character 1752, 1754
A
A, format character 1752
ACCELERATOR option, menu
items 226
Accelerators
character interface 2220
menu items 2218
portable 2220
Action code segment, r-code A2,
A3
ACTIVE-WINDOW handle 2549
example 2130
ActiveX 165
Automation objects 237
controls 237
ActiveX components, handles,
purpose 1616
ActiveX controls
assigning colors 237
assigning fonts 237
Index2
ADD-FIRST method 1735, 1745
ADD-LAST method 1735, 1738,
1744, 1745, 1748
Adding records 919
Advancing frames 38
Alert boxes
creating 257
defined 164
displaying in active window
2549
Aliases
compiling procedures 914
creating in applications 913
DICTDB 145
logical database name 912
shared record buffers 916
All-or-nothing processing 123
Allocating frames 37
ALLOW REPLICATION phrase
1110, 1115
Ampersand (&), menu mnemonic
226
Angle brackets (<>) 182
ANYWHERE option 635, 641,
1640
Application deployment
CRC validation A21
run-time execution 126
time stamp validation A21
Application environment
management 2323
Application security 141
activities-based checking 1410
CAN-DO function 1414, 1415
checking user IDs at run time
147
creating, permissions table 1410
using the CAN-DO function
149
Application-driven programming.
See Procedure-driven
programming
Applications
compile-time execution 119,
126
multi-user 132
run-time execution 119
APPLY statement 1038, 1642
compared to RUN statement
1643
procedure triggers 329
Applying events 1642
procedure triggers 329
AppServers, handles, purpose
1616
Arguments, include files 818
Arrays, efficient processing 1242
ASC function, code page
conversion 728
ASSIGN statement 917
ASSIGN trigger 113, 118
Asterisk (*) 1754
user ID lists 149
AT phrase 2516
Attributes
AUTO-RESIZE 1630, 174
AUTO-RETURN 175
AUTO-ZAP 175
BLANK 175
CHECKED 2215
COLUMN 204
combo box widget 1745
CURRENT-WINDOW 211
persistent procedures 340
DATA-ENTRY-RETURN 175,
Index3
Index
189
DATA-TYPE 1745
DBNAME 175
DELIMITER 1735, 1745,
1748
direct manipulation 242
DRAG-ENABLED 1735
editor widget 1727
FILE-NAME, persistent
procedures 340
fill-in widget 175, 178
FIRST-CHILD 2226
FIRST-PROCEDURE 339
FIRST-TAB-ITEM 2544
FORMAT 175, 1714, 1745,
204
FRAME 1922, 204
FRAME-COL 2520
FRAME-NAME 175
FRAME-ROW 2520
FRAME-SPACING 2541
GET-SIGNATURE, persistent
procedures 340
GRAPHIC-EDGE 1816
GRID-FACTOR-HORIZONTA
L 2417
GRID-FACTOR-VERTICAL
2417
GRID-SNAP 2418
GRID-UNIT-HEIGHT-CHARS
2418
GRID-UNIT-HEIGHT-PIXELS
2418
GRID-UNIT-WIDTH-CHARS
2418
GRID-UNIT-WIDTH-PIXELS
2418
GRID-VISIBLE 2417
HANDLE 166
HEIGHT 174
HEIGHT-CHARS 1711
HEIGHT-PIXELS 1711
INDEX 175
INNER-CHARS 1735
INNER-LINES 1735, 1745
INTERNAL-ENTRIES,
KEEP-FRAME-Z-ORDER
1932
LARGE 1726
LAST-CHILD 2226
LAST-PROCEDURE 339
LAST-TAB-ITEM 2544
LIST-ITEMS 1735, 1736,
1738, 1744, 1745, 1746,
1748
MAX-CHARS 1724
MAX-VALUE 1710
MIN-VALUE 1710
MULTIPLE 1735
NEXT-SIBLING 2226
NEXT-TAB-ITEM 2544
NUM-ITEMS 1735, 1745
NUM-TABS 2544
PARENT 2226
PERSISTENT, persistent
procedures 340
PREV-SIBLING, persistent
procedures 339
PREV-TAB-ITEM 2544
PRIVATE-DATA 1635
procedures 339
ROW 204
SCREEN-VALUE 1735,
1745, 204, 205
selection list widget 1735
SENSITIVE 176
SIDE-LABEL-HANDLE 204
slider widget 1710
SORT 1735, 1745
SUBTYPE 173
TAB-POSITION 2544
TABLE 175
THREE-D 2549
TYPE 329, 1619
USE-TEXT 178
WIDTH 174
WIDTH-CHARS 1711, 204
WIDTH-PIXELS 1711
X 204
Y 204
Attributes, widget
example 1623
expressions 1622
handles 1620
Index4
reading 1621
referencing 1621
setting 1622
Audit trails. See Transactions
Authentication
defined 143
examples 146, 147
procedure in Progress 145
Auto-connect, connecting databases
95
AUTO-RESIZE attribute 1630,
174
AUTO-RETURN attribute 175
AUTO-ZAP attribute 175
Automation, ActiveX Automation
objects 237
AVAILABLE function 1319
B
Batch processing 725
{&BATCH-MODE} name
reference 814
Before-image files 1241
BGCOLOR, widget assignment
234
BLANK attribute 175
Blank user IDs 145
Bleeding record locks 1315
Block properties 32
See also Frames, designing
Blocks 31
4GL 114
context 115
default frames 2511
default processing 33
defined 114
DO 32
DO ON ENDKEY 1218
DO ON ERROR 1218
DO TRANSACTION 1218
dynamic resources 117
EDITING 33
editing 636
error processing 318
FOR 32
FOR EACH 36
frame scopes 38
LEAVE processing 54
looping 35
NEXT processing 54
Procedure blocks 32
properties 32, 33
reading records 36
record scoping 310
REPEAT 32
retrying 38, 54
RETURN processing 54
scope 116
scoping properties 35
services for frames 38, 1926
TRANSACTION option 128,
1218
transactions 317, 128
trigger 33
undoing 53
unscoped resources 116
BORDER-TOP attribute 256
BORDER-TOP-CHARS attribute
256
Borrowing frames 39
Box selecting 247, 2411, 2415
BREAK keyword. See
Control-break reports
Browse
moving 1041
resizable 1040
resizing 1040
Index5
Index
row height, changing 1043
BROWSE statement 917
Browse widgets 105 to 1043,
139
calculated fields 1012
character interfaces 1046
colors 1039
column events 1023
creating rows 1027
data set size 104
defining 105
deleting rows 1030
described 102
events 1020
field lists 104
fonts 1023
justified labels 1038
locking columns 1031
overlaying widgets 1034
programming techniques 1020
queries 103, 1011
read-only 105
refreshing rows 1024
related tables 1037
repositioning focus 1024
row events 1023
searching columns 1015
sizing 1013
stacked labels 1038
style options 1038
table joins 1037
ToolTips 1039
updating editable rows 1025
Browse-column 2027
moving 1042
resizing 1041
Browsing records 139
-Bt startup parameter, temporary
table buffer size 1515
BTN-DOWN-ARROW image 184
BTN-LEFT-ARROW image 184
BTN-RIGHT-ARROW image 184
BTN-UP-ARROW image 184
Buffer object 2015, 2018
BUFFER-COMPARE statement
1118
Buffer-field object 2015, 2020
Buffers
free record scope 310
free references 310
internal procedures 333
locks and multiple 1315
record 310, 916
screen 916
strong record scope 310
weak record scope 310
Button widget 182
calculating the default size 186
choosing 182
DEFAULT option 189
defaults in dialog boxes 189
images 183
NO-CONVERT-3D COLORS
option 188
NO-FOCUS option 184
predefined images 184
states 183
TOOLTIP attribute 182
Buttons, mouse 627, 245
C
Calculated fields, browse widgets
1012
Call stack, procedure 323
CAN-DO function
application security 1414
using to check user IDs 149
Cascading replication. See Data
replication
Index6
CENTERED option, DISPLAY
statement 258
Character browse 1046
color management 1052
control keys
edit mode 1050
row mode 1048
differences from Windows 1052
modes of operation 1047
tabbing 1053
CHARACTER data type
combo boxes 1739
editor widget 1724
radio set 1719
selection lists 1730
Character display formats 1751
Character interface accelerators
2220
Character interfaces 212, 252
colors 238
reserved values 239
widget states 238
scroll mode 2533
simulating windows 253
specifying colors 232
Character set management. See
Code page conversion
Character units 254, 2517
conversion with pixels 255
rounding error 255
CHECKED attribute 2215
Checking data entry for keys 635
Child frames 1919
defining 1922
field-level widgets 1921
restrictions 1923
Child windows 219
CHOOSE event 1633
CHOOSE statement 172, 2531,
2535
See also SCROLL statement
CHR function
code page conversion 728
Clearing frames 38
Clipboard output 76
Code example, resizable browse
1045
Code generation. See Dynamic code
generation
Code pages
conversion map file 729
conversions 728
example of conversion 729
CODEPAGE-CONVERT function
728
Collision log. See Data collision
Color
adding for startup 233
availability 232
See also Character interfaces
management 238
reserved values 239
widget states 238
common dialog 2311
example 2312
custom, Windows color dialog
2312
definitions 2321
changing 2321
dynamic 2311
environment files 232
See also Environment files
environments 2323
graphical interfaces
definition access 2321
environment management
2323
management 2310
Index7
Index
table access 2318
user changes 2311
inheritance 237
managing display limitations
2326
numeric, Windows color dialog
2312
Progress defaults 233
RGB-VALUE function 232
sample application 234
table access 2318
the registry 232
visual, Windows color dialog
2312
widget assignment 234
example 235
Windows 239
Palette Manager 239, 2310
Color dialogs 2312
4GL statements 2311, 2313
Windows example 2312
COLOR-TABLE handle 2318
environment management 2324
example 236, 2311
using 2318
Colors
assigning 234
assigning to ActiveX controls
237
modifying 2318
COLUMN attribute 204
COLUMN frame phrase option
1931
Combo box widget 1739 to 1748
attributes 1745
example 1743, 1746
item selection 1739 to 1746
methods 1745
options 1740
value settings 1742
Comma (,) 1754
Comments, 4GL 113
Commit
two-phase 1239
Commit unit. See Transactions
Common dialogs
4GL statements 2311, 2313,
2316
color 2312
examples 2312, 2315
font 2315
COMPILE statement, compared to
RUN statement 126, 127
Compiler
listing 315
messages 525
STREAM-IO option 710
Compile-time, security 141
Compile-time code 119, 124
execution 126
interaction with run-time 123
procedure execution 126
run-time expressions 126
syntax elements 120
uses 126
COMPLETE option, SAVE
CACHE statement 979
Component handles, compared to
other handles 1616
Condition handling
Conditions
ENDKEY 513
ERROR 56
QUIT 519
STOP 518
database disconnection 524
CONNECT statement 93
authentication 145
NO-ERROR option 93, 97
Index8
CONNECTED function 97, 1239
Connection failures 96
See also Multi-database
connection(s)
Connection overhead 99
Connection parameters. See Startup
parameters
Connection security 141
Connections, lost 524
CONTAINS operator 947
Context
blocks 115
compared to scope 324
defined 114, 319
Control frame 165
Control tables, sequences 963
Control-break reports, using work
tables to produce 153
Controlling frame allocation 199
Controls 161
See also Widgets
ActiveX controls 237
Conversion map files 729
CONVERT-3D-COLORS attribute
1814
CONVERT-3D-COLORS option
1814
Converting
code pages 728
See also Code page conversion
data 730
IMPORT statement 740
QUOTER utility 731
CR, minus sign 1755
CRC. See Cyclic redundancy check
CRC calculation
database
metaschema fields A20
tables A20
r-code A24
CRC compared to time stamps,
r-code availability A24
CRC validation A19
CREATE ALIAS statement 912
CREATE statement 917
CREATE trigger 112, 117
CREATE Widget statement 1612
CREATE-RESULT-LIST-ENTRY
method 1027
Creating persistent procedures 338
Cross-tab reports, using work tables
to produce 1513
CURRENT option, SAVE CACHE
statement 980
CURRENT-LANGUAGE function
346
CURRENT-LANGUAGE variable
changes, persistent procedures
346
CURRENT-VALUE function 969
syntax 968
CURRENT-VALUE statement
970
syntax 968
CURRENT-WINDOW attribute
211
persistent procedures 340,
2120
Index9
Index
CURRENT-WINDOW handle
211, 2116
Cursor repositioning
field lists 936
FIND statement 931
after FIND fetches 931
Custom colors, Windows color
dialog 2312
Cyclic redundancy check
compared to time stamps A21
database A18
advantages A23
calculation A20
changes affecting A22
code validation A19
compared to time stamps
A21
deployment A22
disadvantages A23
R-code
RCODE-INFO handle A25
schema triggers A25
r-code A24
See also R-code CRCs
application procedures A24
calculation A24
schema triggers A25
D
-D startup parameter, Directory Size
A10, A13
-d startup parameter, Date Format
1758
Data
formats 1749 to 1758
handling statements 916
movement 916
read-only 176
representing 171
Data collision. See Data replication
Data Dictionary
validation 1949
Data entry, monitoring 63, 635
Data replication
4GL support for 1110
data collision 1117
collision log 1117
Data Dictionary support for
1111
process configuration 1120
replication changes log 1112
replication models, cascading
replication 1116
trigger-based replication 1111
Data types
RAW 973
WIDGET-HANDLE 166
DATA-ENTRY-RETURN attribute
175, 189
DATA-TYPE attribute 1745
Database connection, lost
connections 524
Database CRCs A18
database changes affecting A22
Database disconnection 524
Database triggers
ASSIGN 113, 118
CREATE 112, 117
default error phrase 1126
DELETE 112, 117
disabling for dump/load 1127
error status 1126
ESQL considerations 1127
FIND 112, 1124
FIND NEXT statement 1125
FIND PREV statement 1125
interaction 114
overriding 1123
procedure library 1127
reverting 1123
Index10
schema 114
session 1121
WRITE 113, 115
Databases
connect parameters, limits 92
CRC A18
code validation A19
disconnecting 1239
integrity 122
multiple connections. See
Multi-database connections
Number of Databases (-h) startup
parameter 92
records, sharing 133
security 141
time stamps A18
triggers 111
DATE data type
combo boxes 1739
radio set 1719
Date display formats 1758
Date Format (-d) startup parameter
1758
DB, minus sign 1755
DBNAME attribute 175
DBTASKID function 1110, 1113
DCOLOR
using 238
widget states 238
Deadly embrace 1321
Debugger segment, r-code A3
DECIMAL data type
combo boxes 1739
formats 1753
radio set 1719
Default action, selection lists 1730
Default buttons 189
Default frames 37
DO blocks 37
specifying 197
DEFAULT option 189
DEFAULT-ACTION event 1633,
1730, 1738
browse widget 1020
DEFAULT-BUTTON option 189
DEFAULT-WINDOW handle 211
DEFINE BUTTON statement 182
DEFINE FRAME statement 2513,
2514
DEFINE IMAGE statement 189
DEFINE QUERY statement 928
SCROLLING option 929
DEFINE RECTANGLE statement
1816
DEFINE SHARED FRAME
statement 1935
DEFINE SHARED STREAM
statement 722
See also Streams, shared
DEFINE SHARED VARIABLE
statement 1938
DEFINE STREAM statement 719
DEFINE TEMP-TABLE statement
1516
See also Temporary tables
DEFINE VARIABLE statement
use of FORMAT option 1749
using VIEW-AS phrase 172
DEFINE widget statement 1612
DEFINE WORK-TABLE statement
155, 158
Index11
Index
See also Work tables
DEFINED function 86, 810
DELETE ALIAS statement 913
DELETE method 1735, 1745
DELETE PROCEDURE statement
341
DELETE statement 917, 919
DELETE trigger 112, 117
DELETE WIDGET statement
1613
DELETE-SELECTED-ROWS
method 1030
Deleting
dynamic widgets 1613
field lists 935
records 919
DELIMITER attribute 1735,
1745, 1748
DELIMITER option
EXPORT statement 738
IMPORT statement 739, 740,
743
Derealizing widgets 1629
Descendant frames 1922
DESELECT event 2412
Determining frame type 1912
Dialog boxes
compared to windows 213
default buttons 189
2549
viewing frames 2538
DICTDB alias 145
-dictexps startup parameter 1951
Dictionary Expressions (-dictexps)
startup parameter 1951
Direct manipulation 241
event ordering 2415
events 2411
modes 2411
Directory Size (-D) startup
parameter A10, A13
DISABLE TRIGGERS FOR LOAD
statement 1110, 1115
DISCONNECT statement
affect on aliases 913
transactions 1239
Display formats 1749 to 1758
character 1751
date 1758
defaults 1751
logical 1757
numeric 1753
DISPLAY statement 917
CENTERED option 258
OVERLAY option 1931
RETAIN option 258
TITLE option 258
DO blocks
default frame 37
described 32
error property 53
frame scoping 38
infinite loop protection 54
ON ERROR phrase 317
DO statement, FOR option 310
Down frames 2525
DR, minus sign 1755
Index12
Drag box 248
DRAG-ENABLED attribute 1735
Dragging, selection lists 1731,
1732
Duplicating menus 2216
Dynamic browse, Browse 2025
Dynamic code generation
4GL 127
optimized 127
Dynamic frames 194
Dynamic menus 2221
creating menu bars 2224
example 2227
pop-up menus 2229
properties 2222
querying sibling attributes 2226
setting up menu bars 2223
Dynamic resources 117
Dynamic scoping, internal
procedures and user-defined
functions 352
Dynamic submenus, defining
submenus 2224
Dynamic temporary tables. See
Temporary tables
Dynamic widgets
4GL actions 202
creating 1612
defined 165
deleting 1613
describing 1612
field-level widget setup 204,
206
example 206
frame setup 207
example 208
instantiating 1612
managing 202
compared to static widgets
202
reasons for using 201
triggers 1636
widget pools 209
E
EDGE-CHARS option
rectangle widget 1815
with RECTANGLE widget
1816
EDGE-PIXELS option
rectangle widget 1815
with RECTANGLE widget
1816
Edit mode, character browse 1046
EDITING blocks 635
described 33
Editing blocks 636
Editor widgets 1724
attributes 1727
example 1728
interactions 1726
LARGE option 1726
MAX-CHARS attribute 1724
methods 1727
options 1724
save file portability 1730
scrolling 1726
word wrap 1726
&ELSE directive 86
&ELSEIF directive 86
EMPTY-SELECTION event 2412
ENABLE statement 917
ALL option 1950
END-ERROR key 523
EXCEPT option 1950
Encapsulation
defined 332
Index13
Index
example 339, 342
ENCODE function 142
END event, browse widget 1020
End of file 516
END-BOX-SELECTION event
2414
END-ERROR key 633
ENABLE/WAIT-FOR 523
handling by Progress 519
END-MOVE event 2413
END-RESIZE event 2413
END-SEARCH event 1019
&ENDIF directive 86
ENDKEY condition 52, 513
default handling 514
END-ERROR key 521
handling 517
ENDKEY, processing 633
See also UNDO statement
ENTRY event 1633
ENTRY method 1735, 1745
Environment files
changing resources 2321
colors and fonts 232
hints for managing 2325
managing 2323
managing multiple 2324
managing statements 2323
scenario for managing 2324
ERROR condition 52, 56
default handling 57
END-ERROR key 521
overriding default handling 510
ERROR key 56, 58
ERROR option 54
RETURN statement 56
Error processing, blocks 318
ERROR-STATUS handle 56
Errors
handling in procedures 510
processing 122
European Numeric Format (-E)
Event-driven programming 22
definition 22
example 210
flow of execution 25
interrupt-drive handling 27
real-time 27
WAIT-FOR statement 210
Events
applying 1642
CHOOSE 1633
database 112, 1127
DEFAULT-ACTION 1633,
1730, 1738
defined 25
defining 1634
DESELECT 2412
direct manipulation 245, 2411,
2415
EMPTY-SELECTION 2412
END-BOX-SELECTION 2414
END-MOVE 2413
END-RESIZE 2413
ENTRY 1633
interrupt signal 28
ITERATION-CHANGED 1633
keyboard 635
keystroke 1631
LEAVE 1633
MENU-DROP 1633, 2218
mouse 1631, 245
named 41
resizable browse, user
manipulation 1044
RETURN 189
Index14
SELECT 2412
START-BOX-SELECTION
2414
START-MOVE 2413
START-RESIZE 2413
triggers 25
user-interface 1631
VALUE-CHANGED 1633,
1717, 1722, 1730, 1732,
1740, 1744, 1748, 2216
WINDOW-CLOSE 1633, 218
WINDOW-MAXIMIZED
1633, 218
WINDOW-MINIMIZED 1633,
218
WINDOW-RESTORED 1633,
218
Example code, resizable browse
1045
Examples
external procedures,
non-persistent 321
shared objects 327
Exclamation point (!)
format character 1752
user ID lists 149
EXCLUSIVE-LOCK option, record
phrase 128, 135, 1313, 1316
Executable code. See Run-time code
Execution buffer
available memory A10
ceiling
described A10
size A10
described A7, A11
Execution environment
limits A10, A13
r-code A7, A11
typical layout A8, A12
statistics A14
.srt file access A15
execution map A15
segment information A16
startup parameters A14
summary information A17
EXPAND option, radio sets 1720
EXPORT statement 738
DELIMITER option 738
Exporting data 738
Expression code segment, r-code
A2
EXTEND mouse button 627
External procedures
defining 320
described 32
examples, non-persistent 321
naming 320
running non-persistently 320
options 321
running persistently 338
shared objects 325
External user-defined functions. See
Persistent procedures
F
Fetching records 921
defining record set 919
order 921
preselect list 923
results list 923
ROWID and RECID 923
using field lists. See Field lists
FGCOLOR, widget assignment
234
Field List Disable (-fldisable)
Field lists 932
benefits 932
browse widget 104
Index15
Index
cursor repositioning 936
DataServers 932, 935, 937
degenerate cases 937
deletes 935
deployment 937
implied entries 935
multiple queries 937
server versions 937
shared queries 934
specifying 933
updates 935
Field references 317
Field(s), FORM statement 2514
Field-level widgets
child frames 1921
defined 163
dynamic 204
Field-group widgets 1939
accessing 1946
characteristics 1942
position relative to frames 1943
size 1942
types 1941
visibility 1944
z-order 1943
Fields
order of update 2514
validation 730
FILE option, image widget 189
File types 726
FILE-INFO system handle 727
FILE-NAME attribute, persistent
procedures 340
{&FILE-NAME} name reference
814
Files
attributes 726
before-image 1241
conversion map 729
convmap.cp 729
information 727
input 730
local-before-image (.lbi) 1241
redirecting input 714
redirecting output 76
schema cache 978
See also Schema cache files
sort (.srt) A7
Fill characters, display formats
1752
FILL-IN widget, width 174
Fill-in widgets 172, 176
attributes 175
AUTO-RESIZE attribute 173
font used in Windows 174
NATIVE option 172
FIND CURRENT statement 1320
FIND FIRST statement, using to
sort work tables 1510
FIND statement 917
repositioning 931
after FIND fetches 931
temporary tables 1516
FIND trigger 112, 1124
FIRST-CHILD attribute 2226
FIRST-PROCEDURE attribute
339
FIRST-TAB-ITEM attribute 2544
Flow of execution 22
event-driven programs 25
procedure-driven programs 22
Focus 109
Font dialogs 2315
4GL statements 2311, 2316
Windows example 2315
FONT, widget assignment 234
Index16
FONT-TABLE handle 2318
example 236
using 2320
Fonts
adding for startup 234
assigning 234
assigning to ActiveX controls
237
availability 232
character interfaces, management
238
common dialog 2311
example 2315
definitions 2321
changing 2321
environment files 232
See also Environment files
environments 2323
graphical interfaces
definition access 2321
environment management
2323
management 2310
table access 2318
user changes 2311
inheritance 237
Progress defaults on Windows
234
proportional width 174
sample application 234
table access 2318
example 235
FOR blocks
described 32
error property 53
FOR EACH blocks 317
frame scoping 38
FOR EACH statement 917
FOR option
DO statement 310
REPEAT statement 310
FOR statement
EACH option 310
Form backgrounds 2519
FORM statement 2513, 2514
frame header 2517
in shared frames 1938
shared frames 1936
FORMAT attribute 175, 1714,
1745, 204
FORMAT option 1749
fill-ins 173
Formats, display 1749 to 1758
character 1751
date 1758
defaults 1751
logical 1757
numeric 1753
FRAME attribute 204
child frames 1922
field groups 1940
Frame families 1919
defining 1922
fill-in tabbing 2548
shared 1939
tab order 2544
using 1922
viewing and hiding 1932
FRAME option, frame phrase 37
Frame phrase, FRAME option 37
Frame segment, r-code A3
Frame services
advancing 38
clearing 38
hiding 38
viewing 38
FRAME-COL attribute 2520
FRAME-COL function 2520
Index17
Index
FRAME-DOWN function 2525
FRAME-FIELD function 641
FRAME-LINE function 2524
FRAME-NAME attribute 175
FRAME-NAME function 175
FRAME-ROW attribute 2520
FRAME-ROW function 2520
FRAME-SPACING attribute 2541
Frames 258
advancing 1934
allocating 37, 195
behavior 1927, 1931, 2520,
2522, 2524, 2525
FRAME-ROW and
FRAME-COL 2520
borders 256
borrowed 39
carry-over display 258
CENTERED option 258
characteristics 257
child 1919
clearing 1934
default 37
default button 189
default services 1926
defined 193
design issues 2511
determining type 1912
down 2525
dynamic 207
families 1919
field-level design 2513
flashing 1918
hiding 1927, 1928
layout 2514, 2517
moving 2410
multiple active 2541
non-terminal devices 2541
options 257
overlaying 1931
parent 1919
resizing 2410
resolving references 37
root 1919
scope 1915
scope of shared frames 1939
scoping properties 38
scrollable 2532
scrolling 2527
See also SCROLL statement
2527
services for blocks 38
setting attributes 259
shared 1935
tab order 2543
triggers 39, 1917
types 1911
unnamed 37
usage rules 2511
validation 1950
variable-level design 2513
viewing 1927
See also TOP-ONLY,
OVERLAY, NO-HIDE
frame phrase options
Free references, buffers 310
FREQUENCY attribute 1710
FREQUENCY option 1710
Function keys
changing definitions 625
monitoring usage 635
Functions
ASC 728
AVAILABLE 1319
CAN-DO 147, 1412, 1414
CHR 728
CODEPAGE-CONVERT 728
CONNECTED 1239
CURRENT-LANGUAGE 346
ENCODE 142
FRAME-COL 2520
FRAME-DOWN 2525
FRAME-FIELD 641
FRAME-LINE 2524
FRAME-NAME 175
Index18
FRAME-ROW 2520
KBLABEL 64
KEYCODE 64
KEYFUNCTION 64
KEYLABEL 64
LASTKEY 630
LOCKED 1319
OS-GETENV 727
RETRY 54
RETURN-VALUE 54, 526
SEARCH 78
SETUSERID 145
SUBSTRING 735
TRANSACTION 1240
user-defined
See also Persistent procedures
external. See Persistent
procedures
local. See Persistent
procedures
remote. See Persistent
procedures
USERID 149
VALID-HANDLE 1619
procedure handles 329
WIDGET-HANDLE 1619
G
GET CURRENT statement 1320
GET statement, browse widget
1011
GET-BYTE function 974
GET-KEY-VALUE statement
2321
example 2321
GET-SIGNATURE attribute,
GET-TAB-ITEM method 2544
Global shared objects 325
&GLOBAL-DEFINE directive 82
GO event,
DATA-ENTRY-RETURN 2548
GO-ON phrase 630
GRAPHIC-EDGE attribute 1816
GRAPHIC-EDGE option 1816
Graphical user interfaces 21, 212
Greater-than sign (>) 1754
GRID-FACTOR-HORIZONTAL
attribute 2417
GRID-FACTOR-VERTICAL
attribute 2417
GRID-SNAP attribute 2418
GRID-UNIT-HEIGHT-CHARS
attribute 2418
GRID-UNIT-HEIGHT-PIXELS
attribute 2418
GRID-UNIT-WIDTH-CHARS
attribute 2418
GRID-UNIT-WIDTH-PIXELS
attribute 2418
GRID-VISIBLE attribute 2417
Grids 2417
GUI. See Graphical user interface
H
HANDLE attribute 166
Handle management 1619
Handles
ACTIVE-WINDOW 2549
attributes 1620
COLOR-TABLE 2318
component, purpose 1616
Index19
Index
CURRENT-WINDOW 211,
2116
DEFAULT-WINDOW 211
ERROR-STATUS 56
FILE-INFO 727
FONT-TABLE 2320
managing 1619
procedures 328
query, buffer, and buffer-field
object, purpose 1616
server, purpose 1616
SESSION 339
frame spacing 2541
system 1617
THIS-PROCEDURE 328
See also THIS-PROCEDURE
handle
transaction, purpose 1616
types 1615
widgets 166
purpose 1615
Header statements 197
Headers, frame 2517
HEIGHT attribute 174
HEIGHT-CHARS attribute 1711
HEIGHT-PIXELS attribute 1711
Help
Progress 525
providing context-sensitive 175
Help facilities 110
Help submenu 227
HIDE statement 1927
Hiding frames 38, 1928
Highlighting 246
custom 2410
HOME event, browse widget 1020
I
&IF directive 86
Image widgets 189 to 1814
built-in 184
buttons 183
CONVERT-3D-COLORS option
1814
determining image file size
1810
example 1812
ignoring file at compile time
1810
options 189
TOOLTIP option 1814
TRANSPARENT attribute
1814
IMAGE-SIZE option, image widget
189
IMAGE-SIZE phrase 1810
button border thickness 186
buttons 186
NO-FOCUS option 186
IMAGE-SIZE-CHARS option,
image widget 189
IMAGE-SIZE-PIXELS option,
image widget 1810
IMPORT statement 740, 741
DELIMITER option 739, 740,
743
UNFORMATTED option 741
Importing, data 740
IN FRAME phrase
attribute references 1621
method references 1623
IN MENU phrase 2215
IN option, RUN statement 332
condition handling 333
IN WINDOW option 2116
Index20
Include files, arguments 818
INDEX attribute 175
Index cursors 931
Index-sorted queries 926
INDEXED-REPOSITION option,
browse widgets 104
Indexes
defining, for temporary tables
1522
positioning 317
Indexing, word 947
Infinite loop protections 54
Initial value segment, r-code A2,
A4
Initialization files, colors and fonts
232
Inner joins
defined 940
example 938, 943
mixing with left outer 947
specifying 940
INNER-CHARS attribute 1735
INNER-CHARS option
editor widget 1724
INNER-LINES attribute 1735,
1745
INNER-LINES option
combo boxes 1740
editor widget 1724
Input
changing the source 714
control character 718
devices 715
directory contents 715
end of file 516
file preparation 730
QUOTER utility 731
files 714
multiple sources 716, 719
streams 72
terminal 715
working within procedures 71
INPUT CLOSE statement 718
QUOTER utility 735
INPUT FROM statement 714
BINARY option 718
OS-DIR option 726
QUOTER utility 734
redirecting input 718
INPUT THROUGH statement 725
INPUT-OUTPUT THROUGH
statement
INSERT method 1735, 1745
INSERT statement 917, 919
Instantiating, RUN statement 338
INTEGER data type
combo boxes 1739
formats 1753
radio set 1719
slider 179
Interaction modes 2411
Interfaces
character 212
graphical 212
Internal procedures
buffers 333
call stack 337
compared to triggers 1643
context 333
defining 330
Index21
Index
described 32
encapsulation 332
See also Encapsulation
examples 335
execution options 331
frames 39
IN execution option 332
naming 331
prototyping 355
running 331
running in any context 332
streams 333
work tables 333
INTERNAL-ENTRIES attribute,
internationalization, word break
tables 947
Interrupt-drive handling,
event-driven programming 27
IS-SELECTED method 1735
Iterating blocks 1918
Iteration 35, 128
ITERATION-CHANGED event
1633
J
Joins
See also Inner join, Left outer
join
conditions 941
defined 938
full outer 946
inner 938, 940
left outer 940
mixing inner and left outer 947
nested reads 943
right outer 946
specifying 940
Journaling. See Transactions
K
KBLABEL function 64
KEEP-FRAME-Z-ORDER
attribute 1932
KEEP-TAB-ORDER option 2544
Keyboard events 635
KEYCODE function 64
KEYFUNCTION function 64
KEYLABEL function 64
Keys
changing the function 625
codes 65, 66, 617
END-ERROR 519, 633
ENDKEY 513
ERROR 58
functions 619, 636
input 62
input precedence 63
labels 65, 66, 617, 636
STOP 518
Keystroke events 1631
Keystrokes
monitoring 63, 635
L
LARGE attribute 1726
LARGE option, editor widget
1726
LARGE-TO-SMALL attribute
179
LARGE-TO-SMALL option 179
LAST-CHILD attribute 2226
LAST-PROCEDURE attribute
339
Index22
LAST-TAB-ITEM attribute 2544
LASTKEY function 630
LEAVE event 1633
LEAVE processing 54, 517
avoiding infinite loops 54
Left outer joins
defined 940
example 941, 945
mixing with inner 947
specifying 940
Less-than sign (<) 1755
Libraries A5
PROPATH A6
Licensed user count, exceeding 92
LIKE option 1635
connected database 978
{&LINE-NUMBER} name
reference 814
LIST-ITEMS attribute 1735,
1736, 1738, 1744, 1745,
1746, 1748
LIST-ITEMS option
combo boxes 1740
LISTING option, COMPILE
statement 315
LOAD statement
scenario 2324
using 2323
LOAD-ICON method 215
LOAD-IMAGE method 1811
LOAD-IMAGE-DOWN method
186
LOAD-IMAGE-INSENSITIVE
method 186
LOAD-IMAGE-UP method 186
LOAD-SMALL-ICON 215
Local before-image files 1241
Local user-defined functions. See
LOCKED function 1319
Locking 133
Locking records
browse 1233
handling 129
update 1233
Locks
See also Record locks
browse widget 103
deadly embrace 1321
Logging. See Transactions
LOGICAL data type
combo boxes 1739
radio set 1719
toggle box 1714
Logical display formats 1757
_login.p procedure 143, 145
LOOKUP method 1735, 1745
Looping 35, 128
Loops, infinite 54
Lost database connections 524
M
MANUAL-HIGHLIGHT attribute
2410
MAX-CHARS attribute, editor
widget 1724
Index23
Index
MAX-VALUE attribute 1710
MAX-VALUE option, sliders
1710
Maximized window, attributes 255
Maximum Memory (-mmax) startup
parameter A10
Menu bars 221, 222
assigning a static menu bar to a
window 228
defining a static menu bar 227
dynamic 2223
static 225
Menu hierarchy 224
Menu items
creating menu items 2225
enabling and disabling 2213
referencing 2215
subtypes 2225
Menu mnemonics 2221
MENU mouse button 627
MENU-DROP event 1633, 2218
Menus 222
accelerator keys 226, 2218
accelerators, character interface
2220
dynamic menu bars 2223
dynamic menus 2221
creating a menu bar 2224
creating menu items 2225
creating submenus 2224
example 2227
pop-up menus 2229
properties 2222
querying sibling attributes
2226
help 227
menu bars 221, 222
menu hierarchy 224
mnemonics 226
nested pull-down menus 2212
pop-up menus 2211, 2229
pull-down menus 222
scrolling 2527
static menu bars 225
static menu, defining a menu bar
227
static menus 225
assigning a menu bar to a
window 228
defining submenus 226
duplicating menus 2216
enabling and disabling menu
items 2213
menu mnemonics 2221
nested submenus 2212
pop-up menus 2211
toggle boxes 2215
strip 2534
&MESSAGE directive 810
MESSAGE statement 252
alert boxes 257
Messages
application 526
compiler 525
2549
during execution 525
startup 525
Metaschema tables, CRC
calculations A20
Methods
ADD-FIRST 1735, 1745
ADD-LAST 1735, 1738,
1744, 1745, 1748
combo box widget 1745
DELETE 1735, 1745
editor widget 1727
ENTRY 1735, 1745
GET-TAB-ITEM 2544
INSERT 1735, 1745
IS-SELECTED 1735
LOAD-ICON 215
LOAD-IMAGE 1811
Index24
LOAD-IMAGE-DOWN 186
LOAD-IMAGE-INSENSITIVE
186
LOAD-IMAGE-UP 186
LOAD-SMALL-ICON 215
LOOKUP 1735, 1745
MOVE-AFTER-TAB-ITEM
2544
MOVE-BEFORE-TAB-ITEM
2544
MOVE-COLUMN 1032
MOVE-TO-BOTTOM 1932
MOVE-TO-TOP 1932
REPLACE 1735, 1745
SCROLL-TO-ITEM 1735
selection list 1735
VALIDATE 1949
Methods, widget 1623
example 1625
expressions 1624
invoking 1624
referencing 1623
MIN-VALUE attribute 1710
MIN-VALUE option, sliders 1710
Minus sign (-) 1755, 1757
-mmax startup parameter, execution
buffer ceiling A10
Mnemonics, menu items 226
Models, programming 21
Modes
transactions 1228
Monitoring keystrokes 63, 635
EDITING blocks 635
user interface triggers 635
Mouse
buttons 627, 245
EXTEND 627
MENU 627
MOVE 627
events 1631, 245
specifying 628
input 62
Mouse buttons, SELECT 627
Move mode 2411
MOVE mouse button 627
MOVE-AFTER-TAB-ITEM
method 2544
MOVE-BEFORE-TAB-ITEM
method 2544
MOVE-COLUMN method, browse
widget 1032
MOVE-TO-BOTTOM method
1932
MOVE-TO-TOP method 1932
Moving
browse 1041
browse-column 1042
Moving widgets 248, 2416
MS-Windows, three-dimensional
effects 2549
Multi-database applications
referencing files and field names
975
transaction behavior 1239
Multi-database connections
CONNECTED function 97
connection overhead 99
connection parameters 92
conserving 99
considerations at development
95
disconnecting 910
failures and disruptions 96
methods list 92
Physical Database Name (-db)
Index25
Index
positioning references in
applications 977
Progress functions 98
run-time considerations 95
Multi-databases
disconnecting 910
Multi-user
applications 132
environment 132
record locks 133
sharing records 133
starting client 1317
starting server 1317
Multiple
input sources 716
output destinations 77
MULTIPLE attribute 1735
MULTIPLE option, selection lists
1731
Multiple windows
non-persistent management
2114
persistent management 2116
creating 2116
example 2117
widget pools 2116
pros and cons 212
Multiple-select browse, defined
109
Multi-window applications,
described 2114
N
N, format character 1752
Named events 41
Native fill-ins 172
Nested Blocks (-nb) startup
parameter 319, 324
Nested pull-down menus 222
Nested submenus 2212
NEXT processing 54
avoiding infinite loops 54
Next tab item 2545
NEXT-SIBLING attribute 2226
NEXT-TAB-ITEM attribute 2544
NEXT-VALUE function 969
syntax 968
NO-APPLY option 54
NO-BOX option, frame phrase
2541
NO-CONVERT-3D-COLORS
attribute 188
NO-CONVERT-3D-COLORS
option 188
NO-CURRENT-VALUE attribute
1710
NO-CURRENT-VALUE option
1710
NO-DRAG option, selection lists
1731
NO-ERROR option 56
CONNECT statement 93
NO-FILL option, rectangle widget
1815
NO-FOCUS attribute 184
NO-FOCUS option 184
NO-LOCK option, record phrase
138, 1313, 1316
Index26
risks 1310
NO-ROW-MARKERS option 108
NO-UNDO option
variables defined 1236, 1242
Non-persistent procedures,
described 337
Nonexecutable code. See
Compile-time code
Non-Progress databases 92
NORMAL menu items 2225
NUM-ITEMS attribute 1735,
1745
NUM-TABS attribute 2544
Number of Databases (-h) startup
parameter 92
Number of Users (-n) startup
parameter 96
Numeric colors, Windows color
dialog 2312
Numeric display formats 1753
O
ON ENDKEY phrase 517
ON ERROR phrase 510
ON QUIT phrase 519
ON statement 1122, 1634
ANYWHERE option 635,
641, 1640
changing key function 59, 513,
625
REVERT option 1639
ON STOP phrase 518
OPEN QUERY statement, browse
widget 1011
{&OPSYS} name reference 815
OS-DIR option, INPUT FROM
statement 726
OS-GETENV function 727
_osprint.p 711
Outer joins
see also Left outer join
full outer 946
right outer 946
Output
changing the destination 72
devices 76
files 76
multiple destinations 77, 719
printers 73
PUT statement 739
streams 72
terminal 76
Windows clipboard 76
working within procedures 71
OUTPUT CLOSE statement 78,
79, 722
OUTPUT STREAM statement 721
OUTPUT THROUGH statement
725
OUTPUT TO statement 72, 79
PAGED option 76
Overlay frames 1931
using 1930
OVERLAY option, DISPLAY
statement 1931
Overriding triggers 1123
Index27
Index
Overriding, internal procedures and
user-defined functions 352
P
PAGED option, OUTPUT TO
statement 76
Parameter files
different systems 92
invoking 92
Parameter File (-pf) startup
parameter 92
PARENT attribute 2226
Parent frames 1919
defining 1922
Parent windows 219
Parentheses ( ) 1753
Password 142
ENCODE function 142
validating password 143
Period (.) 1754
Permissions table 1410
adding records 1410
security 1416
using the Data Dictionary to
create 1410
PERSISTENT attribute, persistent
procedures 340, 2119
advantages 338
condition handling 346
context 344
creating 338
CURRENT-LANGUAGE
variable changes 346
CURRENT-WINDOW attribute
2120
deleting the context 341
described 337
dialog boxes 2129
DISABLE TRIGGERS statement
344
encapsulation 338
See also Encapsulation
examples 342
handles 339
instantiating 338
NEXT-SIBLING attribute 339
PERSISTENT attribute 2119
PREV-SIBLING attribute 339
PRIVATE-DATA attribute
2124
QUIT condition 346
run-time parameters 345
schema changes 346
schema locks 346
SESSION handle, example
2119, 2124
shared objects 344
STOP condition 346
transactions 345
UNDO processing 345
widget pools 2015
window management 2116
See also Persistent windows
Persistent triggers 1636
Persistent widget pools 2014
PFCOLOR
using 238
widget states 238
startup parameter, connection
parameter 92
Pixels 254
conversion with character units
255
Plus sign (+) 1754
Pop-up menus 223, 2229
dynamic pop-up menus 2229
static pop-up menus 2211
Index28
Portable accelerators 2220
Portable r-code A17
Positioning
character units 2517
pixels 2517
Preparing input files 730
Preprocessors 81
&ELSE directive 86
&ELSEIF directive 86
&ENDIF directive 86
&GLOBAL-DEFINE directive
82
&IF directive 86
&MESSAGE directive 810
&SCOPED-DEFINE directive
82
&THEN directive 86
&UNDEFINE directive 85
{&BATCH-MODE} 814
{&FILE-NAME} 814
{&LINE-NUMBER} 814
{&OPSYS} 815
{&SEQUENCE} 815
saving value 816
{&WINDOW-SYSTEM} 815
built-in names 814
quoting 816
references 814
DEFINED function 86, 810
expanding names 811
expressions 87, 89
name scoping 83
names 82, 85, 810, 811
nesting references 817
operators 87
referencing names 811
Preselect lists. See Results lists
PRESELECT option, browse
widgets 104
PRESELECT statement, EACH
option 310
Preselected queries 927
Presorted queries 926
PREV-SIBLING attribute,
PREV-TAB-ITEM attribute 2544
Previous tab item 2545
Printers
redirecting output 73
setting up on Windows 74, 75
Printing
_osprint.p 711
converting widgets 710
solutions 711
text files 711
PRIVATE-DATA attribute 1635
persistent procedures 340,
2124
Procedure blocks 317
described 32
error property 53
frame scoping 38
Procedure call stack
described 323
Procedure context, defined 319
Procedure handles
attributes 339
compared to other handles 1616
defined 328
TYPE attribute 329
validity 329
running internal procedures
332
Procedure overriding 352
Procedure parameters, run-time
323
PROCEDURE statement 330
Index29
Index
Procedure triggers
applying events 329
defined 328
Procedure-driven programming 22
definition 22
example 28
flow of execution 22
Procedures
call stack 323
changing output destination 72
changing the input source 714
compiling 126
context 319
external procedures 323
continuing processing 629
errors 56
executing 126
external 32
See also External procedures
handles 328
purpose 1616
internal 32, 330
See also Internal procedures
compared to triggers 1643
monitoring keystrokes 63
non-persistent 337
See also Non-persistent
procedures
parameters 323
persistent 337
See also Persistent procedures
properties 319
r-code integrity A24
example A25
running 126
scope 35
shared objects 325
sharing streams 722
super 352
using for security checking
1412
Processes, input and output streams
725
Processing, all-or-nothing 123
Program execution. See Flow of
control
Program structure
event-driven programs 29
procedure-driven programs 28
Programming models 21
event-driven 21
procedure-driven 21
Programming, multi-database,
techniques, and considerations
975
Programs
event-driven, example 210
procedure-driven, example 28
Progress 4GL 112
connectivity 111
consistency 17
data model 18
default processing 110
encapsulation 19
event handler 19
features 16
flexibility 17
foundations 11
help facilities 110
internationalization 112
interoperability 110
localizability 112
portability 111
preprocessor 19
programming models 19
security 110
syntax and semantics 112
See also Syntax of the 4GL
user interface model 18
Progress database functions 98
Progress file, colors and fonts 232
progress.ini file, Use-3D-Size
parameter 2552
PROLIB utility A5
Index30
PROMPT-FOR statement 917
_prostar.p procedure 143
PROTERMCAP file, colors and
fonts 232
Prototyping, super procedures 355
PUBLISH statement 42
PUBLISHED-EVENTS attribute
42
Pull-down menus 222
PUT statement 739
PUT-BYTE statement 974
PUT-KEY-VALUE statement
2321
example 2322
Q
Queries 921
See also Fetching records
browse selection 1011
browse widgets 103
field lists 933, 937
results lists 926
Query object 2015
Query, buffer, and buffer-field
objects, handles, purpose 1616
Query, dynamic query 2015
QUIT condition 52, 519
QUIT statement 519
QUOTER utility 731
example procedure 734
interactive 737
options
columns in fields 736
field delimiter 736
R
R-code CRC
schema triggers A25
Radio set widget 1719
initial value 1721
options 1720
Range, slider widget 1710
Rapid prototyping 126
RAW data field 1113
RAW data type 973, 1110
RAW statement 974
RAW TRANSFER statement
1110, 1113, 1114
R-code
action code segment A2, A3
CRC A24
debugger segment A3
defined A1
directory
described A7, A11
management A13
execution A7
available memory A11
environment limits A10,
A13
environment statistics A14
segment management A10,
A13
sequence A9, A12
execution buffer, described A7,
A11
execution environment A7,
A11
typical layout A8, A12
expression code segment A2
Index31
Index
factors affecting size A3
features A2, A7
files
segment layout A4
frame segment A3
initial value segment A2, A4
memory-mapped execution
environment A11
portability A17
segment descriptor table,
described A7, A11
segment types A2
standard execution environment
A7
structure A2
text segment A2
R-code CRC A24, A25
procedure integrity A24, A25
schema triggers
example A27
RCODE-INFO handle, R-code
CRC A25
R-code directory
described A7, A11
management A13
size A10
R-code file, segment layout A5
R-code segments A2
READ-ONLY attribute, browse
widgets 108
READ-ONLY menu items 2225
Reading multiple tables. See Joins
Read-only browse, defined 105
Realizing widgets 1626
Real-time 27
definition 27
event-driven programming 27
RECID data type
See also ROWID data type
converting to ROWID 925
DBRESTRICTIONS function
925
Record buffers 310, 916
Record locks
applying 136
AVAILABLE function 1319
avoiding record conflicts 134
bleeding 1315
bypassing 138
common problem 1311
duration 1310
LOCKED function 1319
multi-user applications 134
multiple buffers 1315
NO-LOCK 138
releasing 1310, 1312
resolving conflicts 1316
changing size of transactions
1322
transactions 1310
types 1313
Record phrase
EXCLUSIVE-LOCK option
135, 1313, 1316
field lists 933
NO-LOCK option 1316
SHARE-LOCK option 136,
1313, 1316
Record scoping
free references 310
strong 310
weak 310
Records
adding 919
adding to a permissions table
1410
deleting 919
fetching 921
locks 129, 133
releasing 317
retrieving 36
scoping 310
sharing 133
Index32
validation 317
writing 317
Rectangle widget 1815 to 1816
colors 1815
example 1816
proportions in character mode
1816
TOOLTIP option 1815
Redirecting I/O 725
input streams 714, 718
output streams 72, 77
References
free 310
resolving to fields 317
resolving to frame 37
Referencing widgets
dynamic 1613
static 1611
Registry
changing resources 2321
colors and fonts 232
RELEASE statement 917, 1310
Releasing records 317, 1310,
1312
Remote user-defined functions. See
REPEAT blocks 317
described 32
error property 53
frame scoping 38
REPEAT statement
FOR option 310
frame allocation 37
REPLACE method 1735, 1745
Replication Changes Log. See Data
replication
Replication configuration. See Data
replication
REPLICATION-CREATE trigger
1110, 1112
REPLICATION-DELETE trigger
1110, 1112
REPLICATION-WRITE trigger
1110, 1112
Reports
control-break 153
cross-tab 1513
spreadsheet 1513
tabular 1513
using work tables to write 153
REPOSITION statement 929
browse widgets 104, 1011
ROWID 925
Resizable browse 1040
additional attributes
programmatic manipulation
1044
user manipulation 1043
code example 1045
events, user manipulation 1044
Resize mode 2411
Resizing 1041
browse 1040
browse-column 1041
widgets 249, 2416
Resource, definitions, changing
2321
Results lists 926
navigating 929
RETAIN option, frame phrase 258
RETAIN-SHAPE, Image widget
1810
Retaining data during RETRY
1934
Index33
Index
See also RETAIN option
Retrieving records. See Fetching
records
RETRY function 54
RETRY processing 54, 57, 514
infinite loops 54
retaining data 38
RETURN event 189
RETURN key
dialog boxes 189
fill-in 175
RETURN processing 54
RETURN statement 526
ERROR option 56
RETURN-VALUE function 54,
526
Returning ERROR 54
REVERT option 1639
Reverting triggers 1123, 1639
RGB-VALUE function 232, 237
ActiveX controls 237
Root frames 1919
Root windows 219
Rounding errors, character units
255
ROW attribute 204
ROW frame phrase option 1931
Row height, browse, changing
1043
Row mode, character browse 1046
ROW option, frame phrase 2541
ROW-DISPLAY event 1023
ROW-ENTRY event 1023
ROW-LEAVE event 1023
ROWID data type 923
converting from RECID 925
CREATE statement 925
DataServer
portability 925
value construction 926
versions 925
views 925
INSERT statement 925
RECID 923
REPOSITION statement 925
returning record values 924
storing values 924
value scope 925
ROWID function 924
RULE menu items 2225
RUN statement
compared to COMPILE
statement 126, 127
for external procedures,
persistent 338
IN option 332
instantiating 338
non-persistent external
procedures 320
RUN-PROCEDURE option,
SUBSCRIBE statement 42
Run-time connection, methods list
95
Run-time code 119
execution 126
interaction with compile-time
123
object names 125
syntax elements 122
uses 127
Index34
Run-time parameters
procedure 323
Run-time procedure execution 126
Run-time security 141
S
Sample code, resizable browse
1045
SAVE CACHE statement 979
Schema Cache File (-cache) startup
parameter 982
Schema cache files
building 978
creating 978
example 980
DataServers 979
described 978
saving entire schema cache 979
saving partial schema cache 980
startup 982
Schema changes, persistent
procedures 346
Schema locks, persistent procedures
346
Schema security 141
Schema triggers 113, 114
auto-deployment example A27
locating 1127
R-code CRC A25
setting A24
validating A25
r-code CRC A24
deployment A27
Scope 116, 35
block context 116, 35
compared to context 324
data and widgets 35
frames 38
preprocessor names 83
records 310
triggers 35, 1636
unscoped resources 116
Scoped shared objects 325
&SCOPED-DEFINE directive 82
Scoping, dynamic, internal
procedures and user-defined
functions 352
Screen
buffers 916
resolutions 254
SCREEN-IO option 710
SCREEN-VALUE attribute 1735,
1745, 204, 205
Screens
See also Frame(s)
designing frames 252
length in lines 253
width 253
Scroll bars
editor widgets 1726
Scroll mode, character interfaces
2533
SCROLL-NOTIFY event 1034
browse widget 1020
SCROLL-TO-ITEM method 1735
Scrollable frames 2532
SCROLLABLE option 103
Scrolling
editor widgets 1726
Index35
Index
Scrolling queries 926
SEARCH function 78
Searching, browse columns 1015
Security
application 141
checking procedures 1412
checking user IDs at run-time
147
checking, activities-based 1410
compile-time 141
connection 141
password 142
validating password 143
permissions table 1416
run-time 141
schema 141
Segment descriptor table, described
A7, A11
Segment layout, r-code file A5
Segment management, r-code
A10, A13
Segment Statistics (-yd) parameter
A14
Segmented r-code A2
types A2
SELECT event 2412
SELECT mouse button 627
Selecting widgets 246
box selecting 247
multiple 248
Selection list widgets 1730 to
1739
attributes 1735
dragging 1731, 1732
example 1733, 1736
methods 1735
options 1731
scrolling 1732
SELF system handle 1635
Semantics of the 4GL
compile-time compared to
run-time 119
context 115
scope 116
SENSITIVE attribute 176, 1949
Sequence definitions
creating and maintaining 967
storage 967
{&SEQUENCE} name reference
815
saving value 816
Sequence statements and functions
968
_Sequence table 967
Sequences
accessing values 968
attributes 964
compiling procedures 971
control tables 963
performance 965
storage limits 967
trade-offs 964
transaction handling 966
defined 962
dumping and loading 967
fields 963
security 967
storage 967
transactions 966
WHERE clause 972
Server handles, compared to other
handles 1616
Servers, starting 1317
SESSION handle
Index36
frame spacing 2541
example 2119, 2124
Session triggers 113, 1121
SET statement 917
SET-REPOSITIONED-ROW
event 1025
method 1025
SETUSERID function 145
SHARE-LOCK option, record
phrase 1313, 1316
See also Record locking
Shared frames 1935
Shared objects
call stack 344
defining and referencing 327
external procedures 325
scoped compared to global 325
Shared queries, field lists 934
Sibling attributes, querying 2226
SIDE-LABEL-HANDLE attribute
204
SINGLE option, selection lists
1731
Single-select browse, defined 109
Single-window applications,
described 2114
SIZE phrase
button border thickness 186
buttons 186
combo boxes 1740
editor widgets 1724
fill-ins 173
NO-FOCUS option 186
sliders 1711
Sizing widgets 1630
SKIP menu items 2225
Slider widget 179
attributes 1710
even marker movement,
character mode 1711
example 1712
FREQUENCY option 1710
LARGE-TO-SMALL option
179
manipulating 1710
NO-CURRENT-VALUE option
1710
range 1710
size 1711
TIC-MARKS option 1710
Software failure, handling by
Progress 524
Sort (.srt) files A7, A10
r-code execution A9, A12
SORT attribute 1735, 1745
SORT option, combo boxes 1741
Sorting
comparing two methods 1512
using work tables 159
Specifying default frames 197
Spreadsheet reports. See Cross-tab
reports
.srt file. See Sort (.srt) file
Stack Size (-s) startup parameter
324
START-BOX-SELECTION event
2414
START-MOVE event 2413
START-RESIZE event 2413
Index37
Index
START-SEARCH event 1019
Startup messages 525
Startup parameters
connection 92
European Numeric Format (-E)
1756
Field List Disable (-fldisable)
937
grouping 92
multi-database connection 92
Number of Databases (-h) 92
92
Schema Cache File (-cache) 982
Startup Procedure (-p) 97
Time Stamp (-tstamp) 971
Trigger Location (-trig) 972
Triggers (-trig) 1127
Startup procedure
retrying 518
specifying 97
Startup Procedure (-p) startup
parameter 97
Statements
4GL 112
data handling 916
DEFINE BUTTON 182
DISPLAY 1931, 258
executable 119
nonexecutable 119
static and dynamic widgets 202
VIEW 1927, 2517
Static frames 194
Static menu bars 227
Static menus 225
enabling and disabling menu
items 2213
nested submenus 2212
pop-up menus 2211
Static submenus, defining
submenus 226
Static widgets
creating 167
defined 165
describing 167
instantiating 168
triggers 1634
Statistics (-y) startup parameter
A14
STOP condition 52, 518
STOP key 518
Stream I/O 710
converting widgets 710
STREAM-IO option 710
Streams 72
assignment 72
closing 78
default 72
defining additional 718
establishing 719
input 72, 718
opening 721
output 72, 718
redirecting 715
See also OUTPUT statements
redirecting input. See OUTPUT
statements
shared 722
unnamed 72
STRETCH-TO-FIT option
Image widget 1810
String conversion, ROWID data
type 924
STRING function, ROWID 924
Strip menus 2534
Index38
See also CHOOSE statement
Strong record scoping 310
SUB-MENU-HELP phrase 227
Submenus
dynamic 2224
static submenus 226
Subprocedures, transactions 1234
SUBSCRIBE statement 42
SUBSTRING function
QUOTER utility 735
Subtransactions 317, 1216
mechanics 1241
SUBTYPE attribute 173
Super procedure prototyping 355
Super procedures 352
Syntax of the 4GL 112
blocks 114
comments 113
statements 112
System failures
handling 1215
System handles 161, 1617
ERROR-STATUS 56
SELF 1635
SYSTEM-DIALOG COLOR
statement 2311
example 2313
SYSTEM-DIALOG FONT
statement 2311
example 2316
SYSTEM-DIALOG
PRINTER-SETUP statement 74,
75
T
-T startup parameter, temporary file
directory 1515
Tab
item 2544
order 2543
TAB-POSITION attribute 2544
Tabbing
fill-in 175
fill-in RETURN 2548
TABLE attribute 175
Tables
CRC calculation A20
joining. See Joins
reading multiple 938
word break 947
Tab-order widget 2544
Temporary Directory (-T) startup
parameter 1515
Temporary tables 1515
See also Work tables
advantages over work tables
1516
based on database tables 1519
buffer size 1515
characteristics 1515
DEFINE TEMP-TABLE
statement 1516
deletion 1519
differences from work tables
1519
indexes 1516, 1522
joins 941
performance 1519
sharing 1519
similarities to work tables 1519
using FIND statement 1516
Index39
Index
Terminals, screen formatting 252
Terminating sequences, resetting
972
Text segments
r-code A2
translation A4
Text widgets 176
&THEN directive 86
THIS-PROCEDURE handle 328
THREE-D attribute 2549
Three-dimensional effects 2549,
2551
example 2550
images 2551
layout considerations 2552
rectangles 2551
windows 2552
TIC-MARKS attribute 1710
TIC-MARKS option 1710
Tilde (~), input files 742
Time Stamp (-tstamp) startup
parameter 971
Time stamps
compared to CRC A21
database changes affecting A21
deployment A22
validation A19
TITLE option, DISPLAY statement
258
Title, frames 258
TO-ROWID function 924
Toggle box widget 1714
attributes 1714
Toggle boxes, menu items 2215
TOOLTIP attribute 182, 1814,
1815
TOOLTIP option 182, 1814,
1815
TRANSACTION function 1240
TRANSACTION option, blocks
128, 1218
Transactions 122
active 1240
begin and end 128
benefits of small 1321
blocks 317, 128
changing size, resolve record
locks 1322 to 1325
controlling 1218
database connections 1239
defined 122
handles, purpose 1616
handling 122
improving efficiency 1242
input from a file 1236
making larger 1219, 1323
making smaller 1221, 1324
mechanics 1241
modeless model 1228
multi-windows 213
multiple databases 1239
processing 123
relationship to record locks
1310
specifying UNDO processing
1215
subprocedures 1234
subtransactions 1216
triggers 1223
variables 1236
TRANSPARENT, Image widget
1810
Trigger blocks 317
described 33
Index40
Trigger Location (-trig) startup
parameter 972
Trigger-based replication 1110
Triggers
database 111
defined 26
definitional 1634
dynamic widgets 1636
execution 1636
frames 39, 1917
LIKE option 1635
NO-APPLY option 54
persistent 1636
procedure 328
See also Procedure triggers
real-time response 28
reverting 1639
run-time 1634
schema 114
scope 1636
static widgets 1634
transactions 1223
universal 1640
user-interface 1631
Triggers (-trig) startup parameter
1127
Two-phase commit 1239
TYPE attribute 329
handles 1619
U
&UNDEFINE directive 85
UNDO keyword, usage rules 53
UNDO processing 57, 510, 514,
517, 518, 519, 122, 1215,
1236
UNDO statement 1217
UNFORMATTED option,
Universal triggers 1640
UNIX, processes as input and output
streams 725
UNLOAD statement
scenario 2324
using 2323
Unnamed frame 37
Unnamed streams 72
Unscoped resources 116
UNSUBSCRIBE statement 42
UPDATE statement 917
Updateable browse, defined 107
USE statement
scenario 2324
using 2323
Use-3D-Size parameter,
progress.ini file 2552
USE-DICT-EXPS option, frame
phrase 1950
USE-TEXT attribute 178
User count, exceeding 92
User IDs 142
blank 145
checking at run time 147
validating user ID 143, 149
validation list 149
User interfaces
character 212
graphical 212
User-defined functions 347
Index41
Index
external. See Persistent
procedures
local. See Persistent procedures
prototyping 356
remote. See Persistent procedures
User-interface components 161
See also Widgets
USERID function 149, 1410
User-interface events 1631
User-interface triggers 635
instead of EDITING blocks 637
monitoring keystrokes 1631
V
VALID-HANDLE function 1619
procedure handles 329
VALIDATE method
data widgets 1952
frames 1949
VALIDATE option
DEFINE BROWSE statement
1949
DEFINE FRAME statement
1949
FORM statement 1949
Validation
Data Dictionary
disabling 1954
forcing 1951
data widgets 1952
field-level 730
frames 1949
records 317
VALUE option
OUTPUT TO statement 78
run-time object names 125
VALUE-CHANGED event 1633,
1717, 1722, 1730, 1732,
1740, 1744, 1748, 2216
browse widget 1020
Variables, transactions 1236
Version, of Progress, determining
the current 619
VIEW statement 1927, 2517
VIEW-AS phrase 1610, 172
Viewing, frames 38
VIRTUAL-HEIGHT-CHARS
attribute 2532
VIRTUAL-HEIGHT-PIXELS
attribute 2532
VIRTUAL-WIDTH-CHARS
attribute 2532
VIRTUAL-WIDTH-PIXELS
attribute 2532
Visual colors, Windows color
dialog 2312
W
WAIT-FOR condition 27
WAIT-FOR statement 29, 210
END-ERROR key 523
Weak record scoping 310
Widget attribute references 1621
Widget handles
compared to other handles 1615
defined 166
Widget method references 1623
Widget pools 209
creating 209
deleting 209, 2011, 2014
Index42
named 2010
persistent 2010
session pool 209
unnamed 2014
Widget types 163
WIDGET-HANDLE data type 166
WIDGET-HANDLE function
1619
Widgets 161
atomic 163
attributes 1620
box selecting 247
browse 101 to 1053, 139
button 182, 189
DEFAULT option 189
combo box 1739 to 1749
attributes 1745
example 1743 to 1746
item selection 1739 to 1748
methods 1745
options 1740
value settings 1742
containers 163
converting for stream I/O 710
creating 166
data representation
choosing 171 to 175
defined 164
VIEW-AS phrase 172
default 172
default display formats 1751
deleting dynamic 1613
derealizing 1629
describing static 167
DEFINE widget statement
1610
frames and dialog boxes
1610
VIEW-AS phrase 1610
dragging 248
dynamic 165
See also Dynamic widgets
editor 1724
attributes 1727
example 1728
interactions 1726
methods 1727
options 1724
save file portability 1730
fill-in 172, 176
attributes 173
fonts used in Windows 175
format 1749 to 1757
character 1751
date 1758
decimal 1753 to 1756
integer 1753 to 1756
logical 1757
grid alignment 2417
handles 166
purpose 1615
hierarchy 164
highlighting 246, 2410
image 189 to 1814
determining image file size
1810
example 1812
ignoring file at compile time
1810
methods 1811
options 189
instantiating static 168
instantiating, defined 166
methods 1623
moving 248, 2410, 2416
overview 163
radio set 1719
initial value 1721
options 1720
realizing 1626
rectangle 1815
EDGE-CHARS option 1815,
1816
EDGE-PIXELS option 1815,
1816
example 1816
NO-FILL option 1815
proportions in character mode
1816
referencing dynamic 1613
referencing static 1611
Index43
Index
resizing 249, 2410, 2416
selecting 246, 248
selection list 1730 to 1738
attributes 1735
example 1733, 1736
methods 1735
options 1731
sizing 1630
slider 179, 1711
example 1712
range 1710
size 1711
static 165
text 176
toggle box 1714
attributes 1714
types 163
window 211 to 2130
attributes 214
creating at run-time 218
events 218
maximizing 218
methods 215
minimizing 218
restoring 218
restrictions in character mode
218
working with static 1610
WIDTH attribute 174
WIDTH option, browse widgets
1014
WIDTH-CHARS attribute 1711,
204
WIDTH-PIXELS attribute 1711
Window families
defined 219
example 2111, 2129
Window size 255
Window widgets 211 to 2130
attributes 214
creating at run-time 218
events 218
maximizing 218
methods 215
minimizing 218
restoring 218
restrictions in character mode
218
WINDOW-CLOSE event 1633,
218
WINDOW-MAXIMIZED event
1633, 218
WINDOW-MINIMIZED event
1633, 218
WINDOW-RESTORED event
1633, 218
{&WINDOW-SYSTEM} name
reference 815
Windows
active 2549
character simulated 253
clipboard output 76
color 239
Palette Manager 239, 2310
compared to dialog boxes 213
current procedure 211
current session 211
default 211
directing I/O 2116
families 219
multi-window pros and cons
212
multiple non-persistent 2114,
2115
multiple persistent 2116
See also Multiple windows
described 2114
printer setup 74, 75
single, described 2114
transactions 213
types of applications 2114
Windows interface design options
2552
Icon size 2553
Index44
Progress support for
Winhlp32.exe 2553
ToolTips 2552
WITH option, frame phrase 257
Word break tables 947
internationalization 947
Word indexing 947
Word wrap, editor widgets 1726
Word-break, rules file
applying to database 956
compiling 955
Work tables 152
See also Temporary tables
based on database tables 1519
characteristics 152
DEFINE WORK-TABLE
statement 155, 158
differences from temporary
tables 1519
joins 941
number allowed in memory 152
similarities to temporary tables
1519
using FIND FIRST statement to
sort 1510
using to collect data 157
using to create cross-tab reports
1513
using to manipulate data 157
using to produce control-break
reports 153
using to sort 159
using to write reports 153
WRITE trigger 113, 115
Writing records 317
X
X attribute 204
X, format character 1752
Y
Y attribute 204
-y startup parameter, statistics A14
-yd startup parameter, Segment
Statistics A14
Z
Z, format character 1754
Z order 1932
Index45
Index
Index46

Progress

Uploaded by

Copyright:

Available Formats

Progress

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Progress

Uploaded by

Copyright:

Available Formats

Progress

2001 Progress Software Corporation. All rights reserved.

are trademarks of IBM Corporation and are used

BEFORE_DIGIT Treated as part of a word

DISPLAY "Daily Report"

Action Code Segment (Internal Procedure)

One per Internal Procedure

One per Frame

One per Language

Segment Descriptor Table

R-code files listed in

You might also like