Command-line interaction for IBM i Access Client Solutions
Unleash the product’s full potential
If you have been following the latest news for the IBM i Access family, you have probably heard of IBM i Access Client Solutions. At the time of publishing this article, this product is the newest member of the family, offering platform-independence, flexibility, and simplicity. It uses the same 5733XW1 licensing paradigm as the rest of the product family, and is entitled to anyone with a Software Maintenance (SWMA) agreement.
Running Access Client Solutions is easy. With just a few clicks, you can be connected to your IBM i! While that makes the product very easy to use, "just a few clicks" is not always the right tool for the job.
This article explains and illustrates the command-line usage for the IBM i Access Client Solutions product. Though the notion of command-line usage may sound scary, not all of the tasks outlined in this article are reserved for advanced users. Yes, it does allow for interactive use from a command prompt, but the utility of this knowledge does not stop there. You can write scripts to automate tasks, or use these skills for better desktop integration, such as creating shortcuts to specific functions.
All examples and screen captures in this article are done on a Microsoft® Windows® 7 64-bit workstation. I have downloaded the IBM-supplied zip file (by following the steps provided in this blog) and extracted the contents into the C:\IBMiAccess_v1r1 directory. Though the examples used in this article are oriented for Windows 7, the basic techniques apply to all platforms.
Finding the getting started documentation
Access Client Solutions provides a broad set of functions that you can access from the command line. Most of those, as you can imagine, will not be covered in this article. For a comprehensive and up-to-date list of what's available, you need to reference the "getting started" documentation. This useful set of instructions is included with the product, in a directory aptly named Documentation.
Within this directory, you will find a text file, named GettingStarted.txt, which is the English version. You will also find a number of versions for other languages, named GettingStarted_xx.txt, where 'xx' is a two-digit language identifier. For instance, GettingStarted_es.txt contains the documentation in Spanish.
Figure 1: GettingStarted.txt is available in many languages
Determining your launch command
Before you get started with command-line usage of Access Client Solutions, you must first determine the command that you will be using to start Access Client Solutions. This command serves as the basis for any other command-line tasks you perform. Access Client Solutions can be started with executable launchers or by calling Java™ directly.
Using Access Client Solutions’ executable launchers
Access Client Solutions provide executable launchers for Windows, Linux®, and Macintosh operating systems. They are the preferred means to launch the product because they implicitly set Java performance parameters for you. They also tend to enable better integration with the operating system. For instance, you can open an Access Client Solutions emulator file on Windows by right-clicking the file and then clicking Open With… and browsing to the Access Client Solutions launcher.
The Access Client Solutions product includes these launchers in the Start_Programs directory with Access Client Solutions. The Start_Programs directory contains subdirectories for each platform. On Windows, they can be launched with the following commands, for 32-bit and 64-bit, respectively:
The launchers will scan the system for an appropriate Java runtime environment (JRE), and use that JRE to launch the product. The 64-bit launcher attempts to locate a 64-bit JRE, and a 32-bit launcher tries to find a 32-bit one. Note that 64-bit systems often have a 32-bit JRE available. So, if the 64-bit launcher does not work, try the 32-bit one!
If you know the location of a particular JRE, and you want to instruct Access Client Solutions to use it, you can do so by using the
-vm argument in the command line. For example:
C:\IBMiAccess_v1r1\Start_Programs\Windows_x86-64\acslaunch_win-64.exe -vm "C:\Program Files\Java\jre7"
C:\IBMiAccess_v1r1\Start_Programs\Windows_i386-32\acslaunch_win-32.exe -vm "C:\Program Files (x86)\Java\jre7"
Alternatively, you can choose a specific JRE by setting the
JAVA_HOME environment variable appropriately, making the
-vm option unnecessary.
Running Java directly
You can also invoke the product directly through executables installed with your JRE. This gives us a lot of options. For instance, on a workstation with both 32-bit and 64-bit JREs (installed in their default locations), any of the following commands will work:
java -jar C:\IBMiAccess_v1r1\acsbundle.jar
"C:\Program Files (x86)\Java\jre7\bin\java.exe" -jar C:\IBMiAccess_v1r1\acsbundle.jar
"C:\Program Files\Java\jre7\bin\java.exe" -jar C:\IBMiAccess_v1r1\acsbundle.jar
These examples invoke a Java command, passing the Java-standard
-jar argument to specify the path of a runnable JAR file. Access Client Solutions includes a runnable JAR file suited for this purpose, named acsbundle.jar. The first example invokes the default JRE installed on the PC, the second example fully-qualifies a path to a specific (32-bit) JRE, and the last specifies a complete path to a specific 64-bit JRE.
Should I specify a particular JRE?
Both techniques allow you to explicitly state which JRE to use. Of course, most of the time, it simply does not matter. After all, Access Client Solutions can run on any JRE that is Java 6 or later. Therefore, the typical way to launch the product will be to simply use the executable launchers (without the
You can check or verify which JRE is being used by launching Access Client Solutions and clicking Help -> About from the main panel, as shown in Figure 2.
Figure 2: The About dialog box displays the JRE and product information
Putting it together
After determining your launch command for the product, launching specific functions is easy! Simply append the documented command-line arguments. For instance, the "getting started" documentation says that in order to launch the Data Transfer main window, specify
/PLUGIN=dtgui. So, for example, the full command would be:
You will quickly notice a few important points when invoking specific functions. For one, the command always includes
/plugin= followed by a short name. Access Client Solutions uses a plugin-based infrastructure to deliver functionality, and it is through this infrastructure that command-line invocation is possible. You can also notice that the
/plugin= argument is case-insensitive, meaning, you can specify it in upper-, lower-, or mixed-case.
For those running Access Client Solutions on multiple platforms, you can also notice that the commands are consistent across platforms, with the exception of the launch command. For example, to launch the Data Transfer main window on Linux, the full command might look something like:
Now that you have a basic understanding of how to interact with Access Client Solutions from a command line, let us walk through a few simple examples. In each example, I will reference how the same task would have been done with IBM i Access for Windows, because many users will be migrating from that product.
Example 1: Creating Windows shortcuts to 5250 Session Manager
You likely might already know that IBM i Access for Windows creates shortcuts automatically when the product is installed. However, because Access Client Solutions does not have an installer, this task must be done manually, after the product has been deployed.
The command-line interfaces (CLIs) provide ways to get straight to specific functions within Access Client Solutions. As mentioned earlier, the
/plugin=dtgui option launches the Data Transfer interface. Similarly, you can launch the 5250 Sesssion Manager by using the
This is useful even for those who are not savvy with CLIs, because it enables the user to create Windows shortcuts to the specific function. In order to put a shortcut to the 5250 Session Manager on the Windows desktop, you can follow these easy steps:
- Right-click on the desktop and click New -> Shortcut. This opens the Create Shortcut wizard.
- In the wizard, click Browse and browse to the launcher executable included with Access Client Solutions.
- In the Type the location of the item field, append a space and type /plugin=sm, as shown in Figure 3.
- Click Next and enter a name for the shortcut (for instance, 5250 Session Manager), and click Finish.
Figure 3: The Create Shortcut wizard helps you specify command-line arguments
When these steps are completed, the desktop will have a new shortcut with the name you specified. You can double-click this shortcut to open the session manager.
Figure 4: The 5250 Session Manager, launched from a custom shortcut
Example 2: Using the “ping” function to verify connectivity
This example demonstrates how you can use Access Client Solutions interactively on the command line. IBM i Access for Windows included a utility named,
cwbping. Running this utility verified connectivity to the host servers on the IBM i.
Figure 5: The IBM i Access for Windows “cwbping” command
Access Client Solutions includes a similar function in a plug-in named
ping. To use it, enter the launch command followed by
/plugin=ping /system=<system_name>. You can also pass other options to this command to test connectivity to specific ports, verify SSL, and various other tasks. For more information about the advanced options, see the "getting started" documentation. If not told otherwise, the
ping function verifies non-SSL connectivity to a standard set of host servers.
Figure 6: The Access Client Solutions “ping” plug-in
Example 3: Automating data transfer and remote command tasks
IBM i Access for Windows offered a command-line way to run data transfer requests and remote commands. As such, users can write their own Windows scripts to run these functions in a predefined order.
In this example, you will learn how to write a script that runs a remote command, and then download the database information to a file.
To accomplish this task in IBM i Access for Windows, you can use the
rtopcb commands included with the products. You would place these commands in a .bat or .cmd file with your favorite text editor.
Figure 7: A sample Windows script using IBM i Access for Windows
You can accomplish the same automation with Access Client Solutions.
Access Client Solutions allows you to run remote commands by specifying the
/plugin=rmtcmd command with the
/cmd= option. For example, to call the DTXL/ANALYZE program on a system named lp06ut23, use the following command:
C:\IBMiAccess_v1r1\Start_Programs\Windows_i386-32\acslaunch_win-32.exe /plugin=rmtcmd /cmd="call DTXL/ANALYZE" /system=lp06ut23
Similarly, you can run saved data transfer requests by specifying
/plugin=upload and giving the name of one or more files. For instance, to run three saved download requests, run the following command:
C:\IBMiAccess_v1r1\Start_Programs\Windows_i386-32\acslaunch_win-32.exe /plugin=download transfer1.dtfx transfer2.dtfx transfer3.dtfx
This command downloads the reports from lp06ut23. Note that we do not need
/system=lp06ut23 on the command line because the stored .dtfx file contains the host name (as well as source and destination file names), just as .dtf files do with IBM i Access for Windows. The .dtfx files can be created entirely within Access Client Solutions, or can be migrated from the .dtf files.
So, in order to run a remote command and then run a saved data transfer request, you can put these commands in a .cmd/.bat file, as shown in Figure 8.
Figure 8: A sample Windows script using Access Client Solutions
If authentication is necessary, you will be prompted on the command line. This enables the function to be run even where a user interface may not be available, such as a Telnet or a Secure Shell (SSH) session (this could not have been done with IBM i Access for Windows).
Figure 9: Access Client Solutions can prompt for credentials in your command terminal
These are just some of the ways in which you can use the command-line interfaces to the Access Client Solutions product. Whether migrating from IBM i Access for Windows or using Access Client Solutions on another platform, these interfaces can unlock a powerful set of functionality for platform integration, automation, or interactive use.
For more information, read through the "getting started" information and visit the resources mentioned in this article.
If you are unfamiliar with Access Client Solutions, the following resources provide detailed information about getting started with the product:
- The product web site
- Move your data with Access Client Solutions | Modern-i-zation
- Access Client Solutions Deployment Options | Modern-i-zation
- Access Client Solutions Migration Made Easy | Modern-i-zation
- How do you actually get Access Client Solutions? | Modern-i-zation
- The Access Client Solutions video playlist