Back to Contents

Record Input

Summary:

• Basics
• Syntax
• Usage
  • Programming Steps
  • Instruction Configuration
  • Default Actions
  • Control Blocks
  • Control Blocks Execution Order
  • Interaction Blocks
  • Control Instructions
  • Control Class
  • Control Functions
• Examples

See also: Variables, Records, Windows, Forms, Record Display, Display Array

Basics

The programs maintain data in variables and use the INPUT statement to bind variables to screen-records or screen-arrays of forms for data entry into form fields. The INPUT statement activates the current form (the form that was most recently displayed or the form in the current window):

During the INPUT statement execution, the user can edit the record fields, while the program controls the behavior of the instruction with control blocks:

To terminate the INPUT execution, the user can validate (or cancel) the dialog to commit (or invalidate) the modifications made in the record:

When the statement completes execution, the form is de-activated. After the user terminates the input (for example, with the Accept key), the program must test the INT_FLAG variable to check if the dialog was validated (or canceled), and then can use the INSERT or UPDATE SQL statements to modify the appropriate database tables.

INPUT

Purpose:

The INPUT statement supports data entry into the fields of the current form.

Syntax 1: Implicit field-to-variable mapping

Syntax 2: Explicit field-to-variable mapping

where dialog-control-block is one of:

{ BEFORE INPUT
    dialog-statement
    [...]
| AFTER INPUT
    dialog-statement
    [...]
| BEFORE FIELD field-list
    dialog-statement
    [...]
| AFTER FIELD field-list
    dialog-statement
    [...]
| ON CHANGE field-list
    dialog-statement
    [...]
| ON IDLE idle-seconds
    dialog-statement
    [...]
| ON ACTION action-name
    dialog-statement
    [...]
| ON KEY ( key-name [,...] )
    dialog-statement
    [...]
}

where dialog-statement is one of:

{ statement
| ACCEPT INPUT
| CONTINUE INPUT
| EXIT INPUT
| NEXT FIELD { CURRENT | NEXT | PREVIOUS | field-name }
}

where field-list is:

{ field-name
| table-name.*
| table-name.field-name
| screen-array[line].*
| screen-array[line].field-name
| screen-record.*
| screen-record.field-name
} [,...]

Notes:

1. variable is a program variable that will be filled by the INPUT statement.
2. record.* is a record variable that will be filled by the INPUT statement.
3. help-number is an integer that allows you to associate a help message number with the instruction.
4. field-name is the identifier of a field of the current form.
5. table-name is the identifier of a database table of the current form.
6. screen-record is the identifier of a screen record of the current form.
7. screen-array is the screen array that will be used in the form.
8. key-name is a hot-key identifier (like F11 or Control-z).
9. idle-seconds is an integer expression that defines a number of seconds.
10. action-name identifies an action that can be executed by the user.
11. field-name identifies a field used in the dialog instruction.
12. statement is any instruction supported by the language.

The following table shows the display-attributes supported by the INPUT statement:

The following table shows the control-attributes supported by the INPUT statement:

Usage:

When the runtime system encounters an INPUT statement, it does the following::

1. Displays the program array values in the screen fields.
2. Selects the first field in the input list.
3. Waits for the user to initiate an action on the form (input, validation or cancellation).

The INPUT statement does not terminate until the user validates or cancels the dialog.

Warnings:

1. The ON KEY blocks are supported for backward compatibility, use ON ACTION instead.
2. For new programs, use the UNBUFFERED mode instead of the default buffered mode.

Usage

Programming Steps

The following steps describe how to use the INPUT statement:

1. Create a form specification file, with an optional screen record. The screen record identifies the presentation elements to be used by the runtime system to display the records. if you omit the declaration of the screen record in the form file, the runtime system will use the default screen records created by the form compiler for each table listed in the TABLES section and for the FORMONLY pseudo-table.
2. Make sure that the program controls interruption handling with DEFER INTERRUPT, to manage the validation/cancellation of the interactive dialog.
3. Define a program record with the DEFINE instruction. The members of the program record must correspond to the elements of the screen record, by number and data types. 
4. Open and display the form, using an OPEN WINDOW with the WITH FORM clause.
5. If needed, fill the program record with data, for example with a result set cursor.
6. Write the INPUT statement to handle data input.
7. Inside the INPUT statement, control the behavior of the instruction with BEFORE INPUT, BEFORE FIELD, AFTER FIELD, AFTER INPUT and ON KEY blocks.
8. After the INPUT ARRAY statement, test the INT_FLAG pre-defined variable to check if the interactive dialog was canceled ( INT_FLAG = TRUE ) or validated ( INT_FLAG = FALSE ).

Variable Binding

The program record member variables are bound to the fields of a screen record, so the INPUT instruction can manipulate the values that the user enters in the screen record.

The BY NAME clause implicitly binds the fields to the variables that have the same identifiers as the field names. You must first declare variables with the same names as the fields from which they accept input. The runtime system ignores any record name prefix when making the match. The unqualified names of the variables and of the fields must be unique and unambiguous within their respective domains. If they are not, the runtime system generates an exception, and sets the STATUS variable to a negative value.

