Understanding and Using the IWSRV Executable Program

In this section:

The iwsrv executable program allows you to install a Windows service for iWay Service Manager (iSM) that can be used to start an iSM configuration. You can also start iSM using iwsrv in a command window for debugging purposes.


Top of page

x
IWSRV Options

This section lists and describes all of the available options for the iwsrv executable program.

The full syntax for the iwsrv command is:

iwsrv [config_name] [-s service] [-l launch] [options]

where:

config_name

Is the name of the iSM configuration that is loaded for this instance. The default iSM configuration is base.

service

Is the name of the iSM Windows service that is executed. Valid values are:

start: Starts the iSM configuration for the Windows service (default). For more information, see How to Start iSM in a Command Window.

stop: Stops the iSM configuration for the Windows service. For more information, see How to Stop iSM in a Command Window

install: Installs the iSM Windows service. For more information, see How to Install an iSM Windows Service.

remove: Deletes the iSM Windows service. For more information, see How to Delete an iSM Windows Service.

query: Displays the options that were used to install an iSM Windows service. For more information, see How to Query the Install Options for an iSM Windows Service.

launch

Specifies the launch method. Valid values are:

java: Loads Java in a separate process and uses the JVM options, NT dependencies, and other preferences found within the iSM configuration that are configured through the console.

For example:

iwsrv config_name -s start -l java

where:

config_name

Is the name of the iSM configuration.

Using the -l option forces the iSM Windows service to load Java in a separate process. When the iSM Windows service is stopped, iwsrv.exe and java.exe are terminated.

options

Specifies tracing or server backup information. Valid values include:

-b: Indicates that iSM is a backup server.

For example:

iwsrv config_name -s start -b

where:

config_name

Is the name of the iSM configuration.

-c: Enables tracing. In this mode, you can display useful error messages on the console. For example, you can display a message which indicates that the Java Runtime Environment (JRE) is not properly installed.

For example:

iwsrv config_name -s start -c

where:

config_name

Is the name of the iSM configuration.

-d: Limits tracing to debug only.

For example:

iwsrv config_name -s start -d

where:

config_name

Is the name of the iSM configuration.

-f: [PATH] -- Filters the system path when invoking Java.

-f [RESTART] -- Suppresses the JVM fault restart capability.

-h: Sets the iway7 home directory.

For example:

iwsrv config_name -s start -h C:\Program Files\iway7

where:

config_name

Is the name of the iSM configuration.

-t: The amount of time (in seconds) to process an iSM Windows service shutdown.

For example:

iwsrv config_name -s start -t

where:

config_name

Is the name of the iSM configuration.

Note:


Top of page

x
Starting and Stopping iSM in a Command Window

For debugging purposes, you can run iSM in a command window instead of running it as a Windows service.

The command window enables you to interact with iSM and displays diagnostic information about iSM processing.



x
Procedure: How to Start iSM in a Command Window

To start iSM in a command window:

  1. Open a Command Prompt window and navigate to the iSM home \bin directory. For example:
    C:\Program Files\iway7\bin
  2. At the command prompt, type:
    iwsrv

    By default, the iSM base configuration is started.

    Note: To start other iSM configurations, type the iSM configuration name after the iwsrv command. For example:

    iwsrv TestConfig

    iSM configuration names are case-sensitive.

  3. Press Enter.

    Messages are displayed in the command window detailing the iSM startup process. The following prompt is displayed when the iSM startup process is completed:

    Enter command:>

    If you receive the following error message, then iSM is probably already running as a Windows service:

    ERROR (HTTP1) Unable to create server socket 9980:
    java.net.BindException: Address already in use: JVM_Bind
    ERROR (SOAP1) Unable to create server socket 9000:
    java.net.BindException: Address already in use: JVM_Bind

    You cannot run the same iSM configuration at the same time as an iSM Windows service and in the command window.



x
Procedure: How to Stop iSM in a Command Window

