Home

	Expand Search

DataWindow Programmer's Guide

Chapter 7: Server-Side Processing for the Web DataWindow

Instantiating and configuring the server component

Instantiating and configuring the server component

If you are not using the Web DataWindow DTC or the Web Target object model, you can write code to create an instance of the Web DataWindow server component, and you can call its methods to create a Web DataWindow application.

For information on the types of Web DataWindow server components, see "The Web DataWindow server component and client control". For information on the Web Target object model and its 4GL extensions, see Working with Web and JSP Targets.

Two sets of methods

There are two sets of methods available on the generic Web DataWindow server component: methods that are available for other DataWindow controls, and methods used to configure the component and generate HTML.

DataWindow control methods

DataWindow control methods supported by the generic server component include sorting, filtering, validation, and get and set methods. When you call one of these methods on the server component, the server reloads the page in the browser.

Methods with more than one syntax have a different form for each syntax to overcome restrictions on the use of overloading. For example, the ClearValues method takes a string as an argument and the ClearValuesByColNum method takes a number.

For a complete list of supported DataWindow control methods, see the DataWindow Reference or the online Help.

Examining server component methods

You can view the generic EAServer component methods on the Components page of the System Tree or in Jaguar Manager. You can examine the methods in the COM server component in an OLE viewer (look for PowerBuilder.HTMLDataWindow in the Programmable Objects list on the OLE tab of the PowerBuilder Browser, or in the Automation Objects list in the Microsoft OLE/COM Object Viewer).

Configuration and generation methods

Other methods are available to set up the component, retrieve data, establish persistent values needed by your Web page, and generate HTML.

If you use a custom server component, there are additional configuration tasks. For more information, see "Using a custom server component".

Mixed case method names

The methods of the generic EAServer server component use mixed case names and all the examples in this section use mixed case. If you write your own server component, the methods of the component you generate are all lowercase. (You can use the sample PBDWRMT.PBL as a starting point if you want the methods described here.) The generic COM component method names are also all lowercase.

Coding steps

In your server-side script, you will code these tasks:

1. Instantiate the component.

2. Load the DataWindow object.

3. Control what HTML is generated (for example, by specifying what functionality to include and what browser to target).

4. Specify the database connection and retrieve data.

5. Pass page-specific data to the reloaded page.

6. Pass user action information to the server component.

7. Insert the generated HTML in the page template.

Sample code for each of these tasks follows. Most of the code examples show the DynaScript code you would use to instantiate and configure the EAServer component. Some ASP examples are provided, but the code in other ASP server-side scripts would be similar to the DynaScript examples shown here.

For detailed information about the methods used in the examples, see the DataWindow Reference or the online Help.

Instantiating the component

CreateComponent

In PowerDynamo, you use the CreateComponent method of the Java object to create an instance of the EAServer component. The first argument is the EAServer package and module name--for the generic component this is DataWindow/HTMLGenerator90. Additional arguments specify the URL for the EAServer server and the account ID and password.

The last argument is necessary only for instantiating a custom component, described in "Creating a custom server component in EAServer".

This statement creates a component instance called dwMine. If dwMine is null, the creation fails and the PowerDynamo site object provides some error information:

dwMine = java.CreateComponent(

        "DataWindow/HTMLGenerator90", 

        "iiop://testMachine:9000", "Jagadmin", "" );

if( dwMine == null ) {

        document.Writeln( "Error Message: " +

                site.GetErrorInfo() + "<BR>");

}

CreateObject

In ASP, you can access the registered COM component using its Program ID. For example, if you use the generic component:

    dwMine = Server.CreateObject(
        "PowerBuilder.HTMLDataWindow")

Loading the DataWindow object

SetDWObject

The next step is to specify the PBD or PBL file that contains the DataWindow object and the name of the DataWindow object. You do not need to specify the location of the file, but it must be available on the component server in a directory on the server's path (or on the system path if the EAServer component is running as a service or if you are using IIS or MTS):

 retVal = dwMine.SetDWObject ("htgenex.pbl",

        "d_tabular_dept");

This DynaScript example tests the return value and writes an error message to the HTML page (in ASP, use Response.Write instead of document.Writeln):

    if (retVal != 1){

        document.Writeln("SetDWObject failed " + 

            retVal + "<BR>");

}

You can also specify a:

• Source definition (SRD) file containing the source for a DataWindow object. You can export a DataWindow definition to an SRD file in the Library painter or System Tree.

