Getting Started

Use of the Express ActiveX automation objects requires installation of iSeries Access for Windows (V5R2) or Client Access Express on the desktop. The Dynamic Link Library (DLL) containing the code for the Express automation objects, cwbx.dll, is installed as part of the Express base. Therefore, any desktop with Express currently installed may use the Express automation objects. Application developers should install the Express Toolkit, specifically the Headers, Libraries, and Documentation. By installing the toolkit, developers will get context-sensitive help for each of the various ActiveX objects, object properties, and methods. The context-sensitive help contains VB code samples as well as functional information.

To use the Express automation objects in a VB 6.0 application, you must include a reference to the Express object library in your project. The code examples in this article are written in VB 6, so you'll need to follow these steps to run them on your PC. To include the automation object library in your project, click on the Project menu and select References. Scroll down the list of available object references and select IBM AS/400 Client Access Express ActiveX Object Library. Click OK to add a reference to the Express automations to your project. If you are writing a VBA macro in Microsoft Office, you can add the reference by opening the Visual Basic Editor and choosing References from the Tools menu. Now, you are ready to use the Express automation objects.

Exploring the Express Automation Library

IBM iSeries Access for Windows, formerly Client Access Express, has a very robust toolkit to help developers build client applications for the iSeries and AS/400. Information on the ActiveX automation library, including links to code samples, are found in the toolkit. After installation, you can find the toolkit by opening the IBM iSeries Access for Windows or IBM Client Access Express desktop shortcut, opening the Programmer's Toolkit folder, and selecting the icon of the same name. After the toolkit application starts, expand Overview and then Programming Technologies. Then, click on the ActiveX link. In the left pane, you'll see an overview of ActiveX support. You'll also find a link to the complete documentation for the ActiveX automation library.

The automation library was added in the initial release of Client Access Express (V4R4). In this first release, there were ActiveX automations for accessing AS/400 data queues, calling AS/400 server APIs and user programs, managing connections and validating security, running CL commands on the iSeries server, and performing data type and code page conversions. Specifically, programmers could access the AS/400 from the client using objects such as AS400System, DataQueue, KeyedDataQueue, Command, and Program. By calling methods or functions on these objects, they could sign on to an AS/400, read and write records to and from a data queue, and call AS/400 commands and programs. Since the AS/400 typically stores data in different formats than a Windows PC, programmers could also use the data manipulation automations like StringConverter and ZonedConverter to convert data between PC and AS/400 format. All this could be done from a multitude of different programming languages with very few lines of code.

What's New in the ActiveX Library?

In V5R1 of Client Access Express, the ActiveX automation library was expanded. New objects were added that allow software developers to programmatically run data transfers to and from a Windows workstation and the iSeries or AS/400 in many popular file formats. These new objects are referred to as Database Transfer automations. The Database Transfer objects are built on top of the functionality of the Data Transfer application. Therefore, at least base Data Transfer support must be installed to use these new automations. Since Data Transfer is a licensed component, you must also purchase or have a license for the Client Access family of products (5722-XW1) to use the automations.

The new Database Transfer automations provide a programming interface for all of the functionality in the Data Transfer To AS/400 and Data Transfer From AS/400 applications. These new automations have two types of interfaces: A high-level interface is provided to allow quick and easy data transfers with very little coding, and a low-level interface is provided for those who need complete control over their transfers.

The Quick and Easy Way

If all this talk of ActiveX automations and objects has made you a bit sheepish, fear not! The high-level automation interface was designed just for you. The high-level interface has minimal properties (values you can get or set) and methods (functions you instruct the object to perform). The high-level interface also defaults many of the typical behaviors of Data Transfer. Using the high-level interface, you can run a data transfer in as few as two lines of VB code! Figure 1 shows an example of a simple database transfer.

Figure 1: A simple database transfer

The high-level interface consists of one primary object, DatabaseTransfer. The DatabaseTransfer object has the properties Errors, TransferResults, UserID, and Password. The Errors property allows you to retrieve any errors that may have occurred while running a transfer. The TransferResults property allows you to retrieve information about the transfer, such as the completion time and number of records transferred. The UserID and Password properties allow you to programmatically set the user ID and password that will be used to make the connection to the iSeries or AS/400. Setting the UserID and Password properties can eliminate prompting for credentials while a program executes, highly useful when trying to automate a business process.

