Release 10.1A: OpenEdge Reporting:
Query/Results for UNIX

> ## Preface

> This Preface contains the following sections:

> - Purpose

> - Audience

> - Organization

> - Using this manual

> - Typographical conventions

> - Examples of syntax descriptions

> - OpenEdge messages

> ### Purpose

> This guide introduces you to the character (text-mode) version of Progress ResultsŪ. Query/Results, more commonly referenced throughout this guide as Results, is an interactive, menu-driven tool that lets you query, report, and maintain information stored in Progress-supported databases.

> ### Audience

> This guide is an end-user manual that explains how to use the default Results application. If you purchased Results through a third-party application vendor, the vendor might have modified Results. These modifications might include adding or removing features, or even incorporating Results into another application. If you have a modified Results application, your vendor might modify the help system to reflect these changes or provide you with additional documentation.

> ### Organization

> Chapter 1 "Results Product Overview"

> Describes the product in general terms, and summarizes the options on the main menu.

> Chapter 2 "Getting Started"

> Describes the hardware and software requirements for running the product on your system. Explains how to install the product, log in and out, and how to use the function keys and menus.

> Chapter 3 "A Tour Through Results"

> Provides a tour through the user options in the Results product. Describes many of the features in the Query, Reports, Data Export, and Labels modules.

> Chapter 4 "Query Module"

> Describes different ways to retrieve information from a database using the Query module.

> Chapter 5 "Reports Module"

> Describes how to create reports, and provides examples.

> Chapter 6 "Labels Module"

> Describes and provides examples of how to generate mailing labels.

> Chapter 7 "Data Export Module"

> Describes how to export your data in formats useful to other software.

> Chapter 8 "Multiple Databases with Results"

> Describes the implications of using Results with more than one database open at the same time.

> Chapter 9 "Database Administration"

> Defines how to perform database administration tasks such as defining relations among files, establishing file security, and defining device interfaces such as printers and terminals.

> Chapter 10 "Integrating Results into Existing Applications"

> Describes how application developers can integrate Results into existing applications.

> Appendix A, "Startup and Shutdown Procedures"

> Describes how to start and stop a Results session.

> Appendix B, "Option Descriptions"

> Describes the options that appear in the user modules of the Results package. For example, it describes the options in the Query, Reports, Labels, and Data Export modules.

> Appendix C, "Field Display Formats"

> Describes how Results handles display formats for fields.

> Appendix D, "Results Limits"

> Lists Results’s internal limits, such as maximum number of files that can be joined, total number of query forms, and so forth.

> Appendix E, "Files that Results Creates"

> Describes the file extensions used by Results.

> Appendix F, "Order of Evaluation"

> Describes how Results evaluate expressions in WHERE clauses.

> Appendix G, "Helpful Information"

> Describes and offers solutions to some common problems in database administration.

> ### Using this manual

> To maximize your use of this tutorial, first skim the entire tutorial to get an idea of its content and the various tasks you can perform to become familiar with the Query product’s functionality. Then, return to those sections you intend to explore more completely.

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

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

> 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

> #### Extracting source files from procedure libraries (UNIX)

> | 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 `proghand` directory under `prodoc`:

>     mkdir prodoc/proghand

> 4. To extract all examples in a procedure library directory, run the `PROLIB` utility:

>     prolib $DLC/src/prodoc.pl -extract prodoc/proghand/*.*

> `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/proghand/p-wrk-1.p

> `PROLIB` extracts`p-wrk-1.p` into `prodoc/proghand`.

> ### 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 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 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 Procedure Editor menu, and choose File Exit.

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