Install-Panther WebSphere

After successfully installing the software, there are several post-installation steps required to start using Panther. This chapter discusses the following topics:

• Licensing

• Building Panther executables

• Setting up the environment for each of the software components installed

• Post-installation issues

• Troubleshooting tips

Post-Installation Overview

As part of post-installation, you need to perform the following general tasks for client and server installations, some of which are based on the architecture of your application. This chapter provides specific steps associated with each general task:

• Creating New Panther Executables

• Obtaining Panther Licensing (A Start-up License is provided; obtain a permanent license file before the Start-up License file expires.)

• Configuring the Application Server Engine

• Configuring the Web Application Broker

• Configuring the Client

• Verifying the Installation

• Reviewing Sample Applications

Creating New Panther Executables

As part of the Panther installation package, a set of standard Panther executables is provided for the client, the application server engine, and the web application broker. Depending on your configuration and on the platform and database being used, you might need to create new executables.

Note: In previous versions of Panther software, you needed to create new executables to link in a different database. Panther WebSphere Edition uses shared libraries for database connectivity. The location of the shared libraries can be changed in the global initialization file.

For more information on creating new client, application server engine, and web application broker executables, refer to Appendix C, "New UNIX Executables."

Obtaining Panther Licensing

The Panther software installation includes a Start-up License that enables you to use Panther (and run Panther applications) immediately. The temporary license, license.dat, is located in the licenses subdirectory of the Panther installation directory. Because the license expires in 45 days, you must contact the Prolifics License Desk during this period to receive your permanent license file. Make your request as soon as possible and return to this chapter when you receive the permanent license file. You can reach the License Desk by fax at (212) 608-6753 or by e-mail at license@prolifics.com.

Obtaining a Permanent License File

You must obtain a permanent license file before the Start-up License expires to continue to develop and run Panther applications. Each development client and each server must have access to a license file.

Note: All development components—clients and servers—require licenses. In a deployed application, the application server engine and the web application broker (if applicable) require licenses, but the client does not.

During installation, the setup program prompted you to provide the License Desk with the appropriate information to obtain your permanent license file. It also generated license request files (*.lcl) in the licenses subdirectory of your Panther installation directory for each component installed on a given machine.

How to Obtain the License File

1. Submit the license request file (for each component on a given machine) to the Prolifics License Desk. The License Desk returns the password-enabled file for each component on a given machine via the requested method (as specified during setup).
2. Install the license file or files.
3. Start the license manager daemon.

   Note: For more information on licensing, refer to Appendix E, "License Administration," and to Appendix F, "License File," for a description of the contents of a license file.

Each component you install on a machine—Panther client (prodev), application server engine (proserv), and web application broker (proweb)—receives its own license file (*.lic). Install each password-enabled license file on its appropriate machine and then, via the create_license utility, merge them into a single license.dat for each machine. Follow the directions for the method of receipt.

How to Install a Permanent License File

1. Complete the following step.

   If you received a license file	Then
   Via e-mail	Copy it to the licenses subdirectory on the machine where the software is installed. Go to Step 3.
   Via fax or mail	Copy the license request file, .lcl, to .lic. Go to Step 2.

2. Update the copy of the license file (*.lic file) with the information you received (via fax or mail).

   Replace text in angle brackets (and the angle brackets) with the corresponding information provided on the Feature line. For example, replace <number of tokens> and <password> with the appropriate information from the password-enabled license file.

   Repeat Steps 2 and 3 for each license file you received for this machine.

3. Create the license.dat:

   From the licenses directory, type:

   ./create_license

   All .lic files for the machine are merged into a single license.dat file in the licenses directory and the Start-up License is saved as license.bak.

   Note: After installing the license, if your environment has set LM_LICENSE_FILE, you need to unset it as follows:

   Bourne or Korn shell: unset LM_LICENSE_FILE

   C Shell: unsetenv LM_LICENSE_FILE

   Or you can explicitly set it to the license file.

Panther searches for the license file in the following order:

• The pathname given by the LMLicenseFile variable in your web application initialization (web only).

• The pathname given by the LM_LICENSE_FILE line in the .ini file (Windows Editor only). See Windows Initialization File for more information.

• The pathname given by the LM_LICENSE_FILE variable.

• license.dat in licenses subdirectory of the Panther installation (recommended location).

• license.da.in one of the directories in SMPATH.

Starting the License Manager

After you create the license.dat file, you can start the license manager for development clients. Make sure that you are using version 5.0 or higher of the license manager daemon, lmgrd.

Note: The Panther application server engine and web application broker use local license files and do not require the license manager daemon. Refer to Appendix E, "License Administration."

How to Determine the Version of lmgrd

• At the command line, type the following.

  $SMBASE\util\lmver lmgrd.exe

How to Start the License Manager

• At the command line, type the following.

  $SMBASE\util\lmgrd -c $SMBASE/licenses/license.dat> log &

  where log is the name of a log file to which output is redirected.

  Starting the license manager does not interfere with another lmgrd that might be running to license another application. However, if you are running lmgrd for previous versions of Panther, you must stop the license daemon using lmdown and restart lmgrd as described, or run lmreread to incorporate new Panther license daemon information.

  Note: It is recommended that you add this command to the system startup scripts file so that the daemon runs automatically when the system is rebooted.

Configuring the Application Server Engine

WebSphere Application Server can be configured to support more than one server process. Each server has a directory specified as its current runtime directory. Panther provides a template initialization file, panther.ini, to be placed in each server directory. The template is located in the config directory of the Panther installation.

Panther.ini has the following sections:

• EJB Global—Specify global settings for the Panther application server engine.

• EJB Class—Specify class settings.

• databases—Specify Panther database drivers installed.

How to Configure the Application Server

The following entries are read once, when the shared library is loaded, and are then global to all WebSphere servers.

• LM_LICENSE_FILE—Specify the name and location of your Panther application server engine license file or license server port.

  Note: Licensing information is required.

• SMINITJPL—Specify JPL file(s) to load at global initialization. The JPL file should consist only of calls to the functions sm_slib_load and sm_slib_install to make user code in shared libraries available.

• SMTPCLIENT—Specify the type to Oracle Tuxedo client when use with Oracle Tuxedo support. Valid values are ws for a Oracle Tuxedo /ws client and native for a Oracle Tuxedo native client. If no value is specified, Oracle Tuxedo client support is not initialized.

• SMTPINIT—Specify the default arguments for the JPL command client_init when used with Oracle Tuxedo support.

• SMTPJIF—Specify the name and location of the JIF file to open on application startup when used with Oracle Tuxedo support.

• SMVARS—Specify the name and location of the setup file containing your Panther application variables. If the location is not specified, the default value is smvars.bin in PantherInstallDir/config.

The following variables provide settings that can be different for each WebSphere server.

• SMBASE—Specify the directory where Panther software is installed.

• SMPATH—Specify a search path for Panther application files.

• SMINITJPL—Specify a JPL file to load upon startup of the Panther application.

• SMMSGS—Specify the file that contains messages and other printable strings. If the location is not specified, msgfile.bin in the installation directory will be the default.

• SMFLIBS—Specify the Panther application libraries to open. The default value is server.lib.

The following variables specify database drivers.

• default—If more than one database driver is installed, specify the name of the default database driver.

• installed—Specify the name(s) of the installed database driver(s). The following table provides the names of the drivers.

  Database driver	Version	Installed=Name of database
  DB2	DB2 Version 6	DB2_6
  Oracle	Oracle Version 8.1.5 using Pro*C	oracle8iProC
  	Oracle Version 8.1.5 using OCI	oracle8iOCI

Configuring the Web Application Broker

To ensure that your Panther application can be viewed on a web browser, complete the following platform-specific steps, most of which were applied as part of the Panther setup program. For further information on configuring web applications, refer to Chapter 2, "Web Application Setup," in Web Development Guide.

How to Configure the Web Application Broker

1. Confirm that the following web application broker executables reside in your HTTP server's CGI, ISAPI, or NSAPI directory; otherwise, copy them from $SMBASE/util.

   • websetup (Panther Web Setup Manager)

   • jwsamp (sample application executable)

2. Confirm that the following web application broker files reside in the document root directory (consult your system administrator for the correct name) used by your HTTP server; otherwise, copy them from $SMBASE/notes.

   • samples.htm (configuration HTML files)

   • server.htm

   • *.gif (graphics files)

3. Confirm that the following initialization file resides in the Panther web initialization directory (/home/proweb/ini); otherwise copy it from $SMBASE/config.

   • jwsamp.ini

4. Check jwsamp.ini in the Panther web initialization directory (/home/pro web/ini) for the correct setting of the following variables:

   • AppDirectory—Full pathname to the Panther samples subdirectory to provide initialization information for the sample web application

   • Dispatcher—Full pathname of the dispatcher program in the util subdirectory of the web installation directory

   • Server—Full pathname of the jserver program in the util subdirectory of the web installation directory

   • SMBASE—Full pathname of the Panther web installation directory

   • PATH—Full pathname to the util subdirectory of the web installation directory

Determine the following:

• Note the location of your HTTP server's program directory (such as /usr/web/cgi-bin) for later reference:

  The http server's program directory is:

  _______________________________________________________

