15. Embedded Forms Program Structure : The Display Block : How Returning from an Operation Works
 
Share this page                  
How Returning from an Operation Works
An activate section can end when all of its associated statements have been executed, or it can end when a resume, enddisplay, or breakdisplay is executed.
In some instances, the operation can end if a timeout occurs. The timeout feature lets the programmer specify how long the FRS can wait for keyboard input from the user. If the user fails to supply some keyboard input within the specified time, then the display loop times out and exits. Control returns to the statement unless the display block contains an activate timeout block.
Going Back to the FRS
When an activate section ends, control returns to the FRS, unless an enddisplay or breakdisplay is issued. When control returns to the FRS, the FRS positions the cursor on the same field that it was on prior to the operation. If there are any entry activations defined for the field, this default behavior does not cause them to be performed.
If the default behavior is not satisfactory, you can change the behavior with the resume statement. You can place the cursor exactly where you want it when an operation ends or you can cause an entry activation operation when the cursor returns to the original field.
For example, it is not appropriate to allow an operation activated by the after field condition to use the default because each time the user tried to move on to another field, the operation executes and the cursor returns to the same field. To solve this problem, use the resume statement as the last executable statement in the operation:
resume next;
Use resume next only in an activate field or activate column section.
The various resume statements are as follows:
resume entry
Positions the cursor on the same field that it was on before the operation and causes any entry activations defined for that field to be performed
resume next
Continues the prior action. This is often used to ensure that an operation, such as a cursor movement, which initiates a field activation, is completed when the field activation is finished.
resume field fieldname
Positions the cursor on the specified field
resume column tablename columnname
Positions the cursor on the specified column of the specified table field
resume menu
Positions the cursor on the menu line. You cannot use this resume statement to position the cursor on a simple, non-nested submenu (that is, a menu displayed with the submenu statement).
resume nextfield
Positions the cursor on the first accessible field that is next in the tab sequence
resume previousfield
Positions the cursor on the first accessible field that is before the current field in the tab sequence
How You Terminate the Display Loop
You can terminate a display loop by issuing an enddisplay or breakdisplay from within an operation or you can create a separate operation that ends the display. For example, the following activate block creates an End operation that contains an enddisplay to end the display loop:
exec frs activate menuitem 'End', frskey3;
 exec frs begin;
     exec frs enddisplay;
exec frs end;
The enddisplay terminates the display loop after the FRS performs a validation check on the data in the form. (Validation criteria can be specified for fields when the form is defined in VIFRED. See How Field Validation Works for more information about validations.) If there are no errors in the data, the FRS executes the finalize statement (if any) and then transfers control to the first statement following the end of the display block in the program. If invalid data is found, the display loop continues, with the cursor resuming on the field in error, if possible. (It is not possible if the invalid data was found in an invisible or display-only field.)
To terminate the display loop without validating the data in the form or executing the finalize statement, use the breakdisplay statement. This statement is useful if, for example, you want to discard the data entered on the form.
Finally, if a display block contains no activate statements, the runtime user terminates the display loop when the Menu key is pressed by the user. However, if the display block contains any activate menuitem or frskey statements, the program must provide an explicit means for the user to exit from the display loop.
How the Timeout Feature Works
The timeout feature enables you to control how long the forms system waits for requested input from a user in a forms-based application. If the user fails to perform some keyboard action or respond to a prompt or message in the specified time, the forms system terminates the FRS statement that is waiting for input.
To set the timeout period use the set_frs statement. Once set, the timeout period applies to all display loops, prompts, messages, and all error messages requiring a carriage return for confirmation. The period remains in effect until the forms session is finished or another set_frs statement is issued to change the period's length. The specifying statement can be inside or outside of a display loop, or inside a nested display loop; once executed, it affects the application globally. (If inside a display block, the statement must be inside an activate section.)
Timeouts set in an application do not, however, affect any procedures called by the application. If you want to impose timeout limits on called procedures, you must do so in the code of the called procedure itself. Additionally, timeouts set in an application have no effect on any Ingres tools called by your application using the call statement.
By default, when a display loop times out, the loop exits as if a breakdisplay had been issued. No field validations are performed and the finalize statement is not executed. As an alternative, you can place an activate timeout block in the loop, which executes whenever the display loop times out. Use this block to ensure that the display loop is exited properly, and that all open transactions, display loops, and select loops are correctly terminated. (See the activate statement description for more information about activate timeout blocks.)
If the timeout occurs outside of a display loop while the forms system is waiting for a response to a prompt or message, the system behaves as if the user had typed a carriage return. You can use the inquire_frs statement with the command constant to determine if the user's exit is due to an actual carriage return or a timeout.