OpenEdge Development: Progress 4GL Handbook

Preface

This Preface contains the following sections:

Purpose
Audience
Organization
Typographical conventions
Examples of syntax descriptions
Example procedures
OpenEdge messages

Purpose

This book is a comprehensive tour of all the essential elements of the Progress 4GL. By the time you complete it, you will be competent to build thoroughly modern applications that take advantage of most of the language’s features. And you will use the language to build powerful business application logic, not just the toy demonstration windows you find in other language tutorials. Progress is not a toy. It’s a tool for serious developers who have serious business problems to solve.

There are a lot more specifics to many of the language statements, keywords, and options than this book covers. Therefore, you should always refer to the product documentation for more information. Where the language is concerned, you should refer to the OpenEdge Development: Progress 4GL Reference. This three-volume set has a complete description of all of the 4GL’s methods, attributes, and events in Volume I and an alphabetical listing of all the language keywords on Volumes II and III. Always look to it for more details on any topic covered in this book.

Audience

This book is written for two different kinds of audiences. The first group consists of existing Progress developers who might have created applications in earlier releases of the product, when many of the more recent extensions to the language were not yet available. These extensions include:

Statements to define a Graphical User Interface (GUI).
Event-driven constructs that allow the user of a GUI application to navigate through the code much more flexibly than in an older, top-down, character-mode application, developed in Progress fifteen or twenty years ago. Those older applications are still fully supported. You can compile and run them in the latest releases of the Progress product, but many new language statements and other features have made it possible to build modern applications in ways that were not possible before.

If you are already experienced in the 4GL, you will find some of the material, especially in the first couple of chapters, familiar. Feel free to skim through those sections quickly, but you should not skip even the first chapters altogether to avoid missing anything—there are changes and enhancements to the language at every level.

The second audience for this book consists of people completely new to Progress. The Progress 4GL remains by far the most powerful and comprehensive language for developing serious business applications. Combined with the Progress RDBMS™ database and the other components of the Progress OpenEdge™ product family, the Progress 4GL can support you in building and deploying your applications in ways that are matched by no other environment today. For those of you in this second group, you should take the time to learn enough about the language to understand some of the many ways it can help you in your development work. You probably need to have a background in some other programming language to catch on to Progress quickly, because the material might come at you fast and furious. Despite its many extraordinary and unique features, the Progress 4GL is basically a procedural programming language with most of the same constructs common to almost all such languages.

Organization

"Introducing the Progress 4GL,"

Provides an introduction to the Progress 4GL, including an overview of its characteristics.

"Using Basic 4GL Constructs,"

Describes the basics of writing Progress procedures.

"Running Progress 4GL Procedures,"

Describes how you can work with and run different types of Progress 4GL procedures.

"Introducing the OpenEdge AppBuilder,"

Introduces the AppBuilder's code generating features and pre-built components.

"Examining the Code the AppBuilder Generates,"

Examines the underlying AppBuilder-generated code.

"Procedure Blocks and Data Access,"

Describes how to integrating data-access logic into procedures using procedure blocks and scoping.

"Record Buffers and Record Scope,"

Expands the discussion on integrating data-access logic into procedures with record buffers and record scope.

"Defining Graphical Objects,"

Describes how to create visual objects for data display.

"Using Graphical Objects in Your Interface,"

Describes how to add visual objects to a user interface procedure.

"Providing Help for OpenEdge Applications,"

Describes how to implement field-level help and a complete online help system.

"Using Queries,"

Describes how to define and use queries to pass result sets between application modules.

"Defining and Using Temp-tables,"

Describes how to define and use temp-tables to pass result sets between application modules which is essential when creating distributed applications.

"Using the Browse Object,"

Describes how to design and interact with static browse objects and the queries they represent.

"Advanced Use of Procedures in Progress,"

Describes how to write and invoke procedures in addition to treating them as independent objects.

"Defining Functions and Building Super Procedures,"

Describes how to create user-defined functions and build super procedures.

"Handling Data and Locking Records,"

Describes data handling and record locks from the perspective of a distributed application.

"Updating Your Database and Writing Triggers,"

Describes how to update your database and write triggers—topics you need to understand to build the business logic that is the heart of your application.

"Managing Transactions,"

Describes how to manage database transactions.

"Using Dynamic Graphical Objects,"

Adding flexibility to your application by creating visual objects and defining their attributes programmatically at run time.

"Using Dynamic Queries and Buffers,"

Creating dynamic versions of data management objects such as queries and buffers.

"Creating and Using Dynamic Temp-tables and Browses,"

Creating dynamic versions of data management objects such as temp-tables and the browse.

"Progress Programming Best Practices,"

This final chapter introduces additional language constructs and programming techniques to help you build the best-performing applications you can.

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 CAPITAL LETTERS	Small, bold capital letters indicate OpenEdge™ key functions and 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.
UPPERCASE fixed width	Uppercase words are Progress® 4GL language keywords. Although these always are shown in uppercase, you can type them in either uppercase or lowercase in a procedure.
Period (.) or colon (:)	All statements except DO, FOR, FUNCTION, PROCEDURE, and REPEAT end with a period. DO, FOR, FUNCTION, PROCEDURE, and REPEAT 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.

Examples of syntax descriptions

In this example, ACCUM is a keyword, and aggregate and expression are variables:

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:

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:

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:

{ &argument-name }

In this example, EACH, FIRST, and LAST are optional, but you can choose only one of them:

PRESELECT [ EACH | FIRST | LAST ] record-phrase

In this example, you must include two expressions, and optionally you can include more. Multiple expressions are separated by commas:

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:

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

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

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

Accessing files in procedure libraries

Documentation examples are stored in procedure libraries, prodoc.pl and prohelp.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:

From the Control Panel or the Progress Program Group, double-click the Proenv icon.
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%).
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

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:

From the Control Panel or the Progress Program Group, double-click the Proenv icon.
The Proenv window appears, with the proenv prompt.
At the proenv prompt, enter the following command to create the prodoc directory in your OpenEdge working directory (by default, C:\Progress\Wrk):

MKDIR prodoc

Create the langref directory under prodoc:

MKDIR prodoc\langref

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

PROLIB extracts r-syshlp.p into prodoc\langref.

Extracting source files from procedure libraries (UNIX)

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:

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).
At the proenv prompt, create the prodoc directory in your OpenEdge working directory:

mkdir prodoc

Create the proghand directory under prodoc:

mkdir prodoc/handbook

To extract all examples in a procedure library directory, run the PROLIB utility:

prolib $DLC/src/prodoc.pl -extract prodoc/handbook/*.*

PROLIB extracts all examples into prodoc/proghand.
To extract one source file (p-wrk1.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/handbook/h-mainsig.p

PROLIB extracts h-mainsig.p into prodoc/handbook.

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

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

Start the OpenEdge Procedure Editor:

install-dir/dlc/bin/pro

Press F3 to access the menu bar, then choose HelpMessages.
Type the message number and press ENTER. Details about that message number appear.
Press F4 to close the message, press F3 to access the Procedure Editor menu, and choose FileExit.