Welcome!

PowerBuilder Authors: Chris Pollach, Yeshim Deniz, Jayaram Krishnaswamy, Kevin Benedict, Avi Rosenthal

Related Topics: PowerBuilder

PowerBuilder: Article

PFC Quickstart

Provide more usability and utility to your applications Part 2

U_dw works in conjunction with w_master to handle update and retrieve processing. PFC Menus will call events on a u_dw-based DataWindow control through the message router. U_dw also has right-mouse button support for the m_dw RMB menu.

In many cases u_dw will function just like an ordinary DataWindow control. However, u_dw has a number of events and functions that you can use to control its behavior. Here are a few highlights:

  • pfc_populateDDDW: Add code to this event to populate a dropdown DataWindow. The DataWindow Child reference to the DDDW is passed as an argument to this event.
  • pfc_rowValidation: Add code to this event to perform validation on the data in a row.
  • pfc_updateprep: Add code that prepares for an update (for instance, to fill in values to a column).
  • of_GetParentWindow: This function returns a reference to the parent window.
  • of_messageBox: The of_messageBox functions displays a PFC message box.
  • of_reset: This function resets a single DataWindow or all DataWindows in a linkage chain.
In addition to these methods and functions, u_dw supports all of the functionality provided by PFC's DataWindow services.

Resize Service
Using the resize service is a relatively simple matter. Add code in the window's open event to instantiate the service and register the window's objects with the service. That's all there is to it in the most simple case. Here is an example of the code you'll need to add the resize service to a window and register a static text control:

of_setResize(TRUE)
// set to scale width 100%
// height 50%
this.inv_resize.of_Register &
(st_1, 0, 0, 100, 50)

This works in the most straightforward cases. If you open a window using something other than Original! for the size, the resize service will not function as you expect. The ratios will be relative to the opened size of the window, not the original size. To remedy this, you need to add some additional code:

this.inv_resize.of_setOrigSize(this.width, this.height)

Place this code immediately after the of_setResize call.

Linkage Service
The linkage service allows you to create a master-detail relationship between two DataWindow controls. Unlike other DataWindow services, you instantiate and configure the linkage service from the open event of the window, rather than the constructor event of the DataWindow. This is necessary because the code that you write to configure the linkage service depends on two DataWindow controls being fully created. Since you cannot guarantee the order in which PowerBuilder will create controls on a window, you must wait until the window's open event to ensure that all of the DataWindow controls exist. To set up a master-detail relationship between two DataWindows (dw_master and dw_detail, for instance) first call of_setLinkage to instantiate the linkage service. As previously stated, this code goes in the window open event:

dw_master.of_setLinkage(TRUE)
dw_detail.of_setLinkage(TRUE)

Note that you can also put the call to of_setLinkage in the constructor of each of the DataWindows. Next, establish the relationship by telling the detail DataWindow the identity of the master DataWindow:

dw_detail.inv_linkage.of_setMaster( dw_master )

Next, map columns on the master DataWindow to columns on the detail:

// of_Register( master_column, child_column )
dw_Detail.inv_linkage.of_Register &
( "cust_id", "customer_id" )
dw_Detail.inv_linkage.of_Register &
( "order_id", "order_id" )

You can also specify update direction. That is, do you want your DataWindows to update top-down (master first) or bottom-up (lowest-level detail first)? You can use any of five update styles:

  • TOPDOWN
  • BOTTOMUP
  • TOPDOWN_BOTTOMUP
  • BOTTOMUP_TOPDOWN
  • CUSTOM
The reason for these different styles is to allow you to manage any referential integrity issues that may arise. There are two "mixed" styles that you'll want to consider: TOPDOWN_BOTTOMUP and BOTTOMUP_TOPDOWN. These styles designate that the first style should be used for insert and update, while the second style should be used for delete. Of these two, the typical use would be TOPDOWN_BOTTOMUP, which updates and inserts using the top-down (master first) style and deletes using the bottom-up (detail first) style. This ensures that the master records exist before detail records are inserted into the database, and that detail records are deleted before their masters. The code to set the update style should follow the column registration:

dw_master.inv_linkage.of_SetUpdateStyle (dw_master.inv_linkage.TOPDOWN_BOTTOMUP)

You also need to let the master DataWindow's linkage service know what transaction object to use:

dw_Master.inv_linkage.of_SetTransObject( SQLCA )

Next specify the linkage style. The first linkage style is the Retrieve style. This causes PFC to retrieve the detail whenever a new master record is selected:

dw_detail.inv_linkage.of_SetStyle & (dw_detail.inv_linkage.RETRIEVE)

Other choices include:

  • FILTER: Changes the filter specification of the detail to show only records that link to the master.
  • SCROLL: For shared DataWindows, scrolls the detail to the same record as the master. In addition, you can specify a delete style. This allows you to match the way PFC deletes rows in the detail DataWindows with the way the tables' referential integrity is configured on the database. The function of_SetDeleteStyle determines how detail rows are deleted when master row is deleted. The delete styles are:
    -DEFAULT: No Deletes are processed in detail DataWindows(this matches PFC 5.0 behavior).
    -DELETE_ROWS: Child rows are deleted. Use this if your tables are not set up for cascading deletes.
    -DISCARD_ROWS: Child rows are discarded. Use this if your tables are set up for cascading deletes.
Retrieving and Updating
When you're using the linkage service, call the of_retrieve method on the master DataWindow. Pfc_u_dw contains code to call the of_retrieve method on the linkage service if the linkage service is enabled.

Updates to PFC Master-detail linkages are handled automatically by the LUW (logical unit of work) service. This service is invoked from the pfc_save event on w_master.

But Wait...There's More!
The linkage service is incredibly rich in functionality. There are methods and settings to handle nearly every conceivable relationship between a master and detail DataWindow. Study the documentation, the examples, and the PFC code to see how many ways there are for you to manipulate the linkage service. You'll find methods for:

  • Update on row change - automatically update a detail DataWindow when the master row changes.
  • Synchronize key columns when the keys in master rows change.
  • Obtain references for all detail DataWindows of a particular master.
  • Specify other objects to be updated when master row changes focus.
  • Designate a sound to be played when updates complete.
  • Remove a DataWindow from a linkage chain.

More Stories By Millard F. Brown

Millard F. Brown is vice president of Power3, LLC, a company providing consulting and training services for the enterprise. He has beend developing PowerBuilder applications since PowerBuilder 2 and is the co-author of two new PowerBuilder 9 books: PowerBuilder 9: Advanced Client/Server Development and PowerBuilder 9: Internet and Distributed Application Development.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.