Tips & Tools

Recently, I needed to have FTP support embedded in a PowerBuilder application that I was writing for my day job. Since PowerBuilder lacks the ability to natively manipulate sockets (a big negative, Sybase), a third-party solution had to be found or I was going to be tempting the wrath of the Windows API, something I wasn't looking forward to doing.

After searching, testing, and coming up less-than-satisfied, along came WeOnlyDo! Software's FtpDLX component (www.weonlydo.com). A free trial with a 30-day timeout sounded promising, so I gave it a shot. At first, I had some problems understanding the process by which it worked under PowerBuilder, but with some perseverance and e-mails to WeOnlyDo! (WOD) support, I was able to make a functional and extensible FTP-enabled application.

The WOD FtpDLX component is a combination COM and ActiveX component that can be installed and used in either manner; my experience tells me that the only effective method is ActiveX because of the events-handling system in PowerBuilder. The component handles traditional FTP, FTP+SSL, and SFTP with multiple encryption protocols: DES, Triple DES, AES, Blowfish, DH, ADH, RC2, RC4, and IDEA. The functions are clearly named and well defined; the events are relevant, handy, and useful. In the ActiveX state it provides a powerful GUI that you can use as a pre-defined interface or hide, giving you a more tightly controlled user experience.

And here's the best part: the component only costs $219 for a single developer's license, and that is the last cost you will have...ever. That's because along with a great price, all updates and upgrades are free for the life of the product. Every time the product is updated you get an e-mail with an extremely handy download link embedded to download the update directly. Support via e-mail is also completely free. And you can distribute the product 100% royalty-free. Did I mention there's a lot of free stuff with this?

The e-mail support is excellent. My only e-mail contact has been with a fellow named Kreso and he's been phenomenally patient and courteous. During my initial work to get the component functional, I wrote and said, "The product is great, but...it doesn't work." Kreso never blamed me or said it could not do what I wanted it to, he just said, "It has to work...it's imperative. We'll make it work." Several exchanges later and my problems were solved (they were of my own making) without any chiding or frustration from Kreso.

The documentation for the component is very well written as well. A comprehensive manual and help file come in both PDF and the Microsoft HTML Help (CHM) format for ease of use and printing. They are clearly written for the programming community as each method, event, and property is laid out in clear terms as to the parameters, return values, and actions (where appropriate). The only things I found lacking were sample files and examples in PowerBuilder (hence this review and tutorial); both are included for Visual C++ and Visual Basic.

All in all, if you're looking for an easy way to incorporate FTP into PowerBuilder (or any other language), this is an excellent product that's well worth the price for what you get.

Integration with PowerBuilder
Since the WOD FtpDLX component doesn't come with PowerBuilder examples and samples, I decided to chronicle my experiences for other PB developers. I developed these instructions using PowerBuilder 9.0.1 Build 7171 on Windows 2000 SP4, but I suspect they will work for just about any version of PowerBuilder from 7 on due to similarities.

Disclaimer
These are my experiences; your mileage may vary. I'm not the official support for this product, but you may contact me if you have questions and I'll try to answer them. Use of the instructions, recommendations, and advice contained herein and in any communication with me in any way whatsoever is at your own risk. I'm not responsible for any damage to person or property that using these instructions might cause. These instructions come AS IS and have NO WARRANTY associated with them in any way. Now that my legal end is covered (as such), we're off to the good stuff.

Prerequisites
This tutorial assumes a decent working knowledge of PowerBuilder, PowerScript, and associated functions. It assumes you either have the full or demo version of FtpDLX installed on your computer correctly and that the ActiveX object is available to PowerBuilder. It also assumes you have a network connection to a local or remote FTP server running the FTP, FTP+SSL, or SFTP protocols.

When using FtpDLX in PowerBuilder, you must use the ActiveX component and not the COM object. This is because of how PowerBuilder uses events from OLE; it can't process events from COM objects except through a default interface. In other words, you don't get direct access to events and handlers when using the COM object, which is very limiting. However, when you insert an ActiveX object onto a window, PowerBuilder incorporates the object's events into the event listing for the OLE object, making it very simple to use.

Steps to Integrate
1.  Create a window in PowerBuilder - any sort will do fine.
2.  Choose an OLE object from the object tool or choose Insert->Control->OLE.
3.  When the Insert Object window opens, choose the Insert Control tab.
4.  Scroll to the bottom and find the wodFtpDLX Class control. Select it. Choose OK to close the window.
5.  Click on the window where you want to put the component. Move it around as you like. Name it something useful (ole_wodftp is my name of choice).
6.  Now you need to choose whether or not you want to use the visual part of this component. If you want to use the visual part of this control, then make the OLE object nice and big and put it somewhere significant on your window. If you don't want to use the visual, make it small and tuck it away in a corner. Make it invisible after your coding is complete, but for now, leave it visible; it's much easier to access the functions, events, and properties if you have something to click on. Also, you can watch the component working with the files and folders for debugging/monitoring purposes.
7.  To refer to the object properties and methods, you'll have to use the full object dot syntax as in: ole_wodftp.object.Property=Setting or for a method, ole_wodftp.object.Method(arg1,arg2).
8.  Now we're ready to set up some properties, invoke a few functions, and handle a few events. You have a lot of flexibility in how you do this: you can have buttons on the screen invoke various events or you can perform the connection, file transfer, and disconnection automatically. This example will show you how to set up the properties and method calls; the rest is up to you. Note: The documents describe pre-defined enumerated constants for various settings, but these aren't (as far as I can make out) available to you inside PowerBuilder. So, you'll have to refer to the settings by their raw value (usually an integer value).
9.  First, you have to set up some standard properties before you connect to the server. I usually put these in the open event of the window:

• ole_wodftp.object.Hostname - A string for the fully qualified hostname or IP address of the FTP server.
• ole_wodftp.object.Login - The login name for the FTP account.
• ole_wodftp.object.Password - The password for the FTP account.
• ole_wodftp.object.Authentication - 1 for password authentication, 2 for certificate authentication, 0 for both (automatic mode)
• ole_wodftp.object.TransferMode - 0 for binary, 1 for ASCII (text mode).
• ole_wodftp.object.Blocking - TRUE to block, FALSE for non-blocking. I highly recommend FALSE since it's darn near impossible to do anything if you can't make your application event-based. Even in an automatic, connect-upload-disconnect application one would want to be able to handle events to show progression and to handle errors.
• ole_wodftp.object.protocol - 0 for the traditional FTP protocol, 1 for SFTP, and 2 through 4 for various forms of FTP+SSL, which are elaborated on in the documentation.
• ole_wodftp.object.Compression - The amount of compression to use in SFTP connections, if applicable; 6 is the preferred number, but you can have a range of 1 to 9. The component will self-negotiate with the server to match compression ratios as necessary.
• ole_wodftp.object.Passive - 1 for a passive connection, 0 for an active connection. Passive is most often used when traversing a NAT firewall.

10.  Connecting: Now you're ready to connect to the server. A simple: ole_wodftp.object.Connect() call will do the trick. Because this is event-based programming, the function will return immediately, even if it's not connected. You'll have to script something in either the "done" or "connected" events of the OLE object or set up a timer to read the state property to determine when it's done.
11.  To access the events, you should be able to just select the OLE object and go to the Events window and pull down a list of all available events. Script away! Helpful events to script include the following: