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. After waiting for the cache to refresh, agents needing re-applied updated settings must be disconnected using the administration panel. Doing so does not cancel any already executing jobs or file transfers. The agent is still running with the old settings if you do not reconnect it.
• 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.

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:

  Windows: ANONYMOUS_FT=Y and logon=0

  UNIX: login_check=no

• 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

  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)

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

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

See also:

• List of VARA Objects for System and Client Values
• User-Defined VARA Objects