IBM i Access Client Solutions: Customization and deployment made easy

Chapter 1: Easily deploy the latest product version to your users

Deployment wizard

Several articles have been written about the features and functions of IBM i Access Client
Solutions. This article provides details about three quick and useful ways to deploy IBM i Access
Client Solutions and provide administrators details on how to exclude functions they do not want
their users to have available. A new wizard included in the October 2015 update can assist in making
these types of deployments even easier.

If you have not already downloaded IBM i Access Client Solutions, refer to the product web page.

This is stated on the product web page and is worth mentioning here:

IBM i Access Client Solutions uses the same IBM i host servers as the other IBM i Access Family
of products and requires the same IBM i Access Family license (5770-XW1) in order to use the 5250
emulation and Data Transfer features.

I’m going to assume that as an IT administrator, you are already familiar with IBM i Access
Client Solutions functions such as 5250 emulation, Data Transfer, Printer Output, Consoles, and so
on and that you most likely have the following two questions:

How can I hide certain functions from my users (for example, Console tasks)?

What is the best way to deploy IBM i Access Client Solutions to my users?

In answer to the first question, a deployment wizard has been added to address this requirement.
The wizard leads you through a series of questions, asking which functions should be available. You
can let your users decide the functions they want to use, or you can limit their options. The wizard
is part of the same script used to deploy the product.

In answer to the second question, the answer is, it depends. Whether you have a few or several
thousand users, a variety of options for deployment are possible.

Some administrators have had success using Java Web Start. That is an excellent solution for both
an initial deployment and for applying updates automatically. It takes a little effort to get it set
up and configured and requires a web server. Setting up Java Web Start is beyond the scope of this
article. So I’ll leave that as an exercise for the reader.

Other administrators have had success with the product and configuration on a flash drive. That
is a good solution for users who need the portability. Even though that type of configuration is
easy to set up, it is a fairly specialized deployment. As such, that too is not covered in this
article.

You can also distribute the product’s compressed archive to every user’s PC. Choosing this option
makes it more challenging for an administrator to restrict functions. This might be the best choice
for some. The greater the number of users you have, the more efficient it will be to have a single
version of the product in a central location that all your users can access for performing product
installations and updates.

Use a central location

The three quick and useful ways to deploy this product, covered in this article, provide the most
benefit when the product is in a central location that can be accessed by all users. A couple of
locations to consider would be a network share or somewhere in the integrated file system (IFS) on
an IBM i system. After you have placed the product’s compressed archive in a central location,
extract its contents.

For example, you can use the following Control language (CL) commands to extract the contents of
the product to a location within IBM i IFS:

Create the directory: /QIBM/UserData/Access/ACS

mkdir '/QIBM/UserData/Access/ACS'

Copy the product’s compressed archive file to the IBM i Access Client Solutions directory created in step 1.

As part of extracting the product’s compressed archive, several directories get created. Make
sure that you can access them from a PC where you want to deploy the product by navigating to IBM i
Access Client Solutions Windows_Application directory. Continuing with the example, the
full path would be:

/QIBM/UserData/Access/ACS/Windows_Application

In the Windows_Application directory, you can see the following two scripts:

install_acs_32.js

install_acs_64.js

In the subsequent sections of this article, you will see the reference,
install_acs_xx.js, where xx is either 32 or 64. “

The script you use depends on whether the PC you are deploying has a 32-bit or a 64-bit
architecture and whether or not you want to run IBM i Access Client Solutions as a 32-bit or a
64-bit process. Note that you can run either a 32-bit or a 64-bit process on a 64-bit PC, but only a
32-bit process on a 32-bit PC. Whichever one you choose, you need to make sure that the PC has
access to a Java™ Runtime Environment (JRE) with the same bitness (32 or 64-bit). At the end
of this article, I’ll mention an option for how to deploy and update the JRE used by IBM i Access
Client Solutions.

