: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 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 Advanced Options - Tracing
    • For SERVER_MODE

      Server type

      Allowed values:
      • D

        Switches to a dialog process
      • W

        Switches to a work process
    • Important! You cannot change a work process to a dialog process if it performs a Server role.

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

See also: