Using a custom server component

If you are using EAServer as
the component server, you can deploy a custom component that uses
methods of the generic server component interface. You can also
write a server component with its own DataWindow methods for use with EAServer or COM+.

Some advantages of a custom component

You can use a custom component to enhance:

Maintainability Keep connection information on the server by specifying values
for transaction properties.
Performance Specify the source file and DataWindow object on the server
so that the DataWindow object is loaded when the component instance
is created, resulting in fewer method calls from server-side scripts in
the Web page. You can also improve performance by having your custom
component maintain its state.
For information about changing the state property of a custom
component, see “Maintaining state on the
server”.
Scalability Specify the source file and DataWindow object and use EAServer instance pooling so that
the component is reused and loading the DataWindow object occurs
only once.

Contention between the DataWindow painter and EAServer If you are working in the DataWindow painter and testing the
same PBL in EAServer, your PBL
might be locked when the EAServer component
loads the DataWindow. To avoid this, disable instance pooling for
the component in EAServer Manager.
After you have finished testing and editing the DataWindow object,
you can enable instance pooling.

Instance pooling provides better performance in a production
environment when a component instance can be reinitialized and reused
for multiple clients.

For information on creating a custom component that uses the
generic Web DataWindow interface, see “Creating a custom server
component in EAServer“ or “Deploying DataWindow objects
to the component server”.

Writing your own custom
component

For full control of Web generation and the state of the DataStore
object that holds the DataWindow definition and data, you can write
your own custom class user object in PowerBuilder and deploy it
as an EAServer or
COM component. Using a custom component that includes only the processing
you need can reduce the size of the client control returned to the
Web client.

The source code for the generic component is available in PBDWRMT.PBL in the
PowerBuilder code examples directory so that you can examine or
reuse it. You can modify or add to the code in this PBL or start
from scratch, using the sample PBL as a model for your own component.

Mixed-case method names The methods of the generic EAServer 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 EAServer component you generate
are all lowercase. However, you can change the case of the method
names in the IDL file for your component after it is deployed to EAServer. When you use your own
component, you must generate and compile stubs for the component,
and you must do this after you make any changes to the IDL.

Your server component will use methods on a DataStore object
to retrieve data and return the data and state to the client as
HTML. To get the HTML and JavaScript that represents the state,
data, and presentation of the DataWindow object, use the Describe
method:

 ls_html = ds_1.Describe("DataWindow.Data.HTML");

1	ls_html = ds_1.Describe("DataWindow.Data.HTML");

To update the HTML according to user actions, use the SetHTMLAction method:

 li_rtn = ds_1.SetHTMLAction(arg_action, arg_context);

1	li_rtn = ds_1.SetHTMLAction(arg_action, arg_context);

SetHTMLAction restores the state of the DataStore based on
the context passed in as an argument and then changes the state
based on the passed action.

For more information about SetHTMLAction, see the DataWindow
Reference
or online Help. For information about working
with DataStore objects, see Chapter 4, “Using DataStore Objects “.

If you create your own server component and deploy it to EAServer, you must also generate
and compile the stubs. For information on generating and compiling
stubs, see the EAServer documentation.

If you deploy the user object as a COM component, you need
to register it. For information about registering COM components,
see “Server configuration requirements”.

Creating a custom server component in EAServer

You can install and configure a custom Web DataWindow server
component in EAServer Manager.
In this procedure, you create a custom version of the EAServer server component with custom
properties preset in EAServer Manager.

Using the Web DataWindow Container Project wizard The procedure in this section describes how to create a custom
component in EAServer Manager
that uses the generic DataWindow::HTMLGenerator100 interface. You
can also create a custom component with a Web DataWindow Container
project. For more information, see “The Web DataWindow Container
project wizard”.

To create a Web DataWindow custom component in EAServer:

In the left pane of EAServer Manager,
under the server name, right-click Packages and select New Package
from the pop-up menu.
In the New Package dialog box, type a package
name (you cannot change it later) and click Create A New Package.

For example, use EmpListPkg to identify a package for an application called
EmpList.
On the General tab of the Package Properties dialog
box, enter a description of the package and click OK.

For example, enter DataWindow Components for EmpList
app to describe EmpListPkg in terms of the application
that you are customizing it for.
In the left pane of EAServer Manager,
under the server name, right-click the new package and choose Install
Component from the pop-up menu.
In the wizard, choose the Define New Component
radio button and click Next.
Specify the name of your custom component (you
cannot change it later) and click Finish.

For example, use EmpListDW to identify a component that uses
the d_emplist DataWindow object.

In the Component Properties dialog on the General
tab, specify:

Module and interface	DataWindow::HTMLGenerator100
Component Type	PowerBuilder NVO
PowerBuilder Class Name	nv_remote_datawindow
PowerBuilder Library List	pbdwr100.pbd
PowerBuilder Application	remote_datawindow_appl

On the All Properties tab, add the properties
for which you want preset values.

Setting properties for a custom component in EAServer

You add as many of the following properties as needed for
your custom component. The properties
are divided into two groups: general and database connection.

For boolean properties, values can be true or false, or yes
or no.

General properties These properties specify settings that take effect when the
component is instantiated.

Table 7-3: General properties to add for custom component
General property	Description
com.sybase.datawindow. sourceFileName	Specifies the PBL, the PBD that contains the DataWindow object for the component, or the SRD or PSR file that is the DataWindow object. See also the SetDWObject method in the online Help or DataWindow Reference .
com.sybase.datawindow. dwObjectName	The name of the DataWindow object in the PBL or PBD specified for sourceFileName. See also the SetDWObject method.
com.sybase.datawindow. fixed	Whether component properties can be modified from server-side script (SetDWObject, Create, Modify, and SetTrans methods) that instantiates the component. Values are: Yes — Properties are fixed and cannot be changed. No — Properties can be changed.
com.sybase.datawindow. serverServiceClasses	A list of PowerBuilder user objects that are in the PBL or PBD specified in sourceFileName. The class names should be separated by semicolons (;). The user objects implement custom events for data validation. For information on custom events, see the SetServerServiceClasses method in the online Help or DataWindow Reference .
com.sybase.datawindow. serverSideState	Specifies whether the server attempts to maintain its state between method calls. Values are: Yes — The server component keeps the result set and keeps the transaction open if possible. No — (Default) The result set is not saved and the server component uses information passed back from the client to retrieve the result set again and restore any uncommitted changes.
com.sybase.datawindow. trace	Whether calls to component methods are included in the EAServer server log. Values are: Yes — Calls to component methods are listed in the log. No — (Default) Calls to component methods are not logged.
com.sybase.datawindow. HTMLObjectName	The name used for the Web DataWindow client control in the generated code. The name is used to implement client-side events and to allow client-side scripting Set this property when there will be more than one Web DataWindow on a Web page so that they do not conflict. See also the SetHTMLObjectName method.
com.sybase.datawindow. modifyString	A string that is used as an argument to the Modify method for setting properties of the DataWindow object. The component calls the Modify method when it is initialized. For information on syntax, see the Modify method.

Database connection properties For the database connection properties, you must add com.sybase.datawindow.trans.dbms.
This property must be set for any of the other trans properties
to be recognized. When trans.dbms is set, any unspecified connection
properties default to an empty string.

For more information about database connections, see the SetTrans
method in the DataWindow Reference
.

Table 7-4: Database connection properties to add for custom component
Database connection property	Description
com.sybase.datawindow. trans.dbms	A database vendor identifier, as displayed in the PowerBuilder Connection Profiles dialog box.
com.sybase.datawindow. trans.dbparm	DBMS-specific connection parameters.
com.sybase.datawindow. trans.lock	The isolation level. See the online Help for information about database preferences.
com.sybase.datawindow. trans.logid	The name or ID of the account the component uses when it logs on to the database server.
com.sybase.datawindow. trans.logpass	The password used to log on to the database server.
com.sybase.datawindow. trans.database	The name of the database to which the component is connecting. Ignored for ODBC.
com.sybase.datawindow. trans.servername	The name of the server on which the database resides.