To stop iSM in a command window:

  1. Go to the iSM command prompt:
    Enter command:>
  2. Type the following:
    stop
  3. When any listeners that are running have stopped, type the following:
    quit

    Note: Using the quit command terminates iSM. Never terminate iSM without using quit (for example, the kill command on Unix). Doing so may leave messages in process, resulting in a loss of resource integrity.


Top of page

x
Installing and Deleting an iSM Windows Service

This section describes how to install and delete an iSM Windows service that can be used to start an iSM configuration.

By default, the iwsrv executable program installs an iSM Windows service to run out of process. You can view the options that were used to install an iSM Windows service by using the iwsrv query option. For more information, see How to Query the Install Options for an iSM Windows Service.



x
Procedure: How to Install an iSM Windows Service

To install an iSM Windows service:

  1. Open a Command Prompt window and navigate to the iSM home \bin directory. For example:
    C:\Program Files\iway7\bin
  2. At the command prompt, type
    iwsrv config_name -s install

    where:

    config_name

    Is the name of the iSM configuration for which you are creating a Windows service.

    To create a Windows service with Java running in a separate process, type

    iwsrv config_name -s install -l java

    where:

    config_name

    Is the name of the iSM configuration for which you are creating a Windows service.

    A message is displayed, indicating that the iSM Windows service was installed successfully.

    You must now start the iSM configuration as a Windows service. For more information, see How to Start an iSM Configuration as a Windows Service.



x
Procedure: How to Delete an iSM Windows Service

To delete an iSM Windows service that you created to start an iSM configuration:

  1. Open a Command Prompt window and navigate to the iSM home \bin directory. For example:
    C:\Program Files\iway7\bin
  2. At the command prompt, type
    iwsrv config_name -s remove

    where:

    config_name

    Is the name of the iSM configuration for which you are deleting a Windows service.

    A message is displayed, indicating that the iSM Windows service was deleted successfully.

    You can now delete the iSM configuration from the iWay Service Manager Administration Console. For more information, see How to Remove a Configuration From the Console.



x
Procedure: How to Start an iSM Configuration as a Windows Service

To start an iSM configuration as a Windows service:

  1. From the Windows Start menu, select Control Panel.

    The Control Panel opens.

  2. Double-click Administrative Tools.

    The Administrative Tools are displayed.

  3. Double-click Services.

    The Windows Services are displayed.

  4. Scroll down to display the iSM Windows service, as shown in the following image.

  5. Right-click the service you created (for example, iWay Service Manager 6-1 - TestConfig) and select Start from the context menu.

    The service Status changes to Started. The default Startup Type is Automatic.


Top of page

x
Querying the Install Options for an iSM Windows Service

For debugging purposes, you can perform a query to display the options that were used to install an iSM Windows service.



x
Procedure: How to Query the Install Options for an iSM Windows Service

To query the install options:

  1. Open a Command Prompt window and navigate to the iSM home \bin directory. For example:
    C:\Program Files\iway7\bin
  2. At the command prompt, type
    iwsrv config_name -s query

    where:

    config_name

    Is the name of the iSM configuration for which you are running a query.

  3. Press Enter.

    Information showing the options that were used to install the iSM Windows service is displayed in the command window. For example:

    Copyright (C) iWay Software. 2001-2012 All Rights Reserved
    "iWay Service Manager 7.0 - base" is currently installed
      Installation date  : 11/23/2012
      Installed via         : iwsrv.exe base -s install -l java -h C:\iway7x23
      Installed by       : Administrator

Top of page

x
Understanding How IWSRV Selects a JVM in Process (Not -l Java)