The FROM clause explicitly binds the fields in the screen record to a list of program variables that can be simple variables or records. The form can include other fields that are not part of the specified variable list, but the number of variables or record members must equal the number of fields listed in the FROM clause. Each variable must be of the same (or a compatible) data type as the corresponding screen field. When the user enters data, the runtime system checks the entered value against the data type of the variable, not the data type of the screen field.

The member variables of the records in a program array can be of any data type. If a variable is declared LIKE a SERIAL column, however, the runtime system does not allow the screen cursor to stop in the field. (Values in SERIAL columns are automatically generated by the database server, not by the runtime system.)

The variables are the interface to display data or to get user input through the INPUT instruction. Always use the variables if you want to change some field values programmatically. When using the UNBUFFERED attribute, the instruction is sensitive to program variable changes. If you need to display new data during the INPUT execution, use the UNBUFFERED attribute and assign the values to the program variables; the runtime system will automatically display the values to the screen:

01 INPUT p_items.* FROM s_items.* ATTRIBUTES(UNBUFFERED)
02    ON CHANGE code
03       IF p_items.code = "A34" THEN
04          LET p_items.desc = "Item A34"
05       END IF
06 END INPUT

When the INPUT instruction executes, any column default values are displayed in the screen fields, unless you specify the WITHOUT DEFAULTS keywords. The column default values are specified in the form specification file with the DEFAULT attribute, or in the database schema files.

If you specify the WITHOUT DEFAULTS option, however, the form fields display the current values of the variables when the INPUT statement begins. This option is available with both the BY NAME and the FROM binding clauses.

01 LET p_items.code = "A34"
02 INPUT p_items.* FROM s_items.* WITHOUT DEFAULTS
03    BEFORE INPUT
04       MESSAGE "You should see A34 in field 'code'..."
05 END INPUT

Instruction Configuration

The ATTRIBUTE clause specifications override all default attributes and temporarily override any display attributes that the OPTIONS or the OPEN WINDOW statement specified for these fields. While the INPUT statement is executing, the runtime system ignores the INVISIBLE attribute.

Using the FIELD ORDER FORM attribute: By default, the tabbing order is defined by the variable binding list in the instruction description. You can control the tabbing order by using the FIELD ORDER FORM attribute: When this attribute is used, the tabbing order is defined by the TABINDEX attribute of the form fields.

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

The default order in which the focus moves from field to field in the screen array is determined by the order of the variables used by the INPUT statement. The program options instruction can also change the behavior of the INPUT instruction, with the INPUT WRAP or FIELD ORDER options.

Default Actions

When an INPUT instruction executes, the runtime system creates a set of default actions. See the control block execution order to understand what control blocks are executed when a specific action is fired.

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

The accept and cancel default actions can be avoided with the ACCEPT and CANCEL dialog control attributes:

01  INPUT BY NAME field1 ATTRIBUTES( CANCEL=FALSE )
02       ...

Control Blocks

The BEFORE INPUT block is executed one time, before the runtime system gives control to the user. You can implement initialization in this block.

The AFTER INPUT block is executed one time, after the user has validated or canceled the dialog, and before the runtime system executes the instruction that appears just after the INPUT block. You typically implement dialog finalization in this block. The AFTER INPUT block is not executed if  EXIT INPUT executes. 

A BEFORE FIELD block is executed each time the cursor enters into the specified field, when moving the focus from field to field.

An ON CHANGE block is executed when the value changes in the specified field for RadioGroup, ComboBox and CheckBox views, when the cursor leaves the specified field and the value was changed by the user since the field got the focus. If both an ON CHANGE block and AFTER FIELD block are defined for a field, the ON CHANGE block is executed before the AFTER FIELD block.

An AFTER FIELD block is executed each time the cursor leaves the specified field, when moving the focus from field to field.

Control Block Execution Order

The following table shows the order in which the runtime system executes the control blocks in the INPUT instruction, according to the user action:

Interaction Blocks

The ON IDLE idle-seconds clause defines a set of instructions that must be executed after idle-seconds of inactivity. This can be used, for example, to quit the dialog after the user has not interacted with the program for a specified period of time. The parameter idle-seconds must be an integer expression. If it evaluates to zero, the timeout is disabled. 

01 ...
02    ON IDLE 10
03       IF ask_question("Do you want to leave the dialog?") THEN
04          EXIT INPUT
05       END IF
06 ...

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.

01 ...
02    ON ACTION zoom
03       CALL zoom_customers() RETURNING st, cust_id, cust_name
04       ...

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:

Control Instructions

The NEXT FIELD field-name instruction gives the focus to the specified field. You typically use this instruction to control field input dynamically, in BEFORE FIELD or AFTER FIELD blocks. Abstract field identification is supported with the CURRENT, NEXT and PREVIOUS keywords. These keywords represent respectively the current, next and previous fields, corresponding to variables as defined in the input binding list (with the FROM or BY NAME clause).

