Performing some initial housekeeping

Now that you have the basic objects you need, you are ready to start writing code to make your pipeline work in the application. To begin, you must take care of some setup chores that will prepare the application to handle pipeline execution.

To get the application ready for pipeline execution:

  1. Connect to the source and destination databases for the pipeline.

    To do this, write the usual connection code in an appropriate script. Just make sure you use one Transaction object when connecting to the source database and a different Transaction object when connecting to the destination database (even if it is the same database).

    For details on connecting to a database, see Using Transaction Objects.

  2. Create an instance of your supporting user object (so that the application can use its properties, events, and functions).

    To do this, first declare a variable whose type is that user object. Then, in an appropriate script, code the CREATE statement to create an instance of the user object and assign it to that variable.

  3. Specify the particular Pipeline object you want to use.

    To do this, code an Assignment statement in an appropriate script; assign a string containing the name of the desired Pipeline object to the DataObject property of your user-object instance.

For more information on coding the CREATE and Assignment statements, see the section called “CREATE” in PowerScript Reference and the section called “Assignment” in PowerScript Reference.

Example

The following sample code takes care of these pipeline setup chores in the order entry application.

Connecting to the source and destination database

In this case, the company's sales database (ABNCSALE.DB) is used as both the source and the destination database. To establish the necessary connections to the sales database, write code in a user event named uevent_pipe_setup (which is posted from the Open event of the w_sales_extract window).

The following code establishes the source database connection:

// Create a new instance of the Transaction object
// and store it in itrans_source (a variable
// declared earlier of type transaction).
itrans_source = CREATE transaction

// Next, assign values to the properties of the
// itrans_source Transaction object.
...

// Now connect to the source database.
CONNECT USING itrans_source;

The following code establishes the destination database connection:

// Create a new instance of the Transaction object
// and store it in itrans_destination (a variable
// declared earlier of type transaction).
 
itrans_destination = CREATE transaction
 
// Next, assign values to the properties of the
// itrans_destination Transaction object.
...
// Now connect to the destination database.
 
CONNECT USING itrans_destination;

Setting USERID for native drivers

When you execute a pipeline in the Pipeline painter, if you are using a native driver, PowerBuilder automatically qualifies table names with the owner of the table. When you execute a pipeline in an application, if you are using a native driver, you must set the USERID property in the Transaction object so that the table name is properly qualified.

Failing to set the USERID property in the Transaction object for the destination database causes pipeline execution errors. If the source database uses a native driver, extended attributes are not piped if USERID is not set.

Creating an instance of the user object

Earlier you learned how to develop a supporting user object named u_sales_pipe_logistics. To use u_sales_pipe_logistics in the application, first declare a variable of its type:

// This is an instance variable for the
// w_sales_extract window.
 
u_sales_pipe_logistics iuo_pipe_logistics

Then write code in the uevent_pipe_setup user event to create an instance of u_sales_pipe_logistics and store this instance in the variable iuo_pipe_logistics:

iuo_pipe_logistics = CREATE u_sales_pipe_logistics

Specifying the Pipeline object to use

The application uses one of two different Pipeline objects, depending on the kind of piping operation the user wants to perform:

  • pipe_sales_extract1 (which you saw in detail earlier) creates a new Quarterly_extract table (and assumes that this table does not currently exist)

  • pipe_sales_extract2 inserts rows into the Quarterly_extract table (and assumes that this table does currently exist)

To choose a Pipeline object and prepare to use it, write the following code in the Clicked event of the cb_write CommandButton (which users click when they want to start piping):

// Look at which radio button is checked in the
// w_sales_extract window. Then assign the matching
// Pipeline object to iuo_pipe_logistics.
 
IF rb_create.checked = true THEN
 iuo_pipe_logistics.dataobject = "pipe_sales_extract1"
ELSE
 iuo_pipe_logistics.dataobject = "pipe_sales_extract2"
END IF

This code appears at the beginning of the script, before the code that starts the chosen pipeline.

Deploying Pipeline objects for an application

Because an application must always reference its Pipeline objects dynamically at runtime (through string variables), you must package these objects in one or more dynamic libraries when deploying the application. You cannot include Pipeline objects in an executable (EXE) file.

For more information on deployment, see Part 9, "Deployment Techniques".