Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## DISPLAY statement

> Moves data to a screen buffer and displays the data on the screen or other output destination. Progress uses frames to display data. A frame describes how constant and variable data is arranged for display and data entry. You can let Progress construct default frames or you can explicitly describe frames and their characteristics.

> #### Data movement

> #### Syntax

>     DISPLAY
>       { [ STREAM stream ] [ UNLESS-HIDDEN ] }
>       [    { expression
>                  [ format-phrase ]
>                  [ ( aggregate-phrase ) ]
>                  [ WHEN expression ]
>                  [ @base-field ]
>             }
>          |  [ SPACE [ ( n ) ] ]
>          |  [ SKIP [ ( n ) ] ]
>       ] ...
>       { [ IN WINDOW window ] [ frame-phrase ] [ NO-ERROR ] }

>     DISPLAY
>       { [ STREAM stream ] [ UNLESS-HIDDEN ] }
>          record [ EXCEPT field ... ]
>       { [ IN WINDOW window ] [ frame-phrase ] [ NO-ERROR ] }

>     DISPLAY
>      {     expression ...
>         |  record [ EXCEPT field ... ]
>       }
>       WITH BROWSE browse [ NO-ERROR ]

> `STREAM `stream``

> Specifies the name of a stream. If you do not name a stream, Progress uses the unnamed stream. See the DEFINE STREAM statement reference entry in this book and the chapter on alternate I/O sources in OpenEdge Development: Programming Interfaces for more information on streams.

> `UNLESS-HIDDEN`

> Restricts DISPLAY to fields whose HIDDEN attribute is FALSE.

> ``expression``

> Identifies a constant, field name, variable name, or expression that results in the value you want to display. This can also be the built-in field name, proc-text, that returns a character string of column values from a row returned by a stored procedure proc-text-buffer.

> If `expression` is a simple field or variable, Progress checks to see if that particular field or variable is used previously in the same frame. If it has, Progress displays the field or variable in the same frame field as the earlier instance of that field or variable.

> In array fields, array elements with constant subscripts are treated just as any other field. Array fields with no subscripts are expanded as though you had typed in the implicit elements.

> Note: You cannot display elements of an indeterminate array parameter or variable. If you need to display one or more elements of an indeterminate array parameter or variable, assign those elements to a determinate array variable and display them from that variable.

> If you reference `a[i]` in the same frame that you reference a or `a[constant]`, `a[i]` overlays the appropriate frame field based on the value of i. It is displayed in a new frame field for `a[i]`. For example, examine this procedure.

> r-arry.p
>     1    DEFINE VARIABLE i AS INTEGER.

>     2    FOR EACH salesrep:
>     3       DISPLAY sales-rep region month-quota.
>     4       DO i = 1 TO 12:
>     5          SET month-quota[i] WITH 1 COLUMN.
>     6       END.
>     7       DISPLAY month-quota WITH FRAME a COLUMN 40 ROW 3 1 COLUMN.
>     8    END.

> Here, `month-quota[i]` is referenced in the same frame that `month-quota` is referenced. That is, line 5 references `month-quota[i]` and line 3 references `month-quota`. Both references use the same frame. Therefore, instead of creating a new frame field for `month-quota[i]`, Progress uses the same frame fields created for the entire `month-quota` array.

> In the next procedure, line 4 references only elements 1 and 2. Therefore, when Progress tries to overlay `month-quota[i]` in line 6, there is only room for elements 1 and 2. Progress returns an error after you enter data for those two elements.

> r-arry2.p
>     1    DEFINE VARIABLE i AS INTEGER.

>     2    FOR EACH salesrep:
>     3      DISPLAY sales-rep region
>     4              month-quota[1] month-quota[2].
>     5      DO i = 1 TO 12:
>     6         SET month-quota[i] WITH 1 COLUMN.
>     7      END.
>     8      DISPLAY month-quota WITH FRAME a COLUMN 40 ROW 3 1 COLUMN.
>     9    END.

> The following example shows a solution to that problem:

> r-arry3.p
>     1    DEFINE VARIABLE i AS INTEGER.

>     2    FOR EACH salesrep:
>     3       DISPLAY sales-rep region
>     4               month-quota[1] month-quota[2] WITH 6 DOWN.
>     5       FORM i month-quota[i].
>     6       DO i = 1 TO 12:
>     7          DISPLAY i NO-LABEL.
>     8          SET month-quota[i].
>     9       END.
>     10       DISPLAY month-quota WITH FRAME a COLUMN 40 ROW 3 1 COLUMN.
>     11    END.

> If you explicitly reference `a[i]` in a FORM statement, regular array fields (`month-quota[1]` and `month-quota[2]` in this example) are not overlaid.

> ``format-phrase``

> Specifies one or more frame attributes for a field, variable, or expression. For more information on `format-phrase`, see the Format phrase reference entry.

> ``aggregate-phrase``

> Identifies one or more aggregate values to be calculated optionally based on a change in a break group. This is the syntax for `aggregate-phrase`:

>     {   AVERAGE
>       | COUNT
>       | MAXIMUM
>       | MINIMUM
>       | TOTAL
>       | SUB-AVERAGE
>       | SUB-COUNT
>       | SUB-MAXIMUM
>       | SUB-MINIMUM
>       | SUB-TOTAL
>     } ... [ LABEL aggr-label ] [ BY break-group ] ...

> For more information on `aggregate-phrase`, see the Aggregate phrase reference entry.

> `WHEN `expression``

> Displays an item only when the expression used in the WHEN option has a value of TRUE. Here, `expression` is a field name, variable name, or expression whose value is logical.

> `@ `base-field``

> The `base-field` must be the name of a field or variable; it cannot be an expression or constant. The field or variable must be viewed as a fill-in or text widget on the display.

> Progress reserves enough space for the `base-field` to hold the longest format displayed there. All right-justified fields (numerics that do not use side labels) are right justified within the reserved area. The label is left or right justified according to the `base-field`. Whenever you enter data into the `base-field` Progress blanks out any characters to the left or right of the area used by the field being displayed.

> Progress underlines a screen area that is the longer of the `base-field` and the overlaying field. However, you can enter as many characters as there are spaces in the format of the field.

> To determine the format to use for displaying the expression at the `base-field`, Progress looks at the following and uses the first format that applies:

> - An explicit Format phrase used with the`expression`.
> - If the expression is a character string constant, a format that accommodates that string.
> - If the data type of the expression matches that of the `base-field`, the format of the `base-field`.
> - The standard format of the expression as if it were displayed without a `base-field`.
> `SPACE [ ( `n` ) ]`

> Identifies the number (`n`) of blank spaces Progress inserts after the displayed expression displays. The `n` can be 0. If the number of spaces is more than the spaces left on the current line of the frame, Progress starts a new line and discards extra spaces. If you do not use this option or do not use `n`, Progress inserts one space between items in the frame.

> `SKIP [ (`n` ) ]`

> Identifies the number (`n`) of blank lines Progress needs to insert after the expression is displayed. The `n` can be 0. If you do not use this option, Progress does not skip a line between expressions unless the expressions do not fit on one line. If you use the SKIP option but do not specify `n,` or if `n` is 0, Progress starts a new line unless it is already at the beginning of a new line.

> `IN WINDOW `window``

> Identifies the window where the expression is displayed. The expression `window` must evaluate to the handle of a window.

> ``frame-phrase``

> Specifies the overall layout and processing properties of a frame. For more information on `frame-phrase`, see the Frame phrase reference entry.

> ``record``

> Identifies the name of the record you want to display. Naming a record is shorthand for listing each field individually. This can also be the built-in buffer name, proc-text-buffer, that returns each row retrieved by a stored procedure.

