Start has two basic syntaxes.
To |
Use |
|---|---|
Execute a pipeline object |
|
Activate a timing object |
Executes a pipeline object, which transfers data from the source to the destination as specified by the SQL query in the pipeline object. This pipeline object is a property of a user object inherited from the pipeline system object.
Pipeline objects
pipelineobject.Start ( sourcetrans, destinationtrans, errorobject
{, arg1, arg2,..., argn } )
Argument |
Description |
|---|---|
pipelineobject |
The name of a pipeline user object that contains the pipeline object to be executed |
sourcetrans |
The name of a transaction object with which to connect to the source database |
destinationtrans |
The name of a transaction object with which to connect to the target database |
errorobject |
The name of a DataWindow control or Data Store in which to store the pipeline error DataWindow |
argn (optional) |
One or more retrieval arguments as specified for the pipeline object in the Data Pipeline painter |
Integer. Returns 1 if it succeeds and a negative number if an error occurs. Error values are:
-1 Pipe open failed
-2 Too many columns
-3 Table already exists
-4 Table does not exist
-5 Missing connection
-6 Wrong arguments
-7 Column mismatch
-8 Fatal SQL error in source
-9 Fatal SQL error in destination
-10 Maximum number of errors exceeded
-12 Bad table syntax
-13 Key required but not supplied
-15 Pipe already in progress
-16 Error in source database
-17 Error in destination database
-18 Destination database is read-only
If any argument’s value is null, Start returns null.
A pipeline transfer involves several PowerBuilder objects. You need:
A pipeline object, which you define in the Data Pipeline painter. It contains the SQL statements that specify what data is transferred and how that data is mapped from the tables in the source database to those in the target database.
A user object inherited from the pipeline system object. It inherits properties that let you check the progress of the pipeline transfer. In the painter, you define instance variables and write scripts for pipeline events.
A window that contains a DataWindow control or a Data Store for the pipeline-error DataWindow. Do not put a DataWindow object in the DataWindow control. The control displays PowerBuilder’s pipeline-error DataWindow object if errors occur when the pipeline executes.
The window can also include buttons, menus, or some other means to execute the pipeline, repair errors, and cancel the execution. The scripts for these actions use the functions Start, Repair, and Cancel.
Before the application executes the pipeline, it needs to connect to the source and destination databases, create an instance of the user object, and assign the pipeline object to the user object’s DataObject property. Then it can call Start to execute the pipeline. This code may be in one or several scripts.
When you execute the pipeline, the piped data is committed according to the settings you make in the Data Pipeline painter. You can specify that:
The data is committed when the pipeline finishes. If the maximum error limit is exceeded, all data is rolled back.
Data is committed at regular intervals, after a specified number of rows have been transferred. When the maximum error limit is exceeded, all rows already transferred are committed.
For information about specifying the pipeline object in the Data Pipeline painter and how the settings affect committing, see the PowerBuilder Users Guide. For more information on using a pipeline in an application, see Application Techniques.
When you dynamically assign the pipeline object to the user object’s DataObject property, you must remember to include the pipeline object in a dynamic library when you build your application’s executable.
The following script creates an instance of the pipeline user object, assigns a pipeline object to the pipeline user object’s DataObject property, and executes the pipeline. I_src and i_dst are transaction objects that have been previously declared and created. Another script has established the database connections.
U_pipe is the user object inherited from the pipeline system object. I_upipe is an instance variable of type u_pipe. P_pipe is a pipeline object created in the Data Pipeline painter:
i_upipe = CREATE u_pipe
i_upipe.DataObject = "p_pipe"
i_upipe.Start(i_src, i_dst, dw_1)
Activates a timing object causing a Timer event to occur repeatedly at the specified interval.
Timing objects
timingobject.Start ( interval )
Argument |
Description |
|---|---|
timingobject |
The name of the timing object you want to activate. |
interval |
An expression of type double specifying the number of seconds that you want between timer events. The interval can be a whole number or fraction greater than 0 and less than or equal to 4,294,967 seconds. An interval of 0 is invalid. |
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.
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.
Example 1 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:
uo_timer MyTimer
MyTimer = CREATE uo_timer
MyTimer.Start(60)
Example 2 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:
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):
il_hits++
// connection code omitted
RETURN 1
of_hitcount returns the value of il_hits:
RETURN il_hits
of_resetcounter resets the value of the counter to 0:
il_hits = 0
The timer event in uo_timing calls the of_connect function:
integer li_err
li_err = This.of_connect()
IF li_err <> 1 THEN
MessageBox("Timer Error", "Connection failed ")
END IF
When the main window (w_timer) opens, its Open event script registers the uo_timing user object as a shared object:
ErrorReturn result
string ls_result
SharedObjectRegister("uo_timing","Timing")
result = SharedObjectGet("Timing", iuo_timing)
// convert enumerated type to string
ls_result = of_converterror(result)
IF result = Success! THEN
sle_stat.text = "Object Registered"
ELSE
MessageBox("Failed", "SharedObjectGet failed, " &
+ "Status code: "+ls_result)
END IF
The Start Timer button starts the timer with an interval of five seconds:
double ld_interval
integer li_err
IF (isvalid(iuo_timing)) THEN
li_err = iuo_timing.Start(5)
ld_interval = iuo_timing.interval
sle_2.text = "Timer started. Interval is " & + string(ld_interval) + " seconds"
// disable Start Timer button
THIS.enabled = FALSE
ELSE
sle_2.text = "No timing object"
END IF
The Get Hits button calls the of_hitcount function and writes the result in a single line edit:
long ll_hits
IF (isvalid(iuo_timing)) THEN
ll_hits = iuo_timing.of_hitcount()
sle_hits.text = string(ll_hits)
ELSE
sle_hits.text = ""
sle_stat.text = "Invalid timing object..."
END IF
The Stop Timer button stops the timer, reenables the Start Timer button, and resets the hit counter:
integer li_err
IF (isvalid(iuo_timing)) THEN
li_err = iuo_timing.Stop()
IF li_err = 1 THEN
sle_stat.text = "Timer stopped"
cb_start.enabled = TRUE
iuo_timing.of_resetcounter()
ELSE
sle_stat.text = "Error - timer could " & not be stopped"
END IF
ELSE
sle_stat.text = "Error - no timing object"
END IF
The Close button checks that the timer has been stopped and closes the window if it has:
IF iuo_timing.running = TRUE THEN
MessageBox("Error","Click the Stop Timer " &
+ "button to clean up before closing")
ELSE
close(parent)
END IF
The Close event for the window unregisters the shared timing object:
SharedObjectUnregister("Timing")
The of_converterror window function converts the ErrorReturn enumerated type to a string. It takes an argument of type ErrorReturn:
string ls_result
CHOOSE CASE a_error
CASE Success!
ls_result = "The function succeeded"
CASE FeatureNotSupportedError!
ls_result = "Not supported on this platform"
CASE SharedObjectExistsError!
ls_result = "Instance name already used"
CASE MutexCreateError!
ls_result = "Locking mechanism unobtainable"
CASE SharedObjectCreateInstanceError!
ls_result = "Object could not be created"
CASE SharedObjectCreatePBSessionError!
ls_result = "Could not create context session"
CASE SharedObjectNotExistsError!
ls_result = "Instance name not registered"
CASE ELSE
ls_result = "Unknown Error Code"
END CHOOSE
RETURN ls_result
