manual openedge 4 gl

© 2005 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.
A (and design), Allegrix, Allegrix (and design), Business Empowerment, DataDirect (and design) DataDrirect Connect, DataDirect OLE DB, DirectALert, EdgeXtend, Empowerment Center, eXcelon, IntelliStream, O (and design), ObjectStore, OpenEdge, PeerDirect, P.I.P., POSSENET, Powered by Progress, Progress, Progress Dynamics, Progress Empowerment Center, Progress Empowerment Program, Progress Fast Track, Progress OpenEdge, Partners in Progress, Partners en Progress, Persistence, Persistence (and design), ProCare, Progress en Partners, Progress in Progress, Progress Profiles, Progress Results, Progress Software Developers Network, ProtoSpeed, ProVision, SequeLink, SmartBeans, SpeedScript, Stylus Studio, Technical Empowerment, WebSpeed and Your Software, Our Technology–Experience the Connection are registered trademarks of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and/or other countries. AccelEvent, A Data Center of Your Very Own, AppsAlive, AppServer, ASPen, ASP-in-a-Box, BusinessEdge, Cache-Forward, DataDirect, DataDirect Connect64, DataDirect Technologies, Data Direct XQuery, DataXtend, Fathom, Future Proof, ObjectCache, ObjectStore Event Engine, ObjectStore Inspector, ObjectStore Performance Expert, ObjectStore Trading Accelerator, POSSE, ProDataSet, Progress Business Empowerment, Progress DataXtend, Progress for Partners, Progress ObjectStore, PSE Pro, PS Select, SectorAlliance, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, WebClient, and Who Makes Progress are trademarks or service marks of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and other countries. SonicMQ is a registered trademark of Sonic Software Corporation in the U.S. and other countries. Vermont Views is a registered trademark of Vermont Creative Software in the U.S. and other countries. IBM is a registered trademark of IBM Corporation. JMX and JMX-based marks and Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Any other trademarks or service marks contained herein are the property of their respective owners.
OpenEdge includes Imaging Technology copyrighted by Snowbound Software 1993-2003.www.snowbound.com.
OpenEdge includes software developed by the Apache Software Foundation (http://www.apache.org/ ). Copyright © 1999 The Apache Software Foundation. All rights reserved (Xerces C++ Parser (XML) and Xerces2 Java Parser (XML)); Copyright © 1999-2002 The Apache Software Foundation. All rights reserved (Xerces Parser (XML)); and Copyright © 2000-2003. The Apache Software Foundation. All rights reserved (Ant). The names “Apache,” “Xerces,” “ANT,” and “Apache Software Foundation” must not be used to endorse or promote products derived from this software without prior written permission. Products derived from this software may not be called “Apache”, nor may “Apache” appear in their name, without prior written permission of the Apache Software Foundation. For written permission, please contact [email protected]. Software distributed on an “AS IS” basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License agreement that accompanies the product.
OpenEdge includes software developed by Vermont Creative Software. Copyright © 1988-1991 by Vermont Creative Software.
OpenEdge includes software developed by IBM and others. Copyright © 1999, International Business Machines Corporation and others. All rights reserved.
OpenEdge includes code licensed from RSA Security, Inc. Some portions licensed from IBM are available at http://oss.software.ibm.com/icu4j/ .
OpenEdge includes the UnixWare platform of Perl Runtime authored by Kiem-Phong Vo and David Korn. Copyright © 1991, 1996 by AT&T Labs. Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software. THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHORS NOR AT&T LABS MAKE ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
OpenEdge includes the RSA Data Security, Inc. MD5 Message-Digest Algorithm. Copyright ©1991-2, RSA Data Security, Inc. Created 1991. All rights reserved.
OpenEdge includes software developed by the World Wide Web Consortium. Copyright © 1994-2002 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All rights reserved. This work is distributed under the W3C® Software License [http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231] in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
OpenEdge includes code licensed from Mort Bay Consulting Pty. Ltd. The Jetty Package is Copyright © 1998 Mort Bay Consulting Pty. Ltd. (Australia) and others.
OpenEdge includes the JMX Technology from Sun Microsystems, Inc.
OpenEdge includes software developed by the ModelObjects Group (http://www.modelobjects.com). Copyright © 2000-2001 ModelObjects Group. All rights reserved. The name "ModelObjects" must not be used to endorse or promote products derived from this software without prior written permission. Products derived from this software may not be called "ModelObjects", nor may "ModelObjects" appear in their name, without prior written permission. For written permission, please contact [email protected].
OpenEdge includes files that are subject to the Netscape Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/NPL/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. The Original Code is Mozilla Communicator client code, released March 31, 1998. The Initial Developer of the Original Code is Netscape Communications Corporation. Portions created by Netscape are Copyright © 1998-1999 Netscape Communications Corporation. All Rights Reserved.
Product Code: 4496 R10.1A
&MESSAGE preprocessor directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
&SCOPED-DEFINE preprocessor directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
CREATE BROWSE statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
CREATE BUFFER statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
CREATE CALL statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
CREATE CLIENT-PRINCIPAL statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
CREATE DATABASE statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
CREATE DATASET statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
CREATE DATA-SOURCE statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
CREATE QUERY statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
CREATE SAX-READER statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
CREATE SAX-WRITER statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
CREATE SERVER statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
CREATE SERVER-SOCKET statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
CREATE SOAP-HEADER statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
CREATE SOAP-HEADER-ENTRYREF statement . . . . . . . . . . . . . . . . . . . . . . . 234
CREATE SOCKET statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
CREATE TEMP-TABLE statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
CREATE widget statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
CREATE WIDGET-POOL statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
CREATE X-DOCUMENT statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
CREATE X-NODEREF statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
AUDIT-CONTROL system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384
AUDIT-POLICY system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385
Buffer object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1386
Buffer-field object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1389
CALL object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1390
Client-principal object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397
CLIPBOARD system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1399
CODEBASE-LOCATOR system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1408
COLOR-TABLE system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410
COM-SELF system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1413
COMPILER system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1414
CURRENT-WINDOW system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416
Data-relation object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417
Data-source object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1419
DEBUGGER system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421
DEFAULT-WINDOW system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425
ERROR-STATUS system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1426
FILE-INFO system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1431
FOCUS system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1433
SESSION system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460
SOAP-fault object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1467
SOAP-fault-detail object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1468
SOAP-header object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1469
SOAP-header-entryref object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1470
Socket object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1472
SOURCE-PROCEDURE system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1474
TARGET-PROCEDURE system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1477
Temp-table object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1481
THIS-PROCEDURE system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1484
Transaction object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1488
WEB-CONTEXT system handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1490
X-document object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1492
X-noderef object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494
Referencing widget attributes and methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1498
Widget attribute references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1498
Widget method references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1499
COM object references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1501
Event priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2172
Applying events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2172
Event tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2174
Keyboard events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2175
Mouse events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2178
Table 1: Using the Unknown value (?) in comparison operations . . . . . . . . . . . 3
Table 2: Entering special characters in the Procedure Editor . . . . . . . . . . . . . . 4
Table 3: Built-in preprocessor names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Table 4: SpeedScript built-in preprocessor names . . . . . . . . . . . . . . . . . . . . . . 19
Table 5: Preprocessor expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 6: Preprocessor operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 7: Functions allowed in preprocessor expressions . . . . . . . . . . . . . . . . . 27
Table 8: Default Assignment operator character conversions . . . . . . . . . . . . . 47
Table 9: Default character conversions with the ASSIGN statement . . . . . . . . 74
Table 10: Values to use for ID lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Table 11: CHOOSE statement actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Table 12: Class data member types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Table 13: Windows colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Table 14: Relational operators and the Unknown value (?) . . . . . . . . . . . . . . . . . 153
Table 15: Reference types and object identifiers . . . . . . . . . . . . . . . . . . . . . . . . . 161
Table 16: Valid statement type and detail tag combination . . . . . . . . . . . . . . . . . 166
Table 17: Default COPY-LOB statement character conversions . . . . . . . . . . . . 194
Table 18: Automation object connection options . . . . . . . . . . . . . . . . . . . . . . . . . 206
Table 19: Progress data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Table 20: Default initial values and display formats . . . . . . . . . . . . . . . . . . . . . . . 263
Table 21: DBRESTRICTIONS keyword values . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Table 22: DBRESTRICTIONS return values by DataServer . . . . . . . . . . . . . . . . 287
Table 23: Determining button border thickness . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Table 24: 3D-color conversions for buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Table 25: 3D-color conversions for images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Table 26: Data types for DLL and UNIX shared library routine parameters . . . . 388
Table 27: Data types for ActiveX control event procedures . . . . . . . . . . . . . . . . . 390
Table 28: XML node types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Table 29: Default display formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Table 30: Default variable initial values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Table 31: Progress version 6 index selection examples . . . . . . . . . . . . . . . . . . . 596
Table 33: Default data type display formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
Table 34: Determining labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
Table 35: Using PAGE-TOP and PAGE-BOTTOM frames . . . . . . . . . . . . . . . . . 627
Table 36: Standard ISO formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
Table 39: Suppressing messages to the terminal . . . . . . . . . . . . . . . . . . . . . . . . 829
Table 40: Progress OS-ERROR codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906
Table 41: Key actions in a TEXT field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971

Table 45: RUN statement ERROR and STOP conditions . . . . . . . . . . . . . . . . . . . 1105
Table 46: Key actions in a TEXT field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156
Table 47: Byte order options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162
Table 48: Determining a UNIX user ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1172
Table 49: Determining a Windows user ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173
Table 50: Key actions in a TEXT() field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1269
Table 51: Determining a UNIX user ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1279
Table 52: Determining a Windows user ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1280
Table 53: System handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1308
Table 54: Keyword constants for the CALL-TYPE attribute . . . . . . . . . . . . . . . . . 1578
Table 55: CLIENT-TYPE attribute values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1591
Table 56: AppServer basic connection parameters . . . . . . . . . . . . . . . . . . . . . . . 1602
Table 57: AppServer session model connection parameters . . . . . . . . . . . . . . . . 1605
Table 58: Socket connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1610
Table 59: Web service connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 1612
Table 60: 3D-color conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1624
Table 61: Relationship between the SUBTYPE and NAME attributes . . . . . . . . . 1637
Table 62: Progress DDE errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1650
Table 63: Socket connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684
Table 64: IANA encodings and corresponding Progress code pages . . . . . . . . . . 1687
Table 65: File type characters — one per file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1711
Table 66: File type characters — one or more per file . . . . . . . . . . . . . . . . . . . . . 1712
Table 67: FILL( ) method modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1714
Table 68: Options for GET-SOCKET-OPTION( ) . . . . . . . . . . . . . . . . . . . . . . . . . 1771
Table 69: What INVOKE( ) does for each call type . . . . . . . . . . . . . . . . . . . . . . . . 1821
Table 70: What IN-HANDLE indicates and who sets it . . . . . . . . . . . . . . . . . . . . . 1823
Table 71: Progress mouse pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1854
Table 72: Log entry types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1864
Table 73: Pop-up menu button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1879
Table 74: NEXT-SIBLING attribute values by handle type . . . . . . . . . . . . . . . . . . 1906
Table 75: PARSE-STATUS attribute values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1932
Table 76: PREV-SIBLING attribute values by handle type . . . . . . . . . . . . . . . . . . 1940
Table 77: Valid read modes for the READ( ) method . . . . . . . . . . . . . . . . . . . . . . 1954
Table 78: READ-XML( ) method read modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1958
Table 79: READ-XML( ) method schema verification modes . . . . . . . . . . . . . . . . 1961
Table 80: READ-XMLSCHEMA( ) method verification modes . . . . . . . . . . . . . . . 1969
Table 81: REPLACE flag values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1987
Table 82: Row state values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002
Table 83: SCHEMA-MARSHAL attribute values . . . . . . . . . . . . . . . . . . . . . . . . . . 2015
Table 84: SEARCH flag values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2024
Table 85: Options for the SET-SOCKET-OPTION( ) method . . . . . . . . . . . . . . . . 2069
Table 86: STARTUP-PARAMETERS attribute usage examples . . . . . . . . . . . . . 2082
Table 87: Supported cryptographic algorithm names . . . . . . . . . . . . . . . . . . . . . . 2093
Table 88: TIC-MARK values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102

Table 92: Universal key function events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2175
Table 93: Navigation key function events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2176
Table 94: Field editing key function events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2177
Table 95: Default keyboard events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2177
Table 96: Portable mouse events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2178
Table 97: Three-button mouse events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2180
Table 98: High-level widget events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2182
Table 99: General direct manipulation events . . . . . . . . . . . . . . . . . . . . . . . . . . . 2189
Table 100: Frame-only direct manipulation events . . . . . . . . . . . . . . . . . . . . . . . . 2192
Table 101: First-level FILL events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2196
Table 102: Second-level FILL events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2197
Table 103: Row-level events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2198

• Purpose
• Audience
• Organization
This book defines the Progress® 4GL. It covers all 4GL statements, functions, phrases, operators, preprocessor directives, special symbols, widgets, handles, attributes, methods, events, and classes.
Audience
This book is intended for programmers who develop applications using Progress and for anyone who needs to read and understand Progress 4GL code.
Organization
• A dictionary of Progress statements, functions, phrases, operators, preprocessors, and special symbols beginning with the letters A–Z.
• A dictionary of Progress widgets.
• A dictionary of Progress handles.
• A dictionary of Progress attributes and methods.
• Tables of Progress events.
• An index of Progress 4GL keywords.

Using this manual
Each Progress language element reference description includes some subset of the following information:
• Platform-restriction notations.
• Block properties for all block statements.
• Data-movement diagrams for all data-handling statements.
• The syntax for the language element.
• The options and arguments you can use with the language element.
• One or more examples that illustrate the use of the language element.
• Notes that highlight special cases or provide hints on using the language element.
• A See Also section that lists related language elements.
Platform-restriction notes
Some language elements and features of the Progress 4GL do not apply to all software platforms—operating systems, user interfaces, and database management systems—that OpenEdge® supports. The documentation tries to note each such platform restriction with the language element title. Some language elements apply to SpeedScript programming and some do not; the documentation indicates which language elements do not apply with a note in the language element description.

Preface–4
The platform restriction notes that appear in the documentation include the following:
• AppServer™ only
The element or feature applies only to the OpenEdge AppServer.
• Character interfaces only
The element or feature applies only to the character interfaces that OpenEdge supports.
• Graphical interfaces only
The element or feature applies only to the graphical interfaces that OpenEdge supports.
• NT and UNIX only
The element or feature applies only to the Windows and UNIX versions that OpenEdge supports.
• ORACLE only
The element or feature applies only to the ORACLE versions that OpenEdge supports.
• UNIX only
The element or feature applies only to the UNIX versions that OpenEdge supports.
• Windows only
The element or feature applies only to the Windows versions that OpenEdge supports.
• Windows only; Graphical interfaces only
The element or feature applies only to the graphical interfaces of the Windows and versions that OpenEdge supports.
For a complete list of the software platforms that OpenEdge supports, see OpenEdge Getting
Started: Installation and Configuration.
Convention Description
Bold Bold typeface indicates commands or characters the user types, provides emphasis, or the names of user interface elements.
Italic Italic typeface indicates the title of a document, or signifies new terms.
SMALL, BOLD
CAPITAL LETTERS Small, bold capital letters indicate OpenEdge® key functions and generic keyboard keys; for example, GET and CTRL.
KEY1+KEY2 A plus sign between key names indicates a simultaneous key sequence: you press and hold down the first key while pressing the second key. For example, CTRL+X.
KEY1 KEY2 A space between key names indicates a sequential key sequence: you press and release the first key, then press another key. For example, ESCAPE H.
Syntax:
Fixed width A fixed-width font is used in syntax statements, code examples, system output, and filenames.
Fixed-width italics Fixed-width italics indicate variables in syntax statements.
Fixed-width bold Fixed-width bold indicates variables with special emphasis.
UPPERCASE fixed width
Uppercase words are Progress® 4GL language keywords. Although these are always shown in uppercase, you can type them in either uppercase or lowercase in a procedure.
This icon (three arrows) introduces a multi-step procedure.
This icon (one arrow) introduces a single-step procedure.
Period (.) or colon (:)

Examples of syntax descriptions
In this example, ACCUM is a keyword, and aggregate and expression are variables:
FOR is one of the statements that can end with either a period or a colon, as in this example:
[ ] Large brackets indicate the items within them are optional.
[ ] Small brackets are part of the Progress 4GL language.
{ } Large braces indicate the items within them are required. They are used to simplify complex syntax diagrams.
{ } Small braces are part of the Progress 4GL language. For example, a called external procedure must use braces when referencing arguments passed by a calling procedure.
| A vertical bar indicates a choice.
... Ellipses indicate repetition: you can choose one or more of the preceding items.
Convention Description
END.
In this example, STREAM stream , UNLESS-HIDDEN, and NO-ERROR are optional:
In this example, the outer (small) brackets are part of the language, and the inner (large) brackets denote an optional item:
A called external procedure must use braces when referencing compile-time arguments passed by a calling procedure, as shown in this example:
In this example, EACH, FIRST, and LAST are optional, but you can choose only one of them:
In this example, you must include two expressions, and optionally you can include more. Multiple expressions are separated by commas:
Syntax
Syntax
Syntax
Preface–8
In this example, you must specify MESSAGE and at least one expression or SKIP [ (n) ], and
any number of additional expression or SKIP [ ( n ) ] is allowed:
In this example, you must specify {include-file, then optionally any number of argument or &argument-name = "argument-value" , and then terminate with }:
Long syntax descriptions split across lines
Some syntax descriptions are too long to fit on one line. When syntax descriptions are split across multiple lines, groups of optional and groups of required items are kept together in the required order.
In this example, WITH is followed by six optional items:
Syntax

optional elements
Some syntax descriptions are too complex to distinguish required and optional elements by bracketing only the optional elements. For such syntax, the descriptions include both braces (for required elements) and brackets (for optional elements).
In this example, ASSIGN requires either one or more field entries or one record . Options available with field or record are grouped with braces and brackets:
Example procedures
This manual provides numerous example procedures that illustrate syntax and concepts. You can access the example files and details for installing the examples from the following locations:
• The Documentation and Samples CD that you received with your product.
• The Progress Documentation Web site:
Syntax
| { record [ EXCEPT field ... ] }
Preface–10
OpenEdge messages
OpenEdge displays several types of messages to inform you of routine and unusual occurrences:
• Execution messages inform you of errors encountered while OpenEdge is running a procedure; for example, if OpenEdge cannot find a record with a specified index field value.
• Compile messages inform you of errors found while OpenEdge is reading and analyzing a procedure before 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 OpenEdge is getting ready to execute; for example, if you entered an invalid startup parameter.
After displaying a message, OpenEdge 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 after execution messages.
• Returns to the Progress Procedure Editor, so you can correct an error in a procedure. This is the usual action taken after compiler messages.
• Halts processing of a procedure and returns immediately to the Progress Procedure Editor. This does not happen often.
• Terminates the current session.
OpenEdge messages end with a message number in parentheses. In this example, the message number is 200:
If you encounter an error that terminates OpenEdge, note the message number before restarting.
** Unknown table name table. (200)
Obtaining more information about OpenEdge messages
In Windows platforms, use OpenEdge online help to obtain more information about OpenEdge messages. Many OpenEdge tools include the following Help menu options to provide information about messages:
• Choose Help→Recent Messages to display detailed descriptions of the most recent OpenEdge message and all other messages returned in the current session.
• Choose Help→Messages and then type the message number to display a description of a specific OpenEdge message.
• In the Progress Procedure Editor, press the HELP key or F1.
On UNIX platforms, use the Progress pro command to start a single-user mode character OpenEdge client session and view a brief description of a message by providing its number.
To use the pro command to obtain a message description by message number:
1. Start the Progress Procedure Editor:
2. Press F3 to access the menu bar, then choose Help→Messages.
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 Progress Procedure Editor menu, and choose File→Exit.
install-dir /dlc/bin/pro
This section contains reference entries that describe the Progress® language. They begin with descriptions of the language punctuation and special characters. The remaining entries contain descriptions of the Progress statements, functions, phrases, preprocessor directives, and miscellaneous other language elements.
You can consider a language element as supported for all interfaces, on all operating systems, and for SpeedScript unless otherwise indicated in the language element description.
: Punctuation
The colon (:) symbol ends block labels and block header statements like DO, FOR, and REPEAT. It serves as a separator between a widget reference and an attribute or method, and between a character string literal and its attributes. It also follows the EDITING keyword in an EDITING phrase and is a device delimiter in Windows.
; Special character
@ ][ ^ ' ~}|{
;' ;( ;% ;) ;?;& ;< ;*;>
. Punctuation
2
To suppress the semicolon’s interpretation as a special character, precede it with a tilde (~). For example, to enter the string ;< in the Procedure Editor and not have Progress interpret it as an open bracket, type ~;<.
Additionally, if an ASCII character is mapped to an extended alphabetical character by an IN statement in the PROTERMCAP file, you can enter the extended character in the Procedure Editor by preceding the ASCII character with a semicolon. For example, if [ is mapped to Ä, Progress interprets the ;[ sequence as Ä.
. Punctuation
The period (.) symbol ends all statements, including block header statements. It is also a directory path or file suffix separator in most platforms. The DO, FOR, and REPEAT statements can end with a period or a colon.
; Punctuation
In Progress Version 6.0 or later, the ANSI SQL (-Q) startup parameter allows you to redefine the semicolon as a terminator. This startup parameter enforces strict ANSI SQL conformance and allows you to terminate SQL statements with a semicolon. The ANSI SQL (-Q) parameter allows Progress to run standard SQL statements and scripts built with other products.
The ANSI SQL (-Q) parameter disables the use of the semicolon within UNIX escapes.
As a general rule, use the period (.) as a terminator for Progress statements even when you specify the ANSI SQL (-Q) parameter for an OpenEdge® session.
, Punctuation
The comma (,) symbol separates multiple file specifications (used in FOR statements, FOR phrases of DO and REPEAT statements, and PRESELECT phrases), branching statements (used in UNDO statements and phrases), and multiple arguments of a function.
UNIX SMBL=foo; export SMBL

? Special character
The question mark is a special character that represents the Unknown value. Progress treats a quoted question mark ("?") in a procedure or an input field as a question mark character. It treats an unquoted question mark (?) in a procedure or an input field as an unknown value.
Table 1 indicates the results when using the Unknown value (?) in a comparison expression (EQ, GE, GT, LE, LT, NE). These results are true for both character and integer variables.
Note: WebSpeed® treats an unquoted question mark (?) in an HTML input field as a character.
Additional points about the Unknown value (?) are:
• Any number of Unknown value (?) records can be in a unique index. This is useful in cases where you want to defer choosing key values for a unique index.
• If you define a field as mandatory in the Dictionary, that field cannot contain the Unknown value (?) when OpenEdge writes the record to the database.
• For sorting and indexing purposes, the Unknown value (?) sorts high.
Table 1: Using the Unknown value (?) in comparison operations
Comparison operator One argument is ? Both arguments are ?
EQ or = F T
4
• The question mark (?) character in the first position of a field equals the Unknown value (?), not a question mark.
• When using the Unknown value (?) in a comparison expression for SQL, the result is unknown.
• When using the Unknown value (?) in an expression, the result of that expression is usually unknown. For example, when you concatenate first, middle, and last names, and the middle name is ?, then the result is ?.
For information on how the Unknown value (?) works with logical data types, comparison operators, and conditional statements, see the following reference entries: EQ or = operator, GE or >= operator, GT or > operator, IF...THEN...ELSE statement, LE or < = operator, LT or < operator, NE or <> operator.
\ Special character
The backslash (\) is an escape character on UNIX platforms only. It is a directory path separator in Windows platforms only.
~ Special character
The tilde (~) is an escape character that causes Progress to read the following character literally. A tilde followed by three octal digits represents a single character. Use it as a lead-in to enter the special characters shown in Table 2. In a procedure, a tilde followed by something other than the items in Table 2 is ignored. For example, “~abc” is treated as “abc”. (This may not work as expected when passing parameters to an include file.) The items in Table 2 are case sensitive.
Table 2: Entering special characters in the Procedure Editor (1 of 2)
Sequence Interpreted as Comment
~~ ~ –
~\ \ –

” Special character
The double quote (”) encloses character constants or strings. To use quotes within a quoted character string, you must use two double quotes (””), which compile to a single double quote (”), or you must put a tilde (~) in front of any quotes within the quoted character string. (This does not work when passing parameters to an include file.)
See also “ ” Character-string literal.
’ Special character
The function of the single quote (’) is the same as the double quote. But, if you use single and double quotes in a statement, the compiler checks the outermost quotes first, giving them precedence over the innermost quotes. For example, DISPLAY ’"test"’ returns as "test". (Progress reads the double quotes literally.) And DISPLAY "’test2’" returns as ’test2’.
~{ { –
~nnn A single character Where nnn is an octal value between 000 and 377. All three digits are required.
~t Tab character Octal 011
~r Carriage return Octal 015
~n New line / Line feed Octal 012
~E Escape Octal 033
~b Backspace Octal 010
~f Form feed Octal 014
Table 2: Entering special characters in the Procedure Editor (2 of 2)
Sequence Interpreted as Comment
/ Special character
The slash (/) symbol is a directory path separator (UNIX). It is also used for date fields (99/99/99).
Parentheses raise expression precedence. Also, some functions require you to enclose arguments in parentheses.
See also / Division operator.
[ ] Array reference
Square brackets ([ ]) enclose array subscripts ([1], [2], etc.) or ranges (such as, [1 FOR 4]). In a range, you can use a variable for the first element, but the second element must be a constant. The specification [1 FOR 4] causes Progress to start with the first array element and to work with that and the next three elements. Square brackets are also used when specifying initial values for an array. For example, if you define an array variable of extent 3, you might specify initial values as INITIAL [0, 1, 2].
= Special character

Syntax
characters
R | L | C | T
Specifies the justification of the string within its maximum length: right, left, centered, or trimmed, respectively. The default justification depends on how the string is used. If the string is displayed with side labels, the default is right justification. If column labels are used, the defaults are left justification for character fields and right justification for numeric fields. Strings used in expressions are trimmed by default.
• R means right justified and padded on the left with spaces. “Hello”:R10 = “ Hello”.
• L means left justified and padded on the right with spaces. “Hello”:L10 = “Hello “.
• C means centered within the string and padded on both the right and left as needed. “Hello”:C10 = “ Hello “.
• T means trimmed of leading and trailing blanks (although storage space and screen space is still allocated for the maximum number of characters). “ Hello:T10 = “Hello” (but screen and storage space is still reserved for 10 characters).
U
Specifies that the string is untranslatable. This means that the string will not be processed by the OpenEdge Translation Manager. If you do not specify U, then the string is assumed to be translatable.
max-length
The number of characters reserved for the string contents in the text segment. The default is the length of the string itself. You might want to specify a longer length if you expect a translation of the string to be longer. The longest length you can specify is 5120 characters.
Note If you include the colon (:) after the quoted string, you must supply at least one option. Otherwise, Progress treats the colon as a statement separator.
“characters“ [ : [ R | L | C | T ] [ U ] [ max-length ] ]

{ } Argument reference
References the value of an argument that a procedure passes to a called external procedure file or to an include file.
Progress converts each argument to a character format. This conversion removes the surrounding double-quotes if the parameter was specified as a character string constant in the RUN statement or include file reference.
When one procedure is called from another and arguments are used, Progress recompiles the called procedure, substituting the arguments that the calling procedure passes, and then runs the called procedure.
Syntax
Enter the braces ({}) as shown; they do not represent syntax notation in this description.
n
The number of the argument being referred to. If n = 0, Progress substitutes the name of the current procedure (the name you used when you called it, not the full pathname) as the argument. If n = *, Progress substitutes all arguments that the calling procedure passes (but not the name {0}). If you refer to the nth parameter and the calling procedure does not supply it, {n} is ignored.
&argument-name
The name of the argument being referred to. If you refer to an argument-name and the calling procedure does not supply it, Progress ignores {&argument-name}.
If argument-name is an asterisk (*), Progress substitutes all arguments that the calling procedure passes. It also adds quotation marks to each parameter, so you can pass the named argument list through multiple levels of include files.
Note: It is invalid to pass both numbered and named arguments within a single pair of braces. Although this will not cause a compile-time or run-time error, the arguments will not be passed correctly.
{ { n | &argument-name } }
10
Examples The procedure r-arg.p runs procedure r-arg2.p, passing the arguments customer and name to r-arg2.p. Progress substitutes these arguments for {1} and {2} in the r-arg2.p procedure:
The r-inc.p procedure defines the variables txt and num, and assigns the values Progress VERSION and 7 to them. The r-inc.p procedure includes the r-inc.ifile and passes the &int and &str arguments to the include file. Because the parameters are named, their order is unimportant. The called procedure can find each argument, regardless of placement. The r-inc.i include file displays a message that consists of the passed arguments. The asterisk argument displays all the parameters as they are listed in the r-inc.p procedure:
r-arg.p
END.
r-inc.p
DEFINE VARIABLE txt AS CHARACTER. DEFINE VARIABLE num AS INTEGER.
txt = "Progress VERSION". num = 7.
{r-inc.i &int=num &str=txt}
r-inc.i
MESSAGE {&str} /* the &str named argument */ {&int}. /* the &int named argument */

11
Notes • If you pass {} arguments using the RUN statement, you cannot precompile the called procedure. When Progress compiles a procedure, it must have all the values the procedure needs. So, if you pass arguments to a procedure you are calling with the RUN statement, Progress evaluates those arguments when the calling procedure is run, not when it is compiled.
• You can use the name of an include file as an argument to another include file. For example, a reference to {{1}} in an included procedure causes Progress to include the statements from the file with the name that passed as the first argument.
• Use DEFINE PARAMETER to define a run-time parameter in a called subprocedure. Each parameter requires its own DEFINE statement. The parameters must be specified in the RUN statement in the same order as defined with DEFINE statements.
• Progress disregards an empty pair of braces ({}).
• The maximum length of the arguments you can pass to an include file is determined by the Input Characters (-inp) startup parameter.
• An argument argument-name behaves like a scoped preprocessor name. Thus, if you define a preprocessor name, argument-name, its value replaces the value of any argument argument-name passed to the same file at the point where the preprocessor name, argument-name, is defined.

{ } Include file reference
Causes Progress to retrieve the statements in a file and compile them as part of the main procedure if it encounters the file’s name inside braces ({}) when compiling the procedure. You can name arguments you want substituted in the file before compilation.
Syntax
include-file
The name of an external operating system file that contains statements you want included during the compilation of a procedure. This filename follows normal operating system naming conventions and is case sensitive on UNIX. If the file you name has an unqualified path name, Progress searches directories based on the PROPATH environment variable.
argument
A value used by include-file. When Progress compiles the main procedure (the procedure containing the braces), it copies the contents of include-file into that procedure, substituting any arguments. The first argument replaces {1} in the included file, the second argument replaces {2}, etc. So, you can use included procedures with arguments even when you precompile a procedure.
&argument-name = "argument-value"
The argument-name is the name of the argument you want to pass to the include file. You can use variable names, field names, and reserved words as argument names.
The argument-value is the value of the argument you pass to the include file. Enclose the argument-value in quotation marks.
Examples The main procedure uses externally defined and maintained files for the layout and display of a customer report. You can use these same include files in many procedures.
{ include-file

13
The following example references an include file that can take up to five arguments, and the main routine passes four arguments:
When the main procedure is compiled, the line referencing the show include file is replaced by the following line:
This example shows how you can use include files to extend the Progress language. The main procedure uses a new statement, r-show.i, to display the values of fields or variables at various points in a procedure. The include file in this example can handle up to five passed arguments. The main procedure only passes four (point-A, var1, var2, and var3). The output for this example is as follows:
r-fcust.i
r-dcust.i
r-incl2.p
DEFINE VARIABLE var1 as INTEGER INITIAL 9. DEFINE VARIABLE var2 as DECIMAL INITIAL 6.43. DEFINE VARIABLE var3 as LOGICAL INITIAL TRUE. /* any statements */ {r-show.i point-A var1 var2 var3} /* any statements */
r-show.i
MESSAGE "At" "{1}" "{2}" {2} "{3}" {3} "{4}" {4} "{5}" {5}.
MESSAGE At point-A var1 9 var2 6.43 var3 yes

14
The r-custin.p procedure displays a frame for each customer that you can update with customer information. The procedure includes r-cstord.i and passes the named argument &frame-options, and the value of the argument (CENTERED ROW 3 NO-LABEL) to the include file. When the include file references the &frame-options argument, it uses the value of the argument, and therefore displays the OVERLAY frame cust-ord as a centered frame at row 3 without a label, as shown:
Include files are particularly useful for using form layouts in multiple procedures, especially if you do not include the keyword FORM or the closing period (.) of the FORM statement.
r-custin.p
r-cstord.i
FORM "Cust #" AT 1 customer.cust-num AT 10 SKIP(1) customer.name AT 10 customer.address AT 10 customer.address2 AT 10 customer.city AT 10 customer.city customer.state customer.postal-code SKIP(1) "Phone " AT 1 customer.phone FORMAT "999/999-9999" AT 10 "Max Crd" AT 1 customer.credit-limit AT 10 WITH FRAME cust-ord OVERLAY {&frame-options}.
r-cust.f
15
The r-incl3.p procedure includes the r-cust.f file as the definition of a FORM statement, as shown:
The r-incl4.p procedure uses the include file as a layout for a DISPLAY statement, as shown:
Notes • When you use braces to include one procedure in another, Progress does not include the second procedure until it compiles the first one. This technique has the same effect as using the Editor to copy statements into the main procedure. At times, separate include files are easier to maintain.
• You can nest include files. (They can contain references to other include files.) The number of nested include files is limited by the number of file descriptors available on the system.
• If you have many nested include files and you are running on a Sequent machine, use Maximum Files (-Mv) startup parameter to control the number of files you can open simultaneously.
• When you have a base procedure and want to make several copies of it, changing it slightly each time, use include files with parameters. For example, at times you might only want to change the name of some files or fields used by the procedure.
• If you define a preprocessor name and later pass a compile-time argument with the same name, but a different value, to a procedure or include file, the value of the initial preprocessor name remains unchanged. Thus, a compile-time argument is scoped to the file to which it is passed.
• Instead of maintaining duplicate source files, create a single include file with the variable portions (such as the names of files and fields) replaced by {1}, {2}, etc. Then each procedure you write can use that include file, passing file and field names as arguments.
r-incl3.p

16
• You can use the name of an include file as an argument to another include file. For example, a reference to {{1}} in an include file causes Progress to include the statements from the file with the name that passed as the first argument.
• Progress disregards an empty pair of braces ({}).
• If you use double quotes (“ ”) around arguments in an argument list, Progress removes them. However, if you use single quotes (’ ’), Progress passes them. To pass one set of double quotes, you must use four sets of double quotes.
• When Progress reads an include file into the source, it appends a space character to the end of an include file. For example, the following include file r-string.i contains data that is used by r-incstr.p:
Although r-string.i contains five letters, when you run r-incstr.p, it returns the value 6 because Progress appends a space character to the end of r-string.i.
• The maximum length of the arguments you can pass to an include file is determined by the Input Characters (-inp) startup parameter.
See also { } Argument reference, { } Preprocessor name reference, COMPILE statement, DEFINE PARAMETER statement, RUN statement
r-string.i
abcde
r-incstr.p
{ } Preprocessor name reference
References the value of a preprocessor name in any 4GL or preprocessor expression.
Syntax
&preprocessor-name
Expands the name, preprocessor-name, to its defined value. You can define preprocessor names using either the &GLOBAL-DEFINE preprocessor directive or the &SCOPED-DEFINE preprocessor directive. Progress also provides a set of built-in preprocessor names that you can reference for a variety of session information. Table 3 lists each built-in preprocessor name with its description.
{ &preprocessor-name }
Table 3: Built-in preprocessor names (1 of 2)
The preprocessor name ... Expands to an unquoted string ...
BATCH-MODE Equal to "yes" if the Batch (-b) startup parameter was used to start the client session. Otherwise, it expands to "no".
FILE-NAME That contains the name 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}.
LINE-NUMBER 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.
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
18
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.
WINDOW-SYSTEM That contains the name of the windowing system in which the file is being compiled. The possible values include
"MS-WINDOWS", “MS-WIN95", and ”TTY".3
1 When running the source code of a procedure file loaded into the Procedure Editor or the AppBuilder, {&FILE-NAME} 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 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 the 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 function returns the value associated with the Opsys key on all platforms.
3 Progress supports an override option for the &WINDOW-SYSTEM preprocessor name that provides backward compatibility. This option enables applications that need the WINDOW-SYSTEM preprocessor name to return the value of MS-WINDOWS for all Microsoft operating systems to do so. To establish this override value, define the WindowSystem key in the Startup section of the current environment, which can be in the registry or in an initialization file. If the WindowSystem key is located, the WINDOW-SYSTEM preprocessor name returns the value associated with the WindowSystem key on all platforms.
Table 3: Built-in preprocessor names (2 of 2)

19
Table 4 lists the additional built-in preprocessor names that apply to SpeedScript.
Examples The following procedure r-prprc1.p shows how you can reference a built-in preprocessor name and include it in a character string:
Table 4: SpeedScript built-in preprocessor names
DISPLAY DISPLAY {&WEBSTREAM}

20
The procedure r-prprc2.p shows how to capture the value of a {&SEQUENCE} reference. In this example, {&SEQUENCE} is referenced three times, once each to assign its value to wvar (0) and xvar (1) at run time. The third reference defines the preprocessor name Last-Value with the value 3. As shown, Last-Value is assigned unchanged to both yvar and zvar, each of which take the value 3 at run time:
The procedure r-prprc3.p shows how preprocessor names override compile-time arguments. In this example, r-prprc3.p defines the preprocessor name My-Name as "Daniel". It then passes the compile-time argument My-Name, with the value "David", to the include file r-prprc3.i, which in turn defines a preprocessor name My-Name as "Donald".
r-prprc2.p
DEFINE VARIABLE wvar AS INTEGER. DEFINE VARIABLE xvar AS INTEGER. DEFINE VARIABLE yvar AS INTEGER. DEFINE VARIABLE zvar AS INTEGER.
wvar = {&SEQUENCE}. xvar = {&SEQUENCE}.
yvar = {&Last-Value}. zvar = {&Last-Value}.
MESSAGE "wvar =" wvar SKIP "xvar =" xvar SKIP "yvar =" yvar SKIP "zvar =" zvar VIEW-AS ALERT-BOX.
r-prprc3.p
r-prprc3.i
VIEW-AS ALERT-BOX
21
During execution, the first message included by r-prprc3.i displays the value of the My-Name argument, "David". The second message included by r-prprc3.i displays the value of the following My-Name preprocessor name, defined as "Donald", permanently overriding "David" passed by the My-Name argument. Finally, the message in r-prprc3.p displays the value of the My-Name preprocessor name that was initially defined there, "Daniel", because the value from My-Name established in r-prprc3.i ("Donald") went out of scope during compilation.
Note also that the reference to the My-Name compile-time argument in r-prprc3.i is inside double-quotes, because Progress passes string constant values for compile-time arguments without the surrounding double-quotes.
You can encounter compilation problems mixing preprocessor names with compile-time argument names. The following example, a variation of r-prprc3.i, does not compile, even when passed a My-Name argument as an include file. This is because the preprocessor My-Name value overrides the argument My-Name value, as shown:
Because the preprocessor My-Name defines a quoted "Donald" value, Progress replaces "{&My-Name}" in the fourth line with ""Donald"". This appears to the compiler as two empty strings and an unknown variable reference (Donald). Although you can do it with care, in general, avoid using the same names for compile-time arguments and preprocessor names.
Notes • Progress expands preprocessor names wherever and in whatever context it finds them, including inside quoted character strings.
• If you define a preprocessor name in the same file and with the same name as a compile-time argument passed to the file, the value of the preprocessor name takes precedence over the value of the argument name from the point where the preprocessor name is defined.
See also &GLOBAL-DEFINE preprocessor directive, &SCOPED-DEFINE preprocessor directive, { } Argument reference, { } Include file reference, ; Special character

Syntax
preprocessor-name
The preprocessor name (compile-time constant) that you supply. Progress reserved keywords are allowed, but cannot be used in preprocessor expressions.
definition
A string of characters (or preprocessor references that evaluate to a string of characters) whose content the preprocessor substitutes for preprocessor-name during compilation. If the definition is longer than one line, a tilde (~) at the end of the first line indicates continuation to the next line.
Examples In this example, the preprocessor name MAX-EXPENSE is defined as the text string "5000":
Wherever the reference {&MAX-EXPENSE} appears in the source code, the preprocessor substitutes the text string “5000". For example, the preprocessor changes this line of code:
to this line:
&GLOBAL-DEFINE preprocessor-name definition
&GLOBAL-DEFINE MAX-EXPENSE 5000

23
Notes • You must place the &GLOBAL-DEFINE directive at the beginning of a line, preceded only by blanks, tab characters, or comments (/* comment */). The preprocessor trims all leading and trailing spaces from definition.
• The syntax of the &GLOBAL-DEFINE and &SCOPED-DEFINE directives are identical but these directives are used differently.
See also { } Preprocessor name reference, &SCOPED-DEFINE preprocessor directive, &UNDEFINE preprocessor directive, DEFINED preprocessor function

24
&IF, &THEN, &ELSEIF, &ELSE, and &ENDIF preprocessor directives
These directives set logical conditions for the inclusion of blocks of code to compile.
Syntax
expression
An expression that can contain preprocessor name references, the operators listed in Table 6, the Progress functions listed in Table 7, and the DEFINED( ) preprocessor function.
When it encounters 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 block of code are included in the final source. You can nest &IF directives.
The expression that follows the &ELSEIF directive is evaluated only if the &IF expression tests false. If the &ELSEIF expression tests TRUE, 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.
&IF expression &THEN block
25
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 5 shows how preprocessor expressions are evaluated.
Table 5: Preprocessor expressions
LOGICAL TRUE FALSE
CHARACTER non-empty empty
INTEGER non-zero 0

26
Table 6 lists the operators supported within preprocessor expressions. These operators have the same precedence as the regular Progress 4GL operators.
Table 6: Preprocessor operators
AND Logical and
OR Logical or
NOT Logical not
MATCHES Compares two strings
27
Table 7 lists the Progress 4GL functions supported within preprocessor expressions.
Note When the preprocessor evaluates expressions, all arithmetic operations are performed with 32-bit integers. Preprocessor name references used in arithmetic operations must evaluate to integers.
See also &GLOBAL-DEFINE preprocessor directive, &SCOPED-DEFINE preprocessor directive, &UNDEFINE preprocessor directive
Table 7: Functions allowed in preprocessor expressions
ABSOLUTE ASC AUDIT-ENABLED
DATE DAY DBTYPE
DECIMAL ENCODE ENTRY
ETIME EXP FILL
INDEX INTEGER KEYWORD
KEYWORDALL LC LEFT-TRIM
LENGTH LIBRARY LOG
LOOKUP MATCHES MAXIMUM
MEMBER MINIMUM MODULO
MONTH NUM-ENTRIES OPSYS
PROPATH PROVERSION RANDOM
REPLACE RIGHT-TRIM R-INDEX
ROUND SQRT STRING
SUBSTITUTE SUBSTRING TIME
TODAY TRIM TRUNCATE
&MESSAGE preprocessor directive
Displays a message at compile time in the Compiler Messages dialog box.
Note: Does not apply to SpeedScript programming.
Syntax
text-string
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 text-string argument does not need to be quoted.
Examples This is a possible compile-time message directive:
If this fragment appears in a procedure file, cmessage.p, compiling this file with the COMPILE statement causes the following message to be included with the compiler messages:
See also { } Preprocessor name reference
&MESSAGE text-string
Compiling the cmessage.p file.
Syntax
preprocessor-name
The preprocessor name (compile-time constant) that you supply. Progress reserved keywords are allowed, but cannot be used in preprocessor expressions.
definition
A string of characters (or preprocessor references that evaluate to a string of characters) whose content the preprocessor substitutes for preprocessor-name during compilation. If definition is longer than on line, a tilde (~) at the end of the first line indicates continuation to the next line.
Notes • You must place the &SCOPED-DEFINE directive at the beginning of a line, preceded only by blanks, tab characters, or comments (/* comment */). The preprocessor trims all leading and trailing spaces from definition.
• The syntax of the &GLOBAL-DEFINE and &SCOPED-DEFINE directives are identical but these directives are used differently.
See also { } Preprocessor name reference, &GLOBAL-DEFINE preprocessor directive, &UNDEFINE preprocessor directive, DEFINED preprocessor function
&SCOPED-DEFINE preprocessor-name definition
Syntax
preprocessor-name
The preprocessor name (compile-time constant) that you want to undefine.
Notes • 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 currently active name. It also undefines named include file arguments.
• To globally define the same name more than once, use this directive to undefine the name before redefining it. If you do not undefine the global name before redefining it, the compiler produces a warning message. This does not apply to non-globally (scoped) defined names.
See also &GLOBAL-DEFINE preprocessor directive, &SCOPED-DEFINE preprocessor directive, DEFINED preprocessor function
&UNDEFINE preprocessor-name
/* Comments */
31
/* Comments */
Allows you to add explanatory text to a procedure between the /* and */ characters.
Syntax
comment
Note: Comments can be nested.
Examples This example uses comments to document the history of procedure modifications:
/* comment */
r-comm.p

/* Comments */
32
The following example uses comments to describe what the procedure does:
The comment symbols that enclose the inner FOR EACH block turn that block into a comment for testing purposes. Since you can nest comments, Progress correctly processes any comments already in the bypassed code.
r-comm2.p

+ Unary positive operator
Preserves the positive or negative value of a numeric expression. Do not confuse this operator with the addition operator that you use to add expressions together.
Syntax
expression
An expression whose value is numeric.
Example In this example, the sign of credit-limit is preserved as is the sign of the sum of credit-limit + 100. The unary positive is not necessary; it is used simply to document the procedure.
+ expression
r-unpos.p

Example In the following example, the addition operator (+) adds 100 to the value of the credit-limit field:
Note Adding two decimal expressions produces a decimal value. Adding two integer expressions produces an integer value. Adding an integer expression and a decimal expression produces a decimal value.
expression + expression

+ Concatenation operator
Produces a character value by joining two character strings or expressions.
Syntax
expression
An expression whose value is a character string. If any expression is a LONGCHAR, the result is a LONGCHAR. Also, the result converts to the code page of the expression on the left.
Example This procedure prints mailing labels. It uses the concatenation operator (+) to ensure that the third line of each label shows the city and state separated by a comma and a space. The FORMAT x(16) is specified to provide room for up to 16 characters in the result of the concatenation. If a FORMAT is not given, then Progress only displays the first eight characters of the result since x(8) is the default format for a character expression.
This is a label produced by this procedure:
expression + expression
r-conc.p
FOR EACH customer: DISPLAY SKIP(1) name SKIP address SKIP city + ", " + state FORMAT "x(16)" country postal-code SKIP(2). END.
Lift Line Skiing
276 North Street
36
Note If any of the string values you concatenate is the Unknown value (?), then the result is the Unknown value (?). This might lead to unexpected results if a field used in an expression is not mandatory. For example, you might have fields for a person’s first name, last name, and middle initial. You might combine these into a full name with an expression like the following:
If minit is not a mandatory field, it might be set to the Unknown value ( ?) in some records. If so, then those records are displayed as the Unknown value (?). You can avoid this by using conditional code. For example:
DISPLAY fname + " " + minit + " " + lname FORMAT "x(36)".

+ Date addition operator
Adds a number of days to a date, producing a date result.
Syntax
date
days
An expression with a value of the number of days you want to add to a date.
Example This procedure finds all unshipped orders that are at least one week overdue. If the order is not shipped and the promised date is more than seven days ago, the procedure finds the record for the customer who placed the order and displays the order and customer data.
date + days
r-dadd.p

38
Notes • The date addition operator rounds days to the nearest integer value.
• To add a specific number of days or a specific number of milliseconds to a DATETIME, use the DATETIME function. For example:
The DATETIME function ensures that the time portion remains within the valid range, by adding day(s) to the date part when the time part goes over the number of milliseconds in a day.
• To add a specific number of days or milliseconds to a DATETIME-TZ, use the DATETIME-TZ function. For example:
The DATETIME-TZ function ensures that the time portion remains within the valid range, by adding day(s) to the date portion when the time part goes over the number of milliseconds in a day.
new-datetime = DATETIME( DATE(old-datetime) + days, MTIME(old-datetime) + milliseconds ).
new-datetime-tz = DATETIME-TZ( DATE(old-datetime-tz) + days, MTIME (old-datetime-tz) + milliseconds, TIMEZONE(old-dateime-tz)).

– Unary negative operator
Reverses the sign of a numeric expression. Do not confuse this operator with the subtraction operator that subtracts one expression from another.
Syntax
expression
Example If you supply a negative value for the variable x, the following example procedure uses the unary negative operator (-) to reverse the sign of x, producing the absolute value of x (abs-x):
- expression
r-uneg.p
DEFINE VARIABLE x AS DECIMAL LABEL "X". DEFINE VARIABLE abs-x AS DECIMAL LABEL "ABS(X)".

Syntax
expression
Example This procedure determines the amount of inventory available by subtracting the amount allocated from the total on hand:
Note Subtracting one decimal expression from another produces a decimal value. Subtracting one integer expression from another produces an integer. Subtracting an integer expression from a decimal expression (or subtracting a decimal expression from an integer expression) produces a decimal value.
expression - expression

– Date subtraction operator
Subtracts a number of days from a date to produce a date result, or subtracts one date from another to produce an integer result that represents the number of days between the two dates.
Syntax
date
days
An expression with a value of the number of days you want to subtract from a date.
Example This procedure finds all unshipped orders. If the promised date is more than one week ago, the procedure finds the customers who placed the order and displays the order and customer data.
date - { days | date }
r-dsub.p

42
Notes • The date subtraction operator rounds days to the nearest integer value.
• To get the number of days between two DATETIME or DATETIME-TZ variable values, use the DATE function. For example:
This operation does not take the time portion into account.
To ensure the correct result when working with two DATETIME-TZ values, convert one of the values to the time zone of the other. For example:
• To subtract a specific number of days or milliseconds from a DATETIME, use the DATETIME function. For example:
The DATETIME function ensures the time portion remains within a valid range by borrowing a day from the date portion, when necessary.
• To subtract a specific number of days or milliseconds from a DATETIME-TZ, use the DATETIME-TZ function. For example:
The DATETIME-TZ function ensures the time portion remains within a valid range by borrowing a day from the date portion, when necessary.
num-days = DATE(dt2) - DATE(dt1)

An expression with a numeric value.
Example This procedure computes the value of the on-hand inventory for each item. If the on-hand inventory is negative, the procedure sets the inventory value to 0.
Note Multiplying two decimal expressions produces a decimal value. Multiplying two integer expressions produces an integer value. Multiplying an integer expression and a decimal expression produces a decimal value.
expression * expression
DEFINE VARIABLE inv-value AS DECIMAL LABEL "VALUE".

Divides one numeric expression by another numeric expression, producing a decimal result.
Syntax
expression
An expression that evaluates to a numeric value.
Example This procedure divides the number of items allocated by the number of items on hand, producing a decimal value. The multiplication operator (*) converts that decimal value to a percentage.
Notes • Progress always performs division as a decimal operation (the product of 5 / 2 is 2.5, not 2). If you assign the result to an integer field, Progress rounds the decimal to make the assignment. When you want Progress to truncate a quotient to an integer, use the TRUNCATE function (TRUNCATE(5 / 2, 0) is 2).
• The result of dividing a number by 0 is the Unknown value (?), and Progress does not display an error message.
expression / expression
DISPLAY "INVENTORY COMMITMENTS AS A PERCENT OF UNITS ON HAND".

= Assignment operator
Assigns the value of an expression to a database field or variable.
Data
movement
Syntax
field
The name of a database field or variable to which you want to assign the value of the expression. If the field is an array, and you do not name a particular element, Progress stores expression in each element of the array. If you name a particular element, Progress stores expression in that element.
The left side of an assignment can also be an attribute or Progress keyword (such as ENTRY, FRAME-VALUE, SUBSTRING, or OVERLAY).
expression
An expression with a data type that is consistent with the data type of the field . If field is integer and expression is decimal, then Progress rounds the value of the expression before assigning it. If field is decimal and expression is decimal, then Progress rounds the value of the expression to the number of decimal places defined for the field in the Dictionary or defined or implied for a variable.
Field or
Variable Expression
46
NO-ERROR
Suppresses any errors that occur as a result of the operation. After the assignment completes, you can check the ERROR-STATUS system handle for information about any errors that might have occurred.
If you do not specify this option and an error occurs, the assignment is canceled and any changes to field values within the assignment are undone. If the assignment occurs within a transaction, any changes to variables, work table fields, and temporary table fields are also undone, unless you define the variable or field with the NO-UNDO option.
Example This procedure resets all the monthly quota values to 0 in all salesrep records. If you want to set values for individual array elements, you can do so by making an explicit assignment using the assignment statement and a specific array reference, such as month-quota[1] or month-quota[i].
Notes • If you assign a value to a database field, any ASSIGN trigger associated with that field executes at the end of the assignment statement (after any index changes are made). If the trigger returns ERROR, the assignment fails and the database changes are undone.
• You can embed an assignment in a SET or UPDATE statement.
• For multiple assignments, use the ASSIGN statement. This is more efficient than multiple assignment statements.
r-asgmnt.p
DEFINE VARIABLE ctr AS INTEGER.

47
• You can assign DATE, DATETIME, and DATETIME-TZ data. When the data type expression on the left side of the assignment statement contains more information than the data type expression on the right side provides (for example, datetime-tz = date where a DATETIME-TZ value contains more information than a DATE value), the time value defaults to midnight and the time zone value defaults to the session's time zone. When the data type expression on the left side of the assignment statement contains less information than the data type expression on the right side provides (for example, date = datetime-tz where a DATE value contains less information than a DATETIME-TZ value), Progress converts the DATETIME-TZ value to the local date and time of the session, then drops the time and time zone.
• You can assign large object data from one BLOB or MEMPTR to another, and from one CLOB, LONGCHAR, or CHARACTER to another. You cannot assign large object data between BLOBs and CLOBs or MEMPTRs and LONGCHARs. You can accomplish this, indirectly, by using the COPY-LOB statement. For more information, see the COPY-LOB statement reference entry.
Note: When assigning BLOB or CLOB fields, the field must appear by itself on either the right-hand or the left-hand side of the assignment.
Table 8 lists the default character conversions Progress performs when assigning CLOB, LONGCHAR, and CHARACTER data between a source and target object. References to CLOBCP and CLOBDB represent CLOB data in either the CLOB’s defined code page or the database's defined code page, respectively. References to the "fixed code page" represent the code page of a target LONGCHAR variable set using the FIX-CODEPAGE function.
Table 8: Default Assignment operator character conversions (1 of 2)
When the target object
And the source object
Progress converts the data in the source object to ...
LONGCHAR CLOBDB -cpinternal or the fixed code page.
LONGCHAR CLOBCP The CLOB’s defined code page or the fixed code page.
LONGCHAR CHARACTER -cpinternal or the fixed code page.
CLOBDB CHARACTER The database's defined code page.

48
• When you assign the Unknown value (?) to a BLOB or CLOB field, Progress deletes any associated object data.
See also ASSIGN statement, Data types, COPY-LOB statement, FIX-CODEPAGE function
CLOBDB LONGCHAR The database's defined code page.
CLOBCP CHARACTER The CLOB’s defined code page.
CLOBCP LONGCHAR The CLOB’s defined code page.
CHARACTER CLOBDB -cpinternal code page.
CHARACTER CLOBCP -cpinternal code page.
CHARACTER LONGCHAR -cpinternal code page.
Table 8: Default Assignment operator character conversions (2 of 2)
When the target object
And the source object
Progress converts the data in the source object to ...

Syntax
n
An integer or decimal expression. The return value is the same format as n.
Example This procedure calculates the number of miles you drive between highway exit ramps:
ABSOLUTE ( n )
DEFINE VARIABLE mark-start AS DECIMAL NO-UNDO. DEFINE VARIABLE mark-finish AS DECIMAL NO-UNDO. DEFINE VARIABLE units AS LOGICAL FORMAT "miles/kilometers" NO-UNDO.
FORM mark-start LABEL "Mile marker for highway on-ramp" SKIP mark-finish LABEL "Mile marker next to your exit" SKIP(1) units LABEL "Measure in <m>iles or <k>ilometers" SKIP(1) WITH FRAME question SIDE-LABELS TITLE "This program calculates distance driven.".
UPDATE mark-start mark-finish units WITH FRAME question.
DISPLAY "You have driven" ABSOLUTE(mark-start - mark-finish) units WITH NO-LABELS FRAME answer.

ACCUM function
Returns the value of an aggregate expression that is calculated by an ACCUMULATE or aggregate phrase of a DISPLAY statement.
Syntax
aggregate-phrase
A phrase that identifies the aggregate value it should return. This is the syntax for aggregate-phrase:
For more information on aggregate items, see the Aggregate phrase reference entry.
expression
An expression that was

manual openedge 4 gl

Documents