> To display a record in a table defined for multiple databases, you must qualify the record’s table name with the database name. See the Record phrase reference entry for more information.

> `EXCEPT `field` . . .`

> Indicates that Progress displays all fields except those fields listed in the EXCEPT phrase.

> `WITH BROWSE `browse``

> Indicates that Progress displays the values into the current row of the specified browse widget.

> Note: DISPLAY . . . WITH BROWSE cannot be used with a dynamic browse. Instead, the user must set the browse column’s SCREEN-VALUE attributes.

> `NO-ERROR`

> Specifies that any errors that occur when you try to display the data are suppressed. After the DISPLAY statement completes, you can check the ERROR-STATUS system handle for information on any errors that might have occurred.

> Examples

> This procedure generates a hierarchical report of customers (sorted by state and name), the orders belonging to those customers, and the order-lines belonging to each order:

> r-disp.p
>     FOR EACH customer BY state BY name:
>          DISPLAY state cust-num name.
>          FOR EACH order OF customer:
>              DISPLAY order-num name ship-date promise-date.
>              FOR EACH order-line OF order, item OF order-line:
>                  DISPLAY line-num item-name qty order-line.price.
>              END.
>          END.
>     END.

> This procedure lists each order, customer information, and the order-lines for each order. The procedure calculates an Order-value for each of the order-lines of an order, and adds those values to produce a total value for an entire order.

> r-disp2.p
>     FOR EACH order, customer OF order:
>          DISPLAY order-num customer.name ship-date promise-date.
>          FOR EACH order-line OF order, item OF order-line:
>              DISPLAY line-num item-name qty order-line.price
>                      qty * order-line.price (TOTAL) LABEL "Order-value".
>          END.
>     END.

> The`r-disp3.p` procedure displays a name and address list in a mailing label. The SKIP and FORMAT options are used to produce a standard address format. The WHEN option suppresses the display of the postal-code field if there is no postal code value in the field.

> r-disp3.p
>     FOR EACH customer:
>         DISPLAY name SKIP address SKIP address2 SKIP
>                 city + ", " + state FORMAT "x(16)"
>                 postal-code WHEN postal-code NE "" SKIP(2)
>                 WITH NO-BOX NO-LABELS USE-TEXT.
>     END.

> #### Notes

> - When Progress compiles a procedure, it uses a top-to-bottom pass of the procedure to design all the frames that procedure requires, adding field and related format attributes as it goes through the procedure.

> - If you are displaying data that contains special control characters such as tabs, form feeds, or backspaces, be sure to use an EDITOR widget of the appropriate size for `expression` or `base-field`, or use the VIEW-AS EDITOR option from `format-phrase` in the DISPLAY statement. Otherwise, do not display data containing these characters.

> - If you use a single qualified identifier with the DISPLAY statement, the Compiler first interprets the reference as `dbname.table-name`. If the Compiler cannot resolve the reference as`dbname.table-name`, it tries to resolve it as `table-name.fieldname.`

> - If you invoke the DISPLAY statement for a frame, Progress brings the frame into view unless the HIDDEN attribute for the frame or one of its ancestor frames or windows is TRUE.

> - For more information on using the built-in field and buffer names, proc-text and proc-text-buffer in a DISPLAY statement, see the OpenEdge DataServer Guides, OpenEdge Data Management: DataServer for Microsoft SQL Server , OpenEdge Data Management: DataServer for ODBC , and OpenEdge Data Management: DataServer for ORACLE .

> - You cannot use the DISPLAY statement to display an object reference for a class object instance directly. To display an object reference, you must first convert it using the INTEGER or STRING function and display the result.

> #### See also

> ACCUM function, Aggregate phrase, DEFINE BROWSE statement, DEFINE FRAME statement, DOWN statement, EXPORT statement, FORM statement, Format phrase, Frame phrase, MESSAGE statement, PAGE statement, PUT statement, PUT SCREEN statement, UP statement, VIEW-AS phrase

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