Deploying the product from a central location gives administrators the option of customizing the
deployment for their users. Before calling the installacs_xx.js script from the PC where the
product is to be deployed, the administrator can customize what will get deployed by calling the
_install_acs_xx.js script with the /AdminConfig parameter. It does not matter
which of the two scripts the administrator uses to customize the deployment. Any customization done
using /AdminConfig will apply to all future deployments using either
install_acs_32.js or install_acs_64.js. It also does not matter which PC is used
when calling the install_acs_xx.js script with the /AdminConfig parameter..
The customizations done using /AdminConfig cause the product files at the central
location to be updated.

Local and remote

deployments

The two types of deployments mentioned in this article are local and remote. In
a local deployment, the product files are placed locally on the PC. In a remote deployment, the
product files are accessed from a remote location. For either of the deployment types, it is
recommended that you place the product files in a central location that can be accessed by all
users.

To deploy IBM i Access Client Solutions, the install_acs_xx.js script must be called
from the PC where the product is to be deployed. Depending on the type of deployment chosen, the
same script might need to be called again to apply product updates.

When the install_acs_xx.js script is used for local deployments, the product files get
copied to the PC. After an administrator updates the central location with a new version of the
product by extracting the contents of the newer version over the top of the older version of the
product files, the install_acs_xx.js script must be called again from each PC where it was
previously installed.

When install_acs_xx.js is used for remote deployments, the product files are not copied
to the PC. Instead, they are accessed remotely from the PC. In this way, the product files can be
shared by multiple users. Also, remote deployments do not need to call install_acs_xx.js
again to apply product updates. After the administrator updates the product files at the central
location with a newer version, the updates will take effect the next time users start IBM i Access
Client Solutions from their PC.

The administrator can set the deployment type (local or remote) by configuring the product using
the /AdminConfig parameter.

Deployment options

The following options enable you to customize and deploy IBM i Access Client Solutions:

Local and User Customized The product files are copied to each user’s PC. Each user decides for themselves which functions are available.

Local and Admin Customized The product files are copied to each user’s PC. The administrator decides which functions are available.

Remote and Admin Customized The product files are accessed from the shared central location. The administrator decides which functions are available.

Each of these approaches are quick and easy. So choose the option that closely aligns with your
requirements.

Option 1: Local and

User Customized

This type of deployment assumes that you are willing to allow your users to decide for themselves
which functions they want to use. From the PC where the product is to be deployed, run the
install_acs_xx.js script. For example, using Microsoft® Windows® Explorer,
navigate to the central location of the product files and double-click the appropriate
install_acs_xx.js file in the product’s Windows_Application folder.

When install_acs_xx.js is called for the first time, the following actions take
place:

The deployment wizard prompts the user to choose the usable functions.

The user will be asked if product shortcuts on the Desktop are required.

The product files will be copied from the remote location to the local PC: <user_home>\IBM\ClientSolutions

File associations will be created.

If IBM i Access Client Solutions has never run on this PC before, the user will be presented with a license agreement that must be accepted.

Product shortcuts will be placed on the Desktop (depending on the answer provided in step 2).

When the product shortcuts appear on the desktop, the product is ready to be used.

If nothing happens when you try to run the install_acs_xx.js script, open a command prompt and
invoke the script using the wscript command. For example:

cd <path>\Windows_Application
wscript install_acs_64.js

Local and User Customized option: Applying product

updates

To apply product updates, the administrator must first update the product at the central
location. This is done by extracting the contents of a new version of the product on top of the
existing product files. To deploy these updates to the PC, the user should end all IBM i Access
Client Solutions processes and functions on the PC and then run the install_acs_xx.js
script. If you are unsure how to end all IBM i Access Client Solutions processes or have problems
when running the install_acs.xx.js script, log off and then log in and try running the
install_acs_xx.js script again.

During subsequent invocations of install_acs_xx.js, the following actions take place:

The updated product files are copied from the remote location to the local PC: <user_home>\IBM\ClientSolutions

File associations are updated.

The product functions chosen during the initial deployment remain unchanged.

If at any time the user would like to change the functions that are available, the
install_acs_xx.js script can be called with the /Reset parameter. More
information about this option is available in the help text of the command.

Local and User Customized option: Highlights

Here are the highlights for a local and userized deployment:

The product files will be copied from the central location to the local PC.

Each user gets to decide for themselves what functions are available.

To apply product updates to the PC, the install_acs_xx.js script needs to be run again.

