Setting up IBM i Access Client Solutions

· 19 min read · Software

Log in to save

IBM i Access Client Solutions (ACS) is a single Java package, IBMiAccess_v1r1.zip, the same for Windows, macOS and Linux. The current version is 1.1.9.16, dated 8 September 2026, and IBM plans the next one for November 2026. This page follows the order in which things are needed: Java, download, installation, first system, 5250 session, and at the end what to look at when it does not start.

Java first

ACS is written in Java, but Java is not in the package: it has to be installed separately on the PC, and until it is there ACS does not start. IBM states it is supported on Java 8 or higher and recommends the current update of an LTS (Long Term Support) version.

Java version Type With ACS
8, 11, 17, 21, 25 LTS the ones IBM lists
26 not LTS 5250 does not work (see below)

IBM names three free distributions, all available for Windows, Mac and Linux:

Oracle's Java works, but for business use IBM warns that the Oracle licences need reading: public updates of Oracle Java 8 released after January 2019 require a commercial licence.

What to install depends on the operating system:

System What is needed
Windows the JRE is enough
macOS the JDK. The JRE for Mac installs Java for the browser only, and ACS does not see it
Linux a Java 8 or higher reachable through the java command

To see what is already there:

java -version

Java 26 and 5250. With a Java 26 distribution, starting a session gives Invalid Session Profile. No sessions could be started because this is not a valid session profile, or Session Manager and the session open a tiny window that stays blank when enlarged. IBM attributes it to changes in Java 26 that the emulator is incompatible with, and the fix it gives is to remove Java 26 and install an LTS version. The session profile is not damaged.

Downloading the package

The base package is downloaded from ibm.com/resources/mrs/assets?source=swg-ia. IBM makes it available to customers with an IBM i software maintenance contract. It is also on Entitled Systems Support (ESS), under 5761-SS1 or 5770-SS1.

The same page lists the optional packages, which are not needed to use ACS: they are the drivers for people writing applications.

Package What it adds
Windows Application Package ODBC, .NET, OLE DB
Linux Application Package ODBC with unixODBC
Mac Application Package ODBC with unixODBC, for Intel and Apple Silicon from macOS 12
PASE Application Package ODBC on IBM i, from 7.3

Installing

Once the zip is extracted, each system has its own folder with the install script.

System What to run Where it goes
Windows, one user Windows_Application\install_acs_64.js (double-click) IBM\ClientSolutions in the user's folder
Windows, all users Windows_Application\install_acs_64_allusers.js \Users\Public\IBM\ClientSolutions
macOS Mac_Application/install_acs (double-click) the application in Applications, the files in /usr/local/ibmiaccess
Linux sudo ./install_acs_64 from Linux_Application /opt/ibm/iAccessClientSolutions

On Windows, if the question about icons is answered yes, Access Client Solutions and ACS Session Mgr are left on the desktop. On Mac the script opens a Terminal window, which can be closed once it has finished.

What the installer asks

On a first installation the script asks which functions are wanted. This is where what will appear in the main window gets decided, and four answers have "no" preselected: confirming everything without reading leaves you without the SQL tools.

Question Preselected What is lost by answering no
Do you want to use 5250 emulation? yes 5250 Emulator and Session Manager
Do you want to view printer output? yes Printer Output
Is it ok to view printer output for all users? no viewing other users' spooled files
Do you want to use the Integrated File System? yes Integrated File System
Do you want to transfer data to/from spreadsheets? yes Data Transfer
Do you want to use Navigator for i? yes launching Navigator for i
Do you need to manage SSL/TLS certificates? yes Key Management
Do you need to use Database tools? no Run SQL Scripts, Schemas, SQL Performance Center
Do you need to use an HMC or LAN console? no 5250 Console, Virtual Control Panel, hardware interfaces
Do you need to issue remote commands? no remote commands from the command line
Do you need to use the System Debugger? no System Debugger

Windows asks two more: whether to make ACS the default program for existing 5250 profiles, and whether to put the icons on the desktop.

The answers end up in AcsConfig.properties, next to acsbundle.jar, on the com.ibm.iaccess.ExcludeComps line. There are two ways to change them later:

  • run the script again with /Reset, which asks the questions again:

    ./install_acs /Reset

  • edit the line by hand. This one, for instance, excludes only consoles and remote commands and keeps the database tools:

    com.ibm.iaccess.ExcludeComps=opconsole,hwconsole,rmtcmd

