Running an EntireX RPC Server as a Windows Service

This page covers the following topics:

Introduction
Sample Installation
EntireX RPC Service Tool
Customizing the Service
Removing the Service
Tracing for the Windows Service
Starting an RPC Server Using the Service
Stopping an RPC Server Using the Service
Running with EntireX Security
Windows-specific Folders

Introduction

Any EntireX RPC server can be run as a Windows service. This has the following advantages:

The server is started automatically when the PC is booted and shut down automatically when the PC is shut down.
The service can be run under a system account that has different rights on a PC than the user account.
The service can be run under any valid user ID.
The Control Panel provides an overview of started servers and their status.

To run an RPC server as a Windows service, a batch script (.bat) that can start the RPC server is required. Sample batch scripts are provided in the EntireX bin folder:

microfocusserver.bat
cserver.bat
cicseciserver.bat
imsconnectserver.bat
dotNetServer.bat
jrpcserver.bat
jxmlrpcserver.bat
...

To install RPC server as windows services, use the EntireX RPC Service Tool. Multiple services can be installed if more than one RPC server is required.

Sample Installation

Note:
The steps below use the C RPC Server as an example, but the information applies to all RPC servers.

To install an RPC Server as a Windows Service

Enter the EntireX installation directory and copy file EntireX\bin\RPCService.bat. Save the file under a different name, for example EntireX\bin\RPCService_C.bat.

The EntireX installation directory is specified during installation. Later on when registering the service, the argument value of parameter -ext of rpcservice.exe must correspond with this extension, for example -ext C.

The extension _C will later correspond with the argument in parameter –ext when registering the service using rpcservice.exe. Also the name of the service will be extended by this value. This is needed to distinguish multiple server instances.
Modify batch file RPCService_C.bat and uncomment the line where the C RPC server batch file is referenced.
```
cserver.bat %*
```
The file contains entries for all the different types of RPC servers. The C RPC server is already uncommented, it is the default.
Adapt the corresponding configuration file, for example \EntireX\config\cserver.cfg, to your needs.
Optionally test whether the server is configured correctly before registering it as a Windows service by entering the following from a command prompt:
```
RPCService_C.bat
```

rpcservice.exe -install -ext C -serverlog c:\serverlog.txt -trace c:\servertrace.txt -script c:\SoftwareAG\EntireX\bin\RPCservice_C.bat

where	`c:\SoftwareAG`	is the installation directory,
	`-ext`	must correspond with the extension specified in step 1
	`-serverlog`	is optional
	`-trace`	is optional
	`-script`	must point to file RPCservice_C.bat created in step 1

EntireX RPC Service Tool

The EntireX RPC Service Tool is provided to install, remove, start and stop RPC services. An overview screen "Software AG EntireX RPC Service" lists the available arguments and options.

Displaying the available Arguments and Options

To display the overview screen

In the command line, go to the EntireX bin directory and enter:

rpcservice.exe -help

The following screen is displayed:

            Software AG EntireX RPC Service (V.n.n.n)
             Service Tool to start/stop RPC servers
      (c) Copyright Software AG 1997-20nn. All rights reserved.
           ---------------------------------------------------

Usage:
rpcservice -install         [options]    to install the service
rpcservice -remove          [options]    to remove the service
rpcservice -help            [options]    prints this panel

Options:
      [-ext[ension]     <extension>]         use a service extension
      [-script          <path\script>]       set the server startup file 
                                             for this service
      [-serverlog       <path\logfile>]      set the communication file
                                             between server and service
      [-userid          <userid>]            set userid for broker logon
      [-password        <password>]          set password for broker logon
      [-trace           [<tracefile>]]       used for diagnostics

Explanation of Options

No option
This will install a service displayed as "Software AG EntireX RPC Service". The service is registered as EXXRPCService (Service name under Properties). Required suboptions will be set to their defaults.
-extension <ext>
use this option to add an extension to the service to differentiate it from other instances, if you want to install multiple RPC service instances. The service will be displayed as "Software AG EntireX RPC Service [<ext>]". The default log file RPCservice_<ext>.log. will be added.

Important:
If you use this option, the program will by default search for a script with the same extension, RPCService_<ext>.bat. Make sure it exists.

Example:
- For a Java RPC Server (see also Running the Java RPC Server as a Windows Service), you can use
```
-install -ext java -script <EntireX bin directory>\jrpcserver.bat
```
  The service will be displayed as Software AG EntireX RPC Service [java], the log file will be called RPCservice_java.log.
- For an XML/SOAP RPC Server (see also Running the XML/SOAP RPC Server as a Windows Service), you can use
```
-install -ext java -script <EntireX bin directory>\jxmlrpcserver.bat
```
  The service will be displayed as Software AG EntireX RPC Service [xml], the log file will be called RPCservice_xml.log.
