This page covers the following topics:
This document describes how to run an EntireX RPC server using a batch script. Since EntireX version 10.1 you can perform this task using Command Central. See
parameter install.service of the Command Central command-line (C | CICS Socket Listener | .NET | IMS Connect | Java | IBM MQ | XML/SOAP)
checkbox Register Windows service for automatic startup of the Command Central GUI (C | CICS Socket Listener | .NET | IMS Connect | Java | IBM MQ | XML/SOAP)
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:
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.
The steps below use the RPC Server for C as an example. In a similar way the information applies to other RPC servers. See Running an EntireX RPC Server as a Windows Service(C | .NET | Java | XML/SOAP | IMS Connect | CICS ECI | AS/400 | IBM MQ | RPC-ACI Bridge).
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 RPC Server for C start script file is referenced.
cserver.bat %*
The file contains entries for various RPC servers. The RPC Server for C is already uncommented, it is the default.
Make sure the referenced start script (cserver.bat for the RPC Server for C) considers the notes given under Running an EntireX RPC Server as a Windows Service(C | .NET | Java | XML/SOAP | IMS Connect | CICS ECI | AS/400 | IBM MQ | RPC-ACI Bridge).
For the RPC Server for C, this is the option -silent and the feature to pass external parameters to the RPC server: rpcserver CFG=..\config\cserver.cfg -s %*
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
Register the Server as a Windows service. Enter:
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 |
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.
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
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 an RPC Server for Java 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 RPC Server for XML/SOAP you can use
-install -ext xml -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 an RPC Server for C 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.
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.
You can set the service to start the RPC server automatically or manually.
To customize the service
Go to > > and select the service and then .
Set the Startup type as desired or
Start/stop the service as desired.
To remove the service
In the command line, go to the EntireX bin folder and enter:
rpcservice.exe -remove [-ext[ension] <extension>]
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.
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 > > and select the service, then and choose .
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 > > and select the service, then and choose the 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.
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).
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=*.
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.
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.
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.