Getting Started-JetNet

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:

• Create an application directory and copy to it the libraries, environment files, and other files needed for the tutorial.

• Edit the environment files used by the server, client, and middleware.

• Copy or link to the server executables.

• Create and boot a Panther application with JetMan, the JetNet manager utility.

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:

• The location of your Panther application server installation. (The default location is /usr/prolifics.)

  Panther is installed at:	______________________

• The location of your license file.
  (The default location is /usr/prolifics/licenses/license.dat.)

  The license location is:	______________________

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.

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.

5. Open up the setup.sh file using an editor. Make the following changes:

   • Note that SMBASE is set to /usr/prolifics by default. If Panther is installed at another location, then set SMBASE to the full path name of the correct directory (as noted on page 1-2).

   • Check the location of the license.dat file. If it is not in the default directory ($SMBASE/licenses/license.dat), set the LM_LICENSE_FILE variable to the license file's full path name (as noted on page 1-2 ). Uncomment this setting and its export line.

   • Uncomment the SMTERM line and set it to the appropriate terminal type. This variable tells Panther what console type and model you are using. For example, if you are running under Motif, set SMTERM=X. If you are running under UNIX in character mode, refer to the Configuration for information on using video files, which tell Panther how to drive the terminal display.

   • Uncomment the shared library path variable setting that is appropriate to your UNIX system. Also uncomment the corresponding export line. For example, for Solaris systems, uncomment these lines:

     LD_LIBRARY_PATH=$SMBASE/lib:$LD_LIBRARY_PATH
     export LD_LIBRARY_PATH

6. Save and close the setup.sh file.
7. At the command line, type:

   . ./setup.sh

   This applies the settings in setup.sh.

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.

8. 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.

• client.lib—client library that contains components of the user interface. such as screens, menus, toolbars, JPL modules (Panther's scripting language) used by the client, a styles file, and images that illustrate push buttons and toolbar items.

• server.lib—server library that contains server components (graphical representations of server functions) and routines; this library is required only for developing and deploying three-tier applications.

• common.lib—common library that contains components needed application-wide by both client and server, such as the JIF (JetNet Interface file) and JPL code.

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.

9. 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.

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.

10. Open up the machine.env file and edit the following:

    • Uncomment SMBASE (remove the # from the beginning of the line) and provide the full path name of the Panther installation (as noted on page 1-2 ) if it is not /usr/prolifics.

      SMBASE=ProInstallDir

    • Uncomment the shared library path variable setting that is appropriate to your UNIX system.

    • Update the license file location if it is not in the default location.

11. Save and close the file.

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.

12. 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.

13. 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:

• Standard servers, which advertise services defined in the JIF (JetNet Interface File, which contains service information used in client/server processing) and perform remote processing of report during runtime.

• Conversion servers, which provide services for three-tier applications that have been converted from a two-tier architecture.

• File access servers, which provide the development team shared access to libraries and repositories across the network, and also provide file transfer services at runtime.

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.

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

    jetman

    The opening screen of the JetNet manager displays:

    

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.

15. Choose FileNewApplication.

    JetMan displays the Application Configuration dialog:

    

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.

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

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

18. 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)

19. 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)

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.

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

    The Machine Networking dialog displays:

    

21. Select the Workstation Listener check box.on page 1-11
22. Copy the Listener Port number (under the Workstation Connections section).

    Listener Port:____________________________
    (SMRBPORT)

23. Choose OK to return to the Machine Configuration dialog.
24. 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.

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

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

26. 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.

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

27. From the server command line, reestablish the environment that the Tutorial application requires by entering this command:

    . setup.sh

28. Enter this command:

    jetman

    The Application Status dialog opens.

    

29. If Application "Tutorial" is not already highlighted, select it by choosing FileSelect Application.
30. 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.

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.

31. 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:

    • The dialog for workstation clients asks for the server machine's host name and port.

    • The dialog for a native client (shown above) asks only for login information.

      Note: In this tutorial, user name and password are not needed; however, a deployed application typically requires, at a minimum, this level of security. You can set a password in the JetNet manager through the application's Application Password property (refer to page 3-12 in JetNet/Oracle Tuxedo Guide).

      All components of the tutorial application now display in the Application Status window.

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:

• rbconfig creates a minimal middleware configuration file (broker.bin) that you can use as a starting point for further development.

• rbboot activates a Panther application.

• rbshutdown deactivates a Panther application.

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.

32. 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.

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

• Establish the environment by running setup.sh.

• Start jetman.

• Select the application, if it is not already highlighted. (If the application is not listed, you need to open the broker.bin file. Choose FileSelect Application.)

• Choose EditActivate.

• Open a middleware connection.

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:

• The location of your Panther application server installation. (The default location is C:\Prolifics\Panther; this is the location referenced in the steps in this tutorial.)

  Panther is installed at:						 	______________________

• The location of your license file. (The default location is C:\Prolifics\Panther\licenses\license.dat.)

  The license location is: 							______________________

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.

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.

