Post-installation Steps under Windows

Under UNIX and Windows, EntireX is now installed using the Software AG Installer, which you download from the Software AG Empower website at Empower. You can view the documentation for the Software AG Installer under Cross-Product Guides > Software AG Installer and Update Manager Using the Software AG Installer> in the Software AG Documentation. Alternatively, you can install and configure EntireX using Command Central; see Installing EntireX using Command Central.

This document assumes you have already installed EntireX using the Software AG Installer. It covers installation instructions for components not included in the Software AG Installer; instruction on how to verify the installation and set up EntireX Security. It covers the following topics:

See also General Installation Information for topics that apply to multiple operating systems.


Broker Instance Created Automatically during Installation

If check box Turn on Autostart for default EntireX Broker is checked, the installation starts the default broker ETB001. This broker instance listens on the TCP/IP port defined in the custom panel during installation. Default port numbers are 1971 (TCP/IP) and 1958 (SSL), but only the TCP/IP port is enabled by default.

Start of instruction setTo change the default port of the default broker

  1. Stop the broker, using one of the following methods:

    • Use Command Central to stop the broker. See Administering EntireX Components with Command Central or the separate Command Central documentation and online help for details.

    • Use the Windows start menu entry Software AG > Stop Servers > Stop EntireX Default Broker.

  2. Edit the configuration file, using one of the following methods:

    • Use Command Central to change. See Configuring a Broker Instance > Ports using the Command Central GUI | Command Line.

    • Edit the broker attribute file config/etb/ETB001/ETB001.atr and change the TCP/IP and SSL port numbers to a different value.

  3. Start the broker, using one of the following methods:

    • Use Command Central to start the broker. See Administering EntireX Components with Command Central or the separate Command Central documentation and online help for details.

    • Use the Windows start menu entry Software AG > Start Servers > Start EntireX Default Broker.

Startup Service for Broker Administration

When installation is complete, the Windows service sagexxbrokeradmin10.8_<installation id> is running and ready to be used by etbsrv script located in directory <Installation_Dir>/EntireX/bin. This script can be used, for example, to start or stop the broker.

Eclipse Considerations

Eclipse is an optional component of EntireX. For Software AG Designer, it is required.

If you have not already installed Eclipse at your site, you can install Eclipse and the Software AG Designer from the installation medium. If you wish to install the Software AG Designer into an existing Eclipse environment, use the Eclipse update mechanism to deploy the EntireX feature.

Migrating from one EntireX Version to a Higher Version

When you migrate from one EntireX version to a higher version you have to change the license file setting to the new license file.

Start of instruction setTo set a new license file

  • Go to the Preferences pages in Eclipse (Window > Preferences) and select the page Software AG > EntireX > Installation.

Installing the EntireX Designer Plug-ins in Standalone Mode

If you want to install the EntireX design-time separately, that is, not as part of the full webMethods EntireX installation, see Installing EntireX Design-time outside the Designer.

Verifying the EntireX Broker Installation

The following methods are available to verify successful broker installation:

Start of instruction setTo verify the broker installation

  1. If you have not already created a default broker, create one using Command Central. See Creating a Broker Instance under Administering EntireX Broker using the Command Central GUI.

  2. Start the broker using Command Central. See Starting a Broker Instance under Administering EntireX Broker using the Command Central GUI.

  3. Use one of the following methods to check if the broker is running:

    • Run etbinfo to query the broker for information. Start a Command Prompt session, change your directory to the EntireX bin directory and use the following command:

      etbinfo -blocalhost -dBROKER -pbroker.pro

      This assumes that you use the default port 1971. Otherwise use the command:

      etbinfo -blocalhost:port -dBROKER -pbroker.pro

      where port is the port number of your broker.

      This should display a formatted report with information about the broker. If the broker is not active, you get response 02150148 "EntireX Broker not active".

    • Run the etbcmd utility.

      etbcmd -bETB048 -cPING -dBROKER

      The broker ID is ETB0248. If successful, the message PING broker ETB048 successfully performed is returned. If the broker is not active, you get response 02150148 "EntireX Broker not active".

    • Use the client program bcoc and server program bcos to test broker request and replies.

      • Server
        For the server, start a Command Prompt session, change your directory to the EntireX bin directory and use the following command:

        bcos -i100 -bETB048.
      • Client
        For the client start another Command Prompt session, change your directory also to the EntireX bin directory and use the following command:

         bcoc -i100 -bETB048

        The Broker ID is ETB048 and the number_of_messages is 100. The parameters are described under Sample Programs for Client (bcoc) and Server (bcos).

Sample Programs for Client (bcoc) and Server (bcos)

The programs bcoc and bcos are client and server programs provided for test purposes. They are delivered as executables in the <Install_Dir>\Entirex\bin\ folder.

If the broker is not active, you get 02150148 "EntireX Broker not active".

bcoc Parameters

Parameter Description ACI Field
-alocale locale_string,environment LOCALE-STRING, ENVIRONMENT
-bbroker_id Broker ID (same as the database ID). This is an EntireX Broker configuration parameter. Example:
bcoc -bETB045
BROKER-ID
-cclass Server class (part of the server definition). Default is ACLASS. Value must be configured in the Broker Attributes. Together with server and service it forms the fully qualified server name. SERVER-CLASS
-ginput_file_name Use a file as send buffer.  
-h Display usage information.  
-inum_messages[,num_uows] If num_uows is not specified, the number of messages sent. If num_uows is specified, the number of UOWs and messages therein sent. Example:
bcoc -i10
 
-jreply_error Test REPLY-ERROR.  
-kconversation_flag Using conversational mode.  
-l Silent mode. Suppress output.  
-ntoken Specify the security token, if desired. TOKEN
-pmessage_size The size, in bytes, of the packets that will be transmitted. Used to specify send and receive length in the broker API. Example:
bcoc -p10000
 
-rcompress Compression level. Values: N|Y|0-9. COMPRESSLEVEL
-sserver Name of server. Default is ASERVER. Value must be configured in Broker Attributes. Together with class and service it forms the fully qualified server name. SERVER-NAME
-twait_time Set the wait time. WAIT
-uuser_id User ID. With a secure broker, this will be used to perform authentication. USER-ID
-vservice Name of service (part of the server definition). The default is ASERVICE. Value must be configured in Broker Attributes. Together with class and server it forms the fully qualified server name. SERVER-NAME
-wpassword Password. With a secure broker, this will be used to perform authentication. PASSWORD
-xssl_parms SSL parameters. For example:
-x"TRUST_STORE=..\ExxCACert.pem&VERIFY_SERVER=NO"
See also SSL/TLS Parameters for SSL Clients.
 
-ysleep_time Delay between messages in seconds.  
-zstore[uwstatp[,uowtime]] Test unit of work.  
-1..12 By default, if omitted, the highest possible API version is used. Note that if you specify the API version, certain features might depend on a minimum API version. API-VERSION

bcos Parameters

Most bcoc parameters apply to bcos, too. The following table lists additional parameters or parameters that have a different meaning.

Parameter Description ACI Field
-goutput-file-name Name of output file for receive buffer (if not running in silent mode).  
-inum_messages[,num_uows] If num_uows is not specified, the number of messages accepted. If num_uows is specified, the number of UOWs and messages therein that are accepted before deregistration.
Example: bcos -i10
 
-iunit_of_work_flag Test unit of work.  

Setting up EntireX Security under Windows

This section covers the following topics:

Note:
You must set up EntireX Security for broker kernel and - if your application(s) use API version 7 or below - also for broker stubs.

Setting up EntireX Security for Broker Kernel

Start of instruction setTo set up EntireX Security for broker kernel under Windows

  1. Determine that all prerequisites for EntireX components have been met before setting up EntireX Security. See Windows Prerequisites.

  2. Insert the following statement into the broker-specific section of the attribute file. See Broker-specific Attributes.

    • SECURITY=YES

  3. Modify the security-specific section of the broker attribute file according to your requirements. See Security-specific Attributes. These parameters are used to determine whether you will use Windows local security or LDAP-based authentication.

    Note:
    If you are using LDAP-based authentication, define your authorization rules in LDAP and reference these with Security-specific attribute LDAP-AUTHORIZATION-RULE.

Note:
Authentication: Windows authentication calls LogonUser() with the flag LOGON32_LOGON_INTERACTIVE.

Setting up EntireX Security for Broker Stubs

Note:
If you are running your application(s) at ACI version 7 or below, the following steps are required to install EntireX Security for the Broker stubs in all environments where applications execute either as clients or servers. See Platform Coverage for where EntireX Security for broker stubs is supported.
These steps are not required if you are running your application(s) at ACI version 8 or above.

Start of instruction setTo install EntireX Security for broker stubs on Windows

  • When requested to specify the installation type, choose Custom and check the Security box.

    (The required directories including secuexit.dll are copied to your computer during installation.)

    Notes:

    1. Secuexit.dll is needed for backward compatibility if your applications issue any commands using ACI version 7 or below. Applications using ACI version 8 do not require this additional component in the stub.
    2. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS, HTTP(S), and Certificates with EntireX.
Warning:
If stub tracing level is > 1, unencrypted contents of the send/receive buffers are exposed in the trace.

Installation of EntireX Security for Broker stubs is now complete. Now you can install the security components for the Broker stubs on the remaining operating systems where your application components are located.

EntireX Mini Runtime Considerations

The EntireX Mini Runtime is a set of components that can be used for the deployment of applications using the Broker ACI, the Broker RPC, and - under Windows only - DCOM Wrapper objects and the Broker ActiveX Control. Unlike the full EntireX Runtime, the Mini Runtime does not include Java capabilities. The EntireX Mini Runtime is provided as a separate package in the Software AG Installer.

If you need the EntireX Mini Runtime with your application, you may have to extend the PATH variable to <inst_root>\EntireX\bin before starting your application.

Broker ActiveX Control and TOR Editor

Before you can use the Broker ActiveX Control (file ebx.dll) and/or the TOR Editor (file toredit.exe) you have to register the Broker ActiveX Control as a COM component. Start the program regsvr32 with "Run as Administrator":

regsvr32 <path>\ebx.dll

Files ebx.dll and toredit.exe are located in the <inst_root>\EntireX\bin\x86 directory of the installation.

Note:
Only program ebx.dll needs to be registered as a COM component. See Calling the Transaction Object Editor.