DataWindows

The development of the Web DataWindow is a great technological advancement. It's extremely helpful in moving an existing PowerBuilder application to the Web. Most PowerBuilder applications contain many DataWindows for the various screens and reports. The ability to quickly render these controls as HTML in a browser is a huge timesaver.

The update process of the Web DataWindow is one of the most frequently posted topics on the Sybase forums. There are many questions about which attributes to set in order to successfully apply an update. The specific coding required to take data that was entered into the browser and update a database on the server is another hot topic. The recent volume increase in Web DataWindow questions is indicative of its increased use. This article will discuss, step by step, how the update process works, as well as the necessary settings and code required for Web DataWindow updates.

Retrieval Process Review
The Web DataWindow is simply a DataStore that exists within an application server. In my opinion, this component will execute best in Jaguar because of Jaguar's built-in PowerBuilder virtual machine and DataStore features. Other application servers, such as Microsoft MTS, know nothing about DataStore. For a PowerBuilder component to work in MTS, that component must be created as a COM object, seriously degrading the functionality and performance of Web DataWindows.

The default Web DataWindow logic resides within a PowerBuilder component called HTMLGenerator. This component has functions that access and change attributes and data of a DataStore. The most basic scripting to create a Web DataWindow performs the following basic functions:

• Create an "instance" of the HTMLGenerator component
• Set the PBL and dataobject
• Set the transaction object information
• Generate the HTML

A few lines of code will display a DataWindow object in a browser as HTML and JavaScript. The Power-Builder runtime DLLs aren't needed on the client machines.

This greatly simplifies the distribution of PowerBuilder applications. Anyone who has had to install ODBC on several different machines is familiar with the problems inherent in such multi-platform deployments.

Update Process
Successful use of the update process requires an understanding of what happens in a browser when the update button is pressed. The HTML that is generated by PowerBuilder creates two hidden fields: one for action and one for the context of that action. As data is entered and the Update button is pressed, an action field specifying update is created. The other hidden field, context of the action, indicates which data was entered, changed, or deleted.

<FORM NAME="webDW_submitForm" METHOD="POST" ACTION="expense_grid.htm">
<INPUT TYPE="hidden" NAME="webDW_action" VALUE="none">
<INPUT TYPE="hidden" NAME="webDW_context" VALUE="">
</FORM>

The clicking of the button causes the page to be reloaded as the server-side script is executed. This is the same script described in the previous section, but with additional code to check if the user took an action and what the context of that action was. The script will reload the DataStore and then apply the action and context from the browser to the DataStore. This is accomplished by calling a method on the HTMLGenerator component named SetAction, which uses action and context as arguments. This is a PowerBuilder component, executing an associated PowerScript function named SetHTMLAction. This "magic" function takes the data entered into a browser and applies it to a DataStore. The applicable line of HTMLGenerator source code is shown below.

li_result =
ids_datastore.SetHTMLAction
(as_action, as_context)

Yes, It Reloads the Data
You may be asking yourself if I just said that the data is reloaded when an update occurs. That's exactly what happens! The Web DataWindow component out-of-the-box isn't bound to a particular client. The instance is released after the HTML is generated in the Generate method. There are ways to bind clients to instances of components, but that's outside the scope of this article.

The Code
Now that we have reviewed the process, we can examine the underlying code. The script is named pbdj_update.html and is shown in Listing 1. The first part of the script is the server-side tag, <!--SCRIPT, indicating that this code will execute on the application server. All the code from the script tag to the end tag, -->, will be executed on the application server. Next is a function called GetParam, which loops thru the page and finds the passed argument. This parameter is then used to identify the action and context of the action.

The instance of the Jaguar component is created with the java. Create-Component method call. Once the reference to the component is made, the methods on the component are called to create the Web DataWindow. The PBL and dataobject are set with the SetDWObject method and the database transaction information is set with the SetTrans method call. The DataStore is loaded by the Retrieve method, as the name implies.

The next step is to determine if the user took any action. This is accomplished by calling the GetParam function that was mentioned earlier. The name of the action is determined by the name provided as the client-side reference to the DataWindow with the SetHTMLObjectName method call. The script names the DataWindow as dwClient. This name is case sensitive. The default name is htmlDw if the SetHTMLObjectName method isn't called. The action and context parameters are named as the DataWindow client references, suffixed by "_action" and "_context", respectively. The line of code that checks for action calls the GetParam function and passes "dwClient_action" as the argument. If an action is identified, the context is obtained and the SetAction method is called, passing the action and context as arguments. The SetAction method returns a "1" if successful and a negative number if unsuccessful.

An example of an update action and associated context is shown if Figure 1. The action is "Update", since the Department Name field was changed to "This row was changed". The context indicates that, for the DataWindow referenced by dwClient, a modify occurred (ModifiedRow). The primary key field is part of the context statement and indicates which record (in this case, "600") to update in the DataStore. The second column was changed to the value of 'This row was changed' as indicated with ((2 0 'This row was changed')). Finally, it was the fifth row that was changed as indicated with (row 5). Figuring out how the context works isn't a difficult task. However, be warned that the context shouldn't be changed programmatically. Sybase won't support any problems caused by changing the context. This is explicitly stated in the disclaimer that is generated at the beginning of every Web DataWindow.

The order of the method calls in the script is crucial. The DataStore must be retrieved before the action is applied or the SetAction method call will fail with a -1 code. This makes sense since the data from the browser must be "synched up" with the DataStore. If the DataStore is empty then there is no data to "synch up."

Self Link
The Self Link parameter must be set in order for updates to work. Its absence will result in an error, as shown in Figure 2. This parameter is used to identify the page that should be reloaded when an action is taken. It also indicates any parameters that were passed to the page and must be preserved after the page is reloaded. The SetSelfLink method call requires two arguments: the page to reload and any parameters for that page. The attribute document.page can be used to reference the current page. This will allow you to avoid hard-coding the page name into a script. The page in this example has no parameters so an empty string is passed to the method. However, if parameters do exist, the syntax of the arguments must be in exact order to succeed. The format of the syntax is parameter_name='expression'. Multiple parameters are separated by the pipe symbol (|).

Summary
The update process of the Web DataWindow is very simple. However, it's frequently misunderstood. This article reviewed the process step by step and provided an example that can be used as a template for your Web DataWindows. This template can be easily modified to handle all your Web DataWindows.

Add Your Feedback

In order to post a comment you need to be registered and logged in.

Register | Log in

Please wait while we process your request...