2. 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.

• client.lib—client library that contains components of the user interface. such as screens, menus, toolbars, JPL modules (Panther's scripting language) used by the client, a styles file, and images that illustrate push buttons and toolbar items.

• server.lib—server library that contains server components (graphical representations of server functions) and routines; this library is required only for developing and deploying three-tier applications.

• common.lib—common library that contains components needed application-wide by both client and server, such as the JIF (JetNet Interface file) and JPL code.

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.

3. 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.

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.

4. Edit the SMBASE setting in the machine.env file. It should be set to the Panther installation directory (as noted on page 1-16 ).
5. 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 ).

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.

6. 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:

• Standard servers, which advertise services defined in the JIF (JetNet Interface File, which contains service information used in client/server processing) and perform remote processing of report during runtime.

• Conversion servers, which provide services for three-tier applications that have been converted from a two-tier architecture.

• File access servers, which provide the development team shared access to libraries and repositories across the network, and also provide file transfer services at runtime.

• For more information about servers, refer to 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.

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

   The opening screen of the JetNet manager displays:

   

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.

8. Choose FileNewApplication.

   JetMan displays the Application Configuration dialog.

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:

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

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

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

11. 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)

12. Change the Application Directory setting to the tutorial's application directory (C:\proltut).
13. 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)

14. 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).
    

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.

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

    The Machine Networking dialog displays:

    

16. Select the Workstation Listener check box.
17. Copy the Port number (under the Workstation Connections section).

    Port:____________________________
    (SMRBPORT)

18. Return to the Machine Configuration dialog by choosing OK.
19. 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:

    

20. When it completes, choose FileExit.

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

21. 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.

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

22. Start JetMan.
23. If Application "Tutorial" is not displayed, choose FileSelect Application. Browse to the \proltut\ directory, highlight broker.bin, and choose Open.
24. 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.

25. 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:

• rbconfig creates a minimal middleware configuration file (broker.bin) that you can use as a starting point for further development.

• rbboot activates a Panther application.

• rbshutdown deactivates a Panther 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.

26. 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:

    • The dialog for workstation clients asks for the server machine's host name and port.

    • The dialog for a native client (shown above) asks only for login information.

      Note: In this tutorial, user name and password are not needed; however, a deployed application typically requires, at a minimum, this level of security. You can set a password in the JetNet manager through the application's Application Password property (refer to page 3-12 in JetNet Guide/Oracle TuxedoGuide).

      All components of the tutorial application now display in the Application Status window.

      

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.

27. 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.

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

• Start up the JetNet manager by choosing ProgramsPanther Application ServerUtilitiesLocal JetMan.

• Select the application, if it is not already highlighted. (If the application is not listed, you need to open the broker.bin file. Choose FileSelect Application.)

• Choose EditActivate.

• Open a middleware connection.

  ---

What did you do?

In this lesson, you performed these tasks:

• Created a Panther application directory, proltut, where, for this tutorial, you store all necessary files, perform all server-related tasks and boot your application. In practice, this directory should be in a central location that is accessible to the entire development team.

• Set the server machine environment—path names, location of the Panther installation, libraries, and so forth. The extent of this work depended on whether your server runs on Windows or UNIX.

• Copied the standard application libraries, environment files, tutorial library, and vidsales database to the proltut directory, and edited the server environment files for your application.

• Provided access to the Panther server executables by creating links in the application directory (in UNIX) or by copying those executables to the application directory (in Windows).

• Created the binary middleware configuration file, broker.bin, with the JetNet manager. This also created your application.

• Activated your application with the JetNet manager.

What did you learn?

You learned:

• The application directory is the area where a server machine runs Panther. In general, it contains files that need to be accessed by all development team members, such as server executables, server environment files, and application libraries. Also, each developer has a working directory with local files such as client environment files and local copies of libraries.

• On UNIX, a setup file setup.sh contains variable settings, path names, and other information that are required for running Panther software. Each time you want to start up the application, you need to apply these settings before booting.

• The environment variable SMBASE is referred to frequently during installation and configuration tasks. It refers to the Panther installation directory and is set in several environment and configuration files. The default location is:

  UNIX: /usr/prolifics

  Windows: C:\Program Files\Prolifics\Panther

• The JetNet manager lets you define an application by creating the middleware configuration file broker.bin, and view and edit configuration file settings. Some of these settings were applied elsewhere in the setup procedure.

• All Panther components reside in libraries. Three standard libraries (client.lib, server.lib, and common.lib) are provided with Panther; an application component must reside in a shared library to be available to other developers.

• When you want to start your application, then reactivate the application with the JetNet manager (or the rbboot utility). For UNIX, make sure you are in the application directory, and set up the UNIX environment with the setup file setup.sh before running JetMan.

• When you are done using your application—at the end of the day or if you want to continue the tutorial later—you should shut it down, along with any active servers, with the JetNet manager (or the rbshutdown utility).