Installing BES VisiBroker on IBM zSeries

This document describes procedures for installing either BES VisiBroker on IBM zSeries (s390 31 bit system and zSeries 64 bit system) SuSE Linux operating systems.

Important: For documentation updates, go to http://www.borland.com/techpubs.

Notes:

Preparing for installation

Before installing on IBM zSeries you should:

• check platform requirements
• check system requirements
• check JDK requirements

Platform and system requirements

Before installing BES VisiBroker on IBM zSeries check the platform, system, and JDK requirements. For the latest platform information and system requirements see the BES Installation Guide or go to http://www.borland.com/techpubs/bes/platforms.

JDK requirements

The installation package for IBM zSeries does not ship any version of the Java Development Kit (JDK). For information on Java products for IBM zSeries go to http://www.ibm.com/developerworks/java/jdk.

Important: Before installing on IBM zSeries, you must have an existing JDK (1.4.2 is supported) installed. Make sure to put the JDK bin directory into the path variable.

To check the location of your JDK and the version, use the following syntax:

$which java

/opt/local/bin/java

$java -version

java version "1.4.2"

Installing BES VisiBroker on IBM zSeries

You can install BES VisiBroker from the CD or download the software from the Borland web site:

http://www.borland.com/products/downloads/download_bes.html

Before you install BES VisiBroker, select the installation method:

• If you want to download a version of the product from the Borland web site, go to the web site mentioned above.
• If you are installing from CD, mount the Borland Enterprise Server CD before starting the installation.
• If you want to perform a silent installation using definitions from a properties file, see Invoking silent installation.

1. To install BES VisiBroker from a CD:

   1. Mount the CD-ROM.
   2. The CD splash screen appears after a few moments.
   3. Follow the installation wizard's onscreen instructions. For most options, defaults offered by the installation wizard are acceptable. You can use the Previous button to return to earlier screens and change any information that is incorrect.

   If installing from a downloaded file:

   1. Extract the installer .bin file by untarring the appropriate .tar file:
      • VBE_65_SUSE_S390_Web.tar
      • VBE_65_SUSE_ZSERIES_Web.tar
   2. Go to the directory where you downloaded the installer and invoke the appropriate command to launch the installer:
      • VBE_65_SUSE_S390.bin
      • VBE_65_SUSE_ZSERIES.bin
   3. Follow the installation wizard's onscreen instructions. For most options, defaults offered by the installation wizard are acceptable. You can use the Previous button to return to earlier screens and change any information that is incorrect.
2. License agreement. Installation and use of BES VisiBroker requires acceptance of the license agreement.
3. Choose Install Folder.

   This creates a new installation of BES, or adds components to an existing 6.5 installation.

   Important: You cannot install this version of BES VisiBroker on top of previous releases.

4. Choose Product Components.

   Select from the following product components for each feature set:

   VisiBroker Core. VisiBroker for Java and C++ development tools and server components.

   Documentation. Suite of online documentation.

   Examples. Example applications for Borland Enterprise Server.

   VisiBroker Extended Services. Optional components you purchase for extended VisiBroker functionality.

5. Choose VisiBroker Extended Services. If you chose the option to install the VisiBroker Extended Services you purchased, select from the following extended services:

   VisiNotify. An industrial strength, ORB-level implementation of the OMG Event/Notification Service.

   VisiSecure. A framework for establishing secure connections between clients and servers.

   VisiTime. A complete implementation of the OMG Time Service Specification, Version 1.1.

   VisiTransact. A complete implementation of the OMG transaction management solution for transactions with CORBA applications over the Internet or intranets.

   VisiTelcoLog. An OMG compliant implementation of the OMG Telecom Log Service specification version 1.1.2

6. Choose Install Type. Typical/Custom panel:
   1. Typical. Express install - uses default settings. The installer generates the BES example configuration, which is comprised of different example Partitions, and their supporting services.

      In addition, the typical installation includes the following defaults:

      • Smart Agent port. Also known as the osagent. This port is used by the ORB to communicate with the server. You can use the Management Console to change the Smart Agent port after installation is completed. The default is 14000.
      • Adding the BES bin directory to your PATH variable. The typical installation does not add the BES bin folder to your PATH. To add it, choose the Custom install type.

        Note: If you select the default, you may have to manually add certain components to your environment path.

      • Adding the BES environment variables. The typical installation does not add the BES environment variables to your system environment. If you choose the Custom install type to add the VisiBroker environment variables, the installation sets the BES_LIC_DIR to <install_dir>/var and BES_LIC_DEFAULT_DIR to <install_dir>/license.
   2. Custom. This option allows you to set various installation options, such as:
      • Specifying Smart Agent port to other than default values (see Choose Install Type for the default values).
      • Include bin directory in PATH. The default is "No". To add the directory to your PATH, choose "Yes".
      • Include BES environment variables. The default is "No". To add the BES environment variables to your system environment, choose "Yes". The installation sets the BES_LIC_DIR to <install_dir>/var and BES_LIC_DEFAULT_DIR to <install_dir>/license.
7. Pre-Installation Summary. Review the displayed information before proceeding with the installation. You can click the Previous button to revisit and change any selections you made except your choice for which product to install.
8. To approve your choices and start installing, click the Install button.
9. Registration.
   • To launch the Borland Product Registration Wizard before exiting the installer, choose "Yes" (default) and click Next. The Registration Wizard launches in a separate window. After you dismiss the Registration Wizard, the installer completion panel displays.
   • If you are installing an evaluation or free version of BES VisiBroker, you are not prompted to launch the Registration Wizard. Before using BES VisiBroker, copy the license activation key file you receive by email from Borland to the <install_dir>/license directory. If you did not receive a license activation key file, or if you are reinstalling the software, go to http://www.borland.com/products/downloads/download_bes.html and download a new license key.

   Important: You must register and activate your license in order to use the product. If you have a valid, node-locked license for BES VisiBroker 6.0 on the same machine where you installed BES VisiBroker 6.5, use the lmadm command-line tool to migrate your 6.0 license for use with the newly-installed BES VisiBroker 6.5 software (see Migrating an existing 6.0 license).

   Note: If you want to register and activate your license later, either by running the lmadm executable found in the <install_dir>/bin directory.

10. When the installation completes, to dismiss the installer, click Done.

Install log

The installer generates an install log that is written to the root of the installation directory if you installed BES VisiBroker from CD, or to the folder where the installer file resides if you used a downloaded file to install BES VisiBroker.

The BES VisiBroker install log file is:

<install_dir>/BES_VisiBroker_Edition_InstallLog.xml

The file is an XML formatted log with installation-specific information, such as errors.

Running the installer without a GUI

The installer is capable of running in a text only mode for UNIX systems. You can invoke the installer with a parameter which specifies the UI mode.

To run the installer in text-only mode:

1. Change directories to the folder where the installation executable file is.

   <install_file>.bin -i console

2. When the installer launches, follow the onscreen installation panels.

   The installer will write to stdout and read from stdin. This allows you to telnet from one system to another and run the installer remotely.

Configuring VisiBroker for C++ server, VisiTransact, or VisiNotify license variables

Before running VisiBroker C++ server, VisiTransact, or VisiNotify, you need to set two license environment variables (BES_LIC_DIR and BES_LIC_DEFAULT_DIR). During installation, a shell script is created for you to use for setting these environment variables.

To set the variables:

1. Open a command window.
2. Change directory to <install dir>/bin.
3. Determine the appropriate script for your shell.

   If you are using the Korn or Bourne shell, use the following script to set environment variables:

   vbroker.sh

   If you are using the C shell, use the following script to set environment variables:

   vbroker.csh

4. To run the script automatically when you log in, add a command to your .profile, .cshrc, or .login file.

Using silent installation

Before invoking the silent installation process, you must first create a text file that contains the properties for configuration settings, such as install directory, server name and JDK home. Each property must be listed on its own line, terminated by a carriage return, with no blank spaces at the end of each line and no blank lines at the end of the file. See the Properties file for silent installation section for more information.

After creating the text properties file, save it as <propertiesfile>.txt, where <propertiesfile> is the filename prefix for your properties file. Now you can invoke the silent installation process using the values specified in the properties file(s).

Note: All properties and values are case-sensitive. When specifying directory and file paths, always use a forward slash.

Properties file for silent installation

The properties file is a plain text file, with each property listed on its own line, terminated by a carriage return, with no blank spaces at the end of each line and no blank lines at the end of the file. The properties can appear in any order in the file.

Properties File Contents for Silent Installation

Sample silent installation properties for BES

This example installs BES VisiBroker Edition on non-default agent ports, and installs several VisiBroker Extended Services.

 INSTALLER_UI=silent

 USER_INSTALL_DIR=/opt/Borland/BDP

 USER_SHORTCUTS=/dev/null

 OSAGENT_PORT=14925

 INSTALL_TYPE=VisiBroker

 VISI_SERVICES=VisiNotify,VisiSecure,VisiTime,VisiTransact,VisiTelcoLog

 INSTALL_VISIMGT=NO

 INSTALL_VISIWEB=NO

Invoking silent installation

To invoke the silent installation process using the values specified in the properties file:

1. Open a command-line shell.
2. Download BES VisiBroker for IBM zSeries from the Borland web site.
3. Extract the installer executable from the tar file you downloaded.
4. Go to the directory where you extracted the installer and obtain all permissions, or chmod all, where 777 indicates all, to run the installer.
5. Invoke the silent installation process by entering the following command. Make sure to specify the full path name of the <propertiesfile> file:

   VBE_65_SUSE_S390.bin -f <path to properties file>

   or

   VBE_65_SUSE_ZSERIES.bin -f <path to properties file>

   where <path to properties file> is the full path of the propertiesfile file.

