1
Installation, Migration, and Configuration

1.1.1 Hardware Requirements

• CPU: SunSPARC Ultra 1 or higher

• RAM: 192 MB or higher

• Disk Space: 555 MB

1.1.2 Software Requirements

• Operating System: Sun Solaris 2.6, Solaris 7, or Solaris 8

• Oracle9i Application Server

  • version 2.0 using Oracle9i client libraries, or,

  • version 1.0.2.2.0 using Oracle database 8.1.7 client libraries.

• Java Development Kit 1.3.1

• Run-time C/C++ libraries

1.2.1 Pre-Installation Notes

The following circumstances can seriously affect the success of your installation:

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

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

3. Set the value for JAVA13_HOME in the .login file to the directory where you installed the JDK. For example:

   JAVA13_HOME=/private/mobile/jdk1.3
   
   

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

   ORACLE_HOME=/private/orahome1
   
   

1.2.2 Installing the Mobile Server on Top of Oracle9i Application Server 2.0 (9iAS)

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.

1.2.3 Installing the Mobile Server

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

   
   

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

   
   

3. 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 1.0.2.2.0 or the Oracle9i database. Select the Next button.

   Figure 1-3 Mobile Server Installation Types Screen

   
   

4. 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 1.0.2.2.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 1.0.2.2.0, using the Oracle 8.1.7 libraries, select only the "Oracle9i Lite Mobile Server 2.0.3.0.0" component as shown in Figure 1-4. Select the Next button.

   Figure 1-5 Mobile Server Repository Database Information Screen

   
   

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

   
   

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

   
   

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

   
   

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

   
   

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

   
   

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

    
    

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

    
    

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

    
    

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

    
    

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

    
    

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

1.3.1 Migrating the Mobile Server Repository Manually

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:

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

   
   

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

   
   

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

   
   

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

1.3.2 File Migration to the Existing File System

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.

1.3.3 User Migration to the Oracle Internet Directory (OID)

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.

1. From a command line, enter the following:

   oiduser <Mobile Server repository user name> <password>
   
   

   For example the default setting would be:

   oiduser mobileadmin manager
   
   

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

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

4. Restart the Mobile Server.

1.3.4 Migration Troubleshooting

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.

SELECT * FROM DEPT WHERE DEPT_NAME =:DEPT_NAME

SELECT * FROM DEPT WHERE DEPT_NAME = RPAD(:DEPT_NAME,<length of column>)

1.4.1 Configuring the Mobile Server Module for Oracle9i Application 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 1.0.2.2.0 you should perform Step 1 and Step 6, skipping Steps 2–5. Steps 2–5 configure your instance of Mobile Server to run as a module of Oracle9iAS version 2.0, and Steps 1–6 are required.

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

   <Oracle9iAS_DIR>/Apache/Apache/conf/httpd.conf
   
   

   where <Oracle9iAS_DIR> is the directory where you installed Oracle9iAS.

   For example, if you installed Oracle9iAS in the location:

   /Program Files/Oracle9iAS
   
   

   then the full path to the configuration file would be:

   /Program Files/Oracle9iAS/Apache/Apache/conf/httpd.conf
   
   

   Add the Mobile Server Module for Oracle9i Application Server by adding the following line at the very end of the Oracle9iAS configuration file:

   include "<ORACLE_HOME>/mobile/server/bin/wtgias.conf" 
   
   

   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.

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

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

4. Open the file <ORACLE_HOME>/config/jazn-data.xml, search for webtogo.jar and edit the following line, replacing Mobile/Server with mobile/server, to make the leading characters lower case:

   From:

   <url>file:/private/<user_name>/<ORACLE_HOME>/Mobile/Server/bin/webtogo.jar</url>
   
   

   to:

   <url>file:/private/<user_name>/<ORACLE_HOME>/mobile/server/bin/webtogo.jar</url>
   
   

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

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

1.4.2 Configuring the Mobile Server to Run in Standalone Mode

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:

>webtogo

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:

>webtogo -d

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:

>webtogo -d0

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.

1.5.1 Logging into the Mobile Server

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.

1.5.1.1 User Name and Password Security

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:

1. Start the Mobile Server Listener.

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

1. Enter the administrator's user name and password for the Mobile Server Repository.

   Figure 1-22 Invalid Password Screen

   
   

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

   
   

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

1.5.2 Changing a Password for the Mobile Server Repository

To change a password for the Mobile Server Repository:

1. In the Menu Options screen, select Change. The Change Password screen appears as shown in Figure 1-24.

   Figure 1-24 Change Password Screen

   
   

2. Enter the current password in the Old Password field.

3. Enter the new password in both of the New Password fields.

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

1.5.3 Shutting Down the Mobile Server

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:

1. From the Menu Options screen, Figure 1-23, select the Shutdown option.

   Figure 1-25 Mobile Server Options Menu While Terminating

   
   

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

   
   

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

   
   

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

   
   

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