Building a window

One other object you need when piping data in your application is a window. You 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 the pipeline’s execution
Displaying and repairing any 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 cannot pipe to the destination table for some reason). You do not have to associate a DataWindow object with this DataWindow control—the pipeline provides one of its own at runtime.

To learn how to work with this DataWindow control in your application, see “Starting the pipeline” and “Handling row errors”.

Optional features for your window

Other than including the required DataWindow control, you can design the window as you like. You will 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 to display the contents of the source and/or destination tables

If you need assistance with building a window, see the PowerBuilder Users Guide.

Example

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

The sample Write Extract screen has three horizontal areas, labeled, from top to bottom, Operation, Status, and Errors. In the Operation area are two radio buttons labeled Create Quarterly Extract Table and Add to Quarterly Extract Table, and two command buttons labeled Write and Stop. In the Status area are text boxes that display status for database connections and rows read, written, and in error, and a Data Window for displaying the contents of the extract table. In the error section is an area where the PowerBuilder pipeline-error Data Window can be displayed, and the following command buttons: Apply Fixes, Forgo Fixes, Drop Table, and Close.

Several of the controls in this window are used to implement particular pipeline-related capabilities. Table 17-2 provides more information about them.

**Table 17-2: Window controls to implement pipeline capabilities**
Control type	Control name	Purpose
RadioButton	rb_create	Selects pipe_sales_extract1 as the Pipeline object to execute
RadioButton	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)
DataWindow	dw_pipe_errors	(Required) Used by the pipeline itself to automatically display the PowerBuilder pipeline-error DataWindow (which lists rows that cannot 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 error)