Start

Start has two basic syntaxes.

To

Use

Execute a pipeline object

Syntax 1 For executing pipeline objects

Activate a timing object

Syntax 2 For activating timing objects


Syntax 1 For executing pipeline objects

Description

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.

Applies to

Pipeline objects

Syntax

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

Returns

Integer. Returns 1 if it succeeds and a negative number if an error occurs. Error values are:

If any argument’s value is null, Start returns null.

Usage

A pipeline transfer involves several PowerBuilder objects. You need:

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:

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.

Examples

Example 1

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)

See also


Syntax 2 For activating timing objects

Description

Activates a timing object causing a Timer event to occur repeatedly at the specified interval.

Applies to

Timing objects

Syntax

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.

Returns

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.

NoteWhen 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.

NoteGarbage 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

Example 2

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 3

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:

Example 4

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

Example 5

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

Example 6

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

Example 7

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

Example 8

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

Example 9

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

Example 10

The Close event for the window unregisters the shared timing object:

SharedObjectUnregister("Timing")

Example 11

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

See also