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

  • MODIFY_SYSTEM
    Processes Service Manager actions or queue modifications
  • Action
    Defines the modifications to be made in Queue objects
    Format: script literal or script variable
    Allowed values:
    • 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.
  • 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:
    • 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

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

  • MODIFY_SYSTEM
    Processes Service Manager actions or queue modifications

  • Action
    Defines the action to 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
      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 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
  • Name
    Name of the agent or server process that should start or end, or whose mode you want to change
    Format: 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.
    Format: script literal or script variable
    Allowed values:
    • D
      Dialog process
    • W
      Work process

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

  • MODIFY_SYSTEM
    Switches the processing direction during a ZDU
  • Action
    Allowed value:
    • ZERO_DOWNTIME_UPGRADE
      Zero Downtime Upgrade control
  • Value
    This parameter applies for routing messages processed by new or old WPs/CPs.
    Allowed values:
    • 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

  • MODIFY_ACTION
    Processes actions for a CAU
  • Action
    Allowed value:
    • AGENT_UPGRADE
      Centralized Agent Upgrade (CAU)
  • Subfunction
    Allowed values:

    • 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
    Format: script literal or script variable
  • Version
    Full semantic version to which the agent should be upgraded, or Storage object name, or the 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 0.
    Format: script literal or script variable
    Important! Use this parameter only together with the DEPLOY value of the Subfunction parameter.
  • 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).
  • Custom text
    (Optional) Free text
    Maximum length: 20
    Allowed characters: The same ones as in the General page of Workflows. For more information, see General Tab.
    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).

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


See also:

Related Script Elements

:DISCONNECT

:SHUTDOWN

:TERMINATE