Progress
Language Reference


DEFINE BROWSE Statement

Interfaces
OS
SpeedScript
All
All
No

Defines and creates either a static read-only browse widget or a static updateable browse widget.

SYNTAX

DEFINE [ [ NEW ] SHARED ] BROWSE browse-name
  QUERY query-name  
    [ SHARE-LOCK | EXCLUSIVE-LOCK | NO-LOCK ] [ NO-WAIT ] 
  DISPLAY
    { column-list | record [ EXCEPT field ... ] } 
    [ browse-enable-phrase ] 
    { browse-options-phrase }
    [ CONTEXT-HELP-ID expression ]
    [ DROP-TARGET ]
    [ TOOLTIP tooltip ] 

NEW SHARED

Defines a browse widget that can be used by other procedures. When the procedure containing this statement ends, the browse is no longer available.

You cannot define a SHARED or NEW SHARED browse widget in a persistent procedure. If you do, Progress raises ERROR on the RUN statement that creates the procedure.

SHARED

Defines a browse that was created in another procedure with the DEFINE NEW SHARED BROWSE statement.

BROWSE browse-name

Identifies the name of the browse you want to define for the query.

QUERY query-name

The name of the query to browse. You must have previously defined or opened the query.

[ SHARE-LOCK | EXCLUSIVE-LOCK | NO-LOCK ]

Specifies the locking mode for records retrieved by the browse widget. The default locking mode is NO-LOCK. To control locking during preselection for a query associated with a browse widget, use the SHARE-LOCK, EXCLUSIVE-LOCK, or NO-LOCK option in the OPEN QUERY statement that opens the query.

NO-WAIT

Specifies not to wait for a record that is currently locked by another process. Instead, the record in conflict will be made available in NO-LOCK mode and the LOCKED function for that record will return TRUE.

DISPLAY column-list

Specifies the column items to display in the browse. Note that the column-list cannot contain widgets other than fill-ins and the column-list cannot contain SKIP options.

SYNTAX
DISPLAY
  { expression
      [ column-format-phase ]
      [ @ base-field ]
  } ... 

expression

A field name, variable, constant, or expression to display in each iteration of the browse frame.

column-format-phrase

Specifies the format for a value displayed in the browse. The column-format-phrase is a subset of the Format phrase.

SYNTAX
[ FORMAT expression ]
  [ LABEL label | NO-LABELS ]
  [ WIDTH n ]
  [ COLUMN-FONT expression ]
  [ COLUMN-LABEL label ]
  [ COLUMN-DCOLOR expression ]
  [ COLUMN-BGCOLOR expression ] 
  [ COLUMN-FGCOLOR expression ]
  [ COLUMN-PFCOLOR expression ]
  [ LABEL-FONT constant ]
  [ LABEL-DCOLOR expression ]
  [ LABEL-BGCOLOR expression ]
  [ LABEL-FGCOLOR expression ] 

WIDTH n

Specify a width for the browse column. n represents a multiplier of the average character width of the column font. Specifying a width smaller than the format string creates a scrolling browse cell, if the column is updateable.

For more information on FORMAT strings and label options, see the Format Phrase reference entry. The column and label color and font options work like those specified in the browse-options-phrase. If color or fonts are specified with this phrase, they only affect the specific column and override similar options specified in the browse-options-phrase.

@base-field

The base-field must be the name of a field or variable; it cannot be an expression or constant.

Progress reserves enough space for the base-field to hold the longest format displayed there. All right-justified fields (numeric fields that do not use side labels) are right justified within the reserved area.

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:

DISPLAY record

Specifies the record you want to display. If you specify a record, all fields from the record are displayed unless you use the EXCEPT option to eliminate specific fields.

See the Record Phrase reference entry for more information.

EXCEPT field . . .

Specifies fields that are not displayed in the browse. You can use the EXCEPT option only if you specify a record name in the DISPLAY option.

browse-enable-phrase

Specifies which fields in the column-list are enabled for input.

SYNTAX
ENABLE
  { { field [ HELP string ]
      [ VALIDATE ( condition , msg-exp ) ]
      [ AUTO-RETURN ]
      [ DISABLE-AUTO-ZAP ]
     } ...
     ALL [ EXCEPT field ]
  } 

List each field or variable from the column-list that you want enabled. Specify ALL to specify every item in the column-list. Use the EXCEPT option to eliminate specific items when you use the ALL option. For each field or variable, you can also specify custom help and validation, as shown in the next two entries.

HELP string

Represents a character string that you want to display whenever the user enters the frame field for the field or variable. When the user leaves the frame field, Progress removes the help string from the message area. You must enclose the string in quotation marks ("").

VALIDATE ( condition, msg-expression )

