PERFORM SUBSTATEMENT - DATA FIELD TRIGGER IN FORM LAYOUTS

The PERFORM substatement of the FIELD statement specifies a Process Module (PM) trigger that is associated with a data field.

The execution of the PM trigger allows the opportunity for the field value to be checked. Such a PM trigger is typically used to validate the input value, to perform a security check, or to perform calculations based on the input value so that the result is reflected in other data fields. The field value can be rejected, the form operation terminated, or calculations performed based on the field's value.

For forms, a PERFORM substatement without options executes the trigger for a field when one of the following conditions are met:

1) The number of digits or characters entered from the keyboard equals the width of the data entry.

2) The user entered data into the field and pressed:

a) one of the arrow keys

b) one of the keys defined in @TERM_LIST (by default, the Tab and Return keys)

3) The user pressed the key contained in @END_CODE or @CANCEL_CODE.

NOTE: If no data is entered in a field on a form, the PERFORM substatement is not executed unless the ALWAYS AFTER option is specified (explained below).

If the FILL is executed at the command level, this substatement is ignored. This substatement is also ignored if a FILL statement is executed in a PM and the trigger specified does not exist.

After the trigger is executed, ACCENT R returns to the form and continues the form operation unless @FILL_ACTION has been set, as explained below.

The action that the FILL statement should perform can be specified by changing the value of @FILL_ACTION. If the value of @FILL_ACTION is not changed, the FILL statement will proceed to the next field. The valid values of @FILL_ACTION are:

"INVALID" resumes the form operation after the execution of the trigger. The cursor remains at the current field, the bell rings, and the current value of the field is re-displayed. If the field's value is changed in the trigger, the new value will be displayed. The user will have the option of accepting the new value or entering a correct value. If a data entry error is detected in the trigger, @FILL_ACTION can be set to "INVALID" and an error message displayed that asks the user to reenter the data.

"END" terminates the form operation. This is equivalent to typing the terminating code specified in @END_CODE. If a final trigger is defined, it will be executed.

"REDISPLAY" causes SMF to update all values in the form upon return from the trigger. "REDISPLAY" enables new values to be displayed for form fields that were changed in the trigger. Any changes to field values that were made within the trigger will then be reflected on the screen.

"REDO" causes SMF to position the cursor at this field again and wait for operator input upon return from the trigger. All data entry areas retain their previous values. This is useful when there are additional steps needed after the user has entered data for a field correctly.

NOTE: The user can be prevented from terminating a form with the keys in @END_CODE and @CANCEL_CODE. In the performed trigger for a field, assign "REDO" or "INVALID" to @FILL_ACTION.

SYNTAX

/[PERFORM trigger_name [/ALWAYS/ {BEFORE; AFTER}]]

trigger_name	specifies an existing trigger name of the current PM.
BEFORE	performs a trigger as soon as the cursor is moved to the field. Some useful functions that the performed trigger could do are display a prompt, a help message, a form, or a menu. If a trigger by the given name does not exist in the PM execution continue normally.The performed trigger could also move the cursor to another field based on some condition by setting a value to the system field @NEXT_ITEM.
AFTER	performs the trigger when data is entered into the field or when the cursor is moved to another field, or when the form operation is terminated. PERFORM ALWAYS AFTER executes the routine unconditionally, even if the user presses one of the cursor arrow keys.
	Examples of functions that the trigger could perform are checking to see if data has been entered into the field, validating data, forcing the user to enter data into the field, moving the cursor to another field, or unpasting a window. When the trigger is executed with PERFORM ALWAYS AFTER, @FILL_ACTION has;
	1) "DATA" if any of the following occurred: A value was input for a ENTER field. A value was modified for a CHANGE field. The cursor passed through a SHOW field (which always contains data). NOTE: that the cursor does not stop at a SHOW field, but only passes through it. A CHOICE field was selected with one of the keys defined in @TERM_LIST. 2) "NODATA" if none of the above occurred.

EXAMPLE 1: PERFORM WITHOUT OPTIONAL CLAUSES

/PERFORM FIGURE_SALES

This substatement shows that the trigger FIGURE_SALES is executed after the data is entered into the corresponding field.

EXAMPLE 2: PERFORM ALWAYS BEFORE & ALWAYS AFTER CLAUSES

This example shows how these substatements can be used to display a window when the cursor moves to a field. The information window is removed when the cursor moves to the next field. Two triggers are performed for the FORM field:

/      FIELD 8 22 8 @NORMAL REQ_DATE, CHANGE
/          PERFORM VALID_DATES ALWAYS BEFORE
/          PERFORM VALID_DATES_EXIT ALWAYS AFTER

The triggers in the PROCESS Section are shown below. VALID_DATES is a help box that displays acceptable formats for a date field. Note that the trigger VALID_DATES_EXIT is always executed, even if the user has not entered any data in the field and has only pressed a cursor arrow key or one of the characters in the system field @TERM_LIST.

ROUTINE VALID_DATES
      GENERATE VALID_DATES TO VALID_DATES_ID IF (VALID_DATES_ID EQ 0)
      SCREEN PASTE_WINDOW USING VALID_DATES_ID, 11, 22
ROUTINE VALID_DATES_EXIT
          SCREEN UNPASTE_WINDOW USING VALID_DATES_ID

Screen before cursor is moved to Order Date

Figure 10 Screen before Cursor is moved to Order Date

This figure shows a window with the cursor positioned on the P.O. Number field.

Screen after cursor is moved to Order Date

Figure 11 Screen after Cursor is moved to Order Date

When the user moves the cursor to the Date Requested field, the trigger that is specified in the PERFORM ALWAYS BEFORE statement is executed which pastes a help box as shown here. When the cursor moves to another field, the help box is unpasted by the routine specified in the PERFORM ALWAYS AFTER statement. See the system field @ERROR for additional error checking.

The LAYOUT segment for the pasted window is shown below. The LAYOUT has a field called BLANK (with a length of 1 and a type of SHOW) that is needed because a form layout must have at least one FIELD statement. The field is not visible on the displayed window and the cursor does not stop at it. This illustrates how to have a form with message text only.

LAYOUT SCREEN VALID_DATES

/ FILL     11 22 6 23 @NORMAL

/ SELECTION           @NORMAL

/ BORDER

/ MESSAGE         1 3 @NORMAL "Enter a date in any"

/ MESSAGE         2 3 @NORMAL "of these formats:"

/ MESSAGE         4 7 @NORMAL "MM/DD/YY"

/ MESSAGE         5 7 @NORMAL "MM-DD-YY"

/ MESSAGE         6 7 @NORMAL "YYMMDD"

/ FIELD         7 7 1 @NORMAL BLANK:D SHOW

LAYOUT END

NOTE: This substatement is not valid for a HELP trigger or a final trigger.

Both a PERFORM ALWAYS BEFORE substatement and a PERFORM ALWAYS AFTER substatement may be specified for the same field.