This section describes how the iwsrv executable program selects a JVM in process (not -l Java).

  1. If the IWAYISM7 environmental variable is set, then it will use its value to load the JVM (for example, G:\j2sdk1.4.1_03\jre\bin\server\jvm.dll).
  2. If -server is specified as a JVM option, then the service uses the registry to find JAVAHOME of the Java Development Kit (JDK). Once JAVAHOME is determined (for example, G:\j2sdk1.4.1_03), then it appends the following string:
    \jre\bin\server\jvm.dll
  3. The service uses the registry to determine where the current version of the JRE is installed. It queries for the following registry key:
    JavaSoft\\Java Runtime Environment\1.4\RuntimeLib

    The 1.4 component of the key is dynamic based on the current version of the JRE. The value of this key is then used to load the JVM. For example:

    E:\Program Files\Java\j2re1.4.1_03\bin\client\jvm.dll
  4. During installation, you have the option to point to a JVM. If you choose this option, then the service uses this value to load the JVM.

Top of page

x
Server Command Files

This section describes the available server command files that you can use to manually control startup activity.

You can use iWay Service Manager (iSM) to execute commands, such as start and stop, from the iSM command shell, as shown in the following image.

These commands can also be added to command files and executed by the following:

All server commands that are available from the shell can be included in command files. iWay expects that those commands that affect the server, such as start, stop and set will be the most useful. Nothing prevents other commands, such as memory, from being run in the command file. However, the information that is output by these commands may not appear in a convenient place.

Note: To control which JRE is used by the iWay Secure Messaging Option (iSMO) product, you can set the IWAYISM7 system environment variable to the full path where the jvm.dll file is located. For example:

IWAYISM7=c:\java\jre\bin\server\jvm.dll


x
Understanding the Command File Structure

Command files can make use of the iWay Functional Language during their execution. For example, consider a properties file names testprop that contains the following lines:

1. dostart=start
2. whattoday=chan3

Now consider the following command file:

1. // this is a test file
2. set debug on
3. _property('c:/testprop.properties','dostart',';') file1
4. _if(sreg('condition1')='true'),'start file1',';')
5. // last line of test file

The first line is a comment. Any line beginning with a // or a semicolon is a comment. The second line enables debug tracing. Line 3 is an IFL statement, testing the dostart property in the testprop.properties file. If the property is not found, then the semicolon is returned and the line is ignored. If it is found, the value start is returned, and the line now reads:

start file1

This line starts the named channel file1.

Line 4 is another IFL statement. In this case, if the special register condition1 is set to true, then the start file1 command is executed.

Line 3 and line 4 show two methods for conditionally executing lines in a command file.

The command file also supports the special command goto <label>. A label is a named line in the file located after the goto command. A label is defined as a Java defined name that ends with a colon and must exist with no other commands on that line.

1. // this is a test file with goto
2. goto point
3. _if (_properties('c:/props','whattoday')=='chan3','goto point3')
4. start chan1
5. start chan2
6. goto end
7. point3:
8. start chan3
9. end:
10. // last line of test file

In this command file, the IFL statement on line 3 instructs the server that if the whattoday property is set to chan3, then the commands pick up on line 7. Else, the commands on lines 4 through 6 will execute. For more information on using a command file, see the iWay Service Manager Command Reference Guide.


Top of page

x
Configuring the Autocmd.txt File

The autocmd.txt file can be configured to run during the iSM startup process to set customized options for use by iSM. For example, this configuration file can be used to map network drives on your system.

To enable this functionality, the autocmd.txt file must be copied to an iSM configuration directory. For example:

C:\Program Files\iway7\config\base

The contents of the autocmd.txt file can point to a batch file on your file system. For example:

shell C:\a1.bat

The batch file (for example, a1.bat) can contain the following network drive assignments:

net use W: /delete > c:\iway7\netuse.txt 2>&1
net use W: \\ibiprda\IBI  xxxx /USER:ibi\XX12345 /persistent:yes >> c:\iway7\netuse.txt 2>&1

Top of page

x
Channel Startup Order

iWay Service Manager (iSM) startup always first creates internal (and ordered) queues, so that they are available as soon as channels that may need to be added to the queue begin processing messages. Next, active channels are started. If the channel is configured with a startup dependency, then the dependent channels are started before the channel itself. This way, you can control the startup sequence.

A startup script (or flow) can also start channels in any order that is required.


iWay Software