: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 Considerations

Keep the following prerequisites, rules, and behaviors in mind when using this script statement:

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

Parameter	Description	Format	Allowed Values / Notes
Setting	Addresses the system setting that should be changed.	AE name, script literal, or script variable	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.	Script literal, script variable, AE name, or script function	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.	Script literal, script variable, or script function	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 Configuring the Traces for Agents in AWI. For SERVER_MODE: Server type. 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.	AE name, script literal, or script variable	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.	AE name, script literal, or script variable	For SET_TRACE: Buffer size in MB.
Trace Search Text	(Optional) Text that should be searched for in the traces.	AE name, script literal, or script variable	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.