Building the objects you need – PB Docs 70

Building the objects you need

To implement data piping in an application, you’ll
need to build a few different objects:

  • A Pipeline object
  • A supporting user object
  • A window

Building a Pipeline object

You must build a Pipeline object to specify the data definition
and access aspects of the pipeline that you want your application
to execute. Use the Data Pipeline painter in PowerBuilder to create
this object and define the characteristics you want it to have.

Characteristics to define

Among the characteristics you can define in the Data Pipeline
painter are:

  • The source

    to access and the data to retrieve from them (you
    can also access database stored procedures as the data source)
  • The destination table
    to which
    you want that data piped
  • The piping operation
    to perform
    (create, replace, refresh, append, or update)
  • The frequency of commits
    the piping operation (after every n
    rows are
    piped, or after all rows are piped, or not at all–if you
    plan to code your own commit logic)
  • The number of errors
    to allow
    before the piping operation is terminated
  • Whether or not to pipe extended attributes
    the destination database (from the PowerBuilder repository in the
    source database)

For full details on using the Data Pipeline
painter to build your Pipeline object, see the PowerBuilder User’s



Here’s an example of how you would the Data Pipeline
painter to define a Pipeline object named pipe_sales_extract1
(one of two Pipeline objects employed by the w_sales_extract
window in a sample order entry application).

The source data to pipe This Pipeline object joins two tables (Sales_rep and
Sales_summary) from the company’s sales database
to provide the source data to be piped. It retrieves just the rows
from a particular quarter of the year (which the application must
specify by supplying a value for the retrieval argument named quarter


Notice that this Pipeline object also indicates specific columns
to be piped from each source table (srep_id, srep_lname,
and srep_fname from the Sales_rep table, as well
as ssum_quarter and ssum_rep_team from
the Sales_summary table). In addition, it defines a computed
column to be calculated and piped. This computed column subtracts
the ssum_rep_quota column of the Sales_summary
table from the ssum_rep_actual column:


How to pipe the data The details of how pipe_sales_extract1 is
to pipe its source data are specified here:


Notice that this Pipeline object is defined to create a new
destination table named Quarterly_extract. A little later
you’ll learn how the application specifies the destination
database in which to put this table (as well as how it specifies
the source database in which to look for the source tables).

Also notice that:

  • A commit
    be performed only after all appropriate rows have been piped (which
    means that if the pipeline’s execution is terminated early,
    all changes to the Quarterly_extract table will be rolled
  • No error limit
    is to be imposed
    by the application, so any number of rows can be in error without
    causing the pipeline’s execution to terminate early
  • No extended attributes
    to be piped to the destination database
  • The primary key
    of the Quarterly_extract
    table is to consist of the srep_id column and the ssum_quarter
  • The computed column
    that the
    application is to create in the Quarterly_extract table
    is to be named computed_net

Building a supporting user object

far you’ve seen how your Pipeline object defines the details
of the data and access for a pipeline. But a Pipeline object doesn’t
include the logistical supports–properties, events, and
functions–that an application requires to handle pipeline
execution and control.

About the Pipeline system object

To provide these logistical supports, you must build an appropriate
user object inherited from the PowerBuilder Pipeline system
. This system object contains various properties,
events, and functions that enable your application to manage a Pipeline
object at execution time. These include:

Properties Events Functions
DataObjectRowsReadRowsWrittenRowsInErrorSyntax PipeStartPipeMeterPipeEnd StartRepairCancel

A little later in this chapter you’ll learn how to
use most of these properties, events, and functions in your application.

proc.gif To build the supporting user object for a pipeline:

  1. Select Standard Class from the Object tab
    of the New dialog box.

    The Select Standard Class Type dialog box displays, prompting
    you to specify the name of the PowerBuilder system object (class)
    from which you want to inherit your new user object:


  2. Select pipeline and click OK.

  3. Make any changes you want to the user object (although
    none are required). This might involve coding events, functions,
    or variables for use in your application.

    To learn about one particularly useful specialization
    you can make to your user object, see “Monitoring pipeline

    note.gif Planning ahead for reuse As you work on your user object, keep in mind that it can
    be reused in the future to support any other pipelines you want
    to execute–it isn’t automatically tied in any
    way to a particular Pipeline object you’ve built in the
    Data Pipeline painter.

    To take advantage of this flexibility, make sure that the
    events, functions, and variables you code in the user object are
    generic enough to accommodate any Pipeline object.

  4. Save the user object.

For more information on working with the User
Object painter, see the PowerBuilder User’s Guide

Building a window

One other object you need when piping data in your application
is a window. You’ll use this window to provide a user interface
to the pipeline, enabling people to interact with it in one or more
ways. These include:

  • Starting
    pipeline’s execution
  • Displaying and repairing
    errors that occur
  • Canceling
    the pipeline’s
    execution if necessary

Required features for your window

When you build your window, you must include a DataWindow
control that the pipeline itself can use to display error rows (that
is, rows it can’t pipe to the destination table for some
reason). You don’t have to associate a DataWindow object
with this DataWindow control–the pipeline will provide
one of its own at execution time.

To learn about how you’ll work with
this DataWindow control in your application, see “Starting the pipeline “ and “Handling row errors “.

Optional features for your window

Other than that, you can design the window as you like. You’ll
typically want to include various other controls, such as:

  • CommandButton
    or PictureButton controls

    to let the user initiate actions (such
    as starting, repairing, or canceling the pipeline)
  • StaticText controls
    to display
    pipeline status information
  • Additional DataWindow controls
    display the contents of the source and/or destination tables

If you need assistance with building a window,
see the PowerBuilder User’s Guide


The following window handles the user-interface aspect of
the data piping in the order entry application. This window is named


Several of the controls in this window are used to implement
particular pipeline-related capabilities. Here’s more information
about them:

Control type Control name Purpose
RadioButton rb_create Selects pipe_sales_extract1
as the Pipeline object to execute
rb_insert Selects pipe_sales_extract2
as the Pipeline object to execute
CommandButton cb_write Starts execution of the selected pipeline
cb_stop Cancels pipeline execution or applying
of row repairs
cb_applyfixes Applies row repairs made by the user
(in the dw_pipe_errors DataWindow control) to
the destination table
cb_forgofixes Clears all error rows from the dw_pipe_errors
DataWindow control (for use when the user decides not to make repairs)
DataWindow dw_review_extract Displays the current contents of the destination
table (Quarterly_extract)
dw_pipe_errors (Required
) Used
by the pipeline itself to automatically display the PowerBuilder pipeline-error
DataWindow (which lists rows that can’t be piped due to
some error)
StaticText st_status_read Displays the count of rows that the pipeline
reads from the source tables
st_status_written Displays the count of rows that the pipeline
writes to the destination table or places in dw_pipe_errors
st_status_error Displays the count of rows that the pipeline
places in dw_pipe_errors (because they are in

Document get from Powerbuilder help
Thank you for watching.
Was this article helpful?
Notify of
Inline Feedbacks
View all comments
Would love your thoughts, please comment.x