Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## Preface

> This Preface contains the following sections:

> - Purpose

> - Audience

> - Organization

> - Using this manual

> - Typographical conventions

> - Examples of syntax descriptions

> - Example procedures

> - OpenEdge messages

> ### Purpose

> This book defines the Progress® 4GL. It covers all 4GL statements, functions, phrases, operators, preprocessor directives, special symbols, widgets, handles, attributes, methods, events, and classes.

> ### Audience

> This book is intended for programmers who develop applications using Progress and for anyone who needs to read and understand Progress 4GL code.

> ### Organization

> This book consists of the following sections:

> - A dictionary of Progress statements, functions, phrases, operators, preprocessors, and special symbols beginning with the letters A–Z.

> - A dictionary of Progress widgets.

> - A dictionary of Progress handles.

> - A dictionary of Progress attributes and methods.

> - Tables of Progress events.

> - A dictionary of Progress classes.

> - An index of Progress 4GL keywords.

> ### Using this manual

> Each Progress language element reference description includes some subset of the following information:

> - Platform-restriction notations.

> - A purpose or description of the language element.

> - Block properties for all block statements.

> - Data-movement diagrams for all data-handling statements.

> - The syntax for the language element.

> - The options and arguments you can use with the language element.

> - One or more examples that illustrate the use of the language element.

> - Notes that highlight special cases or provide hints on using the language element.

> - A See Also section that lists related language elements.

> ##### Platform-restriction notes

> Some language elements and features of the Progress 4GL do not apply to all software platforms—operating systems, user interfaces, and database management systems—that OpenEdge® supports. The documentation tries to note each such platform restriction with the language element title. Some language elements apply to SpeedScript programming and some do not; the documentation indicates which language elements do not apply with a note in the language element description.

> You can consider a language element as supported for all interfaces, on all operating systems, and for SpeedScript unless otherwise indicated in the language element description.

> The platform restriction notes that appear in the documentation include the following:

> - AppServer™ only

> The element or feature applies only to the OpenEdge AppServer.

> - Character interfaces only

> The element or feature applies only to the character interfaces that OpenEdge supports.

> - Graphical interfaces only

> The element or feature applies only to the graphical interfaces that OpenEdge supports.

> - NT and UNIX only

> The element or feature applies only to the Windows and UNIX versions that OpenEdge supports.

> - ORACLE only

> The element or feature applies only to the ORACLE versions that OpenEdge supports.

> - UNIX only

> The element or feature applies only to the UNIX versions that OpenEdge supports.

> - Windows only

> The element or feature applies only to the Windows versions that OpenEdge supports.

> - Windows only; Graphical interfaces only

> The element or feature applies only to the graphical interfaces of the Windows and versions that OpenEdge supports.

> For a complete list of the software platforms that OpenEdge supports, see OpenEdge Getting Started: Installation and Configuration .

> ### Typographical conventions

> This manual uses the following typographical conventions:

> Convention | Description
> --- | ---
> Bold | Bold typeface indicates commands or characters the user types, provides emphasis, or the names of user interface elements.
> Italic | Italic typeface indicates the title of a document, or signifies new terms.
> SMALL, BOLD CAPITAL LETTERS | Small, bold capital letters indicate OpenEdge® key functions and generic keyboard keys; for example, GET and CTRL.
> KEY1+KEY2 | A plus sign between key names indicates a simultaneous key sequence: you press and hold down the first key while pressing the second key. For example, CTRL+X.
> KEY1 KEY2 | A space between key names indicates a sequential key sequence: you press and release the first key, then press another key. For example, ESCAPE H.
> Syntax:
> `Fixed width` | A fixed-width font is used in syntax statements, code examples, system output, and filenames.
> `Fixed-width italics` | Fixed-width italics indicate variables in syntax statements.
> `Fixed-width bold` | Fixed-width bold indicates variables with special emphasis.
>     UPPERCASE
>     fixed width
> | Uppercase words are Progress® 4GL language keywords. Although these are always shown in uppercase, you can type them in either uppercase or lowercase in a procedure.
> | This icon (three arrows) introduces a multi-step procedure.
> | This icon (one arrow) introduces a single-step procedure.
> Period (.) or colon (:) | 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:

> 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

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

> #### 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. You can access the example files and details for installing the examples from the following locations:

> - The Documentation and Samples CD that you received with your product.

> - The Progress Documentation Web site:

>     http://www.progress.com/products/documentation

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

> #### Obtaining more information about OpenEdge messages

> In Windows platforms, use OpenEdge online help to obtain more information about OpenEdge messages. Many OpenEdge tools include the following Help menu options to provide information about messages:

> - Choose Help Recent Messages to display detailed descriptions of the most recent OpenEdge message and all other messages returned in the current session.

> - Choose Help Messages and then type the message number to display a description of a specific OpenEdge message.

> - In the Progress Procedure Editor, press the HELP key or F1.

> On UNIX platforms, use the Progress `pro` command to start a single-user mode character OpenEdge client session and view a brief description of a message by providing its number.

> | To use the pro command to obtain a message description by message number:

> 1. Start the Progress Procedure Editor:

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

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095