MODIFY_SYSTEM

ScriptEigener Objekttyp in der Automation Engine function: Processes ServiceManager actions, queue modifications, controls steps in a Zero Downtime UpgradeEine besondere Funktion in der Automation Engine, die System-Upgrades zwischen Hauptversionen, Minor Releases oder Service Packs möglich macht, ohne dass das AE System während des Upgrades heruntergefahren werden muss. scenario and for the Centralized Agent UpgradeDas Cenralized Agent Upgrade erlaubt das zentrale Upgrade von allen installierten und durch das CAU unterstützten Agenten auf neue Versionen mithilfe des Automic Web Interface (AWI)..

General Information

This script element can be used to handle four different types of tasks:

  1. Executing the actions of a ServiceManager that is connected to the AE system
  2. Changing the values or states of QueueObjekttyp in der Automation Engine. Legt die maximale Anzahl parallel laufender Aufgaben, deren Prioritäten und somit die Reihenfolge von auszuführenden Objekten fest. objects (GO/STOP)
  3. Switching the processing direction during a Zero Downtime Upgrade scenario or finalizing the Zero Downtime Upgrade phase.
  4. Executing actions for processing a Centralized Agent"Programm, das die Ausführung von Verarbeitungen auf Zielsystemen wie z.B. Rechner oder Geschäftslösungen ermöglicht. Auch ein eigener Objekttyp in der Automation Engine. [Früher ""Executor"" genannt.] Siehe auch ""Host""." 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 descriptions of the settings for Agent objects and Server objects.

For a list of possible return codes see the bottom of each section.

Queue

[ 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.
Format: script literal or script variable 

Allowed values: "MODE", "MAX_SLOTS" or "PRIORITY"

"MODE" = Queue status, start or stop of queue task execution.
"MAX_SLOTS" = Max. number of tasks that can run at the same time (max. slots).
"PRIORITY" = Task priority.

Queue

Name of the Queue object that should be changed.
Format: script literal or script variable 
Value

Value for the setting or status that should be changed (Action).
Format: script literal or script variable

Allowed values depending on the selected action:

"MODE": "GO" or "STOP"
"MAX_SLOTS": Number between "0" and "99999" or "UNLIMITED".
"PRIORITY": Number between "0" and "255".

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.

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

[ 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.
Format: script literal or script variable 

Allowed values:

"STARTUP" = Starts an agent or a server process.
"TERMINATE" = Ends an agent or a server process.
"SHUTDOWN" = Shuts down the complete AE system.
"CHANGE_MODE" = Changes the mode of a Server's work process (WP).
"DISCONNECT" = Closes the agent connection and re-establishes it.

Name

Name of the agent or server process that should be started/ended or whose mode should be changed.
Format: script literal or script variable
Server mode

Mode to which the specified WP should be changed.
Format: script literal or script variable

This parameter is only required if the mode of a WP should be changed (Action = CHANGE_MODE).

Allowed values:
"D": Dialog process
"W": Work process

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 tab of Agent objects or Server 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.
"11678" - Server or agent has not been 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

[ 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.
The message queue set belonging to the new CPs and WPs will be set active. The PWP role switches to a new WP. Messages will be routed to the new processing, while the old processing will be phased out.

"ROLLBACK" = Rollback mode.
The message queue set belonging to the old CPs and WPs will be set active. Messages will be routed back to the old processing, while the new processing will be phased out.

"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.
"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 taks 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]. 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

[ 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"
or
'LATEST' for the latest available version of the agent represented by an APM package in current system's client 0000.

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 Alias 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().
">0" - RunID"Kurzform für ""laufende Nummer"". Hierbei handelt es sich genauer um eine Zahl, welche die Durchführung einer Aufgabe eindeutig kennzeichnet. Die RunID kann zwischen 7 und 10 Stellen aufweisen. Sie wird von der Komponente Automation Engine vergeben." for the whole upgrade process, which has a report line for each agent that was processed.

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