Getting Started-JetNet

In Lessons 1 through 4 you set up the Panther application server, started the client, saved a service component and client screen to the correct libraries, updated the JIF, and tested the client screen. At the end of Lesson 4, a client made service requests to a server. In this lesson, you will set up a Panther web application and test the same client screen from a web browser.

A Panther web application server is installed on your HTTP server and can work with the following web architectures:

• CGI (Common Gateway Interface)

• ISAPI (Internet Server API for Microsoft's Internet Information Server)

• NSAPI (Netscape Server API)

When a browser request comes in for a Panther screen, the HTTP server passes the screen name to Panther. Panther opens the screen, performs any processing on the screen including service calls, generates the HTML to display the screen, at which point the HTTP server transmits the HTML back to the browser that requested it. For more information on web applications, refer to the Web Developer's Guide.

This lesson shows how to set up a Panther web application and is independent of all subsequent lessons in this tutorial.

In this lesson you learn how to:

• Run the Panther Web Setup Manager.

• Hook in a JPL module to handle the Panther web application server startup and shutdown procedures.

• Start up the Panther web application server and test the connection.

More About Web Application Server Processes

The Web Application Server consists of three executable processes for each application: requester, dispatcher, and jserver.

• Requester - accepts the CI/ISAP/NSAPI request from the HTTP server, asks the dispatcher for an available jserver, passes the request to the jserver, waits for the response, and transmits it back to the HTTP server.

• Dispatcher - Acts as the interface between the requester and the jserver. The dispatcher keeps track of available and busy jservers, and provides an available jserver to the requester.

• Jserver - Processes the CGI/ISAPI/NSAPI request from the requester, performing all application processing.

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

• The location of your Panther web application server installation:

  _____________________________________________

  • UNIX: The default location is /usr/prolifics.

  • Windows: The default location is C:\Prolifics\Panther.

• The location of your HTTP server's program directory:

  _____________________________________________ 

  Common names for the program directory include cgi-bin and scripts.

• The URL for the Panther web setup manager on your HTTP server, as in:

  http://hostMachineName/ProgramDirectory/websetup

  _____________________________________________ 

This tutorial assumes that the Panther application server and the Panther web application server are installed on the same machine or accessible via the network. To test the screen on the web, your HTTP server must be able to access your application directory.

Each Panther web application must have an initialization file, which contains con figuration settings for the application. The Panther Web Setup Manager helps you create a new initialization file (or update an existing one).

1. Start up your web browser (for example, Mozilla Firefox or Microsoft Internet Explorer).
2. In the URL window, type the location of the Panther Web Setup Manager.

   UNIX HTTP server:

   http://hostMachineName/ProgramDirectory/websetup

   Windows HTTP server:

   http://hostMachineName/ProgramDirectory/websetup.exe

   

3. Check that the Create an application radio button is selected.
4. Choose Continue.

You assign each web application a unique name which is used to name the application's requester program and the application's initialization (.ini) file.

5. For Application Name, enter a unique name to identify this lesson's web application, like tut_webapp.
6. For SMBASE, type the full path pointing to the Panther web application server installation (which you recorded on page 5-2).
7. For Program Directory, type the path to your HTTP server's program directory (which you recorded on page 5-2).

   Note: This should be a directory path, not a browser URL path.

8. For application type, choose CGI.

   (There are three types of requester programs. Depending on your platform, your options can include CGI, NSAPI, and ISAPI.)

9. Choose Continue.

   The program will now create both an .ini file and an executable specific to your application (for example, tut_webapp.ini and the executable tut_webapp). The next screen will tell you that both files have been created; the following steps will be to update the initialization file with the correct settings.

   

10. Choose OK.

In the left-hand frame, you will see icons for the initialization settings specific to the Panther web application server. When you click on each setting, there will be an accompanying explanation of how to set that variable. Most settings can be left at the default for now; however, the following steps lead you through settings which you need to edit or double-check:

11. In Application Directory, enter the path where you created your proltut directory in Lesson 1.
    

12. Choose Server Executables in order to specify the location of the dispatcher and jserver executables. Generally, the path location is to the util directory of the web application server installation.
    

13. In Dispatcher, set or check the full path name of the dispatcher executable.
14. In Server, set or check the full path name of the jserver executable.
15. Choose Server Variables.
    

16. In Number of Servers, set it to 5. This is the number of concurrent users. Since this setting greatly affects performance, you must set it for each web application.
17. Choose Licensing.
    

18. In License File, set or check the path of your license.dat file.
19. Choose Continue.

In the next section, you specify the environment settings needed by the web application server. You will see a new set of icons in the left-hand frame. Step through each category, editing or double-checking settings as necessary.

20. In SMBASE, set or check the setting of the web application server installation.
    

21. Choose Initial JPL.
    

22. In SMINITJPL, enter initial.jpl.

    This is the name of the JPL file that will be run when the web application server starts. (Later in this lesson you will add this JPL file to the client library.)

23. Choose Initial Development Libraries.
    

24. In SMFLIBS, set or check the settings for client libraries:

    client.lib|com mon.lib.

25. (UNIX only) Choose Shared Library Path.
    

26. (UNIX only) Depending on the operating system, enter one of the following:

    • Set LD_LIBRARY_PATH to the full path name of WebInstallDir/lib.

    • (AIX) Set LIBPATH to the full path name of WebInstallDir/lib.

    • (HPUX) Set SHLIB_PATH to the full path name of WebInstallDir/lib.

Depending on whether you are running the Panther web application server on a separate machine from your Panther application server, you will need to set this parameter in one of two ways, as outlined below.

27. Choose 3 Tier Configuration from the left-hand menu.

    • (If running a Panther application server and a Panther web application server on same machine): In JetNet Configuration File (SMRBCONFIG), type the directory path name where you created your broker.bin file in Lesson 2. Leave the lines for SMRBHOST and SMRBPORT blank.

    • (If running servers on different machines): Leave the line for JetNet Configuration File (SMRBCONFIG) blank. Enter the information for SMRBHOST (refer to Step 18 on page 1-9 in Lesson 1 for UNIX and to Step 11 on page 1-21 for Windows) and for SMRBPORT (refer to Step 22 on page 1-10 in Lesson 1 for UNIX and to Step 17 on page 1-23 for Windows).
      

28. If you are running the Panther web application server on a different machine from the Panther application server, you will need to set a value for certain platforms. It is not needed if you are using JetNet or Oracle Tuxedo 6.4 or later. Choose one of the values below and enter it under Work Station Device:

    • For Oracle Solaris platforms, enter:

      /dev/tcp.

    • For SCO platform, enter:

      /dev/inet/tcp.

29. Choose Path.
    

30. Check that the path location is set to the util directory of the web application server installation. If the jserver executable is not in the Panther webutil directory, you must set the correct path to the jserver directory here.
31. Choose Continue.

The next screen allows you to enter Additional Environment Variables for such applications as databases. If you were setting variables for an Oracle database, for instance, type the variable under "Settings" (e.g., ORACLE_HOME) and the path name under "Value" (e.g., /usr/oracle). You will also be setting access to the JIF file.

32. Under Setting, enter SMTPJIF, the Panther variable that identifies the JIF file.

    Note: If the EnableWebId option displays, note that it will not be used in the tutorial.

33. Under Value, enter jif.bin.
34. Choose Continue. A screen informs you that your Panther web application has been created.
    

35. Choose Start Application.

When a Panther web application server starts up, it looks for a JPL web_startup procedure to handle any necessary startup processing, open and close connections to the middleware API (and therefore to the database), and create global variables. Similarly, when the server is shut down, it looks for the web_shutdown routine-accessed by all users of the web application-to perform processing such as clean up. Both procedures are in the JPL module initial.jpl which is in the tutorial library. By copying initial.jpl to your client library and setting SMINITJPL in proweb.ini, these routines automatically run when the web application server is initialized.

More About JPL

JPL is a powerful scripting language with a C-like syntax. You can write and edit JPL modules directly in the editor environment, using the JPL editor or your preferred test editor. You can also write JPL procedures directly to a library and call these procedures from objects in your screens.

You'll practice writing and executing JPL in Lesson 13 of this tutorial. For more information on JPL commands and syntax, refer to the online Programming Guide.

36. For a UNIX client:

    • Log on to your Panther application server and change to the application directory:

      cd username/proltut

    • Reapply the settings:

      . setup.sh

    • Invoke the editor by starting up the client executable, prodev. At the command line, type:

      prodev

37. For Windows client:

    • From the Start menu, choose ProgramsPanther ClientTutorial (folder)Tutorial.

    • When the Connect screen opens, check your Host and Port settings for the middleware session and choose OK.

38. Choose FileOpenJPL.

    The Open JPL Module dialog opens.

    

    • If tutorial.lib is not open, choose Open and select it from the Open Library dialog box. (You will need to set the directory path to /prolifics/samples/tutorial/ to find this file).

39. Select tutorial.lib from the list of open libraries, and double-click on initial.jpl in the Members list to open it.

    The initial.jpl file opens in the JPL Program Text dialog box.

    

40. Choose Save As. The Save JPL dialog opens with initial.jpl in the Member box.
    

41. Select client.lib in the Libraries list. Choose OK.

    The initial.jpl file is saved to client.lib.

42. Choose OK.
43. Choose Close.
44. Choose FileExit to end your editor session.

The Panther web application server must be able to access some files in the application directory on UNIX. Because the user account for the HTTP server is different from your user account, the web application server is normally not allowed to write to your directory.

45. Switch to the /proltut directory.

    If error.log does not exist, create an error log file and set its permissions so that the web application server has read and write access to the file:touch error.log

    chmod 666 error.log

46. Change permissions so that the Panther web application server has read and write access to the server configuration file, broker.bin:

    chmod 666 broker.bin

Now you can start the Panther web application server and test the client/server connection by trying to invoke the service routine from your client screen with a web browser.

47. If your Panther application server is not running, reactivate it now from the server machine (refer to Steps 27 to 31 on page 1-11 in Lesson 1 for UNIX or refer to Steps 22 to 26 on page 1-25 in Lesson 1 for Windows). Also, start the web browser, if it is not already running.
48. Since the Panther web application server was started when you ran the web setup manager, you must restart it so that it will read the new JPL file:

    WebInstallDir/util/monitor -stop webAppname
    WebInstallDir/util/monitor -start webAppname

    Note: On Windows, if your web application has been installed as a service, then you use the following command to start the web application:

    WebInstallDir/util/net start webAppname

49. Request the test screen with this URL:

    http://hostName/ProgramDirectory/webAppname/test

    The client screen appears.

50. Click on the Test Service button.

    The phrase "It worked!" is displayed in the text box.

    

If you have a problem either starting the web application server or seeing the message returned from the server, refer to Appendix B on page B-1.

Stop and restart server after making any changes

If you make any changes to the web initialization (webAppname.ini) file, or if you see any error messages indicating that you failed to connect to the server, you must stop and restart your web application server to have the changes take effect. Shut down the server by going to a UNIX window and typing at a command prompt:

$SMBASE/util/monitor -stop webAppname

Edit the initialization file the same way you created it, by typing in the browser:

http://hostMachineName/ProgramDirectory/websetup

and choosing to update the application.

You can then restart the server by repeating the procedure outlined in Step 47 above.

Shut down the server

After you successfully start the web application server, you can shut it down. The lessons that immediately follow do not require its usage.

51. Shut down the web application server:

    $SMBASE/util/monitor -stop webAppname

    ---

In this lesson, you performed these tasks:

• Used the Panther Web Setup Manager to create a copy of the CGI/ISAPI/ NSAPI program so that your application is available on your HTTP server.

• Used the Panther Web Setup Manager to create a web application server initialization file, webAppname.ini, which has the same name as your web application. and edited it to reflect variable settings for your application.

• Used the Panther Web Setup Manager to specify the application's settings for your applications.

• Saved a copy of a JPL module, initial.jpl, to your client library. This file contains startup and shutdown routines that run when the web application server is initialized.

• Changed permissions on the error log file and configuration file broker.bin, so the web application server has read/write access to them.

• Started up the web application server, tested the connection, and shut the server down.

What did you learn?

You learned:

• A Panther web application is only accessible on an HTTP server if there is a link to, or a copy of, its requester executable in the server's program directory.

• Each application must have an initialization file, which contains variables determining the behavior of the web application, the Panther environment used by the jserver program, and the database environment.

• Certain processing, such as opening a middleware session or setting global variables, occurs each time a web application server starts. By creating JPL routines to handle this processing, and then setting variables in the web application initialization file, you can set up default processing to take place each time the web application server is initialized.