Running an EntireX RPC Server as a Windows Service

This page covers the following topics:

Note:

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


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

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 | Micro Focus | Java | XML/SOAP | IMS Connect | CICS ECI | AS/400 | IBM MQ | RPC-ACI Bridge).

Start of instruction setTo install an RPC Server as a Windows Service

  1. 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.

  2. 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 | Micro Focus | 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 %*

  3. Adapt the corresponding configuration file, for example \EntireX\config\cserver.cfg, to your needs.

  4. 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
  5. 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

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

Start of instruction setTo 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 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 Micro Focus 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 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. 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.

Start of instruction setTo customize the service

  1. Go to Control Panel > Administrative Tools > Services and select the service and then Properties.

  2. Set the Startup type as desired or

  3. Start/stop the service as desired.

Removing the Service

Start of instruction setTo 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.

Start of instruction setTo 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.

Start of instruction setTo 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.

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.