These new objects are known as ActiveX automation objects. ActiveX is a technology developed by Microsoft. It facilitates the use and reuse of common objects and controls. ActiveX technology accomplishes this feat by maintaining a defined, standard interface that each object or control must provide. By querying an object, applications can determine the capabilities of the object. This would be like phoning your local carpenter and asking him what types of carpentry work he does. ActiveX is built on top of Microsoft's Component Object Model (COM), which brought about Object Linking and Embedding (OLE). OLE allows application objects and data to be easily linked into other applications. Inserting an Excel spreadsheet into a Word document is a common use of OLE. ActiveX objects work in the same fashion.
ActiveX automation objects are the OLE of the programming world. As easily as you would plug an Excel spreadsheet into Word, you can plug automation objects into development languages such as C++ and Visual Basic (VB). In fact, ActiveX is designed such that any programming or scripting language running under Windows may easily incorporate and use ActiveX objects. Currently, there is support for ActiveX automation objects in Visual C++, VB, Visual Basic for Applications (VBA), Java, VB Script (including Active Server Pages), J Script, Perl, .NET, and many other languages.
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
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
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
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
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.
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