Welcome!

PowerBuilder Authors: Chris Pollach, Avi Rosenthal, Yakov Fain, RealWire News Distribution, Al Soucy

Related Topics: PowerBuilder

PowerBuilder: Article

PowerBuilder Web Deployment Kit

PowerBuilder Web Deployment Kit

Let's look first at what PowerBuilder Web Deployment Kit (PBWDK) does and doesn't do. What it doesn't do is convert your existing client/server applications into Web applications. That is, it doesn't render your existing client/server applications into HTML and JavaScript. What it does do, however, is allow you to take advantage of one of the most significant benefits of Web applications - ease of deployment.

A PBWDK-deployed client/server application (see Figure 1) looks and feels like a standard client/server application, but without the large footprint typical of such an application. It's similar in approach to some terminal server software products in which the actual application is running on the host server. The server sends a screen image down to the client and the client sends keyboard and mouse input back to the server for processing.

There are some important differences, however, between such programs (e.g., Citrix) and the approach used by the PBWDK in that PBWDK doesn't simply copy the screen image off the server; it actually redirects the screen update API calls to the client. That is, the client isn't just displaying a window into the application running on the server, it's actually running a portion of the application on the client. Because of this, the approach currently works only with Windows clients. However, it also offers a significant increase in performance. A PBWDK-enabled PowerBuilder application can operate with essentially the same speed as if it were running locally, even over the Internet or over dial-up lines.

Once the application is installed on the PBWDK Server, the PBWDK Administrator is used to create a "launch" file for the application. This file is basically a shortcut that tells the client runtime where to find the application, what working directory to use on the server, what command-line parameters to send when launching it and what security measures to use before launching the application. If the client has direct access to the launch file, it could run the application directly from it. The browser is simply a convenient way to get the launch file to the client.

Once the client obtains the launch file and submits it to the client runtime, there's no further communication with the Web server. The client runtime uses the information in the launch file to locate the PBWDK server and talk to it directly. As indicated in Figure 1, the PBWDK uses port 2287 to communicate through, so with Internet applications that port will need to be opened on the firewall. Depending on how the PBWDK server is configured, the applications running on the server may be able to access the drives and printers on the client. Depending on how the launch file is set up, the client may be challenged to provide a username and password for the NT domain before using the application.

Installing the Product
The PBWDK has a standard Windows application install process. You'll need to be logged in as the system administrator or have a user account with administrator rights, because the PBWDK installs as a service.

Note that the PBWDK server doesn't need to be installed on the Web server but on a separate server or server "farm." The only part of PBWDK that must be installed on the Web server, or at least accessible from it, is the PBWDK launch files that you'll create; they'll operate as shortcuts to the PBWDK-enabled applications.

Warning: Windows NT Service Pack 6 (SP6) is known to "break" most applications that, like PBWDK, use Winsock. If your server is running SP6, an upgrade to SP6a is highly recommended.

The setup routine gives you four options:

  1. Install WDK Client
  2. Install WDK Server
  3. Copy Installer to Network
  4. Exit

At a minimum, you select option 2 to install the PBWDK server on the server. If you want your users to be able to download the client runtimes directly to their machines from the Web, you should also choose option 3. That option copies the routines used for the client runtime install to the server.

During the installation of the product, you'll be asked how you want to handle remote (i.e., client) drive access and mappings. The issue is that there is often a conflict between the drive letters assigned on the server and the client (e.g., A: or C:). As a result - if access to both server and client drives is desired - one set of drives will have to be remapped to new drive letters.

There are three options for PBWDK enabled application:

  1. It can access server and network shared drives with their original mappings and can't access local drives.
  2. It can access server and network shared drives with their original mappings and can access local drives using new drive letters. With this option local drives are temporarily remapped while the PBWDK-enabled application is running.
  3. It can access local drives using their original drive letters and server drives using new drive mappings. With this option the setup stops and you then use the Windows NT Disk Administrator to remap the server drives permanently. Warning: Choose this third option with care. It's the one configuration option for the PBWDK server that requires a complete reinstall of the product.

Configuring the Server
Once the product is installed on the server, you can bring up the PBWDK Administrator to make additional server configuration changes (see Figure 2). The "Termination Period" is the default time delay after you have invoked a user session termination in the Administrator and their session is actually terminated. You can override the default when you perform individual user session terminations. The "Execution Errors" option determines whether the PowerBuilder application execution errors are stored in the NT event log. When a PBWDK-enabled PowerBuilder application experiences runtime errors, the users will get those error messages. However, if a PBWDK-enabled PowerBuilder application experiences an error at the operating system level (e.g., stack fault, invalid page fault), the client will lose the connection to the server. As a result, the application simply "disappears" from the client's screen without any warning or error message. Logging execution errors to the NT log helps you capture the information so you can then determine the cause of the error.

