Skip Headers

Oracle® Database Lite Oracle Lite Client Guide Release 10.3 Part Number E12548-02 |
Home | Book List | Contents | Index | Contact Us

Previous | Next
| View PDF

# 5 Building a Client/Server Environment

If you want multiple clients to access an Oracle Lite database, you need to configure a client/server environment. The following sections describe how to configure this environment with the multi-user service:

- Section 5.1, "Overview of the Multi-User Service"

- Section 5.2, "Administration for the Multi-User Service on the Windows Platform"

- Section 5.3, "Administration for the Multi-User Service on the Linux Platform"

- Section 5.4, "Debugging the Multi-User Service"

- Section 5.5, "Creating DSNs"

- Section 5.6, "Accessing the Database"

- Section 5.7, "Verifying the Connection Using mSQL"

## 5.1 Overview of the Multi-User Service

Multiple clients can execute an application that accesses the same database. You can protect all of your data on a centralized machine and allow clients to remotely access the information within the database.

Figure 5-1 demonstrates how to centralize multiple Oracle Lite databases (ODB files) by installing them on a Windows or Linux host machine. The Oracle Database Lite multi-user service facilitates the communication between the remote application clients by starting the multi-user service, which opens the designated ports, and then translates the DSNs to the appropriate database.

Figure 5-1 Diagram of Multi-User Service

Description of "Figure 5-1 Diagram of Multi-User Service"

The multi-user service enables you to use up to sixty-four concurrent client connections, each of which can connect to up to five `ODB` database files on the remote machine. All clients and server must install the same binary with the same NLS. The server machine with the multi-user service and each of the clients can be installed on either Windows or Linux platforms.

When you implement the client/server data access for your application, the flow of events is as follows:

1. Remote client sends the connect request to the multi-user service.

   The client connection can use the ODBC 2.0 client driver, the JDBC Type 2 MU driver, or the JDBC Type 4 driver. In addition, the client provides the following in the connection string: remote host and port where the multi-user service is listening for incoming calls and the DSN of the Oracle Lite database (ODB file) where the data is stored. The default port number is 1160.

2. Multi-user service receives incoming call with the DSN from the remote client.

3. The multi-user service parses the DSN name and completes the request by connecting to the Oracle Lite database that maps to the DSN name.

You can provide a client/server environment for multiple users accessing a single entry point for the Oracle Lite database with the multi-user service. For the multi-user service, you first create the application and the database in the same manner as the embedded application, as described in Chapter 4, "Building an Embedded Application". Then, configure for a client/server environment and set up a listener to receive requests from each of these clients. The difference between an embedded application and the client/server options is that you will configure two DSNs: one for the client and one for the server. The DSN for the server is the same as the one configured for the embedded application.

## 5.2 Administration for the Multi-User Service on the Windows Platform

The following sections describe how to install, start, stop and query the multi-user service on Windows:

- Section 5.2.1, "Installation and Configuration on Windows"

- Section 5.2.2, "Starting the Multi-User Service on Windows"

- Section 5.2.3, "Stopping the Multi-User Service on Windows"

- Section 5.2.4, "Querying the Multi-User Service on Windows"

### 5.2.1 Installation and Configuration on Windows

To install and configure the Oracle Database Lite multi-user service, perform the following steps:

1. Ensure that you install the `olsv2040.exe` in the following directory.

   <`OLITE_HOME``>\Mobile\Sdk\bin`

   Note:

   This directory must also be included in your system `PATH`.

   If not already available, re-install the MDK to retrieve the component. A sample <`OLITE_HOME`> location is `C:\Olite`.

2. To install the service, start the Command Prompt and enter the following command.

       olsv2040.exe /install [/account=AccountName][/password=ValidPassword]
           [/wdir=WorkingDirectory] [/port=ServicePort]

   where the optional parameters can be as follows:

   - `AccountName`: Provide either the `DomainName\UserName` or `.\UserName`.

   - `ValidPassword`: If you specify an account, but don't want to give out the password in command prompt during service installation. You can provide the password to the "Log On" page of "Oracle Lite Multiuser Service Properties" dialog box which can be found in Services.

   - `WorkingDirectory`: If you use '`.`' in SQL scripts that load Java classes, you must specify a working directory.

   - `ServicePort`: The default port number is 1160.

