MODIFY_SYSTEM
Script function: Processes ServiceManager actions, queue modifications, controls steps in a Zero Downtime Upgrade scenario and for the Centralized Agent Upgrade.
This script element can be used to handle four different types of tasks:
- Executing the actions of a ServiceManager that is connected to the AE system
- Changing the values or states of Queue objects (GO/STOP)
- Switching the processing direction during a Zero Downtime Upgrade scenario or finalizing the Zero Downtime Upgrade phase.
- Executing actions for processing a Centralized Agent Upgrade.
The actions that this script function takes, depend on the parameters that are specified. Refer to the syntax descriptions below.
Warning! You can only start server processes and agents using this script element if 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 Attributes Page.
Syntax
MODIFY_SYSTEM (Action, Queue, Value)
|
Syntax |
Description/Format |
|---|---|
|
Action |
Defines the modifications that should be made in Queue objects Allowed values:
|
|
Queue |
Name of the Queue object that should be changed. |
| Value |
Value for the setting or status that should be changed (Action). Allowed values depending on the selected action: MODE: GO or STOP |
Changing the status of Queue objects (Start/Stop) using this script element (Action: MODE) has the effect that the new status is valid until a new modification is made. Modifications to priority or 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.
Note: The number of parallel running tasks is not limited if the maximum slots of Queue objects are changed to UNLIMITED.
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
List of Possible Return Codes when modifying Queue objects:
| Return codes |
|---|
|
0 - The action defined for this script function has successfully been processed. |
Syntax
MODIFY_SYSTEM (Action, Name [,Server mode])
|
Syntax |
Description/Format |
|---|---|
|
Action |
Defines the action that should be taken for agents, server processes or the AE system. Allowed values: STARTUP = Starts an agent or a server process. |
|
Name |
Name of the agent or server process that should be started or ended, or whose mode should be changed. |
| Server mode |
Mode to which the specified WP should be changed. This parameter is only required if the mode of a WP should be changed (Action = CHANGE_MODE). Allowed values: |
The script element MODIFY_SYSTEM can also be used to start or end server processes and agents or to change the mode of a server's work processes.
The action STARTUP can only be used if a ServiceManager is available and if the agent or server process to be started has correctly been configured. Refer to the settings in the Attributes page of Agents or Server objects. For more information, see Attributes Page.
In order to terminate the AE system using SHUTDOWN, the value UC4 is required for the parameter Name. For more information, see :SHUTDOWN.
The parameter Server mode is required in order to change the mode of a Server's work process (Action: CHANGE_MODE). The parameter Server mode must not be used in combination with the actions STARTUP, TERMINATE, DISCONNECT and SHUTDOWN.
Example
Shutting down the agent WIN01:
List of Possible Return Codes when modifying the ServiceManager:
| Return codes |
|---|
|
11677 - The ServiceManager call could not be processed: No CP is started. |
Syntax
MODIFY_SYSTEM (Action, Value)
|
Syntax |
Description/Format |
|---|---|
|
Action |
Allowed value ZERO_DOWNTIME_UPGRADE = Zero Downtime Upgrade control. |
|
Value |
This parameter will be applied for routing messages to be processed by new or old WPs / CPs . Allowed values: BEGIN = sets UC_SYSTEM_SETTINGS / ZERO_DOWNTIME_UPGRADE to "Y" END = sets UC_SYSTEM_SETTINGS / ZERO_DOWNTIME_UPGRADE to "N" - only possible before taking any steps in the upgrade process UPGRADE = Upgrade mode. ROLLBACK = Rollback mode. FINALIZE = Finalizes the Zero Downtime Upgrade phase by setting the currently active message queue set as base and resetting UC_SYSTEM_SETTINGS / ZERO_DOWNTIME_UPGRADE to N |
Warning! Usage for carrying out an upgrade with zero downtime only, when UC_SYSTEM_SETTINGS / ZERO_DOWNTIME_UPGRADE = Y
Warning! The database upgrade has to be processed successfully beforehand. At least one CP and one WP of the new version have to be up and running.
For more information on Zero Downtime Upgrades, see Upgrade Process.
Example
This example shows the settings necessary for starting the rollback:
:SET &RET# = MODIFY_SYSTEM("ZERO_DOWNTIME_UPGRADE", "ROLLBACK")
List of Possible Return Codes for the Zero Downtime Upgrade:
| Return codes |
|---|
|
0 - The action defined for this script function has successfully been processed. |
Attention administrators: You have to conduct the import of upgrade packages for the CAU in system client 0000.
Attention administrators: 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 for it.
Syntax
MODIFY_SYSTEM (Action, Sub function, Agent(s), Version[,FORCED][,Custom text])
|
Syntax |
Description/Format |
|---|---|
|
Action |
Allowed value: AGENT_UPGRADE = Centralized Agent Upgrade. |
|
Sub function |
Allowed values: DEPLOY = Deploy an agent specified by the parameter Version. SKIP_WAITING = Skip a registered deployment for currently inactive or busy agents. |
| Agent(s) |
Reference to a data sequence or filter on agent name the Action should be applied to. Format: script literal or script variable |
| Version |
Full semantic version that agent should be upgraded to or Storage object name or literal 'LATEST'. Example: "12.0.0+BUILD.2112"
Format: script literal or script variable Warning! Use this parameter only together with the value DEPLOY of the parameter Sub function. |
| FORCED |
Fixed value: FORCED (optional) Note: If this parameter is set, the check if an agent has an active ServiceManager connection will be skipped (use with DEPLOY only). |
| Custom text |
Free text (optional) Max length = 20 Allowed characters: Same as in the General page of Workflows. For more information, see General Tab. Note: If this parameter is set, the text will be used as name prefix for the top statistics record instead of CAU (usage with DEPLOY only). |
Note: For more information, see CAU - Upgrade Procedure
Attention administrators: The user executing these scripts needs the privilege Execute System Upgrades.
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
List of Possible Return Codes for the Centralized Agent Upgrade:
Warning! In case of return code 0, use SYS_LAST_ERR_NR() and SYS_LAST_ERR_INS() to check for possible errors.
| Return codes |
|---|
|
Note: Possible 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_LAST_ERR_INS(). |
|
Note: Return value for the AGENT_UPGRADE action SKIP_WAITING >= 0 - AGENT_UPGRADE - Amount of successfully skipped upgrades. |
See also: