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. Your project could grow old while you learn the Winsock API!

That has all changed with Distinct Corporation's Visual Internet Toolkit-32 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.

ActiveX Controls for Every Need
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 Visual Internet Toolkit-32, 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 send 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 here.

Distinct Corporation makes Internet related API's for developers. Their current Visual Internet Toolkit-32 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). Table 1 has 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 certain data types 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 support for VBX controls is limited to those compliant with version 1.0. Because of this, Distinct does not support the 16-bit version of PowerBuilder. 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 which 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 Visual Internet Toolkit-32 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 dropdown 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 3 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 at runtime the control is not visible.

Implementing the FTP Client Control
Now let's take a look at using the Distinct custom controls in a PowerBuilder application. 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.

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 which provides generic properties for all ActiveX controls such as visible and border. This is where PowerBuilder displays its default object name, ole_1, for the first OLE control placed.

The popup menu option is named OCX Properties" and provides direct access to design-time properties for the selected control. For example, the FTP Client control offers several properties which may be set including host name, user name, password and more. Figure 3 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.

Inside PowerBuilder script, you reference the ActiveX control's methods, properties and events just like you would any other PowerBuilder control. The only difference is that OLE dot notation requires the word object" to separate the control name from the property or method name. This permits the PowerBuilder compiler to recognize the code as external objects and not return errors since the object's methods and properties are not part of Powerscript. For example, to set the FTP control's password property to "mypassword", you would code:

ole_ftp.object.password = "mypassword"

Some actions may be performed by setting properties, calling methods with or without arguments or a combination of both. For example, to connect to an FTP server, we need to provide the host name (to identify the FTP server host), a user name and the user's password. The following lines show a simple connect by setting properties. Note the last line, where the special Action property is set to a constant. Setting this property to this value actually initiates the connection to the host.

ole_ftp.Object.Host = "ftp.powersoft.com"
ole_ftp.Object.User = "someuser"
ole_ftp.Object.Password = "somepassword"
ole_ftp.Object.Action = ACTION_CONNECT

The ACTION_CONNECT represents a global constant which was declared and set in the global variable declarations window. Distinct provides a complete listing of all global constants. The ACTION_CONNECT declaration would appear in the global declaration window as:

constant int ACTION_CONNECT = 2

A second, more familiar syntax for connecting to the host server is to call the Connect method directly and pass it the necessary arguments. The last argument represents a user account and may not be required to connect.

ole_ftp.Object.Connect("ftp.powersoft.com", "someuser", "somepassword", "")

Return values may be checked for error logic but errors also trigger the OnError event where error messages and handling may occur. All of the low-level socket handling and protocol hand-shaking is taken care of for you. It does not get any easier than this!

Internet Communications Made Easy
The Distinct FTP control supports many useful events. For example, the OnTransfer event may be triggered during file based transfers. The event is passed a single argument of type long which 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 which occurred. Distinct provides a complete set of error codes which may be mapped to an error message in the OnError event.

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 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 Visual Internet Toolkit-32 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 which 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.

Company/Product Summary
The Visual Internet Toolkit'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 permits 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, offer excellent technical support and 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 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.

The version I tested for this review was version 1.3.. 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 Visual Internet Toolkit-32!