• Check that the Panther Web Setup Manager is installed on your HTTP server and ready to run via a web browser. The default URL location is:

  http://serverName/program_directory/websetup

  Make a note of its location for later reference:

  The Setup Manager is accessed from the following URL:

  _______________________________________________________

Using Two Host Machines

If you are running your Panther web application broker on a machine other than the Panther application server engine, you will need to first recompile the jserver. To do this, follow these steps.

1. Go to the /link/ subdirectory of your Panther web application broker.
2. Using an editor, such as vi or emacs, open up the file makefile.
3. Near the top of the file, in the section regarding which products to build, comment out all products except for the line indicating JSERVER.
4. Toward the end of the file, under Middleware Parameters, set the following parameters.

   RBLIBS=$(RBWSLIBS)
   RBWSCFLAGS=$DWSCLIENT
   #RBLIBS=$(RBNATIVELIBS)

   This builds a workstation client on the remote Panther web application broker.

5. Save and exit this file.
6. At the command line, type make to create the new jserver files.

---

Creating Your Web Application

Panther provides the Panther Web Setup Manager to guide you through configuring your customized web application. For more information, refer to Appendix B, "Web Setup Manager," in the Web Development Guide.

To run the Web Setup Manager, enter the URL recorded above into a web browser.

Configuring the Client

A Panther client provides the development environment required to build two- and three-tier applications. The environment must contain properly set application variables in order to run Panther. To set up the development environment, complete the following platform-specific steps. Refer to Chapter 6, "Preparing the Development Clients," in the Application Development Guide for more details on setting up the client environment.

1. For each client, copy or link the following file in the installation config directory to each developer's home directory:

   • Prolifics—X resource file used by the Panther client. Copy to each user's app-defaults directory (if there is one) or to the user's home directory.

2. The setup shell scripts are useful for setting Panther application variables. The setup program determined values for some of these variables, based on your system's configuration, and modified the scripts accordingly. Review setup.sh (Bourne or Korn shell users) and setup.csh (C shell users) in the application directory (if it exists) or the file $SMBASE/config/setup.sh ($SMBASE/config/setup.csh) to ensure proper settings for the following application variables:

   • SMBASE—Full pathname of the Panther installation directory. The installation recommends /usr/prolifics; therefore, SMBASE would be set to equal /usr/prolifics. If Panther was installed in a different directory, use that directory's name.

   • PATH—Identifies directories to search when looking for executable programs. PATH should include the path to Panther's util directory so that the system can find the development executable (prodev) and Panther utilities. If Panther's util directory is not on the PATH, business graphs and online help will not work.

   • JAVA_HOME and CLASSPATH—These path names are specific to Java files and event handlers and need to be set to the location where your Java classes sit. Additionally, you can change the defaults for SMJAVAEDITOR, SMJAVAFACTORY and SMJAVALIBRARY.

   • SMTERM—Specifies the type/model console the client is using. For Motif, set SMTERM to X.

     If you are running a character mode terminal with Panther, then you need to have appropriate video and key files (which instruct Panther on how to drive your terminal). Panther provides files to support several popular terminal types (which are in turn often emulated by other brands of terminals). Refer to Chapter 7, "Video File," in Configuration Guide for details on video files. Then examine the file $SMBASE/config/smvars. There you should find a setting of SMTERM which meets your needs.

   • LM_LICENSE_FILE—Full pathname of the license file (default location is $SMBASE/licenses/license.dat).

   • LD_LIBRARY_PATH—Identifies directories to search when looking for shared libraries. On AIX, use LIBPATH. LD_LIBRARY_PATH should include the path to the Motif shared library directory.

   • XNLSPATH—Some implementations of Motif require you to set the XNLSPATH application variable before Panther can be successfully used. Check the documentation for your implementation of Motif to see if this is the case for you.

3. You can set SMFLIBS in setup.sh (setup.csh) to point to shared Panther application libraries in the application directory. The default setting opens only local libraries (that is, libraries in the current directory).
4. To automatically set up the environment, execute the setup shell script directly from each user's logon script.

   • Korn or Bourne shell—Append the following line to the .profile:

     applicationDir/setup.sh

     Note: If application variables are set in the user's environment for previous versions of JAM or Panther, they should be removed so that they do not interfere with the setup for this version.

5. If a user's terminal type is different from the value of SMTERM in the setup script, override that value by adding a line to the .profile or .cshrc to set SMTERM correctly. The line should immediately follow the script invocation. For example:

   . /usr/prolifics/config/setup.sh
   SMTERM=vt100

   Alternatively, you can merge the appropriate setup script file into .profile or .cshrc, and modify the value of SMTERM as needed.

   Overriding other application variables for a given user can be implemented in the same way.

---

Verifying the Installation

After you install and configure Panther software, you should verify that Panther starts up properly on client and application server engine machines. If Panther is not installed and configured correctly, an appropriate error message is displayed. Depending on the problem, the program might also terminate. Refer to Appendix G, "Error Messages," for a list of the more common error messages related to system configuration, and how to resolve them.

Client Installation

On a client machine, a correct installation is verified if you can invoke the Panther editor.

How to Verify a UNIX Client Installation

Type prodev at the command line.

Application Server Engine Installation

On the WebSphere Application Server machine, the Panther application server engine is loaded the first time you access a Panther-built EJB. At this time, the EJB Global section of the panther.ini file is initialized.

Web Application Broker Installation

On the Panther web application broker machine, verify the installation by running the Panther Gallery, and verify the configuration by running your own application.

How to Verify the Panther Web Application Broker Installation

Run the Panther Web Gallery:

1. Start the Gallery application by typing the following on the command line in the Panther util directory:

   monitor -start jwsamp

2. Run the Gallery by entering the following URL in your browser:

   http://serverName/program_directory/jwsamp/main

3. Stop the Gallery application by typing the following on the command line in the Panther util directory:

   monitor -stop jwsamp

You can use the following method to verify your web application broker installation:

1. Configure a new application by running the Web Setup Manager.
2. Start the application by typing the following on the command line in the Panther util directory:

   monitor -start applicationName

3. Run the application in your browser:

   http://serverName/program_directory/applicationName

   Note: If you get the message "No Service Requested!" you were successful.

4. Stop the application by typing the following on the command line in the Panther util directory:

   monitor -stop applicationName

---

Reviewing Sample Applications

Before you begin building your applications, you might want to review sample applications. The following sample applications are delivered with Panther:

• EJB Application—Sample EJB applications are provided. For more information on EJB samples, refer to Appendix B, "Sample Applications," in Panther for IBM WebSphere Developer's Studio.

• Panther Web Gallery—Provides several pre-built two- and three-tier sample applications for the web.

  1. Start the Gallery application by typing the following on the command line in the Panther util directory:

     monitor -start jwsamp

  2. Run the Gallery by entering the following URL in your browser:

     http://serverName/program_directory/jwsamp/main

     For example:

     http://myServer/cgi-bin/jwsamp/main

  3. Stop the Gallery application by typing the following on the command line in the Panther util directory:

     monitor -stop jwsamp

Post-Installation Notes

The following additional information might be required to configure and run Panther on your system.

Implementing Character-Mode Utilities

Character-mode specific utilities, mbedit.cm (menu bar editor) and showkey.cm (key translation utility), are provided in the distributed util directory. You may need to use these if you are running Panther using character-mode and your system does not have Motif installed. To ensure that directions and menu options that reference these utilities can be used and accessed, rename the executables:

1. In the util directory, save the Motif versions of the utilities by giving each a new extension to distinguish it from their corresponding character-mode utilities. For example:

   cp mbedit mbedit.xm
   cp showkey showkey.xm

2. Copy the character-mode utilities to the utility name having no extension. For example:

   cp mbedit.cm mbedit
   cp showkey.cm showkey

---

Troubleshooting

The information in this section provides you with guidance should you encounter error messages. The messages you receive may be categorized as follows: license manager, motif version number, graph functionality, or online manuals.

License Manager-Related Messages

If the license manager is not able to process the license file, an appropriate error message is displayed. Appendix G, "Error Messages," lists error messages generated by FLEXlm and hints for resolving them.

If the Panther license server is not running, its clients will not be able to run.

Motif Version Number-Related Messages

From your Motif installation directory, run the following command:

strings libXm.a | grep -i version

Panther's graph capabilities rely upon external programs, therefore, it is possible for Panther to be working properly except for the business graph component. If you have problems with the graph functionality, check the following:

• Ensure that the grafcap file (distributed in the config directory) is located in one of the directories pointed to by SMPATH.

• Ensure that the files gdsp and swsdrvr (distributed in the util directory) can be found along the search PATH for executables (Panther must be able to execute these programs).

Online Manuals-Related Messages

Panther's online manuals are delivered in PDF and HTML formats. To verify that you can access the online documents, view the documents with Adobe Acrobat Reader or a web browser, respectively.

Installed documents are located in the following directory.

4.25:  PantherInstallationDir/docs/websphere4_25/webindex.htm
4.26+: PantherInstallationDir/docs/index.htm

The documents on the Windows documentation CD are located in the following directory.

4.25:  CD-ROMDrive:\Docs\websphere\4_25\webindex.htm
4.26+: CD-ROMDrive:\Docs\index.htm

Note: For more information on the online documentation, refer to Appendix A, "Panther Online Documentation."