The CONTINUE INPUT instruction continues the execution of the INPUT instruction, skipping all statements appearing after this instruction. Use this instruction to give control back to the interactive dialog, for example after testing for a special situation where the user must continue to input data.

You can use the EXIT INPUT statement to terminate the INPUT instruction and resume the program execution at the instruction following the INPUT block.

The ACCEPT INPUT instruction validates the INPUT instruction and exits the INPUT instruction if no error is raised. The AFTER FIELD, ON CHANGE, etc. control blocks will be executed. Statements after the ACCEPT INPUT will not be executed: the statement acts like a CONTINUE {INPUT|CONSTRUCT}.

The CLEAR field-list instruction can be used to clear a specific field or all fields in a line of the screen record. You can specify the screen record as described in the following table:

Warning: When using the UNBUFFERED attribute, it is not recommended that you use the CLEAR instruction; always use program variables to set field values to NULL.

Control Class

Inside the dialog instruction, the predefined keyword DIALOG represents the current dialog object. It can be used to execute methods provided in the dialog built-in class.

For example, you can enable or disable an action with the setActionAction() dialog method, or you can also hide and show the default action view with the setActionHidden() method: 

01 ...
02    BEFORE INPUT
03       CALL DIALOG.setActionActive("zoom",FALSE)
04    AFTER FIELD field1
05       CALL DIALOG.setActionHidden("zoom",1)
06 ...

The setFieldActive() method can be used to enable or disable a field during the dialog. This instruction takes an integer expression as argument.

01 ...
02    ON CHANGE custname
03       CALL DIALOG.setFieldActive( "custaddr", (rec.custname IS NOT NULL) )
04 ...

Control Functions

The language provides several built-in functions and operators to use in a INPUT statement. For example: FIELD_TOUCHED(), FGL_DIALOG_GETFIELDNAME(), FGL_DIALOG_GETBUFFER().

Examples

Example 1: Simple INPUT statement using an explicit screen record

Form definition file:

01 DATABASE stores
02
03 LAYOUT
04 GRID
05 {
06   Customer : [f001    ]
07   Name     : [f002                    ]
08   Last Name: [f003                    ]
09 } 
10 END
11 END
12 
13 TABLES
14   customer
15 END
16 
17 ATTRIBUTES
18   f001 = customer.customer_num ;
19   f002 = customer.fname, default = "<no name>", upshift ;
20   f003 = customer.lname ;
21 END
22 
23 INSTRUCTIONS
24   SCREEN RECORD sr_cust(
25     customer.customer_num,
26     customer.fname,
27     customer.lname);
28 END

Program source code:

01 MAIN
02 
03     DEFINE custrec RECORD
04             id INTEGER,
05             first_name CHAR(30),
06             last_name CHAR(30)
07     END RECORD
09 
10     DEFER INTERRUPT
11     DEFER QUIT
12 
13     OPEN WINDOW w1 AT 1,1 WITH FORM "FormFile"
14 
15     LET INT_FLAG = FALSE
16     INPUT custrec.* FROM sr_cust.*
17 
18     IF INT_FLAG = FALSE THEN
19        DISPLAY custrec.*
20     END IF
21
22     CLOSE WINDOW w1
23
24 END MAIN

Example 2: Complex INPUT statement using the BY NAME clause and control blocks

Form definition file:

01 DATABASE stores
02
03 LAYOUT
04 GRID
05 {
06   Customer : [f001    ]
07   Name     : [f002                    ]
08   Last Name: [f003                    ]
09 } 
10 END
11 END
12 
13 TABLES
14   customer
15 END
16 
17 ATTRIBUTES
18   f001 = customer.customer_num ;
19   f002 = customer.fname, upshift ;
20   f003 = customer.lname ;
21 END

Program source code:

01 MAIN
02 
03     DEFINE custrec RECORD
04             customer_num INTEGER,
05             fname CHAR(30),
06             lname CHAR(30)
07     END RECORD
09 
10     DEFER INTERRUPT
11     DEFER QUIT
12 
13     OPEN WINDOW w1 AT 1,1 WITH FORM "FormFile"
14 
15     LET INT_FLAG = FALSE
16     LET custrec.customer_num = 0
17     LET custrec.fname = "<no name>"
18     LET custrec.lname = NULL
19     INPUT BY NAME custrec.* WITHOUT DEFAULTS
20        BEFORE INPUT
21          MESSAGE "Enter customer details..."
22        AFTER FIELD fname
23          IF FIELD_TOUCHED(custrec.fname)
24             AND custrec.fname IS NULL THEN
25             LET custrec.lname = NULL
26             DISPLAY BY NAME custrec.lname
27          END IF
28        BEFORE FIELD lname
29          IF NOT canEditLastName() THEN
30            NEXT FIELD fname
31          END IF
32        AFTER INPUT
33          MESSAGE "Input terminated..."
34     END INPUT
35 
36     IF INT_FLAG = FALSE THEN
37        DISPLAY custrec.*
38     END IF
39
40     CLOSE WINDOW w1
41
42 END MAIN