- For a Micro Focus RPC Server you can use:
```
-install -ext MicroFocus -script  <EntireX bin directory>\microfocusserver.bat
```
  The service will be displayed as Software AG EntireX RPC Service [MicroFocus], the log file will be called RPCservice_MicroFocus.log.
- For a C RPC Server you can use:
```
-install -ext C -script cserver.bat
```
  The service will be displayed as Software AG EntireX RPC Service [C], the log file will be called RPCservice_C.log.
Default: none.
-script
use this option to specify a batch script other than the default scripts RPCService.bat or RPCService_<ext>.bat.

Important:
The script file must pass external parameters to the RPC server. Please make sure that %* remains at the end of the line that contains the RPC server call, so that parameters coming from the Windows Service are passed to the RPC server:
```
rpcserver.exe "cfg=..\config\cserver.cfg"%*
```
Default: <EntireX-installation>\bin\RPCService.bat
or, if -ext <ext> is applied:
<EntireX-installation>\bin\RPCService_<ext>.bat
-serverlog
We recommend that you do not change the name of this file.

Default: CSIDL_LOCAL_APPDATA\Software AG\EntireX\RPCservice.log
or, if -ext <ext> is applied:
CSIDL_LOCAL_APPDATA\Software AG\EntireX\RPCservice_<ext>.log

CSIDL_LOCAL_APPDATA is resolved at runtime according Microsoft's policy for user and application repositories. See Windows-specific Folders.
-userid and -password
use these options if your target Broker requires EntireX Security.

These options are obsolete from EntireX versions 8.2 SP1. RPC servers communicate their user ID/password credentials via the server log file if required by EntireX Security. See Running with EntireX Security. The options are still supported for compatibility with earlier versions or if the user ID and password of the RPC service have to be different from those of the RPC server(s). If the user ID and password are applied in this RPC service (and are different from the default), these values take precedence over the credentials that may be supplied by the RPC server(s).

Defaults:
User ID: ERX-USER
Password: PASSWORD

Note:
This service requires the broker.dll. Make sure that when the service is executing under the control of the Windows Service Manager it can access the broker.dll in the standard path definitions or in the EntireX installation directory.

Customizing the Service

You can set the service to start the RPC server automatically or manually.

To customize the service

Go to Control Panel > Administrative Tools > Services and select the service and then Properties.
Set the Startup type as desired or
Start/stop the service as desired.

Removing the Service

To remove the service

In the command line, go to the EntireX bin folder and enter:
```
rpcservice.exe -remove [-ext[ension] <extension>]
```

Tracing for the Windows Service

Use the -trace option with the individual commands.

with -install

The trace option will be stored in the System Registry and tracing will be enabled if the service is started/stopped by the Service Manager. It can only be switched off by removing the service.
With the other commands trace runs as long as the command takes to finish its task.
You can specify a target log file. By default the file is written to the Windows folder for user documents. See Folder for User Documents.

Starting an RPC Server Using the Service

If the startup type for the service is set to automatic, the server will be started when the PC is booted.

To start the server manually

Go to Control Panel > Administrative Tools > Services and select the service, then Properties and choose Start.

Stopping an RPC Server Using the Service

If you selected startup type automatic in the service properties, the server will be stopped by the operating system when the PC is shut down.

To stop the server manually

Use the service, go to Control Panel > Administrative Tools > Services and select the service, then Properties and choose the Stop button.

If you choose to stop the server using the EntireX utilities, the Windows service will change the status from "running" to "stopped" and writes a warning message in the event log that the EntireX server has stopped for an unknown reason.

Running with EntireX Security

Starting an RPC Server running under EntireX Security

To start an RPC server, supply a valid user ID and password to log on to the broker. The ID and password are applied to the configuration of the individual RPC server(s).

Stopping an RPC Server running under EntireX Security;

When you stop an RPC server, the RPC service uses the user ID/password from the credentials provided by the new RPC server(s), if applied. Otherwise user ID and password may be taken from the RPC service installation options (see above).

Note:
Broker command service etbcmd is used to stop the broker. See Broker Command and Information Services. This means that users who can start RPC servers to certain broker services also need access rights to Class=SAG, Server=ETBCIS, Service=*.

Windows-specific Folders

Folder for Application Data

The file system directory that serves as a common repository for application-specific data.

A typical path is C:\Documents and Settings\username\Application Data.

Under Windows 7, this path for the SYSTEM user might resolve to:
"C:\Windows\System32\config\systemprofile\AppData\Local".

Folder for Local (Non-roaming) Application Data

The file system directory that serves as a data repository for local (non-roaming) applications.

A typical path is C:\Documents and Settings\username\Local Settings\Application Data.

Folder for User Documents

The file system directory used to physically store a user's common repository of documents.

A typical path is C:\Documents and Settings\username\My Documents.

See MSDN Library.