Automation Engine

Structure of the INI File ucsrv.ini

Parameter Name 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 "#".

Default: AUTOMIC

language =

The Language(s) in which the log messages are displayed.Always a pair of languages separated by comma enclosed in brackets.

if a message text is not available in the primary language the secondary language will be taken.

Values

  • E: english
  • D: german
  • F: french

Default: (E,D)

logging =

Full file name pattern for log file names

$$ is replaced by the purpose of a Process (CP or WP or JWP or DBSERVICE). No replacements in other components

* is replaced by the 3 digit number of a Worker Process.

## is replaced by the log file sequence number after the existing log files' corresponding numbers have been raised by one during startup of the component.

z/OS components only:

If you comment this parameter, this log file is stored in JES. Also refer to the parameter logpurgeclass= which is described below.

The following parameters can be added if the log is written to a dataset (after the dataset name and separated by semicolons):

"recfm" = (all 27 z/OS plus * and A record formats are valid)

"lrecl" = (0, each positive number up to 32760 and X for each reclen)

"blksize" = (0, each positive number up to 32760)

"space" = ([CYL,TRK],(prim,sec,directory))

For relative path indications the system uses the installation directory when creating files.

For BS2000/OSD Operation System the name may be specified with or without User ID. If without User ID the log file is written to the user ID under which the component has been started

Default: ..\temp\$$srv_log_*_##.txt

logCount =

number of log files being kept on disk

Default: 10

helplib =

name of the message text library

may have different names dependent on platform rules.

Default: uc.msl

helpcache =

Availability of the messages and language dependent strings.

Values

  • 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 Engine).

Default: ALL

startMode =

Automation Engine system startup mode.

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

Values

  • NORMAL: Normal AE start
  • COLD: AE cold start. All task queues are cleared.

Default: NORMAL

snmp =

SNMP connection.

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.

Values

  • 0: No SNMP connection.
  • 1: SNMP connection is active.
  • 2: SNMP connection is active. SNMP Traps are additionally logged in the Windows Event Viewer.

Default: 0

nodename =

The description of the dialog process environment.

In a distributed server environment, this value must be unique for each host.

Default: 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 normal work process.

Values

  • 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.

Default: 1

exception =

Exception handling.

With this option being activated, messages that caused a server process crash are intercepted and moved to quarantine. Doing so protects your AE system because intercepted messages will not affect further worker processes.

Note that this setting can negatively affect performance on UNIX

Values

  • 0: exception handler turned off
  • 1: exception handler tuned on

Default: 1

systemStop =

Client handling 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.

Values

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

Default: NORMAL

[ CPMsgTypes ]
srvquery =

Determines which process responds to the agent's life sign message

This setting has a performance impact. If the CP layer responds than the workload is distributed as agents are connected to different CP's whereas only one Primary WP exists in a system. Furthermore there is no need to hand over the agent's life sign messages to the PWP via the message queue tables which safes database IO's

Setting this parameter to 1 turns off implementation logic of the agent's life sign within the PWP. As a result among other things the column "last checked" in the agent overview will not be updated anymore.

You may change the setting to 1 if you experience performance issues on the PWP.

Values

  • 0: The primary work process (PWP) responds to the agent's live sign messages. (Slower)
  • 1: The communication processes (CPs) respond to the agent's live sign messages. (Faster)

Default: 0

[ CACHE ]
script =

The maximum cache size (bytes) for script.

Default: 3000000

vara =

The maximum cache size (bytes) for variables.

Default: 3000000

mqmem =

The maximum cache size (in bytes) for the mqmem table records.

Default: 3000000

[ 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) in the context of a server process.

* is replaced by the three-digit process number in the context of a server process.

## is replaced by 00 after the available trace files' corresponding numbers have been raised by one during startup of a trace.

xxx is replaced by the three-digit abbreviation of the respective unix version (unix agent only).

z/OS components only:

The following parameters can be added (after the dataset name and separated by semicolons) if the log is written to a dataset:

"recfm" = (all 27 record formats of z/OS plus * and A are valid)

"lrecl" = (0, each positive number up to 32760 and X for each reclen)

"blksize" = (0, each positive number up to 32760)

"space" = ([CYL,TRK],(prim,sec,directory))

Currently the External Monitoring Interface (EMI) does not produce any trace regardless of the settings here.

For BS2000/OSD the name might be specified with or without user ID. If without the trace file is written to the user ID under which the component has been started.

Default: ..\temp\$$srv_trc_*_##.txt

trccount =

Number of stored trace files

Default: 10

tcp/ip =

traceflag

Default: 0

database =

traceflags

Values

  • 0: no trace
  • 1: SQL
  • 2: OPC
  • 3: Bind parameters
  • 4: Data fields

Default: 0

trc03 =

traceflag

Default: 0

srcall =

traceflag

Default: 0

memio =

traceflag

Default: 0

jcl =

traceflag

Default: 0

memsv =

traceflag

Default: 0

snmp =

traceflag

Default: 0

zuxml =

traceflag

Default: 0

cache =

traceflag

Default: 0

trc11 =

traceflag

Default: 0

ucds =

traceflag

Default: 0

xscript =

traceflag

Default: 0

uc4global =

traceflag

Default: 0

trc15 =

traceflag

Default: 0

trc16 =

traceflag

Default: 0

memtrace =

traceflag

Values

  • 0: This setting enables writing into the file when a WP starts.
  • 1: This setting enables writing into the memory when a WP starts.

Default: 0

[ TCP/IP ]
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.

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.

Default: 600

bindAddr =

IP address the component uses to connect.

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.

In a distributed server environment, this value must be adapted with a valid IP address that is available to that specific host.

Default: 111.1.1.1

bindLocal =

Consideration of local host 127.0.0.1 (IPv4) or ::1 (IPv6).

Use this parameter together with bindAddr=. This setting is ignored if bindAddr is not set.

Values

  • 0: No listen socket is created.
  • 1: An additional listen socket is created on the local host.

Default: 1

chiffre =

Encryption for transfer.

Values

  • 0: Non-encrypted transfer.
  • 1: Transfers are encrypted.

Default: 1

connect =

The time interval in seconds for the reestablishment of connections after a loss of connection.

For the Automation Engine: reconnect between Server Processes

For Agents: reconnect to the Engine

For the zOS Event Monitor: reconnect to the Agent

For the Proxy: reconnect to Automation Engine or Server Proxy

For Agents: This parameter is only effective until the first successful logon to the AE system. Afterwards, you can use the parameter RECONNECT_TIME in the host characteristics.

For z/OS Event Monitor: The Console command "MODIFY ..., EX=<addr>,:<port> serves to facilitate a new connection immediately. In this case, the attempt to re-connect to the specified agent is made immediately. A reconnection is established, even if the Event Monitor already has a connection to another agent. A new connection is then established. The old connection is ended if the new connection has successfully been established.

Default: 120

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.

In a distributed server environment, this value must be set to the name of each host.

Default:

listenQueue =

The maximum number of login requests in the list queue.

Default: 2030

maxMsgSize =

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

Default: 31457280

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 chapter 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.

Default:

pwpPort =

The port number of the primary work process.

In a distributed server environment, the primary port must remain the same on all hosts.

Default: 2270

report =

The time interval in seconds in which an Agent sends or the Automation Engine saves the logging to the database.

Default: 60

retryWait =

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

Format: (number, interval)

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.

Default: (3,10)

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: (3,10)

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.

Default: 1024k

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.

Default: 1024k

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.

Activate this setting if the server should reject connections where the IP addresses do not match.

Values

  • 0: The TCP/IP connection and the IP address are not checked.
  • 1: Activates the query.

Default: 0

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=.

Default:

snmpReconnect =

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

Default: 500

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.

Default: 6600

tcp_Nodelay =

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

Values

  • 0: Activates Nagle algorithm on all sockets.
  • 1: Deactivates the Nagle algorithm on all sockets.

Default: 1

[ PORTS ]
CP.PORTS =

List of semicolon-separated ports or a range of ports to which CPs will bind. CPs bind in the order as listed.

A range can be specified with a dash (-) in between a starting and an ending port.

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

Default: 2217-2221

JCP.PORTS =

List of semicolon-separated ports or a range of ports to which JCPs will bind. JCPs bind in the order as listed.

Use this setting if you do not want JCPs to automatically bind to random ports.

A range can be specified with a dash (-) in between a starting and an ending port.

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

Default: 2317

JWP.SYNC.PORTS =

List of semicolon-separated ports or ranges of ports on which JWPs will listen for incoming connections from WPs. JWPs bind in the order as listed.

Use this setting if you do not want JWPs to automatically bind to random ports.

A range can be specified with a dash (-) in between a starting and an ending port.

Default: 2271-2279

[ DB_SERVICE ]
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

Default: localhost:2217

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: A-Z, 0-9, $, @, _, -, .

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.

The name of the database agent has to be unique in the whole system. Change it accordingly if you use this ini file in a distributed server environment. Usually, the field remains empty so that the name of the host is used automatically.

Default:

tcp/ip =

traceflag

Default: 0

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.

Default:

keyStore =

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

Default: KStore.ini

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.

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

Default: 60

retention_time =

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

Default: 60

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.

Default: 10

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.

Values

  • 0: Database optimization off.
  • 1: Database optimization on.

Default: 1

[ ODBC ]
sqlDriverConnect =

Connection String for the database.

General format of the connection string is "OBDCVAR=<cmd>,<odbc-string>"

<cmd> is an eight figure command field for controlling database accesses like follows

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.

8. Position = Type of SQL Syntax; P - PostgreSQL.

<odbc-string> contains standard and vendor related keywords and values

DSN - Alias name of the database connection.

UID - User ID for database access. Note that this parameter is case sensitive.

PWD - Password for database access.

For Microsoft SQL Server only: Connection String can be extended with MARS Connection setting. We strongly recommend to set Mars_Connection=Yes.

For Oracle only: Code page settings must correspond to those of the database. Either use the environment variable NLS_LANG or extend the connection string with Session Parameters like this: "SP=NLS_LANGUAGE=language,NLS_TERRITORY=area,CODESET=character set,RECONNECT=interval"

Values

  • ODBCVAR=NNNNNNRN,DSN=UC4;UID=uc4;PWD=--1037B2E22BF022EBE2;Mars_Connection=Yes: Microsoft SQL Server with MARS
  • ODBCVAR=SNNNNNRN,DSN=UC4;UID=uc4;PWD=--1037B2E22BF022EBE2: Microsoft SQL Server without MARS
  • ODBCVAR=NNJNIORO,DSN=UC4;UID=uc4;PWD=--1037B2E22BF022EBE2;SP=NLS_LANGUAGE=AMERICAN,NLS_TERRITORY=AMERICA,CODESET=WE8ISO8859P15: Oracle
  • ODBCVAR=NNJNIORP,host=localhost port=5432 dbname=UC4 user=UC4 password=--1037B2E22BF022EBE2 connect_timeout=10 client_encoding=LATIN9: PostgreSQL

Default: ODBCVAR=SNNNNNRN,DSN=UC4;UID=uc4;PWD=--10BFDC349F38156A22

[ JDBC ]
sqlDriverConnect =

The JDBC connection string to connect JAVA based worker processes (JWP) to the database.

Values

  • jdbc:sqlserver://localhost:1433;databaseName=AUTOMIC: MS SQL Server
  • jdbc:db2://localhost:50000/AUTOMIC: DB2
  • jdbc:oracle:thin:@//localhost:1521/AUTOMIC: ORACLE
  • jdbc:postgresql://localhost:5432/AUTOMIC: PostgreSQL

Default:

[ JWP ]
allowDbTracing =

By default, JWP will ignore the traceflag set for database operations for performance resons. Set this to "0" to explicitly disable db-tracing according to DATABASE traceflag.

Values

  • 0: Database operations will never write to tracefile, even when enabled using traceflags.
  • 1: Database operations will write to tracefile when and how it is configured in traceflags.

Default: 1

libpath =

Semicolon separated list of directories where to look for optional external 3rd party libraries. Configure this with path to CyberArk SDK library if you want to enable CyberArk integration.

Default:

[ REST ]
host =

Hostname where the REST API will be reachable from external. Configure this when using an SSL Termination proxy.

Default:

port =

Port where the REST API will accept HTTP/HTTPS requests

Default: 8088

sslEnabled =

Defines if HTTP or HTTPS will be used

Values

  • 0: HTTP will be used
  • 1: HTTPS will be used

Default: 0

keystore =

Path and file where the keystore for the SSL certificate is stored

Password might be encrypted with our encrypting tool (UCYBCRYP Utility)

It's a must to define a keystore. If the parameter is missing or if it points to a wrong target, the JCP server will terminate.

Default: ./httpsKeyfile

keystorePassword =

Password of the keystore File

Password might be encrypted with our encrypting tool (UCYBCRYP Utility)

Default: changeit

keyPassword =

Password for the Keys protection

Default: changeit

docu =

Enable or disable the REST-API documentation on this URL: http[s]://{host}:{port}/ae/api/{version}.

Values

  • 0: Documentation is disabled
  • 1: Documentation is enabled

Default: 1

parallelDbConnections =

The maximal number of parallel connections to the database so requests can be processed at the same time

Values

  • 1..99: Number of parallel connections

Default: 5

sessionTimeout =

Session timeout in seconds, if a session is not used within this time span the AE user session is closed

Values

  • 2..2147483648: seconds (maxvalue 2^31)

Default: 120

corsSupportEnabled =

Enable or disable the Access-Control-Allow-Origin response header configured with CORSACCESSCONTROLALLOWORIGIN, more details: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS.

Values

  • 0: CORS requests are not allowed
  • 1: CORS requests are allowed

Default: 0

corsAccessControlAllowOrigin =

This sets the The Access-Control-Allow-Origin response header which indicates whether the response can be shared with resources with the given origin. If multiple origins are allowed, they must be separated with char ','. Use char '*' if all origins should be allowed.

Default: *

gzipSupportEnabled =

Enable GZIP compression for REST API responses.

Values

  • 0: gzip support is disabled
  • 1: gzip support is enabled

Default: 0

minPoolSize =

Minimum number of threads waiting for incoming requests, raise this if you expect multiple parallel requests to maximize the response time.

Default: 8

maxPoolSize =

Maximum number of threads waiting for incoming requests.

Default: 200

idleTimeout =

Set the maximum idle time for threads in the thread pool. Threads that are idle for longer than this period may be stopped.

Default: 60000

[ OBJECTSEARCH ]
index.cache.folder =

Path to the folder where the search index wil be stored.

Default: indexCache

update.batch.size =

Amount of objects that get indexed simultaneously

Default: 1000

[ CAPKI ]
certificate =

Path to the file where the certificate is stored

Default:

key =

Path to the file containing the private key

Default:

chain =

Some certificates may require an intermediate certificate for validation if the signing certificate authority is not trusted directly. The location of the intermediate certificate can be set here.

Default:

trusted_cert_folder =

Path to the trusted certificate files

Default: