MODIFY_SYSTEM

Use the MODIFY_SYSTEM script function to process the actions of a ServiceManager connected to the AE system, modify Queue objects, control steps in a Zero Downtime Upgrade scenario, and process Centralized Agent Upgrade (CAU) actions. Which actions this script function takes depend on the parameters that you define.

Important! To start server processes and agents by using this script element requires that a ServiceManager is available that is correctly configured and connected to the AE system. Refer to the settings in the Attributes page of Agents or Server objects. For more information, see Defining the Attributes Page.

This page includes the following:

Queue Objects

Use the MODIFY_SYSTEM script function to change the values or states of Queue objects (GO/STOP).

Syntax

MODIFY_SYSTEM (Action, Queue, Value)

Parameters

Parameter	Description	Format / Allowed Values
Action	Defines the modifications to be made in Queue objects: MODE: Queue status, start or stop of queue task execution. Note: Changing the status of Queue objects with Start or Stop by using this script element in the MODE action has the effect that the new status is valid until a new modification is made. MAX_SLOTS: Maximum number of tasks that can run at the same time (max. slots). Note: Modifications to the maximum queue slots remain valid until these values are changed due to an exception or if a user changes them manually, see Considering ERT in Queue Objects. PRIORITY: Task priority. Note: Modifications to the priority remain valid until these values are changed due to an exception or if a user changes them manually, see Considering ERT in Queue Objects.	Script literal or script variable
Queue	Name of the Queue object that should be changed.	Script literal or script variable
Value	Value for the setting or status that should be changed (Action): For the Action-type MODE: GO or STOP. For the Action-type MAX_SLOTS: Any number between 0 and 99999, or UNLIMITED. Note: The number of parallel running tasks is not limited if the maximum slots of Queue objects are changed to UNLIMITED. For the Action-type PRIORITY: Any number between 0 and 255.	Script literal or script variable

Parameter

Description

Format / Allowed Values

Action

Defines the modifications to be made in Queue objects:

MODE: Queue status, start or stop of queue task execution.
Note: Changing the status of Queue objects with Start or Stop by using this script element in the MODE action has the effect that the new status is valid until a new modification is made.
MAX_SLOTS: Maximum number of tasks that can run at the same time (max. slots).
Note: Modifications to the maximum queue slots remain valid until these values are changed due to an exception or if a user changes them manually, see Considering ERT in Queue Objects.
PRIORITY: Task priority.
Note: Modifications to the priority remain valid until these values are changed due to an exception or if a user changes them manually, see Considering ERT in Queue Objects.

Script literal or script variable

Queue

Name of the Queue object that should be changed.

Script literal or script variable

Value

Value for the setting or status that should be changed (Action):

For the Action-type MODE: GO or STOP.
For the Action-type MAX_SLOTS: Any number between 0 and 99999, or UNLIMITED.
Note: The number of parallel running tasks is not limited if the maximum slots of Queue objects are changed to UNLIMITED.
For the Action-type PRIORITY: Any number between 0 and 255.

Script literal or script variable

Example

The following example sets the status of the Queue object QUEUE.JOBS to GO:

:SET &RET# = MODIFY_SYSTEM("MODE", "QUEUE.JOBS", "GO")

:IF &RET# = "0"

:PRINT "Processing the Queue object QUEUE.JOBS has successfully been activated."

:ELSE

:PRINT "QUEUE.JOBS: Error when changing the status to GO."

:ENDIF

Return Codes

0: The action defined for this script function has successfully been processed.
11901: The specified Queue object could not be found in the client.
20836: An invalid value has been specified for the Queue object's priority or max. slots.
20837: An invalid value has been specified for the parameter MOD.

ServiceManager

Use the MODIFY_SYSTEM script function to process the actions of a ServiceManager connected to the AE system.

Syntax

MODIFY_SYSTEM (Action, Name [,Server mode])

Parameters

Parameter	Description	Format / Allowed Values
Action	Defines the action to be taken for agents, server processes, or the AE system: STARTUP: Starts an agent or a server process. Note: You can only use this action if a ServiceManager is available and if the agent or the server process to be started is correctly configured. Refer to the settings in the Attributes page of Agents or Server objects. For more information, see Defining the Attributes Page. TERMINATE: Ends an agent or a server process. SHUTDOWN: Shuts down the complete AE system. Note: To shut down the AE system with SHUTDOWN, you must set UC4 as the value for the Name parameter. For more information, see :SHUTDOWN. CHANGE_MODE: Changes the mode of a Server's work process (WP). DISCONNECT: Closes the agent connection and re-establishes it.	Script literal or script variable
Name	Name of the agent or server process that should start or end, or whose mode you want to change.	Script literal or script variable
Server mode	(Optional) Mode to which the specified WT should change. Important! Do not use this parameter together with the STARTUP, TERMINATE, DISCONNECT, and SHUTDOWN action. Allowed values: D: Dialog process. W: Work process.	Script literal or script variable

Parameter

Description

Format / Allowed Values

Action

Defines the action to be taken for agents, server processes, or the AE system:

STARTUP: Starts an agent or a server process.
Note: You can only use this action if a ServiceManager is available and if the agent or the server process to be started is correctly configured. Refer to the settings in the Attributes page of Agents or Server objects. For more information, see Defining the Attributes Page.
TERMINATE: Ends an agent or a server process.
SHUTDOWN: Shuts down the complete AE system.
Note: To shut down the AE system with SHUTDOWN, you must set UC4 as the value for the Name parameter. For more information, see :SHUTDOWN.
CHANGE_MODE: Changes the mode of a Server's work process (WP).
DISCONNECT: Closes the agent connection and re-establishes it.

Script literal or script variable

Name

Name of the agent or server process that should start or end, or whose mode you want to change.

Script literal or script variable

Server mode

(Optional) Mode to which the specified WT should change.

Important! Do not use this parameter together with the STARTUP, TERMINATE, DISCONNECT, and SHUTDOWN action.

Allowed values:

D: Dialog process.
W: Work process.

Script literal or script variable

Example

The following example shuts down the agent WIN01:

:SET &ACT# = MODIFY_SYSTEM("TERMINATE", "WIN01 ")

Return Codes

11677: The ServiceManager call could not be processed. No CP is started.
11678: Server or agent has not started.
11679: Successful ServiceManager query.
11680: Connection to ServiceManager could not be established, or the specified process could not be found in the ServiceManager.
11681: ServiceManager call is not possible because the specified host type is not supported.
11682: ServiceManager call is not possible because the specified agent / server process could not be found.
11683: ServiceManager call will not be processed because the Server is not linked to the specified ServiceManager, or the same query has already been processed.

Zero Downtime Upgrade

Use the MODIFY_SYSTEM script function to switch the processing direction during a Zero Downtime Upgrade (ZDU) scenario or when finalizing the Zero Downtime Upgrade phase.

Important!

Usage for carrying out an upgrade with zero downtime only, if the UC_SYSTEM_SETTINGS variable, ZERO_DOWNTIME_UPGRADE key is set to "Y".
The database upgrade has to be processed successfully beforehand. At least one CP and one WP of the new version must be up and running.
For more information on Zero Downtime Upgrades, see Upgrade Process.

Syntax

MODIFY_SYSTEM (Action, Value)

Parameters

