EntireX	Version 9.7	SEARCH   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

This document covers the following topics:

• Assembly Versioning

• Client Configuration

• Server Configuration

Most applications require some configuration parameters that represent durable applications or user preferences.

The .NET framework includes configuration functionality that loads an application's configuration automatically at runtime without programmer intervention. For a standalone application, named, for example, myapp.exe you must name the configuration file (containing configuration settings in a given XML format) myapp.exe.config. The framework will then be able to load and parse the configuration file automatically when myapp.exe is run. For an ASP.NET Web application the configuration file is named web.config.

Assembly Versioning

.NET Framework assemblies support a strong versioning concept. The specific version of an assembly and the versions of dependent assemblies are recorded in the assembly's manifest. The versions of the dependent assemblies to be loaded at runtime are determined depending on the version policy in effect.

The default version policy is that applications run only with the exact versions of dependent assemblies they were built with. Thus applications that are deployed together with their dependent assemblies are not affected by newer or older versions of some of these assemblies. However, it is sometimes desirable to update an assembly with a newer version. In order to make this possible, the default version policy can be overridden by explicit version policies specified in configuration files, for example, the application configuration file (<appname>.exe.config or web.config for Web applications), the computer's machine configuration file (machine.config) or a publisher's policy file.

The following example shows a configuration file fragment that, when placed in a standalone application's <appname>.exe.config file or a Web application's web.config file or in the machine.config file, directs the .NET runtime loader to load version 9.7.0.n of the .NET Wrapper runtime whenever earlier versions in the range 7.1.1.0-7.2.1.73 are required.

<runtime>
  <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
    <dependentAssembly>
      <assemblyIdentity name="SoftwareAG.EntireX.NETWrapper.Runtime"
publicKeyToken="645917c53ee5c617" />
      <bindingRedirect oldVersion="7.1.1.0-7.2.1.73" newVersion="9.7.0.n" />
      <codeBase version="9.7.0.n"
      href="file:///C:\SoftwareAG\EntireX\bin\SoftwareAG.EntireX.NETWrapper.Runtime.dll"/>
    </dependentAssembly>
  </assemblyBinding>
</runtime>

Note:
The runtime configuration fragment must come after the configSections and appSettings sections of the configuration file, otherwise the .NET runtime will report errors.

See also the Microsoft .NET Framework documentation on assembly versioning.

Client Configuration

The .NET Wrapper Runtime supports the .NET framework configuration mechanism for several EntireX Broker and (RPC) Service class properties. By making use of this configuration mechanism, .NET Wrapper client applications can avoid constructing Broker and Service objects explicitly and leave this task to the .NET Wrapper Runtime.

There is one section group named EntireX with the two sections Broker and Service where you can specify the settings for EntireX .NET Wrapper Broker and Service class instances respectively.

Example

    <sectionGroup name="EntireX">  <!-- EntireX Configuration Section Group Definition -->
      <section name="Broker"  type="System.Configuration.NameValueSectionHandler" />
      <section name="Service" type="System.Configuration.NameValueSectionHandler" />
    </sectionGroup>

For an ASP.NET web.config configuration file, the parameters of the NameValueSectionHandler that processes the configuration must be specified in more detail.

<sectionGroup name="EntireX">
  <section name="Broker"  type="System.Configuration.NameValueSectionHandler,
    System,Version=2.0.0.0,Culture=neutral,PublicKeyToken=b77a5c561934e089,Custom=null" />
  <section name="Service" type="System.Configuration.NameValueSectionHandler,
    System,Version=2.0.0.0,Culture=neutral,PublicKeyToken=b77a5c561934e089,Custom=null" />
</sectionGroup>

Broker Configuration Section

If the default constructor Broker() is used to construct a Broker object, i.e. if there is no Broker name (or Broker ID) supplied, then the application's configuration file is examined for configuration settings to be taken as values. If no entry is found for a given setting name, the default values listed in the table below will apply.

The following can be configured for Broker instances:

Broker Configuration Example

<Broker>
  <!-- EntireX Broker Configuration -->
  <add key="name"                    value="localhost:1971" />
  <add key="userID"                  value="NET-USER" />
  <add key="password"                value="NET-PASS" />
  <add key="compression"             value="NO_COMPRESSION" />
  <add key="encryptionLevel"         value="0" />
  <add key="forceLogon"              value="false" />
  <add key="token"                   value="top secret" />
 </Broker>

Service Configuration Section

If the default constructor Service() is used to construct a Service object, i.e. there is no Service name (class/server/service) supplied, then the application's configuration file is examined for configuration settings to be taken as values. If no entry is found for a given setting name, then the default values apply as listed below.

The following can be configured for Service instances.

Service Configuration Example

<Service>
  <!-- EntireX Service Configuration -->
  <add key="name"                    value="RPC/SRV1/CALLNAT" />
  <add key="libraryName"             value="" />
  <add key="naturalLogon"            value="false" />
</Service>

An Example Configuration File

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <sectionGroup name="EntireX">  <!-- EntireX Configuration Section Group Definition -->
      <section name="Broker"  type="System.Configuration.NameValueSectionHandler" />
      <section name="Service" type="System.Configuration.NameValueSectionHandler" />
    </sectionGroup>
  </configSections>
  <EntireX>
    <!-- EntireX Configuration Section -->
    <Broker>
      <!-- EntireX Broker Configuration -->
      <add key="name"                    value="localhost:1971" />
      <add key="userID"                  value="NET-USER" />
      <add key="password"                value="NET-PASS" />
      <add key="compression"             value="NO_COMPRESSION" />
      <add key="encryptionLevel"         value="0" />
      <add key="forceLogon"              value="false" />
      <add key="token"                   value="top secret" />
    </Broker>
    <Service>
      <!-- EntireX Service Configuration -->
      <add key="name"                    value="RPC/SRV1/CALLNAT" />
      <add key="libraryName"             value="" />
      <add key="naturalLogon"            value="false" />
    </Service>
  </EntireX>
  <appSettings>
    <!-- other app settings go here -->
  </appSettings>
</configuration>

Server Configuration

This section covers the following topics:

• Prerequisites

• Starting the RPC Server

• Stopping the Server

• Configuring the EntireX RPC Server for use with the .NET Wrapper

• Configuring the EntireX RPC Server for use with the .NET Framework

See also Administering the EntireX RPC Server.

Prerequisites

The requirements for the .NET RPC Server are:

• the EntireX RPC Server (rpcserver.exe), dotNetServer.dll and dotNetServer.cfg from the EntireX bin directory

• Software AG's .NET Wrapper (SoftwareAG.EntireX.NETWrapper.Runtime.dll)

• a .NET Server DLL (Assembly).

Starting the RPC Server

Before starting the EntireX RPC server, ensure that all dynamically loaded objects (server stubs and server) can be accessed using the search path.

To start the EntireX RPC server manually

• Use the format

  RPCserver CFG=<name> [-option] [Brokerid] [Class] [ServerName] [Service]

  where <name> determines the configuration file in use.

  Options:

  • -smhport number
    Sets the RPC server parameter smhport to number. Typically used by SMH Facility.

  • -serverlog <file>
    Defines an alternative log file for Window services. Typically used by Windows Services. See Running an EntireX RPC Server as a Windows Service in the Windows administration documentation.

  • -s[ilent]: Run server in silent mode, that is: no terminal input will be required (e.g. acknowledge error messages). The job will terminate automatically. Recommended for background jobs.

  • -TraceDestination <file>
    Set the trace destination parameter.

  • -TraceLevel None.Standard.Advanced. Set the trace level parameter.

  Note:
  The server input arguments will be resolved from left to right. Thus parameters that can be applied on the command line as well in the configuration file may be overriden.

To start the EntireX RPC server using Windows services

• See Running an EntireX RPC Server as a Windows Service in the Windows administration documentation.

Note:
For reasons of compatibility with versions before 5.1.1, the old command to start the server

RPCserver <Brokerid> <Class> <ServerName> <Service>

will continue to be supported. However, a server started with this call will use the default parameters. Parameters other than Broker ID, Class, ServerName, Service require the CFG= form of the server start command.

To start the EntireX RPC server using System Mangagement Hub

1. See Administering the EntireX RPC Servers using System Management Hub under UNIX | Windows for information on adding an EntireX RPC server to the System Management Hub.

2. The System Management Hub facility "Adding a Local RPC Server" will use the batch script startcserver.bat of the EntireX Installation to apply the server parameters. Change the batch script according to your system installation or add parameters to the System Management Hub "Start Command" input property.

Stopping the Server

To stop the EntireX RPC server

• Use one of the System Management Hub functions Deregister a Service or Deregister a Server. This method ensures that the deregistration from the Broker will be complete and correct.

  See also EntireX RPC Server Return Codes.

A file that corresponds to dotNetServer.cfg must be used as configuration file (configuration of the EntireX RPC Server for use with the .NET Wrapper). The .NET Server Assembly (containing one IDL library) will then be loaded when a program from this library is first accessed. With the .NET Framework there are two distinct ways to locate the .NET Server Assembly:

1. If the rpcserver.exe, our .NET Wrapper and the .NET Server Assembly are all in the same directory, the .NET Server Assembly will also be loaded from this directory.

2. If rpcserver.exe, our .NET Wrapper and the .NET Server Assembly are in different libraries, the rpcserver.exe must be configured in the context of the .NET Framework (Configuring the EntireX RPC Server for the .NET Framework). The Server Assembly must also have a strong name. This is described in the Microsoft documentation for the .NET Framework (in our example server in EntireXDir\Examples\NET Wrapper\server\calc the Server Assembly has a strong name and in Configuring the EntireX RPC Server for use with the .NET Framework).

Whereas method 1 is very well suited for test and development purposes, method 2 is to be recommended for more complex production environments. The user can decide which method to use.

Configuring the EntireX RPC Server for use with the .NET Wrapper

For the EntireX RPC Server to function with the .NET Wrapper properly, the file dotNetServer.cfg from the installation or a similar file, should be used. The entries

• Class=RPC

• ServerName=dotNetServer

• Service=CALLNAT

• CallExit=dotNetServer

• RunOption=Reset

should not be changed or deleted. No other run options should be added. All of the other settings for the configuration of an EntireX RPC Server are available. See Administering the EntireX RPC Server.

Note:
Any server name can be used. However, we recommend using the name dotNetServer to distinguish this one from any other RPC servers.

Configuring the EntireX RPC Server for use with the .NET Framework

Due to an incompatibility of the .NET Framework 2.0 to the earlier versions, we had to add an additional section in the configSections part of rpcserver.exe.config:

<configSections>
  <!-- EntireX Configuration Section Group Definition -->
  <sectionGroup name="EntireX">
    <section name="Assemblies" type="System.Configuration.NameValueSectionHandler, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089, Custom=null" />
  </sectionGroup>
</configSections>
<EntireX>
  <!-- EntireX Assembly Configuration -->
  <Assemblies>
    <add key="SoftwareAG.EntireX.NETWrapper.Runtime" value="C:\SoftwareAG\EntireX\bin\SoftwareAG.EntireX.NETWrapper.Runtime.dll" />
  </Assemblies>
</EntireX>

where the location of our .NET Runtime is replaced by the location used in your EntireX installation. Add an entry in the Assemblies section for each of your server assemblies:

<add key="MyAssembly", value="MyLocation"/>

where MyAssembly and MyLocation represent the name and location of your server assembly. If versioning is required for your assemblies, follow the rules under Assembly Versioning.

www.softwareag.com

Copyright © 1997-2014 Software AG, Darmstadt, Germany.

SEARCH   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT