This statement activates a section of program code within a display block.

When the specified condition occurs, the activate statement interrupts the form's display loop and executes the associated block of code. Each condition represents a user action. When the user performs the indicated action, the associated block of code is executed. After the code is executed, control returns to the FRS and the display loop continues (unless the code executed a statement that terminated the loop).

You must place the activate statement in a display block. (A display block is that portion of code in a forms-based program that displays a form. For a discussion of display blocks and the structure of a forms-based program, see Part 4: Embedded Forms Programming.)

The begin/end block contains the code that is executed when the condition is true. You cannot put any other statements or any comment lines between the activate statement and its associated begin/end block, or between activate sections. Any such statements or comments generate a preprocessor error.

Condition can be any of the following:

The exact syntax of the activate statement varies with the chosen condition. The subsections of this statement description describe each of these conditions and its appropriate syntax. You can specify more than one condition in a single activate statement (see the examples at the end of this description).

Objectname identifies the particular object on which the specified condition is performed. For example, if the condition is menuitem, then objectname identifies a particular menu item and whenever the user selects that menu item, the associated block of code executes. Not all of the conditions require an objectname; see the separate discussions of each condition for details.

When you specify the menuitem and frskey conditions, you can include the validate and activate clauses in the statement.

The validate clause causes a validation check on the current field to take place when the activate statement is executed. (Validation checks on fields are described in Table Fields.) The activate clause causes any activate field or activate column statement associated with the current field or column to be executed before executing the activate statement associated with the menuitem or frskey. These clauses allow you to build checks and controls into the application. For example, you can use these clauses to ensure that a particular field has a valid entry before allowing the user to leave the field. An example at the end of this section illustrates using the activate clause in conjunction with field or column conditions.

The value must be either 1 or 0, or an integer variable evaluating to 1 or 0. If value is 1 for the validate clause, the FRS validates the current field before the section of code is executed. If the field fails the check, an error message is displayed, the cursor is positioned back on the field, and the section of code is not executed. When the activate clause has a value of 1, the code associated with the field or column condition for the current field or column is executed before the code for the selected menuitem or frskey condition. Assigning a value of 0 to either the validate or activate clause turns off (overrides) any validations or activations that were defined for the specified condition using the set_frs statement.

If you include both the validate and activate clauses, you must separate them with a comma.

You can always include an explicit validate statement in the associated block of code, regardless of whether the activate statement contains a validate clause.