Getting Started-JetNet


Lesson 1 . Setting Up the Server

The first step in preparing the three-tier Panther software environment for JetNet and Oracle Tuxedo applications is to set up the application server. This includes creating the directory where you run the tutorial, populating it with the appropriate files, setting some environment variables, copying or linking to the server executables, and then starting the application.

In this lesson you learn how to:

A Panther application server can run either on UNIX or Windows; instructions are given for both.


UNIX Application Server

If you are setting up the server on UNIX, it is assumed that you are running under either the Korn or Bourne shell.

Before beginning this lesson, you need to know the following:

Create an application directory

For the tutorial, it is recommended that you create the application directory as a local directory under your home directory. You will work in that directory, copying all the necessary files for the tutorial application to that location. In practice, the application directory is located in a central location that is accessible to the development team.

  1. Log onto your application server machine.
  2. Create an application directory. For the purposes of this tutorial, create the directory in your home directory and call it proltut. At the command line, type:mkdir proltut
  3. Change to the proltut directory:
    cd proltut
  4. Copy the file setup.sh from the Panther server installation's config directory to the proltut directory. This file contains environment setup information that is required by Panther, such as path names and terminal information. Usually, a copy of this file resides in the application directory and in each developer's working directory.
    cp ProInstallDir/config/setup.sh .

    where ProInstallDir is the full pathname to the Panther application server installation (which you noted on page 1-2). It is /usr/prolifics by default.

Edit the environment setup file

You set the Panther environment on a UNIX server with the setup.sh file. Edit your copy of this file to include information needed by Panther such as location of the installation and license file.

  1. Open up the setup.sh file using an editor. Make the following changes:
  2. Save and close the setup.sh file.
  3. At the command line, type:
    . ./setup.sh

    This applies the settings in setup.sh.

Get new application components

