Installing the Agent for UNIX

Installing the Agents

Installing the Agent for Windows

---

Installing the Agent for VMS

This document guides you through the new installation of a VMS agent.

A two-character code is assigned to each supported VMS version. This code then appears in all agent file names and is described in the terminology. In this document, 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 document, capital letters are used with only one exception: Commands of the program FTP.EXE can only be entered in lowercase.

Tip: The VMS agent can be started automatically when booting the operating system. Refer to the configurationA set of constituent components that make up a system. This includes information on how the components are connected including the settings applied. details that are described at the end of this document. The required command files UC4$STARTUP.COM and UC4$STARTUP_BAT.COM must be transferred to the directory SYS$STARTUP. Their names meet the requirements of the 8.3 conventions of the AE CD and are freely definable. Note that names that have been changed must also be modified in the command files. 

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 VMS agent's 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.

Supplied Installation Files

The files are found in the subdirectory of IMAGE:AGENTS\VMS that corresponds with the particular VMS variant.

The CallAPI files and their implementation are described separately.

Special Feature: Logical Name for Agent

VMS often uses global variables, also called logical names, to transfer information.

AE's VMS agent also uses this kind of 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. You can, however, also define a different logical name, using the parameter uc4_logical= in the INI file.

The global variable is automatically created when the agent starts and deleted when it ends. The value of the variable is "OK" by default. The agent can be ended by changing the variable content to "TERM" using the command file UC$STOP.COM. Within 20 seconds the agent reacts and ends normally.

Procedure

	1.	Transferring the command file to the host

• Admin computer
• Transfer the file UC$CRDIR.COM via FTP (ASCII).

	2.	Determining directories and authorizations

• Host
• Register with user ID AE.
• Call command file:

  $  @UC$CRDIR

• Delete command file:

  $DELETE UC$CRDIR.COM;*

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

Directory	Authorization
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.	Transferring more files to the host

• Admin computer
• 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.	Setting up the system environment

• Host
• Change from the login directory to the BIN directory:

  $SET DEF [.BIN]

• Adjust INI file with the editor.
• Adjust HEADER.VMS, TRAILER.VMS and RESTART.VMS if necessary. See:Job - Execution
• Change to the CMD directory:

  $SET DEF [-.CMD]

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

  The name of the AE system and the agent name must be adjusted so that the logical name of the agent can be found.

You can also modify both files on the Admin computer before you transfer them.

•  If the agent has not been installed in the HOME directory, the command file UC$START.COM must be adjusted. It contains a variable that indicates the installation directory.

$   rel_dir     = ""

If the command file remains unchanged, the HOME directory is by default used to start the agent.

•  The user IDs under which AE jobs should run should be given TMPMBX and sometimes NETMBX privileges.
• Admin computer or user computer
• Adjust HEADER.VMS, TRAILER.VMS and RESTART.VMS if needed. See:Job - Execution

	5.	Starting the Agent

• Server computer
• Register using the user AE.
• The AE system must be running.
• Host
• Call command file in the CMD directory:

  $  @UC$START

• The agent's task can be identified by its process ID or process name.

  Information about the task can be obtained in two ways:

1. The process name is created at the start of the agent: UC4_User ID.

   By default, the process name is UC4_UC4.
   $ SHOW PROC UC4_UC4

2. The process ID is displayed at agent start.

   $ SHOW PROC/ID=Process ID

• An Agent object is created automatically in the system client 0000 and stored in the folder HOST.
• Admin computer or Server computer
• Verify that the agent is logged on.
  • Start the UserInterface for client 0000. Information about agents is available in the System Overview. Because a newly logged-on agent has not yet been assigned a client, it can only be viewed in the client 0000. The newly installed agent can be assigned to clients with the required rights through the agent object.

	6.	Shutting down the Agent

• Host
• Log on using the user ID UC4.
• Call the command file in the CMD directory to shut down the agent normally.

  $ @UC$STOP

• Emergency shutdown of agent: network connections are not closed properly.
1. Cancel with process name:

   $  STOP UC4_UC4
   or

2. Cancel with 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 boots. In order 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 (if it exists) is called in the startup script.

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 - command file (2) UC4$STARTUP_BAT.COM
• UC4_LOG - directory in which the log files of the agent are stored
• UC4_USER - agent's user ID

The command file (1) UC4$STARTUP.COM calls the command file (2) UC4$STARTUP_BAT.COM. With the help of the command file UC$START.COM, the VMS agent will then start. Adjust the parameter UC4_COM if the name or directory of this supplied command file has been changed.

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.