Installing the Agent for VMS

This topic guides you through the installation process of a VMS agent.

Notes:

  • Each supported VMS version shows a two-character code which is used in all agent file names. In this topic, the characters "???" are used to represent this code.
  • In VMS, text strings that call and identify items such as commands and files are not case-sensitive. Any combination of uppercase or lowercase letters is acceptable. In this topic, capital letters are used.
  • Additional installation steps are required before the agent can be started and used if you intend to use one of the available authentication methods. For more information, see Agent Authentication.
  • For information about CallAPI files and their implementation, see CallAPI for VMS.

This page includes the following:

Requirements

  • The user AE has been created with the privileges CMKRNL, BYPASS, SYSNAM, SYSPRV and WORLD.
  • The batch queue SYS$BATCH has been initialized and started. Alternately, you can use a batch queue that has been specifically created and prioritized for AE jobs. If a batch file is created for this purpose, it must be defined in the Agent VMS INI file as the VMS command's parameter for starting jobs in batch mode. If you use a different batch queue, note that it must also be initialized and started.

    The job limit must be specified with a number higher than zero in order to enable AE jobs to be performed in batch mode.

    • Tip: The VMS agent can start automatically when the operating system starts. For this purpose, the required command files UC4$STARTUP.COM and UC4$STARTUP_BAT.COM must be transferred to the directory SYS$STARTUP. You can name these command files as you like. Only their length is limited to 32 characters. Names that have been changed must also be modified in the command files. For more information, see Automatic Agent Start when Booting the Operating System.

Supplied Installation Files

The files of the VMS agent are found in the subdirectory of IMAGE:AGENTS\VMS that complies with the particular VMS version.

Special Feature: Logical Name for Agent

VMS often uses global variables called logical names to transfer information. AE's VMS agent also uses such a global variable.

By default, its name is structured as follows: UC4_AE system name_Agent_name_AGENT. The names that have been defined in the INI file are used for the AE system name and agent name. Alternatively, you can define a logical name of your choice. Use the parameter uc4_logical= in the INI file for this purpose.

The global variable is automatically created when the agent starts and deleted when it ends. The value of the variable is "OK" by default. You can end the agent by changing the variable content to "TERM". Use the command file UC$STOP.COM and the agent will react within 20 seconds and end normally.

Connecting to the Automation Engine

Important! The Automation Engine uses TLS/SSL to communicate only with the Windows, UNIX, and Java Agents. This particular Agent is not a TLS/SSL Agent and therefore connects to a communication process (CP) and uses non-TLS/SSL encryption. The communication between a TLS/SSL and a non-TLS/SSL Agent can be established using the TLS Gateway.

More information:

Non-TLS/SSL Agents, when used for the Automic Automation Kubernetes Edition, establish a connection to a TCP load balancer, which must be reachable for the Agent. The address of the load balancer must be defined on both sides: the Automation Engine and the Agent.

Important! When you install or upgrade Agents manually for an Automic Automation Kubernetes Edition system, you have to make sure that you configure your Agents and/or TLS Gateway to reach the TCP or HTTPS load balancer and not the CP or JCP directly. Also, make sure that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to the AAKE Cluster.

Installing the Agent for VMS

  1. On the admin computer, transfer the UC$CRDIR.COM command file to the host.

    If you use FTP to transfer the files to the target host you may consider that all text files are delivered unix-like.

  2. On the host computer, determine directories and authorizations.

    • Call command file: $ @UC$CRDIR

    • Delete command file: $ DELETE UC$CRDIR.COM;*

      The UC UC$CRDIR.COM command file creates all required directories and authorizations:

      • BIN

        SYSTEM: RE, OWNER: RWED, GROUP: E, WORLD: E

      • CMD

        SYSTEM: RWE, OWNER: RWED, GROUP: R, WORLD: -

      • TEMP

        SYSTEM: RE, OWNER: RWED, GROUP: WE, WORLD: WE

      • OUT

        SYSTEM: RW, OWNER: RWD, GROUP: RW, WORLD: RWE

  3. On the admin computer, transfer more files to the host.

    The files of the VMS agent (UCXJV??.EXE), for file event (UCXE???F.EXE) and the messenger program (UCXJV??M.EXE) must be transferred in binary mode. All others are text files.

  4. On the host computer, set up the system environment.

    1. Change from the login directory to the BIN directory: $ SET DEF [.BIN].

    2. Adjust INI file of the VMS agent with the editor. For more information, see Agent VMS.

      When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default. In this case, you only have to check that the root certificates already are in the respective store.

      If you do not want to use the default location for this component, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

      For more information, see Securing Connections to the AE (TLS/SSL).

    3. Adjust HEADER.VMS, TRAILER.VMS and RESTART.VMS if necessary. For more information, see Executing Jobs.

    4. Change to the CMD directory: $ SET DEF [-.CMD].

    5. Use an editor to adjust the command file that closes the agent UC$STOP.COM.

      Adjust the name of the AE system and the agent name so that the logical name of the agent can be found. Alternatively, you can modify both files on the admin computer before you transfer the file.

      By default, the HOME directory is used for the agent start. If the agent is not installed in the HOME directory, you must adjust the command file UC$START.COM. It includes a variable in which you can specify the installation directory.

      $   rel_dir     = ""

      The user IDs under which AE jobs should run should be given TMPMBX and sometimes NETMBX privileges.

    6. On the admin or user computer, adjust HEADER.VMS, TRAILER.VMS and RESTART.VMS if required. For more information, see Executing Jobs.

  5. On the server computer, start the agent.

    1. Make sure that the AE system is running on the server computer. For more information, see Multi-Server Operations.

    2. On the host computer, call command file in the CMD directory: $ @UC$START

      You can identify the agent's task by its process ID or process name:

      • The process name that is created when the agent starts: UC4_User ID. By default, the process name is UC4_UC4.

        $ SHOW PROC UC4_UC4

      • The process ID that is displayed when the agent starts.

        $ SHOW PROC/ID=Process ID

      An Agent object is automatically created in the system client 0 and stored in the HOST folder.

      3. In AWI, client 0, verify that the Agent is logged on to the Automation Engine.

      Newly logged on Agents are not assigned to a client automatically and can only be viewed in Client 0. Once you have logged in to Client 0, access the Administration perspective and select Agents & Groups.

      Assign the new Agent to clients with the required rights using the Agent object definition. For more information, see Authorizations Page.

  6. On the host computer, shut down the agent.

    • Regular shutdown: Call the command file in the CMD directory.

      $ @UC$STOP

    • Emergency shutdown: Network connections are not closed properly in this case.

      Stop it by using the process name:

      $  STOP UC4_UC4

      Stop it by using the process ID:

      $  STOP PROC/ID=Process-ID

Automatic Agent Start when Booting the Operating System

The command file SYS$MANAGER:SYSTARTUP_VMS.COM is executed when the operating system starts. To start the VMS agent automatically with VMS, the agent's startup script is appended to the end of this command file. The command file (1) UC4$STARTUP.COM is called in the startup script if it is available.

Example startup script

$!
$ FILE = F$SEARCH("SYS$STARTUP:UC4$STARTUP.COM")
$ IF FILE .NES. ""
$ THEN
$    @SYS$STARTUP:UC4$STARTUP.COM
$ ENDIF
$!

The following parameters must be adjusted to the system environment in the supplied command file (1) UC4$STARTUP.COM:

  • UC4_BAT
    The command file (2) UC4$STARTUP_BAT.COM
  • UC4_LOG
    The directory in which the log files of the agent are stored
  • UC4_USER
    The agent's user ID

The command file (1) UC4$STARTUP.COM calls the command file (2) UC4$STARTUP_BAT.COM. The VMS agent then starts with the help of the command file UC$START.COM. Adjust the parameter UC4_COM if you have changed the name or directory of this supplied command file.

Comments

  • The command file (2) UC4$STARTUP_BAT.COM must be started with the agent's user ID.
  • The batch queue must be initialized and started.
  • The network environment and administration UCX must be started.
  • The command file (2) UC4$STARTUP_BAT.COM must have WORLD READ privileges so that the agent's user ID can be read: $ SET FILE /PRIV=(W:R) SYS$STARTUP:UC4$STARTUP_BAT.COM.

See also: