Structure of the Automation Engine INI File

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 UCSRV.INI

Section/Parameter Description
[GLOBAL]  
system= AE system name *)

The name can consist of a maximum of 8 characters. Allowed are the upper-case letters A to Z, numbers and "_".

System names must not contain the character "_" if you use a z/OS agent in combination with the SMF technique. By default, the job Includes convert "_" to "#". Should you intend to use "_" despite of this fact, you can bypass this situation by specifying the system name in the Event Monitor with "#".

language= The language in which the logging is processed. Entries for primary and secondary language.

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

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

logging= The path and the file name of the log file.
Any file name for a text file with several place holders for current system information:

$$  is replaced by server process type (WP or CP).
* is replaced by the three-digit process number.
## is replaced by 00 after the existing log files' corresponding numbers have been raised by one during startup. During server process startup, the log files are given a temporary file name until the process number can be determined.

The following rules apply for log-file names if a database agent is used for variables and accesses this INI file (see section [DB_SERVICE] ):
$$ is replaced by "DB_SERVICE".
* has no functionality and is ignored (no character in the log-file name).
## is replaced by 00 when the agent starts, the number of the old log files increases by one. 

For relative path indications, the system uses the agent's installationnull directory when it creates the database agent's log file.

logcount= Number of the stored log file.
helplib= Name of the message file.
helpcache= Availability of the messages and language dependent strings.

Allowed values: "ALL" (default value), "NONE", "CONTROLS"

"ALL" = The complete message file is held in the RAM.
"NONE" = Always read from the hard drive.
"CONTROLS" = All language dependant strings that are necessary in order to display the dialog program are held in the RAM (not relevant for the Automation EngineDiese Komponente steuert ein Automation Engine-System. Besteht aus verschiedenen Serverprozessen.).

StartMode=

AE system startup mode.

Allowed values: "NORMAL" (default value), "COLD"

"NORMAL" = Normal AE start
"COLD" = AE cold start. All task queues are cleared.

This parameter can also be handled via the ServiceManager Dialog. INI-file values are ignored in this case.

snmp=

SNMP connection.

Allowed value: "0", "1", "2"
"0" = No SNMP connection.
"1" = SNMP connection is active.
"2" = SNMP connection is active. SNMP Traps are additionally logged in the Windows Event Viewer.

An event is generated in the Winows Event Viewer's application log (additionally to the trap) if the Automation Engine is interrupted (trap 3410). This application log entry is even written if snmp=2 has been defined.

nodename=

The description of the dialog process environment.

Default value: UC4_1

PrimaryMode=

The mode of the primary work process (PWP).
The primary work process serves to process special messages. This parameter can be used to specify whether it should also serve as work process.

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

"1" - The PWP processes only own messages. This is only possible if a further work process is active.
"0" - The PWP also processes messages which can generally be processed by work processes.

exception=

Checks internal messages for valid contents.

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

"0" - Internal message check has been deactivated.
"1" - Messages are checked and put in quarantine if necessary.

With this option being activated, messages that caused a server process crash are intercepted. Doing so protects your AE system because these messages cannot affect your server processes.

Note that this setting can negatively affect performance on UNIX.

SystemStop=

Client handling after Server-process start.

Allowed values: "NORMAL" (default value) and "YES"

"NORMAL" - Client status remains unchanged.
"YES" - All clients are stopped after Server-process start.

Note that the value "YES" overrides the settings that have been made in the key STARTUP_ACTION of the variable UC_CLIENT_SETTINGS.

This parameter can also be handled via the ServiceManager Dialog. The value specified in the INI file is ignored in this case.

[CPMsgTypes]

 

srvquery=

Performance optimization if many (several thousand) agents log on at the same time.

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

"0" - The primary work process responds to the agents' live messages.
"1" - The communication processes can process these specific messages and in doing so, they increase the AE system performance.

[CACHE]

 

script= The maximum cache size (bytes) for script.
vara= The maximum cache size (bytes) for variables.
mqmem= The maximum cache size (in bytes) for the message queue.
[TRACE]   
file= The path and the file name of the trace file.
Any file name for a text file with several place holders for current system information:

$$  is replaced by server process type (WP or CP).
* is replaced by the three-digit process number.
## is replaced by 00 after the available trace files' corresponding numbers have been raised by one during startup of a trace.

trccount= The number of stored trace files.

tcp/ip=
database=
trc03=
srcall=
memio=
jcl=
memsv=
snmp=
zuxml=
cache=
trc11=
ucds=
xscript=
uc4global=
trc15=
trc16=

Trace flags of the Automation Engine.

Set trace flags only in close cooperation with Automic Support.

[TCP/IP]  
pwpport= The port number of the primary work process.

bindaddr=

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

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

All work processes including the primary work process must be bound to the same IP address.

You can also specify the IP address or host name in pwpport= and in all parameters of section [PORTS] (Format: pwpport=IP address:port or DNS name:port). Specifications that have been made in bindaddr= are then ignored.

bindlocal=

Consideration of local host (127.0.0.1).

Use this parameter together with bindaddr=.

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

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

report=

The time interval in seconds in which the Automation Engine saves the logging to the database.

Default value: 20 seconds

connect= The time interval in seconds for reorganization of server process links following a loss of connection.

Default value: 120 seconds

chiffre=

Encryption for transfer.

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

"0" = Non-encrypted transfer.
"1" = Transfers are encrypted.

retrywait= The time intervals in seconds during which the server processes attempt to get a free port number from the port list in [PORTS].

Format: (number, interval)
Default value: (3,10)

number = Maximum number of attempts that should be made in order to obtain a free port from the port list.
interval
= Waiting period in seconds between attempts.

retrywaitpwp=

This parameter is exclusively used by work processes. They cyclically try to connect to primary-work-process port at system start or when the connection has been lost.

Format: (number, interval)
Default value: (3,10)

number = Maximum number of PWP connection attempts to the port.
interval
= Waiting time from one attempt to the next one in seconds.

hostname=

If you use this parameter, the UserInterfaces, CallAPIS and agents receive the information about the CPs that are known in the system via host name and port and not via the IP address and port during the CP selection phase while the connection to the Automation Engine is being established. In doing so, you can avoid firewall and other NATproblems.

Set hostname=*OWN if you want the operating system to retrieve the host name on which the CP is running. 

alivetimeout=

The duration in seconds in which the AE.Nonstop-Server expects a message from the primary work process. If this time span is exceeded, the AE.Nonstop-Server becomes the primary work process.

Default value: 600 seconds

Be careful when you change this parameter. The selected time span should be high enough because the primary work process is busy for quite some time if comprehensive database transactions take place and cannot send keep-alive messages.

snmp=

The port number that the Automation Engine uses in order to connect to the AE SNMP Subagent.

Ensure that the same port number is specified in the AE SNMP Subagent's INI-file parameter stream_port=.

snmpreconnect=

The interval in seconds that the system needs in order to reconnect to the AE SNMP Subagent after a connection loss.

Default value: 500 seconds

listenqueue=

The maximum number of login requests in the list queue.

A request is stored in a list queue from the point in time that a component's login request is received until the login is acknowledged. This parameter can be used to determine the maximum number of requests that can be stored in the queue at the same time.

Default value : 2030

maxMsgSize=

Maximum length of messages (in bytes) that a CP (Server communication process) accepts.

Default value: 3 145 728 (3 Mbytes)

serverConnectionVerify=

This checks whether the TCP/IP connection with a partner has been entered in the AE database table MQSRV and whether the IP address specified in the database complies with this connection's IP address.
Deactivate this setting if you use computers that have several IP addresses.

Allowed values: "0" (default), "1"
"0" = The TCP/IP connection and the IP address are not checked.
"1" = Activates the query.

NetArea=

The name of the net area of the server processes.

Default value: Name of the AE system

This value affects the CP selection of components such as agents. For more detailed information about this parameter, see Net Areas in AE.

Note that only CPs can use different net areas. All an AE system's WPs must use the same NetArea definition.

The name of the net areas is shown in the System Overviewof the server processes.

tcp_nodelay=

This defines the use of the Naqgle algorithm for the connections of the Automation Engine.

Allowed values: "0" (recommended default value) and "1"

"0" - This activates the Nagle algorithm.
"1" - This procedure is not used.

Set this parameter only in close cooperation with Automic Support.

tcp_keepalive_time=

The time interval in seconds in which keep-alive 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.

Set this parameter only in close cooperation with Automic Support.

SendBufferSize=

The size of the TCP/IP input buffer for the messages that should be sent (in bytes).

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.

Set this parameter only in close cooperation with Automic Support.

RecvBufferSize=

The size of the TCP/IP input buffer for the message that should be received (in bytes).

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.

Set this parameter only in close cooperation with Automic Support.

[PORTS]

 

cp1=  ... cpn= Assignment of communication processes and port numbers.

The port number within an AE system must be explicit, even if the system is distributed over several computers.

wp1=  ... wpn=

Assignment of work processes and port numbers.

The port number within an AE system must be explicit, even if the system is distributed over several computers.

[ODBC]  
SQLDRIVERCONNECT= Connection for the database.

ODBCVAR - Eight figure command field for controlling database accesses.

    1. Position = N - Do not use server cursor.
    1. Position = S - Use server cursor (MS SQL Server 2000).
    2. Position = N - Do not reestablish database connection after 1000 commits.
    2. Position = D - Disconnect database after 1000 commits (perhaps due to memory problems).
    3. Position = N - Field names are compared case-sensitively (Oracle).
    3. Position = J - Field names are compared case-insensitively (Oracle).
    4. Position = N - Not used.
    5. Position = N - Type of database connection: ODBC.
    5. Position = I - Type of database connection: OCI/CLI.
    6. Position = N - Database access without User ID.
    6. Position = O - Database access with User ID.
    7. Position = N - Compression is deactivated.
    7. Position = R - Compression is activated.
    8. Position = Type of SQL Syntax; N - MS SQL Server.
    8. Position = Type of SQL Syntax; O - Oracle.
    8. Position = Type of SQL Syntax; D - DB2.

DSN - Alias name of the database connection.
UID - User ID for database access.
PWD - Password for database access. Should always (also "") be encoded.See: Encoding passwords

Only for MS SQL Server 2005:
For optimal performance values, Automic strongly recommends using the option MARS_CONNECTION=Yes.

For example:
(Two lines are used for the connection parameters for reasons of space. In the INI file, you should only use one line).

SQLDRIVERCONNECT=ODBCVAR=NNNNNNRN,DSN=UC4;UID=uc4;
PWD=--1037B2E22BF022EBE2;Mars_Connection=Yes

Set the first digit of ODBCVAR to "S" if you do not use this option.

 Note that the native client of SQL Server 2005 must be used if MARS is applied. Create a new ODBC data source using the native client. MARS is a function that requires the SQL Server 2005 on client and server side.

Only for ORACLE:
Code-page settings must correspond to those of the database. AE recommends using the variable NLS_LANG or the parameter SP=.

Syntax:
SP=NLS_LANGUAGE=language,NLS_TERRITORY=area,CODESET=character set,RECONNECT=interval

RECONNECT refers to the frequency that should be used to re-establish the database connection. This parameter is given priority even if a "D" is specified in the 2nd digit of ODBCVAR (see above).

For example:

(Two lines are used for the connection parameters for reasons of space. In the INI file, you should only use one line).

SQLDRIVERCONNECT=ODBCVAR=NNJNIORO,DSN=UC4;UID=uc4;PWD=--1037B2E22BF022EBE2;
SP=NLS_LANGUAGE=AMERICAN,NLS_TERRITORY=AMERICA,CODESET=WE8ISO8859P15

See also: Setting up ORACLE databases

[DB_SERVICE]

This section contains specific parameters for the database agent which starts in the mode for resolving variables. The agent's installation guide describes how the agent can be started.

The parameter logging= can be used to specify the path and name of the log files for agent and server processes. Also refer to the specific notes which are provided in the section [GLOBAL].

Note that this INI file can only be used for database agents. Copy this configuration file in order to use several database agents for variables.

cp=

Address of the AE system's communication process to which the agent should connect.

Allowed formats:
DNS name
:port number
TCP/IP address
:port number

name=

Name of the database agent that should be used to resolve variables.

The name of the agent computer (host name) is used if nothing has been defined.

The agent name is limited to 32 characters. The following characters are allowed: (missing or bad snippet)

A hyphen ( "-") can be used for the agent name in the configuration file for reasons of compatibility to former Automation Engine versions. Newly created agents must not include hyphens in their names.

tcp/ip=

Trace flags of the agent.

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

Set trace flags only in close cooperation with Automic Support.

InitialPackage=

Path and name of the file that contains the authentication package

When it starts, the agent reads this file and stores the information it includes in the file specified in the parameter KeyStore=. The original file is then deleted.

KeyStore= Path and name of the file that contains information about the authentication package (see InitialPackage=).
connect=

Time interval in seconds in which the agent attempts to establish connection to the Automation Engines. This affects the connection setup for a restart or after a lost connection.

Default value: 60 seconds

This parameter is only effective until the first successful logon to the AE system. Afterwards, the parameter RECONNECT_TIME can be used in the host characteristics.

retention_time= Number of seconds after which an unused database connection should be terminated.
retry=

Number of connection attempts to the database.

The number that is specified in this parameter determines how often the agent attempts to connect to the database. After the nth failed attempt, the job ends with status ENDED_NOT_OK.

The agent continues to connect to the database if this parameter has not been specified in the INI file. The job remains active until the database is available again or until it is canceled.

OPTIMIZE=

Database optimization, optimization means, that if you select data with a key, the db-service automatically optimizes the query to a new statement where the given key is part of the statement. If the query does not return any data or results in an error, the original query is executed.

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

"0" - Database optimization off.
"1" - Database optimization on.

Example of an INI File

[GLOBAL]
system=UC4
language=(E,D)
logging=..\TEMP\$$srv_log_*_##.txt
logcount=10
helplib=uc.msl
helpcache=ALL
StartMode=NORMAL
snmp=1
nodename=UC4_1
PrimaryMode=0
exception=1
SystemStop=NORMAL


[CPMsgTypes]
srvquery=0


[CACHE]
script=1000000
vara=100000
mqmem=1000000


[TRACE]
file=..\TEMP\$$srv_trc_*_##.txt
trccount=10
tcp/ip=
database=
trc03=
srcall=
memio=
jcl=
memsv=
snmp=
zuxml=
cache=
trc11=
ucds=
xscript=
uc4global=
trc15=
trc16=


[TCP/IP]
pwpport=2270
report=20
connect=120
retrywait=(5,60)
retrywaitpwp=(5,60)
alivetimeout=600
snmp=2200
snmpreconnect=500
listenqueue=2030


[PORTS]
cp1=2217
cp2=2218
wp1=2271
wp2=2272
wp3=2273
wp4=2274
wp5=2275
wp6=2276
wp7=2277
wp8=2278
wp9=2279


[ODBC]
; ODBCVAR xxxxxxxx
;         |||||||+ type of SQL-Syntax N=SQL-SERVER  O=ORACLE  D=DB2  Z=DB2/OS390
;         ||||||+- R=compress messages and local memory
;         |||||+-- O = with userid, N = without userid
;         ||||+--- I=OCI/CLI N=ODBC
;         |||+---- not used
;         ||+----- J = compare fieldnames case-insensitiv (in case of ORACLE !!)
;         |+------ D = DB-Disconnect after 1000 commits (perhaps in case of Oracle memory leaks)
;         +------- S = use Server-Cursor (SQL-SERVER)
;
;         SNNNNNRN for SQL-Server 2000
;         NNNNNNRN for SQL-Server 2005
;         NNJNINRO for Oracle 8.x with OCI (Oracle Call Interface)
;         NNJNIORD for DB2/NT/UNIX with CLI (Call Level Interface)
;         NNJNIORZ for DB2/OS390 (7.1) with CLI (Call Level Interface)

; SQL-Server 2000 with ODBC
SQLDRIVERCONNECT=ODBCVAR=SNNNNNRN,DSN=UC4;UID=uc4;PWD=10BFDC349F38156A22
; SQL-Server 2005 with ODBC
;SQLDRIVERCONNECT=ODBCVAR=SNNNNNRN,DSN=UC4;UID=uc4;PWD=UC4
; SQL-Server 2005 with MARS
;SQLDRIVERCONNECT=ODBCVAR=NNNNNNRN,DSN=UC4;UID=uc4;PWD=UC4;Mars_Connection=Yes
; Oracle with OCI
;SQLDRIVERCONNECT=ODBCVAR=NNJNIORO,DSN=UC4;UID=scott;PWD=tiger
; DB2 with CLI
;SQLDRIVERCONNECT=ODBCVAR=NNJNIORD,DSN=UC4;UID=uc4;PWD=UC4

[DB_SERVICE]
name=SQLVAR_01
InitialPackage=
KeyStore=
connect=60
retention_time=60
retry=3

See also:

Notes for Configuration-File Adjustments