Instantiating the custom component

To use the custom component in your server-side scripts, you
specify your package and component name in the form YourPackage/YourComponent.
If you are using methods of the generic component installed with EAServer, you must use the narrow
method on the generic component helper class to reference the DataWindow/HTMLGenerator100
interface.

The following code in a JSP instantiates a custom component
called EmpListDW that uses the generic HTMLGenerator100 component
interface. EmpListDW is deployed in the EmpListPkg package. You
substitute this code for the line that instantiates the generic
component in the example for “Instantiating the component”, but you do not change the narrow method
called on the generic component’s helper class:

 String dwGenerator = "EmpListPkg/EmpListDW";

1	String dwGenerator = "EmpListPkg/EmpListDW";

    EmpListDW dwGen = null;

1	EmpListDW dwGen = null;

...

...

 dwGen = HTMLGenerator100Helper.narrow(factory.create<br />          ("jagadmin",""));

1	dwGen = HTMLGenerator100Helper.narrow(factory.create<br /> ("jagadmin",""));

Using OneTrip to set up the component and get
the generated HTML “Instantiating and configuring
the server component” described several
items your server script should include to set up the Web DataWindow correctly.
Instead of coding all these things separately, you can do all the
setup and get the generated HTML with a single method when the EAServer component has been configured
with a DataWindow definition and transaction information.

This technique is especially useful for improving performance
without requiring the server component to maintain state.

 String browser=(String)request.getHeader("User-Agent");

1	String browser=(String)request.getHeader("User-Agent");

 dwGen.SetBrowser(browser);

1	dwGen.SetBrowser(browser);

 String URI = request.getRequestURI();

1	String URI = request.getRequestURI();

 String [] myArray = URI.split ("/");

1	String [] myArray = URI.split ("/");

 String selfLink = myArray [myArray.length-1];

1	String selfLink = myArray [myArray.length-1];

 int retVal;

1	int retVal;

 String dw_1_action =(String)request.GetParameter     ("dw_1_action");

1	String dw_1_action =(String)request.GetParameter ("dw_1_action");

 String dw_1_context = (String)request.GetParameter     ("dw_1_context");

1	String dw_1_context = (String)request.GetParameter ("dw_1_context");

 if (dw_1_action == null){

1	if (dw_1_action == null){

  dw_1_action = "";

1	dw_1_action = "";

}

}

 if (dw_1_context == null){

1	if (dw_1_context == null){

  dw_1_context = "";

1	dw_1_context = "";

}

}

 // Pass setup info to server

1	// Pass setup info to server

 String dwHTML = dwGen.OneTrip("dw_1", browser, <br />        selfLink, "", dw_1_action, dw_1_context);

1	String dwHTML = dwGen.OneTrip("dw_1", browser, <br /> selfLink, "", dw_1_action, dw_1_context);

 // Insert HTML returned from OneTrip in the page

1	// Insert HTML returned from OneTrip in the page

 out.print (dwHTML);

1	out.print (dwHTML);

Using OneTripEx for retrieval arguments If your DataWindow requires retrieval arguments, use OneTripEx
instead of OneTrip. The code checks for a page parameter that has
the retrieval argument value. It also makes sure the value will
still be available in a reloaded page by providing a selflinkargs expression:

 String retrievearg = (String) request.getParameter ("RetArg"):

1	String retrievearg = (String) request.getParameter ("RetArg"):

 if (retrievearg == null){

1	if (retrievearg == null){

 // Provide some meaningful default value

1	// Provide some meaningful default value

    retrievearg = "default";

1	retrievearg = "default";

}

}

 String selflinkarg = "RetArg='"" + retrievearg + ""'";

1	String selflinkarg = "RetArg='"" + retrievearg + ""'";

 String dwHTML = dwGen.OneTripEx("dw_1", retrievearg,<br />   browser, selfLink, selflinkarg, action, context);

1	String dwHTML = dwGen.OneTripEx("dw_1", retrievearg,<br /> browser, selfLink, selflinkarg, action, context);

 out.print (dwHTML);

1	out.print (dwHTML);

Maintaining state on the server

Using a stateless component

The Web DataWindow can run in a fully stateless server environment. Variables
in the Web page keep information about the rows being viewed and any
changes the user makes; this information is communicated to the
server component as needed so that the component can restore its
state each time it is called. Restoring its state includes retrieving
data from the database each time the page is reloaded, including
each time the user navigates to another page.

Operating in a stateless mode minimizes use of server resources
but can decrease performance. The client maintains the state of
the server component in string form and the information is sent
back and forth with every request. Also, when state is not maintained
on the server, the component must connect to the database and retrieve
data each time it is called. If the component server does not do
connection caching, response time for the client could be very slow.

Using a stateful component

You can increase performance by maintaining state on the server.
To maintain state, the page server’s session object keeps
a reference to the server component. If the server component is
running in EAServer, you must
mark the component as a stateful object and set a timeout value
for the component. Failing to set a timeout value if you are using
the component as a stateful object will result in orphaned instances
of the component on the server.

Maintaining state on the server provides faster response time
if the same component is accessed again. However, it also increases
the server resources used for each client connection.

To minimize impact on server resources, a short timeout on
a session lets the server get rid of a component that might not
be requested again. If the component is called again, its state
can be restored from the client state information. When the number
of hits on a page is expected to be large, setting a shorter timeout
reduces the number of instances that need to be maintained simultaneously.

Marking the object as stateful

To mark the component as a stateful object, set the component’s com.sybase.datawindow.serverSideState
property in EAServer Manager or call
the SetServerSideState method in a server-side script:

 dwGen.SetServerSideState( true );

1	dwGen.SetServerSideState( true );

You should not set the com.sybase.jaguar.component.stateless
property for the HTMLGenerator100 component in EAServer Manager.

If you are using the Web Target object model, you specify
whether the database state is managed on the server by passing the
boolean value TRUE as the second parameter to the PSDataWindowClass
constructor:

 dw_1 = new PSDataWindowClass("dw_list", true,<br />        jagConn, dwSource, dbConn, 5);

1	dw_1 = new PSDataWindowClass("dw_list", true,<br /> jagConn, dwSource, dbConn, 5);

Passing this parameter calls the SetServerSideState method,
but it does not set a timeout value—you need to set a timeout
value whether or not you are using the Web Target object model.

Setting timeout values

To set the timeout value for the HTMLGenerator100 component,
open its Component Properties dialog box in EAServer Manager
and set the com.sybase.jaguar.component.timeout property. Timeout
values are specified in seconds; a value of 0 means the component
never times out.

Document get from Powerbuilder help

Thank you for watching.

Powerbuilder Documentation 10.0

August 3, 2023

Was this article helpful?

Connection Information

Using a custom server component – PB Docs 100

Using a custom server component

Some advantages of a custom component

Writing your own custom
component

Creating a custom server component in EAServer

Setting properties for a custom component in EAServer

Instantiating the custom component

Maintaining state on the server

Using a stateless component

Using a stateful component

Marking the object as stateful

Setting timeout values

My Website Links

Connection Information

Using a custom server component

Some advantages of a custom component

Writing your own custom component

Creating a custom server component in EAServer

Setting properties for a custom component in EAServer

Instantiating the custom component

Maintaining state on the server

Using a stateless component

Using a stateful component

Marking the object as stateful

Setting timeout values

Writing your own custom
component