Advanced PowerBuilder

DataWindow Buffers

Till now we said that, PowerBuilder retrieves data according to the data source definition and displays the data according to the DataWindow format. That is still right, but, how does PowerBuilder maintain them internally. Knowing DataWindow internals gives you a better understanding and hence, you can code more efficiently.

When we call the Retrieve() function, PowerBuilder retrieves data from the data source and stores it in the buffer in memory. PowerBuilder then reads the data from buffer and formats & displays it in the DataWindow control.

Internally, PowerBuilder maintains one edit control and four buffers for each DataWindow control. The buffers are:

	Original
	Primary
	Deleted
	Filtered

Let's learn about buffers first. When data is retrieved from the database by using Retrieve() function, it is retrieved into the Primary buffer and it is the contents of this buffer that are displayed in the DataWindow:

PowerBuilder always displays the data in DataWindow control from the Primary Buffer. Data from other buffers are not visible to the user. Of course, it is, for the programmer through code.

Adding Rows

As you learned previously, rows can be added to the DataWindow by using the InsertRow() function ( there are other ways also, we'll tell you later ). InsertRow(), ImportFile(),ImportString(),ImportClipboard() functions adds row(s) to the Primary Buffer; but it has no effect on other buffers ( See the following figure. ).

Deleting Rows

When you delete a row with the DeleteRow() function, rows are transferred from Primary buffer to Deleted buffer. For example, If you delete Product No: 5, buffers would look like this:

Filtering Rows

When rows are filtered using the SetFilter() function, all rows that don't match the filtered condition are moved to the Filtered buffer. If we filter on the criteria that the product_no must be greater than 3, the buffers would look like this:

Modifying Rows

If you modify a row in the DataWindow, the row in the Primary buffer is modified and the original value is copied into the Original buffer. Suppose we change the description of product_no 4 from "Desk" to a "Table lamp", the buffers would look like this:

Note that this is the case only for rows which were originally retrieved from the database. If we modified product_no 6, nothing would be copied to the Original buffer, because this row was added to the results set after the data was retrieved from the database.

 The changes made to the data will not be reflected in the database until the Update() function is called. Whenever you call the Update() function, PowerBuilder creates INSERT, DELETE, UPDATE statements and sends them to the database for execution.

PowerBuilder creates the database statements ( such as INSERT, DELETE, UPDATE ) depending upon the row status. Row Status? A New term. Let's see what it is.

Each row and column in the DataWindow have certain statuses. When PowerBuilder retrieves data from the database, all the rows are in the "NotModified!" status. Please note that, the status is an enumerated datatype, i.e., ends with an exclamation mark. If you modify the value of a column in a row, PowerBuilder changes the row status to "Modified!" status. Now, say, you insert a record in the DataWindow. As you know, a freshly inserted row through InsertRow() has no data. In that case, PowerBuilder assigns, "New!" status to that row. When you put data in any of the columns in the newly added row, PowerBuilder changes the row status to "NewModified!".

We said that, if you change a row, PowerBuilder copies the original value to Original buffer from the Primary buffer. Note that, PowerBuilder copies only when you modify the row for the first time, and not every time. For example, if you have a DataWindow defined on "product_master" , as shown below. Say, you change the "product_description" column. PowerBuilder copies the row from Primary to Original because, you changed it for the first time; it doesn't matter which column you change . Now, say, you change the "product_reorder_level". PowerBuilder will not copy this time, because it already copied the values.

Now, let's see how PowerBuilder knows which statement to create. What happens is that, PowerBuilder looks into each buffer one at a time.

From the above table, you can observe that, PowerBuilder doesn't take any action if it is a new blank row with no data. But, PowerBuilder generates an INSERT statement, if the record is new and has data in at least one field.

Edit Control Buffer in the DataWindow Control

Each DataWindow control has one Edit Control. It contains the current column's data. For example, the cursor is in the "product_no" column, then Edit Control contains the value of "product_no" for that row. When you press the tab key and move to the "product_description" column, PowerBuilder copies the value of "product_description" column for that row into the Edit Control.

For example, say, description for Product No: 1 is "Hard Disk". When product no:1 is retrieved from the database, both primary buffer and edit control ( assuming that the cursor is in the "product_description" column ) have the same value. You also see the same data on the screen.

Now, If you change the content of "product_description", to say, "Printer", you see "Printer" on the screen and the value in the Edit Control would be "Printer". That means, the changed data is automatically reflected in the Edit Control. As long as the cursor remains in that column, the data you see on the screen and the content of the Edit Control are same; but, the value in the primary buffer has the old data, "Hard Disk".

When you press the tab key, PowerBuilder validates the data in Edit Control and copies it to the Primary buffer, if the data passes the DataWindow validation. As explained in the buffers section, even before PowerBuilder copies the data from the Edit Control to the primary buffer, it copies the row from the primary buffer to the Original buffer, if it is the first value to be changed for that row.

Home	Previous Lesson: Advanced DataWindows - I Next Lesson: DataWindow - Data Validation