Administration Guide > Configuration > Structure of the Configuration Files > VMS Agent

VMS Agent

Default values have been specified for most parameters. They can be changed if required. Parameters that must be adjusted to your system environment are written in red letters.

Structure of the INI File UCXJV??.INI

Section/Parameter Description
[GLOBAL]  
name= The name of the agent.

The agent name is limited to 32 of the following characters: A-Z, 0-9, _, ., $, @, - and #.

The host name is used instead if this parameter remains undefined. Lowercase letters are converted to uppercase letters.

Hyphens ("-") are only allowed in agent names. They must not be used in the names of any other objects.

system=

The name of the AE system.
This entry must be identical to the entry in the INI file of the Automation Engine.

logging=

The path and the file name of the log file.

The characters xx in the file names are placeholders. They stand for the two-digit abbreviation of the respective VMS version. See: Terminology.

The number signs serve as place holders for a series in numerical order. When starting the agent, the log files are renamed so that the most current log file is always the one with the number "00".

logcount= The number of stored log files.
helplib= The name of message file.
licence_class= The license class that corresponds to the acquired license and the hardware and software that is used.

Allowed values: "1" to "9"
"1" to "9" = License class of the agent

language=

The language that should be used for the logging. You can specify a primary and a secondary language.

Allowed values: "E", "D", "F"
Default: "E,D" (primary English, secondary German)

If there is no message in the primary language, the system searches for a message in the secondary language.

userid_type= Additional possibility of the operating system to allow or reject certain users.

Allowed values: "INCL", "EXCL"

"INCL" = The access must be allowed for every single user that is specified in (USERID).
"EXCL" = Access is denied to the users that are specified in (USERID). All other users can start jobs.

UC_user_type= You can allow or reject certain AE users.

Allowed values: "INCL", "EXCL"

"INCL" = The access must be allowed for every single user that is specified in [UC_USER].
"EXCL" = Access is denied to AE users that are specified in [UC_USER]. All other AE users can start jobs.

rcv_max= The time period in seconds in which the agent waits for the rest of a partially received message. When this time period expires, the connection is considered interrupted. Note: Ensure that the time period that you specify is not too long.

Default value: 30 seconds

uc4_logical=

The definition of the logical name (entries are converted to uppercase letters).

If this parameter is not specified, the logical name is created as shown below:
UC4_AE system name_Agent name_Agent

ReadUserAlways=

You can allow or reject User IDs by using the parameter userid_type= in the [USERID] section. You can use the parameter ReadUserAlways= in order to specify whether this section should always be read before a job starts or only once when the agent starts. Reading this section only once improves the performance of your system and is therefore the default value. 

Allowed values: yes and no (default value)

yes = The agent always reads the [USERID] section before a job starts.
no = The agent reads this section only once when the agent starts.

ft_temp_file=

This creates temporary files in file transfers.

Allowed values: "yes" (default value) and "no"

"yes" - The file obtains a temporary name which is composed of the letter "T" and an alphabetic string that stems from the RunID.The new file transferr additionally appends a file ID to obtain a unique file name because basically, only a RunID is provided. The file is renamed after it has successfully been transferred. 
"no" - The agent assigns the final file name when the file transfer starts.

tcp_nodelay=

Nagle algorithm usage for file transfers and all the agent's other sockets.

Allowed values: yes (default value) and no

no = Activates the Nagle algorithm.
yes = This procedure is not applied.

Activating the Nagle algorithm can improve the performance of file transfers, especially if you transfer many small files.

The BS2000 agent always uses the Nagle algorithm. Therefore, it does not include this INI-file parameter.

Note that this parameter should only be set in close cooperation with Automic Support!

[AUTHORIZATION]  
InitialPackage=

The name and the path of the file that includes the authentication package (company-key file).

This parameter must be specified if you use the authentication methods "Server" or "Server and Agent". Any attempt to log in fails if the company-key file cannot be found.

When the agent starts, it reads the company-key file and stores its information in the file that is specified in the parameter KeyStore=. The first file is deleted afterward.

KeyStore=

The name and the path of the file that includes the information of the authentication package (see parameter InitialPackage=).

If no file name and/or path is specified, the system uses the name (file ending *.kstr) or the path of the agent's INI file. If you define a file name, the ending *.kstr is not automatically appended.

The KeyStore file is created when the agent starts for the first time. You must not delete, rename or move it subsequently. Regardless of the authentication method that you use, any attempt to log in will fail if the agent cannot find this file when it starts. In this case, you must open the menu item "Renew transfer key" in the affected agent's System Overview.

[USERID]

Entry of authorized VMS users in the format:
User name
=START

Entry of unauthorized VMS users in the format:
User name
=NO_START

[UC_USER] Entry of authorized AE users in the format:
User ID
=START

Entry of unauthorized AE users in the format:
User ID
=NO_START

[VARIABLES]

This section contains agent variables containing agent settings and information.

The variable UC_EX_JOB_MD is decisive for the name of the Job Messenger program (by default: UCXJVxxM).
xx stands for the relevant platform's short form. In VMS, the correct Job Messenger is not automatically found via this placeholder (as opposed to UNIX). Therefore, set this agent variable in the INI file depending on the VMS system on which the agent is used: 

  • OpenVMS (IA64):
    UC_EX_JOB_MD = UCXJVI8M
  • Alpha:
    UC_EX_JOB_MD = UCXJVA7M
  • VAX:
    UC_EX_JOB_MD = UCXJVV7M
[TRACE]  
file= The path and the file name of the trace file.

The characters xx in the file name are place holders. They stand for the two-digit abbreviation of the respective VMS version. See:Terminology.

The number signs serve as place holders for a series in numerical order. When starting a trace, the trace files will be renamed so that the most current trace file is always the one with the number "00".

trccount= The number of stored trace files.

tcp/ip=
event=
job_debug=
ft_debug=
ex_init=
signal=
memory=

Trace flags of the agent

Allowed values: "0" (default value) to "9"

Trace flags must only be used in close cooperation with Automic Support.

[HOSTS]

Assignment of an agent's name to its address (DNS name or TCP/IP address) if it cannot directly be accessed through the address that is stored in the server. Specify several assignments line by line, there is no upper limit for the number of assignments.

In file transfers, the sending agent obtains the destination agent's internal address from the Automation Engine. The sending agent replaces this internal address by the external address that is defined here.

This setting is only required if you run file transfers with agents that cannot directly establish a TCP/IP connection between each other by using the address that they have received from the Server. This can happen if the agents that are involved in the file transfer are located on different networks or if a firewall is used.

 

[TCP/IP]

 

port= The agent's port number.

Other agents and the Job Messenger establish connection with the agent via this port number.

bindaddr=

The IP address or host name for Server-process connection.

Use this parameter if the connection should be established via a particular IP address (for example, the computer has more than one network interface card).

Alternately, you can also specify the IP address or host name in port=

(Format: port=IP address:port or DNS name:port). Specifications made in bindaddr= are then ignored.

bindlocal=

Consideration of local host (127.0.0.1).

Use this parameter together with bindaddr=.

Allowed values: "0" (default value), "1"

"0" - No listen socket is created.
"1" - An additional listen socket is created on the local host.

connect=

The time interval in seconds in which the agent attempts to establish a connection to the Automation Engine. This affects the connection specifications when restarting or connection is cut off.
The former parameter name agent= is still valid for compatibility reasons.

Default value: 60 seconds

maxrepcnt=

The maximum number of report blocks that should be transferred to the Automation Engine simultaneously.

Default value: 8 blocks

maxMsgSize=

Maximum length of messages (in bytes) that the agent accepts.

Default value: 500 000

tcp_keepalive_time=

The time interval in seconds in which packets are sent in order to keep connections.

The default value that depends on the system environment is used when you do not define this setting or when you define the value 0.

This parameter has no effect when the agent runs under VAX.

cp=

Address of the communication process in the AE system to which the agent should connect itself.

Allowed formats:
DNS Name:Port number
TCP/IP Address:Port number

[STARTCMD]

 

SUBMIT=

VMS command for starting a job in batch mode. You can adjust is user-specifically by using additional SUBMIT parameters:

For example, you can set up and prioritize your own batch queue for AE and specify it as a parameter  Example: /QUEUE=UC4$BATCH

If no queue parameter is specified, jobs start in the standard queue SYS$BATCH.

ACCESS=

Indication of file attributes for file transfers

Allowed values: "alq", "deq", "mbc", "mbf" and "fop"

