DISPLAY statement
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.
Data movement
Syntax
STREAMstream
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-HANDLEhandle
Specifies the handle to a stream. Ifhandle
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-HIDDENexpression
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.Ifexpression
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 referencea[i]
in the same frame that you reference a ora[constant]
,a[i]
overlays the appropriate frame field based on the value of i. It is displayed in a new frame field fora[i]
. For example.
Here,month-quota[i]
is referenced in the same frame thatmonth-quota
is referenced. That is, line 5 referencesmonth-quota[i]
and line 3 referencesmonth-quota
. Both references use the same frame. Therefore, instead of creating a new frame field formonth-quota[i]
, the AVM uses the same frame fields created for the entiremonth-quota
array.In the next procedure, line 4 references only elements 1 and 2. Therefore, when the AVM tries to overlaymonth-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.
The following example shows a solution to that problem:
If you explicitly referencea[ix]
in a FORM statement, regular array fields (month-quota[1]
andmonth-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 onformat-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 foraggregate-phrase
:
For more information onaggregate-phrase
, see the Aggregate phrase reference entry.WHENexpression
@base-field
Thebase-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 thebase-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 thebase-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 thebase-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 thebase-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 thebase-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. Then
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 usen
, 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. Then
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 specifyn,
or ifn
is 0, the AVM starts a new line unless it is already at the beginning of a new line.IN WINDOWwindow
frame-phrase
Specifies the overall layout and processing properties of a frame. For more information onframe-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.EXCEPTfield
. . .WITH BROWSEbrowse
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, wheremessage-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.
ExamplesThis 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:
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.
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 thePostalCode
field if there is no postal code value in the field.
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
orbase-field
, or use the VIEW-AS EDITOR option fromformat-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 asdbname.table-name
, it tries to resolve it astable-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, 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 instance directly. To display an object reference, you must first convert it using the INTEGER, INT64, or STRING function and display the result.
See alsoACCUM 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
OpenEdge Release 10.2B
|