Service section

The Service section within the application profile defines a group of configuration settings for service attributes. Multiple service elements can be defined in this section with different configuration settings for each service. Defining multiple services allows you to use more than one service within a single application. You can add or update (or remove) a service to an existing application dynamically using the cluster management console.

Service

Description: Configures service attributes.

cleanupTimeout

Maximum time, in seconds, to allow a service instance to cleanup if an application is disabled or unregistered, or a middleware component becomes unavailable.

Cleanup allows the running service method to gracefully finish executing. If the service method and cleanup does not complete within the set time, then IBM® Spectrum Symphony will terminate the SIM.

Where use: Service

Required or optional: Optional

Valid values: 1 to 4294967295

Default: 60

debugSetting

Description: Helps you to use a debugger to step through the service code and find any errors in the service logic or in the environment.

For a customized debugSetting, you can configure the specific events that you want IBM Spectrum Symphony to detect by specifying the customizedDebugAction for each of these events.

Where use: Service

Required or optional: Optional

Valid values: none, customized, or full:

none: never generates debug logs
customized: generates debug logs upon detection of specific customizable events
full: always generate debug logs

default

Description: Identifies a service as the default service, which means that the default service is immediately started when the service instance manager starts.

Where use: Service

Required or optional: Optional when one service section is defined. Required when multiple service sections are defined.

Valid values: true or false

Default value: true if only one service is defined in the application profile. If only one service is defined, that service is identified as the default and is started when the service instance manager starts.

When multiple services are defined, at least one of the services default value should be set to true. Other services' default value is optional.

delaySlotRelease

Description: Specifies the amount of time that an unassigned service will remain idle with the application before releasing its corresponding slot to EGO (and terminating the service). An unassigned service is defined as a service not assigned to any session. If new workload arrives before the configured time elapses, these unassigned services can be used to handle the new workload. Once an unassigned service becomes assigned to a session again, its idle timer is reset.

Note that delaySlotRelease is not supported for MapReduce workload.

Where use: Service

Required or optional: Optional

Valid values: 1 to 2147483647

Default: Unspecified (use application-level setting)

deploymentRetryCount

Description: Specifies the number of times the soamdeploy command retries to connect to the repository server and download the service package from the repository server. After the service experiences the specified number of retries, the service is aborted.

Where use: Service

Required or optional: Optional

Valid values: 0 to 2147483647

Default value: 3

deploymentTimeout

Description: Maximum time, in seconds, to wait before the soamdeploy command checks the connection with the repository server.

Where use: Service

Required or optional: Optional

Valid values: 0 to 2147483647

Default value: 300

description

Description: String that describes the service.

Where use: Service

Required or optional: Optional

Valid values: 1 to 256 alphanumeric characters, including all printable characters

dockerContainerDefinitionName

Description: Associates a service with a ContainerDefinition by name. This parameter only takes effect when enableDockerForServiceInstance is set to true. The maximum length is 128 characters.

Where used: Service

Required or optional: Optional

Valid values: 0 to 9, A to Z, a to z, underscore (_), or hyphen (-)

maxOtherInstances

Description: Applies only when multiple services are used in a single application. Defines the maximum number of other service instances that a single service instance manager can run concurrently, in addition to the current service, on the same resource where the current service running. This preserves the service instance process to remain alive on the resource, and saves the service instance startup time the next time the resource is allocated to another workload and needs this service instance to run tasks.

When this parameter is set to 0, no other service instances started by the service instance manager can run at the same time on the same resource allocated when this service instance manager starts this service.

When this parameter is set to a number larger than 0, the service instance manager can keep maxOtherInstances service instances running along with this service concurrently. Setting a value larger than 0 saves service instance loading time, because service instances are not shut down and restarted.

When a service instance manager needs to shut down a service to satisfy maxOtherInstances, it first tries to gracefully shut down the service instance. If the service instance does not exit when the DestroyService timeout (Service > Control > Method > Timeout duration attribute) expires, the process ends.

Note: A service instance manager only manages multiple services that have the same serviceToSlotRatio. As soon as a service instance manager needs to manage a service with a different serviceToSlotRatio, it will terminate all of the service instances it is managing and start a new service instance with the new ratio. The other service instances will not be restarted with the new serviceToSlotRatio unless they are required to run workload.

Where use: Service

Required or optional: Optional

Valid values: 0 to 2147483647

Default value: 0, indicating that only one service instance can run at a time

Related attributes:

standbyServiceScope (in Consumer section): Enables the global standby service feature, which allows one or more applications to keep service instances running in standby mode on released slots and to reattach to these service instances when required.

Example: If you have three services with different values for maxOtherInstances:

Name	maxOtherInstances	Default
S1	1	true
S2	1	false
S3	0	false

When the service instance manager starts, it starts service S1 by default. The service instance manager has one child process (S1). When service S2 is started, the service instance manager has 2 child processes (S1 and S2). If service S3 is started, the service instance manager has only one child process, which is S3 (S1 and S2 are shut down by the service instance manager).

When service S1 is started again, the service instance manager has only one child process, which is S1 (S3 is shutdown by the service instance manager because its maxOtherInstances value is 0).

name

Description: Name of the service to run for this application. The service name must be unique within the application.

A client application can use the appropriate API to override the service that is used to execute workload. Refer to the API Reference for more details. The service name that the client specifies must be configured in the application profile.

Where use: Service

Required or optional: Required

Valid values: 1 to 256 alphanumeric characters, including all printable characters. Ensure that angle brackets (< >), single quotation marks ('), double quotation marks ("), parentheses (( )), forward slashes (/), and backward slashes (\) are not used.

Related attributes:

ServiceName: Name of service that is used to execute the workload for the sessions in this session type.

packageName

Description: Name assigned to the service package during deployment. The value you specify here must match the value specified during deployment.

Where use: Service

Required or optional: Required if you use the SOAM_DEPLOY_DIR variable in the Service section; optional if you do not use that variable in the Service section.

Valid values: 0 to 9, A to Z, a to z, underscore (_), hyphen (-) or period (.). The name cannot contain only periods.

Default value: None

resourceUsageInStandbyMode

Description: Defines how EGO behaves and how it releases operating system resources when it terminates a standby service. The behavior is different for global (cluster scope) standby services (as defined by standbyServiceScope set to Cluster) and for consumer scope standby services (as defined by standbyServiceScope set to Consumer).

For global (cluster scope) standby services, EGO will terminate a standby service to release operating system resources, as necessary, according to the resourceUsageInStandbyMode defined. If resourceUsageInStandbyMode is not defined for global standby services, EGO will terminate a cluster scope standby service to release operating system resource according to the slot definition when services start.

If resourceUsageInStandbyMode is defined for consumer scope standby service, EGO will terminate a standby service to release operating system resources, as necessary, and will also carry out the behavior for cluster scope standby services. If resourceUsageInStandbyMode is not defined for standby services, EGO will not terminate any consumer scope standby services.

Where use: Service

Required or optional: Optional

Valid values: 0 to 256 alphanumeric characters, including all printable characters

Default value: "" (empty) to indicate no definition

standbyServiceTag

Description: When the global standby service feature is enabled, specifies a cluster-wide tag that identifies the global standby service, allowing one or more applications to share this service. The global service tag must be unique within the application and must be specified only once for each Service section.

Assign the same tag to services that use the same binaries, start command, and startup environment variables for sharing between multiple applications. If standbyServiceTag is not set or is set as an empty string, a service is not placed in the global standby service mode even if standbyServiceScope in the Consumer section of the application profile is set to Cluster.

Note that standbyServiceTag is not supported for MapReduce workload because global standby services are not supported within MapReduce.

Where use: Service

Required or optional: Optional

Valid values: 1 to 30 alphanumeric characters, including all printable characters

Related attributes:

standbyServiceScope (in Consumer section): Enables the global standby service feature, which allows one or more applications to keep service instances running in standby mode on released slots and to reattach to these service instances when required.

Service > osTypes > osType

fileNamePattern

Description: Used for log retrieval through the cluster management console. File naming convention for service log files written to the logDirectory. Specify how your files are named. When retrieving logs for a specific task, the system looks for log files that partially match the file name pattern. If you are going to name files with variables such as the ID or tag for sessions or tasks, specify the appropriate special variable; refer to the valid values for special variables in this section.

Configure logDirectory, fileNamePattern, and subDirectoryPattern for each operating system type defined in your service section.

Note: Log retrieval is only available in IBM Spectrum Symphony on the grid. Log retrieval is not available in IBM Spectrum Symphony Developer Edition.

Where use: Service > osTypes > osType

Required or optional: Optional

Valid values:

Any alphanumeric string
Any of these special variables: %taskId%, %sessionId%, %sessionTag%, or %taskTag%

Default value: "" (empty) to indicate that the system should retrieve all files under logDirectory/subDirectory

Example: If log files have, for example, the service name, then session ID, and task ID, and your log file name is sampleService_123_1.log, you can specify sampleService_%sessionId%_%taskId%.log. The system matches files containing the session ID and task ID.

Related attributes:

logDirectory: Path to the directory in which logs are written by services for this application.
subDirectoryPattern: Convention for naming subdirectories in the logDirectory.

logDirectory

Description: Used for log retrieval through the cluster management console. Path to the directory in which logs are written by services for this application. The path can be any desired path and must be the same on all compute hosts.

Configure logDirectory, fileNamePattern, and subDirectoryPattern for each operating system type defined in your service section.

Note: Log retrieval is only available in IBM Spectrum Symphony on the grid. Log retrieval is not available in IBM Spectrum Symphony Developer Edition.

Where use: Service > osTypes > osType

Required or optional: Required

Default value:

Linux®:
- $SOAM_HOME/work (IBM Spectrum Symphony workload)
- $SOAM_HOME/mapreduce/logs/tasklogs (MapReduce workload)
Windows: %SOAM_HOME%\work

Related attributes:

fileNamePattern: File naming convention for service log files written to the logDirectory.
subDirectoryPattern: Convention for naming subdirectories in the logDirectory.

name

Description: Operating system environment in which to run the service. IBM Spectrum Symphony uses this information to determine where the executable for the service is located and set up the environment variables for the service instance.

Note: While specifying PATH, ensure that you use the proper path delimiter (colon or semicolon) according to the osType.

Where use: Service > osTypes > osType

Required or optional: Required

Valid values: all, LINUX86, NTX86, X86_64, NTX64, LINUXPPC64, or a user-defined operating-system type:

all: this configuration is applied if the osType for the allocated resource is not configured in the application profile.
LINUX86: a 32-bit Linux-based environment, such as Red Hat Linux
NTX86: a 32-bit Windows-based environment, such as Windows 2000, Windows NT, and Windows XP
X86_64: a 64-bit Linux-based environment
NTX64: a 64-bit Windows-based environment
LINUXPPC64: a Linux x86-64 based environment, such as IBM POWER® systems
User-defined operating-system types, defined in the ego.shared file

preExecCmd

Description: When using a deployment tool other than IBM Spectrum Symphony soamdeploy, the command specified here will run on the compute host and can be used to copy the service program to that host.

Multiple commands can be run by calling a script or batch file containing the commands. The path to this command must be defined by an environment variable.

preExecCmd is called only when packageName is not configured in the service section.

Where use: Service > osTypes > osType

Required or optional: Optional

Valid values: Any location accessible on your network or local disk.

Default value: "" (empty) to indicate that no pre-execution command will be executed

startCmd

Description: Path to the program executable for the service. If you deploy a service package using IBM Spectrum Symphony deployment, the directory where your service package is extracted can be referred to as ${SOAM_DEPLOY_DIR}. If you need to reference a file in your service package, use the ${SOAM_DEPLOY_DIR} variable.

For example:

On Windows, if in your service package you have the directory structure \myservice\myservice.exe, indicate ${SOAM_DEPLOY_DIR}\myservice\myservice.exe in startCmd.
On Linux, if in your service package you have the directory structure /myservice/myservice, indicate ${SOAM_DEPLOY_DIR}/myservice/myservice in startCmd.
On Linux, if you are using the default MapReduce service, indicate ${PMR_HOME}/${PMR_VERSION}/${EGO_MACHINE_TYPE}/etc/RunMapReduceService.sh in startCmd.

Note: To run a Windows .bat script, specify a special syntax to run the batch file in command shell. For example:

<osType name=NTX86" startCmd="cmd /c cmd /c install.bat"/>

Where use: Service > osTypes > osType

Required or optional: Required

Valid values: Any location accessible on your network or local disk.

subDirectoryPattern

Description: Used for log retrieval through the cluster management console. Convention for naming subdirectories in the logDirectory. If you want to name subdirectories according to variables such as the ID or tag for sessions or tasks, specify the appropriate special variable; refer to the valid values for special variables in this section. When retrieving logs, the system looks for log files in subdirectories that partially match the subdirectory pattern.

Configure logDirectory, fileNamePattern, and subDirectoryPattern for each operating system type defined in your service section.

Note: Log retrieval is only available in IBM Spectrum Symphony on the grid. Log retrieval is not available in IBM Spectrum Symphony Developer Edition.

Where use: Service > osTypes > osType

Required or optional: Optional

Valid values:

Any alphanumeric string
Any of these special variables: %applicationName%, %sessionId%, %taskId%, %sessionTag%, or %taskTag%

Default value: "" (empty) to indicate that no subdirectories exist

Example: If you want to name subdirectories according to session ID, specify, without any back slashes: specify %sessionId%. The system looks for logs in subdirectories named according to the session ID.

Related attributes:

logDirectory: Path to the directory in which logs are written by services for this application.
fileNamePattern: File naming convention for service log files written to the logDirectory.

workDir

Description: Working directory of the service instance.

Where use: Service > osTypes > osType

Required or optional: Optional

Valid values: Any location accessible on your network or local disk.

Default value: The default working directory for the service is ${SOAM_HOME}/work. The default working directory for the MapReduce service is ${SOAM_HOME}/mapreduce/work/${SUB_WORK_DIR}.

Service > osTypes > osType > env

Description: Configures environment variables for running service instances.

name

Description: Name of an environment variable to set in the run time environment of the service. Provide a name in place of the @ENVNAME@ value in

<env
name"@ENVNAME@"

>. If you have multiple names, use one env statement is for each environment variable.

You can define environment variables so that they are substituted in the startCmd, preExecCmd, and workDir attributes.

You can refer to defined environment variables in other environment variables. For example:

<env name="ENVAR1">${SOAM_HOME}/work</env>
<env name="ENVAR2">${ENVAR1}/${VERSION_NUM }</env>

IBM Spectrum Symphony also substitutes the following environment variables with system values:

${PATH}: specifies the path to the relevant executable. The specified path is appended in front of the system Path at runtime. For Windows, specifies the path to any dependent library, including the IBM Spectrum Symphony libraries.
${LD_LIBRARY_PATH}: Linux only. Specifies the path to the library where the GCC-specific IBM Spectrum Symphony files are located. The specified path is prepended in front of the system LD_LIBRARY_PATH at runtime
${SOAM_HOME}: directory where IBM Spectrum Symphony is installed. Replaced with the value of the operating system environment variable SOAM_HOME set on the host.
${PMR_HOME}: directory where the MapReduce framework is located within the IBM Spectrum Symphony installation. Replaced with the value of the operating system environment variable PMR_HOME set on the host.
${VERSION_NUM}: IBM Spectrum Symphony version on which the service is running.
${PMR_VERSION}: IBM Spectrum Symphony version on which the service is running.
${EGO_MACHINE_TYPE}: Specifies the host type installation. For example, win32-vc7 specifies a Windows machine. The variable is replaced with the value of the operating system environment variable EGO_MACHINE_TYPE set on the host.
${SOAM_DEPLOY_DIR}: internal system directory in which the service package is deployed.
${SOAM_SERVICE_EVENT_REPLAY_LOG}: service is driven by the events logged in the SERL file that this variable references. If this environment variable is not defined, service is driven by the SIM (as through IBM Spectrum Symphony).
CAUTION:
EGO_MACHINE_TYPE, SOAM_DEPLOY_DIR, and SOAM_SERVICE_EVENT_REPLAY_LOG environment variables are reserved by IBM Spectrum Symphony. Modifying these environment variables may result in undesirable behavior of your application.

You can also use the following environment variables for the

<env
name"@ENVNAME@">

section:

PREALLOCATE_FIRST_SORT_MB: for MapReduce workload using dual memory buffers, this variable specifies the buffer size (in MB) for the first map sort buffer which is to be pre-allocated and is recommended when preStartApplication is enabled.
Dual buffers for map tasks are used to temporarily save intermediate data for map tasks. When you specify a value for PREALLOCATE_FIRST_SORT_MB, the memory buffer of the specified size is pre-allocated for the first map sort during SI startup. If you do not specify a value, the memory buffer is created only when the job is executed. Valid values for the buffer size are between 1 and 2047.
SYMPHONY_R_LOG_LEVEL: applicable to the open source R-integration for IBM Spectrum Symphony. This environment variable specifies the level of details for R log files. Valid values are DIABLE, ERROR, WARN, INFO (default), DEBUG, or ALL.

Where use: Service > osTypes > osType > env

Required or optional: Required

Valid values: 1 to 256 alphanumeric characters, including all printable characters

Service > osTypes > osType > resourceUsage

taskLimit

Description: Specifies the maximum number of service instance threads in a multiple task service (MTS). If the taskLimit is specified as n, no more than n tasks are submitted to the MTS. If more tasks are scheduled to the SIM, a new MTS service instance is started for the tasks that exceed n. The default value is 0, which indicates that the service does not have a task limit.

Where use: Service > osTypes > osType > resourceUsage

Required or optional: Optional

Valid values: 0 to 2147483647

Default value: 0 (which means no limit)

Related attributes:

physicalMemoryLimit: Specifies the physical memory limit, in MB, for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
virtualMemoryLimit: Specifies the virtual memory limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
physicalMemoryAutoScale: Enables or disables auto scaling of physical memory limits for a single- or multi-thread service instance (SI) group.
virtualMemoryAutoScale: Enables or disables auto scaling of virtual memory limits for a single- or multi-thread service instance (SI) group.
cpuLimit: Specifies the CPU usage limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
cpuAutoScale: Enables or disables auto scaling of CPU limits for a single- or multi-thread service (SI) group.

Service > osTypes > osType > resourceUsage > memory

physicalMemoryLimit

Description: Specifies the physical memory limit, in MB, for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes. The physicalMemoryLimit parameter is configured in conjunction with virtualMemoryLimit, and represents the maximum amount of memory usage (physical memory and swap memory) allowed for the SI group.

You can set the physicalMemoryLimit, virtualMemoryLimit, or both. However, note that on Linux, during run time, IBM Spectrum Symphony adjusts these memory limits as follows:

If you set a physicalMemoryLimit value, but not a virtualMemoryLimit value, IBM Spectrum Symphony automatically sets the virtualMemoryLimit value to the maximum usage.
If you set a virtualMemoryLimit value, but not a physicalMemoryLimit value, IBM Spectrum Symphony automatically sets the physicalMemoryLimit value to be the same as the virtualMemoryLimit value.
If you set a physicalMemoryLimit value that is greater than the virtualMemoryLimit value, IBM Spectrum Symphony automatically sets the virtualMemoryLimit to be the same as the physicalMemoryLimit value.

Where use: Service > osTypes > osType > resourceUsage > memory

Required or optional: Optional

Valid values: 0 to 2147483647

Default value: 0

Related attributes:

physicalMemoryAutoScale: Enables or disables auto scaling of physical memory limits for a single- or multi-thread service instance (SI) group.
virtualMemoryLimit: Specifies the virtual memory limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
virtualMemoryAutoScale: Enables or disables auto scaling of virtual memory limits for a single- or multi-thread service instance (SI) group.
cpuLimit: Specifies the CPU usage limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
cpuAutoScale: Enables or disables auto scaling of CPU limits for a single- or multi-thread service (SI) group.

virtualMemoryLimit

Description: Specifies the virtual memory limit, in MB, for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes. The virtualMemoryLimit parameter is configured in conjunction with physicalMemoryLimit, and represents the maximum amount of memory usage (physical memory and swap memory) allowed for the SI group.

You can set the physicalMemoryLimit, virtualMemoryLimit, or both. However, note that on Linux, during run time, IBM Spectrum Symphony adjusts these memory limits as follows:

If you set a physicalMemoryLimit value, but not a virtualMemoryLimit value, IBM Spectrum Symphony automatically sets the virtualMemoryLimit value to the maximum usage.
If you set a virtualMemoryLimit value, but not a physicalMemoryLimit value, IBM Spectrum Symphony automatically sets the physicalMemoryLimit value to be the same as the virtualMemoryLimit value.
If you set a physicalMemoryLimit value that is greater than the virtualMemoryLimit value, IBM Spectrum Symphony automatically sets the virtualMemoryLimit to be the same as the physicalMemoryLimit value.

Where use: Service > osTypes > osType > resourceUsage > memory

Required or optional: Optional

Valid values: 0 to 2147483647

Default value: 0

Related attributes:

virtualMemoryAutoScale: Enables or disables auto scaling of virtual memory limits for a single- or multi-thread service instance (SI) group.
physicalMemoryLimit: Specifies the physical memory limit, in MB, for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
physicalMemoryAutoScale: Enables or disables auto scaling of physical memory limits for a single- or multi-thread service instance (SI) group.
cpuLimit: Specifies the CPU usage limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
cpuAutoScale: Enables or disables auto scaling of CPU limits for a single- or multi-thread service (SI) group.

physicalMemoryAutoScale

Description: Enables or disables automatic scaling of physical memory limits a single- or multi-thread service instance (SI) group. When enabled, the physical memory limit is scaled in proportion to the number of tasks running in the MTS. When disabled, the physical memory limit does not change during the MTS' lifetime.

When auto scaling of the physical memory limit is enabled (default), ensure that the physicalMemoryLimit parameter is correctly configured to specify the maximum amount of memory usage (physical memory and swap memory) for an MTS.

Where use: Service > osTypes > osType > resourceUsage > memory

Required or optional: Optional

Valid values: true or false

Default value: true

Related attributes:

physicalMemoryLimit: Specifies the physical memory limit, in MB, for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
virtualMemoryLimit: Specifies the virtual memory limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
virtualMemoryAutoScale: Enables or disables auto scaling of virtual memory limits for a single- or multi-thread service instance (SI) group.
cpuLimit: Specifies the CPU usage limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
cpuAutoScale: Enables or disables auto scaling of CPU limits for a single- or multi-thread service (SI) group.

virtualMemoryAutoScale

Description: Enables or disables auto scaling of virtual memory limits a single- or multi-thread service instance (SI) group. When enabled, the virtual memory limit is scaled in proportion to the number of tasks running in the MTS. When disabled, the virtual memory limit does not change during the MTS' lifetime.

When auto scaling of the virtual memory limit is enabled (default), ensure that the virtualMemoryLimit parameter is correctly configured to specify the maximum amount of memory usage (physical memory and swap memory) for an MTS.

Where use: Service > osTypes > osType > resourceUsage > memory

Required or optional: Optional

Valid values: true or false

Default value: true

Related attributes:

virtualMemoryLimit: Specifies the virtual memory limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
physicalMemoryLimit: Specifies the physical memory limit, in MB, for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
physicalMemoryAutoScale: Enables or disables auto scaling of physical memory limits for a single- or multi-thread service instance (SI) group.
cpuLimit: Specifies the CPU usage limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
cpuAutoScale: Enables or disables auto scaling of CPU limits for a single- or multi-thread service (SI) group.

Service > osTypes > osType > resourceUsage > cpu

cpuLimit

Description: Specifies the CPU usage limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes. The cpuLimit value indicates the number of cores on which an IBM Spectrum Symphony service is expected to run. The default value is 0, to indicate no CPU limit for the service.

Where use: Service > osTypes > osType > resourceUsage > cpu

Required or optional: Optional

Valid values: 0 to 262144

Default value: 0

Related attributes:

cpuAutoScale: Enables or disables auto scaling of CPU limits for a single- or multi-thread service (SI) group.
physicalMemoryLimit: Specifies the physical memory limit, in MB, for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
physicalMemoryAutoScale: Enables or disables auto scaling of physical memory limits for a single- or multi-thread service instance (SI) group.
virtualMemoryLimit: Specifies the virtual memory limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
virtualMemoryAutoScale: Enables or disables auto scaling of virtual memory limits for a single- or multi-thread service instance (SI) group.

cpuAutoScale

Description: Enables or disables auto scaling of CPU limits a single- or multi-thread service instance (SI) group. When enabled, the CPU limit is scaled in proportion to the number of tasks running in the MTS. When disabled, the CPU limit does not change during the MTS' lifetime.

When auto scaling of the CPU limit is enabled (default), ensure that the cpuLimit parameter is correctly configured to specify the CPU usage limit for an MTS.

Where use: Service > osTypes > osType > resourceUsage > cpu

Required or optional: Optional

Valid values: true or false

Default value: true

Related attributes:

cpuLimit: Specifies the CPU usage limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
physicalMemoryLimit: Specifies the physical memory limit, in MB, for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
physicalMemoryAutoScale: Enables or disables auto scaling of physical memory limits for a single- or multi-thread service instance (SI) group.
virtualMemoryLimit: Specifies the virtual memory limit for a single- or multi-thread service instance (SI) group, which is defined as a service instance plus all its descendent processes.
virtualMemoryAutoScale: Enables or disables auto scaling of virtual memory limits for a single- or multi-thread service instance (SI) group.

Service > Control > Method

name

Description: Service API method to which defined events apply.

Where use: Service > Control > Method

Required or optional: Required

Valid values:

Register
Deployment
Startup
CreateService
SessionEnter
SessionUpdate
Invoke
SessionLeave
DestroyService

Default value: No default

retryInterval

Description: Specifies the duration in seconds that the Deployment and Startup methods will attempt to retry before a blockHost action is taken.

Where use: Service > Control > Method

Required or optional: Required for Deployment and Startup methods.

Valid values:

Method	Valid value
Register	No value possible
Deployment	0 to 2147483647
Startup	0 to 2147483647
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

Default value:

Method	Valid value
Register	No value possible
Deployment	0
Startup	0
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

retryLimit

Description: Specifies the number of times the Deployment and Startup methods will retry before a blockHost action is taken.

Where use: Service > Control > Method

Required or optional: Required for Deployment and Startup methods.

Valid values:

Method	Valid value
Register	No value possible
Deployment	0 to 10000
Startup	0 to 10000
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

Default value:

Method	Valid value
Register	No value possible
Deployment	0
Startup	0
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

Service > Control > Method > Timeout

Description: Defines how long to wait for the method specified in the <Mthod name- ...> element to complete, and what action to take on service instances, sessions, or tasks, upon timeout of the method.

actionOnSI

Description: Action to take on the service instance when a timeout occurs.

Where use: Service > Control > Method > Timeout

Required or optional: Required. Not allowed for the Startup method.

Valid values: blockHost or restartService:

blockHost: when a timeout is reached on the method, terminate the running service instance on this host and do not use this host to start any other service instance for the application. The host on which the service instance was running is added to the blocked host list for the application. This host is no longer selected to run work for the application until it is explicitly unblocked through the EGO command line or the cluster management console.
restartService: when a timeout is reached on the method, terminate the service instance, start a new service instance on the same host, and recover state. There is no limit to the number of times that a service instance can be restarted.

Not all values are possible with all methods. The following table outlines possible values:

Method	Possible action
Register	blockHost restartService
Deployment	blockHost
Startup	No action possible
CreateService	blockHost restartService
SessionEnter	blockHost restartService
SessionUpdate	blockHost restartService
Invoke	blockHost restartService
SessionLeave	blockHost restartService
DestroyService	No action possible on the service instance

Default value: Default values differ according to method. The following table outlines default values by method:

Method	Default action
Register	blockHost
Deployment	blockHost
Startup	No action possible
CreateService	blockHost
SessionEnter	blockHost
SessionUpdate	blockHost
Invoke	restartService
SessionLeave	restartService
DestroyService	No action possible

actionOnWorkload

Description: Action to take on sessions and tasks when a timeout occurs.

Where use: Service > Control > Method > Timeout

Required or optional: Required. Not allowed for the Startup method.

Valid values: retry or fail:

retry: when a timeout is reached on the method, retry the method up to the number of times configured by the session and task retry limits in the application profile.
For SessionEnter and SessionUpdate, the system attempts to bind the session to the service instance up to the sessionRetryLimit in the application profile before the session is aborted.
Note: The retry count for both of these methods are considered together. For example, if SessionEnter fails once and SessionUpdate fails twice, then the session rerun count is equal to 3. Therefore the sessionRetryLimit should be set to a value that accounts for both SessionEnter and SessionUpdate failures.

For Invoke, the system attempts to run the task up to the taskRetryLimit defined in the application profile before the task is failed.
fail: when a timeout is reached on the method, abort the session or fail the task, and propagate errors to the client application.
For SessionEnter or SessionUpdate, immediately abort the session. Do not retry the method.

For Invoke, immediately fail the task. Do not retry the method.

Not all values are possible with all methods. The following table outlines possible actions for methods:

Method	Possible action
Register	No action possible
Deployment	No action possible
Startup	No action possible
CreateService	No action possible
SessionEnter	retry fail
SessionUpdate	retry fail
Invoke	retry fail
SessionLeave	No action possible
DestroyService	No action possible

Default value: Default values differ according to method. The following table outlines default values by method for actions taken:

Method	Default action
Register	No action possible
Deployment	No action possible
Startup	No action possible
CreateService	No action possible
SessionEnter	retry
SessionUpdate	retry
Invoke	retry
SessionLeave	No action possible
DestroyService	No action possible

customizedDebugAction

Description: Action to take on sessions and tasks when a timeout occurs and service debugsettion="customized".

Where use: Service > Control > Method > Timeout

Required or optional: Optional. Not allowed for the Startup method.

Valid values: writeServiceEventReplayFiles or none:

writeServiceEventReplayFiles: when IBM Spectrum Symphony detects that the specified method has timed out, it generates service event replay files to capture the relevant events that lead up to the timeout. This is the recommended setting if method timeout is an unexpected event for your service.
none: when IBM Spectrum Symphony detects that the specified method has timed out, it does not generate service event replay files. This is the recommended setting if your service times out as a normal occurrence.

Default value: writeServiceEventReplayFiles

duration

Description: Number of seconds to wait for the method specified in

<Method
name=...>

to complete before a timeout is considered.

Where use: Service > Control > Method > Timeout

Required or optional: Required. Not allowed for the Startup method.

Valid values:

Method	Valid value
Register	1 to 2147483647
Deployment	0 to 2147483647
Startup	No value possible
CreateService	0 to 2147483647
SessionEnter	0 to 2147483647
SessionUpdate	0 to 2147483647
Invoke	0 to 2147483647
SessionLeave	0 to 2147483647
DestroyService	0 to 2147483647

Note: The method never times out if you set the value to 0.

Default value:

Method	Default value
Register	60 seconds
Deployment	0 seconds, never timeout
Startup	No value possible
CreateService	0 seconds, never timeout
SessionEnter	0 seconds, never timeout
SessionUpdate	0 seconds, never timeout
Invoke	0 seconds, never timeout
SessionLeave	0 seconds, never timeout
DestroyService	15 seconds

retryInterval

Description: Specifies the duration in seconds that the Register method will attempt to retry when a timeout occurs.

Where use: Service > Control > Method > Timeout

Required or optional: Required for Register method. Not allowed for the Startup method.

Valid values:

Method	Valid value
Register	0 to 2147483647
Deployment	No value possible
Startup	No value possible
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

Default value:

Method	Valid value
Register	0
Deployment	No value possible
Startup	No value possible
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

retryLimit

Description: Specifies the number of times the Register method will retry when a timeout occurs.

Where use: Service > Control > Method > Timeout

Required or optional: Required for the Register method. Not allowed for the Startup method.

Valid values:

Method	Valid value
Register	0 to 10000
Deployment	No value possible
Startup	No value possible
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

Default value:

Method	Valid value
Register	0
Deployment	No value possible
Startup	No value possible
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

Service > Control > Method > Exit

Description: Defines what action to take on service instances, sessions, or tasks, when the method specified with the Method element exists.

actionOnSI

Description: Action to take on the service instance when the method exits.

Where use: Service > Control > Method > Exit

Required or optional: Required. Not allowed for the Startup method.

Valid values: blockHost or restartService:

blockHost: when the method exits, terminate the running service instance on this host and do not use this host to start any other service instance for the application. The host on which the service instance was running is added to the blocked host list for the application. This host is no longer selected to run work for the application until it is explicitly unblocked through the EGO command line or the cluster management console.
restartService: when the method exits, terminate the service instance, start a new service instance on the same host, and recover state. There is no limit to the number of times that a service instance can be restarted.

Note: For Startup and DestroyService, no action is possible on the service instance.

Default value: Default values differ according to method. The following table outlines default values by method for actions:

Method	Default action
Register	blockHost
Deployment	blockHost
Startup	No action possible
CreateService	blockHost
SessionEnter	blockHost
SessionUpdate	blockHost
Invoke	restartService
SessionLeave	restartService
DestroyService	No action possible

actionOnWorkload

Description: Action to take on sessions and tasks when the method exits.

Where use: Service > Control > Method > Exit

Required or optional: Required. Not allowed for the Startup method.

Valid values: retry or fail:

retry: if the service exits during execution of the specified method, retry the method up to the number of times configured by the session and task retry limits in the application profile.
For SessionEnter and SessionUpdate, the system attempts to bind the session to the service instance up to the sessionRetryLimit in the application profile before the session is aborted.
Note: The retry count for both of these methods are considered together. For example, if SessionEnter fails once and SessionUpdate fails twice, then the session rerun count is equal to 3. Therefore the sessionRetryLimit should be set to a value that accounts for both SessionEnter and SessionUpdate failures.

For Invoke, the system attempts to run the task up to the taskRetryLimit defined in the application profile before the task is failed.
fail: when the method exits, abort the session or fail the task, and propagate errors to the client application.
For SessionEnter or SessionUpdate, immediately abort the session. Do not retry the method.

For Invoke, immediately fail the task. Do not retry the method.

Not all values are possible with all methods. The following table outlines possible actions for methods:

Method	Possible action
Register	No action possible
Deployment	No action possible
Startup	No action possible
CreateService	No action possible
SessionEnter	retry fail
SessionUpdate	retry fail
Invoke	retry fail
SessionLeave	No action possible
DestroyService	No action possible

Default value: Default values differ according to method. The following table outlines default values by method for actions taken:

Method	Default action
Register	No action possible
Deployment	No action possible
Startup	No action possible
CreateService	No action possible
SessionEnter	retry
SessionUpdate	retry
Invoke	retry
SessionLeave	No action possible
DestroyService	No action possible

action

Description: Action to take on sessions and tasks when the service process exits during the execution of the specified method and service debugSetting="customized".

Where use: Service > Control > Method > Exit

Required or optional: Optional. Not allowed for the Startup method.

Valid values: writeServiceEventReplayFiles or none:

writeServiceEventReplayFiles: when IBM Spectrum Symphony detects that the service process has exited (or crashed) while executing the specified method, it generates service event replay files to capture the relevant events that lead up to the exit. This is the recommended setting if the service process exiting or crashing in the specified method is an unexpected event for your service.
none: when IBM Spectrum Symphony detects that the service process has exited (or crashed) during execution of the specified method, it does not generate service event replay files. This is the recommended setting if your service exits as a normal occurrence.

Default value: writeServiceEventReplayFiles

retryInterval

Description: Specifies the duration in seconds that the Register method will attempt to retry on exit.

Where use: Service > Control > Method > Exit

Required or optional: Required for Register method. Not allowed for the Startup method.

Valid values:

Method	Valid value
Register	0 to 2147483647
Deployment	No value possible
Startup	No value possible
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

Default value:

Method	Valid value
Register	0
Deployment	No value possible
Startup	No value possible
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

retryLimit

Description: Specifies the number of times the Register method will attempt to retry on Exit.

Where use: Service > Control > Method > Exit

Required or optional: Required for Register method. Not allowed for the Startup method.

Valid values:

Method	Valid value
Register	0 to 10000
Deployment	No value possible
Startup	No value possible
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

Default value:

Method	Valid value
Register	0
Deployment	No value possible
Startup	No value possible
CreateService	No value possible
SessionEnter	No value possible
SessionUpdate	No value possible
Invoke	No value possible
SessionLeave	No value possible
DestroyService	No value possible

Service > Control > Method > Return

Description: defines what action to take on service instances, sessions, or tasks, when the method specified in the

<Method name
...>

element returns normally (that is, controlCode=0), or if a control code is defined, defines what action to take when the method returns with the specified return code.

actionOnSI

Description: Action to take on the service instance when the method returns normally or with the specified control code.

Where use: Service > Control > Method > Return

Required or optional: Required. Not allowed for the Startup method.

Valid values: blockHost, restartService, or keepAlive:

Note: Actions on return cannot be configured for Register, Deployment, Startup, or DestroyService.

blockHost: when the method returns normally or with a specified control code, terminate the running service instance on this host and do not use this host to start any other service instance for the application.
The host on which the service instance was running is added to the blocked host list for the application. This host is no longer selected to run work for the application until it is explicitly unblocked through the EGO command line or the cluster management console.
restartService: when the method returns normally or with a specified control code, terminate the service instance, start a new service instance on the same host, and recover state. There is no limit to the number of times that a service instance can be restarted.
keepAlive: when the method returns normally or with a specified control code, take no action on the running service instance. Return an error only.

Default value:

Method	Default value
Register	No action possible
Deployment	No action possible
Startup	No action possible
CreateService	keepAlive
SessionEnter	keepAlive
SessionUpdate	keepAlive
Invoke	keepAlive
SessionLeave	keepAlive
DestroyService	No action possible

actionOnWorkload

Description: Action to take on sessions and tasks when the method returns normally, or with a specified control code.

Where use: Service > Control > Method > Return

Required or optional: Required. Not allowed for the Startup method.

Valid values: retry, fail, or succeed:

retry: when the method returns normally or with the specified control code, retry the method up to the number of times configured by the session and task retry limits in the application profile.
For SessionEnter and SessionUpdate, the system attempts to bind the session to the service instance up to the sessionRetryLimit in the application profile before the session is aborted.

Note: The retry count for both of these methods are considered together. For example, if SessionEnter fails once and SessionUpdate fails twice, then the session rerun count is equal to 3. Therefore the sessionRetryLimit should be set to a value that accounts for both SessionEnter and SessionUpdate failures.

For Invoke, the system attempts to run the task up to the taskRetryLimit defined in the application profile before the task is failed.
fail: when the method returns normally or with the specified control code, abort the session or fail the task, and propagate errors to the client application.
For SessionEnter or SessionUpdate, immediately abort the session. Do not retry the method.

For Invoke, immediately fail the task. Do not retry the method.
succeed: this is a normal return. This is treated as a successful execution of SessionEnter, SessionUpdate, or Invoke.
For Invoke, the task completes successfully (in the Done state).

Not all values are possible with all methods. The following table outlines possible actions for methods:

Method	Possible value
Register	No action possible
Deployment	No action possible
Startup	No action possible
CreateService
SessionEnter	retry fail succeed
SessionUpdate	retry fail succeed
Invoke	retry fail succeed
SessionLeave	No action possible
DestroyService	No action possible

Default value: Default values differ according to method:

Method	Default value
Register	No action possible
Deployment	No action possible
Startup	No action possible
CreateService	No action possible
SessionEnter	succeed
SessionUpdate	succeed
Invoke	succeed
SessionLeave	No action possible
DestroyService	No action possible

controlCode

Description: Numeric identifier that indicates to the system what action to take based on the number that is returned by the method specified in the Method element. There can be multiple control codes defined per method, and different actions to take based on control code.

Where use: Service > Control > Method > Return

Required or optional: Required. Not allowed for the Startup method.

Valid values: Any positive or negative integer

Default value: 0 to indicate the default action taken on workload and service instances, as specified by default actions on actionOnSI and actionOnWorkload.

customizedDebugAction

Description: Action to take on the service instance when the method returns normally or with the specified control code when service debugSetting="customized".

Where use: Service > Control > Method > Return

Required or optional: Optional. Not allowed for the Startup method.

Valid values: writeServiceEventReplayFiles or none:

writeServiceEventReplayFiles: when IBM Spectrum Symphony detects that the specified method has returned normally with or without a specific control code, it generates service event replay files.
none: when IBM Spectrum Symphony detects that the specified method has returned normally with or without a specific control code, it does not generate service event replay files. This is the recommended setting, as this is typically a normal, successful event.

Default value: none

Service > Control > Method > Exception

actionOnSI

Description: Action to take on the service instance when a failure or fatal exception occurs.

Where use: Service > Control > Method > Exception

Required or optional: Required. Not allowed for the Startup method.

Valid values: blockHost, restartService, or keepAlive:

blockHost: when the specified exception occurs, terminate the running service instance on this host and do not use this host to start any other service instance for the application.
The host on which the service instance was running is added to the blocked host list for the application. This host is no longer selected to run work for the application until it is explicitly unblocked through the EGO command line or the cluster management console.
restartService: when the specified exception occurs, terminate the service instance, start a new service instance on the same host, and recover state. There is no limit to the number of times that a service instance can be restarted.
keepAlive: when the specified exception occurs, take no action on the running service instance.

Note: Actions cannot be configured for Register, Deployment, Startup, or DestroyService

Method	Possible values Fatal exception	Possible values Failure exception
Register	No action possible	No action possible
Deployment	No action possible	No action possible
Startup	No action possible	No action possible
CreateService	blockHost restartService	blockHost restartService
SessionEnter	blockHost restartService keepAlive	blockHost restartService keepAlive
SessionUpdate	blockHost restartService keepAlive	blockHost restartService keepAlive
Invoke	blockHost restartService keepAlive	blockHost restartService keepAlive
SessionLeave	blockHost restartService keepAlive	blockHost restartService keepAlive
DestroyService	No action possible	No action possible

Default value:

Method	Default values Fatal exception	Default values Failure exception
Register	No action possible	No action possible
Deployment	No action possible	No action possible
Startup	No action possible	No action possible
CreateService	blockHost	blockHost
SessionEnter	keepAlive	keepAlive
SessionUpdate	keepAlive	keepAlive
Invoke	keepAlive	keepAlive
SessionLeave	keepAlive	keepAlive
DestroyService	No action possible	No action possible

actionOnWorkload

Description: Action to take on sessions and tasks when a fatal or failure exception occurs.

Where use: Service > Control > Method > Exception

Required or optional: Required. Not allowed for the Startup method.

Valid values:

retry: when the specified exception occurs, retry the method up to the number of times configured by the session and task retry limits in the application profile.
For SessionEnter and SessionUpdate, the system attempts to bind the session to the service instance up to the sessionRetryLimit in the application profile before the session is aborted.

Note: The retry count for both of these methods are considered together. For example, if SessionEnter fails once and SessionUpdate fails twice, then the session rerun count is equal to 3. Therefore the sessionRetryLimit should be set to a value that accounts for both SessionEnter and SessionUpdate failures.

For Invoke, the system attempts to run the task up to the taskRetryLimit defined in the application profile before the task is failed.
fail: when the specified exception occurs, abort the session or fail the task, and propagate errors to the client application.
For SessionEnter or SessionUpdate, immediately abort the session. Do not retry the method.

For Invoke, immediately fail the task. Do not retry the method.

Not all values are possible with all methods. The following table outlines possible actions for methods:

Method	Possible values Fatal exception	Possible values Failure exception
Register	No action possible	No action possible
Deployment	No action possible	No action possible
Startup	No action possible	No action possible
CreateService	No action possible	No action possible
SessionEnter	retry fail	retry fail
SessionUpdate	retry fail	retry fail
Invoke	retry fail	retry fail
SessionLeave	No action possible	No action possible
DestroyService	No action possible	No action possible

Default value: Default values differ according to method:

Method	Default values Fatal exception	Default values Failure exception
Register	No action possible	No action possible
Deployment	No action possible	No action possible
Startup	No action possible	No action possible
CreateService	No action possible	No action possible
SessionEnter	fail	retry
SessionUpdate	fail	retry
Invoke	fail	retry
SessionLeave	No action possible	No action possible
DestroyService	No action possible	No action possible

controlCode

Description: Numeric identifier that indicates to the system what action to take based on the number that is returned by the specified exception. There can be multiple control codes defined per exception, and different actions to take based on control code.

Where use: Service > Control > Method > Exception

Required or optional: Required. Not allowed for the Startup method.

Valid values: Any positive or negative integer

Default value: 0 to indicate the default action taken on workload and service instances, as specified by default actions on actionOnSI and actionOnWorkload.

customizedDebugAction

Description: Action to take on sessions and tasks when a fatal or failure exception occurs in the specified method and debugSetting="customized".

Where use: Service > Control > Method > Exception

Required or optional: Optional. Not allowed for the Startup method.

Valid values: writeServiceEventReplayFiles or none:

writeServiceEventReplayFiles: when IBM Spectrum Symphony detects that the specified method has thrown a particular exception (FatalException or FailureException), as specified, it generates service event replay files to capture the relevant events that lead up to the exception.
none: when IBM Spectrum Symphony detects that the specified method has thrown a particular exception (FatalException or FailureException), as specified, it does not generate service event replay files.

Default value: writeServiceEventReplayFiles

type

Description: Exception type to which the configured action applies. Exception types cannot be configured for Register, Deployment, Startup, or DestroyService.

Where use: Service > Control > Method > Exception

Required or optional: Required. Not allowed for the Startup method.

Valid values: failure or fatal:

failure: exception type is FailureException.
fatal: exception type is FatalException.

Default value: No default