DP 4 GL

OpenEdge Deployment:
TM
Managing 4GL Applications

© 2004 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.
Allegrix, A [Stylized], ObjectStore, Progress, Powered by Progress, Progress Fast Track, Progress Profiles, Partners in Progress, Partners en Progress, Progress en
Partners, Progress in Progress, P.I.P., Progress Results, ProVision, ProCare, ProtoSpeed, SmartBeans, SpeedScript, and WebSpeed 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, Allegrix
& Design, AppsAlive, AppServer, ASPen, ASP-in-a-Box, BusinessEdge, Business Empowerment, Empowerment Center, eXcelon, Fathom, Future Proof,
IntelliStream, ObjectCache, OpenEdge, PeerDirect, POSSE, POSSENET, ProDataSet, Progress Business Empowerment, Progress Dynamics, Progress
Empowerment Center, Progress Empowerment Program, Progress for Partners, Progress OpenEdge, Progress Software Developers Network, PSE Pro, PS Select,
Real Time Event Engine, SectorAlliance, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder,
SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, Technical Empowerment, Trading Accelerator, 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.
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 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 apache@apache.org. 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 are copyrighted by DataDirect Technologies, 1991-2002.
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.
August 2004
Product Code: 4655

Item Number: 101207; R10.0B
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preface–1
Part I 4GL and R-code Deployment and Management
1. Progress 4GL Client Deployment Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–1

Client deployment process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–2
Client deployment and administration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–3
2. Managing Client Access to Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–1

Connecting clients to databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–2
Logical database names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–3
Connection modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–4
Connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–5
Connection techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–5
Connecting to a non-OpenEdge database . . . . . . . . . . . . . . . . . . . . . . . 2–14
Connection denials when the user count is exceeded . . . . . . . . . . . . . . 2–15
Reducing connection times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–16
Starting clients without connecting to a database . . . . . . . . . . . . . . . . . . 2–17
Selecting a working database for client use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–17
Selecting a database with the Data Dictionary . . . . . . . . . . . . . . . . . . . . 2–17
Selecting a database with the Data Administration tool . . . . . . . . . . . . . 2–18
Disconnecting databases for clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–18
Disconnecting a database with the Data Dictionary . . . . . . . . . . . . . . . . 2–19
Disconnecting a database with the Data Administration tool. . . . . . . . . . 2–19
Contents
3. Maintaining Application Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–1

Compile-time security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–2
Using table- and field-level security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–2
Setting table and field permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–3
Determining the privileges of the blank user ID . . . . . . . . . . . . . . . . . . . . 3–7
Run-time security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–8
Operating system security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–8
Designating a security administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–9
4. Maintaining User Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–1

Maintaining the Windows user environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–2
Using the INI2REG utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–2
Searching progress.ini and the Registry at startup . . . . . . . . . . . . . . . . . 4–6
Maintaining the progress.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–9
Windows icons for running OpenEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–37
Starting the OpenEdge client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–38
Modifying OpenEdge client icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–38
Maintaining the UNIX user environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–39
Maintaining the buildenv script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–39
Maintaining the PROTERMCAP file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–41
PROTERMCAP syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–43
Terminal name entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–46
Terminal capabilities entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–47
Vermont Views key function capabilities . . . . . . . . . . . . . . . . . . . . . . . . . 4–52
Pointer to key functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–55
Specifying colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–55
Specifying the cursor motion capability . . . . . . . . . . . . . . . . . . . . . . . . . . 4–57
Specifying keyboard mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–59
Extended character support entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–66
Creating a PROTERMCAP entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–67
Testing terminal entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–68
Setting up the terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–68
Setting the terminal type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–69
Setting the PROTERMCAP environment variable . . . . . . . . . . . . . . . . . 4–70
Reverting to the default PROTERMCAP file . . . . . . . . . . . . . . . . . . . . . . 4–70
Copying an existing terminal entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–70
iv
Contents
5. Managing Client Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–1

Procedure loading and execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–2
Using r-code libraries to improve r-code performance . . . . . . . . . . . . . . 5–2
R-code execution environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–3
Monitoring r-code activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–7
Distributing OpenEdge files on a network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–11
Distributing OpenEdge system files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–11
Distributing procedure files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–12
Distributing temporary files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–12
Distributing log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–13
Temporary file I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–13
Sorting I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–15
6. Managing R-code Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–1

Library overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–2
Loading r-code from a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–3
Loading r-code from a standard library . . . . . . . . . . . . . . . . . . . . . . . . . 6–4
Loading r-code from a memory-mapped library . . . . . . . . . . . . . . . . . . . 6–5
Setting up a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–6
Running procedures from a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–6
Using an absolute pathname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–6
Using a relative pathname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–7
Related functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–8
Libraries and PROPATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–9
Memory and network considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–10
Using the PROLIB utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–11
Using wild cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–13
Creating a standard library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–13
Generating a memory-mapped Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–14
Adding files to a standard library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–15
Replacing files in a standard library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–16
Deleting files from a standard library. . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–16
Listing the contents of a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–17
Extracting files from a standard library . . . . . . . . . . . . . . . . . . . . . . . . . . 6–19
Extracting files to your current directory . . . . . . . . . . . . . . . . . . . . . . . . . 6–20
Compressing a standard library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–21
PROLIB command examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–22
Code page compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–23
v
Contents
7. Managing Print Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–1

Printing in OpenEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–2
OUTPUT TO statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–3
OUTPUT THROUGH statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–4
Printing on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–5
UNIX networks and printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–7
Printing in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–9
Setting up output-routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–10
Using a startup procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–10
Using an output-routing table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–12
Using interactive output-routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–13
Configuring a printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–14
Creating a printer-control table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–15
Part II Developer’s Toolkit
8. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–1
Toolkit components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–2
9. Choosing a Code Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–1

Unencrypted source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–2
Development product requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–2
User product requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–2
Advantages of unencrypted source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–2
Possible drawbacks of unencrypted source . . . . . . . . . . . . . . . . . . . . . . . 9–3
Encrypted source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–4
Development product requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–4
Advantages of encrypted source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–5
Possible drawbacks of encrypted source . . . . . . . . . . . . . . . . . . . . . . . . . 9–6
R-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–7
Developer product requirements and r-code portability . . . . . . . . . . . . . . 9–7
Advantages of r-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–8
Possible drawbacks of r-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–9
10. Initial Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–1

Deploying database structures and application procedures . . . . . . . . . . . . . . . . . . 10–2
Unencrypted source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–4
Encrypted source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–7
CRC r-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–11
Time-stamp r-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–16
vi
Contents
11. Upgrades. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–1

Deploying upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–2
Modifying the application procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–4
Unencrypted source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–4
Encrypted source files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–4
Time-stamp-based r-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–4
CRC-based r-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–5
Modifying the application database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–5
Upgrading with updated .df and encrypted source . . . . . . . . . . . . . . . . . 11–5
Upgrading with updated .df and CRC-based r-code . . . . . . . . . . . . . . . . 11–9
Upgrading with time-stamp-based r-code files . . . . . . . . . . . . . . . . . . . . 11–10
OpenEdge product upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–12
12. Deployment Topics and Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–1

Encrypting source code procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–2
XCODE utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–2
Preparing to use XCODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–2
Decryption and compilation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–4
Using the BUNDLE utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–4
The bundle.c program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–5
The unbundle.c program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–6
Examples using BUNDLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–7
Dumping and loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–12
MKDUMP utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–12
Using your dump/reload facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–14
Restricting database access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–15
Part III Appendices
A. Building OpenEdge 4GL Executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–1

Licensing requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–2
Building executables on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–2
Preparing the UNIX software environment . . . . . . . . . . . . . . . . . . . . . . . A–2
Building a customized executable on UNIX . . . . . . . . . . . . . . . . . . . . . . A–3
Building executables in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–5
Preparing the Windows software environment . . . . . . . . . . . . . . . . . . . . A–5
Building a customized executable in Windows . . . . . . . . . . . . . . . . . . . . A–6
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–7
vii
Contents
B. R-code Features and Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–1

R-code structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–2
Factors that affect r-code size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–3
R-code file segment layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–4
R-code libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–6
R-code libraries and PROPATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–6
R-code execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–7
Standard r-code execution environment . . . . . . . . . . . . . . . . . . . . . . . . . B–8
Memory-mapped r-code execution environment . . . . . . . . . . . . . . . . . . . B–12
R-code directory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–15
R-code execution environment statistics . . . . . . . . . . . . . . . . . . . . . . . . . B–15
R-code portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–20
Code page compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–20
Database CRCs and time stamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–21
Time stamp validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–21
CRC validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–22
CRC calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–23
CRC versus time stamp validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–23
R-code CRCs and procedure integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–27
Assigning CRCs to schema triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–28
Validating CRCs for schema triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–28
RCODE–INFO handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–28
C. OpenEdge Application Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C–1

Input/output limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C–2
Sorting limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C–3
Name limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C–4
Compiler limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C–5
D. Toolkit Contents and Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D–1

Toolkit templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D–2
Toolkit utilities summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D–3
DBRSTRCT utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D–4
MKDUMP utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D–6
XCODE utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D–7
_tlr Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D–9
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index–1
viii
Contents
Tables
Table 3–1: Security permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–4
Table 3–2: Access restrictions for tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–5
Table 4–1: DLL files for AS/400 communications . . . . . . . . . . . . . . . . . . . . . . . . . 4–12
Table 4–2: User-definable key bindings in Windows . . . . . . . . . . . . . . . . . . . . . . . 4–30
Table 4–3: Static key bindings in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–32
Table 4–4: User-definable key bindings in Windows . . . . . . . . . . . . . . . . . . . . . . . 4–33
Table 4–5: Environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–36
Table 4–6: Windows-installed icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–37
Table 4–7: Syntax for specifying string values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–44
Table 4–8: Alphabetical listing of capability mnemonics . . . . . . . . . . . . . . . . . . . . 4–48
Table 4–9: Data types and operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–52
Table 4–10: Vermont Views key function mnemonics . . . . . . . . . . . . . . . . . . . . . . . 4–53
Table 4–11: Syntax for specifying cursor motion string value . . . . . . . . . . . . . . . . . 4–57
Table 4–12: OpenEdge PROTERMCAP key functions . . . . . . . . . . . . . . . . . . . . . . 4–59
Table 4–13: Setting the terminal type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–69
Table 4–14: Setting the PROTERMCAP environment variable . . . . . . . . . . . . . . . . 4–70
Table 4–15: Reverting to the default PROTERMCAP file . . . . . . . . . . . . . . . . . . . . 4–70
Table 5–1: Startup parameters for tuning the execution environment . . . . . . . . . . 5–5
Table 5–2: Startup parameters for tuning r-code libraries . . . . . . . . . . . . . . . . . . . 5–6
Table 5–3: Startup parameters for monitoring r-code activity . . . . . . . . . . . . . . . . 5–7
Table 5–4: Temporary client session files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–13
Table 5–5: Startup parameters for tuning sort performance . . . . . . . . . . . . . . . . . 5–15
Table 6–1: PROLIB utility parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–11
Table 6–2: List (-list) parameter library information . . . . . . . . . . . . . . . . . . . . . . . . 6–17
Table 6–3: List (-list) parameter file information . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–18
Table 7–1: Standard printer control sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–14
Table B–1: R-code segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–2
Table B–2: Metaschema fields in CRC calculation . . . . . . . . . . . . . . . . . . . . . . . . B–23
Table C–1: Input/output limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C–2
Table C–2: Sorting limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C–3
Table C–3: Name limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C–4
Table C–4: Compiler limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C–5
Table D–1: Toolkit utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D–3
ix
Contents
Figures
Figure 2–1: Connection denial when the user count is exceeded . . . . . . . . . . . . . . 2–15
Figure 4–1: Windows environment information search path . . . . . . . . . . . . . . . . . . 4–7
Figure 4–2: Sample Progress initialization file in Windows . . . . . . . . . . . . . . . . . . . 4–10
Figure 4–3: Sample buildenv script on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–40
Figure 4–4: Parts of a PROTERMCAP entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–42
Figure 5–1: Sample statistics (-y) output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–8
Figure 5–2: Sample segment statistics (-yd) output . . . . . . . . . . . . . . . . . . . . . . . . . 5–10
Figure 6–1: Loading r-code from a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–3
Figure 6–2: Loading r-code from a standard library . . . . . . . . . . . . . . . . . . . . . . . . . 6–4
Figure 6–3: Loading r-code from a memory-mapped library . . . . . . . . . . . . . . . . . . 6–5
Figure 7–1: Sample application startup procedure (UNIX) . . . . . . . . . . . . . . . . . . . . 7–11
Figure 7–2: Sample application startup procedure (NT) . . . . . . . . . . . . . . . . . . . . . 7–11
Figure 7–3: Sample output-routing table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–12
Figure 7–4: Sample printer-control table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–16
Figure 10–1: Deploying database structures and application procedures . . . . . . . . . 10–3
Figure 11–1: Deploying upgraded database structure and application procedures . . 11–3
Figure 12–1: Output of mkdump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–13
Figure B–1: R-code file segment layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–5
Figure B–2: Standard r-code execution environment . . . . . . . . . . . . . . . . . . . . . . . . B–9
Figure B–3: Memory-mapped r-code execution environment . . . . . . . . . . . . . . . . . . B–13
Figure B–4: Progress 4GL client startup options for –yd . . . . . . . . . . . . . . . . . . . . . B–16
Figure B–5: Execution buffer map for –yd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–16
Figure B–6: Accessing the session sort file for –yd . . . . . . . . . . . . . . . . . . . . . . . . . B–17
Figure B–7: Procedure segment information for –yd (Part 1) . . . . . . . . . . . . . . . . . . B–18
Figure B–8: Procedure segment information for –yd (Part 2) . . . . . . . . . . . . . . . . . . B–19
Figure D–1: Database Restriction Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D–5
x
Preface
This Preface contains the following sections:
• Purpose
• Audience
• Organization
• Typographical conventions
• Examples of syntax descriptions
• Example procedures
• OpenEdge messages
OpenEdge Deployment: Managing 4GL Applications
Purpose
This book describes the Progress® 4GL client application deployment process and application
administration concepts and procedures. It includes the steps required to deploy Progress 4GL
applications and a description of the tradeoffs between different deployment scenarios. It also
describes components provided with the Developer’s Toolkit that help you through the
deployment process.
Audience
This book is intended for OpenEdge™ application administrators and experienced Progress
programmers preparing applications for wider distribution or resale.
Organization
Part I, 4GL and R-code Deployment and Management
Chapter 1, “Progress 4GL Client Deployment Overview”
Presents an overview of the client deployment process, and outlines the deployment and
administration tasks you must perform.
Chapter 2, “Managing Client Access to Databases”
Describes how to connect and disconnect databases for Progress 4GL clients.
Chapter 3, “Maintaining Application Security”
Describes how OpenEdge implements application security, including designating security

administrators and setting table and field permissions.
Chapter 4, “Maintaining User Environments”
Describes how to maintain OpenEdge user interface environments in Windows and on

UNIX.
Chapter 5, “Managing Client Performance”
Describes how to monitor and tune Progress 4GL client application performance.
Preface–2
Preface
Chapter 6, “Managing R-code Libraries”
Describes Progress 4GL r-code libraries and how to use the PROLIB utility.
Chapter 7, “Managing Print Devices”
Describes how to set up print devices on OpenEdge-supported operating systems.
Part II, Developer’s Toolkit
Chapter 8, “Introduction”
Provides an introduction to the Developer’s Toolkit.
Chapter 9, “Choosing a Code Format”
Describes the different types of code formats you can choose to deploy a Progress 4GL
application.
Chapter 10, “Initial Deployment”
Describes the initial deployment process using the different code formats.
Chapter 11, “Upgrades”
Describes how to upgrade Progress 4GL applications.
Chapter 12, “Deployment Topics and Tasks”
Describes how to perform several tasks related to deploying Progress 4GL applications.
Part III, Appendices
Appendix A, “Building OpenEdge 4GL Executables”
Describes the process and requirements for building customized OpenEdge executables.
It also provides instructions for using the Make utility in Windows and on UNIX.
Appendix B, “R-code Features and Functions”
Describes the structure and management of Progress r-code, the executable code into
which OpenEdge compiles 4GL procedures. It 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–3
Appendix C, “OpenEdge Application Limits”
Describes the OpenEdge limits you must consider when developing an OpenEdge client
application.
Appendix D, “Toolkit Contents and Reference”
Provides reference information about utilities and scripts provided by the Developer’s
Toolkit.
Typographical conventions
This manual uses the following typographical conventions:
Convention Description
Bold Bold typeface indicates commands or characters the user types, or

the names of user interface elements.
Italic Italic typeface indicates the title of a document, provides

emphasis, or signifies new terms.
SMALL, BOLD Small, bold capital letters indicate OpenEdge™ key functions and
CAPITAL LETTERS generic keyboard keys; for example, GET and CTRL.
KEY1-KEY2 A hyphen 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,

and for 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.
Preface–4
Preface
Convention Description
UPPERCASE Uppercase words are Progress® 4GL language keywords.

fixed width Although these always are 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 (.) All statements except DO, FOR, FUNCTION, PROCEDURE, and REPEAT
or end with a period. DO, FOR, FUNCTION, PROCEDURE, and REPEAT
colon (:) statements can end with either a period or a colon.
[] 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.
Preface–5
Examples of syntax descriptions

In this example, ACCUM is a keyword, and aggregate and expression are variables:
Syntax
ACCUM aggregate expression
FOR is one of the statements that can end with either a period or a colon, as in this example:
FOR EACH Customer:

DISPLAY Name.
END.
In this example, STREAM stream, UNLESS-HIDDEN, and NO-ERROR are optional:
Syntax
DISPLAY [ STREAM stream ][ UNLESS-HIDDEN ] [ NO-ERROR ]
In this example, the outer (small) brackets are part of the language, and the inner (large) brackets
denote an optional item:
Syntax
INITIAL [ constant [ , constant ] ]
A called external procedure must use braces when referencing compile-time arguments passed
by a calling procedure, as shown in this example:
Syntax
{ &argument-name }
In this example, EACH, FIRST, and LAST are optional, but you can choose only one of them:
Syntax
PRESELECT [ EACH | FIRST | LAST ] record-phrase
Preface–6
Preface
In this example, you must include two expressions, and optionally you can include more.
Multiple expressions are separated by commas:
Syntax
MAXIMUM ( expression , expression [ , expression ] ... )
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:
Syntax
MESSAGE { expression | SKIP [ ( n ) ] } ...
In this example, you must specify {include-file, then optionally any number of argument or
&argument-name = "argument-value", and then terminate with }:
Syntax
{ include-file
[ argument | &argument-name = "argument-value" ] ... }
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
WITH [ ACCUM max-length ] [ expression DOWN ]

[ CENTERED ] [ n COLUMNS ] [ SIDE-LABELS ]
[ STREAM-IO ]
Preface–7
Complex syntax descriptions with both required and

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:
Syntax
ASSIGN { [ FRAME frame ] { field [ = expression ] }

[ WHEN expression ] } ...
| { record [ EXCEPT field ... ] }
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 a procedure is available online, its name appears above the box and starts with a prefix
associated with the manual that references it:
– i- — OpenEdge Development: Programming Interfaces, for example, i-ddeex1.p
– h- — OpenEdge Development: Progress 4GL Handbook, for example, h-cleanup.p
– r- — OpenEdge Development: Progress 4GL Reference, for example, r-dynbut.p
If the name does not start with a listed prefix, the procedure is not available online.
• If a procedure is not available online, it compiles as shown but might not execute for lack
of completeness.
• Example procedures used in OpenEdge Development: ProDataSets can be found on the

Documentation PDF CD in a self-extracting ZIP file (DVPDS_examples.exe). You can also
find the procedures in a ZIP file (DVPDS_examples.zip) on the Documentation page of the
PROGRESS Web site: http://www.progress.com/products/documentation.
Preface–8
Preface
Accessing files in procedure libraries

Documentation examples are stored in a procedure library, prodoc.pl, in the src directory
where OpenEdge™ is installed.
You must create all subdirectories required by a library before trying 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 OpenEdge Deployment: Managing 4GL
Applications for more details on the PROLIB utility.
Creating a listing of the procedure libraries

