RealWeb

RealWeb allows the Reality DataBasic programmer to develop Web pages using data held in a Reality database. It consists of a set of Java servlets that run on a web server and a DataBasic API for constructing HTML pages.

The RealWeb API provides a suite of subroutines that the DataBasic programmer can use to interface to the Web browser - that is, to access arguments passed as part of the URL and to construct the HTML page that will be returned to the browser. Routines are provided to do the following:

• Fetch the values of arguments passed to RealWeb by the browser.
• Start and end an HTML page.
• Format text in various ways - for example, as a heading; left, centre or right aligned; fixed-pitch; in a particular font size and colour.
• Insert a horizontal rule.
• Create a hyperlink.
• Create an HTML form containing push buttons, text boxes and drop down lists.
• Create a definition list.
• Fetch and manipulate cookies.

Prerequisites

• A web server with support for Java servlets. (This can be on the same host as the Reality database or on another host.) On web servers that do not support servlets, plug-ins can be used to add servlet support.
• Java Run Time Environment (JRE) version 1.2 or above. If this is not available, it can be downloaded from Sun's Java web site (http://java.sun.com/j2se/).
• If you are connecting to a Reality database on a UNIX host, the host will require UNIX-Connect.

Information You Must Supply

The table below lists the information you will need when installing RealWeb. You can fill in the second column of the table so that you have the information to hand during the installation process (print out this page if you are viewing it on-line).

The location of the directory on your web server or servlet plug-in where servlets are stored (the servlet directory) - refer to your web server or plug-in documentation.
The location of the document root directory of your web server - refer to your web server or plug-in documentation.
root password if installing on UNIX.

Set-up Before Installation

Servlet Plugins

If your web server does not support servlets, install a servlet plugin, such as JRun. This can be purchased from Adobe (http://www.adobe.com/products/jrun/).

Netscape Enterprise Server

If you are using the Netscape Enterprise Server, you will need to do the following:

• Create a directory called servlet in your web server's document root Directory (the path will be something like /usr/netscape/server4/docs/servlet if you use the default installation settings).
• Create a file called realweb.ini in the web server's configuration directory. This will be a directory called https-ServerName/config in the server root directory, where ServerName is the name of your web server.

Java 1.2

The servlets require the Java Run Time Environment (JRE) version 1.2 or above. If this is not available, it can be downloaded from Sun's web site (http://java.sun.com/j2se/).

Sun hosts used as web servers may need Solaris patches in order to run JRE 1.2. These patches are listed on, and may be downloaded from the above Web site.

The installation package includes readme.txt files for several of the external components.

Installation

Windows

1. Start the installation program as described for Windows in the section Starting the Installation.
2. Select RealWeb Servlets & HTML Install from the Web Software menu.
3. If you have not already installed JReal, this is loaded automatically.
4. The destination for the RealWeb servlets must be your servlet directory (see Information You Must Supply).
5. The destination for RealWeb's HTML files must be your web server's document root directory (see Information You Must Supply).

UNIX

1. Start the installation program as described for UNIX in the section Starting the Installation.
2. Enter the root password when prompted. The following menu is displayed:

   Reality CD-ROM Component Installation Utility
   
   The following components are available
   
   JDBCdriver   V1.0         RealSQL-JDBC driver interface to Reality
   JReal        V3.2         Java interface to Reality (DDA & RSC)
   RealWeb      V3.2         Web interface to Reality
   
   Select component to install
              Install JDBC driver  y/n/q [n]:
                    Install JReal  y/n/q [n]:
                  Install RealWeb  y/n/q [n]:

   Press RETURN until you are prompted to install RealWeb; then enter y.

   Note: JReal is a prerequisite for RealWeb. When you select RealWeb, JReal is included automatically.

   You are then prompted

   About to install .........   Confirm?

   Enter y to continue.

3. Enter the installation directory for each component when prompted. For JReal, the default location is /usr/northgateis/Product-Version, but you can change this if required. The destination for the RealWeb servlets must be your servlet directory and that for RealWeb's HTML files must be your web server's document root directory (see Information You Must Supply).

Set-up After Installation

1. Add the jreal.jar file to CLASSPATH. For example, on UNIX:

   /usr/northgateis/JReal-3.1/class/jreal.jar

   or on Windows:

   C:\Program Files\NorthgateIS\JReal-3.1\jreal.jar

2. Add the class directory to CLASSPATH.

   On UNIX:

   /usr/northgateis/JReal-3.1/class

   On Windows:

   C:\Program Files\NorthgateIS\JReal-3.1\class

   This contains the reality.properties file.

For information on how to set CLASSPATH, refer to Setting Environment Variables.

RealWeb User-id

Log on to the SYSMAN account and run SSM. Then do the following:

1. Use SSM option 2 to set up a user-id that will be used to access RealWeb. Set the status (field 13) to 'E' (enabled) and the type (field 14) to 'S' or '*' (so that it can be used as a server). Note that on a UNIX host a corresponding UNIX user-id must also exist, and it is the password for the UNIX user-id that must be used when running the RealWeb configuration editor (see Setting up the Servlets).
2. Use SSM option 3 to configure the security profiles associated with these user-ids, setting field 8 to specify an alternative security profile to be used when logged in via the RealWeb server, RWSRVR. You can specify DEFAULT.REALWEB as this alternative profile, or you can set up a new security profile, based upon DEFAULT.REALWEB, to be used with the RealWeb user-id. For more information on security for external access, refer to Setting up Security for External Access.

Setting up the Servlets

1. Start the RealWeb configuration Servlet by typing the following URL into a Web browser:

   http://ServerName/servlet/rwconfig

   where ServerName is the DNS name of your Web server. If this fails to generate the configuration editor front screen then it may require the web server (and/or the servlet plug in) to be stopped and re-started to recognise the configuration change.

2. Once the configuration servlet's front screen is displayed, select New and click Submit.
3. Enter the details of how to connect to the database to be used (you can obtain help by clicking the Help button). The section name is the name that will be used in the URL to access the database. Create an entry to use the ENGLISH-TUTORIAL account so that the demonstration can be run.
4. Test the new ENGLISH-TUTORIAL section by typing the following URL.

   http://ServerName/servlet/reality/SectionName/RW.DEMO

   where ServerName is the DNS name of your Web server and SectionName is the name of the connection you have just created. This should result in the demonstration front page being displayed. If the message

   RealWeb error: Missing entry in ini file

   is displayed, either you have typed the section name wrongly, or something is missing from the section's configuration.

Upgrading to a New Version

When upgrading from RealWeb 2, you must first remove the directory com/northgateis (on UNIX), or com\northgateis (on Windows) and all its contents from the web server's servlet directory.