Script function: Processes ServiceManager actions, queue modifications, controls steps in a Zero Downtime Upgrade scenario and for the Centralized Agent Upgrade.
General Information
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.
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. Also refer to the settings in the Attributes page of Agents or Server objects (Attributes Pages of Executable Objects).
For a list of possible return codes, see the bottom of each section.
[ Queue ] [ ServiceManager ][ Zero Downtime Upgrade][Centralized Agent Upgrade]
Syntax
MODIFY_SYSTEM (Action, Queue, Value)
|
Syntax |
Description/Format |
|---|---|
|
Action |
Defines the modifications that should be made in Queue objects. Allowed values: "MODE", "MAX_SLOTS" or "PRIORITY" "MODE" = Queue status, start or stop of queue task execution. |
|
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" |
Comments
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.
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. |
[ Queue ] [ ServiceManager ][ Zero Downtime Upgrade][Centralized Agent Upgrade]
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/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: |
Comments
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. Also refer to the settings in the Attributes page of Agents or Server objects (Attributes Pages of Executable Objects).
In order to terminate the AE system using "SHUTDOWN", the value "UC4" is required for the parameter Name (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":
:SET &ACT# = MODIFY_SYSTEM("TERMINATE", "WIN01")
List of Possible Return Codes when modifying the ServiceManager:
| Return codes |
|---|
|
"11677" - The ServiceManager call could not be processed: No CP is started. |
[ Queue ] [ ServiceManager ][ Zero Downtime Upgrade][Centralized Agent Upgrade]
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" |
Comments
Usage for carrying out an upgrade with zero downtime only, when UC_SYSTEM_SETTINGS / ZERO_DOWNTIME_UPGRADE = Y
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 details please refer to the document Zero Downtime Upgrade - 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. |
[ Queue ] [ ServiceManager ][ Zero Downtime Upgrade][ Centralized Agent Upgrade]
You have to conduct the import of upgrade packages for the CAU in system client 0000.
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 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 Use this parameter only together with the value DEPLOY of the parameter Sub function. |
| FORCED |
Fixed value: "FORCED" (optional) 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 General Tab names of workflows. 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). |
Comments
For a detailed guide on how to conduct a CAU, refer to the document Centralized Agent Upgrade Process
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:
In case of return code "0", use SYS_LAST_ERR_NR() and SYS_LAST_ERR_INS() to check for possible errors.
| Return codes |
|---|
|
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(). |
|
Return value for for the AGENT_UPGRADE action "SKIP_WAITING" >= 0 - AGENT_UPGRADE - Amount of successfully skipped upgrades. |
See also:
| Script Element | Description |
|---|---|
| :SHUTDOWN | Ends an AE system. |
| SYS_HOST_ALIVE | Checks if a particular host is active. |
| SYS_SERVER_ALIVE | Checks if a certain server process is active. |
| TOGGLE_SYSTEM_STATUS | Stops or starts the automatic processing of a complete client. |
Script Elements - Read or Modify Objects
Sample Collection
Notification with Variable Message Text
About Scripts
Script Elements - Alphabetical Listing
Script Elements - Ordered by Function