: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 causes all open transactions of the script to be written 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_SETTINGSetting, Component, Value[, Trace Target, Trace Memory Buffer Size, TraceSearch 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 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 Advanced Options - Tracing
- 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 Java work processes and work processes.

: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_SETTINGSET_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.