The QuickStartGuide contains instructions for deploying the product that will work for most users running Windows, Mac or Linux. To install this product for a single user, or for a multi-user PC, see the QuickStartGuide in the Documentation folder.
Additional details about the product, other deployment options and customizing the product are included in the remainder of this document.
IBM i Access Client Solutions is the newest member of the IBM i Access family of products. It provides a Java based platform-independent interface which runs on most operating systems that support Java including Linux, Mac and Windows. IBM i Access Client Solutions consolidates the most commonly used tasks for managing your IBM i into one simplified location.
IBM i Access Client Solutions uses the same IBM i host servers as the other IBM i Access Family products and requires the same IBM i Access Family license (5770XW1) in order to use the 5250 emulation and Data Transfer features.
Also available are two optional packages which include middleware for using and
developing client applications for Windows and Linux:
IBM i Access Client Solutions - Windows Application Package
IBM i Access Client Solutions - Linux Application Package
Customers using IBM i 7.2 or later that have current entitlement can acquire IBM i Access Client Solutions by either of the following two methods:
The optional Windows and Linux application packages are available from the Entitled Software Support (ESS) website.
Customers can acquire media by ordering 5761-SS1 or 5770-SS1 refresh feature 6288. The physical media contains a runnable version of the product which allows you to run the product directly from the CD. The physical media also includes a zip archive of the product which can be copied and extracted to a location of your choice. The physical media for IBM i Access Client Solutions does not contain the optional Windows and Linux Application Packages.
For additional information visit:
IBM i Access Client Solutions
For the latest information about IBM i Access Family products visit:
IBM i Access Family
Features of IBM i Access Client Solutions include:
The optional Windows Application Package includes:
The optional Linux Application Package includes:
IBM i Access Client Solutions will run on most operating systems that support
Java 8.0 or higher including various versions of Linux, Mac and Windows.
Note: ACS may not be able to locate Java 8 on macOS 11.0 Big Sur. We recommend installing Java 11.
Recommendation:
Keeping your version of Java at the most current version will make sure you have
all the latest fixes and security patches.
One way to check the version of Java installed on your system is to bring up a
prompt where a command may be entered (Command Prompt, Shell, Terminal, etc) and
then type the command:
java -version
The following output indicates version 8.0 is installed:
java version "1.8.0_191"
The 191 in this example refers to the update level.
Here are some web sites of Java providers. Make sure you are running with the
most up-to-date version of Java for your platform.
https://adoptopenjdk.net/
https://aws.amazon.com/corretto/
http://openjdk.java.net/install
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
http://www.oracle.com/technetwork/java/javase/downloads/index.html
Tech Note for Mac:
When installing Java on Mac, select a JDK instead of a JRE. The JRE for Mac installs Java for only the browser.
It does not install Java for other applications. Installing the JDK will make Java available to other
applications such as IBM i Access Client Solutions.
IBM i Access Client Solutions will connect to any supported IBM i release.
IBM i Access Client Solutions uses the same IBM i host servers as the other IBM i Access Family products and requires the same IBM i Access Family license (5770XW1) in order to use the 5250 emulation and Data Transfer features.
If you will be using SSL connections, load and apply the following IBM i
PTFs for your release:
7.2 - SI55392, SI57320, MF60333, MF60334
If you will be using Navigator for i, load and apply the appropriate IBM i
PTFs for your release:
7.2 - Group PTF SF99713 level 30 or higher
7.3 - Group PTF SF99722 level 17 or higher
The following files and directories are contained in the product zip archive:
acsbundle.jar - an executable jar file of the product
AcsConfig.properties- file containing configuration settings (also exists
inside acsbundle.jar)
Mac_Application - directory containing install script for Mac
Linux_Application - directory containing install scripts for Linux
Windows_Application - directory containing install scripts for Windows
Start_Programs - directory containing platform specific binary files which
can be used to start the product.
Linux_i386-32
Linux_x86-64
Mac_i386-32_x86-64
Windows_i386-32
Windows_x86-64
Documentation - directory containing documentation
QuickStartGuide - information for how to get started
GettingStarted - detailed information about the product
License - directory containing terms and conditions for usage
Notices - directory containing notices and information
properties - directory containing product version information
Sample_Scripts - directory containing sample scripts which can be used to
start the product if the binary files in Start_Programs
do not work.
Linux_Mac_Other - directory of perl scripts for starting the product
on any platform where perl is available.
Windows - directory containing a JScript for starting on Windows
Icons - directory containing files which can be used as icons
Fonts - directory where additional monospaced fonts may be
added for 5250 emulation
The packaging of IBM i Access Client Solutions provides several installation options from the very simple single user installation, to the more advanced multi-user installations.
Installation scripts have been provided in the Mac_Application, Linux_Application, and Windows_Application folders (see section 4.0 Product Contents) which can be used for a variety of installation options.
For a single user installation on Mac, Linux, and Windows, or a multi-user installation on a Windows PC, see the QuickStartGuide. The QuickStartGuide explains how to use the provided installation scripts for doing these types of simple installs.
If you are an administrator planning on deploying this to several users, you will want to read
the following articles:
IBM i Access Client Solutions: Customization and deployment made easy
IBM i Access Client Solutions: Customization and deployment questions answered
These articles explain how an administrator can pre-customize the installation for multiple users prior to deployment by
using the /AdminConfig option supported by the installation scripts.
For administrators that would like to automate the install in silent mode, use the /AdminConfig
parameter to pre-configure the installation. Then use the /Q parameter during the actual installation. For Example:
Windows_Application\install_acs_64.js /AdminConfig
Windows_Application\install_acs_64.js /Q
In addition to the above options, you also have the option of just unpacking the zip archive to any location of your choice. This can be any location where the workstation has read authority to access the files. This includes the local hard disk drive, a remote network (shared) drive or portable media such as a CD or USB flash drive. Unpacking the zip archive completes the installation.
Technical Note:
Some archive utilities do not preserve all the saved file attributes. For
example, on Mac and Linux platforms, the unzip command is usually a better choice
than the jar command. For additional information, see section 6.0 File
Permissions.
Enhancements and fixes will be made available on a periodic basis. These updates are provided as a complete product installation. When these updates are available, you will need to update your existing installation.
For users maintaining their own installation:
Option 1:
To update an existing installation that was installed by using the installation scripts,
extract the contents of a newer version of the product. Invoke the installation script from this
new version in the same manner as was done during the initial installation. This will update the
product files without changing the existing configuration.
Option 2:
If you chose to install the product without using the installation scripts by extracting the
contents of the zip archive to some location of your choice, then to update the product, you will need
to extract the contents of the newer version of the product over the top of the existing version.
Keep in mind, you may need to save and restore the contents of AcsConfig.properties if you made custom changes to it.
For administrators maintaining a version of the product in a central location accessed by multiple users:
Extract the contents of the newer version over the top of the existing version.
If you have made custom changes to the AcsConfig.properties file, you will want
to save AcsConfig.properties before extracting the contents of the new version of the product over
an existing version. After you have extracted the contents of the new version of the product and
have restored AcsConfig.properties, your users will need to take one of the following options:
Option 1:
If the users are running directly from the remote location, no further action is needed. Have them restart
the product to pick up the new updates.
Option 2:
Run the install script in the same manner as the initial installation to update the local installation.
Option 3:
If you have set up an IBM i Update Location, section 5.2, have your users select Help->Check for Updates from the main GUI.
A panel should appear telling them an update is available. Have them select Install Update. This option may also be run from the command line
using the INSTALLUPDATES plugin.
After following the appropriate steps above, restart the product. Help->About from the main GUI can be used to verify the updates were applied.
Administrators can use an IBM i system as their central location for doing installs and applying updates. Regardless of how you initially deploy the product to your users, you can use a central location on an IBM i so that your users can apply an update with a click of a button. Here are the steps:
com.ibm.iaccess.CheckUpdateSystem=system_name (see Note 1 below)
com.ibm.iaccess.CheckUpdatePath=/path_where_zip_was_extracted (see Note 2 below)
Setting the com.ibm.iaccess.CheckUpdateSystem property causes Help->Check for Updates to behave differently. Instead of checking an external web location for the availability of an updated version, the above IBM i location will be checked for updated product files. An update will be detected when the timestamp of any required product file changes. The timestamp will be displayed on the Help->Check for Updates panel with an option to install the update.
The user will need valid credentials to the system specified for com.ibm.iaccess.CheckUpdateSystem. If their credentials have not already been cached from a previous connection to this system, they will be prompted to provide valid credentials. Failing to provide valid credentials will result in updates not being detected.
Users that have an IBM i Update Location configured and have selected the option "Notify when update is available" under Edit->Preferences, will not be prompted to provide credentials. They will only get notified of an available update if they have successfully connected to the com.ibm.iaccess.CheckUpdateSystem since the last time they logged into their PC.
Note:
Special note for administrators that maintain a customized AcsConfig.properties file within acsbundle.jar:
This feature downloads the acsbundle.jar that exists on the IBM i at the specified location. No special processing is done to maintain a customized version of
the AcsConfig.properties file during an update. If you have previously customized the AcsConfig.properties file inside acsbundle.jar,
you will need to make sure the new version of acsbundle.jar contains your desired customizations before making it available for download.
For Administrators that want to maintain a centralized location on an IBM i for their users to install and update the product,
release-specific PTFs are available that will provide the extracted contents of IBMiAccess_v1r1.zip at:
/QIBM/ProdData/Access/ACS/Base
The initial PTFs are:
V7R4M0 SI73595
V7R3M0 SI73596
V7R2M0 SI73599
These PTFs will be superseded for each product update and will normally be available within 2 weeks of the availability of the product update.
Section 7.0 Starting the Product describes several different ways to start IBM i Access Client Solutions. If you will be using one of the provided binary files or scripts to start the product, you will need to make sure its file permissions have the execute permission enabled. The file permissions assigned while unpacking the zip archive file are determined by several factors including the operating system, the archive utility used to unpack the zip archive, the authority of the user, etc.
If you have trouble using one of the provided binary files or scripts, check the file permissions. The following sections describe some methods for checking the file permissions.
For unix-like operating systems, you can use the following command from a shell
or terminal prompt to check the permissions of a file:
ls -l <file>
To change the permissions of a file, you can use the following command:
chmod <permission> <file>
chmod a+rx <file>
to give the owner of the file read/write/execute permission and only read/execute
for everyone else:
chmod 755 <file>
Additional help for the ls and chmod commands is readily available on the internet.
For Windows, while viewing the file using Windows explorer, right-click the file and select properties. The security tab should contain the file permissions. Make sure you have Read and Execute permission.
On recent versions of Windows, you may also use the icacls command to view and change the permission of a file.
There are multiple ways to start IBM i Access Client Solutions. If you used the installation scripts to install the product, the easiest way to start the product is found in the QuickStartGuide.
If the product was not installed using the installation scripts, the remainder of this section will describe alternative ways to start the product. Since there are a variety of ways and locations how/where java can be installed, some of the methods may require additional configuration. If one of the methods below does not work, try a different method. In some cases, additional guidance is provided. You may also find section 11.0 Frequently Asked Questions (FAQ) helpful.
When using a binary file or script as described below, the binary file or script must be in the same directory structure as contained in the zip archive. For convenience, you may also copy/move the binary file(s) and/or scripts for your platform(s) to the same directory where the acsbundle.jar exists.
To start the product from a file viewer (e.g. Windows Explorer, Mac OS X Finder, etc) using a platform specific binary file, locate the sub-directory in Start_Programs that identifies your operating system and hardware architecture.
Locate the binary file your operating system recognizes. Then double-click it to start the product. You may also start the product with this binary file from a Command Prompt, Terminal, or Shell.
If you get the following error:
"Error loading Java module."
IBM i Access Client solutions could not find a java installation in a
location it recognizes. You may try one of the following methods in sections:
7.1.1 Starting the Product - Additional Options
7.2 Starting the Product (using a script)
7.3 Starting the Product (using the command-line)
You may also try one of the following methods when trying to use the binary file for your platform. These methods allow you to identify which Java Runtime Environment (JRE) should be used to start the product. See section 7.1.2 Finding the Java Home Path for how to locate the Java home path on your workstation. These additional methods are only supported on Linux and Windows platforms:
If you can start the product using one of the methods in section:
7.2 Starting the Product (using a script) (OR)
7.3 Starting the Product (using the command-line)
then you can determine the java home path on your workstation from the
IBM i Access Client Solutions main GUI. On the menu bar, select
Help->About
The java.home path is displayed on this panel.
The java.home property contains the location of the java home path for your workstation. This is the path you will need to specify when setting the JAVA_HOME environment variable or when using the -vm option on the command.
On Windows platforms, search for java.exe. The java binary is normally located in either a bin or jre/bin sub-directory below the Java home path. The Java home path may be used when setting either the JAVA_HOME environment variable or when using the -vm option on the command.
On linux you can use the "which" command:
which java
This will give you a path to the java command or a symbolic link to it.
Resolve any symbolic links until you finally get to the actual binary file
for the java command. You can resolve symbolic links by using the ls
command with the -l option:
ls -l <file>
The java binary is normally located in either a bin or jre/bin sub-directory
below the Java home path. The Java home path may be used when setting either
the JAVA_HOME environment variable or when using the -vm option on the command.
There is a Sample_Scripts directory in the Documentation directory.
The preferred way to start the product is by using a platform specific binary file available in Start_Programs. The scripts in Sample_Scripts should only be used if the platform specific binary does not work.
To start the product from a file system browser (e.g. Windows Explorer, Mac OS X Finder, etc) using one of the supplied scripts, locate the script in the Sample_Scripts sub-directory that is compatible with your operating system.
Most non-Windows based operating systems have perl available by default. The Sample_Scripts/Linux_Mac_Other directory contains a perl script (with three different file extensions) which can be used to start the product on any platform where perl is available. Select the file that has a file extension that your operating system will recognize as a perl script.
Windows based operating systems have JScript available by default. The Sample_Script/Windows directory contains a JScript that can be used to start the product on Windows operating systems.
Using a platform specific method to browse your file system (e.g. Windows Explorer, Mac OS X Finder, etc), locate the script your operating system recognizes. Then, double-click it to start the product. You may also start the product with this script from a Command Prompt, Terminal, or Shell.
You may also start the product from the command-line from any place you can
enter a command (Command Prompt, Terminal, Shell, etc)
java -Xmx1024m -jar <path>/acsbundle.jar
where <path> is the location to the product's executable jar file
java -Xmx1024m -jar V:/some_location/acsbundle.jar
or
<java_path>java -jar V:/some_location/acsbundle.jar
where <java_path> is the location of the java command for JDK 8.0 or higher.
See section 7.1.2 Finding the Java Home Path for determining the complete path to the java command.
You may also use any of the programs or scripts from the command-line. For example:
/Product/Location/Start_Programs/Linux_x86-64/acslaunch_linux-64
/Product/Location/Start_Programs/Mac_i386-32_x86-64/acslaunch_mac
C:\Product\Location\Start_Programs\Windows_x86-64\acslaunch_win-64.exe
Technical Note:
On most platforms, the Java Virtual Machine heap space defaults to a maximum
size that is too small to utilize multiple functions within the IBM i Access
Client Solutions product. A one gigabyte maximum heap size (-Xmx1024m) is
the recommended minimum size. Specifying sizes smaller than one gigabyte or
using the default heap size may produce an OutOfMemoryException.
Add a system configuration for each IBM i system you want to use or manage. To add a system configuration, select System Configurations from the Management tasks. Then select New. On the General tab, enter the System name. To get started, the System name is all that is necessary for performing General tasks.
When you have finished, select OK to save the information you entered for this system, or select Save/New if you have additional systems you would like to add to the configuration.
You may add new systems to your configuration or update existing configurations using the General, Connection, or the Console tabs at any time.
For Console tasks, additional configuration is required. Console configurations are automatically associated with the System name you entered on the General tab. To enter the console configuration for a system, select System Configurations from the Management tasks. Select New or Edit. Then select the Console tab. The 5250 Console task requires a configured LAN console or a configured HMC console. If you do not have a configured LAN or HMC console, see section 9.9 Establishing a Console Connection to IBM i.
The Hardware Management Interface task requires a configured hardware management interface. You may enter up to six hardware management interface configurations.
When you have finished, select Close on the System Configurations panel.
Using the System drop-down box on the main IBM i Access Client Solutions panel, select a System. All Console tasks automatically associate the selected System (entered on the General tab) with the console configuration (entered on the Console tab).
You may now select a task for the selected system. If you select a Console task which does not have the corresponding information entered on the Console configuration tab, an error message will be displayed.
By default, each user will have their own unique location for their
configuration. The configuration root directory is determined in a platform
dependent manner. The configuration directories will be created during the
initial start-up. To see where the configuration directory is:
Start the product (see section 7.0 Starting the Product)
Edit->Preferences
Select the Local Settings tab
Configuration Root
The configuration location cannot be changed while the product is running. To change the location of the configuration, see section 9.3 Changing Configuration Location
Many of the functions that are available from the main GUI are also available
from the command-line. These functions may be invoked by providing the
appropriate parameters to any of the command-line options shown in:
section 7.3 Starting the Product (using the command-line)
For example:
Start_Programs\Windows_x86-64\acslaunch_win-64.exe parm1 parm2 ...
Only the additional parameters will be shown in the following sections:
/PLUGIN=backup [/file=<filename>]
<filename> is the name of the file to be created
This will save the current configuration to the specified file. The resulting file may be used as input to the Restore command-line option on the same or different workstation (regardless of operating system).
The location of the configuration to be saved is determined by the property:
com.ibm.iaccess.AcsBaseDirectory
...which is located in the AcsConfig.properties file.
This function is equivalent to File->Export Configuration from the main GUI.
/PLUGIN=restore /file=<filename>
<filename> is the location of the file created by Backup
This will restore a saved configuration from the specified file. Any existing
configuration not in the specified file will be lost.
The location of the restored configuration is determined by the property:
com.ibm.iaccess.AcsBaseDirectory
...which is located in the AcsConfig.properties file.
This function is equivalent to File->Import Configuration from the main GUI.
Note:
To avoid importing the default user name specified on the Connection tab of a System Configuration,
place the following property in the AcsConfig.properties file.
com.ibm.iaccess.ResetDefaultUserOnImport=true
/PLUGIN=certdl /SYSTEM=<system>Downloads a certificate authority (CA) from the specified IBM i system and stores it in the user's local trust store. This is required for server authentication with SSL.
/PLUGIN=cfg /GUI
/GUI - this option will start the System Configurations GUI
This is equivalent to launching System Configurations from the main GUI.
Note: Setting com.ibm.iaccess.CfgActionsRestricted=true in AcsConfig.properties
will hide the New/Edit/Copy/Delete buttons on the System Configurations panel.
/PLUGIN=cfg /LIST
/LIST - list configured systems with their connection options
/PLUGIN=cfg /SYSTEM=<system> [/ipaddr=<frequency>] [/userid=<userid>]
[/ssl=<switch>]
[/5250path=<path>]
[/del] [/r]
/SYSTEM - name of the system
/ipaddr - when a connection is requested, this value determines whether
or not a lookup of the IP address will occur. Valid frequencies
are:
ALWAYS - lookup IP address for each connection
HOURLY, DAILY, WEEKLY - lookup IP address if the amount of
time has elapsed since the last lookup
IP address - if an IP address is specified, the lookup
frequency is assumed to be NEVER
/userid - user id for a user
may also be set to the following values:
*SHARE - prompts once for logon credentials that
will be shared by systems using this option
*PROMPTALWAYS - prompts at least once for each connection
*KERBEROS - use Kerberos principal name, no prompting
/ssl - switch is 0 to turn SSL mode off, or 1 to turn it on
/5250path - path to 5250 emulation profiles
The /5250path may be set by File->Change Directory... from
5250 Session Manager
/del deletes existing configuration
/r replaces existing configuration
This allows various configuration options to be set from the command-line.
These options may also be set from the main GUI using System Configurations.
/PLUGIN=dump [/<options>]Requests all running processes within the product to dump their threads. This information will be used by IBM service to provide problem support.
The logs generated may be accessed from the main GUI by:
Edit->Preferences
Local Settings tab
Dumps Directory
If no options are specified, this function is equivalent to the following
function from the main GUI:
Tools->Generate Service Logs
Valid options are:
/heapdump - performs the above plus a dump of the JVM heap
/PLUGIN=medicPackages up the existing logs and thread dumps into a zip file that can be sent to IBM for service.
The resulting zip file may be accessed from the main GUI by:
Edit-Preferences
Local Settings tab
Service Directory
This function is equivalent to Tools->Package Service Logs from the main GUI.
/PLUGIN=log /LEVEL=<Level>
<Level> is one of the following:
OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINEST
This plugin enables the user to toggle their logging level from the command-line.
The logging level may also be set from the main GUI by:
Edit->Preferences
General tab
Logging level
/PLUGIN=logon /SYSTEM=<system> [/USERID=<userid>] [/PASSWORD=<password>] [/AUTH] [/C] [/GUI=<1|0>]
/SYSTEM - name of system
/USERID - user id
/PASSWORD - password associated with the user id
/AUTH - attempts connect to system with specified logon credentials
and only caches them on success
/C - clears the cache
/GUI - whether or not a graphical user interface can be used
This command will cache the user id and password which can be used to prevent
password prompting.
/PLUGIN=propsBrings up the same GUI panel as Edit->Preferences from the main GUI.
/PLUGIN=maint [/<options>]
Valid options are:
/killdaemon - ends daemon threads.
Same as Tools->Reset for Maintenance from main GUI.
Setting com.ibm.iaccess.ResetForMaintenanceOnExit=true in AcsConfig.properties
will call /killdaemon when Access Client Solutions exits.
/clearpwcaches - clears all cached passwords
/clearjarcache - clears the product jar cache
/clearlogs - clears the Logs Directory at Edit->Preferences
Local Settings tab from the main GUI
/cleardumps - clears the Dumps Directory at Edit->Preferences
Local Settings tab from the main GUI
/clearsvcdir - clears the Service Directory at Edit->Preferences
Local Settings tab from the main GUI
/clearsettings - clears all settings for current user
If no options are specified, no actions will be performed.
/PLUGIN=ping /SYSTEM=<system> [</options>]
Options include:
/SSL=<1|0> Turn SSL on or off
/ACCEPTALLCERTS=<1|0> Whether or not to automatically add all SSL
certificates to the trusted set (when using SSL).
/SERVERAUTH=<1|0> Turn SSL Server authentication on or off (default is
off). This option is disregarded if not testing SSL.
/GUI=<1|0> Toggle GUI window on/off (default is off if launched
from command-line)
/PORTS=<port1,port2> A comma-separated list of ports to test. It can be
numbers or service names (e.g. /PORTS=as-signon,as-sts). If not
specified, a default set of ports is tested.
Specifying .CONSOLE will check a list of console specific ports.
/TIMEOUT=<seconds> Specify a timeout value, in seconds.
This plugin checks the connectivity to the IBM i by opening a connection to the
appropriate port. If verifying an SSL connection, an SSL handshake is attempted.
If it is launched from the main GUI, or invoked with /GUI=1, this plugin displays
a dialog. If launched from the command-line without /GUI=1, output is sent to
the console.
For non-SSL, the following services and ports are checked:
sshd 22
telnet 23
drda 446
as-svrmap 449
as-nav 2004
as-central 8470
as-database 8471
as-dtaq 8472
as-file 8473
as-netprt 8474
as-rmtcmd 8475
as-signon 8476
For SSL, the following services and ports are checked:
sshd 22
telnet-ssl 992
ddm-ssl 448
as-svrmap 449
as-nav 2005
as-central-s 9470
as-database-s 9471
as-dtaq-s 9472
as-file-s 9473
as-netprt-s 9474
as-rmtcmd-s 9475
as-signon-s 9476
This function can be launched from the main GUI by:
System Configurations
select a system and then Edit
General tab
Verify Connection
/PLUGIN=smThis plugin starts the 5250 Session Manager GUI.
This is equivalent to 5250 Session Manager from the main GUI.
/PLUGIN=5250 /SYSTEM=<system> [/<options>]
This plugin starts a 5250 emulator to the specified system.
This function is equivalent to 5250 Emulator from the main GUI.
Valid options are:
/id=<A-Z> - short session id
/name=<name> - session name
/wsid=<identifier> - workstation id
/wide=<1|0|true|false> - use a wide screen size (27x132)
/fullscreen<1|0|true|false> - use the entire screen
/nosave=<1|0|true|false> - do not save settings on exit
/prompt=<1|0|true|false> - force the configuration dialog to appear
/port=<port> - port number
/ssl=<1|0|true|false> - connect using secure sockets
/sso=<1|0|true|false> - bypass signon screen
/kerberos - Use kerberos
/width=<width> - initial width of the emulator window
/height=<height> - initial height of the emulator window
/xpos=<xpos> - initial x-coordinate position of the top-left
corner of the emulator window
/ypos=<ypos> - initial y-coordinate position of the top-left
corner of the emulator window
/watermark - display system name as watermark on screen
/watermark=<text> - display provided text as watermark on screen
/PLUGIN=dtgui This plugin starts the main GUI for Data Transfer. This function is equivalent to Data Transfer from the main GUI.
/PLUGIN=download [/userid=<userid>] <filename> [<filename> <filename> ...]
/userid - user id to use when connecting to the target system
<filename>- file with the .dtfx extension that was created from a previous
Data Transfer download.
The plugin enables the user to run a previously saved Data Transfer download.
Data Transfer is also available from the main GUI by selecting Data Transfer.
/PLUGIN=upload [/userid=<userid>] <filename> [<filename> <filename> ...]
/userid - user id to use when connecting to the target system
<filename>- file with the .dttx extension that was created from a previous
Data Transfer upload.
The plugin enables the user to run a previously saved Data Transfer upload.
Data Transfer is also available from the main GUI by selecting Data Transfer.
/PLUGIN=cldownload /system=<system>
[/userid=<userid>]
{/hostfile=<library/filename> | /sql="statement"}
{/clientfile=<path><filename>.<extension> | /display}
[/<options>]
/userid - user id to use when connecting to the target system
/hostfile - Source library and file on the IBM i system for the download
e.g. /hostfile=QIWS/QCUSTCDT
/sql - specify an SQL statement
e.g. /sql="select CUSNUM,LSTNAM,INIT,ZIPCOD from QIWS/QCUSTCDT"
/clientfile - Target file location for the download.
The format of this file will be determined by the specified
extension (for example, .csv .ods .xlsx .xlsx)
If the file extension is not specified or is of a type
not supported, the data will be formatted as a .csv file
/display - write the output to the terminal
Valid options are:
/colheadings=<1/0> - Include column headings as the first row. When specified, the column names will be the heading.
/usecollabels - Use column labels for the heading.
The plugin enables the user to run a simple download of an entire file from
the command line.
/PLUGIN=console /SYSTEM=<system>This plugin starts a 5250 console to the specified system.
This function is equivalent to 5250 Console from the main GUI.
/PLUGIN=vcp /SYSTEM=<system>This plugin starts a Virtual Control Panel to the specified system.
This function is equivalent to Virtual Control Panel from the main GUI.
/PLUGIN=l1c /SYSTEM=<system>This plugin launches a browser to IBM Navigator for i using the specified system and port 2001.
This function is equivalent to Navigator for i from the main GUI.
/PLUGIN=splf /SYSTEM=<system>This plugin displays the Printer Output GUI for viewing and downloading spool files from the IBM i.
This function is equivalent to Printer Output from the main GUI.
/PLUGIN=keymanThis plugin displays the Key Management tool.
This function is equivalent to Tools->Key Management from the main GUI.
/PLUGIN=rmtcmd /SYSTEM=<system>
{/CMD="<CL command>" | file=<file_name>}
[/noprompt=<1|0>]
[/immed=<0|1>]
/cmd="<CL command>" - a command to run. Use quotes to avoid spaces from
breaking up the command.
/file=<file_name> - specify an input file with multiple commands. Commands
should be one per line without quotes.
/noprompt=<1|0> - when specifying an input file, ignore the results and
any prompts before continuing.
/immed=<0|1> - send each command as it is read.
This plugin sends CL command(s) to the specified system.
This function is only available from the command line.
/PLUGIN=pwchange /SYSTEMS=<system,system,system,...>This plugin changes the password on the specified systems. It prompts the user for a userid, old and new passwords.
This function may also be used from the main GUI by selecting the Passwords tab from Edit->Preferences
/PLUGIN=migrate /<option> /SYSTEM=<system>
<system> can be set to one system name or set to *ALL to indicate all systems.
Valid options are:
/IMPORT - Copy one (or all) system configurations from the legacy Windows
configuration to IBM i Access Client Solutions.
/EXPORT - Copy one (or all) system configurations to the legacy Windows
configuraiton from IBM i Access Client Solutions.
/DELETE - Delete one (or all) system configurations from the legacy Windows
configuration.
This plugin provides the capability to copy system configurations back and forth
between IBM i Access Client Solutions and the legacy Windows configuration
supported by IBM i Access for Windows.
This function may also be used from the main GUI by selecting File->Copy Connections
/PLUGIN=restrict /<options>
Valid options are:
/restrict=<func1,func2,func3> Restricts the given functions on this
workstation.
/unrestrict=<func1,func2,func3> Allows the given functions on this
workstation.
/list Lists whether functions are allowed or
restricted on this workstation.
/export=<file> Export restrictions to the named file with
a .acsr file extension.
/import=<file>.acsr Import restrictions from a file with
a .acsr file extension.
/exportreg=<file> Export a Windows registry file (.reg file).
This plugin provides the capability to anyone with administrator or root authority to restrict certain functions from all users on the current workstation.
Function Description
5250 5250 Emulator
cfg System Configurations
checkupdates Check for available updates
cldownload Data Transfer command-line downloads
console 5250 Console
consoleprobe Search the local network for console configurations
db2 Schemas
db2tools SQL Performance Center
download Data Transfer command-line downloads
dtgui Data Transfer graphical user interface
hmcprobe Search an HMC for partitions
ifs Integrated File System
installupdates Install updates from an IBM i configured location
keyman SSL/TLS certificate management
l1c IBM Navigator for i (Level 1 Console)
osssetup Open Source Package Management
restrictview Restrict view of currently restricted functions
rmtcmd Remote command (available from the command-line)
rss Run SQL Scripts
sm 5250 Session Manager
splf Printer Output (spool files)
ssh Secure Shell
sysdbg IBM i System Debugger
upload Data Transfer command-line uploads
vcp Virtual Control Panel
Hardware Management Interfaces:
hmi1 Hardware Management Interface 1
hmi2 Hardware Management Interface 2
asmi Advanced System Management Interface (ASMI)
csmi Copy Services Manager for i
dcm Digital Certificate Manager
dshmc DS HMC
hmc Hardware Management Console (HMC)
httpadmin Web (HTTP) Administration for i
ivm Integrated Virtualization Manager
specctrl Spectrum Control
tapemgmt1 Tape Management 1
tapemgmt2 Tape Management 2
are Administration Runtime Expert
db2webquery Db2 Web Query
Functions may also be excluded as a group using keywords:
Group Functions dataxfer dtgui,upload,download,cldownload emulator sm,5250 keyman keyman opconsole console,vcp,consoleprobe,hmcprobe rmtcmd rmtcmd splf splf ifs ifs hwconsole hmi1,hmi2,asmi,csmi,dcm,dshmc,hmc,httpadmin,ivm,specctrl,tapemgmt1,tapemgmt2,are,db2webquery l1cplugin l1c database db2,rss,db2tools debugger sysdbgThe ability to restrict functions is also available to an administrator or user with root authority from the main GUI.
For an easy way to restrict functions on multiple workstations, see section 9.5 Customized Packages.
/PLUGIN=restrictviewLists the functions that are currently restricted on this workstation.
/PLUGIN=fileassoc [<filetype> <filetype> ...] [/c]
<filetype> - valid file types are: dttx, dtfx, hod, bchx, ws, bch, sql
/c - clear the file association for the specified file types
On a Windows platform, this sets the file associations for files of type .dttx,
.dtfx, .hod, .bchx, .ws, .bch, and .sql. On a non-Windows platform, an error message
will be displayed.
This function is equivalent to Tools->File Associations from the main GUI.
/PLUGIN=dtbatch [/userid=<userid>] <filename> [<filename> <filename> ...]
/userid - user id to use when connecting to the target system
<filename>- file with the .dtfx or .dttx extension that was created from a
previous Data Transfer download or upload.
Multiple files may be specified with or without this keyword.
The plugin enables the user to run a previously saved Data Transfer request.
Data Transfer is also available from the main GUI by selecting Data Transfer.
/PLUGIN=pm5250 [/input=<file> ... /output=<directory>] [/verbose] [/gui]
/input - Files to be migrated. The files must be 5250 files with
an extension of .ws, .bch, .kmp, .pmp, or .bar.
/output - location where migrated files will be stored.
/verbose - display results of migrated files.
/gui - start the user interface for migrating 5250 files.
The plugin enables the user to migrate files from the IBM i Access for Windows
Personal Communications emulator to the IBM i Access Client Solutions emulator.
Some converted files will have a new file extension. See section
9.6.2 Migrating 5250 Emulation.
/PLUGIN=rss /SYSTEM=<system> /DATABASE=<database> [/FILE=<file>] [/SQL=<file>] [/AUTORUN=<0,1>]
/FILE=<filename> - Open the specified file
/SQL=<sql> - Start with the specified SQL
/AUTORUN=<1,0> - Automatically run the script
The plugin enables the user to run SQL statements and CL commands.
/PLUGIN=DB2TOOLS /SYSTEM=<system> /DATABASE=<database> [Options]
Valid options are:
/ACTION=<LIST | ANALYZE | STATEMENTS | COMPARE>
- Action to perform:
The LIST option can be used with the LISTNAME argument and displays the
SQL Performance Center with the specified list.
The ANALYZE option analyzes the given performance data set.
The STATEMENTS option shows statements for either the SQL plan cache or
the given performance data set.
The COMPARE option compares the given performance data set(s).
/NAME=<name> - The name of the performance data set
/TABLE=<name> - The name of the table that contains performance data
/SCHEMA=<name> - The name of the schema of the table that contains performance data
/LISTNAME=<DBMONITORS | PCEVENTMONITORS | PCSNAPSHOTS | LIVE_PLAN_CACHE>
- The initial list to display in the SQL Performance Center.
The SQL Performance Center plugin provides a set of tools to help you optimize the SQL in your database applications:
/PLUGIN=ifs /SYSTEM=<system>Integrated File System provides an interface for browsing the integrated file system of your IBM i and working with objects in the integrated file system in the following ways:
/PLUGIN=DB2 /SYSTEM=<system>The plugin provides an interface for managing the Db2 for i databases on the IBM i.
/PLUGIN=checkupdatesThe plugin provides an interface to check for available updates.
/PLUGIN=SSH /SYSTEM=<system>SSH Terminal will launch an already-installed SSH client (terminal emulator) on your PC to the IBM i integrated file system.
/PLUGIN=OSSSETUPOSSSETUP will launch an interface that will allow you to manage open source packages on the IBM i.
/PLUGIN=installupdates [Options]
Valid options are:
/noprompt Do not prompt for user id and password
Note: When using this option, if the user's credentials to the remote system
are already cached, the check for available updates will continue normally.
If the user's credentials are not cached, authorization to the remote
system will be denied and updates will not be available.
INSTALLUPDATES will check the configured IBM i system for available updates and will automatically download and install the update to the local PC installation.
To configure an IBM i location for downloading updates, see section 5.2.
/PLUGIN=httpproxyuiHTTPPROXYUI will launch a secured HTTP proxy that enables connectivity from an IBM i to the internet via the computer running this proxy. Access to the internet will be enabled from any SSH Terminal session that enters the commands provided by the HTTPPROXYUI plugin.
/udcnv [/wide]
/wide This option is only valid with code page 932.
When specified, the font-image file produced will contain unicode characters.
Example invocation:
Start_Programs\Windows_x86-64\acslaunch_win-64.exe /udcnv
This command-line option is for generating a font-image file that contains User Defined Characters (UDC) that are currently
configured on a Windows workstation. The generated font-image file will be an ANSI code page based on the workstation locale. The following
ANSI code pages are supported:
Code Page Platform Font-image filename
932 Japanese Windows jpn24.fnt
949 Korean Windows kor24.fnt
936 Simplified Chinese Windows chs24.fnt
950 Traditional Chinese Windows cht24.fnt
The generated font-image file can be used with 5250 printer emulation in combination with a Printer Definition Table (PDT) on a Windows workstation.
The command will start a GUI which will allow you to specify the path in which to place the generated font-image file.
The generated font-image file needs to have the above specified name and be placed in the Emulator\fonts folder which exists at:
<Configuration Root>\Emulator\fonts
Where <Configuration Root> is normally a path like:
C:\Users\<user_name>\Documents\IBM\iAccessClient
To find the actual Configuration Root for your installation, see section 8.1 Configuration Location.
Limitations:
Some configuration files generated by IBM i Access Client Solutions are supported from the command-line when they are provided as the first and only parameter. When these files with specific file extensions are provided as the first parameter, IBM i Access Client Solutions will associate the file with the function to be invoked and provide the file as input to that function.
The following extensions have file association support:
.dttx - Data Transfer upload request
.dtfx - Data Transfer download request
.hod - 5250 emulator session profile
.bchx - multiple session emulation profile
.ws - 5250 emulator session profile (Personal Communications)
.bch - multiple session emulation profile (Personal Communications)
.sql - SQL file
Command-line examples:
acslaunch_xxx dt_download_file.dtfx - runs the saved download operation
acslaunch_xxx dt_upload_file.dttx - runs the saved upload operation
acslaunch_xxx system_lp13ut20.hod - starts a 5250 session to the system
...where acslaunch_xxx is the command-line syntax used for starting the product. See
section 7.3 Starting the Product (using the command-line).
These supported command-line file associations enable the user to manually set up operating system (OS) specific file associations. Since file associations are platform dependent, the steps required depend on the OS.
The reason you may want to consider setting up file associations for your OS is so you have the ability to double-click a file (of one of the above supported file types) to start the designated function.The following sections provide some examples of setting up file associations for some operating systems.
The appropriate IBM i Access Client Solution function will now run when you double-click files with this type.
Follow the steps in the QuickStartGuide for Linux. This will install the application to /opt/ibm/iAccessClientSolutions. It will also create: /usr/share/applications/IBM i Accesss Client Solutions.desktop
To create an icon for the product on your desktop, copy the above .desktop file to your Desktop folder. You may need to adjust the permissions of file on your desktop so that it is executable.
The steps required for setting file associations will depend on the Linux distribution and the desktop environment being used. In general, the steps required will be similar to the above steps used for Windows.
In order to use File Associations on a Mac, the file type must be associated with an application. Follow the steps in the QuickStartGuide for Mac so IBM i Access Client Solutions is an installed application.
The appropriate IBM i Access Client Solution function will now run when you double-click files with this type.
Use the Preview application to locate the Icons folder within the product directory and use Finder to replace the icon in Get Info.
By default, each user will have their own unique location for their
configuration. The configuration location can be changed by setting the property:
com.ibm.iaccess.AcsBaseDirectory
This property exists inside the AcsConfig.properties file.
The AcsConfig.properties file exists in two locations when the product is shipped. It is contained inside the acsbundle.jar file. For convenience, it is also provided in the product zip archive file and will be in the same directory as the acsbundle.jar file when the zip archive is unpacked.
During start-up, the product will only use the first AcsConfig.properties file it finds. It first checks the directory where the acsbundle.jar file exists. If AcsConfig.properties is not found in the same directory as the acsbundle.jar file , it will use the AcsConfig.properties file inside the acsbundle.jar file.
You may choose to update AcsConfig.properties in acsbundle.jar with a custom configuration path. If you do, make sure the directory where acsbundle.jar exists does not contain an AcsConfig.properties file or it will get used instead. This provides the flexibility of being able to distribute the configuration location with the acsbundle.jar file while also providing the flexibility to override it.
Special keywords are provided which can be used when defining the configuration
path. When the keywords are used in the specified path, the keywords will be
substituted with the text or path they define. Only one keyword can be used
in the configuration path. The special keywords and their meanings are:
{USER} - The current user id. This keyword can be anywhere in the path
The following keywords can only be at the beginning of the specified path:
{PRODUCTDIR} - the path to the same directory as acsbundle.jar
{TEMPDIR} - the path to a platform specific temporary directory
{ROOT} - the path to the root of the file system
{HOME} - the path to the user's home directory
{DEFAULT} - the default path the product would normally use
Technical Note:
We do not recommend sharing a configuration between multiple users.
For example, if X were a shared network drive, the following setting may
cause unpredictable results:
com.ibm.iaccess.AcsBaseDirectory=X:/Shared_Network_drive/config_directory
There are several problems with multiple users sharing this configuration path:
When sharing a configuration path between multiple users, the {USER} keyword should be used to avoid collisions with other users. It will be substituted with the user id of the current user.
When setting the configuration path, use a forward slash ('/') instead of a backward slash ('\') as the directory separator. This will work on all operating systems including Windows.
Here are some recommended sample configurations:
Example 1 - local configuration for current user (default):
com.ibm.iaccess.AcsBaseDirectory=
When AcsBaseDirectory is not set, the configuration defaults to a platform
dependent path for the user.
This is the default setting for IBM i Access Client Solutions.
Example 2 - remote (or local) configuration unique for each user:
com.ibm.iaccess.AcsBaseDirectory={ROOT}/config_directory/{USER}/
The configuration will be remote or local based on the location of {ROOT}.
Example 3 - remote (or local) configuration unique for each user:
com.ibm.iaccess.AcsBaseDirectory={PRODUCTDIR}/config_directory/{USER}/
The configuration will be remote or local based on the location of {PRODUCTDIR}.
Example 4 - local configuration on portable media (like USB drive):
com.ibm.iaccess.AcsBaseDirectory={PRODUCTDIR}/config_directory
Since the path to the portable media will vary depending on the system where
it is being used, this setting allows the configuration to be relative to
the product files. In this example, the {USER} keyword was intentionally not
specified so the configuration on the USB drive would be used by the user of
the USB drive, regardless of the user ID.
Here are some other deployment options you may want to consider:
The following properties may be used in the AcsConfig.properties file to
automatically set up a configuration for new users or to update a
configuration for existing users:
com.ibm.iaccess.autoimport com.ibm.iaccess.autoimport.version
Here are the necessary steps:
Here is how it works:
The saved configuration referenced by the com.ibm.iaccess.autoimport property
will be automatically imported when the integer value of the
com.ibm.iaccess.autoimport.version property mismatches the last value that
was imported. In addition to providing a way to set up an initial
configuration and provide updates to an existing configuration, this also
provides a way to back-level a configuration. The configuration will be
updated anytime there is a mismatch between the integer value of the version
property with the last version that was imported. However, while an imported
configuration may change the configuration for an existing system in the user's
configuration, a system will never be deleted from the user's configuration.
The path for the com.ibm.iaccess.autoimport property may be specified as an absolute path, a URL or with keywords defined in section 9.3. For example:
com.ibm.iaccess.autoimport=C:/acs_bak.zip
com.ibm.iaccess.autoimport=file///C:/acs_bak.zip
com.ibm.iaccess.autoimport=http://your.company.com/path/file/acs_bak.zip
com.ibm.iaccess.autoimport=ftp://your.company.com/path/file/acs_bak.zip
com.ibm.iaccess.autoimport={PRODUCTDIR}/acs_bak.zip
Additional flexibility is provided by allowing the configuration file to be
distributed within acsbundle.jar or in the same directory as acsbundle.jar.
For either case, set com.ibm.iaccess.autoimport with the name of the file
without a preceding path:
com.ibm.iaccess.autoimport=acs_bak.zip
A special value of * is allowed for com.ibm.iaccess.autoimport.version:
com.ibm.iaccess.autoimport.version=*
This will always import the configuration regardless of any previous version.
Note:
To avoid importing the default user name specified on the Connection tab of a System Configuration,
place the following property in the AcsConfig.properties file.
com.ibm.iaccess.ResetDefaultUserOnImport=true
Some of the command-line plugins that do not require a GUI can be used natively on the IBM i. For example, you can use Data Transfer to extract data from your database into a spreadsheet file type directly on the IBM i without downloading the data to the PC.
To do this, you can extract the product zip archive to any place in the IBM i Integrated File System (IFS). For example, if you extracted the product zip archive to:
/home/AccessClientSolutionsAnd you have a previously saved Data Transfer download request that exists at:
/some_path/qcustcdt.dtfxYou can run the following command on the IBM i:
QSH CMD('java -jar /home/AccessClientSolutions/acsbundle.jar /plugin=dtbatch /some_path/qcustcdt.dtfx')
Note:
There are also IBM i PTFs which will extract the contents of the product for you on an IBM i.
See section 5.3 Optional IBM i PTFs
IBM i Access Client Solutions provides system administrators the ability to
restrict the usage of specific functions by setting either of the following two properties in
the AcsConfig.properties file:
com.ibm.iaccess.ExcludeComps=<function, function,...>
com.ibm.iaccess.IncludeComps=<function, function,...>
Setting com.ibm.iaccess.ExcludeComps will disable the specified functions. All other functions will be enabled. Any function specified on this property will not be available from the main ACS GUI nor from the command line. The functions which may be specified on this property are listed below.
Setting com.ibm.iaccess.IncludeComps will enable the specified functions. All other functions will be disabled. Any function specified on this property will be available for normal usage. The functions which may be specified on this property are listed below.
Function Description
5250 5250 Emulator
cfg System Configurations
checkupdates Check for available updates
cldownload Data Transfer command-line downloads
console 5250 Console
consoleprobe Search the local network for console configurations
db2 Schemas
db2tools SQL Performance Center
download Data Transfer command-line downloads
dtgui Data Transfer graphical user interface
hmcprobe Search an HMC for partitions
ifs Integrated File System
keyman SSL/TLS certificate management
l1c IBM Navigator for i (Level 1 Console)
osssetup Open Source Package Management
restrictview Restrict view of currently restricted functions
rmtcmd Remote command (available from the command-line)
rss Run SQL Scripts
sm 5250 Session Manager
splf Printer Output (spool files)
ssh Secure Shell
sysdbg IBM i System Debugger
upload Data Transfer command-line uploads
vcp Virtual Control Panel
Hardware Management Interfaces:
hmi1 Hardware Management Interface 1
hmi2 Hardware Management Interface 2
asmi Advanced System Management Interface (ASMI)
csmi Copy Services Manager for i
dcm Digital Certificate Manager
dshmc DS HMC
hmc Hardware Management Console (HMC)
httpadmin Web (HTTP) Administration for i
ivm Integrated Virtualization Manager
specctrl Spectrum Control
tapemgmt1 Tape Management 1
tapemgmt2 Tape Management 2
are Administration Runtime Expert
db2webquery Db2 Web Query
Functions may also be specified as groups using the following keywords:
Group Functions dataxfer dtgui,upload,download,cldownload emulator sm,5250 keyman keyman opconsole console,vcp,consoleprobe,hmcprobe rmtcmd rmtcmd splf splf ifs ifs hwconsole hmi1,hmi2,asmi,csmi,dcm,dshmc,hmc,httpadmin,ivm,specctrl,tapemgmt1,tapemgmt2,are,db2webquery l1cplugin l1c database db2,rss,db2tools debugger sysdbg
Normally these properties would not be used together. If they are used together and a function is specified on both properties, the function will be disabled.
Example 1: This will disable all the functions associated with OPCONSOLE,HWCONSOLE,L1CPLUGIN. All other functions in the above list will be enabled.
com.ibm.iaccess.ExcludeComps=OPCONSOLE,HWCONSOLE,L1CPLUGIN
Example 2: This will enable 5250 and data transfer downloads. All other functions in the above list will be disabled.
com.ibm.iaccess.IncludeComps=5250,DOWNLOAD
If the system adminstrator would like to update the AcsConfig.properties file
inside acsbundle.jar before deploying it to their users, an example of how to
do that is:
jar uvf acsbundle.jar AcsConfig.properties
Refer to section 9.3 Changing Configuration Location for additional information
about how IBM i Access Client Solutions determines which AcsConfig.properties
file to use.
IBM i Access Client Solutions configuration files are not compatible with the corresponding functions in IBM i Access for Windows. IBM i Access Client Solutions provides a migration path for several key items as discussed in the following sections.
The Copy Connections function available from the main GUI menu at File->Copy Connections provides an interface for copying system configurations between IBM i Access Client Solutions and the legacy Windows configuration supported by IBM i Access for Windows. For additional information, see the help for the main panel of Copy Connections. The system configurations may also be migrated using the command line. See section 9.1.25 MIGRATE for additional information.
5250 emulation files used by the IBM i Access for Windows Personal Communications
emulator can be converted by using the 5250 Session Manager in IBM i Access
Client Solutions. The following file types can be converted from Personal
Communications:
.ws - emulator profile .bch - emulator batch file .kmp - keyboard customization file .pmp - poppad files .bar - menu bar filesThe files will be converted to:
.hod - emulator profile .bchx - emulator batch file .kmp - keyboard customization file .pmp - poppad files .bar - menu bar filesThe .kmp, .pmp, and .bar file types are used by both products. However the formats are not compatible. The converted files will be created in an IBM i Access Client Solutions specific path.
The conversion of these files can be initiated from the IBM i Access Client Solutions Session Manager menu by:
A macro conversion utility is available. From the Session Manager:
Tools->Convert Macro...
Technical Note:Data Transfer in IBM i Access Client Solutions provides a wizard for converting saved Data Transfer request files that were generated by IBM i Access for Windows.
The following file types can be converted from IBM i Access for Windows:
.dtf - data transfer from IBM i .dtt - data transfer to IBM iThe files will be converted to:
.dtfx - data transfer from IBM i .dttx - data transfer to IBM iThe Data Transfer migration wizard does not migrate .fdf files. The new file type required by IBM i Access Client Solutions is of the type .fdfx and can be generated during a download or by using the Create File Wizard.
The Data Transfer migration wizard is available from the Data Transfer main menu by selecting Actions->Data Transfer Migration
For 5250 applications which leverage EHLLAPI when accessing the Personal
Communications emulator shipped with IBM i Access for Windows, refer
to the following KB article for information about using EHLLAPI with
IBM i Access Client Solutions:
http://www-01.ibm.com/support/docview.wss?uid=nas8N1010639
IBM i Access Client Solutions has support for kerberos. To use kerberos
when connecting to a system:
The property com.ibm.iaccess.PC5250Compatibility can be used to change the default behavior for the ACS emulator. This property can be set in AcsConfig.properties with the following values:
allowNnAsFKeyHotspot - treat NN hotspots (eg FNN, PFNN, FPNN) like function key hotspots.
allowHighlightBypassField - allow bypass fields with ENTFLDATR to be highlighted.
allowTypingInSignPosition - allow '-' or ' ' to be keyed in the sign position of a signed numeric field.
allowTransformSpecialCharsOnPaste - change how certain characters get transformed when pasting text
from external documents (eg curly quotes become straight quotes).
Example 1:
com.ibm.iaccess.PC5250Compatibility=allowTransformSpecialCharsOnPaste
Example 2: Multiple values can be specified in a comma separated list.
com.ibm.iaccess.PC5250Compatibility=allowNnAsFKeyHotspot,allowHighlightBypassField,allowTypingInSignPosition
Managing certificates for Secure Socket Layer (SSL) connections is available from the main GUI by selecting Tools->Key Management. Some tasks on the Key Database require the keystore integrity passphrase.
In addition to supporting downloads to a File, Data Transfer also supports downloads to an active spreadsheet for either Microsoft's Excel spreadsheet or OpenOffice's Calc spreadsheet. To download to an active spreadsheet, the main Data Transfer GUI panel provides the option to select an Output Device. By default, the Output Device is File. If your platform supports interaction with the Excel and/or Calc spreadsheet, additional options for an Active Excel Spreadsheet and an Active Calc Spreadsheet can be selected from the Output Device drop down box.
Restrictions:
During a Data Transfer upload request, if a character or numeric field exceeds the defined size of the field, the upload request will terminate.
To enable character fields to be truncated from the end, set the following property
in the AcsConfig.properties file:
com.ibm.iaccess.dataxfer.jdbc.AllowCharacterTruncation=true
To enable numeric fields to be set to their maximum positive or negative
value when the provided numeric field exceeds the defined boundary, set the
following property in the AcsConfig.properties file:
com.ibm.iaccess.dataxfer.jdbc.AllowNumericOverflow=true
When these properties are set to true, the upload request will continue without providing any indication that truncation or overflow occurred. Character fields will be truncated at the end. Numeric fields will be set to their maximum value for overflow and their minimum value for underflow.
Alternatively, the above properties can be set from from the command line like
other java properties as follows:
-Dcom.ibm.iaccess.dataxfer.jdbc.AllowCharacterTruncation=true
-Dcom.ibm.iaccess.dataxfer.jdbc.AllowNumericOverflow=true
During downloads, a sheet name is generated based on the name of the IBM i source library and file
with ">Sheet#" appended where # is replaced with the appropriate sheet number. For example:
qiws.qcustcdt>Sheet1
To override the library and file portion of the sheet name, you may specify the following property:
com.ibm.iaccess.dataxfer.SheetId=your_string
This will generate:
your_string>Sheet1
If the special values of %1$s %2$s or %3$s are used in the property, the placement of library.filename and sheet# can be changed or eliminated.
The values have the following meaning:
%1$s - library.filename For example: qiws.qcustcdt
%2$s - sheet# For example: 1
%3$s - destination file name without file extension
Using any of these special values provides complete control of the sheet name.
Setting the property to Sheet%2$s will produce sheet names: Sheet1, Sheet2, etc
com.ibm.iaccess.dataxfer.SheetId=Sheet%2$s
You may use %1$s %2$s or %3$s in any combination with other text.
Note:
Since sheet names in a spreadsheet must be unique, setting the property to use %1$s or %3$ without also using %2$s will
produce an error if more than one sheet is needed.
To perform administrative functions on the IBM i, a 5250 console is required. IBM i Access Client Solutions supports both LAN and HMC console configurations.
If you know the Service host name or Service IP address for your IBM i or the
host name or IP address for your HMC console, you can configure the console
information within IBM i Access Client Solutions using the following steps:
For an IBM i where the console configuration does not yet exist (e.g. a new
system just delivered to your business), an IP address for a console connection
will be automatically assigned in the range of 169.254.62.0 - 169.254.62.63
during the IPL. For these cases, the following steps will help establish a
console connection using IBM i Access Client Solutions:
When you are ready to add the IBM i system to the rest of your network infrastructure, there is additional information in the IBM Knowledge Center for how to configure the Service Tools LAN Adapter:
See Configuring the service tools server for DST.
For IBM i systems that already have a LAN console configuration and are already
in your network infrastructure, the following steps may be used to find existing
console configurations:
Additional fonts for 5250 emulation may be added to the Fonts directory.
To provide alternative and/or multiple locations for additional fonts, set the com.ibm.iaccess.Fonts property located in the AcsConfig.properties file.
The default Fonts directory may be overridden by setting the
com.ibm.iaccess.Fonts property to a:
Note:
The <path> may be an absolute path or a relative path starting from the location
of acsbundle.jar. Only monospaced fonts will be recognized by 5250 emulation.
Example 1 (default):
com.ibm.iaccess.Fonts=Fonts
Example 2:
com.ibm.iaccess.Fonts=/Users/All/Fonts;Fonts
To enable the usage of a .netrc file (Linux and Mac) or a _netrc file (Windows),
go to the IBM i Access Client Solutions main GUI and from the menu bar, select
Edit->Preferences
General tab
Check the box: Read netrc file for login information
Click the Apply button
Restart IBM i Access Client Solutions
The standard format of a netrc file is:
machine <system> login <user-id> password <password>
The netrc file must be stored in the user's home directory and the system name and user-id
must match System Configurations. From IBM i Access Client
Solutions:
Select System Configurations
Select and then Edit the system
Connections tab
Select Use default user name to prompt once for each system
Fill in the user-id for: Default user name
Select OK
When the system name and Default user name match the contents of the netrc file, a connection to the system will be made using the password from the netrc file without prompting the user.
The Integrated File System Support uses the QFileSvr.400 file system to copy or send objects from one IBM i partition to another. This means the user profile and password on both partitions must match, and the partitions must have the same password level system value (QPWDLVL). If using Kerberos authentication, both partitions must have Network Authentication Service and Enterprise Identity Mapping (EIM) configured. For more details, see the topic "Security and object authority in the QFileSvr.400 file system" in the IBM i Knowledge center.
The connections to other IBM i partitions made by the QFileSvr.400 file system are not secure.
If a secure connection is needed when copying or sending objects from one IBM i partition to another,
the configuration for the partition must be setup to use SSL, System Configurations must have the
"Use SSL for connection" option selected for that partition, and the following property must be set in the
AcsConfig.properties file:
com.ibm.iaccess.ifs.transferMechanism=ACS
Alternatively, the property can be set from from the command line like other java properties as follows:
-Dcom.ibm.iaccess.ifs.transferMechanism=ACS
The Integrated File System support requires authority to use the following CL commands:
CPY
CPYFRMSTMF
CPYTOSTMF
CRTDIR
CRTLIB
CRTSAVF
RMVDIR
RST
SAV
SETASPGRP
If the user cannot use these CL commands, the Copy, Paste, Send, Delete, and New Folder actions will fail.
The Integrated File System support does not allow actions for objects which have paths that start with /QFileSvr.400, /QNTC, or /QOPT. If the current directory path or any selected object path starts with /QFileSvr.400, /QNTC, or /QOPT, all items in the Actions menu will be disabled and a context menu will not be displayed.
The Integrated File System support does not allow the Copy, Paste, or Send action when the source object or target path is located on an independent ASP.
Performance of IFS when displaying the contents of a directory is determined by the column attributes
selected (View->Columns...) and whether the directory contains symbolic links. For non-symbolic links, there is an
additional performance impact when selecting either CCSID or Owner. For symbolic links, there is an
additional performance impact for each column attribute selected other than Icon, Name, and Size (KB)
Note: Size (KB) for symbolic links is not displayed when browsing the directory. Select Properties to get the size
of the file represented by the symbolic link.
When displaying a directory with a large number of entries, you may exceed the default memory limit of the Java Virtual Machine where IBM i Access Client Solutions is running. This can cause all open windows to slow down and eventually stop responding. If you will be displaying directories with a large number of entries, consider using the Include filter to limit the number of entries sent from the server. Or, start the product using the -Xmx option to increase the available memory. For example:
java -Xmx4g -jar V:/some_location/acsbundle.jar
or
Start_Programs\Windows_x86-64\acslaunch_win-64.exe -Xmx4g
The above examples will increase the memory from the default 1 gigabyte to 4 gigabytes. You may need to increase the size even more based on the number of entries in the directory.
For platforms where a Secure Shell exists by default or has been installed, the SSH Terminal feature will appear on the IBM i Access Client Solutions main GUI. SSH Terminal will launch a terminal emulator to the IBM i integrated file system.
Most Mac, Linux, and other UNIX-derived systems already have a Secure Shell by default. For these platforms, it is assumed an OpenSSH client exists and is located at /usr/bin/ssh. Windows users will need to install one of the Secure Shells available for Windows.
Secure Shells supported by IBM i Access Client Solutions:
Linux: Xterm, XterminalEmulator, MateTerminal, Terminator, GnomeTerminal, Konsole, Xfce4
Mac: Terminal, iTerm2
Windows: cygwin, PuTTY, bash
cygwin requires the openssh package to be installed
bash is available as part of the Linux subsystem for Windows
If there are multiple SSH applications installed, you can use the com.ibm.iaccess.PreferredSSHClient property to set the preferred SSH client.
Linux examples:
com.ibm.iaccess.PreferredSSHClient=XterminalEmulator
com.ibm.iaccess.PreferredSSHClient=MateTerminal
com.ibm.iaccess.PreferredSSHClient=Terminator
com.ibm.iaccess.PreferredSSHClient=GnomeTerminal
com.ibm.iaccess.PreferredSSHClient=Konsole
com.ibm.iaccess.PreferredSSHClient=Xfce4
Mac examples:
com.ibm.iaccess.PreferredSSHClient=iTerm2
Windows examples:
com.ibm.iaccess.PreferredSSHClient=Cygwin
com.ibm.iaccess.PreferredSSHClient=Putty
com.ibm.iaccess.PreferredSSHClient=Bash
For cases when the SSH client is not installed to the standard location, you can use the com.ibm.iaccess.PreferredSSHClient property to provide the fully-qualified path to the installed SSH client.
com.ibm.iaccess.PreferredSSHClient=C:\PuTTY\putty.exe
When the fully-qualified path is provided, you may also need to set com.ibm.iaccess.SSHClientOpt to provide all necessary arguments. For example, to disable warnings if you don't use X11 forwarding:
com.ibm.iaccess.SSHClientOpts=-x
If you receive a connection error within the launched SSH client (for example, "connection refused"), or if a window pops up but immediately vanishes, you may need to start the SSH daemon with the above command.
If you encounter a problem which requires IBM service, your IBM service representative may direct you to do one or both of the following:
From the main IBM i Access Client Solutions GUI:
Q1 When I try to start IBM i Access Client Solutions I get the following
error:
class cannot be loaded: java.lang.UnsupportedClassVersionError
A1-1 You need to use JDK 8.0 or higher. See section 3.0 Prerequisites
Q2 When I try to start the product using one of the provided binary files or
scripts from a shell or terminal session, I get the following error:
Permission denied
A2-1 Check the file permissions of the file to make sure you have execute
permission. See section 6.0 File Permissions.
Q3 When I double-click on one of the provided files to start the product,
nothing happens.
A3-1 Java may not be installed. See section 3.0 Prerequisites
A3-2 The file you are using to start the product may not have execute
permission. See section 6.0 File Permissions.
A3-3 There may be problems with your environment. To see what errors may be
occurring, try running the provided file from a command line.
See section 7.3 Starting the Product (using the command-line).
Q4 I want to use one of the binary files to start the product, but I get the
following error: "Error loading Java module."
A4-1 The binary was unable to locate the home directory of the java
installation.
Please verify java is installed. See section 3.0 Prerequisites.
A4-2 Section 7.1.1 Starting the Product - Additional Options
contains additional methods for starting the product using a binary file.
Q5 After I set the JAVA_HOME environment variable, the binary file I use to
start the product works from a command-line, but does not work when I
double-click the file.
A5-1 The JAVA_HOME environment variable may not be visible from the file manager
you are using when you double-click the file. Setting environment
variables varies across operating systems and so does their visibility.
Try setting the JAVA_HOME environment variable as a system environment
variable for your operating system. Your operating system may refer to
system environment variables as global environment variables.
After setting the JAVA_HOME environment variable, close and reopen your
file manager and try to double-click the binary file again.
Q6 When I double-click on one of the provided files to start the product, a
text editor displays the file.
A6-1 Make sure you are using a script that has a file extension your operating
system recognizes.
A6-2 Try one of the other scripts.
A6-3 Change the program that opens the file.
A6-4 Check the file permissions of the file to make sure you have execute
permission. See section6.0 File Permissions.
Q7 When I double-click on one of the provided files to start the product, I am
prompted for which program should be used to open the file.
A7-1 Make sure you are using a script that has a file extension your operating
system recognizes.
A7-2 Set the program that opens the file to something compatible with the binary
file or script you are using. For example, Terminal (on Mac).
A7-3 Check the file permissions of the file to make sure you have execute
permission. See section6.0 File Permissions.
Q8 When I start IBM i Access Client Solutions on a Mac from Finder, a
terminal session pops up and does not go away even after ending
IBM i Access Client Solutions.
A8-1 To eliminate the terminal session from popping up, use the install scripts
for Mac in the QuickStartGuide.
Q9 What is the best way to start the product?
A9-1 You may start the product with any of the three methods in section
7.0 Starting the Product using either the binaries, scripts, or the
command-line. Any method that works in your environment is acceptable.
Q10 Why are there both binary files (Start_Programs) and scripts
(Sample_Scripts) for starting the product?
A10-1 The scripts are not operating system specific and provide a more generic
way to start the product when the platform specific binary file does not work.
A10-2 Some operating systems require binaries when defining file associations.
For most cases, the binary files should be used to start the product.
A10-3 Some environments may have firewalls that restrict access to portions of
IBM i Access Client Solutions. Using one of the binary files to start the
product will make it easier for system administrators to authorize access.
Q11 After installing JDK 8.0 (or higher), I am still getting the following
error:
class cannot be loaded: java.lang.UnsupportedClassVersionError
A11-1 The default version of java being used on your workstation is prior to
JDK 8.0. You will need to use an option that explicitly specifies the
path to the Java home for JDK 8. See section 7.1.2 Finding the Java
Home Path. Use the Java home path for one of the methods described in
either of the following sections:
7.1.1 Starting the Product - Additional Options
7.3 Starting the Product (using the command-line)
Q12 I am not able to import customized keyboard mapping files (.kmp) from
my Windows 5250 emulator sessions.
A12-1 In the initial version of IBM i Access Client Solutions which became
available in July 2012, importing .kmp files from Windows 5250 emulator
session profiles (.ws) was not supported. As of the version which
became available in October 2012, importing .kmp files from 5250
session profiles (.ws) is now supported.
Q13 Keyboard customization for the 5250 emulator is a lot different than it
was on Windows. Do you have any suggestions?
A13-1 Keyboard mapping is divided into categories. From an emulator session:
Click Edit > Preference > Keyboard, or click the Remap button on the
toolbar.
Click the Key Assignment tab.
Select a Category. Default key mappings will appear under the
"Host Functions" and the "Menu Commands" categories.
Select the function you want to assign.
Click Assign a Key.
On your keyboard, press the key (or key combination) you want to assign
to this function.
A13-2 For help on custom key mappings:
Click Edit > Preference > Keyboard, or click the Remap button on the
toolbar. Select the Help button.
Q14 When I try to start the product on Mac OS X 10.8 Mountain Lion, I get
a pop up message indicating the application is not signed.
A14-1 This is a security policy enforced by default beginning with Mac OS X
10.8 Mountain Lion. See the following web page for how to enable the
application to run:
http://macperformanceguide.com/MountainLion-application-signing.html
Q15 I am a user of IBM i Access for Windows, can I migrate my system
configurations to IBM i Access Client Solutions?
A15-1 See section9.6.1 Migrating System Configurations.
Q16 I am a user of IBM i Access for Windows, can I migrate my emulation
profiles to IBM i Access Client Solutions?
A16-1 See section 9.6.2 Migrating 5250 Emulation
Q17 I am a user of IBM i Access for Windows, can I migrate my Data Transfer
request files to IBM i Access Client Solutions?
A17-1 See section9.6.3 Migrating Saved Data Transfer Request Files.
Q18 Does EHLLAPI work with IBM i Access Client Solutions?
A18-1 See section 9.6.4 EHLLAPI
Q19 Does kerberos work with IBM i Access Client Solutions?
A19-1 See section 9.6.5 Kerberos
Q20 I am a system administrator and would like to hide certain functions
from my users.
A20-1 See section 9.5 Customized Packages
Q21 When I select a help icon on a panel, no text is displayed.
A21-1 The help text is normally displayed in the desktop browser. In some cases,
the desktop may not have a browser or it may not be configured correctly.
A21-2 To display the help text without using the desktop browser, set the
following property in the AcsConfig.properties file:
com.ibm.iaccess.javaAwtDesktopAllowed=false
Alternatively, the property may be set from from the command line like
other java properties as follows:
-Dcom.ibm.iaccess.javaAwtDesktopAllowed=false
Q22 When using Data Transfer, I select an Output device of either "Active Excel
Spreadsheet" or "Active Calc Spreadsheet" and I get the following error:
"Active Spreadsheet was not found"
Q22-1 There is no active spreadsheet. Open either a new or existing spreadsheet
and try the request again.
Q22-2 There may be a bitness mismatch between the spreadsheet application you are
using and the Java Virtual Machine running IBM i Access Client Solutions.
See section 9.8 Data Transfer Support for Excel and Calc Spreadsheets
Q23 When using Data Transfer on a Mac, I do not see any options in Output
device for interacting with an active spreadsheet.
Q23-1 Data Transfer is not able to interact with active spreadsheets on Mac due
to the bitness mismatch between the OpenOffice application and the JVM
running IBM i Access Client Solutions. For additional details, see section
9.8 Data Transfer Support for Excel and Calc Spreadsheets.
Q24 When using Data Transfer, I select an Output device of "Active Calc
Spreadsheet" and nothing appears in the Name box.
Q24-1 This is normal for new Calc spreadsheets that have never been saved.
DataTransfer will still be able to update the spreadsheet with downloaded
data.
See the following web page:
IBM i Access Client Solutions (5733XJ1)