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 ABL events until a specific ABL 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` \| STREAM-HANDLE `handle` ] [ 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 | STREAM-HANDLE handle ] 
  [ 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` \| STREAM-HANDLE `handle` ] [ 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, 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-HANDLE handle

Specifies the handle to a stream. If handle it 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-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 ix AS INTEGER NO-UNDO INITIAL 3. PROMPT-FOR ix. MESSAGE "Record buffer" ix SKIP(0) "Screen buffer" INPUT x.

The program does the following:

Stores the initial value of ix in a record buffer

Prompts for a new value of ix, 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, the AVM wraps data that follows into the next TEXT field, if necessary. If you delete data from the middle of a TEXT field, the AVM wraps data that follows into the empty area.

If you enter more characters than the format for the field allows, the AVM 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 55 lists the keys you can use within a TEXT field and their actions.

Table 55: 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 NO-UNDO FORMAT "x(40)" EXTENT 5. FORM "Shipped :" Order.ShipDate 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 NO-LOCK, EACH Order OF Customer: DISPLAY Customer.CustNum Customer.Name Order.OrderNum Order.OrderDate Order.PromiseDate WITH FRAME order-hdr CENTERED. UPDATE Order.ShipDate Order.Instructions TEXT(s-com) WITH FRAME o-com. s-com = "". END.

r-text.p

DEFINE VARIABLE s-com AS CHARACTER NO-UNDO FORMAT "x(40)" EXTENT 5. 
FORM  
  "Shipped   :" Order.ShipDate 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 NO-LOCK, EACH Order OF Customer: 
  DISPLAY Customer.CustNum Customer.Name Order.OrderNum Order.OrderDate 
    Order.PromiseDate WITH FRAME order-hdr CENTERED. 
  UPDATE Order.ShipDate Order.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, 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 specify n, or if n is 0, the AVM starts a new line unless it is already at the beginning of a new line.

Tells the AVM 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 the AVM 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 the AVM 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:

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.CustNum. FIND Customer USING Customer.CustNum NO-ERROR. IF NOT AVAILABLE Customer THEN DO: MESSAGE "No such customer number.". UNDO, RETRY. END. DISPLAY Customer.Name Customer.Phone Customer.SalesRep. END.

r-prmpt.p

REPEAT: 
  PROMPT-FOR Customer.CustNum. 
  FIND Customer USING Customer.CustNum NO-ERROR. 
  IF NOT AVAILABLE Customer THEN DO: 
    MESSAGE "No such customer number.". 
    UNDO, RETRY. 
  END. 
  DISPLAY Customer.Name Customer.Phone Customer.SalesRep. 
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.SalesRep LABEL "Sales rep’s initials" WITH FRAME namefr ROW 2 SIDE-LABELS. FIND SalesRep NO-LOCK USING SalesRep.SalesRep. DISPLAY SalesRep.RepName SalesRep.Region SalesRep.MonthQuota WITH 1 DOWN NO-HIDE. END.

r-prmpt2.p

REPEAT: 
  PROMPT-FOR SalesRep.SalesRep LABEL "Sales rep’s initials" 
    WITH FRAME namefr ROW 2 SIDE-LABELS. 
  FIND SalesRep NO-LOCK USING SalesRep.SalesRep. 
  DISPLAY SalesRep.RepName SalesRep.Region SalesRep.MonthQuota  
    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 ABL compiles a procedure, it designs all the frames used by that procedure. When it encounters a PROMPT-FOR statement, ABL 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, the AVM 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, the AVM converts that value to “y” or “n”.