• Powersoft report (PSR) file containing a DataWindow object plus data. You can save a PSR file from the DataWindow painter

• DataWindow Container component on EAServer containing multiple DataWindow object definitions

For SRD and PSR files, specify an empty string for the DataWindow name:

dwServer.SetDWObject("myreport.psr", "" );

For DataWindow Container components, use the the SetDWObjectEx method:

dwServer.SetDWObjectEx ("d_emp");

Controlling what HTML is generated

Disabling features of the client control

SetWeight

Although the server component generates a considerable amount of HTML and JavaScript for the Web DataWindow client control, it is still no more than an average image file. However, to reduce the size of the control on the client, you can instruct the component to leave out code for features you are not using. You can tell the component to omit code for:

• Updating data

• Validating newly entered data

• Client-side events

• Allowing client-side scripts to call methods of the client control

• Applying display formats to newly entered data

You can disable any of these on the HTML Generation property page in the DataWindow painter or with the SetWeight method. False for a particular argument means no code for that feature is generated.

This statement enables all features:

dwMine.SetWeight(true, true, true, true, true);

If updating of data is false, no validation or display formatting code is generated either. In this statement, it does not matter what the second and fifth arguments are, because the first argument for updating data is false:

dwMine.SetWeight(false, false, true, true, false);

This statement turns off the client-side scripting capability:

dwMine.SetWeight(true, true, true, false, true);

Updating data and display formatting add the most code to the client-side control. Date processing also generates additional code. For the smallest client control, turn on only the features you need and make sure your DataWindow object does not have any date columns.

Naming the client control

SetHTMLObjectName

You need to provide a name for the Web DataWindow client control. The name is used for page parameters and client-side events. If there is more than one Web DataWindow client control on the Web page, each needs a unique name.

This code uses the same name for the server component variable and the client control:

    dwMine.SetHTMLObjectName ("dwMine");

Optimizing HTML for a browser

SetBrowser

The Web DataWindow can generate HTML optimized for particular browsers and versions. In particular, it can generate code for Microsoft and Netscape browsers. The browser may be different each time the server component is instantiated by a different client, so this information cannot be preset in the DataWindow painter. You can tell it what browser and version to target in the server-side script. In the painter, you can set the HTML Version property to specify what level of HTML to generate if the browser is not recognized.

For information on what HTML features the DataWindow uses for different browsers, see the DataWindow Reference or the HTMLGen.property topic in online Help.

At runtime, the HTTP header sent from the client browser to the Web server contains the HTTP_USER_AGENT value, which the server component can use to identify the client browser.

In PowerDynamo, you can use the GetServerVariable method of the document object to get the HTTP_USER_AGENT value:

    dwMine.SetBrowser(

        document.GetServerVariable("HTTP_USER_AGENT"));

In ASP, you can use the ServerVariables method of the Request object to get the HTTP_USER_AGENT value:

    var clientbrowser =

        Request.ServerVariables("HTTP_USER_AGENT");

dwMine.SetBrowser(clientbrowser);

Specifying the database connection and retrieving data

Specifying connection information

SetTrans

You provide connection information for the server component with the SetTrans method. The arguments you specify depend on the type of connection. For an ODBC connection to Adaptive Server Anywhere 6.0, you specify all the connection information in the dbParm argument.

In EAServer, you must also set up a connection cache for the component, described in "Creating a connection cache on EAServer ".

The data source must be defined on the server machine. It must be a system DSN on EAServer if the component is running as a service, and it must always be a system DSN on MTS or IIS. This statement connects to the EAS Demo DB sample database:

dwMine.SetTrans("ODBC",

     "ConnectString='DSN=EAS Demo DB V3;UID=dba;PWD=sql'",

        "", "", "", "", "")

Using Adaptive Server Enterprise

PowerBuilder and EAServer use slightly different versions of the CT-Lib software to connect to Adaptive Server Enterprise via Open Client. In the PowerBuilder development environment, you use the SYC native database interface to connect to the database, but you must use SYJ as the first argument to SetTrans to connect to ASE in EAServer.

Retrieving data

Retrieve

To tell the server component to retrieve data, you call the Retrieve method or, if the DataWindow object expects retrieval arguments, the RetrieveEx method.

This DynaScript code calls Retrieve and, if the return value reports an error, calls GetLastErrorString for the error message text. In ASP, use Response.Write instead of document.Writeln:

    retVal = dwMine.Retrieve();