The keywords are EMULATOR, SPLF, IFS, DATAXFER, L1CPLUGIN, KEYMAN, DATABASE, OPCONSOLE, HWCONSOLE, RMTCMD, DEBUGGER, SSH. Removing a function here removes it from the ACS window on that PC, and does not change what the profile is allowed to do on the system.

Without installing

Extracting the zip is already an installation: IBM says so, and it holds for a network folder or a USB stick too. It is started with the executable in Start_Programs:

System Executable
Windows Start_Programs\Windows_x86-64\acslaunch_win-64.exe
macOS Start_Programs/Mac_i386-32_x86-64/acslaunch_mac
Linux Start_Programs/Linux_x86-64/acslaunch_linux-64

or, wherever Java is available:

java -Xmx1024m -jar /path/acsbundle.jar

IBM gives one gigabyte of heap (-Xmx1024m) as the recommended minimum for this form: below that, using several functions together ends in an OutOfMemoryException.

macOS

On a Mac there are four places where people get stuck, and three of them are about Java.

macOS has no Java. A JDK has to be installed, as said above. Until it is there, the application opens and closes again with no message at all: it looks for Java, does not find it, and the error is not shown. This is the "double-click and nothing happens" case.

Which Java it uses. The installed application does not choose: it uses the JAVA_HOME variable if it exists, otherwise it asks macOS through /usr/libexec/java_home. With several JDKs installed that command returns just one, normally the most recent. To see the list and the one chosen:

/usr/libexec/java_home -V
/usr/libexec/java_home

This is how a Mac ends up on Java 26 without anyone deciding it: installing the latest JDK for some other program is enough, and from the next day ACS starts with that one. The version in use can also be read inside ACS, under Help → About, on the java.home line.

Going back to an LTS version. The route IBM gives is to uninstall Java 26. JDKs live in /Library/Java/JavaVirtualMachines/, one folder per version. To start ACS with a specific version without uninstalling anything, from Terminal:

"$(/usr/libexec/java_home -v 21)/bin/java" -jar /usr/local/ibmiaccess/acsbundle.jar

-v 21 asks for Java 21; any version in the list will do.

macOS blocks install_acs. The script comes from the internet and is not a signed application, so on a double-click macOS may refuse to run it. IBM says to right-click install_acs and choose Open. Where that entry does not appear, go to System Settings → Privacy & Security and authorise it there with Open Anyway. This applies to the script only: the application it produces is signed and notarised by IBM and opens normally.

The script asks for the administrator password the first time, because it creates /usr/local/ibmiaccess.

The first system

On first start the main window has no systems. One is added from System Configurations, in the Management group, then New.

General tab.

  • System name: the host name or the IP address. To get started it is the only required field.
  • Description: free text.
  • Group name: systems can be grouped, with the Groups button of System Configurations.
  • Use SSL for connection: encrypts connections to that system.

Connection tab. It decides when ACS asks for user and password.

Option What it does
Use shared credentials prompts once, and the credentials are shared by every system using this option, until the user logs off the PC
Use default user name to prompt once for each system prompts once per system, until the user logs off the PC
Prompt for user name and password every time prompts on every connection
Use Kerberos authentication; do not prompt uses the current Kerberos credentials

On the same tab, IP address lookup frequency sets how often ACS queries DNS: from Always to Never - Specify IP Address, which pins the address by hand.

OK saves; Save/New saves and opens another system straight away.

Checking that it answers

In the system configuration, Verify Connection tries to connect to the IBM i host servers and shows the status of each. Not all of them are needed: it depends on the functions in use. When they fail, IBM gives three causes: a firewall, the network, or a server not started on the system. For the last one the command is:

STRHOSTSVR SERVER(*ALL)

5250, on the other hand, goes through the Telnet server, on port 23 unless it has been changed.

Encrypted connections

With SSL on, on the first connection ACS asks to accept the system's certificate authority if it is not already in its store. Certificates are managed from Tools → Key Management. To have SSL ticked on every new system: Edit → Preferences, General tab, Default communication to SSL. It does not touch systems already configured.

On an IBM i 7.6 system with multi-factor authentication enabled, ACS asks for password and additional factor at least once, whatever is chosen on the Connection tab.

The 5250 session

With the system picked in the System box, 5250 Emulator opens the session. The parameters are under Communication → Configure.

Field Default What it is for
Session Name the name on the window
Workstation ID assigned by the system the name of the display device
Screen Size 24x80 the other size is 27x132
Host Code Page the one for the PC's language must match the system's
Destination Port 23
Auto-Connect, Auto-Reconnect Yes

Workstation ID accepts special characters, useful when several sessions need predictable names:

You type It becomes
* the session letter, A to Z: ACCT* gives ACCTA, ACCTB, ACCTC
% S for a display session, P for a printer
= a generated character, if the name is already in use on the system
&COMPN, &USERN the computer name, the user name

Saving the profile

The configured session is saved in an .hod file. Saved ones show up in 5250 Session Manager, from which they are started. Communication → Set As Default Profile makes a session the template for new ones.

An .hod file can be copied and handed out. On a Mac, for a double-click to open it with ACS, it has to be associated once: with the file selected, File → Get Info, under Open with choose IBM i Access Client Solutions and then Change All.

Keyboard

Edit → Preferences → Keyboard, Key Assignment tab. Pick the category (Host Functions for Enter, Reset, Field Exit and the other 5250 keys), then the function, then Assign a Key and the key to press. Search for Key tells whether a key is already assigned. The map is saved in a .kmp file.

Colours and watermark

Edit → Preferences → Color changes colours by field type; the Other → Screen Background entry changes the background of the whole screen. Giving the production session a different background from the test one is the most direct way to see which system Enter is about to be pressed on.

The watermark does the same job: a see-through text on the screen. It accepts variables: &SYSNAME writes the system name, &SYSDESC its description, &NAME the session name.

Coming from Client Access

IBM i Access for Windows files are not compatible, and are converted:

From To Where
configured systems File → Copy Connections in the main window
.ws profile, .bch batch .hod, .bchx Session Manager, File → Import, or by dragging the file in
.kmp keyboard .kmp in a different format as above
.dtf, .dtt transfers .dtfx, .dttx Data Transfer, Actions → Data Transfer Migration

The console on old releases

5250 Console opens the system console, LAN or HMC. Two things have to be done first: having answered yes to Do you need to use an HMC or LAN console? during installation, and having filled in the system's Console tab with the Service host name. The console connection is always encrypted, and ACS asks for Service Tools credentials.

Towards a system stuck on an old release, such as 7.1 or 7.2, the console may fail to connect. There are two causes, best looked at in this order.

The console certificate. On old releases that are behind on PTFs the console presents a certificate that today's Java rejects. The errors are MSGSSL002, MSGSSL004 or MSGSSL007. The fix IBM gives as the correct one is the PTFs:

Release PTF Requires
6.1.1 MF60292
7.1 MF60291 MF99010
7.2 MF60290 MF99102

TLS 1.0. It is a deprecated protocol, and current Java versions disable it: together with TLS 1.1 it sits in the jdk.tls.disabledAlgorithms list of the java.security file. A system whose console only speaks TLS 1.0 finds no protocol in common with the PC, and Java answers No appropriate protocol (protocol is disabled or cipher suites are inappropriate). To connect, it has to be re-enabled on the PC.

Re-enabling TLS 1.0

The file is under the Java folder, the one ACS shows under Help → About on the java.home line:

Java Path of the file
11 and later conf/security/java.security
8 lib/security/java.security, or jre/lib/security/java.security in a JDK

The line to change is in there. In Java 21 and 25 it is this one:

jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, DTLSv1.0, RC4, DES, \
    MD5withRSA, DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, \
    ECDH, TLS_RSA_*, rsa_pkcs1_sha1 usage HandshakeSignature, \
    ecdsa_sha1 usage HandshakeSignature, dsa_sha1 usage HandshakeSignature

Remove TLSv1 and, if needed, TLSv1.1, leaving the rest as it is. In other Java versions the list is different: always start from the line in your own file, not from this one.

There are two ways to do it, and the first is the one to prefer.

A separate file, for ACS only. Copy the line, already corrected, into a new file, for instance acs-tls10.security, and start ACS pointing at it:

java -Djava.security.properties=/path/acs-tls10.security -jar /usr/local/ibmiaccess/acsbundle.jar

TLS 1.0 comes back for that run of ACS only. The rest of the PC keeps using Java with its protections, and so does ACS when opened from its icon. On Windows the command is the same, with the path of acsbundle.jar inside IBM\ClientSolutions. Adding /PLUGIN=console /SYSTEM=name at the end opens that system's console directly.

