Back to Contents

Prompt for Values

Summary:

• Basics
• Syntax
• Usage
  • Programming Steps
  • Instruction Configuration
  • Default Actions
  • Interaction Blocks
• Examples
  • Example 1: Simple PROMPT
  • Example 2: PROMPT with interrupt checking
  • Example 3: PROMPT with ATTRIBUTE and ON ACTION handlers

See also: Record Input, Programs, Variables

Basics

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

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

Syntax

Purpose:

The PROMPT statement assigns a user-supplied value to a variable.

Syntax:

where dialog-control-block is one of :

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

Notes:

1. question is a string expression displayed as a message for the input of the value.
2. question-attribute 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-attribute is a display and control attribute for the input area. See below for more details.
7. key-name is an hot-key identifier (such as F11 or Control-z).
8. action-name identifies an action that can be executed by the user.
9. idle-seconds is an integer literal or variable 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 display attributes can be used for both question-attribute and input-attribute:

The following control attributes can be used for input-attribute:

Usage

You can use the PROMPT 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.

The ON KEY blocks are provided for backward compatibility; use ON ACTION instead.

The prompt finishes after ON IDLE, ON ACTION, or ON KEY block execution (to ensure backwards compatibility).

Programming Steps

To use the PROMPT statement, you must:

1. Declare a program variable with the DEFINE statement.
2. Set the INT_FLAG variable to FALSE.
3. Describe the PROMPT statement, with dialog-control-blocks to control the instruction.
4. After executing the PROMPT, check the INT_FLAG variable to determine whether the input was validated or canceled by the user. See Example 2 below.

Instruction Configuration

HELP option

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.

ACCEPT option

The ACCEPT attribute can be set to FALSE to avoid the automatic creation of the accept default action.

CANCEL option

The CANCEL attribute can be set to FALSE to avoid the automatic creation of the cancel default action. If the CANCEL=FALSE option is set, no close action will be created, and you must write an ON ACTION close control block to create a close 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

ON ACTION block

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.

Note that because of backward compatibility, the prompt is finished after ON IDLE, ON ACTION, ON KEY block execution.

For more details about ON ACTION, see Interaction Model page.

ON IDLE block

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 literal or variable. If it evaluates to zero, the timeout is disabled.

You should not use the ON IDLE trigger with a short timeout period such as 1 or 2 seconds; The purpose of this trigger is to give the control back to the program after a relatively long period of inactivity (10, 30 or 60 seconds). This is typically the case when the end user leaves the workstation, or got a phone call. The program can then execute some code before the user gets the control back.

ON KEY block

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:

Check carefully the ON KEY CONTROL-? statements because they may result in having duplicate accelerators for multiple actions due to the accelerators defined by Action Defaults. Additionally, ON KEY statements used with ESC, TAB, UP, DOWN, LEFT, RIGHT, HELP, NEXT, PREVIOUS, INSERT, CONTROL-M, CONTROL-X, CONTROL-V, CONTROL-C and CONTROL-A should be avoided for use in GUI programs, because it's very likely to clash with default accelerators defined in the Action Defaults.

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: Simple PROMPT with Interrupt Checking

01 MAIN
02   DEFINE birth DATE
03   LET INT_FLAG = FALSE
04   PROMPT "Please enter your birthday: " FOR birth
05   IF INT_FLAG THEN
06     DISPLAY "Interrupt received."
07   ELSE
08     DISPLAY "Your birthday is : " || birth
09   END IF
10 END MAIN

Example 3: PROMPT with ATTRIBUTES and ON ACTION handlers

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