Creating a listing of the source files from a procedure library involves running PROENV to set up
your OpenEdge environment, and running PROLIB.
To create a listing of the source files from a procedure library:
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
OpenEdge (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. At the proenv prompt, enter the following command to create the prodoc.txt text file,
which contains the file listing for the prodoc.pl library:
PROLIB %DLC%\src\prodoc.pl -list > prodoc.txt
Preface–9
Extracting source files from procedure libraries (Windows)
Extracting source files from a procedure library involves running PROENV to set up your
OpenEdge environment, creating the directory structure for the files you want to extract, and
running PROLIB.
To extract source files from procedure libraries:
1. From the Control Panel or the Progress Program Group, double-click the Proenv icon.
2. The Proenv window appears, with the proenv prompt.
3. At the proenv prompt, enter the following command to create the prodoc directory in your
OpenEdge working directory (by default, C:\OpenEdge\Wrk):
MKDIR prodoc
4. Create the langref directory under prodoc:
MKDIR prodoc\langref
5. To extract all examples in a procedure library directory, run the PROLIB utility. Note you
must use double quotes because “Program Files” contains an embedded space:
PROLIB "%DLC%\src\prodoc.pl" -extract prodoc/langref/*.*
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 "%DLC%\src\prodoc.pl" -extract prodoc/langref/r-syshlpchm.p
PROLIB extracts r-syshlpchm.p into prodoc\langref.
Preface–10
Preface
Extracting source files from procedure libraries (UNIX)
This section describes how to extract source files from procedure libraries on UNIX platforms.
To extract source files from procedure libraries:
1. Run the PROENV utility:
install-dir/dlc/bin/proenv
Running proenv sets the DLC environment variable to the directory where you installed
OpenEdge (by default, /usr/dlc). The proenv utility also adds the bin directory under the
DLC environment variable to your PATH environment variable (PATH=$DLC/bin:$PATH).
2. At the proenv prompt, create the prodoc directory in your OpenEdge working directory:
mkdir prodoc
3. Create the handbook directory under prodoc:
mkdir prodoc/handbook
4. To extract all examples in a procedure library directory, run the PROLIB utility:
prolib $DLC/src/prodoc.pl -extract prodoc/interfaces/*.*
PROLIB extracts all examples into prodoc/interfaces.
To extract one source file (i-ddeex1.p) from a procedure library (prodoc.pl), run PROLIB
and specify the file you want to extract as it is stored in the procedure library:
prolib $DLC/src/prodoc.pl -extract prodoc/interfaces/i-ddeex1.p
PROLIB extracts i-ddeex1.p into prodoc/interfaces.
Preface–11
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:
** Unknown table name table. (200)
If you encounter an error that terminates OpenEdge, note the message number before restarting.
Preface–12
Preface
Obtaining more information about OpenEdge messages
On 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 enter 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:
install-dir/dlc/bin/pro
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.
Preface–13
Preface–14
Part I
4GL and R-code Deployment and
Management
Chapter 1, Progress 4GL Client Deployment Overview
Chapter 2, Managing Client Access to Databases
Chapter 3, Maintaining Application Security
Chapter 4, Maintaining User Environments
Chapter 5, Managing Client Performance
Chapter 6, Managing R-code Libraries
Chapter 7, Managing Print Devices

1
Progress 4GL Client Deployment
Overview
Deploying a Progress® 4GL client application (hereinafter referred to as “client” or

“application”) is a process that involves developing an application and installing that
application in end-user environments. Once you have deployed your application, you must
manage the end-user environments and system resources for your users.
This chapter presents an overview of the client deployment process, and outlines the
deployment and administration tasks you must perform, in the following sections:
• Client deployment process
• Client deployment and administration tasks

Client deployment process

While deployment requirements vary between applications, you follow a basic deployment
process to deploy any Progress 4GL client application.
The client deployment process consists of three basic phases:
• Planning — The phase in which you identify your deployment requirements and define
your deployment strategy.
• Development — The phase in which you design, develop, and debug your client
application.
• Installation and Configuration — The phase in which you deliver your client application
to end-users, and set up the end-user environment.
Each phase of the client deployment process has its own set of requirements and dependencies
that you must consider when defining your client deployment strategy. Decisions made in an
earlier phase will affect the following phases and the process as a whole.
Progress Software Corporation provides you with the following services to help you identify
your client deployment options and accomplish the client deployment process for your
application:
• The Progress Software Consulting Services organization which can assist you in all phases
of the client deployment process.
• The Progress Technical Services staff which can answer your questions about the ADE
tools, 4GL usage, and database administration.
1–2
Progress 4GL Client Deployment Overview
Client deployment and administration tasks

Following are some of the Progress 4GL client application deployment and administration tasks
you must perform:
• Manage client access to databases.
• Maintain application security.
• Manage client performance.
• Maintain user environments.
• Manage r-code libraries.
• Manage print devices.
The remaining chapters in this guide provide detailed information about each of these tasks, as
well as the procedures and utilities you use to accomplish them. The appendixes provide useful
information about building OpenEdge executables and OpenEdge application limits.
Note: Certain deployment and administration tasks will differ among operating systems.
For information about designing and coding a Progress 4GL client application, see OpenEdge
Development: Progress 4GL Handbook.
For information about creating and maintaining an OpenEdge RDBMS, see OpenEdge Data
Management: Database Administration.
For information about AppServer deployment and administration tasks, see OpenEdge
Application Server: Developing AppServer Applications.
1–3
1–4
2
Managing Client Access to Databases
This chapter describes how to connect and disconnect databases for Progress 4GL clients and
provides information about the following topics:
• Connecting clients to databases
• Selecting a working database for client use
• Disconnecting databases for clients

Connecting clients to databases

To access a database, you must connect to the database. You can connect to one or more
databases during a single Progress 4GL session. You can also start a Progress 4GL session
without connecting to a database, and connect later.
Note: On UNIX, the kernel configuration’s file descriptor limit imposes a practical limit on
connected databases. “Unable to open file” or “Unable to allocate I-Node” messages
often mean your system’s file descriptors have been exhausted. “Unable to allocate
shared memory” often means your shared memory has been exhausted on your system.
For more information about kernel configurations, see OpenEdge Getting Started:
Installation and Configuration for UNIX.
When connecting to databases, consider the following factors:
• Logical database names
• Connection modes
• Connection parameters
• Connection techniques
• Connecting to a non-OpenEdge database
• Connection denials when the user count is exceeded
• Reducing connection times
• Starting clients without connecting to a database
2–2
Logical database names

A logical database name is a database reference that represents the name of a connected
physical database. OpenEdge uses the logical database name to resolve database references.
When a procedure is compiled against a database, OpenEdge stores the logical database name
in the procedure’s r-code. When a procedure executes, its database references must match the
logical name of a connected database.
A database has a logical name whenever it is connected. When you connect to a database,
OpenEdge automatically assigns a default logical name for the current session. The default
logical name consists of the physical database name without the .db suffix. For example, if you
connect to a database with the physical name mydb1.db, the default logical database name is
mydb1. Alternatively, you can use the Logical Database Name (-ld) startup parameter to specify
a logical database name other than the default.
For example, to assign the logical name firstdb to the physical database mydb1.db using the
PRO command, enter the command using the following syntax:
pro mydb1 -ld firstdb
Logical database names allow you to run procedures on different physical databases without
recompiling. To run a compiled procedure on a second physical database, the database must
meet the following criteria:
• It must have the identical structure (data definitions) and table time stamps as the database
you compiled the procedure against. However, if you use CRC-based object code (the
default), the database’s table time stamps do not affect the ability of the code to run on the
database. The structure of the database must be the same. For more information about
CRC-based object code, see Appendix B, “R-code Features and Functions.”
• It must be connected with the same logical name as the database you compiled the
procedure against.
A database connection fails if the logical database name of the database that you are connecting
has the same logical name as an already connected database. If you try to connect a database
with a logical database name that matches the logical database name of an existing connected
database of the same database type (OpenEdge RDBMS, ORACLE, etc.), OpenEdge assumes
that database is connected and ignores the request.
2–3
You can change a database’s logical name in a Progress 4GL procedure with the CREATE ALIAS
statement. For more information about logical and physical database names and aliases, and the
CREATE ALIAS statement, see OpenEdge Development: Progress 4GL Reference and OpenEdge
Development: Programming Interfaces.
Connection modes
A database is connected in one of three connection modes:
• Single-user — Only the current Progress 4GL session can access the specified database.
If the database is already in use by another user, you cannot connect to the database from
the current Progress 4GL session.
• Multi-user client — The current Progress 4GL session accesses the database through a
server process. Multi-user client is the default connection mode on non-shared-memory
systems and when you use the Host Name (-H) and Service Name (-S) parameters on
shared-memory systems. All remote (over a network) connections access the database
through a database server and are in multi-user client mode.
• Multi-user direct access — The current Progress 4GL session accesses the database
directly using shared memory. A process connected in multi-user direct-access mode is a
self-service client. Direct access is available only on shared-memory systems and is the
default connection mode on these systems. For information about shared-memory
configurations, see OpenEdge Getting Started: Installation and Configuration for
Windows or OpenEdge Getting Started: Installation and Configuration for UNIX.
You cannot connect to remote databases in multi-user direct-access mode.
When you connect to a database with a OpenEdge multi-user startup command, each database
you specify on the command line is connected in the default multi-user mode. Each database
you specify in a startup file or in a CONNECT statement in an application is also connected in the
default multi-user mode for the current machine.
The first database specified after the OpenEdge single-user or OpenEdge single-user batch
command is connected in single-user mode by default. Any additional databases specified with
the Database Name (-db) connection parameter are connected in the default multi-user mode for
the system. Use the Single-user Mode (-1) startup parameter to override the default multi-user
connection mode for a database and connect to the database in single-user mode.
For more information about the Host Name (-H), Service Name (-S), Database Name (-db), and
Single-user Mode (-1) startup parameters, see OpenEdge Deployment: Startup Command and
Parameter Reference.
2–4
Connection parameters
Connection parameters control how you connect to databases. They are a subset of the
OpenEdge startup parameters. All of the database connection techniques provide a way for you
to specify connection parameters.
You can use a parameter file to specify connection parameters with any of the connection
techniques. A parameter file is an operating system file that contains one or more startup
parameters. A parameter file has a .pf extension. Use the Parameter File (-pf) startup
parameter to invoke a parameter file.
Parameter files are an important factor in developing database connection strategies for
multi-database applications. For example, you can use parameter files to maintain the startup
parameters for a particular database, group of users, or system configuration.
For more information about startup parameters and parameter files, see OpenEdge Deployment:
Startup Command and Parameter Reference.
Connection techniques
There are five ways to connect a database:
• As an argument when starting OpenEdge.
• With the CONNECT statement (in the Progress Procedure Editor or in a 4GL procedure).
• With the OpenEdge Data Dictionary.
• With the OpenEdge Data Administration tool.
• Using the Auto-connect feature.
Note: Starting a server or broker for a database is distinct from connecting to a database. You
must start a server or broker for a database before you can connect to the database in
multi-user mode. For information about starting a server or broker, see OpenEdge
Getting Started: Installation and Configuration for Windows or OpenEdge Getting
Started: Installation and Configuration for UNIX.
This section explains how to connect to databases using the various techniques. OpenEdge
Development: Programming Interfaces explains why you might choose one technique instead
of another.
2–5
Connecting at startup
You can connect to databases at session startup with one of the OpenEdge startup commands or
with an application startup file. For example, the following PRO command starts a single-user
session and connects to three databases:
pro -db mydb1 -db mydb2 -db mydb3
Note: To retain compatibility with earlier versions, OpenEdge does not require you to specify
the Database Name (-db) connection parameter for the first database on the command
line.
If you specify more than one database when you start a session, it is important to specify the
connection parameters for each database directly after the database name to which they apply,
and before the next Database Name (-db) connection parameter. OpenEdge applies database
connection parameters only to the previously specified database.
The following syntax example illustrates the correct location for database connection
parameters:
mpro [ -db ] db1-name [ db1-parameters ]

[ -db db2-name [ db2-parameters ] ] ...
You can specify all other parameters anywhere on the command line. If you specify the same
parameter more than once, OpenEdge uses the value you specified for the last instance of the
parameter.
You can also use a parameter file to specify database connection parameters. The following
example shows a UNIX startup script for a client application. The last line invokes the _progres
executable:
DLC=${DLC-/usr/dlc}; export DLC

PATH=:$PATH:$DLC; export PATH
PROPATH=:$DLC; export PROPATH
exec $DLC/_progres -pf parm1.pf -pf parm2.pf -p $APPL/start.p
2–6
The previous startup script sets up environment variables for an application and starts a Progress
4GL client application session using two parameter files called parm1.pf and parm2.pf. The
parm1.pf parameter file contains the following entry:
-db appldb1 -1 bi-file1
The parm2.pf parameter file contains the following entry:
-db appldb2 -1 bi-file2
This example illustrates a common approach to connecting multiple databases when you start
OpenEdge using a parameter file for each database. Each parameter file is specified on the
command line with the Parameter File (-pf) startup parameter.
Connecting from a procedure with the CONNECT statement
The CONNECT statement allows you to connect to a database from a 4GL procedure or from the
Progress Procedure Editor.
The following CONNECT statements connect the appldb1 database in single-user mode, the
appldb2 database in multi-user mode, and the databases specified in the parameter file,
parm3.pf (respectively):
CONNECT appldb1 -1.

CONNECT appldb2.
CONNECT -pf parm3.pf.
Connecting with the CONNECT statement is very similar to connecting at startup. Although it is
possible to connect to several databases within one CONNECT statement, it is a good idea to
connect only one database per CONNECT statement. A connection failure for one database causes
a termination of the current CONNECT statement, leaving any subsequent database specified with
the CONNECT statement unconnected. For detailed information about the CONNECT statement, see
OpenEdge Development: Progress 4GL Reference and OpenEdge Development: Programming
Interfaces.
2–7
Connecting with the Data Dictionary
You can connect to a database during a Progress 4GL session using the graphical user interface
of the Data Dictionary.
To connect to a database with the Data Dictionary:
1. Open the Data Dictionary. The Data Dictionary main window appears:
2. Choose Database→Connect. The Connect Database dialog box appears:
2–8
3. Choose the Options button. The Connect Database dialog box expands to show optional
connection controls:
4. Enter the following information, then choose OK:
• Physical Name — Specifies the actual name of the database on a disk.
• Logical Name — Specifies the database name that references a connected physical
database.
• Database Type — Specifies the database type. The only possible value is
PROGRESS.
• Network — Specifies the network type, if you are connecting to a network server.
The only possible value is TCP.
• Multiple Users — Specifies whether you want multiple users to be able to access
this database simultaneously.
• Host Name — Specifies the database server machine in a network environment.
• Service Name — Specifies the broker or server service name in a network

environment.
• User Id — Identifies your user ID.
• Password — Identifies your password.
2–9
• Trigger Location — Identifies a directory or Progress 4GL procedure library where

trigger code is stored.
• Parameter File — Specifies the parameter filename that contains the startup
parameters for the database.
• Other CONNECT Statement Parameters — Specifies any other startup

parameters for the database that are not included in the parameter file.
OpenEdge returns you to the Data Dictionary main window. The Data Dictionary
constructs (and executes) a CONNECT statement using the information you supply.
Therefore, any rules that apply to the CONNECT statement also apply to database
connections using the Data Dictionary.
Connecting with the Data Administration tool
You can also connect to a database during a Progress 4GL session using the Data
Administration tool.
To connect to a database with the Data Administration tool:
1. Open the Data Administration tool. The Data Administration main window appears:
2–10
2. Choose Database→Connect. The Connect Database dialog box appears:
3. Choose the Options button. The Connect Database dialog box expands to show optional
connection controls:
4. Enter the following information, then choose OK:
• Physical Name — Specifies the actual name of the database on a disk.
• Logical Name — Specifies the database name that references a connected physical
database.
• Database Type — Specifies the database type. The only possible value is
PROGRESS.
• Network — Specifies the network type, if you are connecting to a network server.
The only possible value is TCP.
• Multiple Users — Specifies whether you want multiple users to be able to access
this database simultaneously.
• Host Name — Specifies the database server machine in a network environment.
2–11
• Service Name — Specifies the broker or server service name in a network

environment.
• User Id — Identifies your user ID.
• Password — Identifies your password.
• Trigger Location — Identifies a directory or 4GL procedure library where trigger

code is stored.
• Parameter File — Specifies the parameter filename that contains the startup
parameters for the database.
• Other CONNECT Statement Parameters — Specifies any other startup

parameters for the database that are not included in the parameter file.
OpenEdge returns you to the Data Administration main window. The Data Administration
tool constructs (and executes) a CONNECT statement using the information you supply.
Therefore, any rules that apply to the CONNECT statement also apply to database
connections using the Data Administration tool.
Connecting with auto-connect
The OpenEdge auto-connect feature allows you to connect to databases automatically as

required during program execution. To perform an auto-connect operation, OpenEdge uses
information stored in a primary database to connect to a secondary application database, before
running compiled procedures that access the second database. The primary database (the one
that contains the auto-connect information for one or more additional databases) must be
connected before OpenEdge can perform an auto-connect.
Use the Data Administration tool to build an auto-connect list for a primary database.
2–12
To create or edit an auto-connect list:
1. Access the Data Administration tool.
2. Choose Utilities→Edit Progress Auto-Connect List. The Edit Auto-Connect List

dialog box appears:
3. Enter or edit connection information for a database.
If you connect to a database with the CONNECT statement, and that database also has an
auto-connect entry in an already connected database, the connection information from both the
CONNECT statement and the auto-connect list is merged. In this situation, the connection
information in the CONNECT statement takes precedence. For more information about the
CONNECT statement, see OpenEdge Development: Progress 4GL Reference.
If the primary database is a schema holder for a DataServer schema, the DataServer schema is
automatically included in the auto-connect list, but it does not appear on the auto-connect list as
viewed from the Data Dictionary.
2–13
Connecting to a non-OpenEdge database

You can also use the OpenEdge tools to connect to a non-OpenEdge database.
To connect to a non-OpenEdge database:
1. Create an OpenEdge RDBMS. This database stores the target database’s structure as an
OpenEdge schema; it is a schema holder. A schema that corresponds to a non-OpenEdge
database is a DataServer schema.
2. Connect the schema holder.
3. Use the appropriate Create Schema parameter from the Data Dictionary’s database menu
to create the DataServer schema in the schema holder. This parameter:
• Creates a _Db table record (auto-connect entry) for the non-OpenEdge database in
the schema holder database.
• Connects to the non-OpenEdge schema (through a DataServer).
• Displays the menu so that you can choose the tables that you want to include in the
OpenEdge schema.
4. Connect the DataServer schema.
For complete information about connecting and using non-OpenEdge databases, see the
OpenEdge DataServer guides (OpenEdge Data Management: DataServer for ODBC or
OpenEdge Data Management: DataServer for ORACLE).
2–14
Connection denials when the user count is exceeded

When a user attempts to connect to a database using either a CONNECT statement or a command
and exceeds the maximum number of users allowed to connect to the database, as specified with
the Number of Users (-n) startup parameter, OpenEdge denies the connection request and
displays an error message. OpenEdge also records the connection denial in the database log file.
Figure 2–1 shows a connection denial when a connection request exceeds the maximum number
of users. In this example, the Number of Users (-n) startup parameter allows a maximum of
three user connections. When the fourth user attempts to connect, OpenEdge denies the
connection.
User1
User2
Database server Database (with
-n = 3)
User3
User4 connection
User4
request denied
Figure 2–1: Connection denial when the user count is exceeded
When OpenEdge denies a user connection because the maximum number of users is exceeded,
you must terminate an existing connection before the user can establish a new connection.
You can use database usage reporting features to track user connections to databases. For
information about database usage reporting features, see OpenEdge Data Management:
Database Administration and either OpenEdge Getting Started: Installation and Configuration
for Windows or OpenEdge Getting Started: Installation and Configuration for UNIX.
For more information about the Number of Users (-n) startup parameter, see OpenEdge
Deployment: Startup Command and Parameter Reference.
For information about coding applications to handle connection denials, see OpenEdge
2–15
Reducing connection times

To perform database activities, the OpenEdge client keeps a copy of the database schema, called
the schema cache, in memory. By default, OpenEdge creates the schema cache by reading the
database schema stored in the database file. The client reads the schema in two parts:
• During connection, the client reads all the _Db and _File records.
• When the database is referenced, the client reads all the _Index, _Index-field, _File-trig,
and _Field-trig records.
The time required to read the schema is usually minimal. However, the time required to read the
schema might be unacceptable under the following conditions:
• If the client connects to the database over a wide area network.
• When a large number of clients connect to a database simultaneously. For example, after
a database shutdown or crash.
To reduce the amount of time required to connect, OpenEdge lets you store the schema cache
as a binary file, called a schema cache file, on a local disk. The client can then read the schema
directly from the schema cache file.
To create the schema cache file, you build the desired schema cache and save it to a binary file
using the Progress statement SAVE CACHE. The schema cache file is portable across systems, so
you can create the file once and distribute it across a heterogeneous network of systems. For
information about building and saving the schema cache file, see OpenEdge Development:
Programming Interfaces. For information about the SAVE CACHE statement, see OpenEdge
Development: Progress 4GL Reference.
To connect using the local schema cache file, specify the Schema Cache File (-cache) startup
parameter when you connect to a database. If the schema cache file is valid, OpenEdge reads
the schema from the local file instead of from the database. The schema cache is valid if the time
stamp of the schema cache file matches the time stamp in the database master block. If the time
stamps do not match, or for some reason OpenEdge cannot read the file, OpenEdge issues a
warning message and reads the schema from the database. For information about the Schema
Cache File (-cache) startup parameter, see OpenEdge Deployment: Startup Command and
2–16
Starting clients without connecting to a database

To permit maximum flexibility for your application, you might want to start OpenEdge without
connecting to a database. For example, you can start OpenEdge and name a startup procedure,
such as a main menu procedure. This startup procedure (or a procedure that it calls) can connect
to a database based on an end user’s menu selection. To start OpenEdge without connecting to
a database, execute the OpenEdge startup command without specifying a database name. On
UNIX, use the PRO command; in Windows, use the PROWIN32 command. For more information
about startup commands, see OpenEdge Deployment: Startup Command and Parameter
Reference.
Selecting a working database for client use

A working database is the database that you are currently accessing through the Data Dictionary
or the Database Administration tool. The working database is also known as the active
database.
Selecting a database with the Data Dictionary

You can select a working database with the Data Dictionary when using either a graphical or
character interface.
To select a working database with the Data Dictionary when using a graphical interface:
1. Access the Data Dictionary. The Data Dictionary displays the connected databases and
their tables and fields.
2. Select the database you want for the working database.
To select a working database with the Data Dictionary when using a character interface:
1. Access the Data Dictionary. The Data Dictionary appears.
2. Choose Database→Select a Working Database. OpenEdge lists the connected

databases.
3. Select the new working database, then choose Enter to return to the Data Dictionary
main window.
2–17
Selecting a database with the Data Administration tool

You can select a working database with the Data Administration tool only when using a
graphical interface.
To select a working database with the Data Administration tool:
2. Choose Database→Select a Working Database. OpenEdge lists the connected

databases.
3. Select the new working database, then choose OK to return to the Data Administration
main window.
Disconnecting databases for clients

By default, OpenEdge disconnects all connected databases at the end of a session. To explicitly
disconnect a database from a Progress 4GL client application, use the DISCONNECT statement.
For more information about the DISCONNECT statement, see OpenEdge Development: Progress
4GL Reference and OpenEdge Development: Programming Interfaces.
Note: When you have more than one database connected and you disconnect the working
database, OpenEdge automatically switches to the next connected database on the list.
2–18
Disconnecting a database with the Data Dictionary

You can disconnect a database with the Data Dictionary when using either a graphical or
character interface.
To disconnect a database with the Data Dictionary when using a graphical interface:
1. Access the Data Dictionary. The Data Dictionary displays the connected databases and
their tables and fields.
2. Select the database you want to disconnect from the database selection list.
3. Choose Database→Disconnect.
4. At the prompt, verify that you want to disconnect the database.
To disconnect a database with the Data Dictionary when using a character interface:
1. Access the Data Dictionary.
2. Choose Database→Disconnect. OpenEdge lists the connected databases.
3. Select the database you want to disconnect, then choose Enter.
Disconnecting a database with the Data Administration

tool
You can disconnect a database with the Data Administration tool only when using a graphical
interface.
To disconnect a database with the Data Administration tool:
2. Choose Database→Disconnect. OpenEdge lists the connected databases.
3. Select the database you want to disconnect, then choose OK.
2–19
2–20
3
Maintaining Application Security
OpenEdge provides two types of security: application security which prevents unauthorized
users from running application procedures or accessing data in a database, and database file
security which prevents unauthorized users from modifying or removing database files.
OpenEdge provides four levels of security: 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, connection security ensures that
only authorized users can connect to the database, and schema security ensures that only
authorized users can modify table, field, and index definitions.
OpenEdge also relies on security mechanisms at the operating system level to ensure that only
authorized users access r-code procedure files, procedure library files, and database files. This
chapter contains the following sections:
• Compile-time security
• Run-time security
• Operating system security
• Designating a security administrator
For information about establishing and maintaining connection security, schema security, and
database file security, see OpenEdge Data Management: Database Administration. In addition
to the security features described in this chapter, OpenEdge supports secure connections
between OpenEdge client and server components on the network using the Secure Sockets
Layer (SSL). For more information, see OpenEdge Getting Started: Security.
Compile-time security
Compile-time security checking is built into OpenEdge. You define compile-time security for
an application database at the table and field levels to prevent the user from writing their own
procedures to access data in the database.
OpenEdge lets you define the type of access rights or permissions different users can have to
the tables and fields in your database applications. OpenEdge checks these permissions when
the user runs and compiles a procedure for the first time during a OpenEdge session. However,
permissions are not checked when the user runs procedures that are precompiled. For
information about how to enable security for precompiled procedures, see the “Run-time
security” section on page 3–8.
If you use CRC-based r-code (the default), the user can compile a procedure against a database
that has the same schema as the database (a counterfeit database) and then run the procedure
against the database. Since OpenEdge does not check the permissions of the database at compile
time, you have no compile-time security. However, you can use the PROUTIL utility’s
DBAUTHKEY qualifier to set an authorization key for the database. The authorization key
prevents unwanted r-code from being run against the database.
For more information about CRC-based object code, see Appendix B, “R-code Features and
Functions,” For more information about the PROUTIL utility, see OpenEdge Data
Using table- and field-level security

After you have designated yourself and others as security administrators, be sure that the user
ID of each security administrator is included in all the permissions lists for the tables and fields
for the database. For example, if you assign user ID sjones as a security administrator, but sjones
is not included in the permissions for the customer table, sjones will not be able to modify
permissions for the customer table. Any attempt to do so results in an error message “Invalid
access to change security for customer table.” Thus, to modify table and field permissions, a
user ID must be designated as a security administrator and be included in each of the individual
table and field permissions.
For information about designating a security administrator, see the “Designating a security
administrator” section on page 3–9.
3–2
Setting table and field permissions

You set table and field permissions by using the Change/Display Data Security utility in the
Data Dictionary. Note that once security administrators are designated, only they can access this
utility. All other users are denied access with the message “You must be a Security
Administrator to execute this function.”
To set table or field permissions:
1. Access the Data Administration tool if you are using a graphical interface or the Data
Dictionary if you are using a character interface.
2. Choose Admin→Security→Edit Data Security.
If you are using a graphical interface, the Edit Data Security dialog box appears:
3–3
If you are using a character interface, OpenEdge alphabetically lists the tables defined for
the working database. Choose the table for which you want to specify permissions. The
Edit Data Security dialog box appears:
3. Choose the table or field for which you want to specify permissions.
If you are using a graphical interface, use the Permissions for Selected Table and
Permissions for Selected Field radio buttons, then choose the table or field from the
selection lists.
If you are using a character interface, use the options at the bottom of the dialog box to
choose the table or field.
4. Specify the security permissions for the table or field. Table 3–1 lists the security
permissions you can specify for a table or field.
Table 3–1: Security permissions (1 of 2)
Permission Description
Can-Read Specifies the users who have permission to read a table.
Can-Write Specifies the users who can write to a table or update records.
Can-Create Specifies the users who can create new records. The user with
Can-Create privileges automatically has Can-Write privileges.
Can-Delete Specifies the users who can delete records from a table.
3–4
Table 3–1: Security permissions (2 of 2)
Permission Description
Can-Dump Specifies the users who can dump database or table definitions and
data.
Can-Load Specifies the users who can load database or table definitions and
data.
Note: Use commas, not periods, to separate the names in these options.
Table 3–2 lists the values you use to define the permissions for a table.
Table 3–2: Access restrictions for tables
Expression Meaning
* All users have access.
user This user has access.
! user All users have access, except this user.
string* User IDs that begin with this string have access.
Any changes you make to the table permissions do not affect the current session or any
other current sessions. This means that if other users are working while you change table
permissions, they are not affected. To use the new permissions, you must exit and restart
OpenEdge.
Note: Do not try to bypass the Data Dictionary to modify the permissions for the tables
and fields in the database. You might lock yourself out of the database.
3–5
Example of personnel security
This example shows how to define permissions for a sample database called mywork. Suppose
the user IDs defined in the user list for the database are salesrep, inventory, and manager. Users
using the IDs are as follows:
• Sales personnel use the salesrep user ID.
• Warehouse personnel use the inventory user ID.
• Managers use the manager user ID.
Suppose you want all users to have Can-Read permission for the customer table, but only users
with the specified user IDs to have Can-Write, Can-Create, and Can-Delete privileges. The
following example shows how to specify this information for the customer table:
Can-Read: *
Can-Write: salesrep,manager
Can-Create: salesrep,manager
Can-Delete: manager
In the next example for the customer table, all users have Can-Read permission for the Name
field. In addition, all users have Can-Write permission, except users with the user ID of
inventory:
Field name: Name
Can-Read: *
Can-Write: *,!inventory
In the next example for the customer table, all users, except those with a user ID of inventory,
have Can-Read permission for the Max-credit field. Here, only managers have permission to
write to this field:
Field name: Max-credit
Can-Read: *,!inventory
Can-Write: manager
3–6
Determining the privileges of the blank user ID

The user has the blank user ID when you run your own startup procedure without using the
SETUSERID function, or without using the User ID (-U) and Password (-P) startup parameters.
For more information about these startup parameters, see OpenEdge Deployment: Startup
Command and Parameter Reference.
The user can use OpenEdge or an OpenEdge application with a blank user ID and access tables
and fields in the database as long as the table- and field-level permissions permit it (blank user
ID), and the procedures being run are precompiled. OpenEdge expects an application to run a
login program to set the user ID to a more meaningful value.
As the security administrator, you might want to deny privileges to the blank user ID to ensure
that unknown users do not gain access to the database.
To specify blank user ID privileges:
1. Access the Data Administration tool if you are using a graphical interface or the Data
Dictionary if you are using a character interface.
2. Choose Admin→Security→Disallow Blank Userid Access. OpenEdge prompts you to

verify that you want to prevent users with blank user IDs from accessing the working
database.
3. Choose Yes. OpenEdge denies the user all security permissions and inserts an exclamation
point (!) at the beginning of all the table and field permissions for the database. You can
restore a blank user ID’s access to selected tables and fields by modifying the permissions.
3–7
Run-time security
The application developer can provide run-time security to prevent unauthorized users from
running precompiled procedures. To establish run-time security, the developer must set up a
permissions table within the database.
The permissions table contains records that specify users who are authorized to run specific
procedures. Each record in the permissions table must contain at least two fields: an Activity
field and a Can-Run field. The Activity field contains the name of the procedure and the
Can-Run field contains the user IDs of those who have permission to run the procedure. Within
the application, the developer uses the CAN-DO and USERID functions to test whether the current
user can run a specific procedure.
As security administrator, you must maintain the permissions table. It is the developer’s
responsibility to provide the tools to maintain this table.
For more information about run-time security and maintaining the permissions table, see
OpenEdge Development: Programming Interfaces.
Operating system security

Each operating system provides security measures that you can use to protect r-code procedure
files, procedure library files, and database files.
On UNIX, you can use operating system file security to protect your procedure files in addition
to, or instead of, including security checking in the application procedures. For example, if you
want to be the only user allowed access to p-adcust.p, you should create the source and r-code
files with your user ID, then change the permissions for the files. To change the permissions for
p-adcust.p, enter one of the following UNIX commands:
chmod 600 p-adcust.p

chmod 600 p-adcust.r
These permissions indicate that you are the only user allowed to read from (R) and (W) write to
p-adcust.p. No other users are allowed any kind of access to that procedure.
For more information about using the operating system to protect database files, see OpenEdge
Data Management: Database Administration. For more information about setting operating
system permissions, see your operating system documentation.
3–8
Designating a security administrator

Each level of security uses a user ID to determine the user’s authority to access data and files.
Associating a user ID with a password provides even more protection against unauthorized
access.
If you establish a list of valid user IDs, you must designate one user, or preferably more than
one user, as security administrator. The security administrator is responsible for maintaining the
security information in the database. Typically, the database administrator also serves as
security administrator. The security administrator uses:
• The Data Dictionary to establish connection, schema, and compile-time security.
• An activity table provided by the developer to establish run-time security.
For more information about designating a security administrator or establishing and

maintaining user IDs, passwords, and data access privileges, see OpenEdge Data Management:
Database Administration.
3–9
3–10
4
Maintaining User Environments
This chapter explains how to maintain user interface environments in Windows and on UNIX,
as described in the following sections:
• Maintaining the Windows user environment
• Maintaining the UNIX user environment

Maintaining the Windows user environment

In the Windows software environment, OpenEdge uses the progress.ini file as well as the
Registry to maintain environment variables.
When you install OpenEdge, the installation program automatically updates the Registry with
the information in the progress.ini file that is shipped to you. Progress Software recommends
that you maintain environment variables in both the progress.ini file and the Registry. If you
modify environment variables in the progress.ini file, you must update the information in the
Registry.
Although there are several methods for adding and deleting information from the Registry
directly, Progress Software recommends that you do not use these direct update methods.
Instead, maintain the Registry information by editing the progress.ini file and using the
INI2REG utility to update the Registry. This approach synchronizes the information in the
progress.ini file and the Registry without causing unintended edits to the Registry.
For more information about modifying the progress.ini file, see the “Maintaining the
progress.ini file” section on page 4–9.
Using the INI2REG utility

The INI2REG utility lets you translate the contents of an initialization (.ini) file into
comparable Registry key entries. You can access the INI2REG utility through a graphical user
interface or from the command line.
4–2
To access the INI2REG utility and translate an initialization file:
1. Specify the INI2REG command using the following syntax:
ini2reg
The INI File to Registry Translation dialog box appears:
2. From the INI File to Registry Translation dialog box, choose the Browse button or
File→Open. The Open dialog box appears.
3. Type in or browse for the initialization file you want to translate, and choose OK. The
name of the selected file appears in the .INI file to translate field.
4. From the Registry base key drop-down list, select the base key under which you want to
create the subkey entries. The default subkey that corresponds to the selected initialization
file and base key appears in the Registry subkey field.
If you want to use a subkey other than the default, type the subkey name in the Registry
subkey field.
4–3
5. To begin the translation, choose the Translate button or File→Translate. For each entry
in the initialization file, INI2REG creates a Registry key entry with the same value. As
each entry is translated, it appears in the Values being translated display area. If a Registry
key entry already exists, INI2REG prompts you to overwrite it.
6. To exit, choose the Exit button or File→Exit.
Using the command line interface
To access the INI2REG utility and translate an initialization file from the command line, specify
the INI2REG command using the following syntax:
ini2reg { -a | -ao } [ -i ini-file-name ] [ -b base-key ]

[ -s subkey ][ -d default-subkey ]
-a
Automates the translation. That is, it processes the translation automatically without
presenting the graphical user interface.
-ao
Automates the translation and automatically overwrites existing Registry entries.
-i ini-file-name
The pathname of the initialization file to translate.
-b base-key
The base key under which the subkey is created. The value of base-key must be one of
following:
• HKEY_CURRENT_USER (default).
• HKEY_USERS.
• HKEY_LOCAL_MACHINE.
• HKEY_CLASSES_ROOT.
• HKEY_CURRENT_CONFIG.
• HKEY_DYN_DATA.
4–4
-s subkey
The subkey under which entries are created. The subkey is created under the base key
specified in the -b parameter.
Use -d to specify a default subkey for the translation destination.
-d default-subkey
The default subkey under which entries are created. The default subkey is created under
the base key specified in the -b parameter.
If the base key is HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER, INI2REG prepends

SOFTWARE to the specified default subkey. If the initialization file name is not
progress.ini, INI2REG appends the root name of the initialization file to the specified
default subkey. If this parameter is not specified, INI2REG uses a default subkey of
PSC\PROGRESS\version.
You can generalize this as follows:
base-key\[SOFTWARE]\default-subkey\[rootname]
Use -s to specify a complete subkey for the translation destination.
By default, the INI2REG utility creates Registry key entries at the following location:
HKEY_CURRENT_USER\SOFTWARE\PSC\PROGRESS\version
4–5
Searching progress.ini and the Registry at startup

At startup, OpenEdge searches for a Registry location, a progress.ini file, or both. The
particular search path depends upon the parameters you specify with the prowin32 command,
particularly the Registry Base Key (-basekey) and Initialization File (-ininame) parameters. You
can use these parameters to create a more efficient search at startup.
Note: The -basekey and -ininame parameters can only be used on the command line. You
cannot use them within a parameter file.
Figure 4–1 illustrates the path that OpenEdge follows when searching for environment
information in Windows.
4–6
OpenEdge starts (prowin32), and

searches for the environment location, according to the
specified or unspecified -basekey and -ininame
parameters.
-ininame =
progress.ini, or no Registry yes
basekey specified? -basekey =
-ininame “INI”?
unspecified? (-basekey)
yes no
yes no
OpenEdge searches:
1. HKEY_CURRENT_USER\<path>
<
\ root name>.<extension> -ininame
2. HKEY_CURRENT_USER\SOFTWARE no specified?
\PSC\PROGRESS\<version>\<path>
<
\ root name>.<extension> OpenEdge searches
3. HKEY_CURRENT_USER\SOFTWARE for progress.ini file yes
<
\ path>\<root name>.<extension>
4. HKEY_CURRENT_USER\<root name>
5. HKEY_CURRENT_USER\SOFTWARE
\PSC\PROGRESS\<version>\<root name> yes
6. HKEY_CURRENT_USER\SOFTWARE -ininame =
<
\ root name> progress.ini?
7. HKEY_LOCAL_MACHINE\<path> OpenEdge searches
<
\ root name>.<extension> for the specified .ini file,
8. HKEY_LOCAL_MACHINE\SOFTWARE
in this order: no
\PSC\PROGRESS\<version>\<path>
<
\ root name>.<extension> 1. Current directory
9. HKEY_LOCAL_MACHINE\SOFTWARE 2. Windows directory
<
\ path>\<root name>.<extension> 3. Progress directory
10. HKEY_LOCAL_MACHINE\<root name> 4. PROPATH
11. HKEY_LOCAL_MACHINE\SOFTWARE -ininame
\PSC\PROGRESS\<version>\<root name> no specified?
12. HKEY_LOCAL_MACHINE\SOFTWARE
<
\ root name> OpenEdge searches in
13. File named the Registry only for
“<path>\<root name>.<extension>” yes
<basekey>\SOFTWARE
\PSC\PROGRESS\<ver>
OpenEdge searches:
yes
1. HKEY_CURRENT_USER\SOFTWARE -ininame =
\PSC\PROGRESS\<version> progress.ini?
2. HKEY_LOCAL_MACHINE OpenEdge searches
\SOFTWARE\PSC\PROGRESS\<version> in the Registry only for
3. File named progress.ini <basekey>\<ininame> no
Figure 4–1: Windows environment information search path
4–7
When OpenEdge does not find environment information in the Registry, or when it was started
with the -basekey INI startup parameter, it searches through directories for a progress.ini file
in the following order:
1. The current working directory (as defined in the Working Directory field in the Program
Item properties sheet for Windows).
2. The WINDOWS directory.
3. The directory that contains the OpenEdge executable.
4. The user’s PROPATH.
This search order fosters deployment flexibility because you can:
• Create a customized progress.ini file.
• Place the file in a consistent place on every machine.
• Allow all users to share the same file on a network.
After OpenEdge locates the environment information, OpenEdge reads the values for DLC,
PROMSGS, and other environment variables. For each variable, OpenEdge first searches the
location where it found the environment information. If OpenEdge does not find the variable, it
searches for an operating system environment variable.
OpenEdge expects to find all environment settings in the same location it finds the environment
variables. There is one exception: OpenEdge searches HKEY_CURRENT_USER and
HKEY_LOCAL_MACHINE first when it starts without the -basekey parameter and finds the
environment information in the Registry. If OpenEdge writes a value to the Registry, however,
it will always write it to HKEY_CURRENT_USER. This allows multiple users of a single machine to
customize settings individually. The environment setting location could be either a Registry key
or an initialization file, but not both.
The Progress 4GL GET-KEY-VALUE statement also searches for user environment information.
The GET-KEY-VALUE statement searches either the Registry or a progress.ini file, but not both.
When GET-KEY-VALUE searches the Registry, it searches both of the HKEY_CURRENT_USER and
HKEY_LOCAL_MACHINE keys if the following conditions are true:
• The OpenEdge startup command (prowin32) used for the current session did not include
the -basekey parameter.
• OpenEdge found the environment information in the Registry at startup or at the last LOAD
statement.
4–8
The Progress 4GL PUT-KEY-VALUE statement writes to the location where the environment
information was found at startup. If that location is the Registry, and if the prowin32 command
did not include the -basekey parameter at startup, the PUT-KEY-VALUE statement writes to the
HKEY_CURRENT_USER key and not to the HKEY_LOCAL_MACHINE key.
Maintaining the progress.ini file

The progress.ini file specifies environment variable settings for the Windows environment.
It contains sections and settings for the following types of options:
• Options required by OpenEdge.
• Options required by OpenEdge tools (such as the Procedure Editor and the Report
Builder).
• User-defined options.
• Environment variables.
4–9
Figure 4–2 shows excerpts from a sample progress.ini file.
[Startup]
V6Display=no
;ImmediateDisplay=yes
;MultitaskingInterval=100
DefaultFont=MS Sans Serif, size=8
DefaultFixedFont=Courier New, size=8
DLC=C:\Progress\OpenEdge
Use-3D-Size=Yes
PROPATH=.,C:\Progress\OpenEdge\C:\Progress\OpenEdge\bin
UseSourceEditor=yes
EditorConfigPath=C:\OpenEdge\WRK\proedit
.
.
.
[WinChar Startup]
DLC=C:\Progress\OpenEdge
PROCFG=C:\DLC\PROGRESS.CFG
PROMSGS=C:\DLC\PROLANG\PROMSGS.GER
PROPATH=.,C:\DLC
V6Keys=No
V6FKeys=No
.
.
.
Figure 4–2: Sample Progress initialization file in Windows
When installed, the progress.ini file contains the following sections:
• Startup section.
• Colors section.
• Default Window section.
• Fonts section.
• WinChar Startup section.
• WinChar Colors section.
• WinChar Default Window section.
• WinChar Keys section.
4–10
The progress.ini file can also contain the following optional sections:
• “Debug-Init section” section on page 4–31.
• “Debug-Macros section” section on page 4–32.
• “Debug-Buttons section” section on page 4–32.
• “Keys section” section on page 4–32.
• “Keymap section” section on page 4–34.
You can edit the progress.ini file to customize environments at different sites. The
progress.ini file is located in the install-dir\bin directory, by default.
The following sections describe each of these progress.ini file sections.
Startup section
The Startup section of the progress.ini file contains options that specify the following
environment characteristics for graphical user interface clients:
• Display attributes and multi-tasking capabilities.
• Default fonts used for displaying and printing alphanumeric data.
The Startup section also contains OpenEdge environment variables that you can set for use with
graphical user interface clients. See Table 4–5 in the “Specifying environment variables”
section on page 4–36 for a list of environment variables you can set in the Startup section.
The Startup section contains the following options:
AlignFrameTitles
AlignFrameTitles=n
Lets you specify the alignment of frame titles in a graphical user interface. Valid settings
include the following: 0 (left justified), 1 (centered), and 2 (right justified). The default is
centered.
4–11
AS/400_AppcDllName
AS/400_AppcDllName=dll-filename
Lets you specify a dynamic link library for AS/400 communications.
For Version 7.3B and later, you can specify the name of the DLL that you want to use for
AS/400 communications. Table 4–1 lists the available DLLs depending on the AS/400
communication protocol and the type of network support you use.
Table 4–1: DLL files for AS/400 communications
AS/400
communication Type of
protocol network support DLL filename
SNA Rumba for APPC AS4WCP32.DLL
SNA Client Access/Netsoft AS4EHN32.DLL
SNA Microsoft SNA Server AS4WCP32.DLL
CarefulPaint
CarefulPaint={ YES | NO }
Lets you set the accuracy with which OpenEdge repaints overlapping 3D widgets and
frames. Set to YES for OpenEdge to repaint overlapping 3D widgets and frames slowly and
carefully. Set to NO for OpenEdge to repaint overlapping 3D widgets and frames quickly
(which might reduce the quality of the graphic). The default value is YES.
This option applies only when UseNative3D=NO.
4–12
ClientTimeOut
ClientTimeOut=n
Lets you specify the number of minutes a client session can remain inactive before the
server disconnects the session.
The server process determines whether a client has been inactive for a specified period of
time, and if so, the server disconnects the client and backs out any related active
transactions.
DefaultFixedFont
DefaultFixedFont=typeface, [ size point-size, keyword, ... ],

[ script=scriptname ]
Lets you specify the default fixed display font.
typeface
A valid typeface name, such as Times or Courier.
point-size
The size of the font, in points. If you omit the point size, OpenEdge uses the default
point size as defined by the typeface.
keyword
You can specify the following keywords: bold, italic, underline, or strikeout.
scriptname
By default, OpenEdge uses the script (character set) of the Windows FixedSys font
for all fonts specified in the environment. If you select a different script when editing
a font using the font common dialog, OpenEdge writes the specified script name to
the font entry.
4–13
DefaultFont
DefaultFont=typeface, [ size point-size, keyword, ... ],

Lets you specify the default display font.
typeface
point-size
keyword
scriptname
the font entry.
DefaultV6UpdateFont
DefaultV6UpdateFont=typeface, [ size point-size, keyword, ... ],

Lets you specify the Version 6 update font.
typeface
point-size
4–14
keyword
scriptname
the font entry.
When V6Display=YES, the font specified by the DefaultV6UpdateFont setting is

used when a fill-in is in update mode. The default value for DefaultV6UpdateFont is
a version of the system default fixed font with underlines (fixedsys, underline).
The DefaultFixedFont and the DefaultV6UpdateFont should be the same base font.
If you change them, make sure that the font is fixed and that the
DefaultV6UpdateFont has the underline attribute. OpenEdge does not automatically
add the underline attribute to the DefaultV6UpdateFont setting.
EndMsgTitle
EndMsgText
EndMsgTitle=title-text
EndMsgText=message-text
Lets you specify the title and text for the Windows shutdown message box.
When Windows shuts down, a dialog box prompts the user to verify the shutdown. If the
user answers YES, OpenEdge closes and the Windows Exit procedure continues. If the user
answers NO, the Windows Exit procedure terminates and Windows remains active.
EndMsgTitle can be up to 80 characters long. Its default value is “OpenEdge.”

EndMsgText can be up to 80 characters long. Its default value is “Windows is exiting. Is
this OK?”.
4–15
FrameSpacing
FrameSpacing=n
Lets you specify how the OpenEdge layout processor spaces frames.
Setting the value to -1 places the frame at the next character unit boundary. Setting the
value to 0 places frames one half of a character unit apart. Setting the value greater than 0
spaces the frames by the specified number of pixels.
ImmediateDisplay
ImmediateDisplay={ YES | NO }
Lets you redisplay the screen at predefined intervals.
If you do not set this option, some Version 6 applications will not draw the screen
correctly. Set this option for applications with existing code that you do not want to
modify. The default setting is NO.
You can also use the IMMEDIATE-DISPLAY attribute with the SESSION system handle to
surround the offending code. This is the preferred technique.
For more information about the IMMEDIATE-DISPLAY attribute and the SESSION system
handle, see OpenEdge Development: Progress 4GL Reference.
Keep3DfillinBorder
Keep3DfillinBorder={ YES | NO }
Set to YES to display a disabled fill-in field with a border. Set to NO to display a disabled
fill-in field without a border. The default value is NO.
4–16
MultitaskingInterval
MultitaskingInterval=n
Lets you specify how the OpenEdge session interacts with a Windows cooperative
multi-tasking environment. Its value determines how often OpenEdge filters events or
messages between itself and other Windows applications. As OpenEdge filters these
events more often, it executes procedures less efficiently but allows other Windows
applications more opportunity to execute. Adjusting the internal event filter is particularly
useful during background processing, such as report generation.
To maximize performance during batch-mode processing, set the value to 9999 (the
maximum value allowed). If you want to run another application while you run OpenEdge
in batch mode, set the value to 1000. If you set the value to 0 (the default), the internal loop
never executes. Although this results in high performance, interoperability with other
Windows applications is poor. The lower the number, the more often the loop executes,
resulting in better interoperability. Set this option for applications with existing code that
you do not want to modify.
You can also use the MULTITASKING-INTERVAL attribute with the SESSION system handle
to control how OpenEdge interacts with Windows cooperative multi-tasking by
surrounding long 4GL processing loops with this attribute.
See OpenEdge Development: Progress 4GL Reference for more information about the
MULTITASKING-INTERVAL attribute and the SESSION system handle.
NoSplash
NoSplash={ YES | NO }
Set to YES to turn off display of the splash screen. By default, the OpenEdge GUI client
and the WebClient display a splash screen during startup. The screen, which is a blue
rectangle with the words “Powered by Progress Software,” disappears when the
OpenEdge application starts.
4–17
Opsys
Opsys=character-string
Lets you specify the value used by the OPSYS preprocessor directive or the value returned
by the OPSYS function. Valid settings include any character string.
PopupAppOverridesSys
PopupAppOverridesSys={ YES | NO }
Set to YES to display the system-default pop-up menu only if a user-defined pop-up menu
is not available. Set to NO to display the system-default pop-up menu regardless of a
user-defined pop-up menu. If a user-defined pop-up menu is available, it is displayed after
the system pop-up menu is closed. The default value is YES.
Note: The system-default pop-up menu is displayed when you click the right mouse
button on a fill-in field or an editor widget and a user-defined pop-up menu is not
available.
PopupNoSysDefault
PopupNoSysDefault={ YES | NO }
Set to YES to suppress the system-default pop-up menu. Only the user-defined pop-up
menu is displayed. The default value is NO.
Note: The system-default pop-up menu is displayed when you click the right mouse
button on a fill-in field or an editor widget and a user-defined pop-up menu is not
available.
4–18
PopupOnMouseDown
PopupOnMouseDown={ YES | NO }
Set to YES to display a pop-up menu when the right mouse button is depressed. Set to NO
to display a pop-up menu when the right mouse button is released. The default value is NO.
Note: This option applies only to pop-up menus that are displayed with the right mouse
button (that is, MENU-MOUSE = 3). Menus that are displayed with the left or middle
mouse button are always displayed when the buttons are depressed.
PrinterFont
PrinterFont=typeface, [ size=screen-point-size ]
Lets you specify the printer fonts OpenEdge uses with the OUTPUT TO PRINTER statement.
PrinterFontn
PrinterFontn=typeface, [ size=screen-point-size ]
Lets you specify the printer font OpenEdge uses with the OUTPUT TO LPTn statement.
UseNative3D
UseNative3D={ YES | NO }
Set to YES to use the 3D drawing capabilities in Windows 95/NT 4.0. Set to NO to use the
3D drawing capabilities in OpenEdge. The default value is YES.
4–19
UseSourceEditor
UseSourceEditor={ YES | NO }
Set to YES if you want to use the Source Editor (Slick Edit). Set to NO if you want to use
Rich Edit editor. Both editors are Unicode-enabled.
Use-3D-Size
Use-3D-Size={ YES | NO }
Lets you specify how OpenEdge calculates the height of a character unit.
If you set the value to YES, OpenEdge uses the height of a three-dimensional fill-in. If you
set the value to NO, OpenEdge uses the height of a non-three-dimensional fill-in. The
default setting is YES.
V6Display
V6Display={ YES | NO }
Lets you specify Progress Version 6 behavior.
When you compile a procedure in Windows, OpenEdge compiles the borders and fonts
associated with user interface widgets into the screen layout by default. As a result, you
might encounter compilation problems when you try to run a Version 6 application in
Progress Version 7 for Windows. There might not be enough space on the display to
accommodate the borders and default fonts that are automatically associated with user
interface widgets of the Version 6 application.
To avoid this problem, set V6Display to YES to specify that you are running Version 6
code.
You can also set a session attribute to control the run-time setting of the V6Display state.
The attribute is V6DISPLAY and has a Boolean value. Setting this attribute has the same
effect as specifying the setting at startup. However, you must hide all existing windows.
4–20
When you set the V6Display option or session attribute:
• The character unit height is recalculated to the height of the font specified by the
DefaultV6UpdateFont option.
• The character unit width is recalculated to the width of an average character in the
font specified by the DefaultV6UpdateFont option.
• The default font is automatically changed to use the font specified by the
DefaultFixedFont option.
• All OpenEdge fill-ins are created without a border.
• OpenEdge fill-ins keep any trailing spaces.
• All OpenEdge fill-ins that are enabled for update use the font specified by the
DefaultV6UpdateFont option (by default, the default fixed font with underlines).
This means that updateable fill-ins are drawn with underlines.
• Frame titles are drawn so that the frame title height measures exactly one character
unit.
The V6Display option or attribute does not enable support for PUT SCREEN. In addition, if
you set the V6Display option, Version 7 applications that have not been compiled with the
V6Display option set to YES will draw screens incorrectly.
Note: The V6Display option is intended for use with applications, not with the OpenEdge
ADE. The ADE is not supported when V6Display is set to YES.
If you plan to use Version 6 user interface code with Version 7 tools (or your own Version
7 interface), Progress Software recommends that you use the V6Frame option instead of
V6Display.
V6FontNumber
V6FontNumber=n
Lets you specify the font for Version 6 frames.
4–21
By default, this option points to the font defined as font3 in the [Fonts] section. Font3 is
the ADE character-mode font. If you change the V6FontNumber value, make sure you
define the new font number in the [Fonts] section.
Note: Do not change the definition of font3 in the [Fonts] section. OpenEdge relies on
that font definition for other purposes.
V6FrameBGC
V6FrameBGC=n
Lets you specify the default background color for all frames that use the V6FRAME option.
Valid settings include any number that corresponds to a color in the OpenEdge color table.
WindowSystem
WindowSystem=character-string
Lets you specify the value used by the WINDOW-SYSTEM preprocessor directive. Valid
settings include any character string.
Colors section
The Colors section of the progress.ini file contains options that specify the colors that make
up the color table for use with graphical user interface clients. There are 16 colors available to
an application for use as either foreground or background colors. You can specify up to 256
colors.
Note: Do not change the first 16 colors. These colors are reserved for the Application
Development Environment (ADE) tools. Changing them could cause the OpenEdge
ADE tools to malfunction.
Each entry in the Colors section performs two semantic functions: it defines a color, and it maps
that color to an integer in the range 0 to 255. An application specifies this integer when making
a color assignment to a widget.
4–22
Specify a color entry using the following syntax:
colorn = { R , G , B , | colorname }
An integer from 0 to 255 that specifies the color table entry.
An integer that specifies the amount of red present in the color.
An integer that specifies the amount of green present in the color.
An integer that specifies the amount of blue present in the color.
colorname
Any of the following color names, mapped to the colors defined in the Windows Control
Panel:
COLOR-SCROLLBAR
COLOR-BACKGROUND
COLOR-ACTIVECAPTION
COLOR-INACTIVECAPTION
COLOR-INACTIVECAPTIONTEXT
COLOR-MENU
COLOR-WINDOW
COLOR-WINDOWFRAME
COLOR-MENUTEXT
COLOR-WINDOWTEXT
COLOR-CAPTIONTEXT
COLOR-ACTIVEBORDER
COLOR-INACTIVEBORDER
COLOR-APPWORKSPACE
COLOR-HIGHLIGHT
COLOR-HIGHLIGHTTEXT
COLOR-BTNFACE
COLOR-BTNHIGHLIGHT
COLOR-BTNSHADOW
COLOR-GRAYTEXT
COLOR-BTNTEXT
4–23
Any entries you add to the color table must be sequential. For example, since the installed
progress.ini file defines color0 to color15, the next color you add must be color16. If you add
an entry for color17, OpenEdge ignores it if color16 is undefined.
For backward compatibility, color0 to color15, as installed, are the same as the colors supported
in Version 6. See the chapter about colors and fonts in OpenEdge Development: Programming
Interfaces for a listing of these colors.
For backward compatibility, the progress.ini file specifies the following color pairs for
Version 6 applications:
• NORMAL specifies the colors for fill-ins that do not have input focus.
• INPUT specifies the colors for fill-ins that have input focus.
• MESSAGES specifies the colors for the message area.
NORMAL, INPUT, and MESSAGES each take a pair of integer values from 0 to 255. The integers
represent color table entries. For example, in the default progress.ini file, NORMAL is defined
as foreground equal to color table entry 0 (RGB value 0,0,0) and background equal to color table
entry 15 (RGB value 255,255,255).
The following example shows how to redefine NORMAL as foreground equal to color table entry
3 and background equal to color table entry 12:
NORMAL=3,12
Default Window section
The Default Window section of the progress.ini file specifies the following options for a
graphical user interface client’s default window:
• The location; specify the location as an x,y pixel value.
• The size; specify the size as a number of rows and columns. The default size is 25 by 80.
4–24
Following is a sample Default Window section:
[Default Window]
x=
y=
rows=
columns=
Fonts section
The progress.ini file as installed contains font table entries for the OpenEdge ADE tools.
OpenEdge uses the default system fonts defined in the Startup section, unless you add additional
fonts to the existing font table in the Fonts section.
Note: You can add site-specific fonts to the file. Do not change the first 8 fonts. These fonts
are reserved for the Application Development Environment (ADE) tools. Changing
them could cause the OpenEdge ADE tools to malfunction.
Determine which screen fonts exist in your environment. The fonts you choose should be
graphically compatible. One way to choose fonts is to use the font common dialog box.
The font table can contain up to 256 entries. Each entry in the table performs two semantic
functions: it names a font that exists in your environment and it maps that font to an integer from
0 to 255. An application specifies this integer when making a font assignment to a widget.
Note: You cannot enter extra spaces in the font definition section. Extra spaces will cause the
error 4499.
Specify a font entry using the following syntax:
fontn=typeface, [ size point-size, keyword, ... ],

An integer that specifies the font table entry.
4–25
typeface
point-size
The size of the font, in points. If you omit the point size, OpenEdge uses the default point
size as defined by the typeface.
keyword
scriptname
By default, OpenEdge uses the script (character set) of the Windows FixedSys font for all
fonts specified in the environment. If you select a different script when editing a font using
the font common dialog, OpenEdge writes the specified script name to the font entry.
WinChar Startup section
The WinChar Startup section of the progress.ini file contains options that specify the
following environment characteristics for character clients:
• Default interface attributes
• Default key bindings
The WinChar Startup section also contains OpenEdge environment variables that you can set
for use with character clients. See Table 4–5 in the “Specifying environment variables” section
on page 4–36 for a list of environment variables you can set in the WinChar Startup section.
The WinChar Startup section contains the following options:
BrowseRowMarker
BrowseRowMarker=n
Lets you specify a character to represent a browse row marker. Valid settings include any
number that corresponds to a character in the CPSTREAM character set.
4–26
CursorHeight
CursorHeight=n
Lets you specify the height of a cursor as a percentage. Valid settings include any number
between 0 and 100. This option overrides the UseDosCursor setting.
EnableMouse
EnableMouse={ YES | NO }
Set to YES to enable mouse input. Set to NO to disable mouse input. The default value is YES.
MenuMnemonicColor
MenuMnemonicColor=n
Lets you specify the color of mnemonic characters in menu items. Valid settings include
any number that corresponds to a color in the OpenEdge color table.
SingleLineBorder
SingleLineBorder=n,n,n,n,n,n,n,n
Lets you specify the characters used to draw borders and lines (such as frame borders,
rectangles, submenu and pop-up menu borders, and horizontal and vertical lines). Valid
settings include any eight numbers that correspond to characters in the CPSTREAM character
set, separated by commas.
These eight numbers represent the corners and sides of a rectangle and must be specified
in the following order: top, bottom, left, right, top-left corner, top-right corner,
bottom-right corner, and bottom-left corner.
4–27
SysCheckmark
SysCheckmark=n
Lets you specify a character to represent a selection marker in widgets (such as a selection
list, menu, or browser). Valid settings include any number that corresponds to a character
in the CPSTREAM character set.
UseDosCursor
UseDosCursor={ YES | NO }
Set to YES to change the cursor from an underscore to a solid block when switching from
insert mode to over-strike mode in a fill-in field or editor widget. Set to NO to use an
underscore as the cursor in either mode. The default value is NO.
V6Keys
V6Keys={ YES | NO }
Set to YES to use a set of key bindings that are Version 6 compatible by default. The default
value is NO.
V6FKeys
V6FKeys={ YES | NO }
Set to YES to use the bindings for the CTRL, ALT, SHIFT, and F13 to F39 keys that are
Version 6 compatible by default. The default value is NO.
4–28
WinChar Colors section
The WinChar Colors section of the progress.ini file contains options that specify the colors
that make up the color table for use with character clients.
Each entry in the WinChar Colors section performs two semantic functions: it defines a color,
and it maps that color to an entry in the color table by specifying an integer from 0 to 255. An
application specifies this integer when making a color assignment to a widget.
Specify a color entry using the following syntax:
keyword | colorn = {[ BLINK- ][ BRIGHT- ] fgnd-color | bgndcolor }
keyword | colorn
You can also specify color0, color1, and color2 using the NORMAL, INPUT, and MESSAGES
keywords, respectively. The keyword overrides the colorn specification. That is, if you
specify both colorn and its corresponding keyword, OpenEdge displays the colors you
specified with the keyword.
fgnd-color
The color to use for the screen foreground.
bgnd-color
The color to use for the screen background.
For information about color definitions for the WinChar Colors section, see the Color Phrase
reference entry in OpenEdge Development: Progress 4GL Reference.
WinChar Default Window section
The WinChar Default Window section of the progress.ini file specifies the line mode for a
character client. You can specify 50 rows if your hardware supports 50-line mode. Specify 25
rows if you want the application to be compatible with Progress Version 6 or if you want to port
the application to a character terminal.
The following is an example WinChar Default Window section:
[WinChar Default Window]

rows=25
4–29
WinChar Keys section
The WinChar Keys section of the progress.ini file defines the customized key bindings for
use with character clients. Table 4–2 lists the user-definable key bindings in the Windows
environment. For a complete listing of the Windows key function and key label mappings for
handling user input, see OpenEdge Development: Programming Interfaces.
Table 4–2: User-definable key bindings in Windows (1 of 2)
Key function Key label
APPEND-LINE CTRL-A
BLOCK CTRL-V
BREAK-LINE CTRL-ALT-B
CLEAR F8
COPY F11
CUT F10
DEFAULT-POP-UP SHIFT-F4
DELETE-LINE CTRL-D
END-ERROR ESC
ENTER-MENUBAR F3
FIND CTRL-F
GET F5
GO F1
HELP F2
INSERT-MODE INS
NEW-LINE CTRL-N
NEXT-FRAME CTRL-TAB
PASTE F12
4–30
PREV-FRAME CTRL-SHIFT-TAB
PUT F6
RECALL F7
Specify a key-binding entry using the following syntax:
keyfunction=keylabel [ , keylabel ]
Use a single entry to specify a key binding; additional entries for the same key function are
ignored.
If you specify more than one key label, OpenEdge uses the first when it needs to display a key
label given a key function, as in “Enter data or press Escape to end.”
For example, the following entry maps the Help key function to the F2 key label, and the Go key
function to the F1 key label:
HELP=F2
GO=F1
You can use any combination of CTRL, SHIFT, and ALT keys. However, SHIFT only has an effect
when used with ASCII keys. If an entry contains nonexistent key labels, the entry is ignored.
Note: Set the V6Keys option in the [WinChar Startup] section to enable OpenEdge to use a set
of key bindings that are Version 6 compatible by default.
Debug-Init section
Do not modify information in the Debug-Init section.
4–31
Debug-Macros section
The Debug-Macros section of the progress.ini file contains a list of parameters that define
initial macros used by the Debugger. You can also define your own macros. For more
information, see OpenEdge Development: Debugging and Troubleshooting.
Debug-Buttons section
The Debug-Buttons section of the progress.ini file contains a list of parameters that define
initial buttons used by the Debugger. You can also define your own buttons. For more
information, see OpenEdge Development: Debugging and Troubleshooting.
Keys section
The Keys section is an optional section you can create in the progress.ini file to customize
key bindings for the Windows environment.
Table 4–3 lists the static key bindings in the Windows environment.
Table 4–3: Static key bindings in Windows (1 of 2)
BACKSPACE BACKSPACE
BACK-TAB SHIFT-TAB
CURSOR-DOWN CURSOR-DOWN
CURSOR-LEFT CURSOR-LEFT
CURSOR-RIGHT CURSOR-RIGHT
CURSOR-UP CURSOR-UP
DELETE-CHARACTER DEL
END END
HOME HOME
PAGE-DOWN PAGE-DOWN
PAGE-UP PAGE-UP
4–32
Table 4–3: Static key bindings in Windows (2 of 2)
RETURN ENTER
TAB TAB
Table 4–4 lists the user-definable key bindings in the Windows environment.
APPEND-LINE No default
BLOCK No default
BREAK-LINE No default
CLEAR No default
DEFAULT-POP-UP F4
DELETE-LINE No default
END-ERROR ESC
FIND No default
GET No default
GO F2
HELP F1
INSERT-MODE INS
NEW-LINE No default
NEXT-FRAME F6
PREV-FRAME SHIFT-F6
4–33
PUT No default
RECALL No default
Keymap section
The Keymap section is an optional section you can create in the progress.ini file to define
mappings between standard ASCII (7-bit) characters and extended (8-bit) characters. Extended
characters are typically non-English alphabetical characters. OpenEdge uses these keymap
entries to build a translation table for processing characters in the input and output streams.
Note: Using the Keymap section is the Version 6 technique for mapping characters. Using
conversion tables is a better technique for processing characters. For information about
defining conversion tables, see OpenEdge Development: Internationalizing
Applications.
Use the IN statement, in a keymap entry, to map an ASCII character to an extended character
using the following syntax:
[ MAP-language ]
:IN(\ascii-char)=\extended-char:
language
An identifier that appears with the MAP option.
ascii-char
The 7-bit character, in octal (\nnn) format. You must specify all three digits.
extended-char
The 8-bit character, in octal (\nnn) format. You must specify all three digits.
4–34
Use the OUT statement, in a keymap entry, to map an extended character to an ASCII character
using the following syntax:
[ MAP-language ]
:OUT(\extended-char)=\ascii-char:
You can use multiple IN and OUT statements in a single keymap entry.
If you use extended character sets, you must specify character mappings for each character set
on a per-terminal basis. For example, the following code fragment demonstrates how to map
characters to German language characters:
[MAP-german]
:IN(\102)=\341:
:IN(\101)=\216:
:IN(\141)=\204:
:IN(\117)=\231:
:IN(\157)=\224:
:IN(\125)=\232:
:IN(\165)=\201:
The IN statements in the preceding example map ASCII characters (B, A, a, O, o, U, and u) to
German characters (ß, Ä, ä, Ö, ö, Ü, and ü). When OpenEdge sees the character A (\101) on
input, it converts the character to Ä (\216). Likewise, when OpenEdge needs to send an Ä to the
terminal, it sends [ (\101). The terminal sees A and displays Ä.
Suppose the terminal cannot display an Ä. You can use the OUT statement to specify an
appropriate character to display for Ä, such as capital A. For example:
[MAP-german]
:OUT(\216)=\101:
You can also specify keymap entries for the input and output streams using the MAP option
with each of the following OpenEdge language elements:
• INPUT FROM statement.
• INPUT THROUGH statement.
4–35
• INPUT-OUTPUT THROUGH statement.
• OUTPUT THROUGH statement.
• OUTPUT TO statement.
For more information about these language elements, see OpenEdge Development: Progress
4GL Reference.
Specifying environment variables
Table 4–5 lists the environment variables you can set in either the Startup section or WinChar
Startup section of the progress.ini file.
Table 4–5: Environment variables (1 of 2)
Variable Description Code example
PROPATH A list of directory paths PROPATH=.,C:\Progress\

separated by commas. When OpenEdge
you run a procedure from
within an OpenEdge session
with the RUN statement,
OpenEdge searches for it in the
directory paths defined in
PROPATH in the order listed.
Note: When OpenEdge

encounters a period in
PROPATH (“.,C . . .”), it
substitutes the pathname
of the current directory.
PROMSGS The full pathname of the PROMSGS=

OpenEdge error messages file. C:\Progress\OpenEdge\PROLANG
The default value is \GER\PROMSGS.GER
install-dir\PROMSGS. You
only have to set the PROMSGS
environment variable if you
want to use an error messages
file different from the default
PROMSGS file in the installation
directory.
4–36
Table 4–5: Environment variables (2 of 2)
Variable Description Code example
PROCFG The path name of your PROCFG=C:\Progress\OpenEdge\

product’s configuration file. PROGRESS.CFG
The configuration file is a data
file that identifies the
OpenEdge product and
components that you are
licensed to use. Reset PROCFG if
you have moved the
configuration file from the
directory in which you installed
OpenEdge.
PROSTARTUP The name of the OpenEdge PROSTARTUP=

startup parameter file. The C:\Progress\OpenEdge\startup
default is startup.pf. .pf
DLC The pathname of the directory DLC=C:\Progress\OpenEdge

in which you installed the
OpenEdge system software.
Windows icons for running OpenEdge

The install process places icons in the OpenEdge group on the Windows Explorer desktop and
in the Windows Start menu. The default group name is OpenEdge; however, you can choose
another group name. The icons vary depending on the products installed. Table 4–6 describes
the icons.
Table 4–6: Windows-installed icons
Icon title Icon command line
OpenEdge Client install-dir\bin\prowin32.exe
OpenEdge Run-time Client install-dir\bin\prowin32.exe -rr
OpenEdge Help install-dir\prohelp\filename
OpenEdge Desktop install-dir\bin\prowin32.exe -p _desk.p
OpenEdge AppBuilder install-dir\bin\prowin32.exe -p _ab.p
4–37
On the icon command line, install-dir is the directory where you have installed the products.
See the Windows user documentation for more information about creating additional icons,
copying and modifying existing icons, and general information about the Windows Explorer.
Starting the OpenEdge client

You can start the OpenEdge client using any of the following techniques:
• Choose the icon on the desktop.
• Choose Start→Run from the task bar and enter startup parameters on the command line.
• Click on prowin32 from the Explorer.
Starting the Progress GL client places you in the Progress Procedure Editor with no databases
attached.
Modifying OpenEdge client icons

You can edit the startup command options, including the environment variables, for the default
OpenEdge clients.
To modify startup parameters for a client icon:
1. Select the client icon from the OpenEdge program group and choose File→Properties
from the Windows Explorer, or right-click on the icon and choose Properties from the
pop-up menu. The Properties dialog box appears.
2. From the Shortcut tab, modify the command-line in the Target field. You can supply up
to 259 characters in this field. The command-line limit of 259 characters is still valid for
the expanded version of the command-line text.
3. Choose OK.
You can specify environment variables in the command-line. For example, specifying the
following command runs the PROWIN32 executable located in the path where the %DLC%
environment variable points:
%DLC%\BIN\PROWIN32.EXE
4–38
Maintaining the UNIX user environment

Typically, you create a user-defined startup script to specify environment variable settings in
the UNIX software environment. You can also use the buildenv script. OpenEdge uses the
buildenv script to maintain environment variables that define objects, libraries, and options
required for building executables on UNIX.
You must also maintain the PROTERMCAP file. PROTERMCAP is a terminal definition file that
contains the terminal description for your monitor’s terminal type. OpenEdge uses this file to
determine how to interact with your terminal, console, or terminal emulator.
Maintaining the buildenv script

The buildenv script contains settings for the following types of options:
• Options required by OpenEdge.
• Options required by OpenEdge tools.
• User-defined options.
• Environment variables.
4–39
Figure 4–3 shows an excerpt from a sample buildenv script.
#!/bin/sh
MACHINE="aix"
export MACHINE
UDORA="User Defined"
export UDORA
if [ x$RDL = x -a -f `pwd`/buildenv.log ] ; then
rm -f `pwd`/buildenv.log
fi
ORA_MK=$DLC/oebuild/make/ORA.mk
if [ x$RDL != x ]; then
ORA_MK=$PRGSSRC/project/ORA.mk
fi
# If ORALIB is not set already, attempt to set it

# ORACLE_HOME must be set for the following to work. Error if unset.
if [ "x$ORALIB" = x -a "x$ORACLE_HOME" != x ] ; then
# Execute ('source' into current environment) oralib.sh if it exists.
# (it is assumed to be a Bourne-shell compatible script which, when
# finished, has defined an appropriate value for $ORALIB.
if [ -x $DLC/oebuild/build/oralib.sh ] ; then
. $DLC/oebuild/build/oralib.sh
else
.
.
.
Figure 4–3: Sample buildenv script on UNIX
You can edit this script to customize environments at different sites. The buildenv script is
located in the $DLC/oebuild/make directory. OpenEdge uses the buildenv script to maintain
environment variables that define objects, libraries, and options required for building
executables on UNIX. For more information about building OpenEdge executables, see
Appendix A, “Building OpenEdge 4GL Executables.”
4–40
Maintaining the PROTERMCAP file

The terminal definition file for most character interfaces is called the PROTERMCAP file. This file
is a flat file database that contains the terminal description for your monitor’s terminal type to
inform OpenEdge on how to interact with your terminal, console, or terminal emulator. It
specifies which characters to use to draw boxes, how to write in various video modes (such as
inverse or blinking), how many lines are on the screen, and what actions to perform for each key
on the keyboard.
Note: Make a backup copy of the PROTERMCAP file before making modifications.
Each terminal entry contains the commands and terminal descriptions that OpenEdge uses to
communicate with and control the terminal. Each entry is divided into these logical sections:
• Terminal name.
• Terminal capabilities.
• OpenEdge terminal-specific key functions.
• OpenEdge color table.
• Vermont Views key functions.
• Pointer to key functions.
The PROTERMCAP environment variable (install-dir/protermcap): points to the PROTERMCAP

file.
4–41
The PROTERMCAP file contains a lengthy entry for each terminal type supported by OpenEdge.
Each entry has six parts. Figure 4–4 shows a partial example of each part of a PROTERMCAP entry.
wy370|wyse370|wyse 370 running in native mode:\ Terminal name

: :\
:ct:\
:cm=\E[%i%d;%dH:\ Terminal capabilities
:co#80:\
:li#24:\
:G1=k:
: :\
:GO(F1)=\EOP:\ OpenEdge terminal-specific
:HELP(F2)=\EOQ:\ key functions
: :\
:COLOR 5 RED/BLACK=\E[31;40m:\E[m:\ OpenEdge
:COLOR 6 GREEN/BLACK=\E[32;40m:\E[m: color table
: :\
:ku=\E[A: :L_ku=<Up>:\
:kd=\E[B: :L_kd=<Down>:\ Vermont Views
:kr=\E[C: :L_kr=<Right>:\ key functions
:kl=\E[D: :L_kl=<Left>:\
:kh=\E[E: L_kh=<Home>:\
:tc=v7kf: Pointer to Version 7 key functions
Figure 4–4: Parts of a PROTERMCAP entry
Note: There is a 8,192-byte limit on the size of each PROTERMCAP entry.
The following sections describe PROTERMCAP syntax and each part of a PROTERMCAP entry.
4–42
PROTERMCAP syntax
This section explains the following:
• The general syntax rules that apply when specifying fields in any of the six PROTERMCAP
sections.
• The syntax rules that apply when specifying string values within a field. String values can
occur in the terminal capabilities section, the key bindings section, and the color table
section.
Syntax rules that apply only to specific sections of the PROTERMCAP file are explained in context.
General syntax
A PROTERMCAP entry is a single logical line that contains many fields. The syntax for an entry is
as follows:
• Each field is terminated by a colon (:). (Use the octal equivalent \072 to specify a colon
that is not a terminator.)
• Unless stated otherwise, a field cannot contain embedded separators. Spaces and tabs
improve readability, but they are considered empty fields and must be terminated by a
colon.
• Comment lines begin with a pound sign (#), and can only occur at the beginning and end
of each PROTERMCAP terminal entry (that is, before the terminal name line and after the
pointer to key functions line).
• To enhance readability, the PROTERMCAP file, as installed, contains as many physical lines
as there are fields. Each physical line in the entry contains the following, in the order
listed:
– An empty field consisting of a tab character.
– A field definition.
– A backslash (\).
– A return.
The backslash indicates that the terminal entry continues on the next physical line of the
file. If you need to include a literal backslash in a field, use two backslashes.
4–43
The following code fragment from the entry for the Wyse 370 shows the use of the colon, tab,
space, backslash, and return characters:
wy370|wyse370|wyse_370|wyse 370 running in native mode:\

: :\
:ct:\
:cm=\E[%i%d;%dH:\
:co#80:\
:li#24:\
:G1=k:
: :\
:GO(F1)=\EOP:\
:HELP(F2)=\EOQ:\
: :\
:COLOR 5 RED/BLACK=\E[31;40m:\E[m:\
:COLOR 6 GREEN/BLACK=\E[32;40m:\E[m:
String syntax
Certain fields in the capabilities, key bindings, and color sections are specified using strings.
Strings are typically a combination of command sequences, literal values, and encoded
arguments that tell OpenEdge how to control some aspect of the display.
Table 4–7 show the symbols that are common to all strings. Symbols that are unique to strings
specified in the capabilities, key bindings, or color sections are explained in context.
Table 4–7: Syntax for specifying string values (1 of 2)
Mnemonic Description
\E ESC (ASCII 27)
\n New line
\r Return
\t Tab
\b Backspace
\f Form feed
\999 Octal representation of a character. A colon (:) within a string must be

represented as \072 and a null character as \200.
4–44
Table 4–7: Syntax for specifying string values (2 of 2)
^x CTRL-x, where x represents an appropriate character. For example, ^N

represents CTRL-N.
\^ ^
\\ \
Some terminal types require you to specify a delay period, also called a padding constant, with
certain string capabilities. The delay, in milliseconds, gives the terminal adequate time to
execute the command. Specify this delay as an integer value after the equals sign (=) in a string,
as shown in the following example:
:cm=20\E[%i%d;%dH:\
This tells OpenEdge to wait 20 milliseconds after sending the cursor motion (cm) command
sequence.
You can optionally follow an integer delay value with an asterisk (*) for commands that affect
more than one line of the display. In this case, OpenEdge delays the specified time for each line
affected by the command. However, this significantly degrades performance and usually is not
required.
When you specify proportional delay, you must specify an integer as the delay in a string field.
It cannot have a fractional part; for example, a delay of 1.5* is not valid.
Note: Do not specify a padding constant with the GS, GH, GV, GE, G1, G2, G3, and G4
capabilities.
4–45
Terminal name entries

The first field in each PROTERMCAP terminal entry is the Name field. This field provides the
names known for the terminal. The Name field contains one or more of the following
components, separated by the pipe symbol ( | ):
• An abbreviation of the terminal’s name.
• The common name of the terminal.
• Additional names for the terminal, if any.
• A description of the terminal in which only the last name can contain blanks for readability
(optional).
PROTERMCAP requires at least one of the name entries (1, 2, or 3, above) to be entered without
spaces; the other two, and the description, are optional. See the following examples.
For example:
wy370|wyse370|wyse_370|wyse 370 running in native mode:\
Abbreviation Common Additional Description

name name
Another example of a terminal name entry is:
wy370|wyse 370 running in native mode:\
Abbreviation Description
4–46
Terminal capabilities entries

The terminal capabilities section of a terminal entry contains fields that tell OpenEdge features
of the terminal being used. These entries are indented from the name line to distinguish them
from the terminal name.
Terminal capabilities entries control visual attributes of the terminal: how big the terminal
screen is, how to move to any point on the screen, how to refresh the screen, how to enter/exit
special display modes (reverse, blinking, underline), etc. They also control specific terminal
functions to set up and clean up the terminal properly, so as not to leave a terminal in an
unexpected state (which might leave the terminal unusable).
These entries are the core sequences that OpenEdge uses to communicate with the terminal.
Changing them can cause very unpredictable results and might even cause OpenEdge to put the
terminal in an unusable state. The entries can be changed, but exercise great care in doing so.
Terminal capability entries consist of:
• A two-character mnemonic that identifies a generic terminal capability.
• An assignment operator equal sign (=), or a pound sign (#).
• For certain capability types, a value that allows OpenEdge to understand and interact with
the capability on a specific terminal.
For example:
:ct:\
:cm=\E[%i%d;%dH:\
:co#80:\
:li#24:\
:G1=k:\
Functional listing of terminal capabilities
These are the cursor terminal capabilities that OpenEdge supports:
bc, CF, CN, cm, kd, kl, kr, ku, ke, ks
These are the color/video terminal capabilities that OpenEdge supports:
BB, BR, ct, HS, HR, se, so, ue, us
4–47
These are the graphics character terminal capabilities that OpenEdge supports:
G1, G2, G3, G4, GH, GV, GE, GS
Note: Do not use a padding constant with any of the above graphic strings.
These are miscellaneous terminal capabilities that OpenEdge supports:
co, li, CA, ce, cl, is, Se, Si, te, ti, pc, xi
These are the key translation capabilities that OpenEdge supports:
k0, k1, k2, k3, k4, k5, k6, k7, k8, k9, k0, k. (period), k, (comma), k- (hyphen)
These are the scroll region capabilities that OpenEdge supports:
al, sf, sr, dl, cs
Note: The ce, cl, and cm capabilities are required for OpenEdge to start up.
Vermont Views supports all the capabilities listed here, except ce, te, and ti, and the key
translation capabilities.
Table 4–8 describes the mnemonics that OpenEdge supports.
Table 4–8: Alphabetical listing of capability mnemonics (1 of 4)
Mnemonic Data type Description
al STRING Add line.
bc STRING Backspace character.
BB STRING Enter COLOR 4 mode (usually blink mode).
BR STRING Exit COLOR 4 mode (usually blink mode).
CA BOOLEAN Terminal clears screen with current attribute. If you do

not specify and this capability is available, full-screen
clears with attributes other than NORMAL will be slow.
ce STRING Clear to end of line.
4–48
CF STRING Cursor off.
cl STRING Clear screen. This improves speed. On some terminals,

you must define cl as home cursor followed by clear to
end of screen.
cm STRING Cursor motion.
CN STRING Cursor on.
co INTEGER Columns on screen (usually 80).
cs STRING Change scroll region. Uses cm syntax.
ct BOOLEAN Terminal supports color.
dl STRING Delete line.
G1 STRING Single-line upper-right corner character.
G2 STRING Single-line upper-left corner character.
G3 STRING Single-line lower-left corner character.
G4 STRING Single-line lower-right corner character.
GE STRING Graphics end. Sent when finished drawing box or

underline.
GH STRING Single-line horizontal character.
GS STRING Graphics start. Sent to begin drawing box or underline.
GV STRING Vertical-line graphic character.
HR STRING Exit COLOR 3 mode (usually highlight mode).
HS STRING Enter COLOR 3 mode (usually highlight mode). This is

usually set to high intensity, if available.
is STRING Terminal initialization string. Sent when OpenEdge

starts.
4–49
k0-9 STRING Define the codes sent by the numeric keypad keys if
k. these are different from the codes sent by the standard
k, 0-9, period, comma, and hyphen keys. These are only
k- used by OpenEdge.
kd STRING Down arrow.
ke STRING Exit keypad mode.
kl STRING Left arrow.
kr STRING Right arrow.
ks STRING Set keypad mode.
ku STRING Up arrow.
li INTEGER Lines on screen (usually 24).
pc CHARACTER Pad character (defaults to null).
Se STRING String to send when OpenEdge terminates (after te).
se STRING Exits COLOR 2 mode, or MESSAGE color (usually reverse

video).
sf STRING Scroll forward. You can use this on terminals that have
scrolling regions (for example, terminals with cs and sr
defined).
Si STRING String to send when OpenEdge starts (after is).
so STRING Enter COLOR 2 mode, or MESSAGE color (usually reverse

video). OpenEdge uses this attribute by default for the
two-line message area at the bottom of the screen. It is
also the default for the PROMPT-FOR color of selectable
widgets (that is, buttons, sliders, toggle-boxes, etc.). If
not set and the PROMPT-FOR color of a widget is not
explicitly set in the 4GL, a widget might not be visible.
sr STRING Scroll reverse.
te STRING Cursor movement string to send when OpenEdge

terminates.
4–50
ti STRING Cursor movement string to send when OpenEdge starts.
ue STRING Exit COLOR 1 mode, or INPUT color.
us STRING Enter COLOR 1 mode, or INPUT color (usually the

underline attribute). OpenEdge uses COLOR 1 as the
default PROMPT-FOR color for fill-ins and editors. If
COLOR 1 is not defined by the us and ue capabilities, and
the PROMPT-FOR color for fill-ins and editor widgets is
not explicitly set in the 4GL, these widgets might not be
visible, and there might be no indication they are
enabled.
ws BOOLEAN Uses the device /dev /tty for the current port to
determine the number of columns and rows for the
terminal. Meaningful primarily for emulated terminals
in a windowing system (that is, xterm). If successful,
overrides co and li; otherwise, defaults to co and li.
OpenEdge will not automatically resize if the size of the
terminal changes after initialization.
xi BOOLEAN Terminal will not automatically do a hardware scroll

when the last position (last row and last column) on the
screen is written to. Specify whether available,
otherwise OpenEdge will not write to the last position in
order to avoid the automatic scrolling.
There are four types of terminal capability fields: BOOLEAN, NUMERIC, CHARACTER, and STRING.
Table 4–9 summarizes the four data types and the operators used in conjunction with each.
Boolean fields are specified by a mnemonic abbreviation only. The mnemonic indicates that the
feature is present and its absence indicates that the feature is not present. All other capabilities
take a value. The value can be a string, a character, or a numeric value.
4–51
Table 4–9: Data types and operators
Data type Operator
BOOLEAN none
NUMERIC # and value
CHARACTER = and character
STRING = and string
The following code fragment from the terminal entry for the Wyse 370 terminal shows how to
specify BOOLEAN, NUMERIC, CHARACTER, and STRING capabilities:
:ct:\
:cm=\E[%i%d;%dH:\
:co#80:\
:li#24:\
:G1=k:\
In this example, the mnemonic ct is a Boolean switch that indicates that the terminal supports
color. The mnemonic cm specifies cursor motion and takes a string. The assignment operator
for string values is an equals sign (=). The mnemonics co and li specify the number of columns
and lines on the display and each takes an integer. The assignment operator for integer values
is a pound sign (#). The mnemonic G1 specifies the upper-right corner line-graphic character
and takes a character. The assignment operator for character values is an equals sign (=).
Vermont Views key function capabilities

Certain programs, such as the install program, use a character interface library called Vermont
Views for character input. Vermont Views does not use the OpenEdge Key Function syntax of
keyfunction(label)=sequence. Instead, it uses key function and key label capabilities. Except
for bc, ku, kd, kl, and kr, these key function capabilities are unique to Vermont Views. The key
label capabilities mnemonics are created from the key function capabilities mnemonics by
prepending “L_”. Because both OpenEdge and Vermont Views use only the first instance of a
capability, each key function capability can represent only one key label.
4–52
For readability, the Vermont Views section of an entry has two distinct columns:
• The first lists the key function capabilities.
• A list of the matching key label capabilities. The label in this column always starts
with “L_”.
Here is an example:
:ku=\E[A: :L_ku=<Up>:\
:kd=\E[B: :L_kd=<Down>:\
:kr=\E[C: :L_kr=<Right>:\
:kl=\E[D: :L_kl=<Left>:\
:kh=\E[E: :L_kh=<Home>:\
Vermont Views Labels

mnemonics
Note: For readability in the PROTERMCAP file, the bc, ku, kd, kl, and kr capabilities are usually
repeated in the Vermont Views part of the file, even though both OpenEdge and
Vermont Views use these capabilities as they appear earlier in the OpenEdge capabilities
part. To avoid confusion, the key sequences for the Vermont Views capabilities should
be the same as the OpenEdge capabilities.
Table 4–10 summarizes the Vermont Views key function capabilities mnemonics.
Table 4–10: Vermont Views key function mnemonics (1 of 2)
kh Home (beginning of line, then beginning of page).
EN End (end of line, then end of page).
PU Page up.
PD Page down.
ki Insert toggle.
DL Delete character.
4–53
Table 4–10: Vermont Views key function mnemonics (2 of 2)
ESC Exit current form.
bt Back tab.
fk0 Function Key 1.
fk1 Function Key 2 (contents).
fk2 Function Key 3 (enter the menu bar, then exit the menu bar).
fk3 Function Key 4 (exit current form).
fk4 Function Key 5 (browse backward).
fk5 Function Key 6 (browse forward).
fk6 Function Key 7 (go back through hypertext links).
fk7 Function Key 8 (bring up search dialog box).
fk8 Function Key 9.
fk9 Function Key 10.
Aka Browse backward.
Akd Browse forward.
Aki Exit current form.
Akp Go back through hypertext links.
Aks Bring up search dialog box.
Aku Menu bar.
Akw Contents.
4–54
Pointer to key functions

The last line of every terminal entry is a pointer to the OpenEdge key functions. These key
functions are common to all terminal types and are used by OpenEdge to map certain key
functions with certain control sequences, for example, :FIND (CTRL-F) = ^F:. This pointer
always appears as follows:
tc=v7kf:
If you modify or create new PROTERMCAP entries, be sure to include this line as the last line in
the entry. This line ensures that the terminal entry can support Progress Version 7 and later.
If you want to use Version 6 mappings with Progress Version 7 and later, change the pointer as
follows:
tc=v6kf:
Specifying colors
You specify colors in the OpenEdge terminal-specific key functions and capabilities section of
PROTERMCAP. You can specify up to 123 color fields in a terminal entry. This manual refers to
the color specifications as the color table.
Each line in the table performs two semantic functions: it defines a foreground/background
color pair and it maps that color pair to an integer from 5 to 127. The integer is how an
application references the color pair when making color assignments to a widget. (An
application typically assigns two color pairs to a widget: one for display mode and another for
prompt mode.)
Use the following syntax to specify a color field in a PROTERMCAP terminal entry:
COLOR color-number [color-name]=start-sequence:stop-sequence:
color-number
An integer from 5 to 127 that specifies the location of the color in the color table. The color
number is the mechanism used to assign a color pair in an application.
4–55
color-name
The name of the color. You can use any color value except a OpenEdge keyword.
Although this is optional, including a name makes the color section of the terminal entry
self-documenting (you cannot embed comments) and also makes the color specifications
backwardly compatible.
start-sequence
The character sequence that starts the color attribute.
stop-sequence
The character sequence that stops the color attribute.
For example, the following fields from the Wyse 370 terminal define color table locations
5 and 6:
COLOR 5 RED/BLACK=\E[31;40m:\E[m:\
COLOR 6 GREEN/BLACK=\E[32;40m:\E[m:\
OpenEdge reserves color table locations 0 to 4 as follows:
• Color 0 holds the Version 6 color NORMAL, which is set by the terminal initialization (is)
field.
• Color 1 holds the Version 6 color INPUT and is set and cleared by us and ue. As installed,
this is underline mode.
• Color 2 holds the Version 6 color MESSAGE and is set and cleared by so and se. As installed,
this is reverse-video.
• Color 3 holds the colors used for high intensity and is set and cleared by HS and HR.
• Color 4 holds the colors used for blink and is set and cleared by BB and BR.
Note: The PROTERMCAP file, as installed, does not support spacetaking (embedded attribute)
terminals. These are terminals that use characters on the display to hold control codes for
video and color capabilities. If you add support for such terminals, OpenEdge ignores
the capability when displaying the interface.
4–56
Specifying the cursor motion capability

The absolute cursor-motion (cm) capability allows OpenEdge to move to any row and column
on the display. The capability takes a string that is composed of two parts:
• Control characters
• Two conversion specifications
The conversion specifications allow OpenEdge to convert an integer row value and an integer
column value into the arguments the terminal expects.
The cm string syntax is exactly the same as that used in the standard UNIX termcap file, in
which the conversion specifications follow the pattern of the UNIX printf() command. Table
4–11 lists the supported conversion specifications, each of which begins with a percent sign
(%).
Table 4–11: Syntax for specifying cursor motion string value (1 of 2)
%d Send the integer to the terminal in ASCII format.
%2 Pad the value with a leading blank if it is only one digit.
%3 Pad the value with up to two leading blanks.
%. Treat the value as an ASCII character value.
%+x Value += x, then does a %.
%>xy If value > x, then value +=y; no output.
%r Reverses the order of row and column; no output.
%i Allows row and column values based on a zero origin to be incremented

by one to make them appropriate for terminals whose origin is at (1,1).
%% Gives a single %.
%n Exclusive OR row and column with 0140.
%B BCD (16*(value/10)) + (value%10); no output.
%D Reverse coding (value - 2*(value%16)); no output.
4–57
Table 4–11: Syntax for specifying cursor motion string value (2 of 2)
%x Gives a two-byte, zero-padded, hex value as in the “%0.2x” format for the
UNIX printf() function.
%M This conversion specification is not similar to any UNIX printf() format.

%Mx%Mx translates to:
p1 = row / x + x
p2 = row mod x + x
p3 = col / x + x
p4 = col mod x + 2x
where p1 through p4 are sent to the terminal as characters.
The following example is the cursor motion field for the wyse 370 terminal:
:cm=\E[%i%d;%dH:\
• \E[ — The standard ANSI console lead-in sequence (Escape, followed by a left square
bracket). OpenEdge transmits this literally.
• %i — Instructs OpenEdge to add one to the row and column values to compensate for a
terminal whose origin is 1,1.
• %d — Instructs OpenEdge to send the row and column values to the terminal in ASCII
format.
• ; — Separates the row value from the column value.
• H — A terminating character.
To create a cm string for a new terminal type, find the description of this capability in your
terminal’s documentation to determine the control characters and the arguments it expects to
move the cursor to a random spot on the display. The documentation specifies an algorithm for
converting a row/column integer pair to the arguments it needs. The manual also specifies the
order in which the row and column values are expected (typically row first), and the character
to use to separate the two values. For example, to move to column 65, row 66, a terminal might
expect the characters A and B, which have ASCII values of 65 and 66, respectively.
4–58
Specifying keyboard mappings

The PROTERMCAP file maps key functions to key labels. Table 4–12 shows the mappings as
installed. Many of the mappings shown are terminal specific, and certain terminals might not
support the function for a particular sequence given in the table.
Table 4–12: OpenEdge PROTERMCAP key functions (1 of 6)
UNIX
Key function key label
ABORT CTRL-\
CTRL-ALT-DEL
APPEND-LINE CTRL-A
BACKSPACE BACKSPACE
CTRL-H
DEL-CHAR
BACK-TAB BACK-TAB
CTRL-U
SHIFT-TAB
BELL BELL
CTRL-G
BLOCK SELECT
CTRL-V
BOTTOM-COLUMN ESC-CTRL-B
BREAK-LINE ESC-B
CANCEL-PICK ESC-CTRL-X
CHOICES ESC-CTRL-H
CLEAR F8
CTRL-Z
CLOSE ESC-Z
COMPILE ESC-P
4–59
UNIX
COPY F11
ESC-C
CURSOR-DOWN CURSOR-DOWN
CTRL-J
CURSOR-LEFT CURSOR-LEFT
CTRL-O
CURSOR-RIGHT CURSOR-RIGHT
CTRL-L
CURSOR-UP CURSOR-UP
CTRL-K
CUT F10
ESC-X
DEFAULT-POP-UP ESC-U
DELETE-CHARACTER DEL
DELETE-COLUMN ESC-CTRL-Z
DELETE-END-LINE ESC-K
DELETE-FIELD ESC-CTRL-D
DELETE-LINE REMOVE
CTRL-D
DELETE-WORD ESC-D
EDITOR-BACKTAB CTRL-B
EDITOR-TAB CTRL-G
END END
ESC ->
ESC-.
4–60
UNIX
END-ERROR F4
PF4
ESC
CTRL-E
ENTER-MENUBAR F3
PF3
ESC-M
EXIT ESC-Q
FIND CTRL-F
FIND
FIND-NEXT ESC-F
FIND-PREVIOUS ESC-I
GET F5
ESC-O
GO F1
PF1
CTRL-X
DO
GOTO ESC-G
HELP HELP
F2
ESC-?
PF2
HOME HOME
ESC-H
ESC-h
ESC-<
ESC-,
INSERT-COLUMN ESC-CTRL-N
INSERT-FIELD ESC-CTRL-G
4–61
UNIX
INSERT-FIELD-DATA ESC-CTRL-F
INSERT-FIELD-LABEL ESC-CTRL-E
INSERT-MODE INS
F9
CTRL-T
CTRL-@
LEFT-END ESC-LEFT-ARROW
MAIN-MENU ESC-CTRL-M
MOVE ESC-CTRL-V
NEW ESC-N
NEW-LINE INSERT-HERE
CTRL-N
NEXT-ERROR ESC-E
NEXT-FRAME ESC-CTRL-I
NEXT-WORD CTRL-W
OPEN-LINE-ABOVE ESC-L
OPTIONS ESC-CTRL-O
PAGE-DOWN PAGE-DOWN
ESC-CURSOR-DOWN
ESC-DOWN-ARROW
NEXT-PAGE
NEXT-SCRN
PAGE-LEFT ESC-W
PAGE-RIGHT ESC-Y
ESC-CTRL-J
PAGE-RIGHT-TEXT ESC-CTRL-J
4–62
UNIX
PAGE-UP PAGE-UP
ESC-CURSOR-UP
ESC-UP-ARROW
PREV-PAGE
PREV-SCRN
PASTE F12
ESC-V
PICK ESC-CTRL-P
PICK-AREA ESC-CTRL-W
PICK-BOTH ESC-CTRL-Q
PREV-FRAME ESC-CTRL-U
PREV-WORD CTRL-P
PUT F6
ESC-S
RECALL F7
CTRL-R
REPLACE ESC-R
REPORTS ESC-CTRL-A
RESUME-DISPLAY CTRL-Q
RETURN RETURN
CTRL-M
RIGHT-END ESC-CURSOR-RIGHT
ESC-RIGHT-ARROW
SAVE-AS ESC-A
SCROLL-LEFT ESC-CTRL-L
SCROLL-MODE ESC-T
4–63
UNIX
SCROLL-RIGHT ESC-CTRL-R
SETTINGS ESC-CTRL-@
STOP CTRL-C
CTRL-BREAK
STOP-DISPLAY CTRL-S
TAB TAB
CTRL-I
TOP-COLUMN ESC-CTRL-T
Using key function syntax
To change any of these mappings or create new ones, use the following syntax:
keyfunction(key-label) = sequence:
keyfunction
The name of a key function.
key-label
The key label as it appears on the keyboard.
sequence
The characters transmitted when the key is pressed.
As in other sections of the PROTERMCAP file, string values are assigned using an equal sign
(=) and the field is terminated with a colon (:).
For example:
RECALL(F7)=^AF\r:
4–64
This field in a PROTERMCAP terminal entry defines the F7 key as transmitting a CTRL-A followed
by a capital F followed by a carriage return, and associates use of F7 with the RECALL function.
The following field defines SCROLL-DOWN to act like PAGE-DOWN:
PAGE-DOWN(SCROLL-DOWN)=\021:
If you assign the same key label to two or more different key functions, you get a warning
message when you start OpenEdge. For example, “You cannot use DELETE for both
DELETE-CHARACTER and BACKSPACE.”
If you use a key in the Progress ON statement or GO-ON option only, and do not have to assign it
to a standard action, then use the following syntax in the PROTERMCAP entry:
(key-label)=sequence:
For example, the following entry indicates that pressing F16 sends a capital O followed by a
carriage return:
(F16)=O\r:
If any of the control code sequences sent when you press a key on the keyboard begin with a
control key, you cannot use that control key on your keyboard and the key does not have its
normal OpenEdge meaning. For example, if you specify CTRL-F in a control code sequence
when creating a key mapping, you can no longer use CTRL-F for FIND. You have to map another
key to the FIND action.
The key labels that the UNIX stty command specifies for FLUSH and SUSPEND override the
PROTERMCAP file’s use of the same key labels. For example, if the stty settings for FLUSH and
SUSPEND are CTRL-Q and CTRL-S, you cannot map these key labels to key functions in the
PROTERMCAP file. If you do, you receive no warning; the labels assume their stty meanings at
run time and OpenEdge ignores them.
UNIX stty control functions
The installed PROTERMCAP file does not map the Progress functions ABORT, STOP, and UNIX-END
to key labels. OpenEdge instead uses the key labels that the UNIX stty command specifies for
QUIT, INTR and EOF respectively.
4–65
For example, the following stty command specifies that OpenEdge should use CTRL-\ for
ABORT, CTRL-C for STOP, and CTRL-D for UNIX-END:
stty quit ^\ intr ^C eof ^D
The labels specified by the stty command are of two forms: either CTRL-X or DEL if the
DELETE key (octal 177, decimal 127) is used. When entering the stty command, indicate the
control character by holding down the CTRL key and pressing the specified key; you do not type
a caret (^) followed by the key.
If an entry in the PROTERMCAP file uses one of the key labels specified in the stty command, you
get a warning message when you start OpenEdge. For example, if the stty command specifies
the DELETE key for the STOP function and the PROTERMCAP file specifies the DELETE key for the
DELETE-CHARACTER function, you receive a warning message.
In UNIX environments that do not use the Bourne shell (for example, the Korn shell or C shell),
job control allows you to end a job currently executing on a terminal. In most environments this
is initiated using CTRL-Z; however, OpenEdge uses this character sequence to clear the editor.
Extended character support entries

You can define mappings between standard ASCII (7-bit) characters and extended (8-bit)
characters in the PROTERMCAP file. Extended characters are typically non-English alphabetical
characters. OpenEdge uses these mappings to build a translation table for processing characters
in the input and output streams.
If you use extended character sets, you must specify character mappings for each character set
on a per-terminal basis. For example, the following code fragment from the PROTERMCAP file
demonstrates how to map characters on the Wyse 60 keyboard to German language characters:
ger|german|wy60 in german mode:\

:IN(\102)=\341:\
:IN(\101)=\216:\
:IN(\141)=\204:\
:IN(\117)=\231:\
:IN(\157)=\224:\
:IN(\125)=\232:\
:IN(\165)=\201:
4–66
The IN statements in the preceding example map ASCII characters (B, A, a, O, o, U, and u) to
German characters (ß, Ä, ä, Ö, ö, Ü, and ü). When OpenEdge sees the character A (\101) on
input, it converts the character to Ä (\216). Likewise, when OpenEdge needs to send an Ä to the
terminal, it sends [ (\101). The terminal sees A and displays Ä.
Suppose the terminal cannot display an Ä. You can use the OUT statement to specify an
appropriate character to display for Ä, such as capital A. For example:
:OUT(\216)=\101:
The IN and OUT statements express both the ASCII character and the extended character in octal
(\nnn) format.
Given the appropriate PROTERMCAP file entries for a language and terminal, set the TERM
environment variable to terminal/language (for example, TERM=wy60/german).
You can also specify character mappings for the input and output streams using the MAP option
with each of the following Progress language elements:
• INPUT FROM statement.
• INPUT THROUGH statement.
• INPUT-OUTPUT THROUGH statement.
• OUTPUT THROUGH statement.
• OUTPUT TO statement.
For more information about these language elements, see OpenEdge Development: Progress
4GL Reference.
Creating a PROTERMCAP entry

On UNIX, if OpenEdge does not support your terminal or you need to modify the PROTERMCAP
entry for your terminal, refer to the programming documentation from your terminal’s
manufacturer. It should specify the appropriate commands, values, and key sequences that
OpenEdge needs to interact with your terminal.
If you need to create a new PROTERMCAP entry, first check the /etc/termcap file for an entry for
your terminal. The /etc/termcap file is the standard terminal definition file used by several
UNIX system programs, such as the vi editor. This file is usually provided with UNIX.
4–67
If this file contains an entry for your terminal, copy this entry to the PROTERMCAP file. Use this
file as a starting point to build an entry for your terminal in the PROTERMCAP file.
If your version of UNIX uses a personal termcap called terminfo, you must modify the
terminfo keywords to match the PROTERMCAP capability mnemonics described in the preceding
sections.
Testing terminal entries

If you left any required specifications out of the PROTERMCAP file, when you run OpenEdge you
will receive an error message. Once in the Progress Procedure Editor, try some operations, such
as insert line, delete line, insert character, delete character, and scroll up/down. Also run
procedures that require data entry and display messages in the message area. To fully test the
terminal:
• Go into the Progress Procedure Editor.
• Test to see that the key-functions and key-labels work.
• Test to see that colors are working correctly on widgets and frames.
• Test the output to terminal paged to test scrolling capabilities.
Setting up the terminal

Use your terminal’s setup mode to synchronize the terminal with the color and key code
definitions in its PROTERMCAP entry.
OpenEdge supports terminals based on definitions of their characteristics stored in a file called
the PROTERMCAP file. The PROTERMCAP file supplied with OpenEdge has built-in definitions for
many terminals. If your terminal is not included in the PROTERMCAP file supplied with
OpenEdge, you must make modifications to that file. OpenEdge uses the shell variable or
logical PROTERMCAP to find the PROTERMCAP file. By default, OpenEdge looks for this file
whenever you start the software in a character environment.
4–68
Setting the terminal type

Use the appropriate command in Table 4–13 to make a new terminal type the current terminal
type. The commands assume that the name of the new terminal type is my_term_type.
Table 4–13: Setting the terminal type
Operating
system Command Environment
UNIX (Bourne shell) TERM="my_term_type"; export In .profile or at the shell

TERM prompt
UNIX (C shell) setenv TERM "my_term_type" In .profile or at the shell

prompt
Alternately, you can change the terminal type from within a Progress program with the
following Progress statement:
TERMINAL = termid
See the TERMINAL Function reference entry in OpenEdge Development: Progress 4GL
Reference for more information.
Note: Terminal names are case sensitive.
4–69
Setting the PROTERMCAP environment variable

If you create a new PROTERMCAP file, store it in the current working directory. Then set the
PROTERMCAP environment variable, using the appropriate command from Table 4–14, to allow
OpenEdge to use the new file.
Table 4–14: Setting the PROTERMCAP environment variable
Operating system Command
UNIX (Bourne shell) PROTERMCAP=protermcap; export PROTERMCAP
UNIX (C shell) setenv PROTERMCAP protermcap
Reverting to the default PROTERMCAP file

Use the appropriate command in Table 4–15 at the operating system prompt to go back to using
the default PROTERMCAP file.
Table 4–15: Reverting to the default PROTERMCAP file
Operating system Command
UNIX (Bourne shell) unset PROTERMCAP
UNIX (C shell) unsetenv PROTERMCAP
Copying an existing terminal entry

Use the tc (terminal copy) command when you are defining a new terminal entry that is similar
to an existing entry. The command appends the specifications for the similar terminal to the new
entry, so you do not have to retype the similar information.
The tc command takes a string, as shown in the following example:
:tc=terminal-name
4–70
Follow these guidelines when using the tc command:
• To override a capability in the copied entry, specify the capability in the new terminal’s
entry. Commands specified first always override those specified later.
• To suppress the inclusion of a capability that you do not want to specify in the new
terminal’s entry, specify only the mnemonic, followed by an at symbol (@) in the new
terminal’s entry. This tells OpenEdge to ignore the capability when it reads it from the
similar terminal.
• You cannot use the Version 6 PROTERMCAP in Version 7 or later. You can edit the
PROTERMCAP to use the Version 6 key bindings by editing the following line at the end of
the file:
:tc=v7kf {change to} :tc=v6kf
• Make tc the last field in the terminal entry.
• Place the similar terminal entry in the PROTERMCAP file before entries that reference it.
• The combined length of all the definitions must be less than 8,192 bytes.
For example, the following code fragment is a terminal entry for a Wyse 370 in 132 column
mode. The entry specifies the name of the terminal, a terminal initialization sequence, the
number of columns, and then uses tc to append the specifications for the Wyse 370 terminal:
wy370-132:Wyse 370 in 132 column mode:\

:is=\E[?3h\E[90;1"p\E(B\E)0\E[63;0w:\
:co#132:
:tc=wy370:
4–71
4–72
5
Managing Client Performance
On client systems, OpenEdge consumes system resources to execute Progress 4GL procedures,
store variables and record buffers, sort records, and store temporary files. When managing client
performance, be aware of key performance factors such as procedure loading and execution,
temporary file I/O, and sorting I/O. In addition to these factors, application design and coding
can significantly affect client performance. For information about this topic, see OpenEdge
This chapter provides information about the following topics:
• Procedure loading and execution
• Distributing OpenEdge files on a network
• Temporary file I/O
• Sorting I/O
Procedure loading and execution

R-code is the intermediate binary code that the Progress Compiler generates when it compiles
4GL source files. This is the code that OpenEdge actually runs when it executes a procedure,
whether from session compiles or from permanently generated r-code (.r) files. Execution of
r-code can affect client performance. This section describes r-code and the performance options
related to it. For information about r-code features and functions, see Appendix B, “R-code
Features and Functions.”
Using r-code libraries to improve r-code performance

You can organize and store r-code files in a Progress 4GL r-code library. A Progress 4GL 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.
OpenEdge 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. You create r-code libraries by using
the PROLIB utility. For information about using the PROLIB utility to create and manage
r-code libraries, see Chapter 6, “Managing R-code Libraries.”
When loading and executing r-code procedures from operating system files in a directory,
OpenEdge must open and close each file individually. When loading and executing r-code
procedures from standard or memory-mapped libraries, OpenEdge opens only one file—the
library itself—to access all of the r-code files in the library.
When you execute r-code procedures from either a standard library in local memory or a
memory-mapped library in shared memory, you gain the following advantages:
• Faster access to r-code.
• Fewer file open and close operations.
• Less I/O to temporary files.
When you execute r-code procedures from a memory-mapped library in shared memory, you
gain the following additional advantages:
• Even faster access to r-code.
• Requires less memory because multiple clients access the same r-code segments in shared
memory.
5–2
R-code execution environment

OpenEdge provides a dynamic environment for loading and executing r-code procedures from
operating system files, standard procedure libraries, and memory-mapped procedure libraries.
This execution environment consists of the following components:
• Execution buffer — The portion of local memory that OpenEdge allocates and uses to
store the chain of loaded r-code segments for all standard r-code procedures executing in
local memory.
• Session sort file (.srt) — A file that OpenEdge uses to dynamically swap standard r-code
segments in and out of the execution buffer.
• Shared memory buffer — The portion of shared memory that the operating system
allocates and uses to store and execute the r-code segments for all memory-mapped r-code
procedures.
• 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
local or shared memory and usage count information.
• R-code directory — An in-memory table that contains information about all r-code
procedures executing in local or shared memory, including r-code size, usage count,
segment descriptions, and a reference to the segment descriptor table for each segment.
For more information about the r-code execution environment, see Appendix B, “R-code
Features and Functions.”
OpenEdge loads and 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. The following sections provide
an overview of how OpenEdge loads and executes r-code from an operating system file, a
standard procedure library, and a memory-mapped procedure library.
Loading and executing r-code from a file
When loading an r-code procedure from an operating system file in a directory, OpenEdge
opens the r-code file, loads the required r-code segments into local memory, and closes the file.
When executing an r-code procedure from an operating system file, OpenEdge accesses and
executes the r-code segments in the execution buffer in local memory. OpenEdge also swaps
segments to and from the session sort file, as necessary.
5–3
Loading and executing r-code from a standard library
When loading an r-code procedure from a standard library, OpenEdge opens the library file and
loads the required r-code segments into local memory. The library remains open until the end
of your Progress 4GL session or until you remove the library from the PROPATH. When
OpenEdge needs to load an r-code segment for a procedure in that library, it accesses the open
library in local memory. This is much faster than loading the same procedure from an operating
system file.
When executing an r-code procedure from a standard r-code library, OpenEdge accesses and
executes the r-code segments in the execution buffer in local memory. OpenEdge does not swap
r-code segments to the session sort file unless you specify the PROLIB Swap (-pls) startup
parameter. By default, OpenEdge reloads segments from the open library in local memory.
Loading and executing r-code from a memory-mapped library
When loading an r-code procedure from a memory-mapped library, OpenEdge opens the library
and maps it in shared memory where multiple users can access it. The library remains mapped
until the end of your Progress 4GL session or until you remove the library from the PROPATH.
When OpenEdge needs to execute an r-code segment for a memory-mapped procedure, it
accesses the library in shared memory. This is even faster than loading the same procedure from
a standard library.
5–4
Tuning r-code execution
Table 5–1 lists the startup parameters you use to tune the r-code execution environment for a
session.
Table 5–1: Startup parameters for tuning the execution environment
Startup parameter Suggested use
Maximum Memory (-mmax) Use this parameter to set the initial execution buffer
ceiling. The default is 3096K. OpenEdge increases the
execution buffer dynamically as required, but only after
attempting to swap segments to the sort file. To
minimize swapping I/O, increase this parameter.
Directory Size (-D) Use this parameter to set the initial number of r-code
directory entries. OpenEdge can reuse directory entries
for inactive r-code files. However, reusing an entry
requires some overhead. To reduce this overhead,
increase the value of the -D parameter. The default is
100 entries, the minimum is 5 entries, and the maximum
is 500 entries.
Stack size (-s) When you load data definitions for very large tables or
use recursive procedures, you might receive an error
message directing you to increase this parameter. This
parameter changes the size of the stack (an internal
memory area used by Progress program modules).
Nested Blocks (-nb) If memory is severely limited, use this parameter to

limit the maximum number of nested procedure blocks
allowed.
5–5
Tuning standard r-code libraries
Table 5–2 lists the startup parameters you use to tune standard r-code libraries for a session.
Table 5–2: Startup parameters for tuning r-code libraries
Startup parameter Suggested use
PROLIB Memory (-plm) If you have a large standard library or a memory

shortage, use this parameter to allocate a 512-byte cache
for the library’s directory instead of loading the entire
directory into memory. This parameter slows the speed
of library access but increases available memory.
PROLIB Swap (-pls) Use this parameter to allow swapping from a standard
library to a sort file. OpenEdge typically reads
library-stored r-code from the library instead of
swapping to a sort file. However, when storing the
library over a network, swapping to a local sort file
might be faster than accessing the remote library.
If you specify the PROLIB Memory (-plm) and PROLIB Swap (-pls) startup parameters with
memory-mapped libraries, OpenEdge ignores them.
5–6
Monitoring r-code activity

You can monitor execution environment activity by using the startup parameters listed in Table
5–3 to collect usage statistics during a Progress 4GL client session.
Table 5–3: Startup parameters for monitoring r-code activity
Startup parameter Description
Statistics (-y) Collects procedure access and usage statistics throughout the
Progress 4GL session and writes them to an output file (by
default, client.mon in your current working directory). Use
the SHOW-STATS statement at any time during the session to
instruct OpenEdge to write the statistics immediately.
Statistics with CTRL-C Collects the same statistics as the -y parameter, but lets you
(-yc) press CTRL-C as an alternative to executing the SHOW-STATS
statement. Use this parameter if you cannot execute
SHOW-STATS.
Segment Statistics (-yd) Collects r-code segment statistics and writes them to the
client monitor file (by default, client.mon in your current
working directory). It provides a breakdown of an r-code file
by segment type, including the number of segments and its
size. It also summarizes read and write access to the sort file
by segment type and access type, including the number of
times the sort file was accessed and the number of bytes read
from or written to the sort file.
Statistics with Collects procedure call statistics and writes them to an

Cross-reference (-yx) output file (by default, proc.mon in your current working
directory). Use this parameter to answer these questions:
• How many calls were made in a given period of time?
• How long did a procedure spend executing?
• How often was a procedure swapped to and from the
sort file?
5–7
Interpreting r-code usage statistics
Figure 5–1 shows a sample excerpt from the output of the Statistics (-y) startup parameter.
Execution buffer map 17:38:51

Size Name
---- ----
3789 _edit.r
9542 adecomm/_adeload.r
6931 _prostar.r
5087 _login.r
Amount of execution buffer
562 adecomm/_setcurs.r
used by each procedure.
181638 adeedit/_proedit.r
2570 adecomm/_toollic.r
1510 adecomm/_tmpfile.r
2624 adecomm/_kvlist.r
2752 adecomm/_pwexit.r
3279 adecomm/_adehelp.r
Program access statistics: Times Bytes

Reads from temp file: 0 0 Reads and writes to
Writes to temp file: 0 0 the sort file.
Loads of .r programs: 10 217532
Saves of compilation .r’s: 0 0
Compilations of .p’s: 1 2752
Checks of files with stat: 61 0
Memory usage summary: Current Max Used Limit (Bytes)

Stack usage (-s): 60 8264 40960
Local buffer usage: 256 3136 Execution
R-code Execution Buffer: 196688 196688 524288 buffer size.
Segment Descriptors Usage: (numbers)

Max Used: 152 Limit: 480
Figure 5–1: Sample statistics (-y) output
The Reads from temp file and Writes to temp file fields show the amount of swapping to and
from the sort file. Segments are written to the sort file only once. Once swapped, they remain in
the sort file, even when they are reloaded into memory. For this reason, the number of writes is
typically much smaller than the number of reads. If these numbers are relatively high, consider
putting the sort files on a dedicated disk. For more information, see the “Temporary file I/O”
section on page 5–13.
5–8
The R-code Execution Buffer field shows the current size of the execution buffer, the peak
usage during the session, and the current ceiling. Use the data in these fields to determine the
optimal initial ceiling for the execution buffer (that is, the point at which OpenEdge starts
swapping to the sort file). Set this value with the Maximum Memory (-mmax) startup
parameter. For more information, see the “Tuning r-code execution” section on page 5–5.
5–9
Interpreting r-code segment statistics
Figure 5–2 shows a sample excerpt from the output of the Segment Statistics (-yd) startup
parameter.
Per procedure temp file access statistics:

Segment Read/Write Times Bytes
------- ---------- ----- -----
_edit.r
Initial Read 1 1556
Initial Write 1 1556
Action Read 1 1556
Action Write 1 1556
Read and write
E-code seg: 1 Read 4 2032
access to the sort
E-code seg: 1 Write 1 508
file by segment
adecomm/_adeload.r
type and access
Initial Read 1 1556
type.
Initial Write 1 736
Action Read 1 4504
Action Write 1 4504
_prostar.r
_login.r
.
.
.
Per procedure segment information
-----------------------------
File Segment #Segments Total-Size
---- ------- --------- ---------- Breakdown of r-code
_edit.r file by segment type,
Initial 1 1556 including the number
Action 1 736 of segments and their
E-Code: 1 508 total size.
Text: 1 816
.
.
.
Figure 5–2: Sample segment statistics (-yd) output
5–10
The Per procedure temp file access statistics fields show the swap rates for each segment of each
procedure executed during the session. The Per procedure segment information fields show the
number and size of r-code segments in each procedure. Use this information to determine how
your application design is affecting r-code performance. For more information about
application design and r-code performance, see Appendix B, “R-code Features and Functions.”
Distributing OpenEdge files on a network

The performance of OpenEdge on your network depends largely on your hardware
configuration and where you place the following files:
• OpenEdge system files
• Procedure files
• Temporary files
• Log files
Distributing OpenEdge system files

OpenEdge system software files are the executable and support files that run OpenEdge. The
OpenEdge installation procedure places these files in the default installation directory on the
nodes where you install OpenEdge. If you install OpenEdge on a network file server, you can
sometimes improve performance by moving the appropriate system files to the node where they
are executed (application workstation or database server machine). This is often true on TCP/IP
networks running high-speed UNIX workstations and file servers.
Make sure you copy the correct OpenEdge executables for your LAN protocol. Also, make sure
that the operating system on each node knows the new location of the files you copy. Set the
appropriate environment variables to point to that directory.
For operating systems with a PATH environment variable or other standard search list
convention (such as search directories set with the map command in NetWare), be sure that the
local OpenEdge installation directory appears before the file server OpenEdge installation
directory in the search order. You can do this in the startup file for each network node that
receives the OpenEdge system files.
5–11
Distributing procedure files

Procedure files are files that contain Progress source code (.p) or run code (.r). Store procedure
files in those directories that OpenEdge can access most rapidly, preferably on a local hard disk
attached to each application workstation or OpenEdge AppServer machine.
Once you have distributed your procedure files, modify the PROPATH environment variable in
the startup files on each application workstation to include the directory search path that
contains those files. The following example sets the PROPATH environment variable to the
working directory (.) and the \ACCTPAY directory on the C: drive of a Windows workstation:
SET PROPATH=.;C:\ACCTPAY
In Windows, you can use the registry or progress.ini file to set this environment variable. For
more information, see Chapter 4, “Maintaining User Environments.”
Distributing temporary files

Temporary files are the files that OpenEdge creates during a session and deletes at the end of a
session. Because local I/O is usually much faster than network I/O, put temporary files on the
local hard disk or a RAM disk on each application workstation, whenever possible. By default,
OpenEdge stores temporary files in the user’s working directory, whether the working directory
is local or remote. To ensure that OpenEdge stores temporary files in a local directory, either
start each client in a local directory or with the Temporary Directory (-T) startup parameter set
to a local directory.
For more information about temporary files, see the “Temporary file I/O” section on page 5–13.
For more information about the Temporary Directory (-T) startup parameter, see OpenEdge
5–12
Distributing log files

OpenEdge creates the following log files:
• Event log, which contains a history of significant database events, such as OpenEdge
startup and shutdown and system errors. This file always has a .lg extension. Place the
event log file in the same directory as the database file.
• Transaction log, if you are using the two-phase commit feature. The log records two-phase
commit transactions, and uses a .tl extension. The transaction log file belongs on the
same disk as the database.
• OpenEdge AppServer log, if you are using the OpenEdge AppServer option. The log
records OpenEdge AppServer broker and server startup and shutdown information, and it
contains other system messages that are not directed elsewhere with the OUTPUT TO
KEEP-MESSAGES statement. The default location of the AppServer log is the directory
where the application broker starts. For information about moving the AppServer log file,
see OpenEdge Application Server: Developing AppServer Applications.
Temporary file I/O

OpenEdge creates temporary files during each client session. Each operating system has
different temporary files. Table 5–4 describes the temporary files.
Table 5–4: Temporary client session files
File Description
.dbi Stores temporary tables.
.lbi Local before-image file (subtransaction undo).
.pge Edit buffer contents.
.srt Temporary sort space; session compile storage.
.trp Stores Data Dictionary changes until they are saved.
5–13
By default, OpenEdge stores the temporary files in the user’s working directory. Use the
Temporary Directory (-T) startup parameter to specify an alternate location. When a session
ends, OpenEdge deletes these files unless you specify the Save Temp Files (-t) startup
parameter. For more information about the Temporary Directory (-T) and Save Temp Files (-t)
startup parameters, see OpenEdge Deployment: Startup Command and Parameter Reference.
On UNIX, unless you use the Save Temp Files (-t) startup parameter, you do not see the
temporary files in the directory, because they are created unlinked. However, if your system
crashes, the UNIX file system recovery program, fsck, finds the files. This program might then
prompt you to delete the files. If this occurs, delete them.
On Windows, these temporary files are always visible during a Progress 4GL session, but the
file sizes are set to zero. Windows does not record file sizes until files are closed.
Writing to these temporary files creates I/O activity that might slow down client performance.
The amount of temporary file I/O activity varies among applications.
You might find that running a particular procedure results in OpenEdge abnormally terminating
in a way that indicates the hard disk is full. However, when you check the disk immediately
afterward, adequate space is available. One possibility is that temporary files created during a
Progress 4GL session become quite large, taking up disk space as they expand. Since OpenEdge
erases temporary files at the end of a session, they do not appear when you check the disk. Of
the temporary files, the following files are most likely to cause this problem:
• Temp table file (.dbi) — OpenEdge uses this file to store temporary tables. If the
application uses a lot of temporary tables, this file can grow quite large.
• Local before-image file (.lbi) — OpenEdge uses this file to back out of subtransactions
and variable value changes. If the local before-image file becomes too large, the
procedures probably use a lot of subtransactions. Examine the transaction structure of the
application procedures to understand why OpenEdge starts so many subtransactions. For
more information about transaction processing, see OpenEdge Development: Progress
4GL Handbook.
• Session sort file (.srt) — OpenEdge uses this file to dynamically swap r-code segments
in and out of the execution buffer. Use the r-code usage statistics startup parameters to
collect information about I/O to the sort file, as explained in the “Monitoring r-code
activity” section on page 5–7. Using r-code libraries helps reduce the amount of I/O
required to load r-code files. For more information, see the “Using r-code libraries to
improve r-code performance” section on page 5–2.
5–14
If temporary files grow to exceed disk space, change the application to reduce the size of
temporary files, or use the Temporary Directory (-T) parameter to store the temporary files on
a disk with sufficient space to hold the files. To optimize performance, place the temporary files
on a dedicated disk.
Sorting I/O
Table 5–5 lists the startup parameters you use to improve performance when sorting records for
reports and during index rebuild operations.
Table 5–5: Startup parameters for tuning sort performance
Startup parameter Description
Speed Sort (-TB) Increase this parameter to 8K, 16K, or even 31K, particularly
for index rebuild operations. Increasing this parameter
increases memory usage during sorting and index rebuilds. It
also slightly increases disk space usage.
Merge Number (-TM) Increase this parameter to 32 to speed the merge phase of the
sort process (at the cost of increased temporary memory
usage).
5–15
5–16
6
Managing R-code Libraries
A Progress 4GL r-code library is a collection of r-code procedures combined in a single file. It
is similar to an object library in DOS or an archive file in UNIX. However, object libraries and
archive files are used solely for efficient storage. R-code libraries allow you to manage and
execute r-code procedures more efficiently.
• Library overview
• Setting up a library
• Running procedures from a library
• Libraries and PROPATH
• Memory and network considerations
• Using the PROLIB utility
• Code page compatibility

Library overview
contains r-code procedures that execute in shared memory.
When you execute r-code procedures from either a standard library in local memory or a
memory-mapped library in shared memory, you gain the following advantages:
• Faster access to r-code.
• Fewer file open and close operations.
• Less I/O to temporary files.
When you execute r-code procedures from a memory-mapped library in shared memory, you
gain the following additional advantages:
• Even faster access to r-code.
• Requires less memory because multiple users access the same r-code segments in shared
memory.
When loading and executing r-code procedures from operating system files in a directory,
OpenEdge must open and close each file individually. When loading and executing r-code
procedures from standard or memory-mapped libraries, OpenEdge opens only one file—the
library itself—to access all of the r-code files in the library.
The r-code files that you place in a library are called members. OpenEdge opens a library the
first time you run a member procedure from the library. The library stays open until the end of
your Progress 4GL session or until you remove the library from the PROPATH. For more
information about how standard and memory-mapped libraries interact with PROPATH during
a Progress 4GL session, see the “Libraries and PROPATH” section on page 6–9.
For information about monitoring and optimizing r-code execution during a client session, see
Chapter 1, “Progress 4GL Client Deployment Overview.” For more information about r-code
structure and execution, see Appendix B, “R-code Features and Functions.”
6–2
Loading r-code from a file

Figure 6–1 shows the load operation when executing a standard r-code procedure from an
operating system file.
Standard r-code
Execution buffer
in local memory
ADDCUST.R
Client
ADDCUST.R file
process
Sort file
(1 per user)
Load/Reload from disk
Figure 6–1: Loading r-code from a file
As shown in Figure 6–1, when a client process accesses an r-code procedure from an operating
system file, OpenEdge loads the procedure into local memory for that individual client and
executes the segments from local memory. OpenEdge swaps segments to the session sort file,
and reloads segments from the session sort file, as necessary.
6–3
Loading r-code from a standard library

After locating a procedure in a standard library, OpenEdge loads the procedure into local
memory.
Figure 6–2 shows the load operation when executing an r-code procedure from a standard
library.
Standard library r-code
Execution buffer
in local memory
Client APPL.PL
ADDCUST.R
process Llbrary
Load/Reload from local memory
Figure 6–2: Loading r-code from a standard library
As shown in Figure 6–2, when a client process accesses an r-code procedure from a standard
library, OpenEdge loads the procedure into local memory for that individual client and executes
the segments from local memory. OpenEdge does not swap segments to and from the session
sort file unless you specify the PROLIB Swap (-pls) startup parameter. By default, OpenEdge
reloads segments from the open library in local memory.
6–4
Loading r-code from a memory-mapped library

After locating a procedure in a memory-mapped library, OpenEdge loads the procedure by
mapping the library in shared memory where one or more clients can access it.
Figure 6–3 shows the load operation when executing an r-code procedure from a
memory-mapped library.
Memory-mapped library r-code
Shared memory buffer
Client
process
A APPL.PL
ADDCUST.R
Client library
process
B
No Load/Reload from shared memory
Figure 6–3: Loading r-code from a memory-mapped library
As shown in Figure 6–3, when one or more client processes access an r-code procedure in a
memory-mapped library, they access the same segments in shared memory. Because OpenEdge
executes the segments from the mapped library in shared memory (not local memory), no
reloading is necessary. If you specify the PROLIB Swap (-pls) startup parameter with
memory-mapped libraries, OpenEdge ignores it.
6–5
Setting up a library
This section provides step-by-step instructions for setting up a library using the PROLIB utility.
To set up a library:
1. Create the standard library with the PROLIB utility. (All libraries must have a .pl
extension.)
2. Add the r-code files to the library with the PROLIB utility.
3. If you are setting up a memory-mapped library, use the PROLIB utility to generate the
memory-mapped library from the standard library.
4. Place the library in the PROPATH.
For more information about the PROLIB utility, see the “Using the PROLIB utility” section on
page 6–11. For more information about placing libraries in the PROPATH, see the “Libraries
and PROPATH” section on page 6–9.
Running procedures from a library

Whether you run a procedure from an operating system file or library depends on how you
reference it. You can reference a procedure in an operating system file or a library using either
an absolute or relative pathname.
Using an absolute pathname

The most efficient but least flexible way to reference a procedure in an operating system file or
a library is by using an absolute pathname. When you reference a procedure using an absolute
pathname, OpenEdge does not search the PROPATH. It looks for the procedure in the specified
directory.
To run a procedure from an operating system file in a specific directory, reference the procedure
using an absolute pathname. For example:
RUN /usr/appl/addcust.r
6–6
To run a procedure from a library in a specific directory, reference the library and procedure
using an absolute pathname. For example:
RUN /usr/appl.pl<<addcust.r>>
When you reference a procedure in a specific library, you must enclose the member name in
double angle brackets as shown.
Using a relative pathname

The most flexible but least efficient way to reference a procedure in an operating system file or
a library is by using a relative pathname. When you reference a procedure using a relative
pathname, OpenEdge searches the PROPATH.
When you reference a procedure in either an operating system file or an unspecified library
using a relative pathname, OpenEdge searches each directory and library defined in the
PROPATH until it finds the first occurrence of the procedure. For example:
RUN mydir/appl/addcust.r
When you reference a procedure in a specific library using a relative pathname, OpenEdge
searches the PROPATH until it finds the first occurrence of the library. For example:
RUN mydir/appl.pl<<addcust.r>>
When you reference a procedure in a specific library, you must enclose the member name in
double angle brackets as shown.
The most flexible way to find procedures is to specify relative pathnames for all procedures run
in your application. This allows you to put a procedure into a library for production, but
maintain separate procedure and r-code files during development. In a development
environment, either place the library in the PROPATH after your development directories or
omit it from the PROPATH entirely. In a production environment, place the library at or near
the beginning of the PROPATH to avoid long searches.
Note: OpenEdge cannot find procedure files in a library; it can find only r-code files.
6–7
For more information about how libraries interact with PROPATH, see the “Libraries and
PROPATH” section on page 6–9. For more information about the RUN statement, see OpenEdge
Related functions
If a file is in a library, the SEARCH function returns the file’s pathname using the following
syntax:
library-pathname<<member-name>>
For example:
/usr/dictionary/dictionary.pl<<dict.r>>
Other Progress functions make use of this syntax. The LIBRARY function parses the pathname
and returns the name of the library (in this example, /usr/dictionary/dictionary.pl). If the
argument to LIBRARY is not in the form library-pathname<<member-name>>, the LIBRARY
function returns the unknown value (?). This is also true of the MEMBER function, which parses
the pathname and returns the name of the member file (in this example, dict.r).
For more information about the SEARCH, LIBRARY, and MEMBER functions, see OpenEdge
6–8
Libraries and PROPATH

The following rules govern how standard and memory-mapped libraries interact with
PROPATH during a Progress 4GL session:
• The first time you run a member procedure from a standard or memory-mapped library
that is specified in the PROPATH, OpenEdge 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, OpenEdge must open the library. When OpenEdge opens a
standard library, it loads the procedure into local memory. When OpenEdge opens a
memory-mapped library, it maps the library in shared memory.
• When searching through directories and libraries in the PROPATH, OpenEdge 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 4GL 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),
OpenEdge displays an error message and the library remains open until you end your
Progress 4GL session. Otherwise, OpenEdge closes a standard library and unmaps a
• 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 4GL session.
• If you use libraries, OpenEdge accesses r-code files as if you had specified the Quick
Request (-q) startup parameter. That is, OpenEdge 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, OpenEdge reuses the procedure instead
of searching the PROPATH again. For more information about the Quick Request (-q)
startup parameter, see OpenEdge Deployment: Startup Command and Parameter
Reference.
Note: To ensure that all users access the same memory-mapped library in shared memory, each
user must place the library in their PROPATH using the same library pathname.
For more information about running procedures from a library, see the “Running procedures
from a library” section on page 6–6.
6–9
Memory and network considerations

Each library has an internal directory that OpenEdge uses to access member procedures.
OpenEdge loads this directory into memory when it opens the library. The directory stays in
memory until the library is closed.
By default, OpenEdge tries to load the entire directory of each library into memory. In some
cases, you might not have enough available memory to store a library’s entire internal directory.
Use the PROLIB Memory (-plm) startup parameter to limit the size of a standard library’s
internal directory in memory. This parameter allocates a 512-byte cache for a standard library’s
directory. This parameter is especially useful when running in limited memory with several
libraries opened simultaneously. If you specify the PROLIB Memory (-plm) startup parameter
with memory-mapped libraries, OpenEdge ignores it.
If you run OpenEdge over a network and place a standard library on a file server, remote reads
from the library might take longer than reading an r-code procedure and storing it locally in the
session sort file. Use the PROLIB Swap (-pls) startup parameter to store standard library r-code
procedures locally in the session sort file. If you specify the PROLIB Swap (-pls) startup
parameter with memory-mapped libraries, OpenEdge ignores it.
For more information about the PROLIB Memory (-plm) and PROLIB Swap (-pls) startup
parameters, see OpenEdge Deployment: Startup Command and Parameter Reference.
6–10
Using the PROLIB utility

The PROLIB utility allows you to create and maintain standard libraries and generate
memory-mapped libraries. This is the syntax to start the PROLIB utility:
Operating
system Syntax
UNIX
Windows
prolib library-name parameter [ file-name ... ]
[ parameter [ file-name ... ] ... ]
library-name
Specifies the name of an r-code library. The library name must have a .pl extension.
parameter
Specifies what action to take on the library. Table 6–1 lists the parameters and their
descriptions.
Table 6–1: PROLIB utility parameters (1 of 2)
Parameters Description
-create Creates a new standard library.
-makeshared Generates a memory-mapped library from a standard library.
-add Adds files to a standard library.
-replace Replaces files in a standard library.
-delete Deletes files from a standard library.
-list Lists library information such as library name, format, code page,
and file contents.
-extract Extracts files from a standard library. This parameter copies a file
from the library into another file, outside of the library, and gives it
the same name.
-yank Extracts files from a standard library and places them in the current
working directory.
6–11
Table 6–1: PROLIB utility parameters (2 of 2)
Parameters Description
-compress Compresses a standard library by making a copy of it.
-nowarn Suppresses any warning message that might occur during the
operation of the primary parameters. If you add a file to a standard
library with the -add and -nowarn parameters, and the file already
exists in the library, PROLIB replaces the file.
-pf Allows you to supply command-line arguments in a parameter file.

You cannot use -pf in a parameter file.
-verbose Directs PROLIB to display processing information that is ordinarily

suppressed.
-date Specifies the format of the date as it appears when you use the -list
parameter.
When specifying a parameter, you do not have to type the complete parameter name. You
can type the minimally unique string for each parameter (for example, -l for -list and
-e for -extract).
The -nowarn and -verbose parameters modify the behavior of the -create, -makeshared,
-add, -replace, -delete, -list, -extract,and -yank parameters.
You can place the -nowarn, -pf, and -verbose parameters anywhere on the command
line. They affect the processing of all other specified parameters.
You must place the -create parameter before all other parameters. PROLIB processes
parameters in left-to-right order as they appear on the command line. If an error occurs
during the PROLIB command, PROLIB terminates. This behavior occurs so that options
specified later in the command line, which might depend on the failed option, do not
execute.
You cannot use the -add, -replace, -delete, -extract, -yank, or -compress parameters
with a memory-mapped library (that is, when you specify a memory-mapped library in
library-name).
file-name
Specifies the name of an r-code file, or a memory-mapped library file when using the
-makeshared parameter.
6–12
Using wild cards

The -add, -replace, -extract, -list, -delete, and -yank parameters accept wild card
arguments. Wild card arguments can contain only the ? or * wild card characters. Depending on
the parameter you want to use, you must specify these arguments in one of two ways:
• Using your operating system’s regular wild card conventions.
• Escaping the wild cards.
The -add and -replace parameters act on operating system files. PROLIB uses system calls to
copy the files. Thus, when you use these parameters, use your operating system’s standard
conventions to specify wild cards.
The -extract, -list, -delete, and -yank parameters act on files that are already placed in a
library. PROLIB does not use system calls to act on the files, but instead uses its own internal
code. On UNIX, you must escape your wild card arguments by either enclosing them in quotes
(for example, prolib app.pl -delete "sys*.r") or escaping the wild card characters
individually (for example, prolib app.pl -delete sys\*.r). Your operating system might
use different techniques to escape wild cards. In Windows, you do not need to escape wild card
arguments because the operating system does not expand them before passing them to PROLIB.
Creating a standard library

To create a standard library, enter the following command:
Operating
system Syntax
UNIX prolib library-name

Windows -create [ -codepage codepage-name ]
library-name
Specifies the name of the library you want to create.
All libraries must have a .pl extension. You can add libraries to the PROPATH
environment variable by specifying the file’s absolute or relative pathname.
codepage-name
Specifies the name of the code page for the library you want to create.
6–13
A library can contain r-code procedures with different code pages. All r-code procedures
retain their respective code pages.
If you do not specify the -codepage parameter at creation time, OpenEdge marks the
r-code library with the code page specified in the Internal Code Page (-cpinternal) startup
parameter.
For information about code page compatibility, see the “Code page compatibility” section
on page 6–23.
Generating a memory-mapped Library

To generate a memory-mapped library from a standard library, enter the following command:
Operating
system Syntax
UNIX prolib standard-library-name

Windows -makeshared mapped-library-name
standard-library-name
Specifies the name of the standard library from which to generate the memory-mapped
library. The library name must have a .pl extension. You can add libraries to the
PROPATH environment variable by specifying the file’s absolute or relative pathname.
Note: Save the standard library. It is the source of modification for the memory-mapped
library. Each time you modify the standard library you must regenerate the
mapped-library-name
Specifies the name of the memory-mapped library you are generating. The library name
must have a .pl extension.
Note: You cannot modify a memory-mapped library directly. To modify a

memory-mapped library, you must modify its source standard library and
regenerate the memory-mapped library.
6–14
PROLIB generates a memory-mapped library with the standard library’s code page. All text
segments in all r-code procedures retain their respective code pages.
For information about code page compatibility, see the “Code page compatibility” section on
page 6–23.
Adding files to a standard library

To add files to a standard library, enter the following command:
Operating
system Syntax

Windows -add file-name [ file-name ] ...
library-name
Specifies the name of the library where you want to add the file.
file-name
Specifies the pathname of the file. You can add a file to a library by specifying the file’s
absolute or relative pathname.
When you add a file to a library, the library entry for that file retains the entire pathname. For
example, enter a file into a library called newlib.pl using the following command:
prolib newlib.pl -add /usr/apps/proc1.r
The pathname /usr/apps/proc1.r appears in the library’s table of contents. You can display
the library’s table of contents with the -list parameter.
When you extract a file from a library, PROLIB copies the file into the directory specified by
the pathname (in this example, /usr/apps). See the “Extracting files from a standard library”
section on page 6–19 for more information.
If you try to add a file that already exists, PROLIB displays an error message. However, if you
specify the -nowarn parameter, PROLIB replaces the existing file. See the “Replacing files in a
standard library” section on page 6–16 for more information.
6–15
Replacing files in a standard library

To replace one or more files in a standard library, enter the following command:
Operating
system Syntax

Windows -replace file-name [ file-name ] ...
library-name
Specifies the name of the library with the file you want to replace.
file-name
Specifies the name of the file.
When you replace a file, the system overwrites the old file with a file of the same name.
Therefore, the pathname you supply for the file has to be the same as the pathname you used
originally to add the file to the library. If you try to replace a file that does not exist, PROLIB
displays an error message. However, if you specify the -nowarn parameter, PROLIB adds the
existing file to the library. See the “Adding files to a standard library” section on page 6–15 for
more information.
Deleting files from a standard library

To delete files from a standard library, enter the following command:
Operating
system Syntax

Windows -delete file-name [ file-name ] ...
library-name
Specifies the name of the library with the file you want to delete.
file-name
Specifies the name of the file. You can specify more than one file at a time.
6–16
Listing the contents of a library

To list the contents of a library, enter the following command:
Operating
system Syntax

Windows -list [ file-name ] ...
library-name
Specifies the name of the library with the contents you want to list.
file-name
Specifies that PROLIB should list information about that file only; file-name has to be
the same absolute or relative pathname as when you originally add the file. You can
specify more than one file at a time.
Table 6–2 lists the information that appears in the header section of the output.
Table 6–2: List (-list) parameter library information
Information Description
Library Name The name of the library.
Code Page The code page in which the library was created.
Format The format of the library. The valid library formats are STANDARD and
MAPPED.
6–17
Table 6–3 lists the information that appears in the output for each file in the library.
Table 6–3: List (-list) parameter file information
Information Description
Name The name of the file.
Size The size of the file in the library, in bytes.
Type The file type. PROLIB recognizes two file types: R (r-code file type)
and O (any other file type). Although libraries are specifically
designed to hold r-code files, you can place any type of file in them.
Offset The distance, in bytes, of the start of the file from the beginning of the
library.
Modified The date and time of the file’s last modification.
Added To Lib The date and time the file was entered into the library.
You can also change the format of the dates as they appear in the
Modified and Added To Lib fields with the -date parameter, where
date-format is three letters: m (month), d (day), and y (year). To
specify a format, place the letters in the order you want the months,
days, and years to appear on screen. The default is mdy.
6–18
Extracting files from a standard library

To extract files from a standard library, enter the following command:
Operating
system Syntax

Windows -extract file-name [ file-name ] ...
library-name
Specifies the name of the library with the file you want to extract.
file-name
Note: You must create all subdirectories required by a library before trying to extract files from
the library. You can see what directories and subdirectories a library needs by using the
PROLIB -list parameter to view the contents of the library.
When you extract a file from a library, PROLIB copies the file and places it in its original
directory. Depending on how you add a file to a library, PROLIB extracts differently:
• If you added the file by specifying a relative pathname, PROLIB searches your current
working directory for the subdirectory indicated in the pathname. For example, if you
added a file by using the relative pathname apps/proc1.r, PROLIB searches your current
working directory for the subdirectory apps. If the directory does not exist, PROLIB
displays an error message.
• If you added the file by specifying its absolute pathname, PROLIB searches for the
original directory. If the directory does not exist, PROLIB displays an error message.
Note: If you specify the -yank parameter instead of -extract, OpenEdge strips everything but
the filename from the pathname and places the file in your current directory.
6–19
If the file you are extracting (or yanking) already exists in the directory outside of the library,
PROLIB displays the following message:
File file-name already exists. Do you want to replace it?

Please answer ’yes’ or ’no’ or ’rename’ to assign new name:
where file-name is the pathname of the file you are extracting (or yanking). If you answer yes,
PROLIB overwrites the file. If you answer no, PROLIB does not overwrite the file. If you
answer rename, PROLIB displays the following message:
Enter new name to use for extracted file file-name -->
where file-name is the pathname of the file you are extracting (or yanking). After you enter the
pathname, PROLIB gives the file the new pathname and places it in the appropriate directory.
Extracting files to your current directory

When extracting a file with the -yank parameter, PROLIB discards everything but the filename
from the file’s pathname. For example, if you added a file using the pathname
/usr/apps/proc1.r, PROLIB discards /usr/apps from the pathname and places proc1.r in
your current working directory.
To extract files from a library using the -yank parameter, enter the following command:
Operating
system Syntax

Windows -yank file-name [ file-name ] ...
library-name
Specifies the name of the library with the file you want to extract.
file-name
6–20
Compressing a standard library

To compress a standard library, enter the following command:
Operating
system Syntax
UNIX prolib library-name -compress

Windows
library-name
Specifies the name of the library you are compressing. The -compress parameter removes
extra spaces that occur in the library as a result of repeated adds or deletes.
To compress a library, PROLIB creates a temporary file that requires an area of disk space equal
to the size of the compressed library. Before compressing a library, make sure you have enough
disk space for the temporary file. Temporary files have names that begin with the letters PLB,
followed by numbers and possibly letters.
If your system goes down during a compress operation, the temporary file might remain on your
disk. Delete this file to free up disk space. The original library will not be damaged.
Repeated adds create empty spaces in the library over time. To minimize the rate at which these
empty spaces are created, you can use one command instead of many. For example, instead of
entering the following commands:
prolib test.pl -add test.r

prolib test.pl -add test2.r
prolib test.pl -add test3.r
enter this command:
prolib test.pl -add test*.r
You can use the -list parameter to determine how much space in your library is unused.
6–21
PROLIB command examples

This section provides several PROLIB command examples.
The following example creates a standard library called app.pl in your current directory:
prolib app.pl -create
The following example adds all the r-code files in the current directory that begin with the
letters sys to the standard library app.pl. In this example, the r-code files are in a directory, so
the operating system processes the wild card argument:
prolib app.pl -add sys*.r
The following example deletes all r-code files ending with the letters dev from the standard
library app.pl and lists all of the files in the library. In this example, the r-code files are in the
app.pl library, so PROLIB processes the wild card argument. This requires escaping the
*dev.r argument. On UNIX, this means placing quotes around it. Your operating system might
use different techniques to escape wild cards:
prolib app.pl -delete "*dev.r" -list
The following example replaces the files appmenu.r and apprept.r in the standard library
app.pl, then compresses the library to free up unused disk space:
prolib app.pl -replace appmenu.r apprept.r -compress
The following example creates a standard library called app.pl in your current directory, adds
all the r-code files in the current directory that begin with the letters sys to the library app.pl,
and generates a memory-mapped library called app_map.pl:
prolib app.pl -create -add sys*.r -makeshared app_map.pl
6–22
Code page compatibility

The Internal Code Page (-cpinternal) startup parameter determines the internal code page that
OpenEdge 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 session’s internal code page, OpenEdge performs an
in-memory conversion of the r-code text segments to the session’s 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, OpenEdge 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, OpenEdge

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 with the internal code page of the
session in which the r-code runs, OpenEdge 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 OpenEdge Deployment: Startup Command and
6–23
6–24
7
Managing Print Devices
System administrators are responsible for setting up and maintaining the output devices
required by an application. Most OpenEdge applications access printers to print reports or other
output. This chapter provides an overview of how to set up print devices on
OpenEdge-supported operating systems. It also describes how to use OpenEdge to set up and
control output routing and printing characteristics.
• Printing in OpenEdge
• Printing on UNIX
• Printing in Windows
• Setting up output-routing
• Configuring a printer
Printing in OpenEdge
Most operating systems support two general printing techniques: direct printing and spooled
printing. Direct printing sends application output directly to a printer set up on the operating
system. This technique of printing is frequently found on single-user systems. However, you
can use direct printing in other situations (for example, printing tickets and special forms).
Spooled printing sends application output to a temporary file and places a print request in a print
queue set up on the operating system. Spooling permits you to queue a print request and
continue processing; the system executes the print request when a printer becomes available. A
spooled device can help balance the demand on line printers if you are running applications on
a time-shared system.
OpenEdge runs with most printers and, depending on the operating system in use, makes default
assumptions about printer setup. OpenEdge uses the printer port or spooler named at execution
time, not at compile time. Thus, precompiled OpenEdge applications work regardless of the
printer port or spooler in effect.
This section provides an overview of the Progress language elements you can use to direct
application output, which includes the:
• OUTPUT TO statement
• OUTPUT THROUGH statement
7–2
OUTPUT TO statement
By default, all OpenEdge output is directed to the terminal. The OUTPUT TO statement allows an
application to redirect output to other output devices. Following is a partial syntax example of
the OUTPUT TO statement:
OUTPUT [ STREAM stream ] TO

{ PRINTER [ printer-name ]
| opsys-file
| opsys-device
| TERMINAL
| VALUE ( expression )
| "CLIPBOARD"
}
.
.
.
[ PAGED ]
[ PAGE-SIZE { constant | VALUE ( expression ) }]
.
.
.
Use the OUTPUT TO statement with the PRINTER option to send output to the default print device
on the current operating system. For example:
OUTPUT TO PRINTER.
On UNIX, the OUTPUT TO PRINTER statement sends output to the default spooler. To use a
spooler other than the default, start OpenEdge using the Printer (-o) startup parameter.
In Windows, the OUTPUT TO PRINTER statement sends output to the printer defined in default
print context. The default print context is the set of values that defines the default printer and
setup for that printer in Windows. If there is no default print context, OpenEdge uses the printer
control settings from the current environment.
7–3
Use the SYSTEM-DIALOG PRINTER-SETUP statement to display the Windows Print dialog box and
let the user change the default print context at runtime. Use the PRINTER-NAME attribute of the
SESSION system handle to change the printer name in the default print context without user
intervention. You can change the system default printer from the Windows Control Panel.
Use the OUTPUT TO PRINTER statement with its various options to override the default print
context for a specific print job. For example, send output to a printer other than the default
printer by using the following syntax:
OUTPUT [ STREAM stream ] TO PRINTER printer-name
OpenEdge assumes that all printers can handle hard-coded form feed characters (CTRL-L or 0C
Hex). The OUTPUT TO PRINTER statement automatically paginates OpenEdge output on the
default printer. To paginate output on a printer, other than the default printer, use the OUTPUT TO
PRINTER statement with the PAGED or PAGE-SIZE option.
Use the Printer (-o) startup parameter to specify a default printer to use when processing the
OUTPUT TO PRINTER statement in procedures. The specified printer must be set up on the current
operating system.
For a complete description of the OUTPUT TO PRINTER statement, the SYSTEM-DIALOG

PRINTER-SETUP statement, and the SESSION system handle, see OpenEdge Development:
Progress 4GL Reference. For more information about the Printer (-o) startup parameter, see
OpenEdge Deployment: Startup Command and Parameter Reference.
OUTPUT THROUGH statement

The OUTPUT THROUGH statement allows an application to redirect output to a process that
OpenEdge starts. On UNIX, this statement allows you to pipe OpenEdge output to a UNIX
process. Following is a partial syntax example of the OUTPUT THROUGH statement:
OUTPUT [ STREAM stream ] THROUGH

{ program-name | VALUE ( expression ) }
[ argument | VALUE ( expression ) ] ...
.
.
.
7–4
You can also use the OUTPUT THROUGH statement to access spooling capabilities on UNIX
systems. For example, this command sends output to the printer named lw on a UNIX system:
OUTPUT THROUGH lpr -Plw.
For a complete description of the OUTPUT THROUGH statement, see OpenEdge Development:
Progress 4GL Reference.
Printing on UNIX
Since UNIX is a multi-tasking operating system, print devices are usually spooled. However, it
is possible to print directly to a device that is not spooled. This section describes the setup of
spooled print devices on UNIX System V and Berkeley 4.n systems. The default spooler name
for all systems that run UNIX System V is lp. The default spooler name for all other UNIX
systems, including Berkeley 4.n, is lpr.
To set up a printer on a UNIX System V system, make sure that the lp system and the printer
hardware are installed and that the LP scheduler is shut down. The LP scheduler services print
requests for all destinations by routing requests to the interface programs that do the printing on
devices. The LP scheduler is usually started when you boot your system. To shut down the LP
scheduler, use the lpshut command. After you log in as the root user, you can set up a printer
on a UNIX System V system.
To set up a printer on a UNIX System V system:
1. Install and configure a device in the /dev directory. Make sure the device is not configured
as a login terminal.
2. Use the lpadmin command to set up a new printer. This command allows you to specify a
printer name and a printer-interface program, and connects them with a print device that
exists in the /dev directory.
3. Use the lpsched command to start the LP scheduler once the printer has been set up.
4. Use the accept and enable commands to let the printer accept print requests and enable
spooling for the printer.
7–5
To set up a printer on a UNIX Berkeley 4.n system, make sure that the lpr system and the
printer hardware are installed and that the lpd daemon is running. The lpd daemon is the master
server that services print requests and routes them to the proper spooling directories for printing.
The lpd daemon usually starts when you boot your system. After you log in as the root user, you
can set up the printer.
To set up a printer on a UNIX Berkeley 4.n system:
1. Install and configure a device in the /dev directory. Make sure the device is not configured
as a login terminal.
2. Edit the /etc/printcap file. This file contains definitions for all of the printers on a
system (or accessible over a network). Each printer definition in /etc/printcap does the
following:
• Designates a device in the /dev directory as the printer port.
• Designates a spooling directory.
• Sets up printer characteristics.
3. Create the spooling directory and make sure the spooling directory and the directories of
the lpr system have the proper permissions and ownership.
4. Use the lpc start and lpc enable commands to let the printer accept print requests and
enable spooling for the printer.
Most UNIX System V or Berkeley 4.n systems have printer installation scripts that perform the
printer installation steps described in this section.
The OUTPUT TO PRINTER statement sends output to the UNIX system default spooler. To use a
spooler other than the default, start OpenEdge using the Printer (-o) startup parameter followed
by the name of the spooler. For example:
pro database-name -o "lp -dpx1"
7–6
Alternately, you can use the OUTPUT THROUGH statement to direct output to a spooler other than
the default spooler:
OUTPUT THROUGH lp spooler-options PAGED.
or:
OUTPUT THROUGH lpr spooler-options PAGED.
With both the OUTPUT THROUGH statement and the Printer (-o) startup parameter, you can specify
UNIX spooler options for the spooler that you designate. If you want to specify spooler options
with the Printer (-o) startup parameter, surround the spooler name and options with quotes. For
example:
pro database-name -o "lpr -Plw"
For more information about printing on UNIX, see the UNIX system documentation.
UNIX networks and printing

UNIX systems can be integrated into a variety of networks. This section describes how to set
up remote printers using the TCP/IP networks and the Basic Networking Utilities. You can use
both of these protocols to connect UNIX System V and Berkeley 4.n systems.
On TCP/IP networks, remote spooling is handled with two spooling queues, one on the local
machine and one on the remote machine.
To set up remote printers using TCP/IP networks:
1. Be sure that the required TCP/IP system files are set up on both the local and remote
machines. The local and remote machines have entries in their /etc/hosts and
/etc/hosts.equiv files to facilitate network operations.
2. Be sure that the printer is set up on the remote machine.
7–7
3. Define an entry for the remote printer in the /etc/printcap file on the local machine.
This remote-printer entry must have an empty field for the lp capability, a remote machine
designation, a remote printer designation, and a remote spooler directory designation. The
remote printer that you define in the /etc/printcap file can be the default print spooler
for the local machine.
4. Create the spooling directory, then use the lpc start and lpc enable commands to
allow the remote printer to receive print requests and to enable spooling for the printer.
When you initiate a remote print job with lpr, the job is queued locally and a daemon process
is created to oversee the transfer of the job to the remote machine. If the destination machine is
unreachable, the job remains queued until it is possible to transfer the files to the spooling queue
on the remote machine.
To set up remote print spooling using the Basic Networking Utilities:
1. Be sure that the Basic Networking Utilities (uucp) are installed on both the remote and
local machines. The Basic Networking Utilities use a series of files to define network
machines (L.sys), to set up communications mechanisms and characteristics (L.devices
and L-dialcodes), to determine what commands can be executed remotely (L-cmd), and
to set up network permissions (USERFILE). An entry is also required in the /etc/passwd
file on each network machine to allow uucp logins.
2. Be sure that the printer is set up on the remote machine.
3. Create an executable script to use the uux command to enact a print job on the printer
attached to the remote node.
When you use the uux command to execute a remote print job, the network request is queued in
the local uucp spooling directory, permissions are checked, and the request is sent to the remote
machine. The remote machine places the print request in the spooling directory of the printer.
For more information about UNIX networks and printers, see the UNIX system administration
documentation.
7–8
Printing in Windows
In Windows, you can choose either of two printing modes:
• Default mode.
• Windows Passthrough Printing (WPP).
In default mode, OpenEdge uses the Windows device drivers. This mode is sufficient for all
basic printing that does not use any printer access control codes, such as those sent by PUT, PUT
CONTROL, or DISPLAY statements.
In WPP mode, OpenEdge bypasses the Windows device drivers. This means you can send
control codes (such as POSTSCRIPT commands) directly to the printer with the PUT, PUT
CONTROL, or DISPLAY statements. To enable windows passthrough printing for a session, use the
Windows Passthrough Printing (-wpp) startup parameter. You can only use this parameter on
the command line.
You cannot use WPP mode with a POSTSCRIPT printer to print OpenEdge standard reports,
such as those produced by the Data Dictionary.
Note: When using windows passthrough printing under Windows95, you must change the
Spool Data Format from EMF spooling to RAW spooling. Use the Control Panel to
access the Printer Properties for the printer, then select Spool Setting from the Details
tab of the Printer Properties tab. Change the Spool Data Format to RAW spooling.
For a complete description of the PUT, PUT CONTROL, and DISPLAY statements, see OpenEdge
Development: Progress 4GL Reference. For more information about the Windows Passthrough
Printing (-wpp) startup parameter, see OpenEdge Deployment: Startup Command and
7–9
Setting up output-routing
For systems with multiple printers, you might want to set up an output-routing scheme.
Output-routing schemes direct application output to different devices based on criteria that you
specify. Since OpenEdge uses the printer port or spooler named at execution time, not at
compile time, you can set up output-routing schemes to send application output to different
printers based on user identification, the type of procedure the user runs, or some other criteria.
When setting up an output-routing scheme, examine the application and system requirements.
For example, your system users might want to direct output to different printers. In this case,
you would have to set up an output-routing scheme based on the user identification. An
application might have reports that require different types of printers. For example, one report
might require a 132-character printer and another report might require an 80-character printer.
In this case, you would have to set up an output-routing scheme based on the report type.
Another output-routing scheme could direct output to different printers based on both the user
and the type of report.
You can set up an output-routing scheme in the following ways:
• Using a Startup Procedure.
• Using an Output-routing Table.
• Using Interactive Output-routing.
Using a startup procedure

The simplest output-routing scheme consists of setting up an OpenEdge application startup
procedure for each printer on a system. Each startup procedure could contain the Printer (-o)
startup parameter to designate a particular printer as the default printer for the current OpenEdge
session.
7–10
Figure 7–1 shows a sample application startup procedure on UNIX. This application startup
procedure designates lpr -Plw as the default print device for the current OpenEdge session and
starts up an OpenEdge application located in the /usr/appl1 directory that access a database
called appldb.
APPL1=${APPL1-/usr/appl1}; export APPL1

PROPATH=$PROPATH:$APPL1; export PROPATH
PROTERMCAP=$PROTERMCAP-$DLC/protermcap}; export PROTERMCAP
exec $DLC/_progres $APPL1/appldb -p $APPL1/mainmenu.p -o "lpr -Plw"
Includes the application Designates startup parameters for

directory in the PROPATH. the application. The shaded
parameter designates "lpr -Plw" as
Sets up an environment the default print device.
variable that designates the Executes the pro startup script to
location of the application. start up Progress with your
application.
Figure 7–1: Sample application startup procedure (UNIX)
Figure 7–2 shows a sample application startup procedures on NT. This application startup
procedure designates LPT2 as the default print device for the current OpenEdge session and
starts up an OpenEdge application located in the /usr/appl1 directory that access a database
called appldb.
echo off
set APPL1=\usr\APPL1
set PROPATH=%PROPATH%;%APPL1%
%DLC%\_progres -D 20 -o LPT2 -p
\usr\APPL1\mainmenu.p appldb
Figure 7–2: Sample application startup procedure (NT)
After the startup procedures are set up for each system printer, you can designate users to use
different startup procedures depending on which output destination they want. For easy user
access and maintenance, all of the startup procedures should be located in the directory where
the system software is located.
7–11
Using an output-routing table

More complex output-routing schemes, such as routing output based on the user ID, require the
creation of several related Progress 4GL tables and an include file that can access these tables
and select the proper output command for the particular user.
Just as you can use Progress 4GL tables (_User) to set up security for OpenEdge applications,
you can also use Progress 4GL tables for output routing. If you want to route application output
to different printers based on user ID, set up a table in the application database containing each
of the valid user IDs and the corresponding print commands.
Figure 7–3 shows a sample output-routing table.
Usrprnt
userid outdev
george lpr -Pcx1

nancy lpr -Plw
kathy lpr -Pcx1
margie lpr -Pcx2
.
.
Figure 7–3: Sample output-routing table
The database table shown in the figure contains records that have a userid field and an outdev
field containing an operating system output device. The userid field is a unique primary index
for the table. You have to keep the Usrprnt table up to date with a record for each new user on
your system.
7–12
After setting up the database table, create an include file that determines the current user ID and
then searches the Usrprnt table for a matching user ID and corresponding output device. For
example:
FIND Usrprnt WHERE Usrprnt.userid = USERID NO-ERROR.

IF AVAILABLE Usrprnt THEN
OUTPUT THROUGH VALUE(Usrprnt.outdev).
ELSE
OUTPUT TO PRINTER.
The include file searches the Usrprnt table for a record that has a user ID that matches the user
ID established for the current application session. If there is no user ID match or established user
ID for the application session, OpenEdge uses the default system printer. If there is a match,
OpenEdge sends the application output to the output device contained in the corresponding
outdev field.
The VALUE option of the OUTPUT THROUGH statement allows you to designate a substitutable
output device. The USERID function allows you to capture system user IDs on UNIX. For more
information about the _User table, see OpenEdge Data Management: Database Administration.
After creating an include file to route application output, replace all OUTPUT statements in your
application with the include file. For example:
{output1.i}.
FOR EACH customer:

PUT cust-num name address city st zip.
END.
Using interactive output-routing

You can also set up interactive output-routing schemes that let application users select an output
device at run time. In Windows, for example, you can change the destination of the OUTPUT TO
PRINTER statement at run time by using the SYSTEM-DIALOG PRINTER-SETUP statement.
7–13
Configuring a printer
Many printers have a set of control sequences that you can use to specify different print
characteristics, such as compressed printing or italics typeface. These control sequences often
involve special characters that can be represented by their octal (base 8) equivalent. To denote
these octal codes, precede the three octal digits with an escape character. On UNIX, the escape
character is a tilde (~) or a backslash (\). Table 7–1 lists the standard control sequences using a
tilde as the escape character.
Table 7–1: Standard printer control sequences
Sequence Interpreted as Comments
~nnn Single character Use to send a single character to the printer, where
nnn is an octal code between 000 and 377. You
must specify all three digits.
~t Tab character Use to send the 011 octal code to the printer.
~r Carriage return Use to send the 015 octal code to the printer.
~n Line feed Use to send the 012 octal code to the printer.
~E Escape Use to send the 033 octal code to the printer.
~b Backspace Use to send the 010 octal code to the printer.
~f Form feed Use to send the 014 octal code to the printer.
~" " Use within quoted strings as an alternative to two

quotes ("").
~\ \ Use to send the backslash character to the printer.
~~ ~ Use to send the tilde character to the printer.
The PUT statement with the CONTROL option allows you to specify a control sequence that you
want to send to a printer. The PUT statement has the following syntax:
PUT [ STREAM stream-name ]

CONTROL "ctrl-sequence" "ctrl-sequence" ...
7–14
In the following example, the control sequence ~017 turns on the compressed printing feature
of the current print device:
PUT STREAM a CONTROL "~017".
The control sequences sent to the output destination do not affect the current line, page counters,
and positions maintained within OpenEdge. For more information about the PUT CONTROL
statement, see OpenEdge Development: Progress 4GL Reference.
Creating a printer-control table

It is important to note that control sequences are hardware dependent. Applications with
hard-coded printer-control sequences are not easily transportable. You cannot change the print
devices that the application accesses without changing the hard-coded printer-control sequences
in the application. To bypass this obstacle, create a printer-control table. The printer-control
table contains a record for each printer on your system. Each record in the printer-control table
must contain a field for the name of the print device and several other fields containing a
corresponding set of standard control sequences.
There is no easy way to employ a Progress UPDATE statement to interpret the printer-control
sequences and enter them into a printer-control table. For example, the Progress UPDATE
statement interprets the octal sequence ~017 as the character string:
[TILDE][ZERO][ONE][SEVEN]
instead of the proper code sequence:
[CONTROL-0]
You can create a system administration procedure that lets you convert printer-control
sequences into the appropriate ASCII character strings, and store the printer-control sequences
as ASCII character strings in the fields of a printer-control table.
7–15
Keep the printer-control table up to date with a record for each printer on your system. Figure
7–4 shows a sample printer-control table.
prntcfg
outdev compres ucomprs linfeed frmfeed italics
default ** ** ... ** ** **
lpr -Pcx1 ** ** ** ** **
lpr -Plw1 ** ** ** ** **
** The ASCII character strings stored in the table represent nonprintable characters and
cannot be viewed. Attempts to display them on a terminal can lead to unpredictable
results.
Figure 7–4: Sample printer-control table
The field containing the print device name must index the table. In this sample control table, the
outdev field indexes the table.
To access the proper control sequences for a printer from a printer-control table, set up an
include file to determine the print device used in the application, then substitute the
corresponding control sequences into the PUT CONTROL statements of the application. For
example:
FIND Usrprnt WHERE Usrprnt.userid = USERID NO-ERROR.

IF AVAILABLE Usrprnt
THEN DO:
OUTPUT THROUGH VALUE(Usrprnt.outdev).
FIND Prntcfg WHERE Prntcfg.outdev = Usrprnt.outdev NO-ERROR.
END.
ELSE DO:
OUTPUT TO PRINTER.
FIND Prntcfg WHERE Prntcfg.outdev = "default".
END.
The include file searches the Usrprnt table to determine the output device (Usrprnt.outdev) for
the current user ID. After determining the output device, the include file searches the
printer-control table to find the appropriate control sequences for the current printer. Notice that
the printer-control table contains a default entry for the default printer.
7–16
The PUT CONTROL statements in your application should use a field in the printer-control table
or a variable name to access the proper control sequence for the current printer. This allows you
to change print devices without recoding the printer-control sequences for all the PUT CONTROL
statements in your application. For example:
{output2.i}.
PUT CONTROL Prntcfg.compres.

FOR EACH customer:
PUT cust-num name address city st zip.
END.
PUT CONTROL Prntcfg.ucomprs.
In this procedure, the first PUT CONTROL statement turns on compressed printing, and the second
PUT CONTROL statement turns off compressed printing for the current print device.
7–17
7–18
Part II
Developer’s Toolkit
Chapter 8, Introduction
Chapter 9, Choosing a Code Format
Chapter 10, Initial Deployment
Chapter 11, Upgrades
Chapter 12, Deployment Topics and Tasks

8
Introduction
The Developer’s Toolkit is a product that helps you deploy applications written in the Progress
4GL. It contains several utilities, procedures, and scripts to help you prepare OpenEdge
applications for wider distribution. The Developer’s Toolkit documentation describes:
• Different Progress 4GL code formats and how they affect deployment.
• Upgrading applications.
• Specific deployment tasks, such as encrypting source code.
• Utilities, procedures, and scripts provided with the Developer’s Toolkit.

Toolkit components
You can use the following set of Developer’s Toolkit components when deploying OpenEdge
applications:
• DBRSTRCT utility
Use the DBRSTRCT utility to specify the kinds of access the user has to an application
database.
• MKDUMP utility
Use the MKDUMP utility to create a dump/reload facility.
• XCODE utility
Use the XCODE utility to encrypt your source procedures for shipment to the user. Users
can compile your procedures against their existing databases without the ability to read the
contents of the procedures.
• BUNDLE utility
Use the BUNDLE utility to put binary files into a file called a bundle, then transport the
bundle to another machine using FTP, tape, or some other mechanism, and extract the files
from the bundle.
• Toolkit templates
Use these templates to perform various tasks related to deploying OpenEdge applications.
See Chapter 12, “Deployment Topics and Tasks,” and Appendix D, “Toolkit Contents and
Reference,” for more information about these components.
8–2
9
Choosing a Code Format
Choosing a code format is the fundamental decision that you must make about deploying an
application. This chapter describes the three types of code format, the OpenEdge product
requirements for those code formats, and the advantages and disadvantages of each format in
the following sections:
• Unencrypted source
• Encrypted source
• R-code (CRC-based and time-stamp-based)

Unencrypted source
Unencrypted source is uncompiled source that users can read and edit with any standard text
editor. Users with full compilation capabilities can read and modify unencrypted source. Thus,
when you choose to deploy using unencrypted source, you give users unrestricted access to your
application code and application database.
The following sections provide information about the requirements for using unencrypted
source, and discuss some advantages and possible disadvantages to deploying unencrypted
source.
Development product requirements

Developers must be able to repeatedly modify, compile, and test your application to ensure that
your application behaves as expected. You must therefore have a full development OpenEdge
product on your development platforms. The 4GL Development System, ProVISION,
ProVISION Plus, and WebSpeed products are all full development products.
User product requirements

To read, modify, compile, and execute unencrypted source, the user must have a full
development OpenEdge product (that is, the 4GL Development System, ProVISION,
ProVISION Plus, or WebSpeed). The Query/Results Client product is not a full development
product because it can compile only read-only application files (source files that contain no code
that modifies the database). Also, products that contain client execution engines—for example,
the Database Server or Client Networking products—cannot compile unencrypted source.
Advantages of unencrypted source

Unencrypted source offers several advantages over other code formats:
• Application extendability.
Since users have full access to your source code and full compilation capabilities, they can
modify your application code any way they want.
• Less to manage at development site.
Other code formats require you to manage multiple code trees and might require you to
keep multiple copies of your application database.
9–2
• Simpler initial deployment.
When you choose unencrypted source, deploying your application is usually easier than
with other code formats. Chapter 10, “Initial Deployment,” describes the steps required for
each code format.
• Simpler upgrades.
When you choose unencrypted source, upgrading your application is usually less complex
than with other code formats. Chapter 11, “Upgrades,” describes the steps required for
each code format.
• Easier maintenance.
Since users have full development environments, it is relatively easy to modify or enhance
your application at their sites.
• Full portability.
Both unencrypted and encrypted source are completely portable across platforms and user
interfaces (character mode and GUI), provided you have followed the necessary
guidelines for writing portable applications. This is not true for r-code, which is not
portable across user interfaces.
• Less space used on storage media.
Unencrypted source files usually occupy much less storage space than r-code files,
decreasing their physical media shipment costs. (Encrypted source files also have this
advantage over r-code files.)
Possible drawbacks of unencrypted source

Unencrypted source has several possible drawbacks:
• Does not prevent code modifications.
Users can modify the application source, which can potentially cause difficulty when
applying application upgrades.
• Does not provide application source code protection.
Unencrypted source does not protect your application from the user. Many Independent
Software Vendors (ISVs) do not want the user to be able to see their code.
9–3
• Does not prevent database schema modifications.
Many ISVs do not want users to modify their application database. If you deploy using
unencrypted source, you lose the ability to prevent unwanted changes. Users can modify
your application and application database any way they want.
• More difficult internationalization.
Only r-code can contain multiple text segments for different spoken languages. For more
information, see OpenEdge Development: Translation Manager.
• More difficult to support.
Users might create bugs when they modify the source code.
Encrypted source
Encrypted source is source code that is encrypted with the XCODE utility (provided with the
Developer’s Toolkit). The user cannot make changes to encrypted source code because it is not
readable by the user, so encrypting the source code protects your application.
The following sections provide information about the requirements for using encrypted source
and discuss some advantages and possible disadvantages to deploying encrypted source.
Development product requirements

The requirements for encrypted source are the same as for unencrypted source. However, you
also need one copy of the Developer’s Toolkit (which contains the XCODE utility) for the
development platform. You do not need a copy of XCODE for the different target platforms.

Any OpenEdge client, server, or standalone database product can compile and run encrypted
source.
9–4
Advantages of encrypted source

Encrypted source code has several possible advantages over other code formats:
• Application protection.
Because encrypted source cannot be read by users, it protects your application from users
by preventing them from making changes. Encrypted source shares this advantage with
r-code, which is also not user-readable.
• Less to manage at development site.
Encrypting source code requires storing two code trees: the unencrypted source tree and
the encrypted source tree (which must be kept in a parallel directory structure). While this
is twice what is required with unencrypted source, it is still less than what is required for
r-code.
• Full portability.
Like unencrypted source, encrypted source is completely portable across platforms and
user interfaces (character mode and GUI). This is not true of r-code, which is not portable
across user interfaces.
• Compile-time flexibility.
Because encrypted code is not precompiled, your application can take advantage of
compile-time functionality. For example, you might want to pass arguments to include
files to determine sort order, field lists, etc. You can take advantage of this behavior at the
user site, allowing users to specify their preferences before compilation. This option is not
available with r-code, which you must compile at the development site.
• Flexible index definitions.
If users have full development OpenEdge products, they can modify their indexes without
invalidating your application code (provided that you have not explicitly named indexes
in your code). This flexibility is not available with r-code. R-code that specifically
references a new or changed index will not work. Because the index Cyclic Redundancy
Check (CRC) value is checked at run time, not all r-code will be affected.
Time-stamp-based r-code is even more restrictive.
9–5
• Less space used on storage media.
Encrypted source files usually occupy much less storage space than r-code files, making
your physical media shipment smaller and less expensive. (Unencrypted source files also
have this advantage over r-code files.)
• Encryption keys.
Encrypted source allows you to specify different encryption keys for different code trees
or subsystems within a code tree. Therefore, it is possible to deploy an entire application
at once, but only give the user encryption keys for certain parts of the application. This
way, you can upgrade the user’s application without physically distributing code a second
time.
Possible drawbacks of encrypted source

Encrypted source code has a number of possible drawbacks:
• Does not prevent index modifications.
When compared to r-code, encrypted source is less restrictive because it allows

modifications to the database’s indexes. Whether this is an advantage or disadvantage
depends on whether you want to give the user the flexibility to change indexes. If your
code explicitly specifies indexes in its search criteria, user modifications to your indexes
might invalidate your code.
• The Encrypted Compiler Mode (-rx) parameter changes the capabilities of the Compiler.
When you start OpenEdge with the -rx parameter, the Progress Compiler can compile
only encrypted source, not unencrypted source. If users have the 4GL Development
System, ProVISION, ProVISION Plus, or WebSpeed, they must start OpenEdge again
without the -rx parameter to write and compile their own procedures.
9–6
R-code
R-code, or run-time code, is precompiled code. When you compile a source procedure, Progress
places the compiled version of the procedure into a file that has the same name as the source
procedure with a .r extension. There are two types of r-code: time-stamp-based and
CRC-based. For a complete discussion of these two types of r-code, see Appendix B, “R-code
Features and Functions.”.
Like encrypted source, r-code is not readable to the human eye and therefore protects your
application from users attempting to make changes.
Developer product requirements and r-code portability

R-code is portable between any two environments if the following are true:
• The user interface is the same—MS-Windows or character mode.
Note: If a procedure contains no code that writes to the screen, its r-code is portable
across user interfaces. This is typical, for example, of database schema trigger
procedures.
• The DataServer or combination of DataServers connected during compilation is the same.
All machines that require 4-byte or less alignment are compatible. Thus, r-code compiled on one
of these machines (a Sun SPARCstation, for example) can run on most other machines. One of
the few machines not compatible with this class is the AS/400, which requires greater than
4-byte alignment.
Thus, you can use the same r-code compiled for a character interface and the ORACLE
DataServer on any compatible machine (for example, Sun SPARCstation and RS-6000) that
also accesses the ORACLE DataServer. Similarly, you can use the same r-code compiled in
Windows on any DataServer-compatible Windows system.
You must be able to reproduce the target environment to generate the required r-code. For each
combination, you have to keep track of a different code tree. For each combination, you also
require a full development OpenEdge product (the 4GL Development System, ProVISION,
ProVISION Plus, or WebSpeed) to do the compilations.
9–7

Any OpenEdge client, server, or standalone database product can run r-code.
Advantages of r-code
R-code provides several advantages over other code formats:
• Speed
This format is faster because the R-code does not have to compile at run time.
• Application protection
Like encrypted source, r-code protects your application from possible user changes.
• Good for internationalization
R-code is the only code format that can contain multiple text segments. This means that
the same application can contain strings for multiple spoken languages (French and
German, for example). For more information about translating OpenEdge applications,
see OpenEdge Development: Translation Manager.
• Prevents database modifications
Time-stamp-based r-code is tightly coupled to the application database because each

r-code file contains a time stamp for each database table that it accesses. If the time stamps
do not match, then the r-code does not run. Modifying the database schema—by deleting
a file, or changing a field’s name, or modifying an index—changes the table’s time stamp.
Users are therefore very limited in what changes they can make to the database without
invalidating the application.
CRC-based r-code is less tightly coupled to the application database than

time-stamp-based r-code. However, CRC-based r-code is still more tightly coupled to the
database than encrypted or unencrypted source. For each table in the database, Progress
calculates a CRC value that represents the structure of the table. Like a time stamp, a CRC
value ensures that the tables in the database match those in the r-code. However, because
a CRC value is not specific to a particular database, it is more flexible than a time stamp.
9–8
With either r-code format, you can further restrict access to your application database with
the DBRSTRCT utility. This procedure restricts everyone’s access to the database,
including your own. After you run this procedure, no one can write or compile code that
updates the database or changes the database’s schema. The only code that can access the
database is r-code that you compiled before running the DBRSTRCT utility. This level of
database protection is available only with r-code. For more information about the
DBRSTRCT utility, see Chapter 12, “Deployment Topics and Tasks.”
Possible drawbacks of r-code

R-code has several possible drawbacks:
• Limited portability across user interfaces.
The “Developer product requirements and r-code portability” section on page 9–7 earlier
in this chapter describes the limitations of r-code portability. Depending on the number of
incompatible environments requiring a separate compilation, you might have to keep track
of multiple r-code trees.
• Loss of compile-time flexibility.
Because you deliver your application in a precompiled format, you cannot make use of
compile-time functionality. For example, you cannot pass arguments to include files to
determine sort order, field lists, etc. Users therefore cannot specify their preferences before
compilation.
• More to manage at the development site.
R-code’s limited portability often requires you to manage multiple code trees for a single
version of a single application. As you modify or fix your application and create new
versions, the number of code trees can become quite large.
R-code is also tightly coupled with the application database. This tight coupling requires
you to keep a copy of all of your application databases that have different CRC values or
different time stamps (depending on which type of r-code you have). After numerous
upgrades and fixes, the number of databases can grow quite large.
9–9
• Time-stamp-based r-code requires a copy of new database for upgrades.
When you modify the schema of your application database, you invalidate the existing
r-code because you change the database’s time stamps. To deploy an upgrade, therefore,
you must provide users with a new database (with the correct time stamps) for each new
version of the application. Users are then required to dump their old data and load it into
the new database. This is a time consuming process for larger databases. For very large
databases, the time required to perform a dump and load can be unacceptable. Progress
Software recommends that you use CRC checked sums instead of time stamps for more
flexibility.
9–10
10
Initial Deployment
This chapter provides an overview of the steps that are required to deploy an OpenEdge
application using different code formats. It does not cover every possible contingency, but
rather tries to give you a general understanding of the initial deployment process for the
different code formats. This chapter puts more emphasis on what to do, rather than how to do it.
These steps are not meant to be performed in a strictly chronological order. More detailed
information about particular aspects of deployment is provided in Chapter 12, “Deployment
Topics and Tasks.”
This chapter contains the following sections:
• Deploying database structures and application procedures
• Unencrypted source
• Encrypted source
• CRC r-code
Deploying database structures and application procedures

Figure 10–1 illustrates the steps required and options available when deploying new database
structures and application procedures. When deploying a database, Progress Software
recommends that you first create an empty database at the deployment site, then load the .df
files to create the database structure. This method of deployment will help you avoid any
difficulties resulting from incompatibility between platforms, operating systems, or software
versions at the development and deployment sites.
When deploying application procedures, you can choose to deploy either unencrypted or
encrypted source code, or to deploy compiled r-code. An important consideration in which
method you choose is whether there is a full development product (4GL Development System,
ProVISION, ProVISION Plus, or WebSpeed) capable of compiling code at the deployment site.
Users with OpenEdge products that cannot compile unencrypted source code will have to
deploy encrypted source code and compile it at the site, or deploy r-code. If you deploy r-code,
you must ensure that the platforms, operating systems, and software versions at the deployment
site match those at the development site. Otherwise, you will have to compile the r-code at the
deployment site to ensure compatibility. The following sections address these considerations in
more detail.
10–2
Initial Deployment
Development environment Deployment environment
Check compatibility:
Database Database
Platform
Operating System
OpenEdge version
Create: Create:
Application
.df files
Dump: database
.d files load:
.df files
.d files .df file
.d files
Application procedures Application procedures

Source code
(.p, .w, .i ) Source code
Source code OR +
(.p, .w, .i) Compilation
Encrypt source code
(.px, .wx, .ix ) routine
Database triggers OR
OR
R-code library
R-code library
(.r files)
Scripts Scripts
Startup routine for database Startup routine for database

Configuration/Startup routine Configuration/Startup routine
for application for application
Compilation routine Compilation routine
for procedures for procedures
Backup/Restore routine Backup/Restore routine
Figure 10–1: Deploying database structures and application procedures
10–3
Unencrypted source
This section provides an overview of the steps to follow to deploy an application using
unencrypted source when you are done developing and testing your application.
1. Dump .df and .d files.
You must dump your application schema (.df) and/or data (.d) into ASCII format. This
step copies your data from the application database, which is not portable, into a format
that is portable.
Keep in mind that the .d and .df files should be represented with the appropriate code
page for the target platform.
2. Transfer files.
You must transfer the resultant .d and .df files and your unencrypted source procedures
(which also must be in the appropriate code page) to the target platform. This is a
preliminary step to creating your distribution media.
There is more than one way to transfer files. For example, you can use FTP or other
protocols, such as CROSSTALK. Or you can put the files on tape or other storage media
and physically transport the files.
3. Rebuild the application database at the user site.
You must provide a way for users to build the application database at their site. To do this,
the users must be able to load your .df and .d files into an empty database.
Because you are deploying unencrypted source, users must have either the 4GL
Development System, ProVISION, ProVISION Plus, or WebSpeed products. These
products contain a complete Data Dictionary, which users can use to load the .df and .d
files into an empty database. (In character environments, the Data Dictionary contains data
administration capabilities. In Windows, these capabilities are provided with the Data
Administration tool.)
However, even though the user can perform these tasks, usually it is a good idea to write
a script that automates this process. This not only frees the user from performing this task,
but also makes your application easier to install. When you buy a full development
OpenEdge product, you get all of the Data Dictionary procedures in the
install-dir/src/gui|tty/product subdirectories. The procedures that load data
definitions and data are called load_df.p and load_d.p respectively. Within your script,
you can start OpenEdge and run these procedures to load your data definitions and data.
10–4
Initial Deployment
If you decide not to write a script and instead rely on the users’ ability to load the data
definitions and data, make sure you provide the users with adequate documentation to
guide them through the process.
4. Copy an empty database and rename it.
To rebuild your application database at the user’s site, you must make a copy of the empty
database and rename it. An empty database is included in the installation directory at the
user’s site. Because databases are not portable, you must use an empty database that
already is ported to the target platform.
Users can copy their empty database and rename it. Or you can write a script that does this
task for them. This script can call the PRODB command to make a copy of the database
and rename it appropriately. The Developer’s Toolkit also provides a newdb script that
creates a database. For more information about this script, see Appendix D, “Toolkit
Contents and Reference.”
If you decide to let the users perform this step, you must provide adequate documentation
to guide them through the process.
5. Provide an install utility.
You must provide a way for users to install your application. OpenEdge must be installed
before they can use your application. You can create one install for both OpenEdge and
your application. To do this, create an install program using a third-party tool, such as
Installshield, and call the OpenEdge Install batch mode from within it.
6. Provide a compilation routine.
This step is optional because users must have either the 4GL Development System,
ProVISION, ProVISION Plus, or WebSpeed products, which can compile your
application on the fly. However, an application that is precompiled runs faster than an
application that is compiled at run time. Therefore, you might want to provide a routine
that compiles all of your procedures before it is run.
You can provide a script to do the compilations, or you can provide the user with adequate
documentation to do this task on their own. The Developer’s Toolkit provides a template
procedure, compile.p that you can use to compile your application.
7. Provide a startup routine.
Provide a way for users to start the application. You can either write a script to do this or
provide adequate documentation.
10–5
8. Provide documentation.
You must provide users with enough documentation to use your application and to
complete the above tasks if you do not automate them.
9. Provide online help.
You might want to provide online help for your application.
10. Prepare distribution media.
You must prepare your distribution media. It should include:
– All procedures and include files.
– All .df and .d files.
– All scripts.
– All bitmap files, if any.
– All DLLs, if deploying in MS-Windows.
– All help files.
– All online documentation.
Now you are ready to deploy your application.
10–6
Initial Deployment
Encrypted source
encrypted source when you are done developing and testing your application.
1. Encrypt your procedures and include files.
Before you can deploy your application, you must encrypt all of your procedures and
include files with the XCODE utility. For more information about how to do this, see the
“Encrypting source code procedures” section on page 12–2 in Chapter 12, “Deployment
Topics and Tasks.” Before encrypting the files, make sure they are represented with the
appropriate code page for the target platform.
As with unencrypted source, you must dump your application schema (.df) and/or data
(.d) files into ASCII format. This step copies your data from the application database,
which is not portable, into a format that is portable. You do not have to encrypt your .df
and .d files.
Like your procedure files and include files, the .d and .df files must be represented with
the appropriate code page for the target platform.
3. Transfer text files.
You must transfer the resultant .d and .df files to the target platform. This is a
preliminary step to creating your distribution media.
4. Transfer binary files (encrypted files).
After you encrypt procedures and include files, they become binary files.
You must provide a way for users to build the application database at their site. To do this,
users must be able to load your .df and .d files into an empty database.
10–7
Any OpenEdge client, server, or stand-alone database product can compile and run
encrypted source. However, only those products that can fully compile can load .d files
into a database. The 4GL Development System, ProVISION, ProVISON Plus, and
WebSpeed are the only products with this capability.
If you deploy to users whose licensed products do not have this capability, you must
provide a way for them to load your .d files. For more information about providing a
dump/load facility for users, see the “Dumping and loading” section on page 12–12.
Note: The dump/load procedures should be considered part of your application. The
decision to distribute encrypted source versions of your application procedures
applies to the dump/load procedures as well.
The 4GL Development System, ProVISION, ProVISON Plus, and WebSpeed products
contain a complete Data Dictionary, which users can use to load the .df and .d files into
an empty database. (In character environments, the Data Dictionary contains data
administration capabilities. In Windows, these capabilities are provided with the Data
Administration tool.) However, even though the user can perform these tasks, usually it is
a good idea to write a script that automates this process. This not only frees the user from
performing this task, but also makes your application easier to use.
Within your script, you can use pre-existing procedures in the install-dir/tty and
install-dir/gui directories (installed for full development OpenEdge products). Within
these directories are procedures that load .df and .d files, called load_df.p and load_d.p,
respectively. Your script can start OpenEdge and run these procedures to load your data
definitions and data. To run these procedures at the user site in the case where users do not
have a license for the 4GL Development System, ProVISION, or WebSpeed, the
procedures must be encrypted or in r-code format. This step is necessary because
OpenEdge must be started with the -rx parameter to run or compile the procedures where
users do not have a license. When started with this startup parameter, OpenEdge cannot
run or compile unencrypted source.
definitions and data, make sure you provide adequate documentation to guide them
through the process.
10–8
Initial Deployment
database and rename it. An empty database is included in the installation directory of all
OpenEdge client, server, or stand-alone database products. Because databases are not
portable, you must use an empty database that already is ported to the target platform.
Users can use OpenEdge to copy the empty database and rename it. Or you can write a
script that does this task for them. This script can call the PRODB command to make a
copy of the database and rename it appropriately. The Developer’s Toolkit also provides
a newdb script that creates a database.
If users have an OpenEdge product that provide these capabilities, and you decide to let
them perform this step, you must provide them with adequate documentation to guide
them through the process.
You must provide a way for users to install your application. OpenEdge must be installed
before they can use your application. You can create one install for both OpenEdge and
your application. To do this, create an install program using a third-party tool, such as
Installshield, and call the OpenEdge Install batch mode from within it.
8. Provide a compilation routine.
When you deploy with encrypted source, you typically provide a compilation routine.
Though this is not necessary in all cases, it is usually a good idea because it frees the user
from performing the task of compiling your application. In the case where you specify
unique encryption keys, providing a compilation routine becomes a necessity.
All OpenEdge client, server, and stand-alone database products can compile encrypted
source. Therefore, if you use the default encryption key, users can compile your
application without a specialized routine. However, if you have users compile your
application, you must provide adequate documentation to guide them through the process.
Because encrypted code is not precompiled, your application can take advantage of
compile-time functionality. For example, you might want to pass arguments to include
files to determine sort order, field lists, etc. You can take advantage of this behavior at the
user site, allowing users to specify their preferences before compilation. This option is not
available with r-code, which must be compiled at the development site. Whether you can
repeatedly take advantage of compile-time features during the ordinary day-to-day
operation of your application depends on what OpenEdge products the users have.
10–9
To compile encrypted source code, OpenEdge must be started with the -rx startup
parameter. When an OpenEdge session is running with this startup parameter, the Progress
Compiler can compile encrypted source but cannot compile unencrypted source. If users
have a full development product (the 4GL Development System, ProVISION, ProVISION
Plus, or WebSpeed), they will probably want to write and compile their own unencrypted
procedures. Thus, in their day-to-day operation of OpenEdge, they must run OpenEdge
without the -rx startup parameter. For users with full development products, therefore,
you probably want to perform a one-time compilation with the -rx parameter, then restart
OpenEdge without this parameter. For users with OpenEdge products that cannot compile
ordinary unencrypted source, running permanently with the -rx parameter is not an issue.
The Developer’s Toolkit provides a template procedure, compile.p, that you can use to
compile your application. For more information about compile.p, see the “Decryption
and compilation” section on page 12–4.
You must provide a way for users to start the application. You can either write a script to
do this or provide adequate documentation.
perform the above tasks if you do not automate them.
Now that you have completed the above steps, you need to prepare your distribution media. It
should include:
• All procedures and include files (encrypted).
• All data definition (.df) and data (.d) files.
• All scripts.
10–10
Initial Deployment
• All bitmap files, if any.
• All DLLs, if deploying on MS-Windows.
• All help files.
• All online documentation.
Now you are ready to deploy your application.
CRC r-code
CRC-based r-code. When you are done developing and testing your application and are ready
to begin deploying, follow the steps described in the following sections. For a complete
description of CRC-based r-code, see Appendix B, “R-code Features and Functions.”
1. Decide whether to restrict database access.
If you deploy your application to users with full development products (the 4GL
Development System, ProVISION, or ProVISION Plus), they can write their own
applications to access the database and modify the database schema. Depending on the
nature of your application, you might not want this to happen. To restrict access to the
database, you can use the DBRSTRCT utility that comes with the Developer’s Toolkit. For
more information about using this procedure, see the “Restricting database access” section
on page 12–15.
If you decide to restrict access to the database, you must physically deploy a copy of your
application database with your application. It is not possible for users to build your
database at their site. Because databases are not portable, you must generate a copy of the
database for each target platform. Then you must run the DBRSTRCT utility on each
platform against all of the databases.
In general, restricting access to the database makes it more difficult to initially deploy and
upgrade applications, but it also helps minimize user-created errors. For each release of
the application, the development site must:
– Generate a database for each platform.
– Compile the application against each database.
– Save copies of each database and each r-code tree.
10–11
To update the application, the user must dump the existing database and load the data into
a new database that you supply. For users with large mission-critical databases, this might
be an unacceptable requirement.
10–12
Initial Deployment
2. Compile your procedures and include files.
As described in Chapter 9, “Choosing a Code Format,” r-code is not completely portable.

For each combination of factors requiring a separate compilation, you need to perform a
separate compilation and keep track of a different code tree at the development site. For
each combination, you also need a full development OpenEdge product (the 4GL
Development System, ProVISION, or ProVISION Plus)) to do the compilations.
Unless you explicitly specify the Time Stamp (-tstamp) startup parameter when you start
OpenEdge, OpenEdge generates CRC-based r-code files at compilation.
Note: Progress Software recommends CRC-based r-code because it affords greater

flexibility.
If you decide not to restrict database access, you should dump your application schema
(.df) and/or data (.d) files into ASCII format. This step copies your data from the
application database, which is not portable, into a format that is portable.
The .d and .df files should be represented with the appropriate code page for the target
platform.
You must transfer the resultant .d and .df files to the target platform.
5. Transfer r-code files.
To aid in moving r-code files between platforms, you can use the BUNDLE utility. For
more information about the BUNDLE utility, see Chapter 12, “Deployment Topics and
Tasks.”
10–13
If you have decided not to restrict access to the database, then you must provide a way for
users to rebuild your application database at their site. To do this, users must be able to
load your .df and .d files into an empty database.
Note: You can restrict access to the database and provide compiled code to load .d files.
Any OpenEdge client, server, or stand-alone database product can run r-code. However,
not all of these products can load .d files into a database. The 4GL Development System,
ProVISION, and ProVISION Plus are the only products that have this capability.
If you deploy to users whose licensed products do not have this capability, you must
provide a way for them to load your .d files. For more information about providing a
dump/load facility for users, see the “Dumping and loading” section on page 12–12.
decision to distribute r-code versions of your application procedures applies to the
dump/load procedures as well.
The 4GL Development System, ProVISION, or ProVISION Plus products contain a

complete Data Dictionary, which users can use to load the .df and .d files into an empty
database. (In character environments, the Data Dictionary contains data administration
capabilities. In Windows, these capabilities are provided with the Data Administration
tool.) However, even though the user can perform these tasks, usually it is a good idea to
write a script that automates this process. This not only frees the user from performing this
task, but also makes your application easier to use.
Within your script, you can use pre-existing procedures in the install-dir/tty and
install-dir/gui directories (installed for full development OpenEdge products). Within
these directories are procedures that load .df and .d files, called load_df.p and
load_d.p, respectively. Your script can start OpenEdge and run these procedures to load
your data definitions and data. To run these procedures at user sites where users do not
have a license for the 4GL Development System or ProVision, the procedures must be in
r-code format.
definitions and data, make sure you provide adequate documentation to guide them
through the process.
10–14
Initial Deployment
database and rename it. An empty database is included in the installation directory of all
OpenEdge client, server, or stand-alone database products. Because databases are not
portable, you must use an empty database that already is ported to the target platform.
Users can use OpenEdge to copy the empty database and rename it. Or you can free them
from this responsibility by writing a script that does this task for them. This script can call
the PRODB command to make a copy of the database and rename it appropriately. The
Developer’s Toolkit also provides a newdb script that creates a database.
If users have an OpenEdge product that provide these capabilities, and you decide to let
them perform this step, you must provide adequate documentation to guide them through
the process. For example, you should let them know there are multiple empty databases,
and you should recommend which one they should use.
You must provide a way for the user to install your application. OpenEdge must be
installed before they can use your application. You can create one install for both
OpenEdge and your application. To do this, create an install program using a third-party
tool, such as Installshield, and call the OpenEdge Install batch mode from within it.
You must provide a way for the user to start the application. You can write a script to do
this or provide adequate documentation.
You must provide the user with enough documentation to use your application and to
10–15
Now that you have completed the above steps, you need to prepare your distribution media. It
should include:
• All compiled procedures.
• All application procedures.
• All dump and load procedures.
• All data definition (.df) and data (.d) files.
• All scripts and bitmap files, if any.
• All DLLs, if deploying in MS-Windows.
• All help files.
Time-stamp r-code
time-stamp-based r-code when you are done developing and testing your application. For a
complete discussion of time-stamp-based r-code, see Appendix B, “R-code Features and
Functions.”
1. Decide whether to restrict database access.
If you deploy your application to users with full development OpenEdge products (the
4GL Development System, ProVISION, or ProVISION Plus), the users can write their
own applications to both access and modify the application database. Depending on the
nature of your application, you might not want this to happen. To restrict access to the
database, you can use the DBRSTRCT utility that comes with the Developer’s Toolkit. For
more information about using this procedure, see the “Restricting database access” section
on page 12–15.
If you decide to restrict access to the database, you must physically deploy a copy of your
application database with your application, because it is not possible for users to build your
database at their site. Databases are not portable, so you must generate a copy of the
database for each target platform. Then you must run the DBRSTRCT utility on each
platform against all of the databases.
10–16
Initial Deployment
In general, restricting access to the database makes it more difficult to initially deploy
applications. The development site must:
– Generate a database for each platform.
– Compile the application against each database.
– Save copies of each database and each r-code tree.
Restricting the database removes any advantage that the portability of r-code gives you.
However, it does ensure that the database schema cannot be modified.
2. Build a database for each target platform.
Time-stamp-based r-code is closely coupled with the application database: both the
database time stamps and the r-code time stamps must match for the application to run. It
is therefore necessary to build the database on each target platform before you compile
your application. To build the database, you can copy an empty database to your target
platform, then load a .df file. You can also load .d files into the database.
After you create r-code for each target platform, you need to duplicate the r-code and
database as a preliminary step to creating your distribution media. At your development
site, you must keep a copy of the application database for each target platform.
3. Compile your procedures and include files.
As described in Chapter 9, “Choosing a Code Format,” r-code is not completely portable.

For each combination of factors requiring a separate compilation, you have to generate and
keep track of a different code tree at the development site. To do the compilations, you
also need a full development OpenEdge product (the 4GL Development System,
ProVISION, or ProVISION Plus). Once you have generated the necessary code trees, you
can duplicate the r-code when you create your distribution media.
Unless you explicitly specify the -tstamp parameter when you start OpenEdge, OpenEdge
generates CRC-based r-code files at compilation.
10–17
You must transfer any .d files that are part of your application to the target platform. This
is a preliminary step to creating your distribution media, which must be created on the
target platform.
protocols, such as CROSSTALK. You can also put the files on tape or other storage media
5. Transfer r-code files.
To aid in moving r-code files between platforms, you can use the BUNDLE utility. For
more information about the BUNDLE utility, see the “Using the BUNDLE utility” section
on page 12–4.
6. Provide a dump/load facility.
If users have the 4GL Development System, ProVISION, or ProVISION Plus products,
they have full dump/load capabilities. If users do not have these products, you must
provide a dump/load facility. If the database is restricted, you must supply r-code files to
dump and load. For more information, see the “Dumping and loading” section on
page 12–12.
decision to distribute r-code versions of your application procedures applies to the
dump/load procedures as well.
You must provide a way for the users to install your application. If they do not have an
OpenEdge product installed, they must install OpenEdge before they can use your
application. You can create one install for both OpenEdge and your application. To do this,
create an install program using a third-party tool, such as Installshield, and call the
OpenEdge Install batch mode from within it.
You must provide a way for users to start the application. You can either write a script to
do this or provide adequate documentation.
10–18
Initial Deployment
Now you have to prepare your distribution media. It should include:
• Application database.
• All procedure and include files (or application r-code if the database is restricted), and
dump/load procedures.
• All .df (unless the database is restricted) and .d files.
• All scripts.
• All bitmap files, if any.
• All DLLs, if deploying in MS-Windows.
• All help files.
10–19
10–20
11
Upgrades
After you distribute your application and users have been using it, you might want to upgrade,
fix, or modify either the application procedures or the application database. It is a good idea to
develop a strategy for dealing with application upgrades before distributing an application. That
way, when you have to upgrade an application, you are less likely to have unexpected problems.
• Deploying upgrades
• Modifying the application procedures
• Modifying the application database

Deploying upgrades
Figure 11–1 illustrates the steps needed and options available when upgrading and distributing
changes to the database structure or application procedures. When making changes to the
database structure, you must to create an incremental .df file that contains the changes in the
database structure. You can then load this .df file into the existing database structure to update
that database. For information on creating an incremental 4GL .df file, see OpenEdge Data
Management: Database Administration. See Appendix B, “R-code Features and Functions,” for
more information about deploying changes to database structures.
When modifying application procedures, you can choose to deploy either unencrypted or
encrypted source code, or to deploy modified r-code. An important consideration in which
method you choose is whether there is a full development product (4GL Development System,
ProVISION, ProVISION Plus, or WebSpeed) capable of compiling code at the deployment site.
When deploying to users with OpenEdge products that cannot compile unencrypted source
code, developers will have to deploy encrypted source code and compile it at the site, or deploy
r-code. If you deploy r-code, you must ensure that the platforms, operating systems, and
software versions at the deployment site match those at the development site. Otherwise, you
will have to compile the r-code at the deployment site to ensure compatibility.
Modifying an application is relatively straightforward if you have not made changes to the
database schema. If you have made changes to the database schema, modifying the application
requires more steps.
11–2
Upgrades
Development environment Deployment environment
Modify database Update database
Modify database:
Update .df file Load:
Incremental .df file Incremental .df file
Create:
Incremental .df file
Modify application procedures Load updated procedures
Modified source code

Modify: Modified
( .p, .w, .i ) source code
Source code
(.p, .w, .i) OR +
Encrypt
Compilation routine
modified source code
OR
(.px, .wx, .ix ) OR
Modify:
r-code Compile modified r-code Modified r-code
(.r) (.r files )
Figure 11–1: Deploying upgraded database structure and application

procedures
11–3
Modifying the application procedures

As with any distribution, you can choose to distribute unencrypted source, encrypted source, or
r-code (CRC-based or time-stamp-based). When you distribute r-code, Progress Software
recommends you choose CRC-based r-code. This section describes upgrading an application
without any modifications to the database. If you have modified the database schema, upgrading
becomes more complicated, as described in the “Modifying the application database” section
on page 11–5.
Unencrypted source
To upgrade your application, distribute the modified versions of your procedures.
Encrypted source files

To upgrade your application, distribute the modified versions of your procedures. If you specify
an encryption key, you must also provide a compilation procedure.
As described in Chapter 10, “Initial Deployment,” when you deploy with encrypted source, you
usually want to provide a compilation procedure. Although this is not necessary in all cases, it
is a good idea because it frees the user from having to compile your application. When you
specify unique encryption keys, providing a compilation routine is a necessity.
All OpenEdge client, server, and stand-alone database products can compile encrypted source.
Therefore, if you use the default encryption key, the user can compile your application without
a specialized procedure. However, if you have the user compile your application without a
script, you must provide adequate documentation to guide them through the process.
Time-stamp-based r-code
If you are supplying time-stamp-based versions of new or modified procedures, you must
compile the procedures against the same version of the database that users are currently using,
and on the same machine type. Otherwise, the r-code versions of the new or modified
procedures will not run, because database file time-stamps are different at the user site.
Once you have precompiled the procedures against the original database, you can distribute the
new r-code files to the user.
11–4
Upgrades
CRC-based r-code
If you supply new or modified CRC-based r-code files, you must precompile the procedures
against a version of the database that is structurally the same as the user’s database. You must
also compile it on a machine of the same class, same user interface, and same combinations of
DataServers (if any). However, since the r-code you create has no time-stamps, it does not
matter when the database tables were created or modified.
Modifying the application database

Upgrading is more complicated when you have to change the database schema. If you are
upgrading with unencrypted source, encrypted source, or CRC-based r-code, you can supply an
incremental .df file and copies of the modified procedures.
If you are upgrading with time-stamp-based r-code, you must supply the following:
• A new empty application database that includes the modified tables, fields, and indexes.
• Precompiled versions of all modified procedures.
• Dump/load utilities that will dump the user’s data and definitions and load them into the
new empty database.
Upgrading with updated .df and encrypted source

When you update a database structure in the development environment, you must then re-create
these changes in the database that is already established at the deployment site. To accomplish
this transfer, an incremental .df file is generated in the development environment. Copies of the
original and updated databases are compared, and the differences between them are
incorporated into an incremental .df file. For more information on creating an incremental 4GL
data definitions file see OpenEdge Data Management: Database Administration for more
information about deploying changes to database structures. The following general steps tell
you how to prepare a .df file that includes new or modified data definitions:
• Obtain copies of the current user database and the new modified database.
• Connect the two databases.
• Compare the data definitions in the user database with the data definitions of your new
updated database, creating a new incremental .df file that reflects the changes.
11–5
• Provide a utility for users that loads the incremental .df file into the existing database.
• Encrypt the procedures affected by changed data definitions.
To prepare a data definitions file:
1. In Windows, open the Data Administration Tool (for character interfaces, open the Data
Dictionary).
2. Connect the two databases by choosing Database→Connect.
3. Select the database that includes the new, modified data definitions as your current
database by choosing Database→Select Working Database.
4. Create an incremental definition file by choosing Admin→Dump Data and

Definitions→Create Incremental .df File.
This option compares the data definitions in the non-empty copy to the current database
schema and creates a new data definition (.df) file. The new .df file contains a record for
each difference between the two schemas. The differences include any added, renamed,
changed, or deleted file, field, or index.
If a file, field, or index exists in the old database but not in the new schema, OpenEdge
asks you whether the object has been renamed. If you respond no, a record appears in the
new .df file marking the object as deleted.
If the new schema includes a new unique active index, OpenEdge asks you whether you
want to deactivate it. If you do not deactivate the index, and there are duplicate keys in the
old database, OpenEdge aborts your attempt to load new definitions into the old database.
If you deactivate the index, the load procedure defines the new index, but does not create
the index file. You must build and activate the index after loading the new data definitions.
11–6
Upgrades
5. Perform steps a through d below for testing purposes. Then prepare a tool for users that
performs these steps on site:
Note: (The upgrade template provided with the Developer’s Toolkit outlines one way to
do this. Before you can use this template, you probably need to modify it.)
a. Select the copy of the old database as your working database.
b. Load the updated data definitions by choosing Admin→Load Data and

Definitions→Load Data Definitions (.df file).
c. If you deactivated any indexes in Step 3, re-create data in the indexed fields as
required to avoid duplicate keys. Then reactivate the indexes with PROUTIL
IDXBUILD. For more information, see OpenEdge Data Management: Database
Administration.
d. OpenEdge now updates the old database schema to match the modified schema.
Compile and test all your procedures against the updated database.
6. Test your procedures.
7. Use the XCODE utility to encrypt procedures invalidated by the new data definitions.
Since the new .df file changes CRC check sums and time-stamps only on the database
tables that are actually modified, you only have to encrypt and ship the source versions of
those procedures that access the changed tables. (If you compile your procedures with the
XREF option, you get a listing of the tables accessed by each procedure.)
Using the upgrade template
The upgrade template, all .p files it uses, and all .inp files it uses are only templates; you must
check each file and modify it to suit your particular application. Following is a list of checks and
modifications you must make before using upgrade; your application might require additional
changes.
The UNIX version of upgrade is found in /usr/dlctk/samples/unix. The DOS version is

located in the respective subdirectories of samples. The files that upgrade uses can be found in
/usr/dlctk/samples.
11–7
The upgrade template performs three basic actions to upgrade an application at the user’s site:
1. Loads the new .df file, which you created from your version of the upgraded database
with the Admin→Dump Data and Definitions→Create Incremental .df File option.
2. Rebuilds any indexes deactivated during the data definition load process.
3. Compiles encrypted source procedures.
Changes to the upgrade template for the data definition load stage (Step 1.):
• Modify upgrade.p (not the upgrade template) and the files it uses:
– Set the system administrator id and password appropriately in loginupg.p (or

prepare a tool your users can use to set them).
– Modify upgrade.inp to name the new .df file.
– Test load_df.p (a standard OpenEdge Dictionary procedure). If you have created a

new unique active index, load_df.p asks whether you want to deactivate the index.
You need to add a response (Y or N) to upgrade.inp.
– If you and your users do not freeze the database files, delete the call to freeze.p.
(Leave the call to unfreeze.p in case your users ever freeze the database files
without your knowledge.)
– Modify unfreeze.p and freeze.p to include the correct filenames.
– Check upgrade.log for any problems.
Changes to the upgrade template for the rebuild deactivated indexes stage (Step 2.):
• If you and your users will not be deactivating indexes, remove the _proutil command line
from upgrade.
• If you have added a new unique active index, modify rebuild.inp to include the correct
responses to prompts by _proutil $1 -C idxbuild. That is, test _proutil idxbuild on
your database and add a line to rebuild.inp to answer each question appropriately.
• Check rebuild.log for problems.
• You might want to add a procedure to upgrade that checks rebuild.log and, if necessary,
fixes duplicate key data and rebuilds the index again. Alternatively, you might want to
check the .log file and just stop before compilation proceeds.
11–8
Upgrades
Changes to upgrade template for the compile encrypted procedures stage (Step 3.):
• Modify compile.inp to name the procedures to be compiled.
• Modify the COMPILE statement in compile.p to use the encryption key you want.
• Prepare to ship compile.p: either encrypt compile.p, possibly with the default key, or
compile compile.p, thereby hiding your encryption key in the .r file. If you ship
compile.r, it must be compiled on the target machine type. It can be compiled against any
database because it does not reference any database files.
The upgrade template is relevant when you want to distribute only new data definitions and
encrypted versions of affected application procedures. However, you might choose instead to
ship a complete new version of the database and application, as described in the following
section.
Upgrading with updated .df and CRC-based r-code

The flexibility of CRC-based r-code makes it easy to distribute a new release of an existing
application.
To distribute a new release of an existing application:
1. Create an incremental .df file of your application database using the Data
Administration tool (for graphical environments) or the Data Dictionary’s Admin
submenu (for character environments). For more information on creating an incremental
.df file, see OpenEdge Data Management: Database Administration.
2. Recompile source files that were affected by the new schema changes.
3. Send the .df file and copies of the new r-code files that were affected by the schema
changes to your users. After the users load the incremental .df file, they can immediately
run your new .r code.
Essentially, the steps you take are the same as when you use encrypted source, but you gain the
following advantages:
• You do not have to encrypt your procedures. However, you need to recompile some
r-code.
• The user does not have to compile your procedures.
11–9
In addition, unlike time-stamp-based r-code, you gain these advantages:
• You do not have to send a copy of a new database to the user.
• The user does not have to dump and reload data.
One possible disadvantage of using CRC-based r-code is that a user with Progress 4GL
Development System, ProVISION, ProVISION Plus, or WebSpeed can create a counterfeit
database (a database with the same structure as your application database). The user can then
write a program, compile the program, and run it against your application database. (The user
cannot do this if you use time-stamp-based r-code because the time-stamps in the counterfeit
code would not match those in your database.)
If this concerns you, the PROUTIL utility’s DBAUTHKEY qualifier enables you to set an
authorization key for your database. When compiling a procedure, OpenEdge includes the value
of this key in your r-code. CRC-based r-code that does not include the correct authorization key
will not run against your database.
You can insert the authorization key into existing CRC-based r-code with the PROUTIL
utility’s RCODEKEY qualifier.
For more information on the PROUTIL utility’s DBAUTHKEY and RCODEKEY qualifiers, see
OpenEdge Data Management: Database Administration.
Upgrading with time-stamp-based r-code files

If database changes are extensive, you might choose to distribute brand new versions of your
application and the database.
To distribute the precompiled version of an upgraded database:
1. Build a new basic database.
2. Recompile all your procedures, including those not directly affected by the schema
change, so that r-code file time-stamps match the database file time-stamps.
3. Distribute the new basic database and the recompiled procedures to users.
Your users will have to dump their data from the old database and load it into the new
database. Therefore, you must also provide your users with a dump/reload facility.
11–10
Upgrades
4. If you are changing any of the file formats used in your application, you must modify the
set of load files to work with those new formats.
5. Run the mkdump script against the new version of the database.
6. Supply a modified set of file load procedures so the user can reload the database using
procedures that are compatible with the old data format. These procedures will probably
be different from the file load procedures the user will use to reload the new database after
dumping it.
7. Supply new file dump, file load, and subdirectory procedures so the user can later dump
and reload the database, if necessary.
To incorporate modifications you made to the database, the user must:
1. Use the old dump procedure to dump the data in the existing database. (Note that dumping
and reloading a large database might take days, depending on the database size.)
Note: You can use the binary dump and load to reduce this time dramatically. See the
section on PROUTIL in OpenEdge Data Management: Database Administration for
more information on binary dump and load.
2. Make a copy of the new basic database.
3. Use the new load procedure to load the old database data into the new database. You must
ensure that the new load procedure is prepared to accept data in the format and order
dumped by the old dump procedures.
11–11
OpenEdge product upgrades

The user might upgrade from an OpenEdge product that does not support full development to
either the 4GL Development System, ProVISION, ProVISION Plus, or WebSpeed.
To allow the users of a previously restricted application database to run your application
using the capabilities of their new, less restrictive version of OpenEdge:
1. Create a new basic database.
2. Distribute the new basic database to the user.
The user must use the dump/load facility you provided to dump the existing database, make a
copy of the new basic database, and reload the existing data into that new database.
If the new version of OpenEdge is being installed in a different directory than the old version,
UNIX users can use the _tlr module to edit the value of the DLC variable in your application
scripts.
11–12
12
Deployment Topics and Tasks
This chapter describes issues related to deploying OpenEdge applications as outlined in the
following sections:
• Encrypting source code procedures
• Using the BUNDLE utility
• Dumping and loading
• Restricting database access

Encrypting source code procedures

This section describes the XCODE utility and the process of encrypting source code before
deploying an application.
XCODE utility
Use the XCODE utility to encrypt Progress 4GL procedures and include files. This is the syntax
for XCODE:
Syntax (UNIX)
xcode [ -k key ] -d directory [ files] [ - ]
key
A character string up to 8 characters long. On UNIX, key is case sensitive. If you do not
specify key, XCODE uses a default key. When OpenEdge is started with the Encrypted
Compiler Mode (-rx) startup parameter, the Progress Application Compiler automatically
uses this default key, unless you specify the XCODE option on the COMPILE statement.
directory
The directory where XCODE places the encrypted files. The specified directory must
be different from the source directory, because each encrypted file retains the name of its
original source file. XCODE overwrites existing files in directory if they are encrypted.
files
The relative pathnames of the files you want to encrypt. XCODE appends the pathnames
supplied to directory.
Preparing to use XCODE

Before running XCODE, create a directory structure exactly parallel to your source directory
structure, then move to the root of the original source directory structure. Supply the root of the
new structure as directory, and supply the relative path names of the files to be encrypted as
files. The relative path names are appended to directory. Because XCODE does not create
new directories, any directories implied by the directory or files arguments must be created
before running XCODE. Encrypted files have the same names as the original source files.
12–2
You must encrypt both your procedure and include files in order for your encrypted procedures
to run.
The dash (-) option tells XCODE to take filenames from the standard input. On UNIX, this
allows you pipe output from an ls, cat, or find command to XCODE.
Here is an example of how you can use XCODE on UNIX. Suppose you have just finished
developing and testing the procedures in /usr/test and its four subdirectories and want to
encrypt them for shipment to users.
To encrypt procedures for shipment to users:
1. Create a directory structure parallel to /usr/test:
cd /usr/test
mkdir /usr/testx
mkdir /usr/testx/ar
mkdir /usr/testx/fm
mkdir /usr/testx/inv
mkdir /usr/testx/oeFk
2. Move to the original development root in preparation for encryption:
cd /usr/test
3. Encrypt your procedures:
xcode -k mykey -d usr/testx *.p ar/*.p fm/*.p inv/*.p oe/*.p
Encrypted versions of the source procedures in /usr/test and its subdirectories now
reside, with the same names, in /usr/testx and its subdirectories.
Note: You must also encrypt include (.i) files.
12–3
Decryption and compilation

If you distribute encrypted source code, you must also prepare and distribute a program that
compiles your application procedures at a user site. The core of this program is one or more
COMPILE statements with the XCODE option. If you encrypt your procedures using the default key,
the XCODE option is unnecessary, because the Compiler recognizes that the procedures are
encrypted and attempts to decrypt them using the default key.
The XCODE option of the COMPILE statement decrypts the specified source files-and any
encrypted include files-using the same keys supplied in XCODE. Decrypting is incremental
during compilation. That is, having the decryption key does not allow a user to examine a
decrypted version of the source code. Furthermore, the key can be easily hidden in an object
version of your compile program.
When started with the Encrypted Compiler (-rx) startup parameter, OpenEdge places you (or a
user) by default in the Progress Procedure Editor. The COMPILE statement and the icompile.p
procedure will only compile encrypted procedures when OpenEdge is started with -rx. When
shipping encrypted source code, you must supply either an encrypted .p or a .r version of your
compile program, which can be run in encrypted compiler mode. The Toolkit includes a sample
template, called upgrade, that invokes OpenEdge with the -rx parameter and compiles
encrypted source programs.
You invoke the encrypted source code compiler with the command PROGRESS/XCOMPILER. See
upgrade.com in the Toolkit samples subdirectory for more information.
After the procedures are compiled, you might want users to delete the source to regain the disk
space. If you do this, consider freezing the database files; otherwise, the user can modify the
database and invalidate object procedures for which the user no longer has the source.
Using the BUNDLE utility

The BUNDLE utility lets you put binary files into a file called a bundle, transport the bundle to
another machine using FTP, KERMIT, tape, or other mechanism, and extract the files from the
bundle. The BUNDLE utility is designed for copying encrypted source files and r-code files,
but any platform-independent binary file or ASCII file can be copied as well. It is not designed
to handle executables, object files, OpenEdge RDBMSs, or other platform-dependent files.
The BUNDLE utility consists of two C language programs: bundle.c and unbundle.c. These
programs are described in the following sections.
12–4
The bundle.c program

The bundle program puts input files into a bundle. This is the syntax:
Syntax (UNIX)
bundle [ -ascii | -binary ] [ -uppercase | -lowercase ]

bundle-file { { -select [ selection-file ] } | input-file }
-ascii | -binary
Specifies whether the input file is to be read as an ASCII text file or as a binary file. The
default is binary.
-uppercase | -lowercase
Tells bundle to convert the names of files being bundled to uppercase or lowercase. By
default, filenames are used without case conversion.
bundle-file
Provides the name of the file into which input files are bundled. If the file does not exist,
bundle creates it. If it does exist, bundle appends data to the end of it.
-select selection-file
Indicates that the names of the input files are to be read from a selection file. By default,
the selection file is read from standard input.
This is the format of selection-file:
Syntax
filename [ ascii | binary ]
Each entry must be on a line by itself and cannot continue across lines.
If ascii or binary is absent, the command line specification is used. Use an exclamation
point ( ! ) or pound sign ( # ) as comment characters. Everything from a comment character
to the end of line is ignored. The comment character must be separated from any preceding
text by a blank space. Blank lines are also ignored. Wild cards are not supported.
12–5
This is a sample file:
# First line.
# Config files follow.
cfg-show.x # Depending on command-line, ascii or binary.
cfg-doc.txt ascii
cfg-make ascii
# The next line is blank. # Last line.
input-file
The name of a single input file. Wild cards are not supported.
The unbundle.c program

The unbundle program takes files out of a bundle. This is the syntax:
Syntax (UNIX)
unbundle [ -toc | -fulltoc | -date | -all] bundle-file

[ -select [ selection-file ] ]
-toc | -date | -fulltoc | -all
Indicates the operation to perform. The default, toc, lists a table of contents that shows the
name and type (ascii or binary) of each file in the bundle. The fulltoc value lists a table of
contents containing: 1) toc information, 2) date information, and 3) the input files’ file
specifications, modify dates, and sizes. The date value lists time stamps showing when
bundle was run. The all value unbundles all files in the bundle putting the unbundled files
in the current directory.
-select selection-file
Allows you to select by name the files to unbundle or to list with toc or fulltoc.
This is the format of selection-file:
Syntax
filename [ unbundle-as-file-spec ]
12–6
The filename value names the file to be processed. When you are unbundling,
unbundle-as-file-spec specifies the name unbundle is to use as the unbundled filename.
Comments and blank lines are permitted as described earlier for the bundle command’s
selection-file. Wild cards are not supported.
If select is specified and no specification-file is provided, selections are read from

standard input.
This is a sample file:
# UNIX example
# First line.
cfg-show.x pdir/cfg-show.p
cfg-doc.txt docdir/cfg-doc.doc
cfg-make # Created as cfg-make in current directory.
readme.txt # Created as readme.txt in current dir.
# The next line is blank.
# Last line.
Examples using BUNDLE

The following synopsis shows how to use bundle and unbundle. This section assumes you have
to transfer encrypted source files, which are binary files.
First you have to create a “bundle” file. To do this you specify the output file (that is, the bundle)
and one or more input files (the encrypted source files). For these examples, the bundle file has
a .bun extension and the encrypted source files have a .x extension. The bundle is created on
UNIX, copied to Windows, and unbundled on Windows.
Put a single file named foo.x in the bundle:
# bundle xcode.bun foo.x
Or put all encrypted source files in the current directory in the bundle:
# ls *.x | bundle xcode.bun -select
12–7
Or put some selected files (this, that, what) in the bundle:
# bundle xcode.bun -select

this.x
that.x
what.x
^D
You can also put the selections into a file:
# cat >xcode.sel
this.x
that.x
what.x
^D
# bundle xcode.bun -select xcode.sel
Note that files are always appended to the bundle, so you can incrementally add files to it. Thus,
the above sequence created xcode.bun with this in it: foo.x, all xcode files in the current
directory, this.x, that.x, and what.x.
Now you need to copy the bundle to some destination. You can use FTP, making sure that
binary mode is in effect; KERMIT, making sure that binary mode is in effect; or dd.
To see what is in the bundle, enter this command:
C:> unbundle /toc xcode.bun
The unbundle program lists a short table of contents. To see a full table of contents, enter this
command:
C:> unbundle /fulltoc xcode.bun
To unbundle everything in the bundle and put the files in the current directory, enter this
command:
C:> unbundle /all xcode.bun
12–8
To unbundle selected files (this.x and that.x) and put them in specified directories, enter this
command:
C:> unbundle xcode.bun /select

this.x usr2:[xcode]this.x
that.x usr1:[xcode]that.x
^Z
You can also put the selections into a file:
C:> create xcode.sel

this.x usr2:[xcode]this.x
that.x usr1:[xcode]that.x
^Z
C:> unbundle xcode.bun /select xcode.sel
Once you have unbundled the files, they can be executed or compiled in OpenEdge.
Text files can also be bundled. You can specify -ascii on the command line, thereby making
ascii the default file type; or you can specify ascii after the filename in the selection list:
C:> dir *.p | bundle -ascii pcode.bun

C:> bundle pcode.bun -select
foo.p ascii
^D
C:>
Binary and ascii can be mixed in a bundle:
C:> bundle allcode.bun -select

foo.p ascii
foo.x binary
^D
C:>
12–9
Since bundle always appends files to the end, multiple files with the same name might appear
in a bundle:
C:> bundle allcode.bun -select

foo.p ascii
xcode/foo.p binary
^D
C:>
In this example, the filename foo.p appears twice and represents two different files. When
unbundling this (with -all) foo.p (ascii) is unbundled first and then foo.p (binary) is unbundled
overwriting the other foo.p. To unbundle both files, use a selection list to give each file a unique
name or put each in a different directory:
C:> unbundle allcode.bun -select

foo.p src/foo.p # This is the ascii foo.p
foo.p xcode/foo.p # This is the binary foo.p
^D
C:>
You can also use a selection list to skip over a file by directing it to the null device, as shown in
the following UNIX example:
$ unbundle allcode.bun -select

foo.p /dev/null
foo.p
^D
$
12–10
To help differentiate files with identical names, unbundle -full shows files’ input file
specifications, modify dates, and sizes in bytes; the current directory when the bundle was
created; and a time stamp showing when the files were bundled:
$ unbundle mystuff.bun -full

# V0 Time-stamp: Thu Apr 15 19:59:19 1993
# V0 Current-directory: C:\TEMP
mon03.txt #ascii
# V0 Input-file: MON03.TXT
# V0 File-modify-time: Thu Apr 15 19:57:12 1993
# V0 File-size: 2503
mon03.txt #ascii
# V0 Input-file: ..\WVM\DOC\MON03.TXT
# V0 File-modify-time: Sun Apr 04 18:17:48 1993
# V0 Time-stamp: Thu Apr 15 20:00:23 1993
# V0 Current-directory: C:\TEMP
mon03.txt #ascii
# V0 Input-file: mon03.txt
# V0 File-modify-time: Thu Apr 15 20:00:10 1993
$
(The V0 denotes version 0 of the bundle record format. It allows backward compatibility should
this format have to be changed.) You can use -select with -full to see information on selected
file names.
Note: Binary dump and loads are dramatically faster. See the section on PROUTIL in
OpenEdge Data Management: Database Administration for more information on binary
dump and load.
12–11
Dumping and loading

You have to supply a facility to dump and reload the application database. Your users need a
dump and reload facility to:
• Convert data to ASCII format for transporting among machines or database products.
• Increase index efficiency.
• Convert from one version of the software to another.
• Upgrade your application if you deploy using time-stamp-based r-code.
The Progress 4GL Development System, ProVISION, ProVISION Plus, and WebSpeed
products all provide full dump/load capabilities via either the GUI Data Administration Tool,
Character Data Dictionary Tool, or command line PROUTIL utility. For more information
about these capabilities, see OpenEdge Data Management: Database Administration. Other
OpenEdge products provide less complete dump/load capabilities. Other OpenEdge products
such as Query Results provide less complete dump/load capabilities.
Note: Progress Software recommends you use binary dump and load instead of MKDUMP
when moving table contents. Refer to OpenEdge Data Management: Database
Administration for more information about binary dump and load, and loading of
sequence values.
The Progress Developer’s Toolkit includes sample utilities that you can use to create your own
dump/load facility. This section covers these samples and explains how to modify them for your
own use.
MKDUMP utility
This sample utility contains a dump/load facility. When you run the MKDUMP utility, it creates
two Progress 4GL procedures: one that dumps a database and one that reloads a database. For
example, you would run MKDUMP to create a dump/reload facility for the sports database, as
follows:
Syntax
mkdump sports
12–12
Figure 12–1 shows the files produced by running MKDUMP.
$ mkdump
Runs
filedump.p
Creates
dmpprocs Idprocs
filedump.p fileload.p
subdirectory subdirectory
Figure 12–1: Output of mkdump
The MKDUMP utility runs a Progress 4GL procedure, mkdump.p, which creates and compiles
two other Progress 4GL procedures, filedump.p and fileload.p. The filedump.p procedure
dumps the files from a database; fileload.p loads the files into a database.
In addition, mkdump.p creates two directories. The dmpprocs subdirectory contains a database
dump procedure for each of the files in the database. The ldprocs subdirectory contains a
database load procedure for each of the files in the database. The mkdump.p procedure also
precompiles all the procedures it creates. These precompiled procedures may not be appropriate
for your use if the deployed database does not have the same name as the original database that
MKDUMP was run against.
The MKDUMP utility creates these files and subdirectories in your current working directory.
Before distributing them to users, you must move them to your application master directory.
You can then supply either the encrypted source or object versions of the filedump.p
procedure, fileload.p procedure, and each of the procedures in the dmpprocs and ldprocs
subdirectories.
12–13
You can modify MKDUMP or any of the mkdump.p, filedump.p, or fileload.p procedures as
needed. However, once you have created and perhaps modified the dump/load scripts or batch
files, be sure to provide a way for users to use these procedures. You should also provide
adequate documentation for users to use the facility.
Note: The dump/load procedures should be considered part of your application. The decision
to distribute r-code or encrypted source versions of your application procedures applies
to the dump/load procedures as well.
Using your dump/reload facility

To dump and reload a database, the user:
• Uses dumpdb to dump the current copy of the database.
• Uses either prodb or newdb to make a fresh copy of the basic database.
• Uses reloaddb to reload the database.
Before you supply the filedump.p, fileload.p, and subdirectories of dump and reload
procedures to a user, you must understand the following points:
• The filedump.p and fileload.p procedures were written to run from an interactive
Progress 4GL procedure. If you plan to have users run these procedures from the operating
system command level, you must supply an output destination by adding OUTPUT TO
filename at the top of each procedure. Comments in the dumpdb and reloaddb files
explain these modifications.
• If you modify the procedures, remember to recompile.
• If the database to be loaded does not have the same name as the database that the
MKDUMP was run against, then you must recompile the fileload.p procedure against
the database with the proper name.
12–14
Restricting database access

The Developer’s Toolkit provides the DBRSTRCT utility to restrict access to a database. If you
restrict the database with DBRSTRCT, you cannot compile procedures or upgrade the database
at the user site. You must provide a new empty database and a complete set of .r files to upgrade
the application, and users must dump and reload their databases.
Because database access restrictions apply to you as well as to your users, you must make a copy
of your original, unrestricted and unfrozen database, and store it under a separate name.
That way, if you want to lessen the restrictions at a later time, you can dump the data in the
restricted database and reload it into a copy of the original, unrestricted database.
You use the DBRSTRCT utility to define the kinds of database access all users, including
yourself, are allowed. This is the syntax for the DBRSTRCT utility:
Syntax (UNIX)
dbrstrct database-name
12–15
In these commands, database-name is the name of the database you want to restrict. The utility
starts OpenEdge and displays the following menu from which you can choose options that let
you define privileges for the update and query activities:
To deny update or query access to all database files that are currently defined, choose 1. A
second menu screen appears.
If you choose 1 (Deny updates), at this second menu, users can query but not update the
database.
Any procedures you compile against a database before restricting that database are exempt from
any restrictions you apply with the DBRSTRCT utility.
Make sure that you compile a complete set of dump procedures before you restrict the database.
Otherwise, users will not be able to dump their database.
Note: Encrypted source procedures cannot be compiled against a restricted database.
12–16
Part III
Appendices
Appendix A, Building OpenEdge 4GL Executables
Appendix B, R-code Features and Functions
Appendix C, OpenEdge Application Limits
Appendix D, Toolkit Contents and Reference

A
Building OpenEdge 4GL Executables
When you purchase an OpenEdge product, you receive a set of executable files, database files,
and other files that are necessary to run the product on your system. In most cases, the files
included in your initial product installation fulfill your system requirements. However, you
might need to customize an OpenEdge executable by adding or removing product capabilities.
For example, you might need to change network protocols or access a non-OpenEdge data
source. When you need to customize an OpenEdge executable, use the OpenEdge make utility.
The make utility is a set of scripts that you use to build customized versions of certain OpenEdge
executables.
This appendix provides information about the process and requirements for building
customized OpenEdge 4GL executables. It also provides instructions for using the make utility
scripts on UNIX and in Windows. This appendix contains the following sections:
• Licensing requirements.
• Building executables on UNIX
• Building executables in Windows
• Troubleshooting
For information on building DataServer executables, see OpenEdge Data Management:

DataServer for ORACLE.
Licensing requirements
You are obligated to ensure that the customers who purchase your product have purchased and
installed a properly licensed version of OpenEdge before you install any OpenEdge executables
you deliver as part of your product.
Building executables on UNIX

This section provides instructions for building a customized executable on UNIX, as described
in the following sections:
• Preparing the UNIX software environment
• Building a customized executable on UNIX
Preparing the UNIX software environment

When you install OpenEdge, the installation program prepares the software environment. In the
UNIX software environment, OpenEdge uses the buildenv script to maintain environment
variables.
The make utility script calls the buildenv.sh script. The buildenv.sh script sets default values
for environment variables that point to objects, libraries, and options involved in linking
executables. You can edit this script to customize environments for different sites.
The make script has software and environment requirements, as follows:
• Build the executable on the same platform on which it is to be run.
• Verify that there is a linker installed on your system, and that the PATH environment
variable contains the path to the C++ compiler and the linker.
• Verify settings for OpenEdge environment variables. Set DLC to the directory where you
have installed OpenEdge.
• Verify that the buildenv.sh script (located in the $DLC/oebuild/make directory) includes
the appropriate environment variable settings for your system.
A–2
For more information about maintaining environment variables in the buildenv script, see the
“Maintaining the UNIX user environment” section on page 4–39.
For more information about UNIX environment variables, see OpenEdge Getting Started:
Installation and Configuration for UNIX.
Building a customized executable on UNIX

This section contains instructions for building UNIX 4GL client executables. The script is
located in the oebuild/make directory under the root of your OpenEdge installation.
To build a UNIX 4GL client executable:
1. Open a terminal and invoke a Bourne shell (/bin/sh) on the system where OpenEdge is
installed.
2. Change to user root.
3. Set and export the environment variable DLC to the OpenEdge installation directory. For
example:
> DLC=/usr/OpenEdge/dlc
> export DLC
4. Optionally set and export the environment variable IMAGE to the full pathname of the
executable to be generated. By default the client executable will be named
$DLC/oebuild/_progres.
5. Unset all the library path variables for your operating system. The script will set these
variables as required. For example:
> unset LD_LIBRARY_PATH LIBPATH SHLIB_PATH
6. Make a backup copy of the build script build_rx.sh. For example:
> cp $DLC/oebuild/make/build_rx.sh $DLC/oebuild/make/build_rx.sh.orig
A–3
7. Edit the script to add customized objects and any necessary libraries to accommodate them
on the link line, and save the file. Available objects and libraries are located in
$DLC/oebuild/obj.
8. Run the script $DLC/oebuild/make/build_rx.sh. If you did not set the IMAGE variable,
the client executable is built as $DLC/oebuild/_progres; otherwise, the executable is built
as specified by $IMAGE.
To use the new executable, you must replace the default executable and set appropriate
permissions.
To replace your default client executable:
1. Make a backup copy of the original executable. For example:
> cp $DLC/bin/_progres $DLC/bin/_progres.orig
2. Copy the newly built executable into your installed bin directory. For example:
> cp $DLC/oebuild/_progres $DLC/bin/_progres
3. Change permissions on the newly created executable to include the Set UID bit. For
example:
> chmod u+s $DLC/bin/_progres
A–4
Building executables in Windows

This section provides instructions for building a customized executable in Windows, as
described in the following sections:
• Preparing the Windows software environment
• Building a customized executable in Windows
Preparing the Windows software environment

When you install OpenEdge, the installation program prepares the software environment. In the
Windows software environment, OpenEdge uses the progress.ini file as well as the Registry
to maintain environment variables.
The make utility script calls the progress.ini file. The progress.ini file sets default values
for environment variables that define objects, libraries, and options required for building
executables in Windows. You can edit the progress.ini file to customize environments at
different sites.
When you install OpenEdge, the installation program automatically updates the Registry with
the information in the progress.ini file that is shipped to you. Progress Software recommends
that you maintain environment variables in both the progress.ini file and the Registry. If you
modify environment variables in the progress.ini file, you must update the information in the
Registry.
Although there are several methods for adding and deleting information from the Registry
directly, Progress Software recommends that you do not use these direct update methods.
Instead, maintain the Registry information by editing the progress.ini file and using the
INI2REG utility to update the Registry. This approach synchronizes the information in the
progress.ini file and the Registry without causing unintended edits to the Registry.
The make script has software and environment requirements, as follows:
• Verify settings for OpenEdge environment variables. Set DLC to the directory where you
have installed OpenEdge.
• Verify that the progress.ini file (located in the C:\\Progress\OpenEdge\bin directory,

by default) and the Registry include the appropriate environment variable settings for your
system.
A–5
• Verify that the Microsoft Visual C++ .NET compiler is installed on the system.
• Verify that the PATH environment variable contains the path to the C++ compiler and the
linker command (link.exe).
For more information about maintaining environment variables in the progress.ini file and
the Registry, and using the INI2REG utility, see the “Maintaining the Windows user
environment” section on page 4–2.
For information about Windows environment variables, see OpenEdge Getting Started:
Installation and Configuration for Windows.
Building a customized executable in Windows

This section contains instructions for building Windows 4GL client executables. The script is
located in the oebuild/make directory under the root of your OpenEdge installation.
To build a Windows 4GL client executable:
1. Log in as Administrator and open a command shell (Start→Run→cmd) on a system

where OpenEdge is installed.
2. Set the variable DLC to the OpenEdge installation directory. For example:
C:\> set DLC=C:\Progress\OpenEdge
3. Change directory to the OpenEdge make directory. For example:
C:\> cd %DLC%\oebuild\make
4. Set up the Microsoft VC++ environment by running vcvars32.bat. For example:
C:\Program Files\Microsoft Visual Studio .NET\Vc7\bin\vcvars32.bat
A–6
5. Make a backup copy the original link options script. For example:
copy build_prow32.link build_prow32.link.orig
6. Edit the link script to add customized objects and any necessary libraries to accommodate
them on the link line, and save the file. Available objects and libraries are located in
%DLC%\oebuild\obj.
7. Run the link command to create a customized 4GL client dynamic link library:
link @build_prow32.link
8. Back up the original 4GL client DLL. For example:
copy %DLC%\bin\prow32.dll %DLC%\bin\prow32.dll.orig
9. Copy the customized 4GL client DLL into the installed bin directory. For example:
copy %DLC%\oebuild\make\prow32.dll %DLC%\bin\prow32.dll
Troubleshooting
Following are some common errors that might occur when you attempt to link an executable:
• An object or library file cannot be found.
• An environment variable is not properly set.
• The system has insufficient memory or disk space.
For link utility error and troubleshooting information, see the documentation supplied with the
operating system.
A–7
A–8
B
R-code Features and Functions
R-code is the intermediate binary code that OpenEdge generates when it compiles 4GL source
files. This is the code that OpenEdge actually runs when it executes a procedure, whether from
session compiles or from permanently generated r-code (.r) files.
OpenEdge 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

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 4MB.
Table B–1 describes and lists the types, maximum size, and maximum number of segments in
an r-code file.
Table B–1: R-code segments (1 of 2)
Segment Max. Max.

type size number Description
Action code 4MB 4 for the Holds the actual executable code in the form of
main action cells. Action cells drive the 4GL
procedure, interpreter and contain the executable code for
4GL verbs. There are between one and four
1 per action code segments for the main procedure,
internal and one separate action code segment for each
procedure internal procedure.
Expression code 4MB 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 16MB of
executable expressions.
Text 4MB 1 per Holds all literal character strings for the r-code
language 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 4MB 1 Contains information required to initialize an

r-code file for execution, including database
and table references, variable definitions,
TEMP-TABLE and WORK-TABLE
definitions, a list of defined frames, time
stamps, and CRCs. There is one initial value
segment per r-code file.
B–2
Table B–1: R-code segments (2 of 2)
Segment Max. Max.

type size number Description
Frame 32K 1 per Contains layout information for a frame,

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 4MB 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 OpenEdge
Development: Debugging and
Troubleshooting.
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 an action code segment (for either the main procedure or an internal
procedure) by consolidating multiple 4GL statements into one. This can also increase the speed
of execution, because the interpreter executes only one action instead of several.
B–3
For example, you can reduce action code size by combining several consecutive assignment
statements into one ASSIGN statement. The following examples require the same amount of
expression code:
a = 1.
b = 2.
c = 3.
ASSIGN a = 1
b = 2
c = 3.
Note: The compiler creates up to four main action code segments, as needed. If, during
compilation, the main action code segments exceed the total size of all four segments,
the compilation fails.
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. OpenEdge 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.
R-code file segment layout

Figure B–1 shows the segment layout in an r-code file. A compiled procedure requires one
initial value segment, at least one main 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.
B–4
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 4MB. For more information about natural language translation for 4GL procedures, see
OpenEdge Development: Translation Manager.
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
Figure B–1: R-code file segment layout
B–5
R-code libraries
You can organize and store r-code files in a Progress 4GL r-code library. A 4GL 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.
contains r-code procedures that execute in shared memory.
For information about using the PROLIB utility to create r-code libraries, see Chapter 6,
“Managing R-code Libraries.”
R-code libraries and PROPATH

The following rules govern how standard and memory-mapped libraries interact with
PROPATH during a Progress 4GL session:
• The first time you run a member procedure from a standard or memory-mapped library
that is specified in the PROPATH, OpenEdge 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, OpenEdge must open the library. When OpenEdge opens a
standard library, it loads the procedure into local memory. When OpenEdge opens a
memory-mapped library, it maps the library in shared memory.
• When searching through directories and libraries in the PROPATH, OpenEdge 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 4GL 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),
OpenEdge displays an error message and the library remains open until you end your
Progress 4GL session. Otherwise, OpenEdge closes a standard library and unmaps a
B–6
• 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 4GL session.
• If you use libraries, OpenEdge accesses r-code files as if you had specified the Quick
Request (-q) startup parameter. That is, OpenEdge 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, OpenEdge reuses the procedure instead
of searching the PROPATH again. For more information about the Quick Request (-q)
startup parameter, see OpenEdge Deployment: Startup Command and Parameter
Reference.
R-code execution
OpenEdge 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, OpenEdge 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 on page B–8.
When executing an r-code procedure from a memory-mapped r-code library, OpenEdge

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 on page B–12.
For information about monitoring execution environment activity during a Progress 4GL client
session, see the “R-code execution environment statistics” section on page B–15.
For information about monitoring and optimizing r-code performance, see Chapter 5,
“Managing Client Performance.”
B–7
Standard r-code execution environment

At run-time, OpenEdge 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 OpenEdge 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 OpenEdge uses to dynamically swap r-code segments
in and out of the execution buffer.
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.
OpenEdge 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.
B–8
Figure B–2 shows the layout for the standard r-code execution environment.
R-code directory Segment descriptor table Execution buffer
cust.r cust.r Main action code R-code

segment
·
·
· ·
· R-code
· cust.r Text segment
cust.r Initial value

R-code
orders.r ·
·
segment
·
orders.r Main action code R-code

segment
·
·
· R-code
.srt File orders.r Initial value segment
·
· R-code
· segment
·
·
·
Figure B–2: Standard r-code execution environment
In Figure B–2, OpenEdge 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, OpenEdge uses the session sort file to swap
out the least-recently used segments. When OpenEdge 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.
B–9
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, OpenEdge 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. OpenEdge 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, OpenEdge attempts
to free space by swapping r-code segments already in the buffer to the session sort file. If
OpenEdge 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, OpenEdge does not
swap r-code segments to the session sort file unless you specify the PROLIB Swap
(-pls) startup parameter. By default, if OpenEdge 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 first
main action code segment and accesses the remaining segments directly from local
memory as required.
B–10
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. OpenEdge dynamically increases the directory size up to the maximum,
as required. Use the Hardlimit (-hardlimit) startup parameter to force OpenEdge 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. OpenEdge
dynamically increases the execution buffer size up to the maximum, as required. Use the
Hardlimit (-hardlimit) startup parameter to force OpenEdge 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 OpenEdge needs to allocate memory beyond that ceiling.
Standard r-code segment management
While OpenEdge loads an r-code file, all of its segments are locked in memory. After all
required segments are loaded for the procedure, OpenEdge unlocks all segments except its main
action code segments and text segment. These 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, OpenEdge attempts to free
space by swapping r-code segments already in the buffer to the session sort file. OpenEdge can
swap out any unlocked segments. OpenEdge removes these segments from the tail end of the
execution buffer chain, in least recently used (LRU) order.
If OpenEdge 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.
B–11
When OpenEdge needs a segment that has been swapped to the sort file, it reloads the segment
from the sort file into the execution buffer. However, OpenEdge keeps the reloaded segments
in the sort file.
Note: When accessing r-code procedures stored in a standard library, OpenEdge does not swap
r-code segments to the session sort file unless you specify the PROLIB Swap (-pls)
startup parameter. By default, if OpenEdge needs an r-code segment in a standard
library, it reloads the segment into the execution buffer from the library in local memory.
Memory-mapped r-code execution environment

At run time, OpenEdge 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.
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.
OpenEdge 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.
B–12
Figure B–3 shows the layout for the memory-mapped r-code execution environment.
Shared Memory
R-code Directory Segment Descriptor Table
Buffer
cust.r cust.r Main Action Code R-code
Segment
·
·
·
· ·
·
· ·
· cust.r Text R-code
Segment
cust.r Initial Value ·
·
orders.r · ·
· R-code
·
Segment
·
orders.r Main Action Code ·
· ·
· R-code
· Segment
·
orders.r Initial Value ·
·
·
R-code
·
·
Segment
·
·
·
Figure B–3: Memory-mapped r-code execution environment
In Figure B–3, OpenEdge 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
OpenEdge 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, OpenEdge 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.
B–13
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 first
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. OpenEdge dynamically increases the directory size up to the maximum,
as required. Use the Hardlimit (-hardlimit) startup parameter to force OpenEdge 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 OpenEdge needs a memory-mapped r-code segment, it executes the segment directly
from shared memory. OpenEdge 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. OpenEdge relies
on the operating system to manage the swapping of r-code segments in and out of shared
memory.
B–14
R-code directory management

If the r-code directory is full when loading a new standard or memory-mapped r-code file,
OpenEdge can reuse existing directory entries for any r-code files no longer in use.
To reuse an r-code directory entry, OpenEdge 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.
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, OpenEdge 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 OpenEdge needs to reload a standard r-code file, it follows the standard execution
sequence. When OpenEdge needs to reload a memory-mapped r-code file, it follows the
memory-mapped execution sequence.
R-code execution environment statistics

You can monitor execution environment activity using the Statistics (-y) and Segment Statistics
(-yd) startup parameters. These parameters cause OpenEdge 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 OpenEdge
For information about monitoring and optimizing r-code performance, see Chapter 5,
“Managing Client Performance.”
B–15
Figure B–4 through Figure B–8 show sections of client.mon output generated with the -yd
startup parameter.
In Figure B–4, the “Progress 4GL 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.
Wed Mar 23 10:38:04 1994

R-code directory size
Progress client startup options:
-A = 0 | -d = mdy | -D = 100 | -h = 7
.
.
.
Figure B–4: Progress 4GL client startup options for –yd
In Figure B–5, the “Execution buffer map” section shows the order and size of procedures
loaded into the execution buffer.
Execution buffer map: 11:27:28

Size Name
---- ----
3813 _edit.r
R-code files listed in
182871 adeedit/_proedit.r
order of execution with
1321 adecomm/_setcurs.r
sizes in bytes
·
·
·
Figure B–5: Execution buffer map for –yd
In Figure B–6, 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 (“Int-Proc Action”), number (5), and size (1364 bytes).
B–16
Per procedure temp file access statistics:

Segment Read/Write Times Bytes
------------ --------------- -------- -------
_edit.r
adeedit/_proedit.r R-code files listed in
E-code seg: 1 Read 1 44476 order of execution
E-code seg: 1 Write 1 44476 showing segments
Int-Proc Action: 5 Read 1 1364 read and written to
Int-Proc Action: 5 Write 1 1364 the session sort file
·
·
·
Figure B–6: 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.
B–17
In Figure B–7, 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
(“Int-Proc”), number (2), and size (816 bytes).
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 R-code files listed in order
adeedit/_proedit.r of execution showing all
Initial 1 4368 segments loaded during the
Action 1 21708 session
E-Code: 1 1 44476
Int-Proc: 1 1 496
Int-Proc: 2 1 816
.
.
.
Figure B–7: Procedure segment information for –yd (Part 1)
B–18
Thus, if there are three internal procedure action segments in appedit/_proedit.r, they are
listed in order (Int-Proc: 1 through 3). Likewise, multiple main action code segments are listed
in order (A-Code: 1 and 2). The number of segments for each entry is always 1. Note that the
“Initial” segment has no segment number, because there is never more than one of this segment
type per r-code file.
In Figure B–8, the listed sections provide memory and segment usage summaries. The -y startup
parameter also generates this information.
-----------------------------------------
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
------------------------------------------------
Figure B–8: 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.
B–19
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.
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.
Code page compatibility

The Internal Code Page (-cpinternal) startup parameter determines the internal code page that
OpenEdge 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 session’s internal code page, OpenEdge performs an
in-memory conversion of the r-code text segments to the session’s 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, OpenEdge 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.
B–20
Since r-code procedures in memory-mapped procedure libraries are read-only, OpenEdge

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, OpenEdge 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 OpenEdge Deployment: Startup Command and
Database CRCs and time stamps

At run time, OpenEdge 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. OpenEdge supports two techniques for checking this
compatibility—time stamp validation and cyclic redundancy check (CRC) validation. Each
technique prevents you from running unauthorized or data-incompatible procedures against a
particular database environment.
Time stamp validation

For each table, OpenEdge maintains a time stamp indicating when the schema was last changed.
When compiling a procedure, OpenEdge inserts the time stamp into the r-code for each database
table accessed by the procedure. This time stamp is the value of the _Last-change 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, OpenEdge 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, OpenEdge uses CRC validation.
Note: The Time Stamp (-tstamp) parameter is obsolete, and is supported only for backward
compatibility.
B–21
CRC validation
For each table, OpenEdge computes a CRC value (database CRC) from selected elements of
the table metaschema. When compiling a procedure, OpenEdge 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 table’s schema was created or updated.
R-code execution with CRCs
When executing a procedure using CRC validation, OpenEdge 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.
Thus, if the time stamps match, OpenEdge assumes that the database schema and r-code must
be compatible. Otherwise, the CRCs determine the outcome.
compatibility.
B–22
CRC calculation
Table B–2 lists the metaschema fields that are involved in each CRC calculation.
Table B–2: Metaschema fields in CRC calculation
Metaschema table
_File _Field _Index _Index–Field
_File-Name _Field-Name _Index-Name (_Field-Name)1

_DB-lang _Data-Type _Unique _Ascending
_dtype _num-comp _Abbreviate
_sys-field _Unsorted
_field-rpos
_Decimals
_Order
_Extent
_Fld-stdtype
_Fld-stlen
_Fld-stoff
_Fld-case
1
The _Field–Name for index fields is referenced in the _Field table using _Field–recid in _Index–Field.
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.
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.
B–23
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.
B–24
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 B–2 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 user’s 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:
1. Install a copy of the production database from the target site in your development
environment.
B–25
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 OpenEdge Data Management: Database
Administration.
3. Apply the incremental data definition file to your copy of the production database.
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 an OpenEdge
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, OpenEdge 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 OpenEdge Data
B–26
CRC and time stamp availability
During compilation, OpenEdge 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, OpenEdge 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.
R-code CRCs and procedure integrity

When OpenEdge 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 4GL 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 RCODE–INFO 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
RCODE–INFO 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.
B–27
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 (_File-Trig for table triggers and _Field-Trig 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 OpenEdge Development: Basic
Development Tools (Character only) and, in graphical interfaces, the on-line help for the Data
Dictionary.
Validating CRCs for schema triggers

When a database event occurs in your application (such as creating a record or assigning a field),
OpenEdge checks whether the CRC of the corresponding trigger procedure matches the CRC
in the trigger metaschema record. If it matches, OpenEdge executes the procedure. Otherwise,
OpenEdge returns a run-time error.
Trigger CRC validation works for both r-code and source versions of a trigger procedure. For
source versions, OpenEdge calculates the CRC during the session compile.
RCODE–INFO handle
The RCODE-INFO 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.
B–28
Getting the r-code CRC
To read the r-code CRC from an r-code file, first set the FILE-NAME attribute of the RCODE-INFO
handle to the pathname of your r-code file. Then read the value of the CRC-VALUE attribute:
DEFINE VARIABLE rCRC AS INTEGER.

RCODE-INFO:FILE-NAME = "sports/crcust.r".
rCRC = RCODE-INFO:CRC-VALUE.
Note: The RCODE-INFO handle cannot read the r-code CRC from a session compile. For source
(.p) procedures, the CRC-VALUE attribute returns the unknown value (?).
Example — Verifying application r-code integrity
Be sure to verify the integrity of your application’s r-code.
To 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.
B–29
4. Run a procedure that contains code like this to build the RcodeSecurity table:
DEFINE VARIABLE i AS INTEGER.

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".
5. At each point where you call a secure procedure in your application, insert this code:
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.
B–30
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:
trload.p (1 of 2)
/* trload.p */
DEFINE VARIABLE i AS INTEGER.
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 doesn’t 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.
B–31
trload.p (2 of 2)
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.".
Note: As this example shows, you must use the RECID function rather than the ROWID function
to reference metaschema table record locations.
B–32
C
OpenEdge Application Limits
The hardware and operating system version on which applications run often determines the
limits for applications. This appendix lists the limits you must consider when developing an
application. The limits are organized in the following sections:
• Input/output limits
• Sorting limits
• Name limits
• Compiler limits
For information about database limits, see OpenEdge Data Management: Database
Administration.
Input/output limits
Table C–1 lists the maximum number of characters you can use for input and output devices
(unless otherwise specified).
Table C–1: Input/output limits
Operating
Device system Limit
Terminal line width UNIX 80 to 132 columns.
Windows 80 columns.
Printer line width All 1 to 255 columns.
Export file All 1 to 3,000 characters per field; 32K bytes per
record.
Import file All 1 to 3,000 characters per field; 32K bytes per
record.
Streams All 1 to 5 streams per procedure.
Note: Windows NT batch files limit you to no more than nine (9) input parameters. This is a
Windows limitation. Actual executables handle more than nine.
C–2
Sorting limits
Table C–2 lists the limits for sorting data (unless otherwise specified).
Table C–2: Sorting limits
Category Limit
Levels 1 to 16 columns or expressions.
Size Typically, 1 to 197 bytes (that is, approximately 200 bytes minus some
overhead per column and expression). The size limit depends on the
number of columns and expressions you are sorting. Each column and
expression uses up some number of available bytes.
C–3
Name limits
Table C–3 lists the maximum number of characters you can use in names (unless otherwise
specified).
Table C–3: Name limits
Operating
Name type system Limit
External procedure UNIX 1 to 58 characters, plus a 2 character

extension.
Windows 1 to 255 characters, plus a 2 character

extension.
Pathnames All 1 to 255 characters.
Table All 1 to 32 characters; can consist of any

Field combination of letters (a-z or A-Z),
Field-level widget numbers (0-9), and these special
Index characters: # $ - _ % &
Variable
Names must begin with a letter.
Run-time procedure parameter
Internal procedure All No set limit; can consist of any

Block label combination of letters (a-z or A-Z),
Query numbers (0-9), and these special
Frame widget characters: # $ - _ % &
Browse widget
Menu widget
Submenu widget
Menu item widget
Stream All 1 to 12 characters; can consist of any

combination of letters (a-z or A-Z),
numbers (0-9), and these special
characters: # $ - _ % &
Tables in the convmap file: All 1 to 20 characters; can consist of any

combination of letters (a-z or A-Z),
Attribute table numbers (0-9), and the hyphen
Collation table character (-).
Conversion table
Case table
C–4
Compiler limits
Table C–4 lists the limits for each element of the Compiler (unless otherwise specified).
Table C–4: Compiler limits
Element Limit
Variables 32,000 bytes for UNDO and NO-UNDO variables per external procedure.
32,000 bytes for local UNDO and local NO-UNDO variables per internal
procedure or trigger block.
Statements 1 to 32,000 characters per statement. Use the Input Characters (-inp)
startup parameter to limit the number of characters allowed in a single
statement.
The number of tokens allowed per statement is limited only by the
available system resources. Each word or special character, such as a
parenthesis, plus sign, and minus sign, counts as one token. Use the
Token (-tok) startup parameter to limit the number of tokens allowed
in a single statement.
Frames 1 to 320 characters.
Nested blocks 1 to 255 blocks, including called procedures. Use the Nested Blocks
(-nb) startup parameter to limit the number of nested blocks allowed
in a procedure.
For more information about the Input Characters (-inp), Token (-tok), and Nested Blocks (-nb)
startup parameters, see OpenEdge Deployment: Startup Command and Parameter Reference.
C–5
C–6
D
Toolkit Contents and Reference
This appendix provides reference information for the Developer’s Toolkit utilities as described
in the following sections:
• Toolkit templates
• Toolkit utilities summary

Toolkit templates
You can use the templates provided with the Developer’s Toolkit, tailor them to the needs of
your application, and supply them with your application. The following templates are located
in the install-dir/toolkit/samples directory:
• runmenu — Starts single-user OpenEdge session.
• multmenu — Starts multi-user OpenEdge session.
• runbatch — Starts single-user batch OpenEdge session.
• multbat — Starts multi-user batch OpenEdge session.
• newdb — Makes a copy of a basic application database.
• strtsrvr — Starts a multi-user OpenEdge server.
• stopsrvr (supplied on UNIX only) — Stops a multi-user OpenEdge server.
• deldb — Deletes a database.
• dumpdb — Dumps an application database.
• reloaddb — Loads an application database.
• trimlog — Discards old information from the database log file.
• upgrade — Upgrades an existing application with new data definitions and/or procedures.
D–2
Toolkit utilities summary

Table D–1 provides a summary of the different utilities provided with the Developer’s Toolkit.
Table D–1: Toolkit utilities
Utility Description
DBRSTRCT Defines the type of access that all users, including you, have
to your application.
MKDUMP Creates procedures a user runs to dump and reload your

database.
XCODE Encrypts source code for shipment to customer sites.
_tlr Lets you tailor the environment variables used in UNIX

scripts.
D–3
DBRSTRCT utility
Defines the access that all users, including you, have to your application database.
Syntax
dbrstrct database-name
database-name
The name of the database for which you want to restrict access.
Notes • Before you define database access, it is very important that you make a copy of your
application database and precompile all of your application procedures against that
database. For example, suppose you do not precompile a procedure that updates the
database and then you deny update access to the database. You will be unable to compile
that procedure against the newly restricted database.
• Keeping a copy of the unrestricted database also lets you redefine the database restrictions
at a later time. To redefine database restrictions, dump the data from the restricted
database, make a copy of the unrestricted database, define restrictions on that database
copy, and reload the data into it.
Example Sample DBSTRCT Command:
dbrstrct mydb
D–4
As you can see from the options listed in Figure D–1, you can define access globally, for all
files, or you can define access on a file-by-file basis. Any restrictions you define affect all users,
including yourself.
Figure D–1: Database Restriction Utility
If you choose option 1 and deny update access but permit query access, no users, including
yourself, will have update access to files or fields in the database, unless that update is being
done by a procedure that was precompiled against the database before the database was
restricted. However, all users will be able to write procedures that query the database.
D–5
MKDUMP utility
Creates a set of file dump and file load procedures for a database.
Syntax
mkdumpc database-name
database-name
The name of the database for which you want to create dump and load procedures.
Note • The filedump.p and fileload.p procedures created by mkdump are meant to run from an
application menu inside OpenEdge. If you plan to have end users run these procedures
directly from the operating system level, you must first modify filedump and fileload.
Comments in the dumpdb and reloaddb scripts or batch files explain these modifications.
Example Sample MKDUMP Command:
mkdump mydb
This command creates two main Progress 4GL procedures: filedump.p and fileload.p. In
addition, it creates two subdirectories: dmpprocs and ldprocs. The dmpprocs subdirectory
contains a single dump procedure for each file in the database; the ldprocs subdirectory
contains a single load procedure for each file in the database.
An end user runs the filedump.p procedure to dump the database. That procedure runs the
procedures in the dmpprocs subdirectory. To load the database, the user runs fileload.p, which
runs the procedures in the ldprocs subdirectory.
D–6
XCODE utility
Encrypts Progress 4GL procedures and include files using either the default or a specified
encryption key.
Syntax
xcode [ -k key ][ -d directory ] { files | - }
key
The encryption key. The key is an ASCII character string up to eight characters long. If key
is not supplied, the default key supplied by OpenEdge is used.
directory
The directory where the encrypted files are placed. The specified directory must be
different from the source directory, because each encrypted file retains the name of its
original source file. Existing files in directory are overwritten only if they are encrypted.
files
The relative pathnames of files to be encrypted. The pathnames supplied are appended to
directory. Therefore, you should build a directory structure exactly parallel to the source
directory structure, move to the source root, and specify relative pathnames.
- SYS$INPUT
Indicates that source filenames are to be read from standard input.
Example
cd /applr001
xcode -k key1 -d applx001 *.p
find applf002/*.p | xcode -k key2 -d applx002 -
D–7
Notes • You must create the full directory structure desired for your encrypted files before running
XCODE; XCODE does not create any directories implied by directory or files.
• The encryption algorithm is based on known techniques; therefore, the code is breakable.
If your source code is highly sensitive, consider additional security methods.
• Encrypted include files must use the same key as any procedure that includes them.
• Decrypt encrypted procedures with the XCODE option on the COMPILE statement. (The
XCODE option is not required if the procedures were encrypted with the default key.) The
XCODE option requires the same key used with the XCODE utility. Decryption is
incremental during compilation. Having the decryption key does not enable you to
examine a decrypted version of the source code. OpenEdge Development: Progress 4GL
Reference describes the COMPILE statement in detail.
D–8
_tlr Module
Changes the default values of environment variables as defined in various scripts.
Syntax
_tlr var-name replace-value file-name ...
_tlr var-name replace-value -< file-list
The first syntax format processes one file at a time. The second processes a list of files read from
a file.
var-name
A constant character string that identifies the environment variable whose value you want
to modify.
replace-value
A constant character string that identifies the new default value of the environment
variable.
file-name
The name of the file in which you want to modify the default value of the environment
variable.
file-list
The name of a file containing a list of filenames in which you want to modify the value of
the environment variable.
Example Several of the scripts provided with OpenEdge and the Toolkit name the DLC environment
variable as follows:
DLC=${DLC-/usr/dlc}
In this example, if the value of the DLC environment variable has been defined, the script uses
the value of that variable. Otherwise, it uses /usr/dlc as the value of DLC.
D–9
To change the default value of the DLC variable to /tmp/dlc in a script named test.dat, use
this command:
_tlr DLC /tmp/dlc test.dat
This command changes the environment variable line in test.dat from:
DLC=${DLC-/usr/dlc}
to:
DLC=${DLC-/tmp/dlc}
D–10
Index
A B
Action code segment, r-code B–2 Blank user IDs 3–7
Application databases buildenv scripts

modifying 11–5 to 11–11 and the PROBUILD utility A–2
maintaining 4–39
Application deployment sample 4–40
CRC validation B–23
time stamp validation B–23 BUNDLE utility 8–2, 12–4 to 12–11
Application security. See Security

C
Applications
accessing databases 2–1 client.mon files 5–7
administration 1–3
deployment 1–2 Colors. See progress.ini file,
limits C–1 PROTERMCAP file
maintaining user environments
in Windows 4–2 Compiler limits C–5
on UNIX 4–39
performance 5–1 Compile-time security
defined 3–1
Auto-connect feature 2–12 establishing 3–2
CONNECT statement 2–7
handling connection denials 2–15
precedence over auto-connect 2–13
Connecting disadvantages B–26

at startup 2–6 R-code
connection modes 2–4 RCODE-INFO handle B–28
connection parameters 2–5 schema triggers B–28
connection techniques 2–5 r-code B–27
from the Data Administration tool 2–10 See also R-code CRCs
from the Data Dictionary 2–8 application procedures B–28
handling connection denials 2–15 calculation B–27
non-Progress databases 2–14 schema triggers B–28
over wide area networks 2–16
reducing connection times 2–16 Cyclic redundancy check (CRC)
specifying logical database names 2–3 and r-code 3–2
with auto-connect 2–12
with the CONNECT statement 2–7
D
Connection parameters. See Startup
parameters -D startup parameter, Directory Size B–11,
B–14
Connection security, defined 3–1
Data Administration tool
CRC. See Cyclic redundancy check connecting databases 2–10
defining compile-time security 3–3
CRC calculation determining privileges 3–7
database disconnecting databases 2–19
metaschema fields B–23 selecting a working database 2–18
tables B–23
r-code B–27 Data Dictionary
connecting databases 2–8
CRC compared to time stamps, r-code defining compile-time security 3–3
availability B–27 determining privileges 3–7
disconnecting databases 2–19
CRC validation B–22
performing security administration 3–9
CRC. See Cyclic redundancy check selecting a working database 2–17
temporary changes (.trp) file 5–13
CRC-based r-code
Database CRCs B–21
upgrading applications 11–5
database changes affecting B–25
Cyclic redundancy check
Databases
compared to time stamps B–23
database B–21 connecting 2–2
CRC B–21
advantages B–26
calculation B–23 code validation B–22
disconnecting 2–18
changes affecting B–25
code validation B–22 file security 3–1
compared to time stamps B–23 logical names 2–3
non-Progress 2–14
deployment B–25
restricting access 12–15
Index–2
Index
selecting a working database 2–17, 2–18 E

startup without connecting 2–17
temporary files 5–13 Edit buffer contents files 5–13
time stamps B–21
Encrypted source code 9–4 to 9–6
DataServers 11–5
application databases 11–5
.dbi files 5–13 steps for deployment 10–7
DBRSTRCT utility 8–2, 9–8, 10–11, 10–16,
Encrypting procedures 12–2 to 12–4
12–15 to 12–16, D–4 to D–5
Encryption keys 9–6
Debugger segment, r-code B–3
Environment characteristics. See
Default window characteristics. See
progress.ini file
progress.ini file
Environment variables
Defining debugger buttons. See progress.ini
UNIX A–2
file
Windows A–5
Defining debugger macros. See progress.ini Environment variables, specifying 4–36
file
Execution buffer
deldb template D–2 available memory B–11
ceiling
Deploying applications
described B–11
steps 10–1 to 10–19
size B–11
Deployment described B–8, B–12
See also Applications Execution environment
process 1–2
limits B–11, B–14
requirements 1–2 r-code B–8, B–12
services 1–2 typical layout B–9, B–13
tasks 1–3
statistics B–15
Direct printing, defined 7–2 .srt file access B–16
execution map B–16
Directory Size (-D) startup parameter B–11, segment information B–18
B–14 startup parameters B–16
summary information B–19
Disconnecting databases 2–18
with the Data Administration Tool 2–19 Expression code segment, r-code B–2
with the Data Dictionary 2–19
Extended character support
dumpdb template D–2 with progress.ini file entries 4–34
with PROTERMCAP file entries 4–66
Dumping 12–12 to 12–14
Index–3
F K
File descriptor limits 2–2 KERMIT 10–4
File system recovery program (fsck) 5–14 Key bindings. See progress.ini file,
PROTERMCAP file
Files
buildenv scripts A–2 Keymapping
client.mon 5–7 See also progress.ini file,
distributing files on a network 5–11 PROTERMCAP file
edit buffer contents files 5–13 Version 6 4–55
local before-image files 5–13
parameter files 2–5
printcap files 7–6 L
printer control files 7–14
proc.mon 5–7 .lbi files 5–13
procedure library (.pl) files 6–6
progress.ini file 4–9, 5–12 Libraries B–6
PROTERMCAP file 4–41 See also PROLIB utility, R-code
sort (.srt) B–8 advantages 5–2
sort (.srt) files 5–3, 5–13 and code pages 6–23
temporary changes files 5–13 and PROPATH 6–9
temporary files 5–13 and r-code performance 5–2
temporary table files 5–13 listing contents 6–17
memory and network considerations
Fonts. See progress.ini file 6–10
memory-mapped format 6–2
Frame segment, r-code B–3 advantages 6–2
fsck (file system recovery program). See generating 6–14
loading and executing 5–4, 6–5
File system recovery program (fsck)
overview 6–2
PROPATH B–6
running procedures 6–6
I using a relative pathname 6–7
using an absolute pathname 6–6
IMAGE environment variable A–3 setting up 6–6
Index modifications 9–6 standard format 6–2
adding files 6–15
INI2REG Utility advantages 6–2
See also Registry compressing files 6–21
command line interface 4–4 creating 6–13
deleting files 6–16
Initial value segment, r-code B–2, B–4 extracting files 6–19
Input/output device limits replacing files 6–16
number of characters C–2 tuning 5–6
Internationalization 9–4, 9–8 LIBRARY function 6–8
Index–4
Index
licensing A–2 N
Limits
Name limits
compiler C–5
number of characters C–4
input/output devices
number of characters C–2 newdb template D–2
name limits
number of characters C–4 Non-English character support 4–66
sorting C–3
Non-Progress databases 2–14
Loading 12–12 to 12–14
Local before-image files 5–13, 5–14 O

Logical database names 2–3
Operating system security 3–8
changing with the ALIAS statement 2–4
Output routing 7–10
LP Scheduler 7–5
OUTPUT THROUGH statement 7–4, 7–7
lp spooler, defined 7–5
OUTPUT TO statement 7–3, 7–6
lpd daemons, defined 7–6
PRINTER option 7–3
lpr spooler, defined 7–5
P
M
Parameter files. See Startup parameters
make utility A–1 Performance
Maximum Memory (-mmax) startup distributing files on a network 5–11
parameter B–11 monitoring r-code activity 5–7
procedure loading and execution 5–2
MEMBER function 6–8 reducing database connection times 2–16
sorting 5–15
Memory-mapped library. See Libraries temporary file I/O 5–14
using r-code libraries 5–2
Metaschema tables, CRC calculations B–23
Permissions
MKDUMP utility 8–2, 12–12, D–6 See also Security
blank user ID 3–7
-mmax startup parameter, execution buffer CAN-CREATE 3–4
ceiling B–11 CAN-DELETE 3–4
CAN-DUMP 3–5
multbat template D–2
CAN-LOAD 3–5
multmenu template D–2 CAN-READ 3–4
CAN-WRITE 3–4
table 3–8
.pge files 5–13
Index–5
Portability progress.ini file

encrypted source 9–5 defining debugger buttons 4–32
r-code 9–7, 9–9 defining debugger macros 4–32
unencrypted source 9–3 defining key bindings 4–30
defining key mappings 4–34
Portable r-code B–20 maintaining 4–9
search path 4–8
Print queues 7–2 sections
printcap files 7–6 colors section 4–22
debug-buttons section 4–32
Printers debug-init section 4–31
administration 7–1 debug-macros section 4–32
configuration 7–14 default window section 4–24
control files 7–14 fonts section 4–25
control sequences 7–14 keymap section 4–34
defaults 7–3, 7–4 keys section 4–32
startup section 4–11
Printing 7–1 winchar colors section 4–29
and UNIX networks 7–7 winchar default window section 4–29
direct 7–2 winchar keys section 4–30
in Progress 7–2 winchar startup section 4–26
in Windows 7–9 specifying colors 4–22, 4–29
on UNIX 7–5 specifying default window characteristics
output routing schemes 7–10 4–24, 4–29
OUTPUT THROUGH statement 7–4, specifying environment characteristics
7–7 4–11, 4–26
OUTPUT TO statement 7–3, 7–6 specifying environment variables 4–36
pagination 7–4 specifying fonts 4–25
PUT CONTROL statement 7–14 specifying key bindings 4–32
spooled 7–2
uux command 7–8 PROLIB utility 6–1, B–6
See also Libraries, R-code
proc.mon files 5–7 parameters 6–11
sample commands 6–22
Procedure files, distributing 5–12 using 6–11
using wild cards 6–13
Procedure library (.pl) files. See Libraries,
R-code PROLOAD environment variable A–2, A–5
Procedures PROTERMCAP file

distributing source files 5–12 copying a UNIX termcap file 4–68
r-code integrity B–27 copying an existing terminal entry 4–70
example B–29 defined 4–41
running from a library 6–6 general syntax 4–43
keyboard mappings 4–59
Product upgrades 11–12 maintaining 4–41
non-English character support 4–66
Progress system files, distributing 5–11
PROTERMCAP environment variable
4–70
Index–6
Index
setting the terminal type 4–69 text segment B–2

size restrictions 4–42 See also Libraries
specifying colors 4–55 and code pages 6–23
syntax 4–43 and cyclic redundancy check (CRC) 3–2
terminal capabilities entries 4–47 application databases 11–9 to 11–12
for cursor motion 4–57 defined 5–2
terminal name entries 4–46 directory
Vermont Views 4–52 defined 5–3
size 5–5
PROUTIL utility 3–2 execution buffer, defined 5–3
execution environment 5–3
PUT CONTROL statement 7–14
from a file 5–3, 6–3
from a memory-mapped library 5–4,
R 6–5
from a standard library 5–4, 6–4
R-code 9–7 to 9–10 monitoring activity 5–7
action code segment B–2, B–3 performance 5–11
CRC B–27 segment descriptor table, defined 5–3
debugger segment B–3 session sort file, defined 5–3
defined B–1 shared memory buffer, defined 5–3
directory steps for deployment (CRC) 10–11 to
described B–8, B–12 10–16
management B–15 time-stamp 10–16 to 10–19
execution B–8 tuning 5–5
available memory B–12
environment limits B–11, B–14 R-code CRC B–27, B–28
environment statistics B–15 procedure integrity B–27, B–29
segment management B–11, B–14 RCODE-INFO handle B–27
sequence B–10, B–13 schema triggers
execution buffer, described B–8, B–12 example B–31
execution environment B–8, B–12 B–29
typical layout B–9, B–13
expression code segment B–2 RCODE-INFO handle, R-code CRC B–28
factors affecting size B–3
features B–2, B–7 R-code directory
files described B–8, B–12
segment layout B–4 management B–14, B–15
frame segment B–3 size B–11
initial value segment B–2, B–4
R-code file, segment layout B–5
memory-mapped execution environment
B–12 R-code segments B–2
portability B–20
segment descriptor table, described B–8, Registry
B–12 See also INI2REG Utility
segment types B–2 updating 4–2
standard execution environment B–8
structure B–2 reloaddb template D–2
Index–7
Remote printing Segment Statistics (-yd) parameter B–15

setting up 7–8
Segmented r-code B–2
runbatch template D–2 types B–2
runmenu template D–2 Session files, distributing 5–12
Run-time security Sort (.srt) files 5–3, 5–13, B–8, B–11

defined 3–1 r-code execution B–10, B–13
establishing permissions tables 3–8
Sorting
improving performance 5–15
S limits C–3
Schema cache files 2–16 Source files, distributing 5–12
Schema holder, defined 2–14 Spooled printing, defined 7–2
Schema security, defined 3–1 Spoolers

lp 7–5
Schema triggers lpd daemon 7–6
auto-deployment example B–31 lpr 7–5
R-code CRC B–28
.srt file. See Sort (.srt) file
RCODE-INFO handle B–28
setting B–28 .srt files 5–13
validating B–28
r-code CRC B–27 Standard library. See Libraries
deployment B–31
Startup parameters
SEARCH function 6–8 Database Name (-db) 2–4
Directory Size (-D) 5–5
Security
Host Name (-H) 2–4
See also Permissions Input Characters (-inp) C–5
administration 3–9 Internal Code Page (-cpinternal) 6–14,
application 3–1
6–23
blank user ID 3–7 Logical Database Name (-ld) 2–3
compile-time 3–2 Maximum Memory (-mmax) 5–5, 5–9
connection 3–1
Merge Number (-TM) 5–15
database file 3–1 Nested Blocks (-nb) 5–5, C–5
field-level 3–2 Number of Users (-n) 2–15
operating system 3–8
Parameter File (-pf) 2–5
run-time 3–8 Password (-P) 3–7
schema 3–1 Printer (-o) 7–3, 7–4, 7–10
table-level 3–2 PROLIB Memory (-plm) 5–6, 6–10
Segment descriptor table, described B–8, PROLIB Swap (-pls) 5–4, 5–6, 6–4, 6–10
B–12 Quick Request (-q) 6–9
R-code In Code Page (-cprcodein) 6–23
Segment layout, r-code file B–5 Save Temp Files (-t) 5–14
Schema Cache File (-cache) 2–16
Segment management, r-code B–11, B–14 Segment Statistics (-yd) 5–7, 5–10
Index–8
Index
Service Name (-S) 2–4 TERMINAL function 4–69

Single-user Mode (-1) 2–4
Speed Sort (-TB) 5–15 Terminals
Stack Size (-s) 5–5 See also PROTERMCAP file
Statistics (-y) 5–7, 5–8 UNIX stty control functions 4–65
Statistics with Cross-reference (-yx) 5–7
Statistics with CTRL-C (-yc) 5–7 Text segments
Temporary Directory (-T) 5–12, 5–14 r-code B–2
Token (-tok) C–5 translation B–4
User ID (-U) 3–7 Time stamps
Windows Passthrough Printing (-wpp)
compared to CRC B–23
7–9
database changes affecting B–24
Statistics (-y) startup parameter B–15 deployment B–25
validation B–21
stopsrvr template D–2
Time-stamp-based r-code
Storage media upgrading applications 11–4
space used 9–3
_tlr module D–9
strtsrvr template D–2
trimlog template D–2
T .trp files 5–13
Table permissions
CAN-CREATE 3–4
U
CAN-DELETE 3–4
Unencrypted source 9–2 to 9–4
CAN-DUMP 3–5
CAN-LOAD 3–5 steps for deployment 10–4 to 10–6
CAN-READ 3–4
CAN-WRITE 3–4 Unicode 4–20
Tables UNIX environment variable A–2
CRC calculation B–23
Upgrade templates 11–7, D–2
Templates D–2
Upgrades
Temporary changes files 5–13
Progress products 11–12
Temporary files User count, exceeding 2–15
defined 5–13
distributing 5–12 User environments
maintaining in Windows 4–2
Temporary table files 5–13
maintaining on UNIX 4–39
Index–9
Utilities W
See also Data Administration tool, Data
Dictionary Wide area networks, connecting 2–16
BUNDLE. See BUNDLE utility
DBRSTRCT. See DBRSTRCT utility Wild cards
INI2REG 4–2 and the PROLIB utility 6–13
MKDUMP. See MKDUMP utility
PROLIB 6–1, 6–11 Windows icons 4–37
PROUTIL 3–2
XCODE. See XCODE utility Working databases, selecting 2–17
uux command 7–8

X
XCODE utility 8–2, 12–2 to 12–4, D–7
Y
-y startup parameter, statistics B–15
-yd startup parameter, Segment Statistics

B–15
Index–10

DP 4 GL

Uploaded by

Copyright:

Available Formats

DP 4 GL

Uploaded by

Document Information

Original Title

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

DP 4 GL

Uploaded by

Copyright:

Available Formats

OpenEdge Deployment:

Managing 4GL Applications

Product Code: 4655

Part I 4GL and R-code Deployment and Management

1. Progress 4GL Client Deployment Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–1

2. Managing Client Access to Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–1

3. Maintaining Application Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–1

4. Maintaining User Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–1

5. Managing Client Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–1

6. Managing R-code Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–1

7. Managing Print Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–1

Part II Developer’s Toolkit

9. Choosing a Code Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9–1

10. Initial Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10–1

11. Upgrades. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11–1

12. Deployment Topics and Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–1

Part III Appendices

A. Building OpenEdge 4GL Executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–1

B. R-code Features and Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B–1

C. OpenEdge Application Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C–1

D. Toolkit Contents and Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D–1

• Examples of syntax descriptions

Chapter 1, “Progress 4GL Client Deployment Overview”

Chapter 2, “Managing Client Access to Databases”

Chapter 3, “Maintaining Application Security”

Describes how OpenEdge implements application security, including designating security

Chapter 4, “Maintaining User Environments”

Describes how to maintain OpenEdge user interface environments in Windows and on

Chapter 5, “Managing Client Performance”

Chapter 6, “Managing R-code Libraries”

Chapter 7, “Managing Print Devices”

Describes how to set up print devices on OpenEdge-supported operating systems.

Part II, Developer’s Toolkit

Provides an introduction to the Developer’s Toolkit.

Chapter 9, “Choosing a Code Format”

Chapter 10, “Initial Deployment”

Chapter 11, “Upgrades”

Describes how to upgrade Progress 4GL applications.

Chapter 12, “Deployment Topics and Tasks”

Part III, Appendices

Appendix A, “Building OpenEdge 4GL Executables”

Appendix B, “R-code Features and Functions”

Appendix C, “OpenEdge Application Limits”

Appendix D, “Toolkit Contents and Reference”

Bold Bold typeface indicates commands or characters the user types, or

Italic Italic typeface indicates the title of a document, provides

KEY1-KEY2 A hyphen between key names indicates a simultaneous key

Fixed width A fixed-width font is used in syntax statements, code examples,

Fixed-width italics Fixed-width italics indicate variables in syntax statements.

Fixed-width bold Fixed-width bold indicates variables with special emphasis.

UPPERCASE Uppercase words are Progress® 4GL language keywords.

This icon (three arrows) introduces a multi-step procedure.

This icon (one arrow) introduces a single-step procedure.

[] Large brackets indicate the items within them are optional.

[] Small brackets are part of the Progress 4GL language.

| A vertical bar indicates a choice.

Examples of syntax descriptions

ACCUM aggregate expression

FOR EACH Customer:

PROLIB "%DLC%\src\prodoc.pl" -extract prodoc/langref/.

prolib $DLC/src/prodoc.pl -extract prodoc/interfaces/.