UC_HOSTCHAR_DEFAULT - Host Characteristics

This variable is used to specify settings for agents.

The variable is available in system client 0000. It contains default settings which apply to agents. Different settings can easily be created by copying this variable and renaming the copies to UC_HOSTCHAR_<SUFFIX> whereas <SUFFIX> can be any term. To each agent, you can assign exactly one of these UC_HOSTCHAR_ variables with its suffix in the variable UC_EX_HOSTCHAR whereas the suffix ‘DEFAULT’ is the default.

Below, the column New start required denotes which component requires a new start after a change to the setting, whereas the column FT Protocol indicates whether the file transfer settings apply for the old and/or the new protocol (see File Transfer (FT) Procedure).

Key

Value

New start required

FT protocol

ANONYMOUS_FE
ANONYMOUS_FT
ANONYMOUS_JOB

Influence usage of login data for the execution of jobs, file events, and file transfers, respectively

The settings ANONYMOUS_FE, ANONYMOUS_FT and ANONYMOUS_JOB are only supported for OS/400, UNIX and Windows agents.

  • ANONYMOUS_FE - for file events
  • ANONYMOUS_FT - for file transfers
  • ANONYMOUS_JOB - for jobs

Allowed values: Y and N (default)

These settings can be used to define whether the login credentials that are stored in the Login object have to be used to execute jobs, file events, and file transfers, respectively. The behavior also depends on the settings that are defined in the following INI-file parameters of the agent:

Windows

  • logon=0

    The login data that is stored in the Login object is not used. The job, file event, and/or file transfer runs under the user of the agent's OS.

  • logon=1

    The Login object is used.

UNIX

  • login_check=no

    The job, file event, and/or file transfer runs with the user of the OS that is stored in the Login object. Passwords are not checked.

    Requirement: The agent must run under a privileged user.

    Note: If the UNIX agent runs under a non-privileged user, the agent can start jobs only with the user who started the agent itself. For this purpose, the agent must also run in anonymous mode (login_check=no and ANONYMOUS_*=Y).

  • login_check=yes

    The Login object is used.

OS/400

  • CheckLogon=0

    The job, file event, and/or file transfer runs with the user of the OS that is stored in the Login object. Passwords are not checked.

    Requirement: The agent must run under a privileged user.

  • CheckLogon=1

    The Login object is used.

For file transfers, you can set the following privilege in the User object:



FileTransfer: Start without Login object specified



With this privilege, file transfers even may be executed without Login objects. Such file transfers are executed under the agent's OS user.

Requirement: ANONYMOUS_FT=Y and logon=0 (Windows) or login_check=no (UNIX).

For file events, you can set the following privilege in the User object:

File event: Start without Login object specified


With this privilege, file events even may be executed without Login object. Such file events are executed under the agent's OS user.
ANONYMOUS_FE and configuration file parameters such as logon (Windows) or login_check (UNIX), or check_logon (OS/400) are ignored.

There is no privilege available in the User object that allows to start jobs without a Login object. Therefore, even if you define ANONYMOUS_JOB=Y, jobs without Login objects abort.

Agent Old and new

APPLICATION_LOGIN

The name of a Login object.

The login data of the Login object is used for:

  • PS agents: Login data for PeopleSoft
  • Windows and UNIX agents: E-mail connection through SMTP

Default value: ERP_LOGIN

Agent

 
BACKUP_RETENTION_CHECK

The time of day at which the backup folder's lifetime will be checked.

All files and directories that are older than the BACKUP_RETENTION_LIFETIME will be deleted.

The backup folder stores the files of the file rollback of jobs and file transfers. You can define the backup folder using the Agent variable UC_EX_PATH_BACKUP in the agent's INI file.

In the Rollback page, you can specify the files that should be copied to the backup folder. They are stored automatically when a Job object or FileTransfer object is processed.

Only affects Windows and Unix agents.

Allowed values: Valid time in the format HH:MM:SS
Default value: "00:00:00"

Agent  
BACKUP_RETENTION_LIFETIME

The life time in days for the content of the backup folder.

With this key, you can determine how long files and directories are kept in the backup folder. The system daily checks this setting at the time that is specified in BACKUP_RETENTION_CHECK. Content which is older is deleted.

Only affects Windows and Unix agents.

Allowed values: "0" - "99"
Default value: "14"

Agent  

BLOCK_ON_LOST

This entry can be used to define the action that a workflow should take if one of its jobs changes its status to ENDED_LOST.

Allowed values: YES (default) and NO

YES - The workflow blocks.
NO - The workflow does not automatically block.

No

 

DISCONNECT_AFTER_FT

This defines whether the connection between the agents ends after a file transfer.

YES - The connection ends after the file transfer (default).
NO - The connection does not end after file transfer.

This parameter only affects the connection but not the execution of the file transfer. The system always checks whether there is a connection to the destination agent BEFORE the file transfer starts. A connection is established if it is not available.

In the 32-bit UNIX agent for SunSolaris, the number of filter descriptors (open connections and files) is limited to 253. Keep this in mind when you execute jobs / file transfers and when you use the setting DISCONNECT_AFTER_FT = "NO". Automic recommends using the value "YES".

This setting is only checked if you use the old file transfer protocol. Using the new protocol means that the connection is always automatically terminated.

Agent

Old
EVENT_CHECKINTERVAL

The time interval in seconds the agent periodically checks the conditions FILE_CHANGED and FILE_STABLE in its file events.

Allowed values: 60 - 100000
Default value: 60

If you select FILE_CHANGED or FILE_STABLE in a file event, this interval is used for all condition checks.

The interval increases automatically if the check of a condition takes longer than the specified interval.

Agent  

EXECUTE_ON_ASSIGNMENT
EXECUTE_ON_END
EXECUTE_ON_LOST
EXECUTE_ON_START

These keys can be used to start any executable object in the following situations:

  • EXECUTE_ON_START

    The executable object starts when the agent starts

    Default value: UC_EXECUTOR_START

    You can use the script variable &uc_ex_host - Agent name to read the agent name from the read buffer.

  • EXECUTE_ON_END

    The executable object starts when the agent ends

    Default value: UC_EXECUTOR_END

    You can use the script variable &uc_ex_host - Agent name to read the agent name from the read buffer.

  • EXECUTE_ON_LOST

    The executable object starts when a task ended with ENDED_LOST

    Default value: UC_EXECUTOR_LOST

    You can use the following script variables:

    • &uc_cause_host - Agent name

    • &uc_cause_type - Object type

    • &uc_cause_name - Object name

    • &uc_cause_nr - RunID

    • &uc_cause_parent - Superordinate task

  • EXECUTE_ON_ASSIGNMENT

    The executable object starts when an agent is assigned

    Default value: UC_EXECUTOR_ASSIGNMENT

    You can use the following script variables:

    • &uc_ex_host - Agent name

    • &uc_ex_auth_mode# - Type of modification

      Possible values:

      • AUTO - The modification was performed automatically by an Agent/Client Assignment object

      • MANUAL - The modification was performed manually directly in the Agent object

    • &uc_ex_auth# - Returns new rights in the form of a 3-digit string (missing rights are displayed with "n").

      Example 

      RnX - The agent now has the right to read and execute.

      Note: You can also use the script function STR_CUT to access the individual digits

Use the script statement :READ to retrieve the values for the script variables.

Example

:READ &uc_ex_host,,

:
PRINT &uc_ex_host

Notes:

  • The objects are searched and activated in all clients in which the agent is authorized, except system client 0000. However, EXECUTE_ON_ASSIGNMENT searches all clients in which authorizations have changed.
  • The objects assigned to EXECUTE_ON_START, EXECUTE_ON_END, EXECUTE_ON_LOST, and EXECUTE_ON_ASSIGNMENT start in the clients where they exist but they run under the user UC/UC of the system client 0000 with this client authorizations. Therefore, authorizations at object level are ignored. For more information, see the Authorization Page.

No

 
EXECUTE_ON_DEPLOYMENT_AGENT EXECUTE_ON_DEPLOYMENT_RUN

These keys are used with the Centralized Agent Upgrade Process.

