:SET_UC_SETTING

Use the SET_UC_SETTING script statement to change the system settings while your system is running. Your modifications are valid until you assign a new value or until the server processes or the agent end. Setting trace options through this script allows you to log the behavior of work processes and agents in exceptional cases. Neither the work processes nor the agents need to be ended in this case. Because tracing can have a noticeable negative effect on system performance, please set or change trace options only in close cooperation with the Support team.

Important! You need the Modify at runtime permission and the Create diagnostic information privilege for this script function. For more information, see Granting Automation Engine Authorizations and Granting Automation Engine Privileges

Notes:

This script statement writes all open transactions of the script to the AE database. For more information, see Script Processing
If you change trace options for JWPs or WPs, these changes apply to all of them. You cannot change trace options for individual JWPs or WPs.
You must change the trace options for JCPs or CPs separately, one at a time.
If you reboot only one work process, it will use the trace options that are specified in the INI file. All other work processes use the values that are specified with the :SET_UC_SETTING script statement until they are rebooted

Syntax

:SET_UC_SETTING Setting, Component, Value[, Trace Target, Trace Memory Buffer Size, Trace Search Text]

Parameters

SET_UC_SETTING
Changes system settings while the system is running
Setting
Addresses the system setting that should be changed
Format: AE name, script literal or script variable
Allowed values:
- WORKLOAD_MAX
  Maximum number of resources the agent provides for file transfers and jobs
- WORKLOAD_MAX_FT
  Maximum number of resources the agent provides for file transfers
- WORKLOAD_MAX_JOB
  Maximum number of resources the agent provides for jobs
- SET_TRACE
  Allows you to change your trace options for the work processes or communication processes of an AE system or agent
- SERVER_MODE
  Type of server process

Component
Addresses the system setting component that should be changed
Format: script literal, script variable, AE name or script function
Allowed values:
- For WORKLOAD_MAX, WORKLOAD_MAX_FT and WORKLOAD_MAX_JOB
  Name of an active agent or agent group
- For SET_TRACE
  Name of an AE system or agent
- For SERVER_MODE
  Name of the server process

Value
New value that should be assigned to the system setting
Format: script literal, script variable or script function
Allowed values:
- For WORKLOAD_MAX, WORKLOAD_MAX_FT and WORKLOAD_MAX_JOB
  Any value between -1 and 100000, or UNLIMITED
  Important! Values greater than 100000 are handled as UNLIMITED
- For SET_TRACE
  16-digit string where each digit corresponds to a particular trace flag such as the first position which refers to the TCP/IP trace flag, for example.
  The order of the trace flags complies with the order that you see in the Advanced Options section of the Administration perspective for server processes and agents. For details, see Defining Agent Tracing Settings
- For SERVER_MODE
  Server type
  Allowed values:
  - D
    Switches to a dialog process
  - W
    Switches to a work process

Trace Target
(Optional) Target to which traces should be written
Format: AE name, script literal or script variable
Allowed values:
- For SET_TRACE
  - FILE
    Traces are written to a file
  - MEMORY
    Traces are written to the internal memory of the agent or the server processes

Trace Memory Buffer Size
(Optional) Size of the provided memory
Format: AE name, script literal or script variable
Allowed values:
- For SET_TRACE
  Buffer size in MB

Trace Search Text
(Optional) Text that should be searched for in the traces
Format: AE name, script literal or script variable
Allowed values:
- For SET_TRACE
  Search text

Examples

The first example sets the number of resources the WIN01 agent provides for jobs and file transfers to 1000. The result is written to the activation report.

:SET_UC_SETTING WORKLOAD_MAX, WIN01, 1000
:SET &RET# = GET_UC_SETTING(WORKLOAD_MAX_JOB, WIN01)
:PRINT &RET#

The second example retrieves the name of the AE system and then activates the TCP/IP trace for its JWPs and WPs:

:SET &TRC# = GET_UC_SYSTEM_NAME()
:SET_UC_SETTING SET_TRACE, &TRC#, "1000000000000000"

Alternatively, you can use the system name to address all WPs and JWPs:

:SET_UC_SETTING SET_TRACE, &$SYSTEM#, "2400000000000000"

The following example shows how you change the system settings for two CPs, as they must be set separately:

:SET_UC_SETTING SET_TRACE, "AUTOMIC#CP002", "1300000000000000"
:SET_UC_SETTING SET_TRACE, "AUTOMIC#CP003", "1200000000000000"

The following example changes the server process AE#WP003 to a dialog process provided that it is active.

:IF SYS_SERVER_ALIVE("AE#WP003") = "Y"
: SET_UC_SETTING "SERVER_MODE", "AE#WP003", "D"
:ELSE
: SEND_MSG "ADMIN","AE","Work process AE#WP003 is not active!"
:ENDIF

The following example sets the trace options for the AE system with defined values and searches for the first Job that ended abnormally with the error message 11003.

Note: If a trace includes this message number, the trace is written to a file, and not to the memory.

:SET_UC_SETTING SET_TRACE, &$SYSTEM#,"2400000000000000", "MEMORY", "128", "U00011003"

The last example sets the trace options for the WINAGENT01 agent with specific values and searches for the first file transfer that ended abnormally.

:SET_UC_SETTING SET_TRACE, "WINAGENT01", "2400000000000000", "MEMORY", "128", "File Transfer * ended abnormally."

Note: If a trace includes this message text, the trace is written to a file, and not to the memory.