How to Apply Timers In Forms

Checked relevance 06-Feb-2008

Purpose
=======
The objective of this note is to explain how to apply and handle timers in
Forms.  This note covers time-initiated processing; that is, processing
that occurs after a certain amount of time has elapsed.  The mechanism
you use to do this is called a "Timer" and it is created, modified, and
deleted at run-time.

This document consists of the following sections:

1. What is a Timer?

2. What are the Built-in Functions for Timers?

3. When Can You Use Timers?

4. How to Create a Timer

5. How to Modify a Timer

6. How to Delete a Timer

7. How to Handle Timer Expiration
   -- What is the Relationship Between Timer Expiration and Timer Queue?

8. An Example for Showing "About" Information Using a Timer in the Form

9. Known Bugs With the Use of Timer in Forms


1) What is a Timer?
===================
Typically, Forms process events that are (originally) initiated by the user. 
You can use timers when you want Forms to perform a set of actions after a
period of time has elapsed.

A timer is a programmatic construct similar to an "internal alarm clock." 
You can create, modify, or delete timers by means of built-ins.  When you
create or modify a timer, you can specify the period of time that elapses
before the timer expires.  Using a trigger, you can specify what actions
must be performed at that time.


2) What Are the Built-in Functions For Timers?
==============================================
The following table describes the built-in functions for timers.

Built-in                  Description
------------------------  ---------------------------------------------------

Find_Timer                Returns the internal timer ID (of datatype Timer)
                          of a timer with the given name.

Create_Timer              Creates a timer with the given name. You can
                          specify the time interval and whether the timer
                          should repeat on expiration.

Set_Timer                 Changes the settings for the given timer. You can
                          modify the time interval and the repeat behavior.

Delete_Timer              Deletes the given timer.

Get_application_property  The Timer_Name property returns the name of the
                          most recently expired timers.


3) When Can You Use Timers?
===========================
You can use timers to:

-- Poll the database to check if a certain event has occurred
-- Perform an automatic query at regular intervals
-- Show "about this" Information at form startup
-- Perform an automatic commit or rollback after a specific amount of idle time

4) How to Create a Timer
========================
You can create a timer by using the CREATE_TIMER built-in function, which
returns type TIMER.

Syntax
------
CREATE_TIMER(TIMER_NAME, MILLISECONDS, ITERATE)

Parameter        Description
--------------   ------------------------------------------------------------
Timer_name       The Timer name

Millisecond      The duration of the timer in milliseconds. The value must
                 be between 1 and 2147483648 (approximately 25 days).

Iterate          Specifies whether the timer should repeat upon expiration.
                 Valid values are REPEAT (default) and NO_REPEAT.

Example
-------
At the When-New-Form-Instance trigger:

DECLARE
CST_HOUR   CONSTANT   NUMBER(7)  := 3600000
--3600000 is one hour in milliseconds

V_TIMER_ID  TIMER;

BEGIN
V_TIMER_ID := CREATE_TIMER('HOUR_ALARM', CST_HOUR);
END;


5) How to Modify a Timer
========================
You can modify a timer by using the SET_TIMER built-in procedure.

Syntax
------
SET_TIMER(TIMER_NAME, MILLISECONDS, ITERATE)
SET_TIMER(TIMER_ID, MILLISECONDS, ITERATE)

Parameter      Description
------------   -----------------------------------------------------------
Timer_name     The Timer name

Timer_ID       The internal timer ID

Millisecond    The duration of the timer in milliseconds. This value must
               be between 1 and 2147483648 (approximately 25 days), or must
               be NO_CHANGE.

Iterate        Specifies whether the timer should repeat upon expiration.
               Valid values are REPEAT (default), NO_REPEAT, AND NO_CHANGE.

Example
-------
The trigger name depends on the situation.  Set the repeat behavior of a timer
named HOUR_ALARM without changing the time interval :

BEGIN
SET_TIMER ('HOUR_ALARM', NO_CHANGE, NO_REPEAT);

6) How to Delete a Timer
========================
You can delete a timer by using the DELETE_TIMER built-in procedure.

Syntax
------
DELETE_TIMER(TIMER_NAME);
DELETE_TIMER(TIMER_ID);


Parameter     Description
-----------   ---------------------------------------------------------------
Timer_name    The Timer name

Timer_ID      The internal timer ID

Note:  Forms generates an error if you attempt to delete a non-existent timer.

Example
-------
BEGIN
IF NOT ID_NULL(FIND_TIMER('HOUR_ALARM'))
THEN
DELETE_TIMER('HOUR_ALARM');
END;


7) How to Handle Timer Expiration
=================================
When a timer expires, the when-timer-expired trigger fires and executes the
desired actions.  If you define more than one timer, you need to know which
timer expired and how expired timers are handled.

What is the Relationship Between Timer Expiration and Timer Queue?
------------------------------------------------------------------
When a timer expires, it is put in a queue of expired timers.  Forms services
this timer queue on a first-in-first-out basis, but only while it is waiting
for user actions.  After an expired timer is handled, it is removed from the
queue. 

Note: A repeating timer will not begin the next iteration while it is still
      in the timer queue.

When using the when-timer-expired trigger remember that it:

-- Fires once for each timer that expires, but only after Form Builder has
   completed any current processing of triggers and built-in functions.

-- Fires after the specified time interval, rather than exactly on the moment
   of expiration.

-- Must be defined at the form level.

-- Should include the GET_APPLICATION_PROPERTY built-in function to find out
   which timer has expired.

Example
-------
Here is an example of how to handle the expiration of two timers names
HOUR-ALARM and  ABOUT_STARTUP:

DECLARE
V_TIMER_NAME  VARCHAR2(30);
BEGIN
V_TIMER_NAME :=GET_APPLICATION_PROPERTY (TIMER_NAME);

IF V_TIMER_NAME = 'HOUR_ALARM'
THEN
    MESSAGE('ONE HOUR HAS PASSED AGAIN.');
ELSIF V_TIMER_NAME = 'ABOUT_STARTUP'
THEN
    DELETE_TIMER('ABOUT_STARTUP');
END IF;

END;

8) An Example of Showing "About" Information Using a Timer in the Form
======================================================================
Here is an example of using a timer in a form to show "About" information
at the startup of the form. This example uses the emp.fmb form that is
based on emp table.

1) Open the emp.fmb form module.

2) Add a window and a canvas to the form to display the two control items.
   The window could be considered an "About" window and should be a modal
   dialog window. Set the Hide on Exit property to YES for this window.

3) Create a new control block manually and name it ABOUT.

4) Create two items in the ABOUT block to display the user name and the
   current date and time. Call one item USER_NAME, and the other item
   CLIENT_DATE.

5) In order to show the "About" Window for a short period of time at the
   startup of the form, create a When-New-Form-Instance trigger at the Form
   level with the following code:

   DECLARE
     CST_SHOW_TIME  CONSTANT NUMBER(4) :=4000;
           V_TIMER_ID TIMER;
   BEGIN
           :ABOUT.USER_NAME := USER;
           :ABOUT.CLIENT_DATE := :SYSTEM.CURRENT_DATETIME;
           V_TIMER_ID := CREATE_TIMER ('ABOUT', CST_SHOW_TIME,
    NO_REPEAT);
           GO_ITEM('ABOUT.USER_NAME');
   END;

6) Create a When-Timer-Expired trigger at the Form level with the following
   code:

   IF GET_APPLICATION_PROPERTY(TIMER_NAME) = 'ABOUT'
     THEN
     GO_ITEM('EMPNO');
   END IF;

7) Run the form. You will get ABOUT window with the information displayed
   about the user name and the client date.  The window will be displayed for
   4 seconds.  Then, you will get the emp window, which displays the emp table
   information.