Specifies an expression that you want to validate against the data entered into a the browse cell. The condition is a Boolean expression (a constant, field name, variable name, or expression) whose value is TRUE or FALSE.

When you use the VALIDATE option to validate a specific cell, any reference to that cell in condition is assumed to be the new input value. For example, in the browse-enable phrase below, the promise-date that is compared to the order-date is the new user input, not the existing data.

ENABLE promise-date VALIDATE(promise-date > order-date,
  "Promise date must be later than order date"). 

To validate a new value against another new value, use the INPUT qualifier, as shown below.

ENABLE order-date promise-date VALIDATE(promise-date > INPUT order-date, 
"Promise date must be later than order date"). 

If the value of condition is FALSE, use msg-expression to display a specific message. You must enclose msg-expression in quotation marks ("").

Progress processes validation criteria whenever the user attempts to leave the browse cell. If the cell value is not valid, Progress displays msg-expression in the message area, causes the terminal to beep, and does not advance out of the browse cell.

If the user tabs to a cell, make no changes, and leave the cell, Progress does not process the validation criteria specified with the VALIDATE option until the you press GO (F1). If the user presses ENDKEY or END-ERROR, or an error occurs, Progress does not test the validation criteria specified with the VALIDATE option.

If the input source for the procedure is a table, Progress validates each input field (except those with a value of "-"). If the result of the validation is FALSE, msg-expression is displayed and Progress treats the validation as an error.

To suppress the Data Dictionary validation criteria for a cell, use this VALIDATE option.

VALIDATE(TRUE,"") 

AUTO-RETURN

Indicates whether Progress should behave as if the user pressed the RETURN key.when the user enters the last allowable character in a browse cell of the specified browse-column.

DISABLE-AUTO-ZAP

Indicates whether Progress should ignore the value of the browse-column’s AUTO-ZAP attribute and assume it is FALSE.

browse-options-phrase

Specifies options that affect the browse widget as a whole. The options affect both the layout and the function of the browse widget. (Note that you cannot include aggregate-phrases (TOTAL, MIN, etc.) in this phrase.) This is the syntax for browse-options-phrase.

SYNTAX
WITH
  { [ constant ] DOWN [ WIDTH width ] | [ size-phrase ] }
  [ FGCOLOR expression ]
  [ BGCOLOR expression ]
  [ DCOLOR expression ]
  [ PFCOLOR expression ] 
  [ LABEL-FONT expression ]
  [ LABEL-DCOLOR expression ]
  [ LABEL-FGCOLOR expression ]
  [ LABEL-BGCOLOR expression ]
  [ MULTIPLE | SINGLE ]
  [ SEPARATORS | NO-SEPARATORS ]
  [ NO-ASSIGN ]
  [ NO-ROW-MARKERS ]
  [ NO-LABELS ]
  [ NO-BOX ]
  [ FONT constant ]
  [ title-phrase ]
  [ NO-VALIDATE ]
  [ NO-SCROLLBAR-VERTICAL | SCROLLBAR-VERTICAL ]
  [ ROW-HEIGHT-CHARS | ROW-HEIGHT-PIXELS ] row-height
  [ EXPANDABLE ] 
  [ DROP-TARGET ]
  [ NO-AUTO-VALIDATE ] 

[ constant ] DOWN [ WIDTH width ]

The constant value is the number of rows displayed in the browse and must be at least 2. You can optionally specify the width of the browse, where width is the width of the browse in character units.

A browse-options-phrase must contain a DOWN option or a size-phrase.

size-phrase

Specifies the outer size of the browse border. When this option is used instead of the DOWN option, Progress determines the number of rows that can be displayed in the browse. This is the syntax for size-phrase.

SYNTAX
{ SIZE SIZE-PIXELS } width BY height 

For more information on size-phrase, see the SIZE Phrase reference entry.

A browse-options-phrase must contain a DOWN option (optionally with a WIDTH option) or a size-phrase.

FGCOLOR expression

Specifies the foreground color for the browse in graphical environments, but not the label foreground color. The value of expression must be an integer value that specifies an entry in the color table. This option is ignored in character environments.

BGCOLOR expression

Specifies the background color for the browse in graphical environments. The value of expression must be an integer value that specifies an entry in the color table. This option is ignored in character environments.

DCOLOR expression

Specifies the display color for the browse in character environments. The value of expression must be an integer value that specifies an entry in the color table. This option is ignored in graphical environments.

PFCOLOR expression

Specifies the prompt color for the browse in character environments. The value of expression must be an integer value that specifies an entry in the color table. This option is ignored in graphical environments.

LABEL-FONT constant

Specifies the font of the browse labels.

LABEL-DCOLOR expression

Specifies the display color for the browse labels in character environments. The value of expression must be an integer value that specifies an entry in the color table. This option is ignored in graphical environments.

LABEL-FGCOLOR expression

Specifies the foreground color for the browse labels in graphical environments. The value of expression must be an integer value that specifies an entry in the color table. This option is ignored in character environments.

LABEL-BGCOLOR expression

Specifies the background color for the browse labels in graphical environments. The value of expression must be an integer value that specifies an entry in the color table. This option is ignored in character environments.

[ MULTIPLE | SINGLE ]

Specifies whether multiple rows can be selected from the browse or only a single row at one time. The default is SINGLE.

[ SEPARATORS | NO-SEPARATORS ]

Specifies whether row and column separators are displayed within the browse. The default is NO-SEPARATORS.

NO-ASSIGN

Disables automatic writes on new data in an updateable browse. If this option is not specified, data entered into an updateable browse is assigned on any action that results in a ROW-LEAVE event. This option is intended for use with user-defined triggers on the ROW-LEAVE event. Essentially, when this option is specified, all data assignments by way of the updateable browse are up to the 4GL programmer.

ON ROW-LEAVE OF my-browse DO:
  IF Customer.State:SCREEN-VALUE IN BROWSE my-browse NE "MA" THEN DO:
    MESSAGE "Customer is out of state."
    RETURN NO-APPLY.
  END.
  
  /* Your code. Transaction scope is up to you. */

  FIND CURRENT customer.

  IF NOT CURRENT-CHANGED(customer) THEN
    ASSIGN INPUT BROWSE field1 field2 field3 field4.
  ELSE MESSAGE "Record has changed since last read.".

END. 

In the above example, the code looks for a special case where automatic database writes are not desirable and prevents them. The body of the trigger handles other processing before proceeding to commit the changes. First the trigger refinds the current customer record and then uses the CURRENT-CHANGED function to see if it has changed while the user was updating the browse cells. If it has not changed, the changes are committed. If it has changed, the trigger would handle that condition, too.

Note that an ASSIGN statement with the INPUT BROWSE option can be mixed with other assignment types, as shown below.

ASSIGN
  Name
  a = b
  INPUT FRAME my-frame c d
  INPUT BROWSE my-browse order-date promise-date
  INPUT e. 

NO-ROW-MARKERS

By default, an updateable browse displays row markers, which allow the user to select currently displayed rows in an updateable browse widget. This option prevents row markers from being displayed.

NO-LABELS

Does not display labels above the columns of the browse.

NO-BOX

Does not display a box around the browse. If you do not use this option, Progress displays a box around the data you are displaying.

If you are sending data to a device other than a terminal and you do not use this option, Progress omits the sides and bottom line of the box and replaces the top line with blanks.

FONT constant

Specifies the font of the browse. The title and labels also use this font, unless otherwise specified.

title-phrase

Displays a title as part of the top line of the box around the browse.

SYNTAX
TITLE
  [ BGCOLOR expression ] [ DCOLOR expression ] 
  [ FGCOLOR expression ] [ FONT expression ]
  [ title-string ] 

The title-string is a constant, field name, variable name, or expression whose result is a character value. The expression is the value you want to display as a title. If title-string is a constant character string, it must be surrounded by quotes (""). Progress automatically centers title-string in the top line of the browse box.

You can use the BGCOLOR and FGCOLOR options to specify the background and foreground color of the title under a graphical user interface. You can use the DCOLOR option to specify the color of the title under a character user interface.

NO-VALIDATE

Tells Progress to ignore the validations conditions in the schema for all fields in the browse.

Since browses do not inherit the NO-VALIDATE option from a parent frame, if you want a browse to have this option, you must specify it explicitly.

NO-SCROLLBAR-VERTICAL | SCROLLBAR-VERTICAL

Indicates whether the browse displays a vertical scrollbar. The default is for the vertical scrollbar to appear.

ROW-HEIGHT-CHARS | ROW-HEIGHT-PIXELS row-height

An INTEGER representing the row height in characters or pixels.

This option applies to graphical interfaces only.

The ROW-HEIGHT-CHARS and ROW-HEIGHT-PIXELS options let you specify the browse’s row height, in either characters or pixels.

EXPANDABLE

If you set a browse’s EXPANDABLE attribute to TRUE, Progress extends the right-most browse-column horizontally to the browse’s right edge, if necessary, to cover any white space that might appear there — unless you explicitly set the width of the right-most browse-column using the WIDTH-CHARS or WIDTH-PIXELS attribute. The expansion of the right-most browse-column might occur anytime the browse or another browse-column is resized.

The right-most browse-column expands only when there is no horizontal scroll bar. This is because when there is a horizontal scroll bar, no white space appears between the right edge of the right-most browse-column and the right edge of the browse.

NO-AUTO-VALIDATE

Tells Progress to compile into the code all relevant validations it finds in the Progress Data Dictionary, but to run the validations only when the code for a browse or for a browse-column specifically invokes the VALIDATE() method.

CONTEXT-HELP-ID expression

An integer value that specifies the identifier of the help topic for this browse in a help file specified at the session, window, or dialog box level using the CONTEXT-HELP-FILE attribute.

DROP-TARGET

Indicates whether the user can drop a file onto the object.

TOOLTIP tooltip

Allows you to define a help text message for a browse widget. Progress automatically displays this text when the user pauses the mouse pointer over a browse widget for which a ToolTip is defined. You can add or change the TOOLTIP option at any time.

If TOOLTIP is set to “” or ? (the unknown value), then the ToolTip is removed from the browse. No ToolTip is the default. ToolTips are supported in Windows only.

EXAMPLES

This procedure sets up a read-only browse widget for the customer table. The browse displays the Cust-num and Name fields. A separate frame, f2, displays more information on the currently chosen customer.

r-browse.p
DEFINE QUERY q1 FOR customer.  
DEFINE BROWSE b1 QUERY q1 DISPLAY cust-num name 
    WITH 17 DOWN TITLE "Customer Browse".
   
DEFINE FRAME f1
             b1
        WITH SIDE-LABELS AT ROW 2 COLUMN 2.
DEFINE FRAME f2
        WITH 1 COLUMNS AT ROW 2 COLUMN 38.
ON VALUE-CHANGED OF b1
DO:
    DISPLAY customer EXCEPT comments WITH FRAME f2.
END.
 
OPEN QUERY q1 FOR EACH customer.
ENABLE b1 WITH FRAME f1.
APPLY "VALUE-CHANGED" TO BROWSE b1.
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW. 

The VALUE-CHANGED event occurs each time the user selects a row within the browse widget. The associated database record is automatically placed into the record buffer. The trigger on the VALUE-CHANGED event displays that record in frame f2.

The APPLY statement causes the first Customer record to display before the user selects a record.

The second example sets up an updateable browse that displays some fields from the customer table. Select a row marker to select a row. Select a cell to edit it. Select a column label to initiate a search.

r-brows2.p
DEFINE QUERY q1 FOR customer SCROLLING.
DEFINE BROWSE b1 QUERY q1 NO-LOCK DISPLAY cust-num name phone
    ENABLE name phone WITH 15 DOWN NO-ASSIGN SEPARATORS.
DEFINE VARIABLE method-return AS LOGICAL NO-UNDO.
DEFINE BUTTON button1 LABEL "New Row".
DEFINE FRAME f1 
    SKIP(1)
    SPACE(8) b1 SKIP(1)
    SPACE(8) button1
        WITH NO-BOX.

ON ROW-LEAVE OF b1 IN FRAME f1 /* No-Assign Browser */
DO:
    /* If new row, create record and assign values in browse. */
    IF b1:NEW-ROW THEN DO:
        CREATE CUSTOMER.
        ASSIGN INPUT BROWSE b1 name phone.
        DISPLAY cust-num WITH BROWSE b1.
       method-return = b1:CREATE-RESULT-LIST-ENTRY().
         RETURN.
    END.
   /* If record exists and was changed in browse, update it. */
    IF BROWSE b1:CURRENT-ROW-MODIFIED then DO:
        GET CURRENT q1 EXCLUSIVE-LOCK.
        IF CURRENT-CHANGED customer THEN DO:
            MESSAGE "This record has been changed by another user."
                SKIP "Please re-enter your changes.".
            DISPLAY cust-num name phone WITH BROWSE b1.
            RETURN NO-APPLY.
        END.
        ELSE /* Record is the same, so update it with exclusive-lock */
            ASSIGN INPUT BROWSE b1 name phone.
        /* Downgrade the lock to a no-lock. */
        GET CURRENT q1 NO-LOCK.
    END.
END.

ON CHOOSE OF button1 IN FRAME f1 /* Insert */
DO:
    method-return = b1:INSERT-ROW("AFTER").
END.
OPEN QUERY q1 FOR EACH customer.
ENABLE ALL WITH FRAME f1.
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW 


The trigger on ROW-LEAVE is only necessary because the NO-ASSIGN option prevents automatic commitment of the data when the user leaves a row.

NOTES

SEE ALSO

ADD-CALC-COLUMN() Method, ADD-COLUMNS-FROM( ) Method, ADD-LIKE-COLUMN( ) Method, CLOSE QUERY Statement, CREATE BROWSE Statement, CURRENT-CHANGED Function, CURRENT-RESULT-ROW Function, DEFINE QUERY Statement, DISPLAY Statement, FIND Statement, Format Phrase, Frame Phrase, GET Statement, NUM-RESULTS Function, OPEN QUERY Statement, RUN Statement


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