if (retVal < 0 )

    {

        document.Writeln("Error on Retrieve: " + retVal +

                "<BR>");

        document.Writeln(dwMine.GetLastErrorString() +

                "<BR>")

    }

Specifying retrieval arguments

RetrieveEx

If the DataWindow object expects retrieval arguments, call RetrieveEx:

dwMine.RetrieveEx("60000");

Typically, the retrieval arguments are not constants. They are page parameters passed to the page from another page where the user filled in a form or clicked a hyperlink. If the DataWindow expects more than one retrieval argument, the arguments must be passed in a single string. The arguments in the string must be separated by newline characters (\n), and individual values cannot contain newline characters as part of the value. Array values must be separated by tab characters (\t).

Values passed into the page are properties of the value property of the document object. For example, this form prompts the user for a salary:

<FORM ACTION="salaryrpt.stm" NAME="log" METHOD="POST">

<p>Please enter a salary ceiling:</p>

<P><INPUT TYPE="text"     NAME="salary" SIZE="15"></p>

<p><Center>

<INPUT TYPE="Submit" VALUE="Register">

</Center></p>

</FORM>

In the PowerDynamo server-side script in salaryrpt.stm, code calls the RetrieveEx method for the server component using the salary value passed as a page parameter:

dwMine.RetrieveEx(document.value.salary);

Getting the retrieval argument from another page works the first time the page is loaded. The retrieval arguments have to be page parameters each time the page is reloaded. To specify page parameters for the reloaded page, you use the SetSelfLink method, described next.

Passing page-specific data to the reloaded page

Using self link information

The first time the client browser requests the page template, it can pass page-specific information using GET or POST, and the page can use those values in the server-side scripts. However, when the page is reloaded because of user interactions with the Web DataWindow, that information is not passed to the page automatically.

To make the information available, you specify a selflinkargs string with values that become page parameters in the reloaded page. Typically, you would use self-link parameters to keep available:

• Login information from another page

• The DataWindow object name

• Retrieval arguments for the DataWindow object

To provide these values when the page is reloaded, you use the SetSelfLink method, which takes as arguments the URL of the page template as well as the selflinkargs string.

Getting the URL for the page

To reload the page correctly in response to user actions, the server component needs to know the URL of the page template. You can get this information from the name property of the document object or the SCRIPT_NAME server variable.

In PowerDynamo, use the GetServerVariable method of the document object:

var url = document.GetServerVariable( "SCRIPT_NAME" );

In ASP, use the ServerVariables method of the Request object:

var url = Request.ServerVariables( "SCRIPT_NAME" );

Building a self-link argument string

Self-link arguments become page parameters in the reloaded page. Your script typically looks at an existing page parameter and re-creates it using a self-link argument. The syntax for specifying a self-link argument string is:

pageparam1='expr1'|pageparam2='expr2'...|pageparamn='exprn'

The string can contain one or more page parameter and expression pairs separated by pipes ( | ). Each expression is a DataWindow expression that evaluates to a string. Usually you specify constant string values that are already values of page parameters rather than expressions.

The expression is enclosed in quotes, and if the value is a constant, it must also be enclosed in quotes. For example, if a page parameter called logname is passed to the page and it has the value Fred, the string you need to pass in the SetSelfLink method is:

logname='"Fred"'

To get the value from the current logname parameter, which is already defined for the page, you build the expression using the logname page parameter. The single quotes and inner double quotes are embedded in the expression. The current value of logname is inserted between the quotes:

var linkargs = 

        "logname='\"" + document.value.logname + "\"'";

An expression does not need the inner quotes:

var linkargs = "date='String(Today())'";

Passing the URL and argument string to SetSelfLink

SetSelfLink

Use the URL obtained from the SCRIPT_NAME server variable and the link arguments string you built as arguments to the SetSelfLink method:

dwMine.SetSelfLink(url, linkargs);

Retrieval arguments as self-link values

The first time the page is loaded, the retrieval argument might be:

• A page parameter passed from another page. The user might have clicked a URL that included the value or filled in a form that posted the value.

• A new value calculated in the current script.

If the value is a page parameter, then you can re-create the page parameter using SetSelfLink. If the value is from some other source, you need to write code that gets the value from the source (which might be a page parameter) the first time the page is loaded and from a page parameter when it is reloaded.

Examples

These PowerDynamo examples show code that works with the types of values listed above. They illustrate how to get each type of value and use it in both RetrieveEx and SetSelfLink method calls.

