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.
The following table lists the keys you can use within a TEXT field and their actions.
Table 56. 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.
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:
[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.
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.
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".
In the context of the .NET blocking method, System.Windows.Forms.Application:Run( ), if you directly or indirectly execute the PROMPT-FOR statement while displaying a non-modal ABL window, in certain contexts (such as within a user-defined function or non-VOID method) this statement execution raises the STOP condition. For more information on the .NET Application:Run( ), method, see the reference entry for the WAIT-FOR statement (.NET andABL).
ENABLE — Enables the specified field-level widgets (in this case fill-in fields) for input
