Tutorial for Building Mobile Applications for Win32 19-1

19
Tutorial for Building Mobile Applications for
Win32
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.
Section 19.1, "Plan the Mobile Application Demo for Win32"
Section 19.2, "Description of Tasks for Win32 Demo"
Section 19.3, "Administer the Application"
Section 19.4, "Execute the Application on the Mobile Client for Web-to-Go"
19.1 Plan the Mobile Application Demo for Win32
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.
Description of Tasks for Win32 Demo
19-2 Oracle Database Lite Developers Guide
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.
1. 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.
2. Use MDW to create a publication that contains a single publication item based on
the TASK table.
3. Use the Packaging Wizard to define and publish the Mobile Field Service
application to the Mobile Server.
4. 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.
5. 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.
6. 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.
7. Synchronize the changes you made in the snapshot with the server database by
running the Mobile Sync application again.
8. 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.
9. 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.
10. 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
11. Use the Packaging Wizard to update the application to include the above program.
The Mobile Server is now ready for real life testing.
19.2 Description of Tasks for Win32 Demo
The following sections describe the command sequence for successfully creating the
Win32 demo:
1. Section 19.2.1, "Create TASK Table on the Server Database"
2. Section 19.2.2, "Create Publication for Application"
3. Section 19.2.3, "Package the Application Using the Packaging Wizard"
Description of Tasks for Win32 Demo
Tutorial for Building Mobile Applications for Win32 19-3
19.2.1 Create TASK Table on the Server Database
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
19.2.2 Create Publication for Application
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.
Section 19.2.2.1, "Create a Project"
Section 19.2.2.2, "Create Publication Item"
Section 19.2.2.3, "Create Publication"
19.2.2.1 Create a Project
Create a new project for this application by selecting File->New->Project. This brings
up a wizard where you enter the following information:
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.
Description of Tasks for Win32 Demo
19-4 Oracle Database Lite Developers Guide
1. Define a name and location for the project.
2. 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.
3. 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.
4. Verify the information that you entered and click Finish.
19.2.2.2 Create Publication Item
For this project, you need to create the taskpi publication item.
Perform the following to create the publication item:
1. Start the new publication item wizard by selecting File->New->Publication Item.
2. 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.
3. 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.
4. Click >> to select all of the columns in the task table. Click Next.
5. In the Query tab, select Edit to edit the query, as follows:
select * from master.task where CustCity = :city
Click Next.
6. 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.
7. The Summary page displays. Click Finish.
Note: For more information, see Section 5.2, "Create a Project".
Note: For more information, see Section 5.4, "Create a Publication
Item".
Description of Tasks for Win32 Demo
Tutorial for Building Mobile Applications for Win32 19-5
19.2.2.3 Create Publication
When you have completed the creation of the publication items, create the publication
within the project by selecting File->New->Publication.
1. In the General tab, enter the name as task, which becomes part of the DSN for the
client-side database.
2. 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
3. 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
4. Save the publication by selecting File->Save.
19.2.3 Package the Application Using the Packaging Wizard
Using the Packaging Wizard, you can package and publish the Task application into
the Mobile Server.
You can select and describe the Task application by launching the Packaging Wizard,
as follows:
1. 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 191.
Note: For full details on how to use the Packaging Wizard, see
Chapter 7, "Using the Packaging Wizard".
Note: Deleting an existing application merely deletes the application
from the XML file and does not remove the application from the
Mobile Server.
Description of Tasks for Win32 Demo
19-6 Oracle Database Lite Developers Guide
Figure 191 Make a Selection Dialog
2. Select the Create a new application option and click OK.
3. The Select a Platform panel appears. As Figure 192 displays, this panel enables
you to specify the platform for your application. Select Oracle Lite WIN32;US
from the Available Platform list. Click Next.
Figure 192 Selecting a Platform
4. As Figure 193 displays, the Application panel appears. Use the Application panel
to modify "Mobile Field Service" application settings. As Table 191 describes,
enter the specified values in the corresponding fields.
Description of Tasks for Win32 Demo
Tutorial for Building Mobile Applications for Win32 19-7
Figure 193 Application Panel
5. Click Next. As Figure 194 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.
Table 191 The Task Application Values
Field Value
Application Name Mobile Field Service
Virtual Path /MFS
Description Field Service Task Assignment
Local Application Directory D:/MFSDEV
Publication Name Click on Browse. The Connect to database window appears.
Enter the following:
username: mobiladmin
password: welcome123
database URL:
jdbc:oracle:thin:@<hostname>:<port>:<SID>
The next window shows the available publications. Select
task.
Description of Tasks for Win32 Demo
19-8 Oracle Database Lite Developers Guide
Figure 194 Uploading Application Files
6. Click Next till you arrive at the Application Definition Completed Dialog as
shown in Figure 195.
Figure 195 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.
a. 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.
Administer the Application
Tutorial for Building Mobile Applications for Win32 19-9
Figure 196 Save the Application Dialog
After choosing the JAR file, click OK. The JAR file is created and contains the
application files and definition.
b. 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 192 describes, enter the
specified values.
c. 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.
d. To confirm that the application is published successfully, click OK.
e. To exit the Packaging Wizard, click Exit.
You have now completed packaging and publishing your application.
19.3 Administer the 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"
Note: The Mobile Server must be up for successful publishing.
Table 192 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>/webtogo
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.
/tutorial
Public Application Do not select this check box unless you want to
make this application available to all users.
Clear
Administer the Application
19-10 Oracle Database Lite Developers Guide
Section 19.3.2, "Using the Mobile Manager to Create New Users for the Task
Application"
Section 19.3.3, "Setting Application Properties"
Section 19.3.4, "Granting User Access to the 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.
19.3.1 Start the Mobile Server and the Mobile Manager
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:
1. Using the command prompt, go to the following directory.
<ORACLE_HOME>\Mobile\Server\bin
2. To start the Mobile Server for the first time and subsequent occasions, execute the
runmobileserver command.
3. Start your Web browser and connect to the Mobile Server by enter the following
URL:
http://<mobile_server>/webtogo
4. Log on as the Mobile Server Administrator using administrator as the User
Name and admin as the Password.
5. To launch the Mobile Manager, click the Mobile Manager link in the workspace.
6. Click the Mobile Server link.
7. Click the Applications link. As Figure 197 displays, the Applications page
appears. Locate the Task application, which shows all applications that are
published.
Figure 197 Applications Page
Note: Replace <mobile_server> with the host name of your
Mobile Server.
Administer the Application
Tutorial for Building Mobile Applications for Win32 19-11
19.3.2 Using the Mobile Manager to Create New Users for the Task Application
For the Task application, create users Tom, Dick and Harry. We only show how to
create the user Tom in the following steps:
1. On the Mobile Manager home page, click the Users link. As Figure 198 displays,
the Users page appears.
Figure 198 Users Page
2. Click Add User. As Figure 199 displays, the Add User page appears.
Figure 199 Add User Page
3. As described in Table 193, enter the following information in the Add User page
and click Save.
Administer the Application
19-12 Oracle Database Lite Developers Guide
Repeat these steps to create the Dick and Harry users.
19.3.3 Setting Application Properties
To set the Task application properties, perform the following steps:
1. On Mobile Manager home page, click the Applications link. The Applications
page appears.
2. 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.
3. Click the Task application link. As Figure 1910 displays, the Application
Properties page lists application properties and database connectivity details.
Figure 1910 Application Properties Page
Table 193 Add User Page Description
Field Value
Display Name Tom Jones
User Name Tom
Password tomjones
Password Confirm tomjones
Privilege User
Register Device True
Software Update Select all updates
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.
Administer the Application
Tutorial for Building Mobile Applications for Win32 19-13
4. 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.
19.3.4 Granting User Access to the Application
To grant the Tom, Dick and Harry users access to the Task application, perform the
following steps:
1. Navigate to the Application Properties page and click the Access link. As
Figure 1911 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.
Figure 1911 Access Page
2. Under the Users table, locate the Tom, Dick and Harry users and select the check
boxes for these users.
3. Click Save. The Mobile Manager displays a confirmation message. The users have
now been granted access to the Task application.
19.3.5 Defining Snapshot Template Values for the User
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:
1. Navigate to the Applications page and click the Task application link. The
Application Properties page appears. Click the Data Subsetting link. As
Figure 1912 displays, the Data Subsetting page appears.
Execute the Application on the Mobile Client for Web-to-Go
19-14 Oracle Database Lite Developers Guide
Figure 1912 Data Subsetting Page
2. Under the User Name column, click the user name link Tom. As Figure 1913
displays, the Data Subsetting Parameters page appears.
Figure 1913 Data Subsetting Parameters Page
3. 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.
19.4 Execute the Application on the Mobile Client for Web-to-Go
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"
Section 19.4.2, "Browse the TASK Snapshot and Update a Row"
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"
19.4.1 Install the Mobile Client on the Win32 Device
You must install the Mobile client before you can use the application that you created
and deployed.
Note: You must install the application and test it on a separate
machine from the Mobile Server.
Note: You must install the Mobile Client on a machine which does
not host the Mobile Server installation.
Execute the Application on the Mobile Client for Web-to-Go
Tutorial for Building Mobile Applications for Win32 19-15
To install the Mobile Client for Win32, perform the following actions:
1. Start your Web browser and connect to the Mobile Server by entering the
following URL.
http://<mobile_server>/webtogo/setup
2. As Figure 1914 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.
Figure 1914 Mobile Client Setup Page
3. 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.
4. 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.
5. 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.
Note: 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.
Execute the Application on the Mobile Client for Web-to-Go
19-16 Oracle Database Lite Developers Guide
6. 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).
19.4.2 Browse the TASK Snapshot and Update a Row
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.
19.4.3 Develop your Mobile Field Service Application Using Oracle Database Lite
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.
Execute the Application on the Mobile Client for Web-to-Go
Tutorial for Building Mobile Applications for Win32 19-17
19.4.4 Republish the Application with the Application Program
Use the Packaging Wizard to republish the application, as follows:
1. From the Command Line, enter the following:
D:>runwtgpack
2. Select the "Edit an existing application" option. From the drop down list, select
"Mobile Field Service" and click the OK button.
3. Click the Files tab. As shown in Figure 1915, verify that the mfs.exe file is listed
in the "File Name" window and click Finish.
Figure 1915 Load the MFS.EXE File.
4. 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.
Figure 1916 Republish the Application
Execute the Application on the Mobile Client for Web-to-Go
19-18 Oracle Database Lite Developers Guide
5. 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.
6. 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
7. 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.