Note: After silent installation is completed, you need to register and activate the license you received for your product. The license may be in the form of an email from Borland listing one or more serial numbers and license keys, or it may be a license key file sent to you in an email from Borland. If you want to register and activate your license by running the lmadmw executable found in the <install_dir>/bin directory.

Licensing and Registration

Before using BES VisiBroker, you need to register and activate the license you received for your product. The license may be in the form of an email from Borland listing one or more serial numbers and license keys, or it may be a license key file sent to you in an email from Borland.

Important: For information on how to license your product, go to http://info.borland.com/devsupport/bdpcommon/faq/6.5/licensing/index.html.

If you have a valid, node-locked license for BES VisiBroker 6.0 installed on the same machine as the newly-installed BES VisiBroker 6.5, use the lmadm command-line tool to migrate your 6.0 license for use with the newly-installed BES VisiBroker 6.5 software (see Migrating an existing 6.0 license).

If you have already received a key file in an email from Borland for a product you purchased online or downloaded for evaluation, or if you downloaded a free version of the product, you can use the registration wizard to apply the key file, or you can copy it to the <install_dir>/license directory and it will be applied automatically when you restart your product.

If you have a serial number and key, you can register and activate your BES VisiBroker product using one of the following registration methods:

• Direct. If your system is connected to the Internet, this is the simplest method. The product registration wizard guides you through all required steps and automatically activates your license for you. For more information, see the Direct registration section.
• Email. You send your registration request via your own email account (from any system), and will receive an activation file via email that you can apply to your installation. For more information, see the Email registration section.
• Web page. Similar to email, except you register by visiting the Borland web site. For more information, see the Web page registration section.
• Telephone. You provide information to a Borland representative, who will send you an activation file by email or mail. For more information, see the Telephone registration section.

Depending on which method you choose, you may be asked to indicate whether you have a Borland Developer Network (BDN) account. If you do not have an account, you will be prompted to create one in the product registration wizard.

If you do not choose the Direct registration method, you will receive an activation file. Simply copy this file into the <install_dir>/license directory and it will be applied automatically when you start your product.

Migrating an existing 6.0 license

To migrate an existing 6.0 node-locked license after installing 6.5:

Direct registration

To use the Borland product registration wizard for Direct registration:

1. Select the Direct registration method in the first wizard screen, and click Next.
2. Indicate whether you have a BDN account, and click Next. If you do not have an account you are prompted to create one in this wizard.
3. If applicable, enter proxy settings for your internet connection.
4. Review the summarized information before clicking Next. The wizard monitors and displays the progress of your registration.
5. When registration is successfully completed, click Next. Then click Finish to close the Wizard.

Email registration

To use the Borland product registration wizard for Email registration:

1. In the first wizard screen, select the Email registration method and click Next.
2. Indicate whether you have a BDN account, and click Next. If you do not have an account you are prompted to create one in this wizard.
3. Review the summarized information before clicking Next.
4. Copy the content of the Email Registration content pane into an email message addressed to reg@borland.com, and click Next.
5. To close the Wizard, click Finish. You will receive a product activation file by email.
6. Copy the activation file into the <install_dir>/license directory, and it will be applied automatically when you start your product.

Web page registration

To use the Borland product registration wizard for Web page registration:

1. In the first wizard screen, select the Web page registration method and click Next.
2. Copy the registration key from the Web Registration step of the wizard, then click Finish to close the Wizard.
3. Start a web browser and open the http://reg.borland.com URL.
4. In the registration web page, enter your BDN account information and click Login. If you do not have an account, click the Create account link (http://reg.borland.com/srs5/new_user.jsp).
5. In the Product Registration web page, enter the Serial Number and the Registration Key (from the registration wizard) and click Continue.
6. Verify the email address to which the activation file will be sent, and click Register. You will receive a product activation file by email.
7. Copy the activation file into the <install_dir>/license directory, and it will be applied automatically when you start your product.

Telephone registration

To use the Borland product registration wizard for Telephone registration:

1. In the first wizard screen, select the Telephone registration method and click Next.
2. From the drop-down list, select the location that is nearest you.
3. Click Next, then click Finish to close the Wizard.
4. Dial the number for assistance by telephone and keep the information in the Phone Registration wizard screen on hand.
5. When you receive your activation file, copy it into the <install_dir>/license directory, and it will be applied automatically when you start your product.

Uninstalling BES VisiBroker

To uninstall BES VisiBroker:

1. Make sure there are no background processes (such as osagent) running during the uninstall.
2. Change directories to <install_root>/UninstallerData directory.
3. Enter the uninstall command:

   uninstall

   Note: This does not remove files and folders that were created after the installation.

4. After you run the uninstall command, check the installation directory and remove any unnecessary files and subdirectories.