Progress
Language Reference


PROMPT-FOR Statement

Interfaces
OS
SpeedScript
All
All
No

Requests input and places that input in the screen buffer (frame).

The PROMPT-FOR statement is a combination of the following statements:

DATA MOVEMENT

SYNTAX

PROMPT-FOR 
  [ STREAM stream ]
  [ UNLESS-HIDDEN ]
  {     { field
            [ format-phrase ]
            [ WHEN expression ]
        }
     |  { TEXT ( { field
                     [ format-phrase ]
                     [ WHEN expression ]
                 } ...
               )
        }
     |  { constant
            [ { AT | TO } n ] 
            [ VIEW-AS TEXT ]
            [ FGCOLOR expression ]
            [ BGCOLOR expression ]
            [ FONT expression ]
        }
     |  SPACE [ ( n ) ]  |  SKIP [ ( n ) ]  |  ^ 
  } ... 
  [ GO-ON ( key-label ... ) ]
  [ IN WINDOW window ]
  [ frame-phrase ]
  [ editing-phrase ] 

PROMPT-FOR
  [ STREAM stream ]
  [ UNLESS-HIDDEN ]
  record [ EXCEPT field ... ] 
  [ IN WINDOW window ]
  {  [ frame-phrase ] } 

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 the Progress Programming Handbook for more information on streams.

UNLESS-HIDDEN

Restricts PROMPT-FOR to fields whose HIDDEN attribute is FALSE.

field

Specifies the name of the field or variable whose value you want to enter and store in the screen buffer. Remember that the PROMPT-FOR statement only accepts input and stores it in the screen buffer. The underlying record buffer of a field or variable is unaffected.

This field parameter is demonstrated in the following program:

DEFINE VARIABLE x AS INTEGER INITIAL 3.
PROMPT-FOR x.
MESSAGE "Record buffer" x SKIP(0) "Screen buffer" INPUT x. 

The program does the following:

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.

WHEN expression

Prompts for the field only when expression has a value of TRUE. Here, expression is a field name, variable name, or expression that evaluates to a LOGICAL value.

TEXT

Defines a group of character fields or variables (including array elements) to use automatic word-wrap. The TEXT option works only with character fields. When you insert data in the middle of a TEXT field, Progress wraps data that follows into the next TEXT field, if necessary. If you delete data from the middle of a TEXT field, Progress wraps data that follows into the empty area.

If you enter more characters than the format for the field allows, Progress discards the extra characters. The character fields must have formats of the form x(n). A blank in the first column of a line marks the beginning of a paragraph. Lines within a paragraph are treated as a group and will not wrap into other paragraphs.

Table 35 lists the keys you can use within a TEXT field and their actions.

Table 35: Key Actions in a TEXT() Field 
Key
Action
APPEND-LINE
Combines the line the cursor is on with the next line.
BACK-TAB
Moves the cursor to the previous TEXT field.
BREAK-LINE
Breaks the current line into two lines beginning with the character the cursor is on.
BACKSPACE
Moves the cursor one position to the left and deletes the character at that position. If the cursor is at the beginning of a line, BACKSPACE moves the cursor to the end of the previous line.
CLEAR
Clears the current field and all fields in the TEXT group that follow.
DELETE-LINE
Deletes the line the cursor is on.
NEW-LINE
Inserts a blank line below the line the cursor is on.
RECALL
Clears fields in the TEXT group and returns initial data values for the group.
RETURN
If you are in overstrike mode, moves to the next field in the TEXT group on the screen. If you are in insert mode, the line breaks at the cursor and the cursor is positioned at the beginning of the new line.
TAB
Moves to the field after the TEXT group on the screen.If there is no other field, the cursor moves to the beginning of the TEXT group.

In this procedure, the s-com, or Order Comments field is a TEXT field. Run the procedure and enter text in the field to see how the TEXT option works.

r-text.p
DEFINE VARIABLE s-com AS CHARACTER FORMAT "x(40)" EXTENT 5.

FORM "Shipped   :" order.ship-date AT 13 SKIP
     "Misc Info :" order.instructions AT 13 SKIP(1)
     "Order Comments :" s-com AT 1
WITH FRAME o-com CENTERED NO-LABELS TITLE "Shipping Information".

FOR EACH customer, EACH order OF customer:
    DISPLAY cust.cust-num cust.name order.order-num order.order-date
           order.promise-date WITH FRAME order-hdr CENTERED.
    UPDATE ship-date instructions TEXT(s-com) WITH FRAME o-com.
    s-com = "".
END. 

constant [ AT n | TO n ] [ VIEW-AS TEXT ] [ FGCOLOR expression ]
[ BGCOLOR expression ] [ FONT expression ]

Specifies a literal value that you want displayed in the frame. If you use the AT option, n is the column in which you want to start the display. If you use the TO option, n is the column in which you want to end the display. You can use the BGCOLOR, FGCOLOR, and FONT options to define the colors and font in which the constant is displayed. If you use the VIEW-AS TEXT option, the constant is displayed as a text widget rather than a fill-in field.

SPACE [ ( n ) ]

Identifies the number (n) of blank spaces to insert after the field is displayed. 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, a new line is started and any extra spaces are discarded. If you do not use this option or n, one space is inserted between items in the frame.

SKIP [ ( n ) ]

Identifies the number (n) of blank lines to insert after the field 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.

^

Tells Progress to ignore an input field when input is being read from a file. Also, the following statement will read a line from an input file and ignore that line. This is an efficient way to skip over lines.

PROMPT-FOR ^ 

GO-ON ( key-label . . . )

The GO-ON option tells Progress to execute the GO action when the user presses any of the keys listed. The keys you list are used in addition to keys that perform the GO action by default (such as F1 or RETURN on the last field) or because of ON statements.

When you list a key in the GO-ON option, you use the keyboard label of that key. For example, if you want Progress to take the GO action when the user presses F2, you use the statement GO-ON(F2). If you list more than one key, separate them with spaces, not commas.

IN WINDOW window

Specifies the window in which the prompt occurs. The expression window must resolve to a handle to 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.

editing-phrase

Identifies processing to take place as each keystroke is entered. This is the syntax for editing-phrase.

SYNTAX
[ label : ] EDITING: statement ... END 

For more information on editing-phrase, see the EDITING Phrase reference entry.

record

The name of a record buffer. All of the fields in the record will be processed exactly as if you prompted for each of them individually.

To use PROMPT-FOR with 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

Affects all fields except those listed in the EXCEPT phrase.

EXAMPLES

The r-prmpt.p procedure requests a customer number from the user and stores that number in the screen buffer. The FIND statement reads a record from the customer database table.

r-prmpt.p
REPEAT:
    PROMPT-FOR customer.cust-num.
    FIND customer USING cust-num NO-ERROR.
    IF NOT AVAILABLE customer THEN DO:
      MESSAGE "No such customer number." .
      UNDO, RETRY.
    END.
    DISPLAY name phone sales-rep.
END. 

The r-prmpt2.p procedure requests the initials of a sales representative and stores those initials in the screen buffer. The FIND statement uses the initials stored in the screen buffer to read a record from the salesrep database table. After finding the record, the procedure displays sales rep information.

r-prmpt2.p
REPEAT:
  PROMPT-FOR salesrep.sales-rep LABEL "Sales rep’s initials"
    WITH FRAME namefr ROW 2 SIDE-LABELS.
  FIND salesrep USING sales-rep.
  DISPLAY rep-name region month-quota WITH 1 DOWN NO-HIDE.
END. 

NOTES

SEE ALSO

DEFINE STREAM Statement, EDITING Phrase, Format Phrase, Frame Phrase


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