Now you can run ACS Data Transfer features on IBM i
In one form or another, the IBM i Access product has been available for more than 20 years. Initially marketed as PC Support, the product morphed into Client Access, then Client Access for Windows, iSeries Access, System i Access, and now IBM i Access. Through all of those iterations, two enduring features of the product are still the most widely used: 5250 emulation and Data Transfer.
Data Transfer is actually two separate programs—one to download data from IBM i to a variety of PC file formats, and the other to upload data from PC files to IBM i database files. It's safe to say that the Data Transfer download application is one of the most widely used features of the IBM i Access program, given the requirement to get data from IBM i into other applications that run in PC environments. Over the years, IBM i developers have devised many techniques to invoke the Data Transfer program, which runs on a PC, from IBM i. IBM seemingly never thought to provide a version of Data Transfer that could run directly on the IBM i, perhaps assuming that the Copy To Import File (CPYTOIMPF) command (to create CSV-type files) or third-party solutions would fill the gap.
Earlier this year, IBM introduced a Java-based version of the IBM i Access program called IBM i Access Client Solutions (ACS). The target customers for ACS seem to be disgruntled Windows users who insist on using a Java version instead of the IBM i Access for Windows product, Mac users, and Linux users. Because ACS is a Java application, you can also install and run it on the IBM i. This means that you can now run the Data Transfer applications (file download/file upload) on IBM i and take advantage of IBM i batch processes to run Data Transfer programs. This ability might lessen the need for creating and maintaining cumbersome, PC-based Data Transfer mechanisms, which traditionally use remote command features.
The files that ACS produces (file download) or consumes (file upload) by using this technique are located in the IFS, along with the Data Transfer description files (file extensions .dtfx and .dttx). You can use a workstation-based version of ACS or the traditional IBM i Access for Windows Data Transfer programs to develop the Data Transfer applications. After creating and saving the description files on your workstation, you copy the description files to the IFS. When you run the Data Transfer programs on IBM i, you reference the description files.
In the article "Client Access on a Stick," IBMer Tim Rowe makes the following statements regarding the new IBM i Access Client Solutions (ACS) offering from IBM: "The product is really a set of .jar files that can be deployed on any system that supports Java. This means that you can run ACS on Windows, Apple Mac, Linux, and yes, even your IBM i." Rowe's article points you to the IBM website, where you can download ACS, and helps you install ACS on your workstation. You don't need to know the Java programming language to install, configure, and run the Data Transfer programs on IBM i.
IBM i Prerequisites
To run the ACS code on IBM i, you must have Java 6 or later on your system, referred to as the IBM Developer Kit for Java (Licensed Program Product [LPP] 5761-JV1). In my tests, I used LPP 5761-JV1 option 11, the 32-bit version of the Java 6 standard edition product.
Run the Data Transfer Download on Your Workstation
The simplest and quickest way to get started with the Data Transfer program is to install it and verify that the download works on your workstation. Verifying that the Data Transfer program works on your workstation takes only a few minutes. In addition to running Data Transfer interactively on your workstation, you can run it using the java command. You'll use that same java command when you run the Data Transfer program on IBM i.
For the first test, start the Data Transfer program and download a small database file to your workstation. Figure 1 shows the Data Transfer dialog box.
Figure 1: Data Transfer dialog box
If you've used IBM i Access for Windows Data Transfer, the new Data Transfer program will be familiar to you.
Save the Data Transfer Download Request
After you run the Data Transfer download test, save the Data Transfer request so that you can copy the saved request file to your IBM i system. In the Data Transfer dialog box, select File, Save As and save the file with a name of your choice. The file that you save will have the extension .dtfx (Data Transfer From—the transfer direction is in relation to IBM i).
Run the Data Transfer from a Command Line
Now that you have a saved Data Transfer request (.dtfx), you can run the transfer on your workstation by using a java command line. You'll also use this technique when you run the Data Transfer program on IBM i.
Open a command prompt and enter a command similar to the following. In the command, the program file is installed in the IAC directory (the acsbundle.jar file). The IACXFER directory contains the saved Data Transfer request file, and the /PLUGIN switch identifies the feature that you want to use (Data Transfer download).
Figure 2 shows an example of how to enter the command in the command prompt.
Figure 2: Entering the command in the Command Prompt window
Running the command for the saved Data Transfer description writes the .csv file that you specified as the output file to a directory on your workstation.
Install the IBM i ACS Program on the IBM i
Now that you've tested the Data Transfer download on your workstation, you can install the code on your IBM i system. To do so, install the acsbundle.jar file into a directory in your IFS. In my tests, I created three IFS directories (Figure 3).
Figure 3: Three IFS directories
The IAC directory contains the IBM i ACS .jar file, the IACOUT directory is where I want the downloaded file to be written to, and the IACXFER directory contains the .dtfx file that describes the Data Transfer request.
After you create the directories in the IFS, locate the directory on your workstation that contains the acsbundle.jar file. That directory also contains the AcsConfig.Properties file. Copy both of these files from your workstation to the IFS directory. You can use any technique you prefer to copy the files; for example, you can copy the files from Windows Explorer and paste them to IBM Navigator for i, or you can send the filesfrom your workstation to the IFS via FTP.
Change the Directories in the Saved Transfer Description File
The saved .dtfx file on your workstation uses directories on the workstation. To use the transfer description on IBM i, you must change the workstation directories to directories that are in the IFS.
On your workstation, open the .dtfx file in a simple text editor (e.g., Notepad). Figure 4 shows the contents of a .dtfx file.
Figure 4: The .dtfx file contents
Before making any changes, select File, Save As to save the file with a different name but the same .dtfx extension. Saving the file with a new name lets you retain the original file on your workstation.
In the editor, change the values of the ClientFile and the Field Description File (FDFFile) items to point to the IFS directories (the FDFFile directory value might be blank). TheFDFFile is required only if you intend to subsequently perform a Data Transfer upload from the file that you downloaded (e.g., if you download to an Excel file, make changes to the data in the workbook, and then upload back to the IBM i database file).
Figure 5 shows an example of the changes that I made to my .dtfx file (although I added blank separator lines between each section, you don't have to do so).
Figure 5: Displaying changes to .dtfx file
After making your changes, copy the revised .dtfx file to the IFS directory that you created to contain the transfer description file.
Configure a VNC Server to Work with the Data Transfer Program
IBM i ACS is designed for use in a workstation environment, which provides a graphical user interface (GUI). When you run the ACS programs, the Java code in the product displays status messages and dialog boxes by using Java GUI features.
However, when you run the ACS Data Transfer program on IBM i, the platform provides no support for the Java GUI. If you simply try to run the Data Transfer program on IBM i, it ends in error. In some cases, you can run Java code on IBM i and indicate that you don't want to use the GUI. This technique is referred to as running in headless mode. You can find a description of that mode in the IBM Developer Kit for Java documentation in the section "Running your Java application on a host that does not have a GUI."
Ideally, ACS programs would have the ability to use headless mode—simply add a command-line parameter to the java command (java.awt.headless=true). Unfortunately, even if you add that parameter value to the java command, the program ends in error. The alternative is to use what IBM calls the Native Abstract Windowing Toolkit (NAWT), which is also described in the IBM Developer Kit for Java documentation in the same section.
The ACS programs will run on your IBM i when you configure NAWT. You obtain NAWT support by using the Virtual Network Computing (VNC) server that's part of the IBM Tools for Developers LPP—a free download from IBM. The VNC server runs in the IBM i Portable Application Solutions Environment (PASE), which provides support for running AIX applications in the IBM i environment. After installing and configuring the VNC server on IBM i, you'll work with a VNC viewer on your workstation. When you use the ACS Data Transfer program, the output of the program is directed through the VNC server to the VNC viewer.
Although it might sound complicated to work with the tools, it's not terribly difficult to install and configure them. Once you've configured the VNC server and VNC viewer, you can use the ACS Data Transfer programs directly on your IBM i. The process of downloading, installing, and configuring the VNC server consists of many steps. For complete, illustrated documentation for those procedures, see the step-by-step guide at tinyurl.com/RunACSXferOnIBMi.
Start the Data Transfer Program on IBM i
Once you have the VNC server installed, configured, and operational on IBM i, and you have the VNC viewer open on your workstation, you can run the Data Transfer program on IBM i. The ACS Data Transfer program uses two environment variables called DISPLAY and XAUTHORITY. The values of each environment variable point to the VNC server and its configuration. Enter the following commands on a 5250 command line:
ADDENVVAR ENVVAR(DISPLAY) VALUE(ꞌibm_i_host_name:vnc_instance_numberꞌ)
ADDENVVAR ENVVAR(XAUTHORITY) VALUE(ꞌ/home/user_profile_name/.Xauthorityꞌ)
The values that you specify for the environment variables are more fully defined in the step-by-step guide previously mentioned.
The important point to remember about environment variables is that they're not "persistent"—once you sign off your 5250 session, the values are gone. When you start a new 5250 session, you must add the environment variables again. If you plan to frequently use the Data Transfer programs on IBM i, consider adding the ADDENVVAR statements to a startup program that runs when you start a 5250 session.
To run the Data Transfer download in a 5250 job, use a java command that's similar to the one you tested earlier at your workstation. You can run the java command by using either the Start QSH (QSH) command or the Run Java Program (RUNJVA) command.
Use the QSH Command to Invoke the Data Transfer
To use QSH to run the java command, enter the QSH command. You can provide the CMD parameter for the QSH command, which will contain the following java command. Alternatively, you can simply enter QSH and then enter the java command in the QSH command entry panel. The java command that you enter for QSH looks like this:
Note that you enter the command on one line (although I show it wrapped here).
The java command might take a few seconds to start. When you initially run the Data Transfer program, you should see the End User License Agreement displayed in the VNC viewer, as Figure 6 shows.
Figure 6: End User License Agreement in the VNC viewer
After you accept the agreement, the Data Transfer program prompts you for your IBM i user ID and password in the QSH Command Entry panel, similar to what you saw when you ran the Data Transfer on your workstation. Your acceptance of the agreement, user ID, and password are cached. The next time you run the Data Transfer program on IBM i, you won't need to use the VNC viewer or enter your user ID and password (the user ID is passed as a parameter on the java command that invokes Data Transfer). Because you don't have to interact with the Data Transfer program when you run it, you can create batch jobs that invoke the Data Transfer. Figure 7 displays the Data Transfer download output as it appears in the QSH Command Entry panel.
Figure 7: Data Transfer download in QSH Command Entry panel
Use the RUNJVA Command to Invoke the Data Transfer
As an alternative to using QSH, you can use the RUNJVA command to invoke the Data Transfer program. The RUNJVA command uses the traditional IBM i command parameter style, so you might find it easier to work with the RUNJVA command instead of QSH. The following command string shows the RUNJVA command that's equivalent to the previous QSH command.
Submit a Data Transfer Request to Batch
You can run a Data Transfer request as a batch job to make it easier to create automated Data Transfer requests. You can use either the QSH or the RUNJVA commands to submit a batch Data Transfer. The following example shows how to submit the QSH command. Note that you enter the CMD parameter on one line (although I show it wrapped here):
This is an example of submitting the RUNJVA command:
Note that for both versions of the submit command, you must enter the value *YES for the CPYENVVAR (Copy Environment Variables) parameter so that the values of the DISPLAY and XAUTHORITY environment variables will be passed to the batch job.
A Whole New Way to Use Data Transfer
For years, many IBM i developers have had to devise elaborate solutions to automate data transfers, using remote command operations to drive the Data Transfer program running on a workstation. By creating a Java version of the Data Transfer applications, IBM has provided an entirely new way to use this feature. Data Transfer is no longer tied to a workstation environment.
So before you spend more time working with workstation-based Data Transfers, consider running the new IBM i ACS Data Transfer on your system. And be sure to download a copy of the step-by-step manual Run IBM Access Client Solutions Data Transfer on the IBM i.