UC_HOSTCHAR_DEFAULT - Host Characteristics

This Variable (VARA) object contains default agent settings and it is supplied with system client 0000. You can copy this variable and rename it to UC_HOSTCHAR_<SUFFIX> to define specific agent settings.

Notes:

In the UC_EX_HOSTCHAR variable, you can assign only one variable with the same suffix to each agent, see UC_EX_HOSTCHAR - Assigning Agents to Host Characteristics
Due to performance reasons, changes in UC_EX_HOSTCHAR and UC_HOSTCHAR_DEFAULT take up to one minute to take effect. These variables are cached and refreshed every minute.
The column FT Protocol in the respective key indicates whether the file transfer settings apply for the old and/or the new protocol. For more information, see Secure File Transfer Protocol.

Watch the video:

Disclaimer: This video has been recorded for version 12.3, this is why you will notice minor variations between the interface elements. These are entirely cosmetic and will not affect your overall experience in any way.

This variable includes the following keys:

ANONYMOUS_FE, ANONYMOUS_FT, ANONYMOUS_JOB

Important! The ANONYMOUS_FE (file events), ANONYMOUS_FT (file transfers), and ANONYMOUS_JOB (jobs) keys are only supported for OS/400, UNIX and Windows agents.

Description: These settings can be used to define whether the login credentials that are stored in the Login (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:
Allowed values: Y and N
Default value: N
Restart required: Agent

For more information, see Working with Agents.
FT Protocol Old and new

The behavior of these keys also depends on the settings that are defined in the [GLOBAL] parameter in the INI file of each 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.

Important! Regardless of the agent's OS, it is recommended using the Login object.

You also have to set the privilege Start without Login object specified in the Users object. For more information, see Users (USER).

File Transfers (JOBF)

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

Requirements:
FILE Events

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

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.

APPLICATION_LOGIN

Description: Name of a Login object

The login data of the Login (LOGIN) object is used for the following purposes:
- PS agents: Login data for PeopleSoft
- Windows and UNIX agents: Email connection through SMTP
Default value: ERP_LOGIN
Restart required: Agent

For more information, see Working with Agents.

BACKUP_RETENTION_CHECK

Important! This key affects only Windows and UNIX agents.

Description: Time of day at which the backup folder's lifetime is checked

All files and directories that are older than the value defined in the BACKUP_RETENTION_LIFETIME key are deleted.

Notes:
- 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 INI File of the agent. for more information, see List of Agent Variables.
- In the Rollback page, you can specify the files that must be copied to the backup folder. They are stored automatically when a Job object or File Transfer object is processed.
Allowed values: Valid time
Format: HH:MM:SS
Default value: 00:00:00
Restart required: Agent

For more information, see Working with Agents.

BACKUP_RETENTION_LIFETIME

Important! This key affects only Windows and UNIX agents.

Description: 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 checks this setting daily at the time that is specified in the BACKUP_RETENTION_CHECK key. Contents older than the value defined are deleted.
Allowed values: 0 to 99
Default value: 14
Restart required: Agent

For more information, see Working with Agents.

BLOCK_ON_LOST

Description: Defines the action that a workflow takes if one of its jobs changes its status to ENDED_LOST, see System Return Codes of Executable Objects
Allowed values: YES and NO
Default value: YES
Restart required: No

CHANGE_LOGGING_DAYS

Important! This key is available only for Java-based, Windows, and UNIX agents.

Description: Number of days after which the agent log files are changed
Allowed values: 1 to 32767
Default value: 14
Restart required: Agent

For more information, see Working with Agents.

CHANGE_LOGGING_MB

Important! This key is available only for Java-based, Windows, and UNIX agents.

Description: Size in MB after which the agent log files are changed
Allowed values: 1 to 32767
Default value: 20
Restart required: Agent

For more information, see Working with Agents.

DISCONNECT_AFTER_FT

Description: Defines whether the connection between the agents ends after a File transfer, see File Transfers (JOBF)

This key 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.
Allowed values: YES and NO
Default value: YES
Restart required: Agent

For more information, see Working with Agents.
FT Protocol Old

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

EVENT_CHECKINTERVAL

Description: Time interval in seconds in which the agent checks the conditions FILE_CHANGED and FILE_STABLE in its File events, see FILE Events.

Note: 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.
Allowed values: 60 - 100000
Default value: 60
Restart required: Agent

For more information, see Working with Agents.

EXECUTE_ON_START, EXECUTE_ON_END, EXECUTE_ON_LOST, EXECUTE_ON_ASSIGNMENT

Description: Keys used to start any executable object, see Object Types

The keys are used 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, see System Return Codes of Executable Objects
  
  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, MID, SUBSTR 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 Authorizations Page.
Restart required: No

EXECUTE_ON_DEPLOYMENT_AGENT, EXECUTE_ON_DEPLOYMENT_RUN

Description: Keys used with the CAU to execute objects, see Centralized Agent Upgrade (CAU)

The keys are used in the following situations:
- EXECUTE_ON_DEPLOYMENT_RUN
  
  The objects are executed after a whole CAU deployment run is completed.
  
  You can use the following variables in the object that is executed with the script statement :READ:
  - &uc_ex_cau_name# - Custom text of an agent upgrade
  - &uc_ex_cau_runId# - RunId of the CAU run (the parent of the agent upgrade)
  - &uc_ex_cau_status# - Status (number) of the whole CAU run
- EXECUTE_ON_DEPLOYMENT_AGENT
  
  The objects are executed after a single agent deployment is completed.
  
  You can use the following variables in the object that is executed with the script statement :READ:
  - &uc_ex_host# - Agent 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 of the CAU run (the parent of the agent upgrade)
  - &uc_ex_cau_name# - Custom text of agent upgrade
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

Use the script function PREP_PROCESS_REPORT and 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
Restart required: No

FE_VERSION

Description: Determines which version of the File events functionality should be used, see FILE Events
Allowed values: 1 or 2
- 1: The file event functionality of versions prior to v11.1 is used where no Login object is required, see Login (LOGIN). Make 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, see ANONYMOUS_FE, ANONYMOUS_FT, ANONYMOUS_JOB
- 2: Allows the use of Login objects. The file event is executed under the user that is specified in the Login object. 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.
Default value: 2
Restart required: Agent

For more information, see Working with Agents.

FT_ASYNC_QUIT_MAX, FT_ASYNC_QUIT_MIN, FT_ASYNC_QUIT_NUM

Important! This keys are available only for OS/400, NSK, Windows, UNIX and z/OS agents.

Description: These keys define the settings for synchronous and asynchronous (default) transfers between a sending and a receiving agent of file transfers
- FT_ASYNC_QUIT_MAX
  
  Maximum number of non-confirmed data packages that the sender sends to the receiving agent
  
  Allowed values: 1 - 100
  
  Default value: 60
- FT_ASYNC_QUIT_MIN
  
  Minimum number of non-confirmed data packages that the sender sends to the receiving agent
  
  Allowed values: 0 - 50
  
  The value defined here cannot exceed the value defined in FT_ASYNC_QUIT_MAX.
  
  Default value: 30
- FT_ASYNC_QUIT_NUM
  
  Number of data packages that are confirmed per receipt
  
  Allowed values: 1 - 50
  
  Default value: 5
Note: The higher the value of FT_ASYNC_QUIT_MIN, the better the agent performs when FT_ASYNC_QUIT_MAX is reached.
Restart required: No
FT Protocol New

Synchronous transfer: Data packages are only sent when the receipt of sent packages is confirmed. The sending and receiving agents adjust their transmission speeds.

You have a synchronous behavior when the setting of the FT_ASYNC_QUIT_NUM key equals the setting of the FT_ASYNC_QUIT_MAX key.

Example

FT_ASYNC_QUIT_MIN: 0
FT_ASYNC_QUIT_MAX: 1
FT_ASYNC_QUIT_NUM: 1

Asynchronous transfer: Data packages are sent although no confirmation is received. This allows data to be transferred faster because the connections (faster or slower) are used more efficiently. The TCP/IP buffer of the agent must be increased accordingly using the SendBufferSize= and RecvBufferSize= parameters in the INI file of the agent.

You have an asynchronous behavior when the setting of the FT_ASYNC_QUIT_MAX key is a multiple of the setting of the FT_ASYNC_QUIT_NUM key.

Examples

Weak asynchronous transfer:

FT_ASYNC_QUIT_MIN: 0
FT_ASYNC_QUIT_MAX: 10
FT_ASYNC_QUIT_NUM: 5

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.

Strong asynchronous transfer:

FT_ASYNC_QUIT_MIN: 30
FT_ASYNC_QUIT_MAX: 60
FT_ASYNC_QUIT_NUM: 5

The sending agent may send a maximum of 60 non-confirmed data packages. Receipts are confirmed each 5 packages. The sending agent always waits until 30 non-confirmed data packages are open before it starts the data transfer.

FT_COMPRESS

Description: Compression type for File transfers, see File Transfers (JOBF)
Allowed values: NO and NORMAL
Default value: NO
Restart required: Agent

For more information, see Working with Agents.
FT Protocol Old and new

FT_CONNECTION_TIMEOUT

Description: Duration in seconds after which an unused file transfer connection between two agents is automatically terminated
Default value: 300

Note: It is recommended to increase the default value if you transfer files larger than 3,8 GB) from NSK. Otherwise, the connection could end prematurely.
Restart required: Agent

For more information, see Working with Agents.
FT Protocol New

FT_REPORT_BLKSIZE

Description: Size of a report block for file transfer reports
Minimum value: 2048
Default value: 31744
Restart required: Agent

For more information, see Working with Agents.
FT Protocol New

FT_REPORT_TIME

Description: Time interval in seconds in which the agent sends report block
Minimum value: 1
Default value: 60
Restart required: Agent

For more information, see Working with Agents.
FT Protocol New

FT_RESTARTINFO_CHECK

Description: Time in UTC at which the life time of a file transfer restart information is checked

The restart information is checked on a daily basis and stored locally in the temp directory of the agent with the extension *.sts (StatusStore file). These files are deleted as specified in the FT_RESTARTINFO_LIFETIME key, see FT_RESTARTINFO_LIFETIME.
Default value: 0:00:00
Restart required: Agent

For more information, see Working with Agents.
FT Protocol New

FT_RESTARTINFO_LIFETIME

Description: Number of storage days (life time) for the restart information of file transfers
Minimum value: 1
Default value: 14
Restart required: Agent

For more information, see Working with Agents.
FT Protocol New

FT_RESTARTINFO_INTERVAL

Description: Time interval in seconds in which the agents store the restart points during a file transfer
Minimum value: 1
Default value: 60
Restart required: Agent

For more information, see Working with Agents.
FT Protocol New

FT_STATUS_INTERVAL

Description: 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. For more information, see Viewing Object and Task Details.
Minimum value: 1
Default value: 60
Restart required: Agent

For more information, see Working with Agents.
FT Protocol New

FT_USE_MD5

Description: MD5 checksum usage that allows checking the files that have been transferred in file transfers

This method ensures that the transferred files comply with the source files if the file transfer is restarted.

Note: 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 and N
Default value: Y
Restart required: Agent

For more information, see Working with Agents.
FT Protocol New

JOB_CHECKINTERVAL

Description: Time interval in seconds in which the agents check for job executions
Minimum value: 1

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

Note: An interval lower than 60 seconds increases the load on the server and therefore affects the server's performance.
Default value: 60
Restart required: Agent

For more information, see Working with Agents.

KEEP_ALIVE

Description: Interval in seconds used for heartbeat signals between an agent and its communication process (CP)

Important! This parameter does not apply to Windows, UNIX, and Java agents. To define the keep-alive interval for these agent types, use the WEBSOCKET_TIMEOUT variable in the UC_SYSTEM_SETTINGS. For more information, see WEBSOCKET_TIMEOUT.
Allowed values: 60 and above

If the value is set lower than 60 seconds, the default is used.

The value also must result in complete minutes (60, 120, 180). If a different value is used, it is rounded up to the next minute. So, if the value is set to 99 seconds, the interval used is 120 seconds.
Default value: 600

Important! 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 the KEEP_ALIVE key.
Restart required: Agent

For more information, see Working with Agents.

LOG_TO_DATABASE

Description: Determines whether agent log files are sent to the Automation Engine database or not

For more information, see REPORT_TIME.
Allowed values: Y 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.
Default value: Y
Restart required: Agent

For more information, see Working with Agents.

MAX_FILE_COUNT

Description: Maximum number of files that are considered in File events, see FILE Events

If wildcard characters are used or sub-directories are included in the search, a large 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. It check whether the specified condition applies and, if applicable, triggers the contents of the Event Process page.
Allowed values: 0 to 100000

0 = unlimited.
Default value: 1000
Restart required: Agent

For more information, see Working with Agents.

MAX_REPORT_SIZE

Description: Maximum number of blocks of job reports that are transferred to the Automation Engine database

You can use the REPORT_BLKSIZE key to specify the maximum number of bytes per block, see REPORT_BLKSIZE.

Example
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 agent-specific page of the job. If a report has to be transferred to the Automation Engine, the settings of the REPORT_BLKSIZE and MAX_REPORT_SIZE keys apply. The report is truncated if it exceeds the maximum number of blocks. In this case, an incomplete report is stored in the database.

Notes:
- If the Job reports are stored in the database, the file is deleted on the file system once it has successfully been transferred.
- If the Job report is stored in a file, the settings defined in the REPORT_BLKSIZE and MAX_REPORT_SIZE keys are not considered. In this case, the complete report is stored in the file system. For more information, see Job Reports.
- While the agent is active, this key can temporarily be set in the field Max. Report Blocks in the Advanced Options page. For more information, see Advanced Options - Agent Settings. Once the agent reconnects, the setting of MAX_REPORT_SIZE applies again.
Allowed values: 1 - 10000
Default value: 120
Restart required: Agent

For more information, see Working with Agents.

RECONNECT_TIME

Description: Interval in seconds in which the agent tries to (re)establish a connection to the Automation Engine in case of a new start or when the connection is interrupted

Note: While the agent is active, this key can temporarily be set in the field Check Interval in the Advanced Options page. For more information, see Advanced Options - Agent Settings. Once the agent reconnects, the setting of RECONNECT_TIME applies again.
Allowed values: 1 - 3600
Default value: 600
Restart required: Agent

For more information, see Working with Agents.

REPORT_BLKSIZE

Description: Size of a report block in bytes

For more information, see MAX_REPORT_SIZE.
Allowed values: 1 - 8000
Default value: 8000
Restart required: Agent

For more information, see Working with Agents.

REPORT_TIME

Description: Time interval in seconds in which the agent updates the agent log messages in the Automation Engine system

For more information, see LOG_TO_DATABASE.
Allowed values: 1 to 3600
Default value: 60
Restart required: Agent

For more information, see Working with Agents.

VAR_TIMEOUT

Description: Maximum time in seconds for resolving User-Defined VARA 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. The VAR_TIMEOUT key 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 - 600
Default value: 600
Restart required: Agent

For more information, see Working with Agents.

WORKLOAD_MAX_FT

Description: Maximum number of resources that the agent provides for file transfers

For more information, see Attributes Page.

Note: While the agent is active, this parameter can temporarily be set in the using the field Max. Resources Jobs in the Advanced Options page. For more information, see Advanced Options - Agent Settings. Once the agent reconnects, the setting of the WORKLOAD_MAX_FT key applies again
Allowed values: -1 to 100000

The value -1 corresponds to UNLIMITED, which means that resource settings are ignored for jobs. If the value is set above 100000, the key uses the default value.
Default value: -1
Restart required: No

WORKLOAD_MAX_JOB

Description: Maximum number of resources that the agent provides for jobs

For more information, see Attributes Page.

Note: While the agent is active, this parameter can temporarily be set in the using the field Max. Resources Jobs in the Advanced Options page. For more information, see Advanced Options - Agent Settings. Once the agent reconnects, the setting of the key WORKLOAD_MAX_JOB applies again
Allowed values: -1 to 100000

The value -1 corresponds to UNLIMITED, which means that resource settings are ignored for jobs. If the value is set above 100000, the key uses the default value.
Default value: -1
Restart required: Agent

For more information, see Working with Agents.