Automation Engine Script Guide > Ordered by Function > System Conditions and Settings > MODIFY_SYSTEM

MODIFY_SYSTEM

Script functionPre-defined run book template in the Automation Engine. One single step only, e.g. Start Windows Service, Copy file,…: Processes ServiceManagerA program that facilitates the starts and stops of Automation Engine components. actions, queueA particular Automation Engine (AE) object type. In AE, a queue determines the maximum number of concurrent tasks, their priorities and the order in which tasks should be executed. In ARA, queues are containers for workflow executions that should be executed at a certain time one after another. modifications and controls steps in a Zero Downtime UpgradeA special function in the Automation Engine, which is meant to enable system upgrades between major versions, minor versions or service packs without the necessity of closing down the AE system at any point during the upgrade. scenario.

General information

This scriptA particular Automation Engine object type. element can be used to handle three 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 Queue objects (GO/STOP)
  3. Switching the processing direction during a Zero Downtime Upgrade scenario or finalizing the Zero Downtime Upgrade phase.

The actions that this script function takes depends on the parameters that are specified. Also 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 this topic.


Queue

[ Queue ] [ ServiceManager ][ Zero Downtime 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 statusThis represents the condition of a task (such as active, blocked, generating)., start or stop of queue taskAn executable object that is running. Tasks are also referred to as activities. execution.
"MAX_SLOTS" = Max. number of tasks that can run at the same time (max. slots).
"PRIORITY" = Task priority.

Queue

Name of the Queue objectAutomation Engine controlled activities and processes are structured in the form of objects. See also: Task 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 actionActions are predefined building blocks for recurring activities. They are commonly used for managing third party systems or in deployment scenarios.:
"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 userIn the Automation Engine, a user is an instance of a User object, and generally the user is a specific person who works with Automic products. The User object is assigned a user ID and then a set of access rights to various parts of the Automation Engine system and product suite. These access rights come in the form of Automation Engine authorizations and privileges, Decision user roles and EventBase rights and ARA web application object rights. You can manage all these centrally in the ECC user management functions. See also, Unified user management. 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

 


ServiceManager

[ Queue ] [ ServiceManager ][ Zero Downtime 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", "TERMINATE", "CHANGE_MODE", "DISCONNECT" or "SHUTDOWN"
"STARTUP" = Starts an agentA program that enables the de-centralized execution of processes (such as deployments) on target systems (computers or business solutions) or a service that provides connectivity to a target system (such as for databases or middleware). An agent is also an object type in the Automation Engine. [Formerly called "Executor."] See also: host or a server processThe core of the component Automation Engine. Different types are available: communication, work and dialog processes, as well as nonstop processes..
"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 processA part of the component Automation Engine. It is responsible for an Automation Engine system's processes (see also 'Primary 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") 

 


Zero Downtime Upgrade

[ Queue ] [ ServiceManager ][ Zero Downtime Upgrade]

Syntax

MODIFY_SYSTEM(Action, Value)

Syntax

Description/Format

Action

Allowed value "ZERO_DOWNTIME_UPGRADE" = Zero Downtime Upgrade control.

The following Value parameter will be applied for routing messages to be processed by new or old WPs / CPs .

Value

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 databaseA database is an organized collection of data including relevant data structures. 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 "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:

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 clientA closed environment within an Automation Engine system where you can create and run objects. A client name consists of a 4-digit number that must be indicated when a user logs on to the Automation Engine system. Users and their rights are also defined in clients. A particular Automation Engine object type..
"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.
"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 hostComputer, target system. 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.
"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.

 


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.

 


Automic Documentation - Tutorials - Automic Blog - Resources - Training & Services - Automic YouTube Channel - Download Center - Support

Copyright © 2016 Automic Software GmbH