A project of mine required adding FTP (File Transfer Protocol) capability to a PowerBuilder application. I evaluated several products from different vendors and chose Distinct Corporation’s TCP/IP Internet Toolkit for the job. The toolkit is vastly powerful and very easy to implement due to OLE Custom controls (also referred to as OCX or ActiveX controls). Stick around and let’s discuss how this product can make your Internet development efforts require less development time and be fun to code.

The ability to add TCP/IP communications capability to your PowerBuilder applications can make you a valuable member of any development team. In the past, developers have relied on skills which required low-level coding and a steep learning curve. This might include making difficult calls to the Winsock API and managing socket connections, application protocol processing and state level management. Wow! Your project could grow old while you learn the Winsock API!

That has all changed with Distinct’s Corporation’s TCP/IP Internet Toolkit and PowerBuilder 5.0’s capability to use ActiveX controls. ActiveX controls provide a whole new level of extensibility to PowerBuilder much like VBX controls have done for Microsoft’s Visual Basic for years. PowerBuilder developers can now create powerful Internet capable applications in record time with a minimal learning curve.

Internet enabling an application can provide many powerful capabilities to your PowerBuilder application including global E-mail, access to web servers, news servers and even simple application to application communications. Remember how excited you were the first time you used DDE to communicate between two Windows applications? With the TCP/IP Toolkit from Distinct, your PowerBuilder applications can communicate with other applications…not just within your workstation but anywhere in the world!

For example, your application might offer "on-line" registration by sending the data directly to a special server application or database over the Internet. Maybe your company needs certain actions in your corporate database to produce PSR reports to sent as MIME encoded E-mail attachments to satellite offices. Perhaps you need the ability to send data files directly to the corporate FTP server or you require the ability to send and receive global E-mail. All that, plus much more is readily available with this product.

Distinct Corporation has been a long time maker of Internet related API’s for developers. Their current TCP/IP Toolkit provides a complete arsenal of VBX and ActiveX controls, each providing support for a specific Internet protocol. All popular protocols are supported, including basic Windows Sockets, TCP Server, FTP Client and Server (file transfer), SMTP (send mail), POP (retrieve mail), and NNTP (news groups). See Table 1. for a complete list and brief description of each control.

ActiveX controls are provided for the 32-bit platform and VBX’s for 16-bit. Unfortunately, the 16-bit VBX controls require support for callback functions not supported in VBX version 1.0. and thus some of the 16-bit VBX controls cannot be used with 16-bit Powerbuilder. PowerBuilder’s implementation of VBX controls is limited to those compliant with version 1.0. Because of this, Distinct does not support the 16-bit version of PowerBuilder. It would be nice if Distinct offered 16-bit ActiveX controls but you can’t blame them for PowerBuilder’s limitation. The good news is that while some Internet enabled ActiveX vendors are only supporting the Visual Basic developer community, Distinct is supporting their products on multiple development platforms, including PowerBuilder. That is a big plus since you don’t want to find yourself using unsupported tools!

If you have not used custom controls in PowerBuilder 5.0, you are in for a real treat. Any bad impressions of OLE or VBX controls should be put aside since ActiveX controls are the next generation of "plug & play" OLE technology. ActiveX controls allow developers to integrate the control’s features into their applications without making calls directly to a Dynamic Link Library (DLL). The control is placed on a window and the PowerBuilder developer has immediate access to the control’s methods, events and properties. The control works like PowerBuilders’s native controls and thus is very intuitive.

In addition, ActiveX controls are not limited to a specific language. Any ActiveX control may be used in a variety of development environments that support ActiveX such as Optima++, Visual Basic and Visual C++. ActiveX controls are also ‘smart’ controls. They ‘publish’ their interface (properties, methods and events) which may be viewed by using PowerBuilder’s object browser. Figure 1. shows how this might look when viewing methods for the Distinct FTP Client control. Let’s briefly review how to use an ActiveX control in PowerBuilder and then we’ll focus on the Distinct TCP/IP toolkit in more detail.

All available ActiveX controls are typically registered in your system at install time using special entries in the registry. To place an ActiveX control on a window or user object, simply select the OLE control from the PowerBuilder drop-down toolbar or choose Controls->OLE from the menu bar. PowerBuilder will display the Insert Object dialog box where you may select an OLE custom control. Select the right-most tab labeled "Insert Control" to see a list of all registered ActiveX controls in your system. Figure 2. shows an example of the PowerBuilder Insert Dialog. Select your ActiveX control from the list and then click the Ok button. Next, click on your window or user object to place your new OLE/ActiveX control. Once the control is placed on a window or user object, it is ready to use like any other control. The control will be visible initially but this may be set to FALSE later when you don’t want it to appear to the user.

Figure 1.

Now let’s take a look at using the Distinct custom controls in a PowerBuilder application. I’ve chosen to show the FTP Client control in the code listings that should provide a good idea of implementing the other controls in the product. FTP is a very old and popular Internet protocol used for transferring files from one computer to another. Typically, an FTP client will connect to an FTP server and transfer files to or from the server.

Figure 2.

FTP is actually one of the more difficult protocols to implement at the Winsock API level since two socket connections are used for each client. One connection provides a command channel while the second connection is used for the actual transfer of file data. However, Distinct’s FTP control can enable your application to transfer a file to or from an FTP server in as little as three lines of code! The management of sockets and the actual application protocol is completely handled by the control.

Once the FTP control is placed on a window, a right mouse click on the control will provide a popup menu for access to two different property dialogs. One is a PowerBuilder dialog that provides generic properties for all ActiveX controls such as visible and border. This is where PowerBuilder displays it’s default object name, which is ole_1 for the first OLE control, placed. In the sample code listings, I renamed the FTP control to ole_ftp.

Figure 3. shows the control’s popup menu. Note the popup menu option is named ‘OCX Properties…’ which provides direct access to design-time properties for the selected control. For example, the FTP Client control offers several properties that may be set including host name, user name, password and more. Figure 4. shows the OCX properties dialog for the FTP Client control. The other controls provide similar dialogs with properties specific for each control. Other properties may only be set at run time such as the Action property used to connect or disconnect from a host server.

Figure 3.

Figure 4.

I mentioned previously that a file could be transferred with as little as three lines of code. Listing 1. shows how to connect to a server, download a specific file to your local workstation and then disconnect. This mode of file transfer is called FILE mode and permits you to name both the local and hosts file and have the transfer occur directly. This mode is set by either calling the FileMode() method or setting the TransferMode property to TRANSFER_MODE_FILE prior to transferring the file. Should you need to transfer data from a source other than a file such as DDE data or from the Window’s clipboard, you may call the EventMode() method or set the TransferMode property to TRANSFER_MODE_EVENT. This option requires that you only specify the server filename while providing the source data from any local buffer. This type of transfer uses a special OnSend event where you pass the data to be sent in chunks. This is a powerful feature that does not limit you to transferring data only from local files. Data may be received in a similar fashion.

The Distinct FTP control supports many other useful events. For example, the OnTransfer event may be triggered during file based transfers. The event is passed a single argument of type long that represents the total number of bytes transferred. You can inform your user of the file transfer progress by simply displaying this value from the OnTransfer event. A boolean property named Notify is available which controls whether the OnTransfer event is triggered during file based transfers.

Error handling is provided by a single OnError event. The argument passed to this event identifies the type of error that occurred. Distinct provides a complete set of error codes that may be mapped to an error message in the OnError event. Listing 2. displays a partial example of how this event might be coded.

A complete list of methods, properties and events for the Distinct FTP ActiveX is provided in Table 2. and readily demonstrates the awesome flexibility that this single control has to offer. The purpose of the each method, property or event can be determined from its name since Distinct’s naming conventions are intuitive. All of the controls in the Distinct TCP/IP Internet Toolkit are robust and full of features like the FTP Client. Having each protocol in a separate ActiveX means you won’t end up with a lot of unnecessary code in your application. Only add the ActiveX controls that you need for any particular project.

Although sample code is provided for several development tools, PowerBuilder code is currently not included. However, you can get PowerBuilder examples by contacting Distinct directly. I suggest installing only the Visual Basic samples and your complete install will be under 4 Meg. The Visual Basic samples will help you get started if you don’t have the PowerBuilder samples on hand.

The product’s documentation is excellent and consists of a large, sturdy, full-size binder with tab-separated sections for each control. Each control is carefully described including standard usage, code examples, events, properties, methods and even constants where appropriate. Separate help files are also available for each control and permit you to focus on the information for the particular control you are using.

My impressions of Distinct Corporation are excellent. They are quick to respond to inquiries and offer excellent technical support. They are committed to supporting PowerBuilder developers. For example, Distinct promptly contacted Powersoft directly to correct a bug I discovered while testing their controls with PowerBuilder 5.0. During my initial testing, I discovered a problem where string arguments being passed from a control’s event to my application contained garbage. I notified Distinct of the problem and they in turn contacted Powersoft. I soon received notification from Distinct that Powersoft had indeed discovered a problem in their PBROI050.DLL and a quick patch solved the problem. I was impressed with both Distinct and Powersoft for taking action and solving the issue so quickly. I’m not sure which release of PowerBuilder 5.0 contains the corrected DLL from so you will want to be sure to get on the latest version of the DLL from Powersoft if you experience problems accessing string data from events.

The only disappointments are that ActiveX’s are only offered for the 32-bit platform and the fact that Distinct does require licensing fees for distribution of their controls. You must also ensure that the serial number and key code are properly set in the user’s registry during installation. However, Distinct will work with volume purchases and I suspect licensing costs may decrease or disappear completely in the future as more vendors heat up the Internet ActiveX market. Most OCX/ActiveX vendors do not require distribution or license fees.

The version I tested for this review was version 1.3 that was released early this year. This release includes firewall support through SOCKS version 5, HTTP 1.1with SSL (Secure Sockets Layer) and even a fully functional FTP Server control. Retail cost for the product is $295, or $545 for the product and a robust subscription program. The subscription provides one year of developer support and upgrades. If you need to add Internet capabilities to your PowerBuilder application or simply want to learn more about Internet protocols, you cannot do better than Distinct’s TCP/IP Internet Toolkit!