Upgrade procedure

Before you begin

Verify that the user running the installation process has the following authorization requirements:

Windows™ operating systems

If you set the Windows User Account Control (UAC), your login account must be a member of the Windows™ Administrators group or domain administrators with the rights Act as Part of the Operating System.
You must run the installation as administrator.

UNIX™ and Linux™ operating systems

You must have root access.
Ensure that you downloaded the HCL Workload Automation agent eImage (for details, see the Download Document at Product Requirements).
Ensure that you have enough temporary space before starting the installation process.

About this task

To upgrade agents, from the directory that contains the HCL Workload Automation agent eImage, run the twsinst script using the synopsis described below.

twsinst for Windows™ is a Visual Basic Script (VBS) that you can run in CScript and WScript mode, for example:

cscript twsinst.vbs -update -uname username -acceptlicense yes

A successful upgrade using the twsinst script issues the return code RC = 0. If the upgrade fails, to understand the cause of the error see Synopsis.

Synopsis:

Windows™ operating systems

Show command usage and version

cscript twsinst.vbs -u | -v

Upgrade an instance

cscript twsinst.vbs -update -uname user_name 
 -acceptlicense yes|no
 [-addjruntime true]
 [-inst_dir install_dir [-recovInstReg true]]
 [-lang lang_id]
 [-patch]
 [-skipbackup]
 [-skipcheckprereq]
 [-skip_usercheck]
 [-wait minutes]
 [-work_dir working_dir]

UNIX™ and Linux™ operating systems

Show command usage and version

./twsinst -u | -v

Upgrade an instance

./twsinst -update [-uname user_name]
 -acceptlicense yes|no
 [-addjruntime true]
 [-create_link]
 [-inst_dir install_dir [-recovInstReg true]]
 [-lang lang-id]
 [-reset_perm]
 [-patch]
 [-skipbackup]
 [-skipcheckprereq]
 [-skip_usercheck]
 [-wait minutes]
 [-work_dir working_dir]

-acceptlicense yes|no: Specify whether or not to accept the License Agreement.

-addjruntime true

Adds the Java™ run time to run job types with advanced options to the agent. The run time environment is used to run application job plug-ins on the agent and to enable the capability to run remotely, from the agent, the dynamic workload broker resource command on the server.

This option is applicable to both fault-tolerant agents and dynamic agents.

Note: Only for version 10.1 and subsequent fix packs, the addjruntime parameter is ignored and Java runtime is always installed automatically.

-create_link

UNIX™ operating systems only. Create the symlink between /usr/bin/at and install_dir/TWS/bin/at. For more information, see Symbolic link options.

-inst_dir install_dir

The directory where you installed HCL Workload Automation. When upgrading, the directory inst_dir is used whether:

The upgrade process cannot retrieve the product install location from the registries.
You need to create the HCL Workload Automation registries again before upgrading. See Re-creating registry files using twsinst for details.

If you do not provide the inst_dir directory and HCL Workload Automation cannot retrieve it from the installation registries, the product is installed in the user home directory.

On Windows™ operating systems:: If you specify a path that contains blanks, enclose it in double quotation marks. If not specified, the path is set to %ProgramFiles%\IBM\TWA.
On UNIX™ and Linux™ operating systems:: The path cannot contain blanks. If not specified, the path is set to the user_name home directory.

-lang

The language in which the twsinst messages are displayed. If not specified, the system LANG is used. If the related catalog is missing, the default C language catalog is used.

Note: The -lang option does not relate to the supported language packs. By default, all supported language packs are installed when you install using the twsinst script.

-password

Windows system only. The password of the user for which you are installing HCL Workload Automation. The password is not required for the upgrade procedure.

-recovInstReg true

To re-create the registry files. Specify if you tried to upgrade a stand-alone, fault-tolerant agent (an agent that is not shared with other components or does not have the connector feature) and you received an error message that states that an instance of HCL Workload Automation cannot be found. This error can be caused by a corrupt registry file. See Upgrading when there are corrupt registry files. If you specify this parameter you must set -inst_dir option.

-reset_perm

UNIX™ systems only. Reset the permissions of the libatrc library.

-skipcheckprereq

If you specify this parameter, HCL Workload Automation does not scan system prerequisites before installing the agent. For more information on the prerequisite check, see Scanning system prerequisites for HCL Workload Automation.

- patch

Specifies that a patch must be installed. When you specify this option, only the files present in the patch package are replaced in the installed product and all other product files remain unchanged.

-skipbackup

If you specify this parameter the upgrade process does not create a backup of the instance you are upgrading. If the agent upgrade fails, the agent cannot be restored. If you do not specify this parameter, the upgrade process creates a backup of the agent instance in the path work_dir>/backup. The work_dir> is a temporary directory used by the upgrade process. It can be defined by passing the parameter -work_dir to the twsinst script. If you do not define the work_dir then by default it is set to /tmp/TWA_${INST_USER}/tws94, where tmp is the temporary directory of the operating system and ${INST_USER} is the user performing the upgrade. For example, /tmp/TWA_jsmith/tws94/backup.

-skip_usercheck

Enable this option if the authentication process within your organization is not standard, thereby disabling the default authentication option. On UNIX™ and Linux™ operating systems if you specify this parameter, the program skips the check of the user in the /etc/passwd file or the check you perform using the su command. On Windows™ operating systems if you specify this parameter, the program does not create the user you specified in the -uname username parameter. If you specify this parameter you must create the user manually before running the script.

-uname username

The name of the user for which HCL Workload Automation is being updated. The software is updated in this userʼs home directory. This user name is not to be confused with the user performing the upgrade.

-update

Upgrades an existing agent that was installed using the twsinst script.

-wait minutes

The number of minutes that the product waits for jobs that are running to complete before starting the upgrade. If the jobs do not complete during this interval the upgrade does not proceed and an error message is displayed. Valid values are integers or -1 for the product to wait indefinitely. The default is 60.

-work_dir working_dir

The temporary directory used for the HCL Workload Automation upgrade process files deployment.

On Windows™ operating systems:: If you specify a path that contains blanks, enclose it in double quotation marks. If you do not manually specify a path, the path is set to %temp%\TWA\twsversion_number>, where %temp% is the temporary directory of the operating system.
On UNIX™ and Linux™ operating systems:: The path cannot contain blanks. If you do not manually specify a path, the path is set to /tmp/TWA/twsversion_number>.

What to do next

When the agent upgrade completes, the agent is restarted and quickly reconnects with its jobs. Any jobs that were actively running before the upgrade that have not yet completed, continue to run, and any jobs that successfully finished running during the upgrade procedure report a successful job status. An automatic backup and restore feature is in place in case of failure.