Editing java.security. Change the line in Java's own file. It applies to every program using that Java, not just ACS, and has to be redone on every Java update, which brings a new file.

Re-enabling TLS 1.0 lowers the security of the PC. For the java.security edit, IBM warns that it affects anything using that Java and exposes you to sites still using the old ciphers. It is a stopgap for reaching the console of a system that cannot be upgraded yet: the right route remains bringing the system to a supported release.

If the console still does not connect after the change, the reason is in the logs: Tools → Generate Service Logs right after the error, then Tools → Package Service Logs.

Where the configuration lives

Each user has their own, in a folder that depends on the operating system. It is shown under Edit → Preferences → Local Settings, in Configuration Root.

To Use
save it or move it to another PC, even on a different operating system File → Export Configuration
load it back File → Import Configuration

Importing replaces: any existing configuration that is not in the imported file is lost.

The other tools

Entry What it does
Run SQL Scripts SQL editor with results in a grid and Visual Explain, from the Explain and Run and Explain entries
Schemas the database objects
SQL Performance Center the SQL performance analysis tools
Data Transfer data between IBM i and PC files: .xlsx, .ods, .csv
Printer Output spooled files, to view and download
Integrated File System the IFS: view, upload, download
Navigator for i opens Navigator for i in the browser
SSH Terminal an SSH terminal to the system. It appears if the PC has an SSH client: Mac and Linux have one by default, on Windows it has to be installed

The first three are there only if Database tools was answered yes during installation.

An example from Run SQL Scripts. Active jobs ordered by CPU time, which is what WRKACTJOB shows, but filterable and exportable:

SELECT JOB_NAME, SUBSYSTEM, AUTHORIZATION_NAME,
       CPU_TIME, ELAPSED_CPU_PERCENTAGE
  FROM TABLE(QSYS2.ACTIVE_JOB_INFO())
 ORDER BY CPU_TIME DESC
 FETCH FIRST 20 ROWS ONLY;

An example from the command line. A transfer saved from Data Transfer is a .dtfx file, and it can be run again without opening the window, so from a scheduled task too:

acslaunch_win-64.exe /PLUGIN=download C:\transfers\orders.dtfx

The file name is an example.

Updating

IBM releases ACS several times a year and recommends always using the latest version, because updates also close security problems: that was the case with 1.1.9.14.

  • Help → Check for Updates tells whether a new version exists.
  • Update by running the install script of the new version, the same way as the first time. The configuration stays, and AcsConfig.properties is not overwritten.
  • Help → About confirms the installed version.

Java is updated separately, from the chosen provider, and needs keeping current in the same way.

If it does not start

What happens Cause What to do
Double-click, nothing happens Java is not installed, or the file lacks execute permission install Java; start from the command line to read the error
Error loading Java module. the executable cannot find Java on Windows and Linux: set JAVA_HOME, or the -vm <path> option, or copy the JRE folder next to the executable
java.lang.UnsupportedClassVersionError Java older than 8 install an LTS version
Invalid Session Profile, or a tiny blank 5250 window Java 26 switch to an LTS version
The console does not connect to a 7.1 or 7.2: MSGSSL002, MSGSSL004, No appropriate protocol old certificate, or TLS 1.0 disabled in Java see "The console on old releases"
Permission denied execute permission missing chmod a+rx <file>
On Mac a Terminal window stays open ACS started from acslaunch_mac install with install_acs

On Windows JAVA_HOME may work from the prompt and not on a double-click: in that case it has to be defined as a system variable.

Which versions it works on

ACS connects to any supported IBM i release and uses the same host servers as the other IBM i Access products. It can be downloaded by customers with IBM i 7.3 or later and current entitlement.

  • On the PC: Java 8 or higher, in an LTS version.
  • From 1.1.9.1, 5250 emulation and Data Transfer no longer require the IBM i Access Family licence.
  • The additional-factor prompt concerns IBM i 7.6, where multi-factor authentication exists.
  • Mac Application Package: from macOS 12, Intel and Apple Silicon.

What is written here was read in the 1.1.9.16 documentation.

Sources

#acs #5250 #emulatore #java #macos #strumenti
← Back to blog

You might also like

Comments

No comments yet. Be the first to comment!

You need an account to comment. Log in · Sign up