Parameter	Description	Allowed Values
Action	Zero Downtime Upgrade control.	ZERO_DOWNTIME_UPGRADE
Value	This parameter applies for routing messages processed by new or old WPs/CPs.	BEGIN: Sets the UC_SYSTEM_SETTINGS variable, ZERO_DOWNTIME_UPGRADE key to "Y". END: Sets UC_SYSTEM_SETTINGS variable, ZERO_DOWNTIME_UPGRADE key to "N". Doing so is only possible before taking any steps in the upgrade process. UPGRADE: Defines the upgrade mode. The message queue set belonging to the new CPs and WPs is set active. The PWP role switches to a new WP. Messages are routed to the new processing while the old processing are phased out. ROLLBACK: Defines the rollback mode. The message queue set belonging to the old CPs and WPs is set active. Messages are routed back to the old processing while the new processing is phased out. FINALIZE: Finalizes the Zero Downtime Upgrade phase by setting the currently active message queue set as base and resetting the UC_SYSTEM_SETTINGS variable, ZERO_DOWNTIME_UPGRADE key to "N".

Example

This example shows the settings necessary for starting the rollback:

:SET &RET# = MODIFY_SYSTEM("ZERO_DOWNTIME_UPGRADE", "ROLLBACK")

Return Codes

0: The action defined for this script function has successfully been processed.
11895: Warning for Zero_Downtime_Upgrade: No active CP or WP found for active version. [Specified] mode has been activated.
20833: Runtime error in object [specified]: MODIFY_SYSTEM with opcode ZERO_DOWNTIME_UPGRADE not valid. ZERO_DOWNTIME_UPGRADE not set in UC_SYSTEM_SETTINGS.
20846: Runtime error in object [specified]: MODIFY_SYSTEM(ZERO_DOWNTIME_UPGRADE) not valid with opcode [specified]. Upgrade version not found in DB. Please load version with DB-Load first.
20890: Runtime error in object [specified]: Error in MODIFY_SYSTEM. Function [specified action] not allowed for opcode 'ZERO_DOWNTIME_UPGRADE'.
20891: Runtime error in object [specified]: ZERO_DOWNTIME_UPGRADE - ROLLBACK not possible. There are still [specified] agents connected with version > [specified].
20892: Runtime error in object [specified]: ZERO_DOWNTIME_UPGRADE - ROLLBACK not possible. There are still [specified] active tasks with version > [specified].
20893: Runtime error in object [specified]: ZERO_DOWNTIME_UPGRADE - UPGRADE not possible. No work process with upgrade version active.
20894: Runtime error in object [specified]: ZERO_DOWNTIME_UPGRADE - ROLLBACK not possible. Rollback mode already active.
20895: Runtime error in object [specified]: ZERO_DOWNTIME_UPGRADE - UPGRADE not possible. Upgrade mode already active.
20896: Runtime error in object [specified]: ZERO_DOWNTIME_UPGRADE - FINALIZE not possible. Upgrade mode not active.
20897: Runtime error in object [specified]: MODIFY_SYSTEM(ZERO_DOWNTIME_UPGRADE) not valid with opcode [specified]. Current (base) version not found in DB.
20898: Runtime error in object [specified]: MODIFY_SYSTEM(ZERO_DOWNTIME_UPGRADE) not valid with opcode [specified]. ZERO_DOWNTIME_UPGRADE already set to "Y".
20899: Runtime error in object [specified]: ZERO_DOWNTIME_UPGRADE - FINALIZE_ROLLBACK not possible. Rollback mode not active.
20900: Runtime error in object [specified]: ZERO_DOWNTIME_UPGRADE - END not possible. Upgrade mode still active. Use FINALIZE first.
20901: Runtime error in object [specified]: ZERO_DOWNTIME_UPGRADE - [specified action] not possible. Old version CPs do still have open connections.
20902: Runtime error in object [specified]: ZERO_DOWNTIME_UPGRADE - [specified action] not possible. There are still entries in MQWP.
20903: Runtime error in object [specified]: ZERO_DOWNTIME_UPGRADE - [specified action] not possible. There are still entries in MQJWP.
29177: UCUDB: ZERO_DOWNTIME_UPGRADE - Caching of table structure is not in use anymore.
29178: UCUDB: ZERO_DOWNTIME_UPGRADE - Caching of table structure is on.
38276: ZERO_DOWNTIME_UPGRADE = 'Y' is only allowed, if a system is running.

Centralized Agent Upgrade (CAU)

Use the MODIFY_SYSTEM script function to execute actions for processing a Centralized Agent Upgrade (CAU).

Important!

You must conduct the import of upgrade packages for the CAU in system client 0.
The CAU can be executed from any client of your system if the agents you want to upgrade and the user(s) have the corresponding authorizations.
The user executing these scripts needs the Upgrade Agents (CAU) privilege.
For more information, see CAU - Upgrade Process.

Syntax

MODIFY_SYSTEM (Action, Subfunction, Agent(s), Version [,FORCED] [,Custom text])

Parameters

Parameter	Description	Format / Allowed Values
Action	Centralized Agent Upgrade (CAU) action.	AGENT_UPGRADE
Subfunction	Specific task to execute within the upgrade.	DEPLOY: Deploys an agent specified with the Version parameter. SKIP_WAITING: Skips a registered deployment for currently inactive or busy agents.
Agent(s)	Refers to a data sequence or a filter on an agent name to which the Action should apply.	Script literal or script variable
Version	Full semantic version to which the agent should be upgraded, or Storage object name, or the literal LATEST. Important! Use this parameter only together with the DEPLOY value of the Subfunction parameter.	Script literal or script variable Example: "12.0.0+BUILD.2112" or LATEST for the latest available version of the agent represented by an APM package in current system's client 0.
FORCED	(Optional) Fixed value: FORCED. Note: If this parameter is set, the check if an agent has an active ServiceManager connection is skipped (use with DEPLOY only).	Keyword
Custom text	(Optional) Free text. Maximum length: 20. Allowed characters: The same ones as in the General page of Workflows. For more information, see Configuring the General Properties of a Task in a Workflow. Note: If this parameter is set, the text is used as a name prefix for the top statistics record (instead of CAU usage with DEPLOY only).	Free text

Examples

Example script that deploys new agents:

:SET &HND# = PREP_PROCESS_AGENTGROUP("AGENTGROUP_WINDOWS")

:SET &RUNID# = MODIFY_SYSTEM(AGENT_UPGRADE, DEPLOY, &HND#, "LATEST", FORCED, "MYHOTFIXUPGRADE")

!OR

!:SET &RUNID# = MODIFY_SYSTEM (AGENT_UPGRADE, DEPLOY, &HND#, "12.0.0+BUILD.2112", FORCED, "MYHOTFIXUPGRADE")

:IF &RUNID# = 0

:SET &MSGNR# = SYS_LAST_ERR_NR()

:SET &MSGINSERT# = SYS_LAST_ERR_INS()

:SET &MSG# = GET_MSG_TXT(&MSGNR#, &MSGINSERT#)

:SEND_MSG &$USER#, &$DEPARTMENT#, &MSG#

:ENDIF

Example script that defines to skip upgrading waiting agents:

:SET &SKIPCOUNT# = MODIFY_SYSTEM(AGENT_UPGRADE, SKIP_WAITING, "AGENTNAMEORFILTER")

:SET &MSGNR# = SYS_LAST_ERR_NR()

:IF &MSGNR# > 0

:SET &MSGINSERT# = SYS_LAST_ERR_INS()

:SET &MSG# = GET_MSG_TXT(&MSGNR#, &MSGINSERT#)

:SEND_MSG &$USER#, &$DEPARTMENT#, &MSG#

:ENDIF

Return Codes

For AGENT_UPGRADE action DEPLOY:

0: Upgrade process could not be started. Check for reason(s) by using SYS_LAST_ERR_NR() and SYS_LASR_ERR_INS().
>0: RunID for the whole upgrade process which has a report line for each agent that was processed.

For AGENT_UPGRADE action SKIP_WAITING:

>=0: AGENT_UPGRADE - Number of successfully skipped upgrades.