In last month's column, I led you through a very forensic and dry discussion on how the update process is performed with PFC DataWindows. This process is complex and a bit daunting for the beginning PowerBuilder programmer. The purpose of that column was not to dissuade you from using the PFC DataWindow when writing applications that require you to update data, but to give you an understanding of what's happening behind the scenes. As a matter of fact, you can safely ignore most of the processing that was explained last month (I know, I know, now you tell me!). Think of my last column as a reference documenting the events of how the PFC DataWindow updates data. Please don't think that you need to memorize the whole process. Just refer to it now and again if you need to.

This month, I'll stray away from theory and show how you can make sense of this mess and actually use the PFC DataWindow. I'll focus on three areas: required column processing, data validation and database error processing. These three areas are the first things you should know about the PFC DataWindow - and they should get you a long way. All of these examples will use the PowerBuilder Demo database so you'll be able to run these examples for yourself.

The Application
The application I'll be using will be a simple one. It'll have one window that contains all the code to run the examples (see Figure 1). The window contains a PFC DataWindow (u_dw) and a two PFC command buttons (u_cb). The three user objects can be found in the PFC library pfemain.pbl. The DataWindow object contains the following columns from the customer's table in the demo database: Customer ID, Customer Name, Last Name, City, State and Zip Code.

The Code
The open event for the window will populate the transaction object and make the connection to the PowerBuilder Demo Database. The last portion of this event will retrieve data into the DataWindow. Remember, when setting the Transaction Object for a PFC DataWindow you should use the function of_SetTransObject rather than SetTransObject. Remember to set SQLCA to point to the object n_tr in the Application Object Properties. Listing 1 shows the code to perform these steps.

The code for the save command button is only one line, which will start the whole PFC update process I described last month. More specifically, the event will check all of the controls on the window to see if they need to be updated. This line of code is listed below:

Parent.Event pfc_save()

The code for the close command button will initiate the close sequence for the window. This sequence has hooks into the closequery event. What this means to you is if there have been changes to the DataWindow, the user will be prompted to make changes before the window is actually closed. The code for the close command button is listed below:

Parent.Event pfc_close()

Required Column Processing
The first step in understanding the PFC update process is learning how it handles required columns. To make a column required, a programmer must set its required flag from within the DataWindow painter. To do this, select the column that you want to make required and navigate to the edit tab on its properties. Simply click on the check box to make it required. In our example, the company name column is set to required (see Figure 2)

Making a column required does two things. First, if in the DataWindow a user doesn't supply a value for a required column and then tries to save it, he or she will get the message displayed in Figure 3. Second, if a required value is not entered, it's considered a validation error. In the case of any validation error, the user will see the message box illustrated in Figure 4. This message box will be displayed if any of the columns don't pass validation or if the user is attempting to close the window without entering a required value within the DataWindow. Data Validation
Let me take the previous example one step further. Instead of making the company name column required, I'll add the code to validate it myself. Why? Although the required column processing works okay, I may want to display a user-friendlier message. Instead of a user getting a generic message that a required column hasn't been entered, I want to tell the user which column he or she forgot to supply a value for. To do this, I added the following code in the window pfc_preupdate event. If the user doesn't enter a value for the company name, the PFC save process will be halted and the user will be directed to the row that contains the empty column. This code is shown in Listing 2.

Database Error Processing
If an error occurs when the DataWindow is saved, the DataWindow dbupdate error is triggered. In a non-PFC application, this event is blank and it's up to the programmer to put error-processing code in this event. However, the PFC does put code in this event. It doesn't do much; it'll show the user a response window with a generic database error message (see Figure 5). In our example, if a user enters a customer ID that already exists - a primary key violation in the database - they'll receive the response window illustrated in Figure 6.

As you can see, if there's a primary key violation when a save is attempted, the database returns a code of - 198. Would you like your users to see this message? I wouldn't. We can put our own code in the DataWindow dberror event. This code will check for the error code and display a more user-friendly message (see Figure 7). Override the dberror event for the DataWindow and add the following code:

If sqldbcode = -198 then
messagebox("Error","ID Already Exists, Please Enter Another.")
dw_1.SetFocus()
dw_1.SetRow(row)
dw_1.SetColumn("customer_id")
Return 1
End If

In Closing
I hope the three techniques we discussed this month will help when you're working with PFC DataWindows. Next month, I'll cover the process of building an executable file and PowerBuilder deployment issues.

• Figure 1
• Figure 2
• Figure 3
• Figure 4
• Figure 5
• Figure 6
• Figure 7