The remote location does not need to be available to start the product because all product files are local on the PC.

But what if you don’t want your users deciding for themselves what functions are available? The
remaining two options, allow an administrator to decide which functions are available to their
users.

Option 2: Local and

Admin Customized

With this type of deployment, an administrator configures the deployment at the central location.
When users invoke the install_acs_xx.js script from their PC, the configuration choices made by the
administrator are deployed.

To configure the deployment at the central location, the administrator must call the
install_acs_xx.js script with the /AdminConfig parameter. This can be done
from any PC of the administrators choice. Customizing the configuration with the
/AdminConfig parameter can be done using the install_acs_32.js script or the
install_acs_64.js script. The customizations will be applied to the product files at the central
location and will apply to all future deployments using either of the scripts.

For example, customizing the central location using the
Windows_Application\install_acs_32.js /AdminConfigcommand will deploy the
customizations to any PC invoking either Windows_Application\install_acs_32.js or
Windows_Application\install_acs_64.js

The /AdminConfig parameter starts the deployment wizard and this allows the
administrator to easily customize the deployment type and function availability.

Figure 1 shows the dialog box that is first displayed when the administrator uses the
/AdminConfig parameter.

Click Yes to start with a default version of AcsConfig.properties. If you have
previously edited AcsConfig.properties to add your own customizations, those changes will be lost
and you need to add them back when /AdminConfig has finished. This step could take a
minute depending on the speed of your file system. A command prompt might appear for a minute or
two. Be patient, it will eventually continue.

Figure 3 shows the dialog box that determines whether the install is remote or local.

If you are migrating your users from IBM i Access for Windows and/or Personal Communications, and
they have .ws profiles on their Desktop, that they click to start a 5250 emulation session, you
should answer Yes to the question in Figure 7. By answering Yes, a file association
will be created. Later, when the user clicks a .ws file, the file association causes the IBM i
Access Client Solutions emulator to be used. This assumes the .ws file itself is on the Desktop and
not just a link to the Personal Communications pcsws.exe file with the .ws file as a parameter.

If you change your mind later, you can disable the IBM i Access Client Solutions file association
by going into the IBM i Access Client Solutions GUI, and clicking Tools -> File Associations and
clearing the .ws check box.

The wizard asks similar questions for other functions such as Printer Output, DataTransfer, and
Navigator for i and for managing Secure Sockets Layer (SSL) / Transport Layer Security (TLS)
certificates, hardware management console (HMC) and local area network (LAN) consoles, and so
on.

Figure 8 shows the dialog box with the customization option to include the product shortcuts on
the Desktop.

Keep in mind that you are only customizing the installation for your users. IBM i Access Client
Solutions is not currently being installed on any user PC.

Figure 9 shows the final message box that is displayed when using the /AdminConfig
parameter to customize future deployments.

Figure 9. IBM i Access Client Solutions deployment wizard – finished

You have now successfully customized a preconfigured deployment for your users.

When your users run the install_acs_xx.js script from their PC the following actions take
place:

The product files will be copied from the remote location to the local PC at: <user_home>\IBM\ClientSolutions

File associations will be created.

If IBM i Access Client Solutions has never run on this PC before, the user will be presented with a license agreement that must be accepted.

Shortcuts will be placed on the Desktop.

If you are concerned about users running the /AdminConfig parameter and changing the
configuration, then you should lock down the AcsConfig.properties file in the product’s central
location so they do not have the authority to modify it.

It is also important to know that when an administrator uses the /AdminConfig
parameter to customize the deployment for their users, and if the user specifies the
/Reset or /Exclude parameter when calling install_acs_xx.js, the parameter
will be ignored and the configuration set by the administrator will be used.

Local and Admin Customized option: Applying product

updates

Updates are applied by calling the install_acs_xx.js script again just like the previous
option. However, for this type of deployment, there is one extra step to be performed by the
administrator.

When customizing the product using the /AdminConfig parameter, these customizations
were written to the AcsConfig.properties file in the product’s root directory. When the
administrator updates the product files with a new version by extracting the contents of the new
version on top of the existing files, by default, the AcsConfig.properties file will get overwritten
with a shipped default version. This means that your existing customizations will be lost. There are
two options to fix this:

After extracting the contents of the product’s compressed archive file, use the /AdminRestore parameter on the install_acs_xx.js script to restore a saved version of the AcsConfig.properties file. Note: When using the /AdminConfig parameter to customize the deployment, a copy of AcsConfig.properties is saved to AcsConfig_save.properties. Calling /AdminRestore will restore AcsConfig.properties from the saved version.

The administrator can choose to manually save the AcsConfig.properties file themselves before extracting the contents of a new version of the product. Then after updating the product files with the new version, restore the saved version.

Local and Admin Customized Option: Highlights

Here are the highlights for a Local and Admin Customized deployment:

The product files will be copied from the central location to the local PC.

The administrator decides what functions are available.

To apply product updates to the PC, the install_acs_xx.js script needs to be run again.

The remote location does not need to be available to start the product because all product files are available locally on the PC.

But what if you don’t want to have to update each and every PC every time an IBM i Access Client
Solutions update is released? You might want to use the third option, Remote and Admin
Customized.

Option 3: Remote

and Admin Customized

This type of deployment is similar to the previous option because the administrator configures
the deployment at the central location using the /AdminConfig parameter. Similar to the
previous options, the install_acs_xx.js script is invoked from each PC to deploy the
customized configuration to that PC. There is one significant difference. To apply updates, the
install_acs_xx.js script does not need to be run in order for the users to get the updates
on their PC. That is because the product files only reside at the central location and are never
copied to the local PC.

Figure 10 displays the dialog box that determines a remote or local installation.

For remote installations, the administrator should click Yes. For this type of
deployment, the product files are not copied to the PC invoking the install_acs_xx.js
script. Instead, the product shortcuts added to the Desktop and the file associations created will
point to the product files at the central location.

Remote and Admin Customized option: Applying product

updates

The key advantage to this type of deployment is that when the administrator updates the product
at the central location or decides to change the function availability, the _install_acs_xx.js_script does not need to be run again to pick up the updates. This is because the Desktop
shortcuts and file associations are already pointing to the updated files at the central location.
However, similar to the previous option, the administrator has one more step after updating the
product files because the AcsConfig.properties file would have been overwritten with a shipped
default version. Administrators need to make sure that they restore the customized
AcsConfig.properties file by using /AdminRestore. As an alternative, administrators could choose to
save the AcsConfig.properties file themselves before updating the product files and then restoring
their saved version of the AcsConfig.properties file after applying the update.

Users can begin using the IBM i Access Client Solutions product updates after they stop and
restart all IBM i Access Client Solutions sessions (including all emulation sessions).

Remote and Admin Customized option: What about remote

performance and availability?

Some concerns you may have about this type of deployment are:

What if our network is slow or slows down? Won’t that make IBM i Access Client Solutions run slow?

What if the central location becomes unavailable while I’m using IBM i Access Client Solutions?

These are genuine concerns. But before you decide not to use this type of deployment, consider
the following: When you click Yes to indicate you want multiple users to share a
common location of the product files, caching will be enabled. That means, the first time you start
IBM i Access Client Solutions on the PC or after a product update, the startup time will depend on
the speed of your network and remote file system. But after the cache is updated with the most
recent files, subsequent startup times will be determined not by the speed of the network and remote
file system, but by the speed of the PC just as if the product had been installed directly to the
PC.

The central location will always need to be available to start IBM i Access Client Solutions for
this type of deployment. But once IBM i Access Client Solutions has started, the product files at
the central location are not accessed. In fact, the central location where the product files exist
could even be disconnected and IBM i Access Client Solutions will continue to run. If the central
location is not accessible, even though existing IBM i Access Client Solutions sessions continue to
run, you might not be able to start new sessions. For example, let’s say you start 5250 sessions by
double-clicking a .hod file on your Desktop. If you already have a 5250 session active, it will
remain active and you can start other 5250 sessions from that existing session. However, you will
not be able to start another 5250 session by double-clicking a .hod file on your Desktop until the
central location comes back online.

Remote and Admin Customized option: Highlights

Here are the highlights for a Remote and Admin Customized deployment:

