uCosminexus Application Server, Definition Reference Guide

[Contents][Index][Back][Next]

10.21 Logical user server definition file

Organization of this section
(1) Format
(2) File storage location
(3) Functionality
(4) Contents that you can define
(5) Sample definition
(6) Precautions

(1) Format

xml file format.

(2) File storage location

Any storage location and file name is possible.

(3) Functionality

You create this file when adding a logical user server by the mngsvrutil command.

(4) Contents that you can define

The following table describes the contents that you can code in the logical user server definition file:

Element name Description Default value
user-server-definition Specify the following path as namespace:
http://www.cosminexus.com/mngsvr/schema/UserServerDefinition-1.1		 -- 
 
Service
 -- 
--
 
 
 
Type
 Specify whether to start directly or indirectly.
When you specify direct:
Starts up directly.
When you specify indirect:
Starts up indirectly.		 
direct
 
 
 
startup-order
 Specify an integer from -1 to 999 for the startup order. When -1 is specified, the element is ignored. 
900
 
 
 
start-watch-time
 Choose a start watch time from the following numeric values (units: seconds). When 0 is specified, monitoring is not performed.
0, 60, 300, 600, 3600		 
60
 
 
 
stop-watch-time
 Choose a stop watch time from the following numeric values (units: seconds). When 0 is specified, monitoring is not performed.
0, 60, 300, 600, 3600, 1800		 
60
 
 
 
force-watch-time
 Choose a force stop watch time in the following numeric value (unit: seconds). When 0 is specified, monitoring is not performed.
0, 60, 300, 600, 1800		 
60
 
 
 
retry-count
 Specify the auto restart frequency, choose one from the following numeric values:
0, 1, 5, 10, 1000		 
1
 
 
 
retry-interval
 Specify the auto restart retry interval, choose one from the following numeric values (units: seconds). When 0 is specified, performs immediate retry.
0, 60, 300, 600, 3600,1800		 
60
 
 
 
watch-interval
 Specify an integer from 1 to 86400 (units: seconds) for the monitoring interval.
Note that if you specify the monitoring interval along with the adminagent.userserver.watch.interval key of the Administration Agent property file, the value specified in this tag is valid.		 
1
 
 
 
start-time-watch-interval
 Specify the start time monitoring interval, as an integer between 1 and 86400 (units: seconds). 
1
 
 
 
env
 Define the environment variable.
You can specify multiple name-value pairs.		 
--
 
 
 
 
name
 Specify an environment variable name.
Specify this value without fail.		 
--
 
 
 
 
value
 Specify an environment variable name.
Specify this value without fail.
If the string ${cosminexus.home} exists in the value specified for environment variables, that value is replaced with Cosminexus-installation-directory.		 
--
 
 
 
working-dir
 Specify the working directory, as an absolute path. 
Cosminexus-installation-directory/manager/bin
 
 
 
user-id
 Specify the user ID at command runtime.
This element is used for UNIX.		 
--
 
 
 
group-id
 Specify the group ID at command runtime.
This element is used for UNIX.		 
--
 
 
 
command
 Define the command.
Specification is mandatory. You can specify multiple commands.		 
--
 
 
 
 
type
 Specify the command type#1. You can specify the following values:
Start: Command for starting the server
Stop: Command for stopping the server
ForceStop: Command for forced termination of the server
GetProcessID: Command for acquiring process ID
IsAlive: Command for service monitoring
Specification is mandatory.		 
--
 
 
 
 
timeout
 Specify an integer (units: bytes) from 1 to 86400 for the timeout time.
It is valid only when the command type is getProcessID or isAlive.		 
180
 
 
 
 
arg
 Specify the command arguments.#2
Specification is mandatory.
To add arguments and argument values for a command, specify multiple <arg> tags.
An example of specifying the <arg> tag is as follows:
<arg>Command</arg>
<arg>Argument-1</arg>
<arg>Value-specified-in-Argument-1</arg>
<arg>Argument-2-(No-value-is-specified)</arg>
<arg>Argument-3</arg>
<arg>Value-specified-in-Argument-3</arg>		 
--
 
 
server
 Define the logical user server.
Specification is mandatory. You can specify multiple servers.		 
--
 
 
 
logical-server-name
 Specify logical server name in less than 128 characters. You can use single byte alphanumeric characters (A to Z, a to z, 0 to 9), under scores (_), and hyphens (-).
Specification is mandatory.		 
--
 
 
 
display-name
 Specifies the display name of the logical server within 128 characters. 
--
 
 
 
description
 Specify the explanation about the logical server in less than 1024 characters. 
--
host-ref Specify the host name defined beforehand in less than 255 characters. You can use single byte alphanumeric characters (A to Z, a to z, 0 to 9), under scores (_), hyphens (-), and periods(.).
Specification is mandatory.		 --

#1
Depending on the type of startup, the various command types have different conditions of specification. The following table describes the specification conditions and command type requirements based on the type of startup:

Startup type Command type Specification condition Requirements Remarks
Direct start start Required Server startup commands are included in the scope of monitoring. --
stop Optional The monitored process is already stopped when the server stop command terminates normally. When you do not specify a stop type of command, the following operations are performed:
  • In Windows
    A Ctrl-C event is issued to the corresponding process. If the process does not stop, TerminateProcess () is executed.
  • In UNIX
    A SIGTERM signal is sent to the corresponding process. If the process does not terminate within 1 second after that, a SIGKILL signal is sent.
forceStop Optional
  • The monitored process is already stopped when the forceStop type of command terminates.
  • After issuing a forceStop type of command, the server startup commands are in an executable status.
 When you do not specify a stop type of command, the following operations are performed:
  • In Windows
    A Ctrl-C event is issued to the corresponding process. If the process does not stop, TerminateProcess () is executed.
  • In UNIX
    A SIGTERM signal is sent to the corresponding process. If the process does not terminate within 1 second after that, a SIGKILL signal is sent.
getProcessID Cannot be specified -- If specified, it results in error.
isAlive Optional The command should return a termination code of 0 if the service is running and a termination code other than 0, if the service is not running. When specified, the service is monitored.
Indirect start start Required
  • All the monitored processes are started when the process startup command terminates normally.
  • When the process startup command terminates normally, the process stop commands are in an executable state.
  • The command returns the termination code as 0 in case of normal termination, and 1 in case of abnormal termination.
 --
stop Optional The monitored process is already stopped when the server stop command terminates normally. When you do not specify a stop type of command, the following operations are performed:
  • In Windows
    A Ctrl-C event is issued to the corresponding process. If the process does not stop, TerminateProcess () is executed.
  • In UNIX
    A SIGTERM signal is sent to the corresponding process. If the process does not terminate within 1 second after that, a SIGKILL signal is sent.
forceStop Optional
  • The monitored process is already stopped when the forceStop type of command terminates.
  • After issuing a forceStop type of command, the server startup commands are in an executable status.
 When you do not specify a stop type of command, the following operations are performed:
  • In Windows
    A Ctrl-C event is issued to the corresponding process. If the process does not stop, TerminateProcess () is executed.
  • In UNIX
    A SIGTERM signal is sent to the corresponding process. If the process does not terminate within 1 second after that, a SIGKILL signal is sent.
getProcessID Required
  • The command outputs the process ID of the process started by the server startup command, to the standard output.
  • When multiple processes are started, the command outputs the process IDs of all the processes.
  • The command returns the termination code as 0 in case of normal termination, and 1 in case of abnormal termination.
  • The output format is as follows:
9 9 9 6 \n
1 0 0 2 3 \n
1 0 2 5 7 \n
 --
isAlive Optional The command should return a termination code of 0 if the service is running and a termination code other than 0, if the service is not running. When specified, the service is monitored.

#2
If you use any of the following character strings when specifying the value of a command argument, it is replaced with the corresponding value of that string:

Character string before replacement Character string after replacement Remarks
${cosminexus.home} Cosminexus-installation-directory --
%{XXX} Environment variable XXX value When the environment variable XXX does not exist, it is replaced with a blank character string.
${server.name} logical-server-name --

(5) Sample definition

<?xml version="1.0" encoding="UTF-8" ?>
<user-server-definition xmlns="http://www.cosminexus.com/mngsvr/schema/UserServerDefinition-1.1">
  
<!--Service definition -->
 <service>
 <!--Start type -->
 <type>direct</type>
 <!--Startup order -->
 <startup-order>900</startup-order>
 <!--Start monitoring time -->
 <start-watch-time>60</start-watch-time>
 <!--Stop monitoring time -->
 <stop-watch-time>60</stop-watch-time>
 <!--Forced stop monitoring time --> 
 <force-watch-time>60</force-watch-time>
 <!--Retry count -->
 <retry-count>1</retry-count>
 <!--Retry interval -->
 <retry-interval>60</retry-interval>
 <!--Monitoring interval -->
 <watch-interval>1</watch-interval>
 <!--Start time monitoring interval -->
 <start-time-watch-interval>1</start-time-watch-interval>
 <!--Environment variable -->
 <env name="USERSERVER_HOME" value="C:\UserServer"/>
 <!--Working directory -->
 <working-dir>C:\UserServer</working-dir>
 <!--User ID -->
 <user-id>userserver</user-id>
 <!--Group ID -->
 <group-id>userserver</group-id>
 <!--Server startup command -->
 <command type="start">
 <arg>C:\UserServer\start.exe</arg>
 </command>
 <!--Server stop command -->
 <command type="stop">
<arg>C:\UserServer\stop.exe</arg>
 </command>
 <!--Command for forced termination of server -->
 <command type="forceStop">
 <arg>C:\UserServer\forceStop.exe</arg>
 </command>
 <!--Command to get process ID -->
<!--
 <command type="getProcessID" timeout="180">
 <arg>C:\UserServer\getProcessID.exe</arg>
 </command>
-->
 <!--Command for service monitoring -->
 <command type="isAlive" timeout="180">
 <arg>C:\UserServer\isAlive.exe</arg>
 </command>
 </service>
 
<!--Logical user server definition -->
 <server>
 <logical-server-name>UserServer01</logical-server-name>
 <display-name>Logical user server</display-name>
 <description>This is a logical user server</description>
 <host-ref>192.168.1.1</host-ref>
 </server>
</user-server-definition>

(6) Precautions

[Contents][Back][Next]

[Trademarks]

All Rights Reserved. Copyright (C) 2012, 2015, Hitachi, Ltd.