Command-line interaction for IBM i Access Client Solutions

Unleash the product’s full potential

In this article, you can learn how to invoke Access Client Solutions from the command line and see the utility through functional examples.

Share:

Jesse Gorzinski (jgorzins@us.ibm.com), Software Engineer, IBM Rochester, MN Labs

Image of Jesse GorzinskiJesse Gorzinski is a developer from the IBM Rochester, MN labs. He has worked on the IBM i Access family of products for a number of years and has been an IBM i professional for over a decade.



03 October 2013

Introduction

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

  • C:\IBMiAccess_v1r1\Start_Programs\Windows_i386-32\acslaunch_win-32.exe
  • C:\IBMiAccess_v1r1\Start_Programs\Windows_x86-64\acslaunch_win-64.exe

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:

  1. java -jar C:\IBMiAccess_v1r1\acsbundle.jar
  2. "C:\Program Files (x86)\Java\jre7\bin\java.exe" -jar C:\IBMiAccess_v1r1\acsbundle.jar
  3. "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 -vm option).

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

C:\IBMiAccess_v1r1\Start_Programs\Windows_i386-32\acslaunch_win-32.exe /PLUGIN=dtgui

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:

/home/ibmr/IBMiAccess_v1r1/Start_Programs/Linux_i386-32/acslaunch_linux-32 /plugin=DTGUI

Functional examples

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 /plugin=sm option.

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:

  1. Right-click on the desktop and click New -> Shortcut. This opens the Create Shortcut wizard.
  2. In the wizard, click Browse and browse to the launcher executable included with Access Client Solutions.
  3. In the Type the location of the item field, append a space and type /plugin=sm, as shown in Figure 3.
  4. 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
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
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
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
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 rmtcmd and 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
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=download or /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
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
Figure 9: Access Client Solutions can prompt for credentials in your command terminal

Summary

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.


Resources

If you are unfamiliar with Access Client Solutions, the following resources provide detailed information about getting started with the product:

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM i on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=IBM i, AIX and UNIX
ArticleID=947153
ArticleTitle=Command-line interaction for IBM i Access Client Solutions
publish-date=10032013