"alq" = Number of disk blocks used for the file transfer by default (1 block = 512 Byte)
"deq" = Number of disk blocks for extending the required memory
"mbc" = Specifies the number of blocks allocated to the I/O buffer
"mbf" = Indicates the number of I/O buffers that are to be allocated
"fop" = This file attribute currently supports the following parameters: cbt (contiguous-best-try), ctg (contiguous) and tef (truncate at end-of-file). They are separated by commas (e.g. fop=ctg,tef).

Automic recommends using the following values: alq=5000,deq=5000,mbc=64,mbf=64

Note that the INI file parameter is read with each file transfer execution. File attributes can be changed while the agent is running.

If you specify the file attributes directly in the file transfer, these attributes are used instead of the attributes that are defined in the INI file.

[JOBREPORT]

 

reportname=

The definition of the job-report's name.

Allowed placeholders in the file name are: "&userid", "&vms-jobname", "&AE-jobname", "&client" and "&runnr"

"&userid" = User ID of the job execution.
"&vms-jobname" = Name of the job in VMS.
"&AE-jobname" = Name of the AE Job object.
"&client" = Number of the client in which the job has been started.
"&runnr" = RunID (run number) of the job.

With the agent variable UC_EX_PATH_JOBREPORT, you can specify the directory in which the job reports should be stored.

[MISC]

 

FileNameLowerCase=

The file name is important for the script functions PREP_PROCESS_FILENAME and wildcard file transfers. Use this parameter in order to specify whether the agent should leave the file name unchanged or convert it to lowercase letters.

Allowed values: "yes" and "no" (default value)

"yes" - File names are always converted to lowercase letters.
"no" - The agent does not adjust the file name's spelling.

TraceFileSize=

The maximum size of a trace file. The agent creates a new file if this value has been reached.

Default value: "32M"

Enter a number followed by the letter "K" for kilobytes or "M" for megabytes. The agent interprets the number as bytes if no measuring unit has been specified.

FileEndDelimiter=

This appends a line break (LF) to the end of text files that have been transferred by using a file transfer.

In VMS, each text file requires a line break at its end.

Allowed values: "yes" (default value) and "no"

"yes" - In file transfers, the agent always appends a LF to the end of text files when it is the receiving agent. It is irrelevant whether the files already end with a LF.
"no" - The files are transferred without any changes.

[CP_LIST]

List of communication processes.

This list is created when the agent starts and is extended when new communication processes are activated. You will find more detailed information about establishing a connection in the chapter Multi-Server Operation.

The communication process that is defined in the parameter cp= (section [TCP/IP]) is not included in the cp list.

Format:
Port number
=DNS name
or
Port number
=TCP/IP address

Example of an INI File

[GLOBAL]
name = VMS01
logging = [-.temp]UCXJVxx.l##
logcount = 6
helplib = ucx.msl
licence_class = 9
language = e,d
userid_type = EXCL
UC_user_type = EXCL
; rcv_block = yes
; rcv_max = 30
ReadUserAlways=no
ft_temp_file=yes


[AUTHORIZATION]
InitialPackage=
KeyStore=


[USERID]
;system = NO_START


[UC_USER]
;6 = START
;7 = NO_START


[VARIABLES]
UC_HOST_CODE = UC_CODE
UC_HOST_JCL_VAR = VMS
UC_EX_PATH_BIN = []
UC_EX_PATH_JOBREPORT = [-.out]
UC_EX_PATH_TEMP = [-.temp]
UC_EX_JOB_MD = UCXJVxxM


[TRACE]
file = [-.temp]UCXJVxx.t##
trccount = 10
tcp/ip = 0
event = 0
job_debug = 0
ft_debug = 0
ex_init = 0
signal = 0


[HOSTS]
; <AE-name>=<dns-name> or
; <AE-name>=<ip-addr>


[TCP/IP]
port = 2220
alarm = 30
maxrepcnt = 8
cp = PC01:2217


[STARTCMD]
SUBMIT = submit &jobFile /LOG=&jobReport /USER=&user
ACCESS = alq=5000,deq=5000,mbc=64,mbf=64


[JOBREPORT]
;reportname =  [-.report]&vms-jobname_&client_&userid_&AE-jobname_&runnr.log
;reportname = [uc4.uc100e.exekutor.report.&userid]&vms-jobname.log


[MISC]
FileNameLowerCase=no
TraceFileSize=32M
FileEndDelimiter=yes


[CP_LIST]
2218=PC01

 

See also:

Notes for Configuration-File Adjustments