The DatabaseTransfer object has three simple methods: Download, Upload, and Transfer. Figure 1 shows an example of how to call the Download method. The download method requires you to identify the iSeries or AS/400 system to transfer data from, the server file name in Library/File(Member) format, the PC file name, and the PC file type. The Upload method is very similar. The Upload method requires the iSeries or AS/400 system to transfer data to, the server file name in Library/File(Member) format, the PC file name, and the File Description File (FDF) to use. If an FDF is not specified, the Upload method will assume the system file is a source physical file. The final method, Transfer, is used to run a stored Data Transfer request. The supported request types are the legacy .TTO and .TFR formats and the newer .DTT and .DTF formats. By using program variables, any of the parameters on these methods can be changed at runtime to produce a custom transfer. For example, your program could prompt the user for the name of the PC file to use, but it could have a hard-coded system name, file type, and system file name.

Need More Control?

The Database Transfer low-level interface was designed to give programmers full control over database transfers. Often, when writing a script or application, some setting is required to make the application behave correctly. The low-level interface allows you to do just that. Unlike the single-object, high-level interface, the low-level interface has over a dozen objects that may be used to configure and run a data transfer.

Two types of object interfaces make up the low-level interface. One interface is the download interface. From a client perspective, downloading is sending data to the PC. The other interface is for uploads, or sending data from the client PC to the iSeries or AS/400 server. Each of these interfaces consists of a core object. Each core object contains many smaller objects.

DatabaseDownloadRequest is the core download object. This object contains other objects, such as DatabaseAS400File and DatabaseQuerySettings. These objects are used to modify specific settings in your transfer requests that you are unable to modify with the high-level interface. DatabaseDownloadRequest also contains another object for storing PC file options. This object is based on the PC file type you chose to store your data in. For example, if you chose HTML output, you'd use the DatabaseDownloadHTMLOptions object or, for the Excel file types, you'd use the DatabaseDownloadBIFFOptions object.

To get data to your iSeries or AS/400, the low-level object to use is DatabaseUploadRequest. DatabaseUploadRequest is similar to DatabaseDownloadRequest in that it contains several objects for setting up an upload request. Some of these objects are DatabaseAS400File, DatabaseUploadPCFile, and DatabaseUserLibraryList. These objects can be used to set the AS/400 file name and type to transfer data to, the name of the PC file to transfer data from, and the PC file type. Also, like the download request object, the upload object contains an object for configuring settings based on the PC file type that is being used. When transferring a Lotus 123 file, use the DatabaseUpload123Options. If your file type is ASCII text, modify settings on the DatabaseUploadASCIIOptions object. Figure 2 shows a database transfer that's more complex than the simple database transfer shown in Figure 1.

Figure 2: A more complex database transfer

Configuration objects such as DatabaseAS400File only allow you to set up your transfer requests. Methods on DatabaseDownloadRequest and DatabaseUploadRequest do the real work. The download request object has five methods: Download, LoadRequest, SaveRequest, Cancel, and DownloadAsync. The Download method performs the transfer of data from the iSeries or AS/400 using the settings specified in the request object. The LoadRequest and SaveRequest methods allow you to load and save Data Transfer request files. The Cancel and DownloadAsync methods will be discussed later in this article. The DatabaseUploadRequest has similar methods, including Upload, LoadRequest, SaveRequest, Cancel, and UploadAsync. The Upload method performs the transfer of data to the iSeries or AS/400, and the LoadRequest and SaveRequest methods allow you to load and save Data Transfer requests. Figure 2 shows an example of calling the Upload method using the low-level automations. The Cancel and UploadAsync methods will be discussed shortly.

As you can see from the code examples, not only is the low-level interface more robust than the high-level interface, it is also more flexible. Later in this article, you'll see how to simplify coding to interfaces by using stored Data Transfer requests.

Asynchronous Transfers and Events

Earlier, I mentioned a few low-level interface methods that I did not discuss. These methods were DownloadAsync, UploadAsync, and Cancel. The Async methods are very powerful in that they allow a program to run a transfer request asynchronously in the "background" while other program statements execute. These methods are especially important for single-threaded languages such as VB, in which a single "thread" of program statements can execute at one time. This can be detrimental when building an application with a GUI, where it is bad practice to "lock up" the user interface while a function is performed.

DownloadAsync and UploadAsync allow you to build better GUIs by providing a way to run transfers and, at the same time, free up your GUI to do other work. The Cancel method provides an added bonus by allowing you to stop a long-running asynchronous transfer request or a request that was not responding because of a network problem or some other problem. If you are building a GUI, you could add a Cancel button that is "wired" to the Cancel method, allowing you to easily cancel a transfer from your application. Another typical scenario would be to add a program timer that canceled a request if it was taking too long.

Figure 3: Asynchronous download with events

Another powerful feature of the Database Transfer Async interface is that it provides events. Events are notifications that may be handled by your program to perform some action when something has changed. The events issued by the Database Transfer Async methods are StatusChanged, UploadComplete, and DownloadComplete. The StatusChanged method gets issued anytime the status of a transfer request has changed, and it includes an indicator for row count and transfer status. The row count indicator can be configured to have an event issued each time a number of rows has been transferred. The status flag shows if there was a warning, if there was an error, or if the transfer is still running. In addition to StatusChanged, an application can handle the UploadComplete and DownloadComplete events. These events are triggered when an asynchronous upload or download completes, respectively. Figure 3 shows an example of using the DownloadComplete event to determine when an asynchronous download has finished.

By using asynchronous transfers and events, you can build a very robust GUI to do database transfers. This interface can include status, resulting information, and the ability to cancel the transfer if problems arise.

Simplifying Code with Transfer Requests

The amount of coding required to use the automations can be greatly reduced by using stored data transfer request profiles. Stored transfer requests are simply files that store all the settings for a transfer request. They include things such as the iSeries system name, iSeries file, PC file name and file type, and all the other options configurable through the Data Transfer interface or the low-level automation objects. Transfer requests can be stored on your local PC or accessed from any network server accessible by your PC. They can even be loaded from an iSeries or AS/400 Netserver share.

The high-level interface allows transfers to be run by issuing the Transfer method on your DatabaseTransfer object simply by giving it the name of the transfer request file. The low-level interface gives you even more flexibility. By using the LoadRequest method on the DatabaseUploadRequest and DatabaseDownloadRequest objects, you can quickly load all the settings from a stored transfer request file into your upload or download object. After loading the request, you can also modify any of the transfer request settings before you run the request. For example, your request could have all the configuration information you need except for the columns to include in your output data. Your program could load the stored request, change the Select property on the DatabaseQuerySettings object in the download request object, and then run the download. Another advantage is that you now have the ability to modify the transfer request without modifying your program. This makes it quick and easy to change something like the iSeries system name outside of the program code.

ActiveX=Easy Access

A Client Access Data Transfer user once said, "I don't really like the user interface. Is there anything I can do to change it?" To the user was replied, "With the new ActiveX automations in V5R1, you can easily write your own!" The automation library contains interfaces ranging from easy for the average computer user to implement to more challenging for the seasoned programmer. If your application requires more than just data transfers, ActiveX automations are the answer. The ActiveX automations provided with Express and iSeries Access for Windows also allow you to access data queues, run commands, and do data manipulation. Since the automations are ActiveX-compliant, they can be used many programming languages. Take a look at the ActiveX library, and you'll see how quickly and easily you can run iSeries commands and access iSeries data.


Jeremy Bauer is a Staff Software Engineer at IBM Rochester. He has worked on client database technologies for six years. He is currently the iSeries Access for Windows Data Transfer team leader. Jeremy is also among the ranks of the sleep deprived, pursuing a Master of Science in Software Engineering at the University of Minnesota. He may be contacted via email at This email address is being protected from spambots. You need JavaScript enabled to view it..

Also Read

RPG Academy - Database Modernization: Entity Relationship Diagrams

RPG Academy - Database Modernization: A Bit of Database Theory

Talking About Modernization Isn’t Good Enough