3. If you are using Java Stored Procedures, then perform the following to set up the environment for Java Stored Procedures:

   1. If you have the JDK installed on your PC, ensure that the system `PATH` variable includes the following:

          <JDK_HOME>\bin
          <JDK_HOME>\jre\bin
          <JDK_HOME>\jre\bin\hotspot

   2. If you have JRE installed on your PC, ensure that the system `PATH` variable includes the following:

          <JRE_HOME>\bin
          <JRE_HOME>\bin\hotspot

      Note:

      JRE does not include the Java compiler. Therefore, attempts to load a Java source into the database with the `CREATE JAVA SOURCE` command and the `loadjava` utility will fail without the Java compiler.

   3. Ensure that your system `CLASSPATH` variable includes the following:

          <OLITE_HOME>\bin\Olite40.jar and '.'

4. You may change the startup type from the Windows service console. Highlight the Oracle Database Lite multi-user service and select Properties. When required, change the startup type to manual. The property also contains startup parameters, but has not been tested.

5. Reboot your PC.

### 5.2.2 Starting the Multi-User Service on Windows

The Oracle Database Lite multi-user service can be started in many ways. By default, the service property "Startup Type" is automatic; thus, the service is started every time you reboot the machine. If you modify the "Startup Type" to "Manual", then you start Oracle Lite multi-user service by entering any one of the following startup commands from the Command Prompt:

- `olsv2040.exe /start`

- `net start "Oracle Lite Multiuser Service"`

### 5.2.3 Stopping the Multi-User Service on Windows

To stop the multi-user service, use one of the following commands:

- `olsv2040.exe /stop`

- `net stop "Oracle Lite Multiuser Service"`

### 5.2.4 Querying the Multi-User Service on Windows

You can query the multi-user status for the following details:

- current status

- current startup parameters

- configuration

- installed startup parameters

Issue the following command to see these details:

    olsv2040.exe /query

The results of this command are as follows:

    OliteService reports the following status:
      The service is running...
         port= 1160
         wdir = C:\WINDOWS\SYSTEM32

    The current status of Oracle Lite Multiuser Service:
      Current State              : SERVICE_RUNNING
      Acceptable Control Code    : (0x1) SERVICE_ACCEPT_STOP

    The configuration of Oracle Lite Multiuser Service:
      Service Type    : (0x10) SERVICE_WIN32_OWN_PROCESS
      Start Type      : SERVICE_AUTO_START
      Error Control   : SERVICE_ERROR_NORMAL
      Binary Path     : C:\Oracle\product\Mobile\Sdk\bin\olsv2040.exe
      Display Name    : Oracle Lite Multiuser Service
      Start Name      : LocalSystem

    Installed Service startup parameters
      port = 1160
      wdir = \%WINDIR%\SYSTEM32

where the port number is 1160 and the working directory is `C:\WINDOWS\SYSTEM32`. The service is installed under the `LocalSystem` account, where the startup parameters for installation are port = 1160 and working directory = `\%WINDIR%\SYSTEM32`. In addition, the Start Type is `SERVICE_AUTO_START` and the binary path as `C:\Oracle\product\Mobile\Sdk\bin\olsv2040.exe`, which is where you installed the Oracle Database Lite multi-user service.

You can also set the default for the service port and working directory by modifying the `SERVICE_PORT` and `SERVICE_WDIR` parameters in the `polite.ini` file. However, if you do so, then it overrides any of the command-line options for port and working directory.

Note:

When you execute the multi-user service with the `/debug` option, then the result of the current status from the `/query` shows that the service is stopped. Since the `/debug` option is executed in a console, the Service Control Manager does not know that the service is running.

## 5.3 Administration for the Multi-User Service on the Linux Platform

The following sections describe how to start, stop and query the multi-user service on Linux:

Note:

There is no need to install this service on Linux.

- Section 5.3.1, "Starting and Stopping the Multi-User Service on Linux"

- Section 5.3.2, "Querying the Multi-User Service on Linux"

### 5.3.1 Starting and Stopping the Multi-User Service on Linux

The Oracle Database Lite multi-user service can be started or stopped with the `olsv` executable. To see all of the options, execute `olsv -help`, which displays the following:

    $ olsv -h
    Usage: olsv [option]
    Options are:
    -start start the server as daemon
    -stop | -s stop the server
    -debug | -d start the server as console app for debugging
    -query | -q get the server status
    -kill | -k equivalent to kill -s SIGKILL PID
    -port | -p PORT execute the server on the specified port——default port is 10000
    -wdir | -w DIR run/debug the server in the specified dir
    -help | -h display this message
    if no option specified, -start by default

