Back to Contents

Prompt for Values

Summary:

• Basics
• Syntax
• Usage
  • Programming Steps
  • Instruction Configuration
  • Default Actions
  • Interaction Blocks
• Examples

See also: Record Input, Programs, Variables

Basics

The PROMPT instruction can be used to query for a single value from the user.

In graphical mode, the PROMPT instruction opens a modal window with an OK button and a Cancel button:

PROMPT

Purpose:

The PROMPT statement can assign a user-supplied value to a variable.

Syntax:

where dialog-control-block is one of :

{ ON IDLE idle-seconds
  statement
  [...]
| ON ACTION action-name
  statement
  [...]
| ON KEY ( key-name [,...] )
  statement
  [...]
}

Notes:

1. question is a string expression displayed as a message for the input of the value.
2. question-attributes defines the display attributes for the question. See below for more details.
3. variable is the name of the variable that receives the data typed by the user.
4. The FOR CHAR clause exits the prompt statement when the first character has been typed.
5. number is the help message number to be displayed when the user presses the help key.
6. input-attributes defines the display and control attributes for the input area. See below for more details.
7. key-name is an hot-key identifier (like F11 or Control-z).
8. action-name identifies an action that can be executed by the user.
9. idle-seconds is an integer expression that defines a number of seconds.
10. statement is an instruction that is executed when the user presses the key defined by key-name.

The following table shows the question-attributes supported by the PROMPT statement:

The following table shows the display attributes that can be used in input-attributes:

The following table shows the control attributes that can be used in input-attributes:

Warnings:

1. The ON KEY blocks are provided for backward compatibility; use ON ACTION instead.
2. Because of backward compatibility, the prompt is finished after ON IDLE, ON ACTION, ON KEY block execution!

Usage:

You can use this instruction to manage a single value input.

Usage

Programming Steps

To use the PROMPT statement, you must do the following:

1. Declare a program variable with the DEFINE statement.
2. Describe the PROMPT statement, with dialog-control-blocks to control the instruction.
3. After executing the PROMPT, check the INT_FLAG variable to verify if the input was validated or canceled by the user.

You can use this instruction to manage a single value input. You provide the text of the question to be displayed to the user and the variable that receives the value entered by the user. The runtime system displays the question in the prompt area (typically a popup window), waits for the user to enter a value, reads whatever value was entered until the user validates (for example with the RETURN key), and stores this value in a response variable. The prompt dialog remains visible until the user enters a response.

Instruction Configuration

The HELP clause specifies the number of a help message to display if the user invokes the help while executing the instruction. The predefined 'help' action is automatically created by the runtime system. You can bind action views to the 'help' action.

Default Actions

When an PROMPT instruction executes, the runtime system creates a set of default actions.

The following table lists the default actions created for this dialog:

Interaction Blocks

You can use ON ACTION blocks to execute a sequence of instructions when the user raises a specific action. This is the preferred solution compared to ON KEY blocks, because ON ACTION blocks use abstract names to control user interaction.

Warning: Because of backward compatibility, the prompt is finished after ON IDLE, ON ACTION, ON KEY block execution!

The ON IDLE idle-seconds clause defines a set of instructions that must be executed after idle-seconds of inactivity. The parameter idle-seconds must be an integer expression. If it evaluates to zero, the timeout is disabled. 

For backward compatibility, you can use ON KEY blocks to execute a sequence of instructions when the user presses a specific key. The following key names are accepted by the compiler:

Examples

Example 1: Simple PROMPT

01 MAIN
02   DEFINE birth DATE
03   DEFINE chkey CHAR(1)
04   PROMPT "Please enter your birthday: " FOR birth
05   DISPLAY "Your birthday is : " || birth
06   PROMPT "Now press a key... " FOR CHAR chkey
07   DISPLAY "You pressed: " || chkey
08 END MAIN

Example 2: PROMPT with ATTRIBUTE and ON ACTION handlers

01 MAIN
02   DEFINE birth DATE
03   LET birth = TODAY
04   PROMPT "Please enter your birthday: " FOR birth
05      ATTRIBUTE(WITHOUT DEFAULTS)
06         ON ACTION action1
07            DISPLAY "Action 1"
08   END PROMPT
09   DISPLAY "Your birthday is " || birth
10 END MAIN