The Panther newapp directory contains three standard application libraries and three server environment files; all must be copied to the proltut directory. The libraries will include all components used by the application such as screens and menus. The three environment files provide environment settings for Panther servers.

  1. Copy all files from the Panther newapp directory to the application directory (proltut):
    cp $SMBASE/samples/newapp/* .

    This copies the libraries ( client.lib, server.lib, common.lib ) and the server environment files (progserv.env, proserv.env, machine.env) to the proltut directory.

More About Libraries

All Panther application components such as screens and menus reside in libraries. The three standard application libraries listed below are installed with Panther software; you can add other libraries to your application as needed.

Get tutorial components

The Panther tutorial directory includes a tutorial-specific library and the JDB database vidsales. (JDB is a single-user SQL database provided with Panther; it is described in Lesson 6.) You need to copy these to the application directory.

  1. Copy all files from the tutorial directory to your proltut directory.
    cp $SMBASE/samples/tutorial/* .

    This copies the tutorial library (tutorial.lib) and the JDB database (vidsales) to the proltut directory.

Define the server environment

In the tutorial, you run executables that are associated with two server types: proserv for standard servers, and devserv for file access servers. When these servers are activated, they read the environment files proserv.env and/or machine.env.

Edit the environment files (use any ASCII text editor such as vi) so that each server can find the Panther installation and knows which libraries to open.

  1. Open up the machine.env file and edit the following:
  2. Save and close the file.

Link to the server executables

You need to create local links in the proltut directory to the server executables provided with Panther. These executables are located in the distributed util directory.

  1. At the command line, type:
    ln -s $SMBASE/util/proserv .

    This creates a symbolic link to the server executable proserv, which runs a standard server.

  2. At the command line, type:
    ln -s $SMBASE/util/devserv .

    This creates a symbolic link to the server executable devserv, which runs a file access server.

More About Panther Servers

Panther supports three types of application servers to handle requests from clients:

For more information about servers, refer to the JetNet/Oracle Tuxedo Guide.

A configuration file is required for Panther's middleware, JetNet, which manages communication between clients and servers. You create this file through JetMan, the JetNet manager.

Note: In the Oracle Tuxedo version, JetNet configuration files can be used with— and are accessible to—all Oracle Tuxedo utilities, including xtuxadm. Thus, you can use the JetNet manager to create a configuration file, then edit and enhance it for use with Oracle Tuxedo later on. The alternative option is to use Oracle Tuxedo's own configuration files; in which case you would not use JetNet at all.

  1. Start up the JetNet manager in the same window where you set the tutorial environment:
    jetman

    The opening screen of the JetNet manager displays:

Create a middleware configuration file

JetMan integrates all the facilities you need to configure and manage the middle ware component of a Panther application. With it, you create and edit a binary Jet Net configuration file—by default, broker.bin—in the current directory.

  1. Choose FileNewApplication.

    JetMan displays the Application Configuration dialog:

Name the application

All components of a Panther application—servers, clients, and services—are identified to your system through the name that you enter in the configuration file's Application Name property.

  1. In the Application Name property, enter Tutorial as the name of your application. Leave all other properties unchanged.
  2. Choose Next. The JetNet manager displays the Machine Configuration dialog, where you can configure the server machine properties as desired.

Get the machine's name and configuration file

The Machine Configuration dialog contains two properties that you use later to set the environment variables SMRBHOST and SMRBCONFIG:

  1. The Name property is set to the host machine—that is, the machine that is running the JetNet manager. Make a note of the Name property (listed under General Information) for later reference:
    Host Machine Name:_______________________________
    (SMRBHOST)
  2. The Local JetNet Configuration File property contains the name and location of the new application's configuration file:
    appDirectory/proltut/broker.bin. 

    Make a note of this property setting for later reference:

    Local JetNet Config File:________________________
    (SMRBCONFIG)

Get the machine's port number

It is likely that you use your own workstation to develop applications and to run JetNet manager for most application configuration tasks. In both cases, a workstation establishes a client connection to the server machine via the machine's name and workstation listener port.

You obtained the host machine's name in the previous section; now get the value of its workstation listener port, which you use later to set the client environment variable SMRBPORT.

  1. From the Machine Configuration dialog, choose the Networking push button.

    The Machine Networking dialog displays:

  2. Select the Workstation Listener check box.on page 1-11
  3. Copy the Listener Port number (under the Workstation Connections section).
    Listener Port:____________________________
    (SMRBPORT)
  4. Choose OK to return to the Machine Configuration dialog.
  5. Choose Done to save the new configuration file.

    It takes a few moments as the JetNet manager creates a configuration file for the Tutorial application.

  6. When it completes, choose FileExit, and choose Yes to the closing message.

Provide the configuration file's location

The name and location of the configuration file broker.bin must be defined in the server environment through the SMRBCONFIG variable:

  1. Set the SMRBCONFIG variable:

    Edit setup.sh to include and export the location of broker.bin. Add the variable and the value for SMRBCONFIG exactly as it is displayed in the JetNet manager (as you recorded in step 22).

    SMRBCONFIG=appDirectory/proltut/broker.bin
    export SMRBCONFIG

    Save and close the file.

    Note: The value in SMRBCONFIG must match the value in JetMan. If your home directory is a symbolic link to another disk location, the disk location that appears in JetMan must be entered, not the value displayed with the UNIX command pwd.

Boot the application

Now you can start your application with the JetNet manager. Run the following utility each time you want to start up your Panther application. Make sure you are in the Tutorial application directory (proltut) and follow these steps:on page 1-15

  1. From the server command line, reestablish the environment that the Tutorial application requires by entering this command:
    . setup.sh
  2. Enter this command:
    jetman

    The Application Status dialog opens.

  3. If Application "Tutorial" is not already highlighted, select it by choosing FileSelect Application.
  4. Choose EditActivate from the menu bar.

    This starts the application. The status window indicates success or failure for each attempt to activate an application server. A successful boot of all servers starts your Panther application.

    Note: If you have problems starting the application, refer to Appendix B on page B-1. Before trying to restart the application, first shut it down by selecting the Application item from the hierarchy list and choosing EditDeactivate. This shuts down all components of the Panther application, including any active servers.

Connect to the application

To view all components of an active application, you must connect to the JetNet manager as a client. If your user name is set in your environment, the connection window displays it.

  1. Enter your user name, if it is not already entered, and choose OK.

    The information required by the Connect dialog differs for native and workstation clients:

More About Panther Utilities

Instead if using the Jet Net manager to create and manage an application, you can use one of several utilities to perform basic tasks:

If you take a break

Whenever you are done using the application—at the end of the day or for an extended break—remember to shut down the application. This is good practice, since it frees up system resources that others might require.

  1. Select the Application item from the Application Hierarchy list and choose EditDeactivate from the menu bar on the Deactivate button from the toolbar.

    This shuts down all components of the Panther application, including any active servers.

To resume the tutorial

When you want to resume the tutorial (or run your application), repeat the following procedures (described in Steps 27 through 31 above):

To continue the tutorial

To skip to the Lesson 1 summary, refer to page 1-29.



Windows Application Server

Before beginning this lesson, you need to know the following:

Create an application directory

For the tutorial, it is recommended that you create the application directory as a new folder under your root directory. You will work in that directory, copying all the necessary files for the tutorial application to that location. In practice, the application directory is located in a central location that is accessible to the development team.

  1. Create an application directory. For the purposes of this tutorial, create a new folder in the root directory (for example C:\) and name it proltut.

Get new application components

The Panther newapp directory contains three standard application libraries and three server environment files; all must be copied to the proltut directory. The libraries will include all components used by the application such as screens and menus. The three environment files provide environment settings for Panther servers.

  1. Copy all files from the C:\Prolifics\Panther\Samples\newapp directory to the application directory (C:\proltut). This copies the standard application libraries (client.lib, server.lib, common.lib) and the server environment files (progserv.env, pros erv.env, machine.env) to the proltut directory.

More About Libraries

All Panther application components such as screens and menus reside in libraries. The three standard application libraries listed below are installed with Panther software; you can add other libraries to your application as needed.

Get tutorial components

The Panther tutorial directory includes a tutorial-specific library and the JDB data base vidsales. (JDB is a single-user SQL database provided with Panther; it is described in Lesson 6.) You need to copy these to the application directory.

  1. Copy all files from the C:\Prolifics\Panther\Samples\Tutorial directory to your C:\proltut directory.

    This copies the tutorial library (tutorial.lib), the JDB database (vidsales), and two initialization files to the proltut directory.

Define the server environment

In the tutorial, you run executables that are associated with two server types: proserv.exe for standard servers, and devserv.exe for file access servers. When these servers are activated, they read the environment files proserv.env and/or machine.env.

Edit the environment files (use any ASCII text editor such as Notepad) so that each server can find the Panther installation and knows which libraries to open.

  1. Edit the SMBASE setting in the machine.env file. It should be set to the Panther installation directory (as noted on page 1-16 ).
  2. Check the location of the license.dat file. If it is not in the default directory ($SMBASE\licenses\license.dat), set LM_LICENSE_FILE to the license file's full path name (as noted on page 1-16 ).

Copy the server executables

In order for your server executables to be able to read the application's settings in the environment files, you need to copy the server executables from Panther's util directory to the tutorial's application directory.

  1. Copy proserv.exe and devserv.exe from the C:\Prolifics\Panther\util directory to the application directory (C:\proltut).

More About Panther Servers

Panther supports three types of application servers to handle requests from clients:

Start the JetNet manager

A configuration file is required for Panther's middleware, JetNet, which manages communication between clients and servers. You create this file through JetMan, the JetNet manager.

Note: In the Oracle Tuxedo version, JetNet configuration files can be used with—and are accessible to—all Oracle Tuxedo utilities, including xtuxadm. Thus, you can use the JetNet manager to create a configuration file, then edit and enhance it for use with Oracle Tuxedo later on. The alternative option is to use Oracle Tuxedo's own configuration files; in which case you would not use JetNet at all.

  1. Start up the JetNet manager from the Start Menu by choosing ProgramsPanther Application ServerUtilitiesLocal JetMan.

    The opening screen of the JetNet manager displays:

Create a middleware configuration file

JetMan integrates all the facilities you need to configure and manage the middleware component of a Panther application. With it, you create and edit a binary Jet Net configuration file—by default, broker.bin, in the current directory.

  1. Choose FileNewApplication.

    JetMan displays the Application Configuration dialog.

Name the application

All components of a Panther application—servers, clients, and services—are identified to your system through the name that you enter in the configuration file's Application Name property:

  1. In the Application Name property, enter Tutorial as the name of your application. Leave all other properties unchanged.

  2. Choose Next. The JetNet manager displays the Machine Configuration dialog, where you can configure the server machine properties as desired.

Get the machine's name and configuration file

The Machine Configuration dialog contains two properties that you use later to set environment variables SMRBHOST and SMRBCONFIG:

  1. The Name property is set to the host machine—that is, the machine that is running the JetNet manager. Make a note of the Name property (listed under General Information) for later reference:
    Name:_____________________________________________
    (SMRBHOST)
  2. Change the Application Directory setting to the tutorial's application directory (C:\proltut).
  3. The Local JetNet Configuration File property contains the name and location of the new application's configuration file. Change this line to specify a path to broker.bin in the proltut directory (for example, C:\proltut\broker.bin). Make a note of this property setting for later reference:
    Local JetNet Configuration File:________________________
    (SMRBCONFIG)
  4. The Machine Environment Variable File contains the name and location of the machine configuration file to use for the application. Change this line to specify a path to machine.env in the proltut directory (for example, C:\proltut\machine.env).

Get the machine's port number

It is likely that you use your own workstation, not the server machine, to develop applications and to run JetNet manager for most application configuration tasks. In both cases, a workstation establishes a client connection to the server machine via the machine's name and workstation listener port.

You obtained the host machine's name in the previous section; now get the value of its workstation listener port, which you use later to set the client environment variable SMRBPORT.

  1. From the Machine Configuration dialog, choose the Networking push button.

    The Machine Networking dialog displays:

  2. Select the Workstation Listener check box.
  3. Copy the Port number (under the Workstation Connections section).
    Port:____________________________
    (SMRBPORT)
  4. Return to the Machine Configuration dialog by choosing OK.
  5. Save the new configuration file by pressing Done.

    It takes a few moments as the JetNet manager creates a configuration file for the Tutorial application and displays its components in the Application Status dialog:

  6. When it completes, choose FileExit.

Provide the configuration file's location

The name and location of the configuration file broker.bin must be defined in the server environment through the SMRBCONFIG variable.

  1. Set the SMRBCONFIG variable:

    Open up the file jetman32.ini in the Windows directory (C:\WINDOWS). Add the variable and the value for SMRBCONFIG exactly as it is shown in the JetNet manager (as you recorded above in Step 17).

    SMRBCONFIG=C:\proltut\broker.bin

    Note: If your Windows server is running a production application and you cannot change SMRBCONFIG in jetman32.ini, you can use the Select Application option within JetMan.

Boot the application

Now you can start your application with the JetNet manager. Run the following utility each time you want to start up your Panther application.

  1. Start JetMan.
  2. If Application "Tutorial" is not displayed, choose FileSelect Application. Browse to the \proltut\ directory, highlight broker.bin, and choose Open.
  3. If Application "Tutorial" is not already highlighted, select it in the Application Hierarchy list.

More About JetNet Manager

If you run the JetNet manager from a native client (one that runs on the same machine as the server), the dialog displays the application but shows incomplete information about its components, as shown above. If you run the utility from a workstation client (one that runs on a different machine from the server), the dialog is initially empty.

  1. Choose EditActivate from the menu bar on the Activate button from the toolbar.

    This starts the application. The status window indicates success or failure for each attempt to activate an application server. A successful boot of all servers starts your Panther application.

    Note: If you have problems starting the application, refer to Appendix B on page B-1. Before trying to restart the application, first shut it down by selecting the Application item from the hierarchy list and choosing EditDeactivate. This shuts down all components of the Panther application, including any active servers.

More About Panther Utilities

Instead if using the Jet Net manager to create and manage an application, you can use one of several utilities to perform basic tasks:

Connect to the application

To view all components of an active application, you must connect to the JetNet manager as a client. If your user name is set in your environment, the connection window displays it.

  1. Enter your user name, if it is not already entered, and choose OK.

    The information required by the Connect dialog differs for native and workstation clients:

If you take a break

Whenever you are done using the application—at the end of the day or for an extended break—remember to shut down the application. This is good practice, since it frees up system resources that others might require.

  1. Select the Application item from the Application Hierarchy list and choose EditDeactivate from the menu bar on the Deactivate button from the toolbar.

    This shuts down all components of the Panther application, including any active servers.

To resume the tutorial

When you want to resume the tutorial (or run your application), repeat the following procedures (described in Steps 22 through 26 above):

What did you do?

In this lesson, you performed these tasks:

What did you learn?

You learned: