Getting Started-2-Tier

This lesson shows you how to set up a Panther web application server and test the server on 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, does any processing on the screen, generates the HTML to display the screen, and returns the HTML to your HTTP server, which transmits the HTML back to the browser that requested it. For more information, refer to the Web Developerment Guide.

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.

In this lesson you learn how to:

• Use the Web Setup Manager to create the web application initialization file and start up the server.

• Include a JPL module that handles server startup and shutdown.

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

Most of this lesson assumes that:

• You can access the Panther web application server from your development environment.

• You are testing the screen on a graphical web browser.

• You are using the CGI version of the Panther web program.

Before starting this lesson

Before you begin this lesson, determine the following:

• The location of your Panther web application server:

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

• That the Panther Web Setup Manager is installed on your HTTP server and ready to run via a web browser (if it is not, refer to the Installation). The default URL location is:

  http://serverName/programDirectory/websetup

  Make a note of its URL:

  ---

Start the Web Setup Manager

Each Panther web application must have an initialization file, which contains con figuration settings for the application. The Web Setup Manager will walk you through the configuration settings and create or update the initialization file accordingly. The initialization file will have the same name as your application, for example tut_webapp.ini. The Web Setup Manager also copies over the executables and starts the application when it first creates the initialization file.

1. In your web browser type the URL of the program directory on your HTTP server and run websetup.

   (UNIX server) http://hostname/ProgramDiectory/websetup

   (Windows server) http://hostname/ProgramDirectory/websetup.exe

   

2. Check that the Create an Application radio button is selected.
3. Choose Continue to set up your application directory and its settings.

You assign each web application a unique name which is used to name the application's CGI/ISAPI/NSAPI program and the application's initialization (.ini) file. The requester executable that is installed as part of the Panther web application server is named proweb. This requester executable is copied to have the same name as your web application.

4. For Application Name, type the unique application name you are using to identify your web application, for example, tut_webapp.
5. Set SMBASE to the full path name of your Panther web installation directory. (Refer to "Before starting this lesson.")
6. Enter the full path to the program directory that contains the executables used by the HTTP server. The program directory may contain CGI (.exe), NSAPI (.nsa), or ISAPI (.isa) executables depending on the protocols used by your HTTP server. (Refer t "Before starting this lesson.")

   Note: The program directory is determined by your HTTP server. If you are not sure of this directory, or if you run into permission problems accessing it, check with your system administrator. It should be a directory path, not a browser URL.

7. For application type, choose CGI by selecting the radio button.
   

8. Choose Continue.

   The Web Setup Manager will confirm that both an .ini file and an executable specific to your application (for example, tut_webapp.ini and tut_webapp have been created.

   

9. 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. Some browsers will display a default; most settings can be left at the default for now. Settings which you need to edit or double-check include:

10. Set the Application Directory to the full path name of your proltut directory.
    

11. Choose Server Executables.
12. In Dispatcher, set or check the full path name of the dispatcher executable, generally, the path location to the util directory of the web application server installation.

    UNIX WebInstallDirectory/util/dispatcher

    Windows WebInstallDirectory\util\dispatcher.exe

13. In Server, set or check the full path name of the jserver executable.

    UNIX WebInstallDirectory/util/jserver

    Windows WebInstallDirectory\util\jserver.exe

    

14. Choose Server Variables to display the server options.
15. Set Number of Servers to 5. This is the number of concurrent users. Since this setting greatly affects performance, you must set it for each web application.
    

16. Choose Licensing to display the licensing options.
17. Set or check the path of your license.dat file.
    

18. Choose Continue.

The next section allows you to create and update tut_webapp.ini settings relevant to the general environment. You will see a new set of icons in the left-hand frame. Step through each category, editing or double-checking settings as necessary.

19. In SMBASE, set or check the full path name of the Web Application Server installation directory.
    

20. Choose Initial JPL.
21. Set SMINITJPL to initial.jpl.
    

22. Choose Initial Development Libraries.
23. In SMFLIBS, set or check client.lib.
    

24. (UNIX only) Select Shared Library Path.
25. (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.
      

26. Choose Path.
27. Set Path to the full path name of util in the WebInstallDir directory.
    

28. Choose Continue.
29. The Additional Environment Variables screen appears. Choose Continue.
30. The Web Setup Manager will give you a message that your application has been created. Choose Start Application or exit from your browser.

    The Web Setup Manager has created your web application .ini file and copied the appropriate executables for that application.

31. If you started the application, shut it down from the command line:

    UNIX WebInstallDir/util/monitor -stop WebAppname

    Windows WebInstallDir\util\monitor -stop WebAppname

When a web application server starts up, it looks in its JPL module—specified by the web initialization file variable SMINITJPL—for the web_startup procedure to handle startup processing. This processing can include opening database connections and creating global variables. The module distributed for this tutorial—in itial.jpl—contains a web_startup procedure that initializes the JDB database engine and establishes a connection to the vidsales database:

proc web_startup
{
	DBMS ENGINE jdb
	DBMS DECLARE tut_conn CONNECTION FOR DATABASE "vidsales"
}

When the server shuts down, it looks in the same module for the web_shutdown procedure to perform cleanup operations such as closing the database connection. The web_shutdown procedure for this tutorial closes the database connection established earlier by web_startup:

proc web_shutdown
{
	DBMS CLOSE_ALL_CONNECTIONS
}

The distributed tutorstd.lib library contains a web initialization file. A copy of this module must be saved in the client library.

32. Start the Panther editor:

    • Windows—Choose Tutorial from the Start menu or choose the Tutorial icon.

      For more information on setting up the client on Windows, refer to "Setting up on Windows."

    • UNIX—Type prodev & at the command line.

      For more information on setting up the client on UNIX, refer to "Setting up on UNIX."

33. In the editor, choose FileOpenLibrary and select tutorstd.lib.
34. Choose FileOpenJPL.

    The Open JPL Module dialog opens.

    

    • If tutorstd.lib is not open, choose Open and select it from the Open Library dialog box.

35. Select tutorstd.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.

    

36. Choose Save As. The Save JPL dialog opens.
    

37. Select client.lib in the Libraries list, and initial.jpl appears in the Member box. Choose OK.

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

38. On the JPL Window, choose Close.
39. Choose FileExit to end your editor session.

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 9 of this tutorial. For more information on JPL commands and syntax, refer to the Programming Guide.

Make sure the application directory can support the web application server started by the httpd program. Because the user that the httpd program runs under is different from your user login, the web application server is normally not allowed to write to your directory.

Test the connection

Now you can start the web application server and test the client/server connection by opening your client screen in a web browser.

40. If your HTTP server is not running, activate it now. Also start the client's web browser on your PC if it is not already running.
41. Start the web application server from the command line:

    UNIX WebInstallDir/util/monitor -start WebAppname

    Windows WebInstallDir\util\monitor -start WebAppname

42. Type in the URL in your browser:

    http://hostname/cgi-bin/WebAppname

    At this point, you have started up the Panther web application server. The client screen appears.

If the phrase "No service requested!" is displayed then you have successfully configured the web application server.

If you make any changes to the web initialization (WebAppname.ini) file, you must stop and restart the Panther web application server to have the changes take effect. Stopping the web application server is described in the next section.

Shut down the server

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

43. Shut down the web application server:

    UNIX WebInstallDir/util/monitor -stop WebAppname

    Windows WebInstallDir\util\monitor -stop WebAppname

    ---

In this lesson, you performed these tasks:

• Used the Web Setup Manager to make a copy of the web application server initialization file, gave it the same name as your web application, and edited it to reflect variable settings for your application. The Web Setup Manager also copied the web executable and started the web application server.

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

• 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 CGI directory.

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

• Certain processing, such as opening a database connection 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.