Progress
Language Reference


FORM Statement

Interfaces
OS
SpeedScript
All
All
Yes

Defines the layout and certain processing attributes of a frame for use within a single procedure. If the frame has not been previously scoped, the FORM statement scopes it to the current block. Use the FORM statement if you want to describe a frame in a single statement rather than let Progress construct the frame based on individual data handling statements in a block. You can use the FORM statement to describe a layout for a data iteration and the frame header or background.

SYNTAX

FORM
  [ form-item  ... ]
  [ { HEADER | BACKGROUND } head-item ... ]
  [ frame-phrase ] 

FORM record [ EXCEPT field ... ] [ frame-phrase ] 

form-item

Specifies a field-level widget or value to display in the frame, or a SPACE or SKIP directive. The data specified by all form items are owned by a single field group, duplicated for each data iteration in the frame.

This is the syntax for form-item.

SYNTAX
field [ format-phrase ] 

constant
  [ at-phrase | TO n ]
  [ BGCOLOR expression ]
  [ DCOLOR expression ]
  [ FGCOLOR expression ]
  [ FONT expression ]
  [ PFCOLOR expression ]
  [ VIEW-AS TEXT ] 

SPACE [ ( n ) ] 

SKIP [ ( n ) ] 

field

A reference to a field or variable to be displayed in the frame. This value cannot be an expression or a frame. To specify a child frame, you must first define the parent and child frames, then assign the FRAME attribute of the child frame to the widget handle of the parent frame. The child frame is assigned to the same field group as other form items.

format-phrase

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

constant

A constant value.

at-phrase

Specifies the location of a value within the frame. The AT phrase does not left justify the data; it simply indicates the placement of the data area. This is the syntax for AT phrase.

SYNTAX
AT {  n
      | { COLUMN column | COLUMN-OF relative-position }
         { ROW row | ROW-OF relative-position }
         [ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ]
      | { X x | X-OF relative-position }
         { Y y | Y-OF relative-position }
         [ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ]
   } 

For more information, see the AT Phrase reference entry.

TO n

The number (n) of the column in which you want the display to end. The TO option does not right justify the data; it simply indicates the placement of the data area.

BGCOLOR expression

Specifies the background color of the form item in graphical interfaces. This option is ignored in character interfaces.

DCOLOR expression

Specifies the display color of the form item in character interfaces. This option is ignored in graphical interfaces.

FGCOLOR expression

Specifies the foreground color of the form item in graphical interfaces. This option is ignored in character interfaces.

FONT expression

Specifies the font of the form item.

PFCOLOR expression

Specifies the prompt color of the form item in character interfaces. This option is ignored in graphical interfaces.

VIEW-AS TEXT

Specifies that the form item be displayed as a TEXT widget rather than as a FILL-IN widget.

SPACE ( n )

Identifies the number (n) of blank spaces to insert after the displayed expression. The n can be 0. If the number of spaces you specify 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 you do not use n, Progress inserts one space between items in the frame.

SKIP ( n )

Identifies the number (n) of blank lines to insert after the displayed expression. The number of blank lines can be 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.

record

Represents the name of the record you want to display. Naming a record is shorthand for listing each field individually, as a form item.

EXCEPT field . . .

Tells Progress to display all the fields in the frame except those fields listed in the EXCEPT phrase.

HEADER

Tells Progress to place the following items in a header section at the top of the frame in a separate field group from all other data. In addition to fields, variables, and constants, the frame header can contain expressions, images, and rectangles. Progress reevaluates these expressions each time it displays the frame.

When you use the FORM statement with the HEADER option, Progress disregards Data Dictionary field labels for fields you name in the FORM statement. Use character strings to specify labels for fields you name in the frame header.

BACKGROUND

Specifies that any following frame items display in the frame background, behind the data and header in a separate field group. Typically, this option is used to display images or rectangles behind the data.

head-item

A description of a value to be displayed in the frame header or background, or a SPACE or SKIP directive. This is the syntax for head-item.

SYNTAX
expression [ format-phrase ] 

constant
  [ at-phrase | TO n ]
  [ BGCOLOR expression ]
  [ DCOLOR expression ]
  [ FGCOLOR expression ]
  [ FONT expression ]
  [ VIEW-AS TEXT ] 

SPACE [ ( n ) ] 

SKIP [ ( n ) ] 

This is exactly the same as the syntax for a form-item, except that a head-item can be an expression and does not include the PFCOLOR option. If you use an expression in a HEADER or BACKGROUND phrase, the expression is evaluated each time the frame is viewed. If you give the PAGE-TOP or PAGE-BOTTOM option for the frame, the expression is evaluated for each page. This allows you, for example, to include a reference to the PAGE-NUMBER function in the frame header.

NOTE: If head-item is an expression, any option of the format-phrase may be used with it; if head-item is a constant, only the AT phrase, TO, BGCOLOR, DCOLOR, FGCOLOR, FONT and VIEW-AS TEXT options are allowed.

frame-phrase

Specifies frame options for the frame associated with the FORM statement. For more information on frame-phrase options, see the Frame Phrase reference entry.

EXAMPLES

This procedure lets the user update information on a specific customer. The FORM statement describes a very specific layout for the UPDATE statement to use.

r-form.p
REPEAT FOR customer:
    FORM name    COLON 10         phone     COLON 50
         address COLON 10         sales-rep COLON 50  SKIP
         city    COLON 10 NO-LABEL state NO-LABEL postal-code NO-LABEL
        WITH SIDE-LABELS 1 DOWN CENTERED.
    PROMPT-FOR cust-num WITH FRAME cnum SIDE-LABELS CENTERED.
    FIND customer USING cust-num.
    UPDATE name address city state postal-code phone sales-rep.
END. 

When you use the FORM statement to control the order in which fields appear on the screen, remember that this order is independent of the order in which Progress processes the fields during data entry.

In the example, the above FORM statement displays the customer name first and the phone number second. But the UPDATE statement specifies the phone number after the name, address, city, state, and postal-code. The fields are displayed as described in the FORM statement, but the tab order is determined by the UPDATE statement.

The following example uses the HEADER option.

r-eval.p
DEFINE VARIABLE i AS INTEGER FORMAT ">9".
FORM HEADER "This is the header - i is" i
    WITH FRAME a ROW i COLUMN i i DOWN.
DO i = 1 TO 8 WITH FRAME a.
  DISPLAY i.
  PAUSE.
END. 

The FORM statement defines a HEADER frame that consists of the text “This is the header - i is” and the value of the variable i. In addition, it also specifies a screen location where the header is displayed. The FORM statement does not bring the header frame into view.

On the first iteration of the DO block, the DISPLAY statement brings the frame into view. On the second iteration of the DO block, the frame is already in view (it was not hidden during the first iteration), so the header of the frame is not re-evaluated. Thus, the new value of i is not reflected in the header portion of the frame, and you do not see the new value of i in the header. You also do not see the position of the frame on the screen change.

In contrast, look at this modified version of the procedure.

r-eval2.p
DEFINE VARIABLE i AS INTEGER FORMAT ">9".
FORM HEADER "This is the header - i is" i
    WITH FRAME a ROW i COLUMN i i DOWN.
DO i = 1 TO 8 WITH FRAME a.
  DISPLAY i.
  HIDE FRAME a.
END. 


On the first iteration of the DO block, the DISPLAY statement displays the frame. The HIDE statement removes the frame from the window. Therefore, on the second iteration of the DO block, the DISPLAY statement redisplays the frame. Progress re-evaluates the header of the frame each time the frame is redisplayed. Therefore, the header of the frame reflects the change to i, and the position of the frame in the window also changes.

NOTES

SEE ALSO

DEFINE FRAME Statement, Format Phrase, Frame Phrase


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