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?
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;
=======
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?
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;
Another Example. How to create clock on forms using timer.
Use Following triggers to create yourself.
On When-New-Form-Instance
======================
Declare
timer1 timer;
Begin
--Create a timer to trigger it every 1 sec(1000msec)
timer1:=create_timer('timer1',1000,repeat);
END;
********************************************************************
On When-Timer-Expired
==================
:DISPLAY_ITEM4 := to_char(sysdate,'hh24:mi:ss');
Run-Time Screenshot:
1 comment:
it's a too much helpful information
Post a Comment