To stop the multi-user service, use the following command:

    olsv -stop

### 5.3.2 Querying the Multi-User Service on Linux

You can query the multi-user status with `olsv -query` which provides the following information:

- process id (PID)

- environment variables

- current status

Issue the following command to see these details:

    olsv -query

The results of this command are as follows:

    Oracle Lite Multiuser Server is running, PID = 2619
    ----------------------------------------------------------------------
    Environment:
    TERM=xterm
    SHELL=/bin/csh
    OLITE_HOME=/scratch/myuser/oracle/OraHome/mobile/sdk
    JDKDIR=/usr/local/packages/jdk14
    MOBILE_CLIENT=/scratch/myuser/mobileclient
    USER=myuser
    LD_LIBRARY_PATH=/usr/local/packages/jdk14/jre/lib/i386:/usr/local/packages/jdk14/jre/lib/i386/server:/scratch/myuser/olite/lib
    HOSTTYPE=i386-linux
    JAVA_HOME=/usr/local/packages/jdk14
    LANG=en_US.UTF-8
    HOME=/home/myuser
    OSTYPE=linux
    LOCAL_PACK=/usr/local/packages/icc_remote
    JAVA_HOME=/usr/local/packages/jdk14
    VENDOR=intel
    MACHTYPE=i386
    ORACLE_HOME=/scratch/user/oracle/OraHome
    CLASSPATH=.:/scratch
    ---------------------------------------------------------------------- Status Summary:
    Database Version: 10.3.0
    Time Started: 11-27-2006 17:58:15
    Listening Port: 10000
    Total Connections: 0
    Current Connections: 0
    No errors encountered

You can also set the default for the service port and working directory by modifying the `SERVICE_PORT` and `SERVICE_WDIR` parameters in the `polite.ini` file. However, if you do so, then it overrides any of the command-line options for port and working directory.

## 5.4 Debugging the Multi-User Service

If the service the does not start, debug the service using the following method:

1. Edit the `POLITE.INI` file, which is available in Windows under `%WINDIR%\POLITE.INI` and in Linux under `$OLITE_HOME/bin`, to add the following entries in the `[ALL_DATABASES]` section:

   - `OLITE_SERVER_TRACE=TRUE`

   - `OLITE_SERVER_LOG=<filename>`. This is used for the LINUX platform only.

   Note:

   For more details on these parameters, see Section A.2, "All Databases Section".

2. Should the service fail, the multi-user service generates the `olsv.log` file in the current working directory. Ensure that the `PATH` and `CLASSPATH` variables are accurate and that the `PATH` includes the directory that contains `jvm.dll`.

3. Correct the cause and retry.

## 5.5 Creating DSNs

To access the database using an ODBC or Visual Basic application, you must create the DSN enabled from the embedded connection. When you add a DSN using the ODBC Administration tool, choose the Oracle Lite 40 ODBC Driver(Client), which creates a client DSN. If you are executing the service on the same machine where the client application is running, leave the Database Host Name, Database Port Number, and Database Host DSN value empty. The remaining values must be included in the same manner as the 'Oracle Lite ODBC Driver' DSN. If you start the service on a port other than 1160, then you must specify the Database Port Number.

## 5.6 Accessing the Database

To access the database, you need not make any changes to the ODBC or VisualBasic application. The DSN automatically routes the request to the service through the ODBC driver `olcl2040.dll`. For a JDBC application, change the URL for the connect string, which is similar to the one used while connecting to the database using mSQL.

## 5.7 Verifying the Connection Using mSQL

Using the Command Prompt, verify the connection to the multi-user service in the following ways:

Connect to `A-DSN` on a Windows local host on port 1160.

    msql system/passwd@jdbc:polite@::a-dsn

Connect to `A-DSN` on the local host on port 1000.

    msql system/passwd@jdbc:polite@:1000:a-dsn

Connect to `A-DSN` on a Windows local host on port 1160 using the Type4 JDBC driver.

    msql system/passwd@jdbc:polite4@::a-dsn

Note:

Oracle Database Lite supports Type2 and Type4 JDBC drivers. Type4 is a pure Java JDBC driver that communicates with the service in the Oracle Database Lite network protocol.

For more information on Type 2 and Type 4 JDBC drivers connecting to Oracle Database Lite, see Chapter 10, "JDBC Programming". For details on mSQL, see Chapter C, "The mSQL Tool".