Oracle9i Lite Installation and Configuration Guide for Sun SPARC Solaris
Part No. A97644-01
This guide provides information regarding the system requirements, as well as detailed instructions on how to install, migrate to, and configure Oracle9i Lite 5.0.2 for Sun SPARC Solaris. It includes discussions of the following topics:
This section describes the system requirements for Oracle9i Lite 5.0.2 for Sun SPARC Solaris.
CPU: SunSPARC Ultra 1 or higher
RAM: 192 MB or higher
Disk Space: 555 MB
This section contains the instructions to install the Mobile Server.
The following circumstances can seriously affect the success of your installation:
If the client software of Oracle9i is already installed, it is recommended that you install the Mobile Server in the same <ORACLE_HOME> directory where the Oracle data server client software is installed. This will avoid having duplicate copies of the required support files installed on your machine.
If the Oracle9i Application Server 2.0 or a later version is already installed on your machine, it is recommended that you install the Mobile Server in the same <ORACLE_HOME> directory where the Oracle9i Application Server is already installed. This will avoid having duplicate copies of the required support files installed on your machine.
Set the value for JAVA13_HOME in the .login file to the directory where you installed the JDK. For example:
Set the value for ORACLE_HOME in the .login file to the directory where you have installed the Oracle database or the Oracle9i Application Server. For example:
If you plan to install Oracle9i Lite for use with Oracle9i Application Server version 2.0 (Oracle9iAS), you must have Oracle9iAS installed first, and you should run the following test to determine if your Oracle9iAS installation is configured to work with Oracle9i Lite.
Note:This step is not required if for Oracle9iAS version 18.104.22.168.0.
Mobile Server depends upon the Oracle Single Sign On (OSSO) server and the mod_osso Apache module to authenticate users from the Oracle Internet Directory (OID). Before installing Mobile Server make sure that all these Oracle9iAS components are installed and configured properly.
To check the proper installation of these components, follow the following steps to Protect the a Apache resource and then try to access that resource:
Insert a protected Apache resource. Create a directory named "private" inside the htdocs directory, for example <ApacheServerRoot>/htdocs/private. Copy some HTML pages into that directory. These can be dummy pages with no real content.
Open the mod_osso.conf file, which you can find at <Oracle9iAS_DIR>/conf/mod_osso.conf, and add the following text at the end:
<Location /private> require valid-user AuthType Basic </Location>
the mod_osso.conf file should look like this:
LoadModule osso_module libexec/mod_osso.so <IfModule mod_osso.c> OssoIpCheck on OssoIdleTimeout off OssoConfigFile <ORACLE_HOME>/Apache/Apache/conf/osso/osso.conf <Location /private> require valid-user AuthType Basic </Location> </IfModule>
Restart your instance of Oracle9iAS.
Open a browser and enter: http://<server>:<port>/private where <server> is your Oracle9iAS server instance and <port> is the port number it is using.
You will see the OSSO log on screen. Log on using the administrator username and password. The default username is "orcladmin".
If you are successfully able to log on and can see list of html pages inside /private, all the 9iAS components Mobile Server uses are installed and configured properly. You can now install Mobile Server using the instructions found in Section 1.2.3, "Installing the Mobile Server".
Insert the Oracle9i Lite CD-ROM into your CD-ROM drive and mount it. From a command line, run the installer
runInstall. Using the command
./runInstall will run the installer from the current directory. The Welcome screen appears as shown in Figure 1-1.
Figure 1-1 Mobile Server Welcome Screen
To see the Oracle products that are installed on your system, click Installed Products. To continue, select the Next button. The File Locations screen appears as shown in Figure 1-2.
Figure 1-2 Mobile Server File Locations Screen
Enter the name of your Oracle Home directory (the directory for your Oracle9i Lite installation) in the Path field, or accept the defaults. It is recommended that you use the same directory where you have installed Oracle9iAS version 22.214.171.124.0 or the Oracle9i database. Select the Next button.
Figure 1-3 Mobile Server Installation Types Screen
The Installation Types screen appears as shown in Figure 1-3. Select the Mobile Server option to install Mobile Server as either a standalone install, or on top of Oracle9iAS version 2.0, then select the Next button.
If you are installing on top of Oracle9iAS version 126.96.36.199.0, using the Oracle 8.1.7 libraries, select Custom, then select the Next button. The Available Product Components screen is displayed where you select the custom components necessary for this installation.
Figure 1-4 Mobile Server Custom Install Component Selection Screen
For an installation of Mobile Server on top of Oracle9iAS version 188.8.131.52.0, using the Oracle 8.1.7 libraries, select only the "Oracle9i Lite Mobile Server 184.108.40.206.0" component as shown in Figure 1-4. Select the Next button.
Figure 1-5 Mobile Server Repository Database Information Screen
The Mobile Server Repository Database Information screen appears as shown in Figure 1-5. Enter the information in the Hostname, Port, and Net Service Name fields regarding the existing Oracle database (Oracle 8.1.7 or higher) which will be used as the Mobile Server Repository. The default port number is 1521. The Net Service Name is your Global Database Name and is not the "SID". Contact your system administrator if you do not have any of this information. Select the Next button after entering the required information.
Figure 1-6 Mobile Server Repository Install Query Screen
The Mobile Server Repository Install Query screen appears as shown in Figure 1-6. Select Yes to install the Repository, for example to install an individual instance of Mobile Server. Select No to bypass this step and not install the Repository, for example if you are installing several instances of Mobile Server which use one repository with a hardware load balancer.
Once you have made your choice, select the Next button
Figure 1-7 Mobile Server Oracle Protocol Support Screen
The Oracle Protocol Support screen appears as shown in Figure 1-7, indicating the network protocol support that is preselected for native network protocols that are required for your platform. Your system may have more options than are shown here, but the default settings are sufficient for most installations. Select the Next button.
Figure 1-8 Mobile Server Summary Screen
The Summary screen appears as shown in Figure 1-8 showing the global settings and space requirements for the Mobile Server on your system. Check the Space Requirements to make sure that the required space for installing the Oracle9i Lite Mobile Server is actually available on the machine that you are installing the Mobile Server on. Click Install to begin the installation.
Figure 1-9 Mobile Server Install Progress Screen
The Install Progress screen appears as shown in Figure 1-9 and provides visual indication of the installation progress. When the installation of the Mobile Server and all the support files is completed, the Configuration Tool screen is displayed and the Mobile Server Repository Wizard starts.
Figure 1-10 Repository Wizard Log On Screen
The Mobile Server Repository Wizard screen is displayed as shown in Figure 1-10. To begin the Mobile Server Repository Wizard, enter your system user password in the field provided. Select the Next button.
Figure 1-11 Repository Wizard Status Screen
The Mobile Server Repository Wizard indicates that no existing Repository is found as shown in Figure 1-11 and that a new Repository will be installed. Select the Next button.
Note: The Mobile Server Repository Wizard queries against the database for the previously installed components of Mobile Server. If it finds any of the previous versions of Mobile Server, it will migrate the previous version of the Repository to the latest version of the Mobile Server Repository. If it does not find a previous version, it will install a new Mobile Server Repository. For information on using the Mobile Server Repository Wizard for migrating your Repository manually, see Section 1.3.1, "Migrating the Mobile Server Repository Manually".
Figure 1-12 Repository Wizard Schema and Password Screen
Enter the information in the Schema Name and the Password fields for the Mobile Server Repository as shown in Figure 1-12. You can either use the name of an existing schema in your Oracle database or you can enter a new schema name and a new password, and Oracle9i Lite will create that schema for you. Enter the password again in the Re-enter the password field. Select the Next button.
Figure 1-13 Repository Wizard Summary Screen
The Summary screen appears as shown in Figure 1-13 displaying the name of the schema, that no existing repositories are found, and that the Mobile Server Repository will be installed. Select the Next button.
Figure 1-14 Repository Wizard Process Screen
In this step, the Mobile Server Repository is in the process of being installed. A progress panel appears, as shown in Figure 1-14, indicating the installation steps and the status of the installation process for each step in terms of whether it is completed or in progress. When the installation of the Mobile Server Repository is completed, the Next button becomes activated. Select the Next button.
Figure 1-15 Repository Wizard Installation Status Screen
The Mobile Server Repository Wizard indicates that the installation of the Mobile Server Repository is completed as shown in Figure 1-15. It displays the path of the Repository.log file, which you should check for any errors. Click Finish to exit the Mobile Server Repository installation and to return to the Mobile Server installation process.
Figure 1-16 Mobile Server Install Complete Screen
The End of Installation screen for installing the Mobile Server appears, as shown in Figure 1-16, displaying the message "The installation of Oracle9i Lite was successful." Click Exit to end the installation process.
You can migrate your data and upgrade your software from previous versions of this product.
Use the Mobile Server Repository Wizard to migrate a previous version of the Repository to the Mobile Server Repository for release 5.0.2.
The Repository Wizard is started during the last phase of the installation. After entering the password and clicking the Next button in Step 9 of Section 1.2.3, "Installing the Mobile Server", the Mobile Server Repository Wizard queries against the database for the previously installed components of Web-to-Go and Consolidator. Follow these steps to migrate your Repository to the Mobile Server Repository manually:
Figure 1-17 Repository Wizard Schema Information Screen
If the Repository Wizard finds any of the previous versions of the Repository, a screen appears, as shown in Figure 1-17, displaying the schema name of the existing Repository and the Web-to-go and Consolidator version numbers.
If the Repository Wizard finds two or more Repository schemas, you have the option of selecting the Repository schema that you want the Repository Wizard to migrate to the Mobile Server Repository.
Select the schema that you want to migrate to the Mobile Server Repository, then select the Next button. Enter the appropriate information in the fields for the Schema Name and the Password, then select the Next button.
Figure 1-18 Repository Wizard Schema Summary Screen
A Summary showing the schema name and the existing repositories appears, as shown in Figure 1-18. The dialog box also displays a statement regarding the action that will be taken by the Repository Wizard at this point, namely, that the repositories will be migrated. Select the Next button.
Figure 1-19 Repository Wizard Migration Progress Screen
The Repository is migrated. A progress panel appears, as shown in Figure 1-19, indicating the installation and migration steps and their status. When the migration is completed, Select the Next button.
Figure 1-20 Repository Wizard Migration Complete Screen
The Repository Wizard indicates that the installation of the Mobile Server Repository is completed on a screen as shown in Figure 1-20. It displays the path of the Repository.log file, which you should check for any errors. Click Finish to exit the Repository migration.
Application files are no longer stored in the Repository in Mobile Server release 5.0.2, but are stored as files on the Mobile Server host system. During migration, existing files are moved from the Repository to a directory structure which has its root as <ORACLE_HOME>/mobile/server/repository.
When migrating to an instance of Mobile Server installed on top of Oracle9i Application Server (Oracle9iAS) any users not present in the Oracle Internet Directory (OID) must be migrated. A tool called oiduser is located in <ORACLE_HOME>mobile/server/bin which is used to migrate existing Mobile Server users from the Mobile Server Repository into the OID with randomly generated passwords, or a user-defined, common password when the following procedure is used.
From a command line, enter the following:
oiduser <Mobile Server repository user name> <password>
For example the default setting would be:
oiduser mobileadmin manager
If you want to set a specific, common password for all the users, instead of generating random passwords, the syntax is:
oiduser <Mobile Server repository user name> <password> -p <common_password>
where the <
common password> is specified by you.
Running oiduser generates a user.dat file which contains a list of users and the passwords created for them in step 1 or 2. This file is strictly for informational purposes. All users from the Mobile Server Repository have been migrated to the OID with the passwords generated in step 1 or specified in step 2.
Restart the Mobile Server.
Migrating legacy data where CHAR columns for bind variables are used in queries requires troubleshooting before migrating the data. Also, the migration of Java Server Pages (JSP) requires troubleshooting. The following sections describe the troubleshooting procedures.
It is recommended that you do not use CHAR columns in the WHERE clauses of the SQL statements of your snapshot definitions for tables. Use VARCHAR2 instead. Otherwise, you will not be able to migrate your data or to synchronize successfully.
If your published snapshot definitions in the Mobile Server Repository contain the bind variable column names in CHAR, you must modify the SQL queries for those snapshot definitions by using RPAD and publish the modified snapshot definitions before migrating your data. Use the Packaging Wizard to edit the queries for the snapshot definitions. The Packaging Wizard must be installed on a Windows system. For information on how to use the Packaging Wizard, see the Oracle9i Lite Developer's Guide for Web-to-Go and the Oracle9i Lite Administration and Deployment Guide.
In the Packaging Wizard, select the table whose query you want to modify. Using the edit function in the Packaging Wizard (clicking the Edit button in the Snapshots panel), select the appropriate tab for each client (for example, the Win32 tab, the Palm tab, and so on) to modify the SQL query in the Edit Snapshots dialog box for each client. In the panel for each client, select the "Create on client" check box. Change the SQL statement in the Template field by using RPAD as shown in the following examples and then click OK.
You must then publish your publication back into the Mobile Server Repository.
SELECT * FROM DEPT WHERE DEPT_NAME =:DEPT_NAME
SELECT * FROM DEPT WHERE DEPT_NAME = RPAD(:DEPT_NAME,<length of column>)
After modifying the queries in your snapshot definitions, publish the snapshot definitions. For information on publishing, see the Oracle9i Lite Developer's Guide for Web-to-Go and the Oracle9i Lite Administration and Deployment Guide. You can migrate your data after publishing the modified snapshot definitions.
The JSP library that ships with Oracle9i Lite is different than the one included in Oracle8i Lite. One of the most visible changes is that the algorithm used to translate the URL for a JSP page in the underlying servlet class name has changed. For example:
Oracle8i Lite uses Oracle JSP 1.0.6.
The URL: /sample1/page.jsp
maps to the servlet class: sample1.page.class
Oracle9i Lite uses Oracle JSP 1.1.2
The URL: /sample1/page.jsp
maps to the servlet class: _sample1._page.class
As a result, after migrating from Oracle8i Lite to Oracle9i Lite, your application may display "ClassNotFound" errors when trying to access JSP pages. There are two options to resolve this issue:
The recommended method is to recompile the JSP files and copy the class files to the Repository using the following steps:
Recompile the JSP files with the newer JSP library.
Manually copy the files into the Mobile Server Repository using the Shell Utility (wsh). See the Oracle9i Lite Administration and Deployment Guide, for a list of the commands on how to manually manipulate the files in the Mobile Server Repository.
Replace the JSP library with the version that shipped with Oracle8i Lite.
Replace the JSP library used by the Mobile Server. Replace the file <ORACLE_HOME>/Mobile/classes/ojsp.jar with the previous version, which was installed in the following location: <ORACLE_HOME>/webtogo/bin.
Change the version of ojsp.jar that is deployed for the Mobile Client for Web-to-Go, using wsh as follows:
wsh -o email@example.com cd /setup/webtogo copy <ORACLE_HOME>/webtogo/bin/ojsp.jar ojsp.jar sync exit
This section provides information for configuring the Mobile Server. Installation alone does not enable you to run the Mobile Server. You must also configure a Web server as a framework to run the Mobile Server. The Mobile Server can run in the following configurations:
Mobile Server Module for Oracle9i Application Server on the Oracle9i Application Server.
The standalone Mobile Server.
The remainder of this section describes in detail how to set up these configurations. When you finish your configuration, you must start the Mobile Server, which is described in Section 1.5, "Running the Mobile Server".
You can run the Mobile Server as a module on the Oracle9i Application Server (Oracle9iAS). To accomplish this, you must first install and configure Oracle9iAS. If you are installing on top of Oracle9iAS version 220.127.116.11.0 you should perform Step 1 and Step 6, skipping Steps 25. Steps 25 configure your instance of Mobile Server to run as a module of Oracle9iAS version 2.0, and Steps 16 are required.
Add the Mobile Server Module for Oracle9i Application Server to Oracle9iAS by changing the Oracle9iAS configuration file. The default location for the configuration file is:
where <Oracle9iAS_DIR> is the directory where you installed Oracle9iAS.
For example, if you installed Oracle9iAS in the location:
then the full path to the configuration file would be:
Add the Mobile Server Module for Oracle9i Application Server by adding the following line at the very end of the Oracle9iAS configuration file:
This points to the wtgias.conf file. This file is the configuration file for loading the Mobile Server Module for Oracle9i Application Server inside Oracle9iAS.
Verify that the file <ORACLE_HOME>/Apache/Apache/bin/.apachectl is not owned by 'root' but is owned by the user who owns the 9iAS installation.
Open the file <ORACLE_HOME>/opmn/conf/opmn.xml and add the environment variables (like LD_LIBRARY_PATH, CLASSPATH, etc.) to it. For example:
<ohs gid="HTTP Server" maxRetry="3"> <start-mode mode="ssl"/> <environment> <prop name="LD_LIBRARY_PATH" value="/<ORACLE_HOME>/jdk/jre/lib/sparc/client:/<ORACLE_HOME>/lib"/> <prop name="CLASSPATH" value="/<ORACLE_HOME>/jdbc/lib/nls_charset12.zip:/<ORACLE_HOME>/jlib/jndi.jar"/> </environment> </ohs>
Open the file <ORACLE_HOME>/config/jazn-data.xml, search for webtogo.jar and edit the following line, replacing
mobile/server, to make the leading characters lower case:
Open the file <ORACLE_HOME>/Apache/Apache/conf/mod_osso.conf and add the following to it:
<Location /webtogo/WLTop> require valid-user AuthType Basic </Location>
The mod.osso.conf file should look like this:
LoadModule osso_module libexec/mod_osso.so <IfModule mod_osso.c> OssoIpCheck on OssoIdleTimeout off OssoConfigFile /<ORACLE_HOME>/Apache/Apache/conf/osso/osso.conf# # Insert Protected Resources: (see Notes below for how to protect resources)# #-------# # Notes# #-------# # 1. Here's what you need to add to protect a resource, # e.g. <ApacheServerRoot>/htdocs/private: <Location /webtogo/WLTop> require valid-user AuthType Basic </Location> <Location /private> require valid-user AuthType Basic </Location> </IfModule>
Start the Oracle9iAS by typing the following command at the command line:
apache -k start
If the Oracle9iAS is already running, restart it by typing the following command at a the command line:
apache -k restart
In some cases, such as when you run the Mobile Server on a development machine, you may want to start it without using Oracle9iAS. You can start the Mobile Server in standalone mode by running the webtogo program. After you install the Mobile Server, start it by typing the following command:
If you want to start the Mobile Server in servlet debug mode (when experiencing problems with running servlets), type the following command at the command line:
If you want to start the Mobile Server in total debug mode (when experiencing problems with the server and the webtogo.ora file), type the following command:
If you want to run the Mobile Server using port number 80, you must log on as 'root'. If your access level is not root and you attempt to run Mobile Server, it will return the following errors:
WTG-23002 You must have root privileges to run on port <port no>. WTG-23003 Please edit the PORT entry in webtogo.ora, if you want to run on a different port.
To run the Mobile Server, the administrator must first start the Oracle9iAS or the webtogo program (the standalone mode). Starting the Mobile Server depends upon system configuration. There are two configuration scenarios for the Mobile Server:
If the administrator configured the Mobile Server as a module in Oracle9iAS, then the Mobile Server starts simultaneously with Oracle9iAS.
If the administrator chooses the standalone mode, then the administrator must start the Mobile Server manually. To start the Mobile Server manually, run webtogo from the command line or the Web-to-Go executable whose default location is <ORACLE_HOME>/mobile/server/bin.
The administrator can log into the Mobile Server after starting it by supplying a user name and a password for the Mobile Server Repository. Logging in connects the Mobile Server to the Mobile Server Repository, giving the administrator access to the account information and applications that reside in the Mobile Server Repository. The administrator uses the Mobile Server Repository to deploy such client software as the Mobile Client for Web-to-Go.
The Mobile Server enables administrators to manage their user Mobile Server Repository names and passwords securely by saving them in encrypted form in the webtogo.ora file. In addition, administrators can change their Mobile Server Repository passwords in the webtogo.ora file or remove them from the file.
To log into the Mobile Server:
Start the Mobile Server Listener.
Connect to the following URL:http://Mobile Server_name/webtogo/startup. If the Mobile Server is running, then the following log on screen appears. If the Mobile Server is not running, then the following log on screen appears, as shown in Figure 1-21.
Figure 1-21 Log On Screen
Enter the administrator's user name and password for the Mobile Server Repository.
Figure 1-22 Invalid Password Screen
Click Startup. If the password is invalid, then the Invalid User Name/Password screen appears, as shown in Figure 1-22, which enables the administrator to enter the user name and password a second time followed by clicking Logon. If the log on is successful, then the Menu Option screen appears.
Figure 1-23 Options Menu Screen
Select one of the following options, as shown in Figure 1-23:
Save - Choose this to save the encrypted versions of both the Mobile Server Repository user name and password in the webtogo.ora file. This activates the Mobile Server Auto Start feature.
Erase - This option removes the encrypted versions of the Mobile Server Repository user name and password from the webtogo.ora file. This turns off the Mobile Server Auto Start feature.
Change - Overwrites the Mobile Server Repository password in the webtogo.ora file. For more information, see Section 1.5.2, "Changing a Password for the Mobile Server Repository".
Startup - This option is not available if the Mobile Server is already running. If the Mobile Server is not running or is terminating a session, you can use this option to start it.
Shutdown - Terminates the current Mobile Server session, allowing connected users to remain connected and synchronize, but preventing new connections. See Section 1.5.3, "Shutting Down the Mobile Server" for more information.
Log Off - Logs off the current user and presents the log on screen.
To change a password for the Mobile Server Repository:
In the Menu Options screen, select Change. The Change Password screen appears as shown in Figure 1-24.
Figure 1-24 Change Password Screen
Enter the current password in the Old Password field.
Enter the new password in both of the New Password fields.
Click Change Password. If the entries in both the Old Password and the New Password fields match, then the password to the Mobile Server Repository is changed and the old password is overwritten in the webtogo.ora file.
The administrator can now put the Mobile Server into a state where users who are connected stay connected and can synchronize normally, but no new users are allowed to log on. When the last connected user logs off, the instance of Mobile Server ends. This is referred to as terminating Mobile Server. To terminate a Mobile Server session:
From the Menu Options screen, Figure 1-23, select the Shutdown option.
Figure 1-25 Mobile Server Options Menu While Terminating
If users are connected to Mobile Server, the screen is displayed, as shown in Figure 1-25, indicating that "Oracle Mobile Server is Terminating". The Save, Erase, Change, and Shutdown options are disabled. The Startup option restarts the Mobile Server instance seamlessly. Selecting the Log Off option logs out the administrator.
Figure 1-26 Mobile Server is Terminating Error Screen
Users attempting to connect to the Mobile Server while it is shutting down see the following screen displayed in Figure 1-26 which indicates that they have "Failed to logon to Web-to-Go!" because "Mobile Server is terminating!." They are also advised to contact the administrator.
Figure 1-27 Mobile Server Options Menu for Disconnected Status
If no users are connected, the screen shown in Figure 1-27 is diplayed indicating that "Oracle Mobile Server is not connected to the Repository". The Save, Erase, Change, and Shutdown options are disabled. The Startup option restarts the Mobile Server instance seamlessly. Selecting the Log Off option logs out the administrator.
Figure 1-28 Mobile Server is Down Error Screen
Users attempting to connect to the Mobile Server after it has been shut down see the following screen displayed in Figure 1-28 indicating that they have "Failed to logon to Web-to-Go!" because "Mobile Server is down!". They are also advised to contact the administrator.
You can install the demos on the Mobile Server by running the batch file instdemo. This batch file is located in <ORACLE_HOME>/mobile/server/samples.
The command syntax is:
instdemo [SYSTEM_password] [Admin_Username] [Admin_Username]
instdemo manager Administrator Admin
By default, the Mobile Server uses the OCI9 JDBC driver to connect to the Mobile Server Repository. This driver does not allow the Mobile Server to detect if the Oracle database containing the Mobile Server Repository has been restarted. As a result, you must manually restart the Mobile Server if the database is bounced.
If you want the Mobile Server to automatically reconnect to the Oracle database, in case the Oracle database is restarted, you must configure the Mobile Server to use the thin JDBC driver.
You can do this by changing the ADMIN_JDBC_URL parameter in the configuration file webtogo.ora.
The location of this file is <ORACLE_HOME>/mobile/server/bin/.
Set the parameter to: