Wed, Jun
4 New Articles

New Data Transfer ActiveX Automations in Express

  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times
In the initial release of Client Access Express, IBM provided a new collection of powerful, easy-to-use automation objects to access AS/400 resources and data. These new objects gave Windows programmers and script writers a simple API to access iSeries and AS/400 data queues, call system APIs and user programs, and run CL commands from many widely used programming languages and applications.

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.

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.

' Visual Basic 6.0 code to run a simple transfer using the high-level interface

' Create new DatabaseTransfer object from the cwbx library
Dim dt As New cwbx.DatabaseTransfer
' Create a variable to easily access transfer results
Dim tr As cwbx.DatabaseTransferResults
' Download QIWS/QCUSTCDT from the server, to the C: drive
' and store it in an Excel (BIFF) 8 file
dt.Download "myiseries", "QIWS/QCUSTCDT", "c:customers.xls", cwbdtBIFF8
' Display the completion time and number of rows transferred
Set tr = dt.TransferResults
MsgBox "CompletionTime = " & tr.CompletionTime & vbCr & _
  "Rows Transferred = " & tr.RowsTransferred & vbCr

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.

' Visual Basic 6.0 code to run a simple transfer using the high-level interface
' Create a new system object
Dim sys As New cwbx.AS400System
' Create a new low-level DatabaseUploadRequest object
Dim upload As New cwbx.DatabaseUploadRequest

' Define the system object and set the user ID and password
sys.Define "myiseries"
sys.UserID = "myuid"
sys.Password = "mypassword"

' Set the System property of the upload request object
Set upload.System = sys

' Set the name of the PC file
upload.pcFile.Name = "c:customers.xls"

' Set the FDF name, to identify the layout of the data in the file
upload.pcFile.fileDescriptionFile = "c:customers.fdf"

' Change the file name to send data to
upload.AS400File.Name = "mylib/customers"

' Change upload creation info to create a new file based on
' QIWS/QCUSTCDT with all authority
upload.AS400File.SetUploadCreationInfo cwbdtCreateFileAndMember, _
                                       "", "", cwbdtObjAuthAll, "QIWS/QCUSTCDT"
' Upload the data to the new file

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.

' Visual Basic 6.0 code to run a simple transfer using the high-level async
' interface.  The GUI is a simple form with two buttons, a cancel button
' and a Run button.  You will need to create the form with VB and plug
' in this code.
' Define the download object and system object at global scope
' The download object must be defined WithEvents to process events
Dim WithEvents download As cwbx.DatabaseDownloadRequest
Dim sys As New cwbx.AS400System

' This is the VB subroutine that is called when the GUI form loads
Private Sub Form_Load()
  ' Create the download request object
  Set download = New cwbx.DatabaseDownloadRequest
  ' Retrieve the default server and use it to initialize the AS400System
  ' object
  sys.Define "myiseries"
  ' Set the System property of the download request object
  Set download.System = sys
  ' Set the server and PC file names for the transfer
  download.AS400File = "qiws/qcustcdt"
  download.pcFile = "c:customers.xls"
End Sub

' Command1 is a button to run the download
Private Sub RunButton_Click()
End Sub

' Command2 is a button to cancel the download
Private Sub CancelButton_Click()
End Sub

' The subroutine to handle the DownloadComplete event
Private Sub download_DownloadComplete(ByVal status As cwbx.cwbdtTransferStatusEnum)
  ' Display the completion status of the request
  If (status = cwbdtStatusCompletedOK) Then
    MsgBox "Transfer completed successfully"
  ElseIf (status = cwbdtStatusCompletedWithWarning) Then
    MsgBox "Transfer completed with a warning"
  ElseIf (status = cwbdtStatusCompletedWithError) Then
    MsgBox "Transfer completed with an error"
  End If
End Sub

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..



Support MC Press Online

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: