Syntax 2 For activating timing objects
Description
Activates a timing object causing a Timer event to occur repeatedly
at the specified interval.
Controls
Timing objects
Syntax
|
1 |
<span>timingobject</span>.<span>Start</span> ( <span>interval </span> ) |
|
Argument |
Description |
|---|---|
|
timingobject |
The name of the timing object you want |
|
interval |
An expression of type double specifying |
Return Values
Integer. Returns 1 if it succeeds and
-1 if the timer is already running, the interval specified is invalid,
or there are no system timers available.
Usage
This syntax of the Start function is used
to activate a nonvisual timing object. Timing objects can be used
to trigger a Timer event that is not associated with a PowerBuilder
window, and they are therefore useful for distributed PowerBuilder
servers or shared objects that do not have a window for each client
connection.
A timing object is a standard class user object inherited
from the Timing system object. Once you have created a timing object
and coded its timer event, you can create any number of instances
of the object within the constraints of your operating system. An
operating system supports a fixed number of timers. Some of those
timers will already be in use by PowerBuilder and other applications
and by the operating system itself.
To activate an instance of the timing object, call the Start function,
specifying the interval that you want between
Timer events. The Timer event of that instance is triggered as soon
as possible after the specified interval, and will continue to be
triggered until you call the Stop function on
that instance of the timing object or the object is destroyed.
When the Timer event occurs
The interval specified for the Start function
is the minimum interval between Timer events. All other posted events
occur before the Timer event.
The resolution of the interval depends on your operating system.
You can determine what the timing interval is and whether
a timer is running by accessing the timing object’s Interval
and Running properties. These properties are read-only. You must
stop and restart a timer in order to change the value of the timing
interval.
Garbage collection
If a timing object is running, it is not subject to garbage
collection. Garbage collection can occur only if the timing object
is not running and there are no references to it.
Examples
Suppose you have a distributed application in which the local client
performs some processing, such as calculating the value of a stock portfolio,
based on values in a database. The client requests a user object
on a remote server to retrieve the data values from the database.
Create a standard class user object on the server called uo_timer,
inherited from the Timing system object, and code its Timer event
to refresh the data. Then the following code creates an instance, MyTimer,
of the timing object uo_timer. The Start function
activates the timer with an interval of 60 seconds so that the request
to the server is issued at 60-second intervals:
|
1 |
uo_timer MyTimer |
|
1 |
|
1 |
MyTimer = CREATE uo_timer |
|
1 |
MyTimer.<span>Start</span>(60) |
The following example uses a timing object as a shared object
in a window that has buttons for starting a timer, getting a hit
count, stopping the timer, and closing the window. Status is shown
in a single line edit called sle_state.
The timing object, uo_timing, is a
standard class user object inherited from the Timing system object.
It has one instance variable that holds the number of times a connection
is made:
|
1 |
long il_hits |
The timing object uo_timing has
three functions:
-
of_connect increments il_hits and
returns an integer (this example omits the connection code for simplicity):1il_hits++1// connection code omitted1RETURN 1 -
of_hitcount returns
the value of il_hits:1RETURN il_hits -
of_resetcounter resets
the value of the counter to 0:1il_hits = 0
The timer event in uo_timing calls
the of_connect function:
|
1 |
integer li_err |
|
1 |
|
1 |
li_err = This.of_connect() |
|
1 |
IF li_err <> 1 THEN |
|
1 |
MessageBox("Timer Error", "Connection failed ") |
|
1 |
END IF |
When the main window (w_timer)
opens, its Open event script registers the uo_timing user
object as a shared object:
|
1 |
ErrorReturn result |
|
1 |
string ls_result |
|
1 |
|
1 |
SharedObjectRegister("uo_timing","Timing") |
|
1 |
result = SharedObjectGet("Timing", iuo_timing) |
|
1 |
// convert enumerated type to string |
|
1 |
ls_result = of_converterror(result) |
|
1 |
|
1 |
IF result = Success! THEN |
|
1 |
sle_stat.text = "Object Registered" |
|
1 |
ELSE |
|
1 |
MessageBox("Failed", "SharedObjectGet failed, " & |
|
1 |
+ "Status code: "+ls_result) |
|
1 |
END IF |
The Start Timer button starts the timer with an interval
of five seconds:
|
1 |
double ld_interval |
|
1 |
integer li_err |
|
1 |
|
1 |
IF (isvalid(iuo_timing)) THEN |
|
1 |
li_err = iuo_timing.<span>Start</span>(5) |
|
1 |
ld_interval = iuo_timing.interval |
|
1 |
sle_2.text = "Timer started. Interval is " & <br> + string(ld_interval) + " seconds" |
|
1 |
// disable Start Timer button |
|
1 |
THIS.enabled = FALSE |
|
1 |
ELSE |
|
1 |
sle_2.text = "No timing object" |
|
1 |
END IF |
The Get Hits button calls the of_hitcount function
and writes the result in a single line edit:
|
1 |
long ll_hits |
|
1 |
|
1 |
IF (isvalid(iuo_timing)) THEN |
|
1 |
ll_hits = iuo_timing.of_hitcount() |
|
1 |
sle_hits.text = string(ll_hits) |
|
1 |
ELSE |
|
1 |
sle_hits.text = "" |
|
1 |
sle_stat.text = "Invalid timing object..." |
|
1 |
END IF |
The Stop Timer button stops the timer, reenables
the Start Timer button, and resets the hit counter:
|
1 |
integer li_err |
|
1 |
|
1 |
IF (isvalid(iuo_timing)) THEN |
|
1 |
li_err = iuo_timing.Stop() |
|
1 |
|
1 |
IF li_err = 1 THEN |
|
1 |
sle_stat.text = "Timer stopped" |
|
1 |
cb_start.enabled = TRUE |
|
1 |
iuo_timing.of_resetcounter() |
|
1 |
ELSE |
|
1 |
sle_stat.text = "Error - timer could " & <br>    not be stopped" |
|
1 |
END IF |
|
1 |
|
1 |
ELSE |
|
1 |
sle_stat.text = "Error - no timing object" |
|
1 |
END IF |
The Close button checks that the timer has been stopped
and closes the window if it has:
|
1 |
IF iuo_timing.running = TRUE THEN |
|
1 |
MessageBox("Error","Click the Stop Timer " & <br> + "button to clean up before closing") |
|
1 |
ELSE |
|
1 |
close(parent) |
|
1 |
END IF |
The Close event for the window unregisters the shared
timing object:
|
1 |
SharedObjectUnregister("Timing") |
The of_converterror window
function converts the ErrorReturn enumerated type to a string. It
takes an argument of type ErrorReturn:
|
1 |
string ls_result |
|
1 |
|
1 |
CHOOSE CASE a_error |
|
1 |
CASE Success! |
|
1 |
ls_result = "The function succeeded" |
|
1 |
CASE FeatureNotSupportedError! |
|
1 |
ls_result = "Not supported on this platform" |
|
1 |
CASE SharedObjectExistsError! |
|
1 |
ls_result = "Instance name already used" |
|
1 |
CASE MutexCreateError! |
|
1 |
ls_result = "Locking mechanism unobtainable" |
|
1 |
CASE SharedObjectCreateInstanceError! |
|
1 |
ls_result = "Object could not be created" |
|
1 |
CASE SharedObjectCreatePBSessionError! |
|
1 |
ls_result = "Could not create context session" |
|
1 |
CASE SharedObjectNotExistsError! |
|
1 |
ls_result = "Instance name not registered" |
|
1 |
CASE ELSE |
|
1 |
ls_result = "Unknown Error Code" |
|
1 |
END CHOOSE |
|
1 |
|
1 |
RETURN ls_result |