The product files will not be copied from the central location to the local PC.

The administrator decides which functions are available.

Updates and configuration changes are picked up automatically by stopping and restarting IBM i Access Client Solutions.

The remote location must be available to start the product.

Prompts and warnings while running install_acs_xx.js

When running the install_acs_xx.js script, depending on the security settings on your
PC, you might see prompts as shown in Figure 11 and Figure 12. The dialog box as shown in Figure 11
might appear when you first invoke the install_acs_xx.js script.

Figure 11. Windows security warning for install_acs_64.js

Click Open to run the script.

The dialog box as shown in Figure 12 is displayed toward the end of running the
install_acs_xx.js script when it invokes acslaunch_win-64.exe (or acslaunch_win-32.exe if
you are using install_acs_32.js).

Figure 12. Windows security warning for acslaunch_win-64.exe

Click Run to allow the installation to continue.

If IBM i Access Client Solutions has never been run before on the PC, the license agreement page
as shown in Figure 13 is displayed. You need to read and accept it for the installation to
continue.

Figure 13. End User License Agreement page

When the product shortcuts appear on the Desktop, IBM i Access Client Solutions is ready to be
used.

Installation location

and log

For local installations, the install_acs_xx.js scripts copy the product files to:

<user_home>\IBM\ClientSolutions

An install log is kept at:

<user_home>\IBM\install_acs_log.txt

Trace records are added to this log each time the install_acs_xx.js script is invoked. This can
be used by administrators to track updates on the PC and can also be used by IBM service teams for
debugging IBM i Access Client Solutions product installation or update problems.

Changing

customizations or deployment type

An administrator can use the /AdminConfig parameter to make a change to the
configuration at the central location. Each time /AdminConfig is used, the
configuration changes are appended to the AcsConfig.properties file. To remove previous changes made
by /AdminConfig to the AcsConfig.properties file, click Yes as shown
in Figure 14.

Clicking Yes removes all previous changes made to AcsConfig.properties by
/AdminConfig and also any changes you may have manually added. If you click Yes,
you need to manually add your changes back to AcsConfig.properties after /AdminConfig completes. If
you click No, you are responsible for making sure AcsConfig.properties does not
have multiple entries for the same property.

For local deployments, the install_acs_xx.js script will need to be run to apply the
configuration updates to the PC.

Optional JRE

deployment

As a platform-independent application, IBM i Access Client Solutions requires a JRE. In most
cases, PCs already have a JRE that IBM i Access Client Solutions can use for its runtime environment. As Java updates become
available, users should update the version of Java on their PC just like they do for other
applications. This is how most people have been using IBM i Access Client Solutions. If that works
for you, then feel free to skip the rest of this section.

It is possible that some of your users might not have a JRE installed. It is also possible and
very common for a PC to have more than one JRE installed. When starting IBM i Access Client
Solutions, the first JRE found is the JRE used to start the product. If, as an administrator, you
decide to deploy a JRE with IBM i Access Client Solutions or you want to control what JRE is being
used by IBM i Access Client Solutions, this section describes one of the ways you can easily deploy
a specific JRE with the IBM i Access Client Solutions product files.

After extracting the compressed archive of the product, navigate to the Start_Programs
directory. It contains two sub-directories and each of those contains a Windows executable file.

Start_Programs\Windows_i386-32\acslaunch_win-32.exe

Start_Programs\Windows_x86-64\acslaunch_win-64.exe

Those .exe files are used to start IBM i Access Client Solutions as either a 32-bit or a 64-bit
process. The desktop shortcuts and file associations created by the install_acs_xx.js script use
these .exe files to launch IBM i Access Client Solutions. In order to launch IBM i Access Client
Solutions, these executable files look for a JRE on the PC in predefined locations and then use that
JRE to launch IBM i Access Client Solutions.

One of the ways to control which JRE is used to run IBM i Access Client Solutions is to put the
JRE you want IBM i Access Client Solutions to use next to the acslaunch_win_xx.exe file. That of
course is easier said than done, so let me give you some pointers.

First, make sure you have a current version of Java installed on a PC. One way to check if Java
is already installed is to open a command prompt and type the java –version
command.

