Moves data to a screen buffer and displays
the data on the screen or other output destination. The AVM uses
frames to display data. A frame describes how constant and variable
data is arranged for display and data entry. You can let ABL construct
default frames or you can explicitly describe frames and their characteristics.
Syntax
DISPLAY
{[ STREAM stream | STREAM-HANDLE handle ] [ 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 | STREAM-HANDLE handle ] [ 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,
the AVM uses the unnamed stream. See the DEFINE STREAM statement reference entry and the chapter on alternate I/O sources
in OpenEdge Development: Programming Interfaces for
more information on streams.
- STREAM-HANDLE handle
- Specifies the handle to a stream. If handle is not
a valid handle to a stream, the AVM generates a run-time error.
Note that stream handles are not valid for the unnamed streams.
See the chapter on alternate I/O sources in OpenEdge Development:
Programming Interfaces for more information on streams and
stream handles.
- 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, the AVM checks to see if that particular
field or variable is used previously in the same frame. If it has,
the AVM 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 unfixed indeterminate array parameter or
variable. You can use the EXTENT statement to fix the number of elements
in the array before displaying them. For more information, see the
EXTENT statement reference
entry.
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.
r-arry.p
/*1*/ DEFINE VARIABLE ix AS INTEGER NO-UNDO.
/*2*/ FOR EACH SalesRep:
/*3*/ DISPLAY SalesRep.SalesRep SalesRep.Region SalesRep.MonthQuota.
/*4*/ DO ix = 1 TO 12:
/*5*/ SET SalesRep.MonthQuota[ix] WITH 1 COLUMN.
/*6*/ END.
/*7*/ DISPLAY SalesRep.MonthQuota
/*8*/ WITH FRAME a COLUMN 40 ROW 3 1 COLUMN.
/*9*/ 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],
the AVM 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 the AVM tries to overlay month-quota[i] in
line 6, there is only room for elements 1 and 2. The AVM returns
an error after you enter data for those two elements.
r-arry2.p
/*1*/ DEFINE VARIABLE ix AS INTEGER NO-UNDO.
/*2*/ FOR EACH SalesRep:
/*3*/ DISPLAY SalesRep.SalesRep SalesRep.Region
/*4*/ SalesRep.MonthQuota[1] SalesRep.MonthQuota[2].
/*5*/ DO ix = 1 TO 12:
/*6*/ SET month-quota[ix] 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 ix AS INTEGER NO-UNDO.
/*2*/ FOR EACH SalesRep:
/*3*/ DISPLAY SalesRep.SalesRep SalesRep.Region
/*4*/ SalesRep.MonthQuota[1] SalesRep.MonthQuota[2] WITH 6 DOWN.
/*5*/ FORM ix SalesRep.MonthQuota[ix].
/*6*/ DO ix = 1 TO 12:
/*7*/ DISPLAY ix NO-LABEL.
/*8*/ SET SalesRep.MonthQuota[ix].
/*9*/ END.
/*10*/ DISPLAY month-quota WITH FRAME a COLUMN 40 ROW 3 1 COLUMN.
/*11*/ END.
|
If you explicitly reference a[ix] 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.
The
AVM 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, the AVM blanks out any characters
to the left or right of the area used by the field being displayed.
The
AVM 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,
the AVM 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
the AVM 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, the AVM starts a new line and discards extra
spaces. If you do not use this option or do not use n,
the AVM inserts one space between items in the frame.
- SKIP [ ( n ) ]
- Identifies the number (n) of blank lines
the AVM needs to insert after the expression is displayed. The n can
be 0. If you do not use this option, the AVM 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, the AVM 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 the AVM displays all fields except those fields listed in the
EXCEPT phrase.
-
WITH BROWSE browse
- Indicates that the AVM 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
- Suppresses ABL errors or error messages that would otherwise
occur and diverts them to the ERROR-STATUS system handle. If an error occurs, the action of the statement
is not done and execution continues with the next statement. If
the statement fails, any persistent side-effects of the statement
are backed out. If the statement includes an expression that contains
other executable elements, like methods, the work performed by these
elements may or may not be done, depending on the order the AVM
resolves the expression elements and the occurrence of the error.
As
an exception to the general rule, the DISPLAY statement may continue
to execute even if it encounters an error resolving some part of an
expression. This attempt to complete the operation may result in displaying
the empty string at the location of the intended output.
To
check for errors after a statement that uses the NO-ERROR option:
- Check the ERROR-STATUS:ERROR attribute to see if the AVM raised
the ERROR condition.
- Check if the ERROR-STATUS:NUM-MESSAGES attribute is greater than
zero to see if the AVM generated error messages. ABL handle methods
used in a block without a CATCH end block treat errors as
warnings and do not raise ERROR, do not set the ERROR-STATUS:ERROR
attribute, but do add messages to the ERROR-STATUS system handle.
Therefore, this test is the better test for code using handle methods
without CATCH end blocks. ABL handle methods used in a block with a
CATCH end block raise ERROR and add messages to the error object
generated by the AVM. In this case, the AVM does not update the
ERROR-STATUS system handle.
- Use ERROR-STATUS:GET-MESSAGE( message-num )
to retrieve a particular message, where message-num is
1 for the first message.
If the statement does not include
the NO-ERROR option, you can use a CATCH end block to handle errors
raised by the statement.
Some other important usage notes
on the NO-ERROR option:
- NO-ERROR does not suppress errors
that raise the STOP or QUIT condition.
- A CATCH statement, which introduces a CATCH end block, is analogous
to a NO-ERROR option in that it also suppresses errors, but it does so
for an entire block of code. It is different in that the error messages
are contained in a class-based error object (generated by the AVM
or explicitly thrown), as opposed to the ERROR-STATUS system handle.
Also, if errors raised in the block are not handled by a compatible
CATCH block, ON ERROR phrase, or UNDO statement, then the error
is not suppressed, but handled with the default error processing
for that block type.
- When a statement contains the NO-ERROR option and resides in
a block with a CATCH end block, the NO-ERROR option takes precedence over
the CATCH block. That is, an error raised on the statement with
the NO-ERROR option will not be handled by a compatible CATCH end block.
The error is redirected to the ERROR-STATUS system handle as normal.
- If an error object is thrown to a statement that includes the NO-ERROR
option, then the information and messages in the error object will
be used to set the ERROR-STATUS system handle. This interoperability
feature is important for those integrating code that uses the traditional
NO-ERROR technique with the newer, structured error handling that
features error objects and CATCH end blocks.
Example
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 NO-LOCK BY Customer.State BY Customer.Name:
DISPLAY Customer.State Customer.CustNum Customer.Name.
FOR EACH Order OF Customer NO-LOCK:
DISPLAY Order.OrderNum Order.Name Order.ShipDate Order.PromiseDate.
FOR EACH OrderLine OF Order NO-LOCK, Item OF OrderLine NO-LOCK:
DISPLAY OrderLine.LineNum Item.ItemName OrderLine.Qty
OrderLline.price.
END.
END.
END.
|
This procedure lists each order, Customer information,
and the OrderLines for each Order. The procedure calculates an Order-value
for each of the OrderLines of an Order, and adds those values to
produce a total value for an entire Order.
r-disp2.p
FOR EACH Order NO-LOCK, Customer OF Order NO-LOCK:
DISPLAY Order.OrderNum Customer.Name Order.ShipDate Order.PromiseDate.
FOR EACH OrderLine OF Order NO-LOCK, Item OF OrderLine NO-UNDO:
DISPLAY OrderLine.LineNum Item.ItemName OrderLine.Qty OrderLine.Price
OrderLine.Qty * OrderLine.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 PostalCode field
if there is no postal code value in the field.
r-disp3.p
FOR EACH Customer NO-LOCK:
DISPLAY Customer.Name SKIP Customer.Address SKIP Customer.Address2 SKIP
Customer.City + ", " + Customer.State FORMAT "x(16)"
Customer.PostalCode WHEN Customer.PostalCode NE "" SKIP(2)
WITH NO-BOX NO-LABELS USE-TEXT.
END.
|
Notes
- When
ABL 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, the AVM 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 and OpenEdge Data Management: DataServer for
Oracle).
- You cannot use the DISPLAY statement to display an object reference for
a class instance directly. To display an object reference, you must
first convert it using the INTEGER, INT64, 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, Stream object handle, UP statement, VIEW-AS phrase