Value from another page

If the user entered a product ID in a form to get detailed information on the product, the product ID is passed to the product report template as a page parameter. The page parameter should always exist because it comes from the calling page, but the code provides a default value anyway:

if (exists(document.value.prodid)) {

        prod_id = document.value.prodid;

    } else { 

prod_id = "1";

}

dwMine.RetrieveEx(prod_id);

dwMine.SetSelfLink(document.name, 

        "prodid=" + "'\"" + prod_id + "\"'");

Calculated value

If the value is to be calculated in the script, then the page parameter will not exist the first time the script runs. If the random page parameter exists, the script gets the value from the parameter; otherwise the script calculates a value using a Math function:

if (exists(document.value.random)) {

        rnd = parseInt(document.value.random);

} else {

        rnd = Math.random();

}

dwMine.RetrieveEx(rnd);

dwMine.SetSelfLink(document.name, 

        "random=" + "'\"" + String(rnd) + "\"'";

Multiple values

In this example, a Web page with a form prompts the user for a user name and a product category and the level of detail the user wants to see. The code uses the product category as a retrieval argument for the Web DataWindow. The script selects a DataWindow object based on the level of detail. All three values are carried over each time the page is reloaded:

// Get product category as a retrieval arg

if (exists(document.value.category)){

        retrievearg = document.value.category;

} else {

retrievearg = "all";

}

rtn = dwMine.RetrieveEx(retrievearg);

if (rtn < 0) {

    ... // Check for error

}

// Get the user name

if (exists(document.value.username)){ 

        username = document.value.username;

        document.Write("<P>Dear " + username + "</P>");

}

    document.Write("<P>Here is the report you
        requested.</P>");

// Choose DW based on detail level requested

if (exists(document.value.reportlevel)) {

        rptlevel = document.value.reportlevel;

        if (rptlevel == "detail"){

            dw = "d_product_detail";

        } else {

            dw = "d_product_summary";

        }

}

else if (exists(document.value.dw)){

        dw = document.value.dw;

} else {

        document.Write("<P>Error selecting report");

        return;

        }

}

dwMine.SetDWObject("productrpt.pbd", dw);

// Tell the server component to recreate the 

// page parameters in HTML generated for the browser

linkargs = "username='\"" + username + "\"'"

 + "|category= '\"" + retrievearg + "\"'"

 + "|dw= '\"" + dw + "\"'";

dwMine.SetSelfLink( document.name, linkargs );

Passing user actions to the server component

SetAction

When the user clicks a DataWindow button, action information is passed back to the page server as context and action page parameters. Your server-side script needs to access those page parameters and call SetAction so the server component can apply the action to the generated HTML.

The names of the parameters use the object name specified in the SetHTMLObjectName method, for example: dwMine_action and dwMine_context. You can also specify the object name on the HTML Generation tab page in the DataWindow painter:.

You can include buttons for scrolling to other pages of data and for retrieving and updating data and inserting and deleting rows. When these button actions occur, the change is sent back to the server component and the change is made in the DataWindow buffer. If the user clicks an update button, the update method is called in the component without any other scripting needed.

No need to call methods

You can call server component methods directly for retrieving data, updating, inserting and deleting rows, and so forth. However, remember that button clicks invoke the actions. You do not need to call the methods too.

This DynaScript code uses a function called GetParam to see if the parameters have been defined (meaning that the page is a reloaded page) and if so, calls SetAction to send the action information to the server component:

// Function to test whether page parameters are defined

function GetParam( envparam ) {

        if( exists(document.value[envparam] ) )  {

            return document.value[envparam];

        }

        return "";

};

// Check if we need to perform the action

var dwMine_action = GetParam("dwMine_action");

var dwMine_context = GetParam("dwMine_context");

if ("" != "" + dwMine_action) {

        retVal = dwMine.SetAction(

            dwMine_action, dwMine_context);

        if (retVal < 0 ) {

            document.Write ("Error on SetAction: "

                + retVal + "<BR>");

            document.Write ( 

                dwMine.GetLastErrorString()+ "<BR>");

        }

}

Inserting the generated HTML into the page

Generate

After the server script has done all the setup, it calls the Generate function, which returns the generated HTML as a string.

In PowerDynamo, use document.Write to insert the code in the page template:

document.Write( dwMine.Generate() );

In ASP, use Response.Write to insert the code in the page template:

Response.Write( dwMine.Generate() );