The format and output of this command can vary significantly, but you should get something that
tells you the version and bitness.

In this example, I have version 1.8 update 60 for a 64-bit enabled PC.

The JRE consists of several files and directories. You’ll need to copy its root directory and all
of its containing files and sub-directories next to the corresponding acslaunch_win-xx.exe. Make
sure you correctly pair the bitness of the JRE with the bitness of the acslaunch_win-xx.exe. You
also need to be aware that JREs are platform specific. So make sure you have a JRE that contains
both the correct bitness and is for Windows. You may not need both 32 and 64 bit JREs if your users
are either all 32-bit or all 64-bit. But, if you have both, then you’ll also need both JREs.

The first place to look for a JRE is in the Program Files folder. Oracle put mine
here:

C:\Program Files\Java\jdk1.8.0_60\jre

To verify the version and bitness, you can use the same command you used above, but specify the
entire path to the JRE’s java.exe:

C:\Program Files\Java\jdk1.8.0_60\jre\bin\java.exe ‑version

If you don’t have a version of Java in Program Files, get a JDK download from Oracle and install
it. You could search your entire C: drive and probably find other JREs included with other
applications. But you really want to use a JRE where you control the updates and not some other
application. The JRE identified here in Program Files is not tied to any specific application and
will get updated when Java updates are installed.

In the event a future Java update moves the JRE to some other location and you have no idea where
to find it, open Windows Explorer, select the C: drive, and search the entire C: drive for jvm.dll.
My PC returned several results including the one in this example:

C:\Program Files\Java\jdk1.8.0_60\jre\bin\server\jvm.dll

Just be aware, doing that will find all the JREs on your PC and you really should only copy the
one where you control when it gets updated.

The jre directory contains a handful of files and also a lib and bin
sub-directory which contains several other files and sub-directories. With the JRE now in hand, you
need to copy it where IBM i Access Client Solutions can use it. To continue the above example of
using /QIBM/UserData/Access/ACS as our central location for the IBM i Access Client Solutions
product files, the following command can be used to copy the 64-bit JRE.

In this example, I previously mapped a network drive (K:) to the ROOT of my IBM i file
system.

If you need a 32-bit JRE, you’ll need to install and locate a 32-bit JRE and copy it next to:

Start_Programs\Windows_i386‑32\acslaunch_win‑32.exe

JRE deployment considerations

If you have decided to include the JRE as part of your deployment for IBM i Access Client
Solutions, there are several things you should consider.

If you have made the JRE part of your deployment, Java updates will not get applied automatically
to the JRE used by IBM i Access Client Solutions. You need to manually update the JRE with a newer
version at the central location by following the previous steps mentioned.

If you are using either deployment option 1 or option 2, the install_acs_xx.js script
will copy the JRE along with the product files to the local PC during the initial installation or
any product update. So, when you update the product files to a new version, you also need to
consider updating the JRE. They do not have to be updated at the same time and it is fine to update
one without the other.

If you are considering deployment option 3, including the JRE might not be the best choice for
this type of deployment. While we have added performance optimizations through caching when the IBM
i Access Client Solutions product is running from a remote location, we are not able to do that for
the JRE. So the startup performance might vary depending on your network and file system performance
of the central location. In addition, if for some reason the central location where the JRE resides
goes offline, whether an active session for IBM i Access Client Solutions is able to keep
functioning properly is unpredictable and might actually hang. This does not happen when the JRE
resides on the local PC.

Having the IBM i Access Client Solutions product files at a remote location is not a problem
because once the Java Virtual Machine (JVM) starts, all of the IBM i Access Client Solutions product
files become resident inside the JVM. As long as the JRE is local and IBM i Access Client Solutions
has already started, IBM i Access Client Solutions will in most cases be immune to a network outage
involving the central location. That is of course until you need to restart IBM i Access Client
Solutions. For remote IBM i Access Client Solutions deployments, the central location must be online
to start IBM i Access Client Solutions.

Summary

This article explained three quick and simple ways to deploy IBM i Access Client Solutions. Each
one has its own merits. Adding an optional JRE to the deployment would give administrators an
installation solution where they also control what JRE is used and when it gets updated.