Driver and Printer Mapping
The "Drive and Printer Mapping" page shows the drive mapping (see Figure 3). However, the drive mapping is not editable except through a reinstall of the product. This page also allows you to specify the directory where the PBWDK server can find the print drivers from the NT install CD to support remote printing (i.e., printing to printers configured on the client). You could copy those files to a directory on the NT server. Alternatively, you may find that they're already located in a directory on your print server. If you simply want to refer to a location on another server, you can use a UNC pointer to them (i.e., \\servername\volume\directory). When a client attempts remote printing, PBWDK will dynamically determine the appropriate print driver to use and install it.

To allow remote printing, you must set the login to Standard or Always in the application launch file. With the login set to Guest, you'll only be able to do local printing (i.e., printing to printers configured on the server). You must also have Windows Networking (NetBios) and IP printing enabled on the server, and the printer must be on an NT print server or otherwise accessible through IP.

When PBWDK attempts to look up the appropriate driver for remote printing, it uses the driver name from the client and matches it against the driver names on the server. Unfortunately, the driver for the same printer may have different names on different operating systems (e.g., Win95 and WinNT). You'll therefore need to make the printer drivers for all of the target client operating systems available to the server or edit the print driver configuration files to make the driver names match.

Load Balancing
The "Load Balancing" page is where the server farm is configured (see Figure 4). To enable load balancing, check the option, give a name to the farm and then indicate the threshold for this particular server. Do the same with the other servers in the farm. When a user attempts to connect, the PBWDK server will determine if the primary server (the one the user originally attempted to connect to) is already at threshold. If so, it will poll the other servers in the farm to determine which is most able to handle the additional user. If no server can, the user will receive an error message saying that none of the servers can currently handle the request.

If you have one primary server that handles all of the incoming connection requests, set its threshold somewhat lower for it than for the other servers in the farm. This will leave it some processing "breathing room" to handle the incoming requests.

Note: Load balancing is built into the product; you don't need to obtain additional load-balancing software in order to scale to accommodate additional users. You do have to acquire a separate license for the product, though, for each server you wish to install it on in the farm.

Installing PB Applications and Supporting Software
The next step is to install the PowerBuilder applications on the PBWDK server. Technically, the PBWDK server only needs to be able to access the files, which means that it may be able to simply reference their current location for your client/server deployment. However, a service running on a separate server may not have access to the file server that the client/server-deployed applications are residing on. You may also want to make minor modifications to the applications to better account for their operating under the PBWDK (see below).

Normally, in a client/server implementation, the database client layer is loaded on the local workstation or is deployed on the network and accessed by the local workstation. With a PBWDK-enabled application, however, the database client layer must be installed on or available on the server, not the client. The same is true for other supporting software (OCX or ActiveX controls, OLE servers and so on); they must be installed on the server - there's no need to install them on the local workstations.

Many client/server applications take advantage of individual user settings in a local copy of the application or user INI file. In a PBWDK-enabled application there's only one copy of those files shared by all the users. Therefore, if you still want to maintain user-specific settings, you'll need to convert to using the registry or modify the routines that access the application or user INI files so it can differentiate between users. The latter could be accomplished by adding different sections for different users or dynamically determining the name of the user INI file based on the user name. If the launch file is configured for Standard login or Always login (see below), you can determine the current user name through standard Windows API calls (GetUserNameA). However, if the launch file is configured for guest login, you'll need to obtain a reference to the user identity through other means (e.g., through a database login prompt). Along those same lines, routines such as those used by PFC that display the user name from a GetUserNameA API call will no longer function appropriately if the launch file is configured for Guest login (they'll show GUEST for the user name).

Interestingly enough, in an intranet environment the PBWDK Administrator can distinguish between different users accessing the same application through guest login, even though the PowerBuilder application itself can't.

Note: This inability of the Sybase Web Deployment Kit to Web-enable non-PowerBuilder Windows applications appears to be a limitation imposed by the license between Sybase and New Moon. New Moon's Liftoff product, which is what the Sybase Web Deployment Kit is based upon, doesn't have any problems Web-enabling non-PowerBuilder applications.

Create "Launch Files" for the PBWDK-Enabled Applications
Once the applications to be PBWDK-enabled are accessible to the PBWDK server, use the PBWDK Administrator to create "launch" files for them (see Figure 5). There are two steps to the process: first the application properties are set, then a launch file is created for the application. At the application level you set the number of instances of the application that the server is allowed to have running simultaneously.

At the launch file level you'll specify the login scheme (Guest, Standard or Always) and the IP address of the server that will be used as the primary server for user connections (see Figure 6).

If you configure the launch file for Guest login, the user will never be prompted with a login dialog from the PBWDK server. PBWDK will use the NT guest account to launch the application on the server, so the guest account must be activated on the NT server that's running PBWDK. As mentioned previously, certain features of many applications (i.e., automatically determining the user name using Windows API calls) won't return useful information. In addition, remote printing is not available with the guest login scheme. This scheme is most appropriate for Internet implementations.

If you configure the launch file for Standard login (the default), users will be prompted with a login dialog from the PBWDK server the first time they attempt to access any PBWDK-enabled application on that server. They won't be prompted again for that application or any other application on that server until they log out of their workstation or the PBWDK server is restarted. This is generally the best setting for intranet implementations.

If you configure the launch file for Always login, the user will be prompted with a login dialog each time they launch a PBWDK-enabled application. This setting is more appropriate when it's necessary to allow users to login to PBWDK-enabled applications with different NT user accounts.

With either the Standard or Always login approach, you'll need to give users the right to log on locally to the NT server that PBWDK is on. I recommend creating a group for PBWDK users and then assigning the local login rights to that group (see Figure 7).

Creating a Web Page to Launch the Applications
The last step is to create a set of Web pages that can be used to launch the applications. You'll probably want to include in those some instructions for configuring the client (e.g., downloading and installing the runtime). There are three steps involved in setting up a client workstation:

  1. Ensure that Winsock2 is installed.
  2. Install the plugin (Netscape) or ActiveX (Internet Explorer)
  3. Install the PBWDK runtime.
Winsock2 is built into WinNT but is an update to Win95. You can obtain that update from the Microsoft Web site and instruct your users on how to install it. Because it's an upgrade to system files, users will need to reboot their workstations before it's fully applied.

For Netscape, the PBWDK plugin can be downloaded to the client using Netscape's SmartUpdate feature using the script in Listing 1.

The primary difference between this script and the one suggested in the PBDWK manual is that I use the JavaScript StartSoftwareUpdate method in FORCE_MODE rather than the JavaScript ConditionalUpdate method in DEFAULT mode to update the client. Rather than trying to do the ConditionalSoftwareUpdate each time the user hits the page (as the example in the PBWDK docs does), I prefer simply to check for the plugin and then redirect the user to the page that does the forced install only if it isn't found. To do this, at the beginning of the page I use the code shown in Listing 2.

The pluginframe.html file contains the definition for only two frames, one that does the actual install of the plugin and another empty, hidden frame (see Listing 3).

The code for the hidden frame is pretty simple (see Listing 4). That's because the only purpose it serves is to give me access to the document.referrer attribute in that document from the "real" plugin installation page, which lets me add a link that will take the user back to whatever page they just came from (see Listing 5).

The PBWDK Client runtime is downloaded and installed when the plugin is activated if it's not already installed on the client.

The example script provided in the PBWDK manual for referencing the plugin uses an icon on the plugin as the target that the user will click on to invoke the application. Since I prefer to keep the plugin hidden and use my own link to activate it, my own pages look more like Listing 6.

For Internet Explorer, the ActiveX will be downloaded and run directly from the reference to it in the application link (see Listing 7).

Note: Make sure that you don't have extraneous embedded spaces in the values for those parameters. The examples given in the PBWDK manual do; as a result, they won't work as given.

Conclusion
While the Sybase Web Deployment Kit allows companies to easily and quickly "Web-enable" their existing PB applications, some of the features of the product - particularly remote printing - require an above-average understanding of configuring the Windows NT Server.

An evaluation version of the product can be downloaded from Sybase at http://www.sybase.com/products/powerbuilder/trial/wdkspecial.html. Technical support during the evaluation is available in the Sybase newsgroups at news://forums.sybase.com/sybase.public.webdeploykit.

Acknowledgments
Special thanks to Mark Clark and Chuck Kahn for their review of this article and to Pat Steinhardt of Sybase for the support of the product in the Sybase newsgroup.

More Stories By Bruce Armstrong

Bruce Armstrong is a development lead with Integrated Data Services (www.get-integrated.com). A charter member of TeamSybase, he has been using PowerBuilder since version 1.0.B. He was a contributing author to SYS-CON's PowerBuilder 4.0 Secrets of the Masters and the editor of SAMs' PowerBuilder 9: Advanced Client/Server Development.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.