You can use these keys to execute objects in the following situations:

  • After a whole CAU deployment run was completed:
    EXECUTE_ON_DEPLOYMENT_RUN
  • After a single agent deployment has ended:
    EXECUTE_ON_DEPLOYMENT_AGENT

Available variables using the Script statement :READ

You can use the following variables in the object that is executed with the Script statement :READ:

  • EXECUTE_ON_DEPLOYMENT_AGENT
    • &uc_ex_cau_name# - Custom text of an agent upgrade
    • &uc_ex_cau_runId# - RunID CAU top upgrade run
    • &uc_ex_cau_status# - Status (number) of the whole CAU run

  • EXECUTE_ON_DEPLOYMENT_RUN
    • &uc_ex_host# - agent / host name (upgrade on agent level)
    • &uc_ex_deployment_runId# - RunID of child / agent upgrade
    • &uc_ex_deployment_status# - Status (number) of child / agent upgrade
    • &uc_ex_cau_runId# - RunID CAU top upgrade run
    • &uc_ex_cau_name# - Custom text of agent upgrade

Script Examples

Use the script function PREP_PROCESS_REPORT and

  • the parameter CAU in order to process the whole report of a CAU run:

    :SET&HND#=PREP_PROCESS_REPORT(,&uc_ex_cau_runid, "CAU")
    :PROCESS&HND#
    :SET&RET#=GET_PROCESS_LINE(&HND#)
    :PRINT&RET#
    :ENDPROCESS
  • the parameter REP to process the detailed report of a single agent upgrade:

    :SET&HND#=PREP_PROCESS_REPORT(,&uc_ex_deployment_runid#, "REP")
    :PROCESS&HND#
    :SET&LINE#=GET_PROCESS_LINE(&HND#)
    :PRINT&LINE#
    :ENDPROCESS
No  
FE_VERSION

Here you can determine which version of Automic's file event functionality should be used.

Allowed values: "1" or "2" (default)

"1" - The file event functionality of versions before v11.1 is used where no Login object is required. Make also sure that the privilege "File event: Start without Login object specified" is activated in the relevant User object. The setting ANONYMOUS_FE is ignored for file event executions

"2" - This version of the file event functionality allows Login objects to be used. The file event is executed under the user that is specified in the Login object. Please note that the settings for ANONYMOUS_FE also apply. If the privilege "File event: Start without Login object specified" is granted, the Login object can be omitted - in this case the file event is executed under the Agent user.

Agent  
FT_ASYNC_QUIT_MAX,
FT_ASYNC_QUIT_MIN,
FT_ASYNC_QUIT_NUM

The settings for synchronous / asynchronous transfers between a sending and a receiving agent of file transfers. Asynchronous transfers are the default setting.

Synchronous transfer: Data packages are only sent when the receipt of sent packages has been confirmed. Sender and receiver adjust their transmission speeds. A synchronous behavior is achieved when the setting FT_ASYNC_QUIT_NUM equals FT_ASYNC_QUIT_MAX.

Asynchronous transfer: Data packages are sent although confirmations are still missing for sent packages. In doing so, data can be transferred faster because a faster sender or a slower connection are used more efficiently. The agents' TCP/IP buffer (INI-file parameter: SendBufferSize= and RecvBufferSize=) should be increased accordingly.

An asynchronous behavior is achieved when FT_ASYNC_QUIT_MAX is a multiple of FT_ASYNC_QUIT_NUM.

The higher the value of FT_ASYNC_QUIT_MIN, the more the receiving agent will be unburdened when FT_ASYNC_QUIT_MAX has been reached.

These options are only effective in OS/400, NSK, UNIX, Windows and z/OS agents.

FT_ASYNC_QUIT_MAX

Maximum number of non-confirmed data packages that the sender sends to the receiving agent.

Minimum value: 1, default value: 60, maximum value: 100

FT_ASYNC_QUIT_MIN

Number of non-confirmed data packages as of which the sender sends them to the receiver.

Minimum value: 0, default value: 30, maximum value: 50

FT_ASYNC_QUIT_NUM

Number of data packages that are confirmed per receipt.

Minimum value: 1, default value: 5, maximum value: 50

Note that the value that is specified as the MIN setting must not exceed the MAX setting.

For example:

FT_ASYNC_QUIT_MIN / MAX / NUM:
0 / 1 / 1: Synchronous file transfer
0 / 10 / 5: Weak asynchronous transfer. The sending agent may send a maximum of 10 non-confirmed data packages. If the maximum has been reached, it waits until all receipts have been confirmed before it continues the sending process.
30 / 60 / 5: Strong asynchronous transfer. The sender may send a maximum of 60 non-confirmed data packages to the receiver. Receipts are confirmed per 5 packages. The sender always waits until 30 non-confirmed data packages are open before it starts the data transfer.

No New

FT_COMPRESS

he compression type for file transfers (see Defining File Transfer Objects).

Allowed values: NO (default) and NORMAL

Agent

Old and new
FT_CONNECTION_TIMEOUT

The duration in seconds after which an unused file transfer connection between two agents is automatically terminated.

Default value: 300 seconds

Automic recommends increasing this setting's default value (5 min) if you transfer huge files (> 3,8 GB) from NSK. Otherwise, the connection could end prematurely.

Agent New
FT_REPORT_BLKSIZE

The size of a report block for file transfer reports.

Minimum value: 2048
Default value: 31744

Agent New
FT_REPORT_TIME

Time interval in seconds in which the agent sends report blocks.

Minimum value: 1

Default value: 60

Agent New
FT_RESTARTINFO_CHECK

The time in UTC at which the life time of file transfer restart information is checked. It is checked on a daily basis.

This restart information is stored locally in the agent's temp directory in the form of StatusStore files (ending *.sts). These files are deleted after the life time specified with the key FT_RESTARTINFO_LIFETIME .

Default value: 0:00:00

Agent New
FT_RESTARTINFO_LIFETIME

The number of days the restart information of file transfers is stored (life time).

Minimum value: 1
Default value: 14 days

Agent New
FT_RESTARTINFO_INTERVAL

The time interval in seconds in which the agents store the restart points during a file transfer.

Minimum value: 1
Default value: 60 seconds

Agent New
FT_STATUS_INTERVAL

The time interval in seconds in which the agents send the status information of file transfers to the Server.

The status of file transfers is displayed in the task's details (see (Viewing Object and Task Details).

Minimum value: 1
Default value: 60 seconds

Agent New
FT_USE_MD5

MD5 checksum usage that allows for the files that have been transferred in file transfers to be checked. This method ensures that the transferred files comply with the source files if the file transfer is restarted.

For performance reasons, the MD5 checksum is not calculated for files that are smaller than 1MB. This behavior is always valid, regardless of the definitions that have been made in this setting.

Allowed values: Y (default) and N

Agent New

JOB_CHECKINTERVAL

Time interval in which the agents periodically check for job executions.

Minimum value: 1
Default value: 60 seconds

There is no upper limit for this setting. The default value is used if 0 is defined.

Be aware that a smaller interval than 60 seconds will increase the load on the server and therefore affect server performance.

Agent

 

KEEP_ALIVE

Keep alive interval used for heartbeat signals between an agent and its CP.

Allowed values: 60 and above
Default value: 600 seconds

The value that is defined here must not be less than 60 seconds. Otherwise, the default value is used.

The specified value must also result in complete minutes (such as 60, 120, 180). If you use a different value, it is rounded up to the next minute (for example, a value of 99 seconds results in 120 seconds).

A fixed value of 60 seconds is always added to the specified value. Therefore, the actual minimum is 120 seconds. The Administration perspective always displays the value that has been set by using KEEP_ALIVE.

Agent

 
LOG_TO_DATABASE

Determines whether agent log files are sent to the Automation Engine database or not. See also the description of REPORT_TIME.

Allowed values: Y (default) and N

Y - The agent sends its log-file messages also to the Automation Engine where they can be accessed as report of the Agent object.
N - The agent does not send log messages to the Automation Engine. This setting improves the Automation Engine system's performance.

Agent  
MAX_FILE_COUNT

The maximum number of files that are considered in file events.

Allowed values: 0 - 100000
Default value: 1000

0 - Unlimited

If wildcard characters are used or sub-directories are included in the search, a huge number of files can be found during the checks. For performance reasons, you can specify a maximum number of files that are considered.

The agent checks files only up to this number whether the specified condition applies and, if applicable, triggers the contents of the Event Process page.

Agent  

MAX_REPORT_SIZE

Maximum number of blocks of job reports transferred to the Automation Engine database.

Allowed values: 1 - 10000

Default value: 120 blocks

The key REPORT_BLKSIZE can be used to specify the maximum number of bytes per block.

For example:

Block size: 8000 bytes

Number of report blocks: 120

This definition results in a maximum report size of 937 KB.

After job execution, a job report can be stored locally in the file system and/or can be transferred to the Automation Engine which then stores it in its database. This is defined in the host-specific page of the job. If a report has to be transferred to the Automation Engine, the settings REPORT_BLKSIZE and MAX_REPORT_SIZE apply and the report is truncated accordingly if it would exceed the maximum number of blocks. In this case, an incomplete report is stored in the database.

- If only the option "Job report" - "Database" has been selected, the file is deleted on the file system once it has successfully been transferred.

- If the option "Job report" - "File" has been selected, the settings REPORT_BLKSIZE and MAX_REPORT_SIZE are not considered. In this case, the complete report is stored in the file system.

While the agent is active, this parameter can temporarily be set in the Advanced Options page in the field Max. Report Blocks. Once the agent reconnects, the setting of MAX_REPORT_SIZE applies again.

Agent

 

RECONNECT_TIME

Time interval in which the agent frequently tries to (re)establish a connection to the Automation Engine in case of a new start or when the connections has been interrupted.

Allowed values: 1 - 3600

Default value: 600 seconds

While the agent is active, this parameter can temporarily be set in the Advanced Options page in the field Check Interval. Once the agent reconnects, the setting of RECONNECT_TIME applies again.

Agent

 

REPORT_BLKSIZE

Size of a report block. See also the description of MAX_REPORT_SIZE.

Allowed values: 1 - 8000
Default value: 8000 Bytes

Agent

 

REPORT_TIME

Time interval in which the agent updates the agent log messages in the Automation Engine system. See also the description of LOG_TO_DATABASE.

Allowed values: 1 - 3600
Default value: 60 seconds

Agent

 
VAR_TIMEOUT

Maximum time in seconds for resolving Variables objects with the sources BACKEND and SQL.

Backend variables run a command on an OS (such as Windows or UNIX) and deliver the result as values. SQL variables process SQL commands on an external database and return its results as values.

VAR_TIMEOUT specifies the time limit for these actions. If this limit is exceeded, processing and the task that uses the variable are canceled.

Allowed values: 1 to 600
Default value: 600

Agent  
WORKLOAD_MAX_FT

Maximum number of resources that the agent provides for file transfers (see Attributes Pages of Executable Objects).

Allowed values: -1 to 100000

Default values: -1

The value -1 corresponds to UNLIMITED which means that the resource settings are ignored for file transfers.

Values above 100000 are treated as -1.

While the agent is active, this parameter can temporarily be set in the Advanced Options page in the field Max. Resources FileTransfer. Once the agent reconnects, the setting of WORKLOAD_MAX_FT applies again.

No  
WORKLOAD_MAX_JOB

Maximum number of resources that the agent provides for jobs (see Attributes Pages of Executable Objects).

Allowed values: -1 to 100000

Default value: -1

The value -1 corresponds to "UNLIMITED", which means that resource settings are ignored for jobs.

Values above 100000 are treated as -1.

While the agent is active, this parameter can temporarily be set in the Advanced Options page in the field Max. Resources Jobs. Once the agent reconnects, the setting of WORKLOAD_MAX_JOB applies again.

Agent  

Due to performance reasons, changes in UC_EX_HOSTCHAR and UC_HOSTCHAR_DEFAULT take up to one minute until the changes have an impact. These variables are cached and only refreshed every minute.

See also:

Overview of all variables in Table Form
Variable