Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## PROMPT-FOR statement

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

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

> - ENABLE Enables the specified field-level widgets (in this case fill-in fields) for input.

> - WAIT-FOR Blocks for input and processes all Progress events until a specific Progress event occurs, in this case the GO universal key function event.

> - DISABLE Disables the specified field-level widgets (in this case fill-in fields) for input.

> Note: Does not apply to SpeedScript programming.

> #### 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 OpenEdge Development: Programming Interfaces 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:

> - Stores the initial value of x in a record buffer.
> - Prompts for a new value of x, and stores the new value in a screen buffer.
> - Displays the value in the record buffer, retrieves the value in the screen buffer, then displays that.

> In the case of array fields, array elements with constant subscripts are treated just like any other field. Array fields with no subscripts or in the FORM statement are expanded as though you had typed in the implicit elements. See the DISPLAY statement reference entry for information on how array fields with expressions as subscripts are handled.

> ``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 41 lists the keys you can use within a TEXT field and their actions.

> Table 41: 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 following 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``

> Supported only for backward compatibility.

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

>     [ 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

> - PROMPT-FOR puts user-supplied data into a screen buffer. It does not put any data into a record buffer. Therefore, if you want to use the data in the screen buffer, you must use the INPUT function to refer to the data in the screen buffer or use the ASSIGN statement to move the data from the screen buffer into a record buffer. You can also use the USING option to FIND a record with the screen data index value.

> - When Progress compiles a procedure, it designs all the frames used by that procedure. When it encounters a PROMPT-FOR statement, Progress designs the display of the prompt fields. When the procedure is run, the PROMPT-FOR statement puts data into those fields.

> - If you are getting input from a device other than the terminal, and the number of characters read by the PROMPT-FOR statement for a particular field or variable exceeds the display format for that field or variable, Progress returns an error. However, if you are setting a logical field that has a format of “y/n” and the data file contains a value of YES or NO, Progress converts that value to “y” or “n”.

> #### See also

> DEFINE STREAM statement, EDITING phrase, Format phrase, Frame phrase

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