To demonstrate the steps involved in building Mobile applications for the Win32 platform, this tutorial presents a simplified Mobile field service example. The following sections guide you through the Mobile application development process for the Win32 platform. When developing, you can use Visual Studio 2003.
Let us assume that you have a TASK
table on the server that contains information about tasks that must be accomplished by your Mobile field service technicians for a day. Listed below is the TASK
table structure. Each row in the TASK
table describes work to be done at a customer site.
TASK(ID number(4) primary key
Description varchar(40) not null
CustName varchar(30) not null
CustPhone varchar(12)
CustStAddr varchar(40) not null
CustCity varchar(40) not null
Notes varchar(100)
Let us also assume that you have three service technicians, Tom, Dick, and Harry. You want to assign all the tasks in the City of Cupertino to Tom, those in the City of Mountain View to Dick, and those in the City of Palo Alto to Harry. You envision your application to work as follows:
Each service technician has a laptop that he uses to obtain his task list in the morning. He will perform the task during the day and will update the Notes column of a task with information about its status or what he has done. At the end of his work day, the service technician uploads his changes to the server.
We will assume the following environment for your application.
The Mobile Server is installed on the machine called mserver
.
The test Oracle database that is used to store the application data and the Mobile Server Repository is installed on the machine oradbserver
with the listener on port 1521. The Oracle database instance name is orcl
. We will assume that you can log in to the database with the user name master
and password master
. You can substitute any user for master
so long as the user has the right privileges.
You have already installed the Mobile Development Kit on your development machine.
Our implementation plan is as follows. The exact sequence of commands for each step is given later.
Create the TASK
table in the oradbserver
and insert some rows into it. This step is not needed if you already have a database that contains a table similar to TASK
.
Use MDW to create a publication that contains a single publication item based on the TASK
table.
Use the Packaging Wizard to define and publish the Mobile Field Service application to the Mobile Server.
Use the Mobile Manager to create users Tom, Dick, and Harry on the Mobile Server. Grant all users the privilege to execute the Mobile Field Service application and create a subscription for each of them.
Install the Oracle Database Lite 10g client on your development machine in a separate directory (emulating a technician's machine). Run the Mobile Sync application to download the Mobile Field Service application (which is currently empty) and data.
On your development machine, use mSQL to look at the rows in the TASK
snapshot and update the rows by entering notes in the Notes column.
Synchronize the changes you made in the snapshot with the server database by running the Mobile Sync application again.
Connect to the server database and check that your changes are there. Modify the Description of one of the rows for the customer in Cupertino.
Run the Mobile Sync application again. You will see the changes that you made on the server are in the snapshot in the client database.
Develop a C or C++ program against Oracle Database Lite to:
show the tasks to the technician, and
let the technician choose a task and enter notes for it
Use the Packaging Wizard to update the application to include the above program.
The Mobile Server is now ready for real life testing.
The following sections describe the command sequence for successfully creating the Win32 demo:
We will use the Oracle 10g thin JDBC driver to connect to the Oracle database running in the oradbserver
machine. Ensure that the thin JDBC driver (<ORACLE_HOME
>\jdbc\lib\ojdbc14.jar
) file is included in your CLASSPATH
environment variable. Connect as master
with password master
.
D:>msql master/master@jdbc:oracle:thin:@oradbserver:1521:orcl
Now create the TASK
table in this database. The SQL script to create and populate the server database is provided in the following directory.
<ORACLE_HOME
>\mobile\sdk\samples\odbc\win32\MFS
SQL>create table TASK( 1> ID number(4) primary key, 2> Description varchar(40) not null, 3> CustName varchar(30) not null, 4> CustPhone varchar(12), 5> CustStAddr varchar(40) not null, 6> CustCity varchar(40) not null, 7> Notes varchar(100));
We will now insert four rows into this table.
SQL> insert into task values(1,'Refrigerator not working','Able','408-999-9999','123 Main St.','Cupertino',null); SQL> insert into task values(2,'Garbage Disposal broken','Baker','408-888-8888','234 Central Ave','Cupertino',null); SQL> insert into task values(3,'Refrigerator makes noise','Choplin','650-777-7777','1 North St.','Mountain View',null); SQL> insert into task values(4,'Faucet leaks','Dean','650-666-6666','10 University St.','Palo Alto','Beware of dogs'); SQL> commit; SQL> exit
As described fully in Chapter 5, "Using Mobile Database Workbench to Create Publications", you can use MDW to create your publication. Launch MDW by executing oramdw
from <ORACLE_HOME>
/Mobile/Sdk/bin
. The following sections detail how to use MDW to create a publication for the application in this tutorial.
Note:
While creating this publication, use Chapter 5, "Using Mobile Database Workbench to Create Publications" for a deeper understanding of how to use MDW and the type of information that you must provide.Create a new project for this application by selecting File->New->Project. This brings up a wizard where you enter the following information:
Note:
For more information, see Section 5.2, "Create a Project".Define a name and location for the project.
Enter the username, password, JDBC driver type, database host, database port and database SID for the Mobile repository. Username and password are master/master
, and the database URL is jdbc:oracle:thin:@oradbserver:1521:orcl
.
Provide the Mobile Repository access information. Because you are interacting with the repository to create and manipulate synchronization objects, including the SQL scripts for the publication items, you need access to the Mobile Repository.
Specify schema username and password. Enter the user and password of the schema owner for the schema that you are using for the Mobile application. The Mobile application schema contains all database tables, views, synonyms used to build the snapshots for the application.
Verify the information that you entered and click Finish.
For this project, you need to create the taskpi
publication item.
Note:
For more information, see Section 5.4, "Create a Publication Item".Perform the following to create the publication item:
Start the new publication item wizard by selecting File->New->Publication Item.
Enter the name as taskpi
and the type as Fast
. If you want this publication item to use automatic synchronization, make sure that the "Enable Automatic Synchronization" checkbox is checked. Uncheck to use manual synchronization. Click Next.
Select the schema name as MASTER
, the object type as Table
, and leave the object filter blank. Click Search. When the search ends, select the task
table from the object list. Click Next.
Click >> to select all of the columns in the task
table. Click Next.
In the Query tab, select Edit to edit the query, as follows:
select * from master.task where CustCity = :city
Click Next.
If you checked the 'Enable Automatic Synchronization' checkbox, then an additional screen comes up. This screen enables you to specify users included in the compose. By default, all users are included. Leave checkbox unchecked and click Next.
The Summary page displays. Click Finish.
When you have completed the creation of the publication items, create the publication within the project by selecting File->New->Publication.
In the General tab, enter the name as task
, which becomes part of the DSN for the client-side database.
In the Publication Item tab, click Add to add the publication item that you just created with the following configuration:
Name: task Updatability: Updatable Conflict Resolution: Server Wins DML Callback: BLANK Grouping Function: BLANK Priority Condition: BLANK My Compose: BLANK Weight: 1 Description: Blank
In the Events tab, set the thresholds for Automatic Synchronization rules, as follows:
Sync if number of modified records in database exceeds threshold value
Sync if number of modified records in out queue exceeds threshold value
Save the publication by selecting File->Save.
Using the Packaging Wizard, you can package and publish the Task application into the Mobile Server.
Note:
For full details on how to use the Packaging Wizard, see Chapter 7, "Using the Packaging Wizard".You can select and describe the Task application by launching the Packaging Wizard, as follows:
Start the Packaging Wizard, as follows:
cd <ORACLE_HOME>\Mobile\Sdk\bin
runwtgpack
The Packaging Wizard appears and provides you with the option to create a new application, edit an existing application, delete an existing application, or open a packaged application, as displayed in Figure 19-1.
Note:
Deleting an existing application merely deletes the application from the XML file and does not remove the application from the Mobile Server.Select the Create a new application option and click OK.
The Select a Platform panel appears. As Figure 19-2 displays, this panel enables you to specify the platform for your application. Select Oracle Lite WIN32;US from the Available Platform list. Click Next.
As Figure 19-3 displays, the Application panel appears. Use the Application panel to modify "Mobile Field Service" application settings. As Table 19-1 describes, enter the specified values in the corresponding fields.
Table 19-1 The Task Application Values
Field | Value |
---|---|
Application Name |
Mobile Field Service |
Virtual Path |
/MFS |
Description |
Field Service Task Assignment |
Local Application Directory |
|
Publication Name |
Click on Browse. The 'Connect to database' window appears. Enter the following:
The next window shows the available publications. Select |
Click Next. As Figure 19-4 displays, the Files panel appears. Using the Files panel, you can select files that are part of the application. The Packaging Wizard uploads the selected files from the local application directory to the application repository on the Mobile Server.
The Files panel identifies files that the Packaging Wizard uploads from the local application directory to the application repository on the Mobile Server.
Click Next till you arrive at the Application Definition Completed Dialog as shown in Figure 19-5.
Figure 19-5 Application Definition Completed Dialog
Using the Application Definition Completed panel, you can package the "Task" application into a JAR file. The Application Definition Completed Dialog remains open for you to initiate application packaging.
Select the Create files option and select both the Package Application into a JAR file and Generate SQL scripts for database objects boxes.
At this stage, the Save the Application dialog prompts you for the name of the JAR file, which is Mobile_Field_Service.jar
.
After choosing the JAR file, click OK. The JAR file is created and contains the application files and definition.
Back in the Application Definition Completed dialog, select the Publish the Current Application option and click OK.
The Publish the Application dialog appears. As Table 19-2 describes, enter the specified values.
Note:
The Mobile Server must be up for successful publishing.Table 19-2 Publish the Application Dialog Description
Field | Description | Value |
---|---|---|
Mobile Server URL |
URL or IP Address of the machine where the Mobile Server is running. |
|
Mobile Server User Name |
User name of the Mobile Server user with administrative privileges. |
Administrator |
Mobile Server Password |
Password of the Mobile Server user with administrative privileges. |
admin |
Repository Directory |
Directory name where all files for this application will be stored inside the Mobile Server Repository. |
|
Public Application |
Do not select this check box unless you want to make this application available to all users. |
Clear |
To publish the application in the Mobile Server Repository, click OK. A dialog displays the application publishing status. You must wait until the application is published.
To confirm that the application is published successfully, click OK.
To exit the Packaging Wizard, click Exit.
You have now completed packaging and publishing your application.
This section describes how to administer the application that you created and deployed through the following tasks.
Section 19.3.1, "Start the Mobile Server and the Mobile Manager"
Section 19.3.2, "Using the Mobile Manager to Create New Users for the Task Application"
Section 19.3.5, "Defining Snapshot Template Values for the User"
For more information about Mobile Manager tasks described in this tutorial, see the Oracle Database Lite Administration and Deployment Guide.
The Mobile Manager is a Web-based application that enables you to administer Mobile Server applications. To start the Mobile Manager, perform the following steps:
Using the command prompt, go to the following directory.
<ORACLE_HOME>\Mobile\Server\bin
To start the Mobile Server for the first time and subsequent occasions, execute the runmobileserver
command.
Start your Web browser and connect to the Mobile Server by enter the following URL:
http://<mobile_server>/webtogo
Note:
Replace<mobile_server>
with the host name of your Mobile Server.Log on as the Mobile Server Administrator using administrator
as the User Name and admin
as the Password.
To launch the Mobile Manager, click the Mobile Manager link in the workspace.
Click the Mobile Server link.
Click the Applications link. As Figure 19-7 displays, the Applications page appears. Locate the Task application, which shows all applications that are published.
For the Task application, create users Tom, Dick and Harry. We only show how to create the user Tom in the following steps:
On the Mobile Manager home page, click the Users link. As Figure 19-8 displays, the Users page appears.
Click Add User. As Figure 19-9 displays, the Add User page appears.
As described in Table 19-3, enter the following information in the Add User page and click Save.
Repeat these steps to create the Dick and Harry users.
To set the Task application properties, perform the following steps:
On Mobile Manager home page, click the Applications link. The Applications page appears.
To search for the application that you just published, enter Task in the Application Name field and click Search. The Task application appears in the workspace.
Note:
To display all the available applications, leave the search field blank and click Search. This action generates a list of all the available Mobile Server applications in the workspace.Click the Task application link. As Figure 19-10 displays, the Application Properties page lists application properties and database connectivity details.
In the Database Password field, type the application demo schema password. In the past, this password was master
. Click Apply. The Mobile Manager displays a confirmation message.
To grant the Tom, Dick and Harry users access to the Task application, perform the following steps:
Navigate to the Application Properties page and click the Access link. As Figure 19-11 displays, the Access page lists groups and users that are associated with the application. The check boxes on this page indicate whether or not the user or group has access to the application.
Under the Users table, locate the Tom, Dick and Harry users and select the check boxes for these users.
Click Save. The Mobile Manager displays a confirmation message. The users have now been granted access to the Task application.
Define the snapshot template variables for the users, Tom, Dick and Harry. For the Mobile Field Service application, we have only one publication item and it has only one subscription parameter called city
.
To modify a user's Data Subsetting parameters, perform the following steps:
Navigate to the Applications page and click the Task application link. The Application Properties page appears. Click the Data Subsetting link. As Figure 19-12 displays, the Data Subsetting page appears.
Under the User Name column, click the user name link Tom
. As Figure 19-13 displays, the Data Subsetting Parameters page appears.
Figure 19-13 Data Subsetting Parameters Page
Select the city
parameter and enter the value Cupertino
. Click Save. The Mobile Manager displays a confirmation message. Click OK.
Repeat these steps for Dick and Harry. For more information about snapshots, refer to the Oracle Database Lite Administration and Deployment Guide.
This section describes how to set up a Mobile client to use the application that you created and tested in the Development section, deployed in the Deployment section, and then administered in the Administration section.
In this section, you will perform the following tasks:
Section 19.4.1, "Install the Mobile Client on the Win32 Device"
Note:
You must install the application and test it on a separate machine from the Mobile Server.Section 19.4.3, "Develop your Mobile Field Service Application Using Oracle Database Lite"
Section 19.4.4, "Republish the Application with the Application Program"
You must install the Mobile client before you can use the application that you created and deployed.
Note:
You must install the Mobile Client on a machine which does not host the Mobile Server installation.To install the Mobile Client for Win32, perform the following actions:
Start your Web browser and connect to the Mobile Server by entering the following URL.
http://<mobile_server>/webtogo/setup
As Figure 19-14 displays, the Mobile Client Setup page lists a set of Mobile clients by platform. To download the Mobile Client for Win32 setup program, click the Oracle Lite WIN32 link.
Note:
While installing the Mobile Client, you will be prompted for the User name and Password. EnterTom
as the user name and tomjones
as the password.If you are using Netscape, choose a location to save the setup program and click OK. In Windows Explorer, double-click setup.exe
to run the setup program.
If you are using Internet Explorer, run the setup program from your browser window.
While installing the Mobile Client, you will be prompted for the user name and password. Enter Tom
as the user name and tomjones
as the password.
The setup program prompts you to choose an installation directory for the Mobile client, such as D:\MFS
, and downloads all the required components and starts the Mobile client on your machine. Browse the directory and familiarize yourself with its structure.
Perform the initial synchronization to bring down the first snapshot and create the Oracle Lite database. Start the Command Prompt and enter the following:
D:\MFS\Mobile\bin>msync
This executes the Mobile Sync application, downloaded as part of the application installation. You can also execute the Mobile Sync application located in the \sdk\bin
directory.). When the dialog appears, enter the following information:
User Name: Tom
Password: tomjones
Server: mserver
Click the Sync button. A message box appears showing the progress of synchronization. When the synchronization process is complete, click the Cancel button on the Mobile Sync application dialog.
You now have an Oracle Database Lite database on your development machine. It contains a snapshot called TASK
which has two rows in it; both rows have Cupertino
for the CustCity
column. These are the service requests by customers in Cupertino and Tom has been assigned these tasks.
The initial synchronization process also created an ODBC data source name (DSN) called tom_mfs
(the user name followed by the underscore character followed by the database name).
You can update a row in the Task snapshot, as follows:
D:>MFS\Mobile\bin>msql system/manager@jdbc:polite:tom_mfs SQL> select * from task;
The following two rows are displayed.
SQL> update task set Notes ='Replaced the motor:$65' where ID = 1; 1 row(s) updated SQL> commit; commit complete SQL> exit
You have successfully updated a row of the TASK
snapshot. Perform another synchronization to upload the changes to the server.
An example ODBC program called MFS.exe
is provided with the Mobile Development Kit in the following directory:
<
ORACLE_HOME>\Mobile\Sdk\samples\odbc\win32\mfs\
The\src
directory contains the source and the makefile for it.
This example displays the task list and prompts the user to enter the Task ID for the chosen task, before entering notes. When the user enters the Task ID value as -1, the program terminates. For any valid Task ID, the MFS application prompts the user to enter notes. Enter notes without using quotes. You can try to improve the example as required.
To republish this program to the Mobile Server, copy the mfs.exe
file into the directory D:\MFSDEV\Win32
.
Use the Packaging Wizard to republish the application, as follows:
From the Command Line, enter the following:
D:>runwtgpack
Select the "Edit an existing application" option. From the drop down list, select "Mobile Field Service" and click the OK button.
Click the Files tab. As shown in Figure 19-15, verify that the mfs.exe
file is listed in the "File Name" window and click Finish.
Select the "Publish the current application" option and click OK. You will be prompted to enter the login information for the Mobile Server. Click OK after entering the information. A message box warns you that the application already exists on the Mobile Server and asks whether you want to overwrite it. Click YES.
If you get the message "Application Published Successfully", click OK and then click EXIT. You have successfully republished an application that has a file called mfs.exe
and one publication item.
Test your application by using a fresh Windows 32 machine. Follow Step 4 to install the Oracle Database Lite 10g client and the Mobile Field Service application on the machine. Then execute the Mobile Field Service application by executing the D:\MFS\Mobile\oldb40\TOM\mfs.exe
program, as follows:
D:\MFS\Mobile\oldb40\TOM\mfs.exe TOM_MFS system manager
When TOM
is the user. Enter notes for one of the tasks. Then execute D:\MFS\Mobile\bin\msync.exe
to synchronize your changes with the server.