Installing agents on IBM i systems

Learn how to install agents on IBM i systems.

About this task

To install the agents on IBM i systems, use the twsinst installation script.

You can either use the default QSECOFR user or create a new user with ALLOBJ authority. If you plan to use a user different from QSECOFR, create the user before the installation and assign it the ALLOBJ authority.

To install the agents, perform the following steps:
  1. Sign on as the user of your choice, either QSECOFR or an existing user with ALLOBJ authority. If you use a user different from QSECOFR, specify the allObjAuth parameter to indicate that the specified user has the ALLOBJ authority. Ensure the user is existing and has ALLOBJ authority because the product does not verify that the correct authority is assigned. For more information about this parameter, see Agent installation parameters on IBM i systems.
  2. Create an IBM i user profile for which the HCL Workload Automation agent is installed.
    Note: The user profile is not the same as for the user that is performing the installation. Instead the user profile is for the user that you specify in the -uname username parameter when running the twsinst script. For descriptions of the syntax parameters, see Agent installation parameters on IBM i systems. You cannot use an existing IBM i system user profile, an application supplied user profile, or any of the following reserved IBM i user profiles:
    • QDBSHR
    • QDFTOWN
    • QDOC
    • QLPAUTO
    • QLPINSTALL
    • QRJE
    • QSECOFR
    • QSPL
    • QSYS
    • QTSTRQS
    Attention: Consider that:
    • If the user profile is a member of a group, the installation fails. Set the group profile that is associated with the user profile to *NONE.
    • If the username is longer than 8 characters, after the installation the agent (and the JobManager component) runs under the QSECOFR user instead of under the authority of the installation user. To prevent this problem, set the PASE_USRGRP_LIMITED environment variable to N.
  3. On the IBM i system, verify that no library exists with the same name as the user profile supplied for the agent user.
  4. Download the IBM i agent eImage from HCL License Portal. For more information about the installation media, see Downloading installation images on your workstation or the Download Document at Product Requirements.
  5. To untar or unzip the agent eImage, you can use the PASE shell or the AIXterm command.
    Using PASE shell:
    1. Open the PASE shell.
    2. Run the command "CALL QP2TERM".
    3. Locate the folder where you downloaded the agent eImage and run the command:
      HCL Workload Automation Agent
      "tar xvf TWSversion_number>_IBM_I.tar"
      Dynamic Agent
      "unzip TWSversion_number>_IBM_I.zip"
    4. Exit from the PASE shell.
    Using AIXterm command:
    1. Start the Xserver on your desktop.
    2. On the iSeries machine, open a QSH shell and export the display.
    3. In QSH shell, go to the directory /QopenSys and run the command "aixterm -sb".
    4. A pop-up window is displayed on your desktop. By Using this pop-up window, unzip the TWSversion_number>_IBM_I.zip file, or untar the TWSversion_number>_IBM_I.tar file.
  6. If your machine's primary language is other than English, carry out these steps:
    1. Add English as secondary language.
    2. Ensure that when connecting to the environment the Host Code-Page is set to 037
    3. Before starting the installation, verify that the Qshell session is configured correctly and type the following command in the <yourfilename> : 
      echo " key key2 " | sed 's/ *$//g' | sed 's/^ *//g'
    4. Run the <yourfilename>
    5. The environment is configured in the correct way if the output is: "key key2".

  7. Open a QSH shell and run the twsinst script. During the installation process, the product creates an IBM i library and a job description with the same name as the user profile created in Step 2.

    The installation procedure adds this library to the user profile library list of the dynamic agent user profile and sets this job description as the job description of the dynamic agent user profile. By default, the software is installed in the user's home directory.

If the installation fails to understand the cause of the error, see Analyzing return codes for agent installation, upgrade, restore, and uninstallation.
After a successful installation, perform the following configuration task:
Command usage and version
Show command usage and version
twsinst -u | -v
Install a new instance
twsinst -new -uname username
   -acceptlicense yes|no 
   [-addjruntime true|false]
   [-agent dynamic]
   [-allObjAuth]
   [-company company_name]
   [-displayname agentname]
   [-gateway local|remote|none]
   [-gweifport gateway_eif_port]
   [-gwid gateway_id]
   [-hostname hostname]
   [-inst_dir install_dir]
   [-jmport port_number]
   [-jmportssl true|false]
   [-lang lang_id]
   [-tdwbport tdwbport_number]
   [-tdwbhostname host_name]
   [-work_dir working_dir]

For a description of the installation parameters and options that are related to agent on this operating system, see Agent installation parameters on IBM i systems.