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.

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.

  • 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"

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.

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.

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:

For more information, see Section 5.2, "Create a Project".

  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.

Note:

For more information, see Section 5.4, "Create a 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.

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.

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:

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

    Figure 19-1 Make a Selection Dialog

    Use this dialog to create a new application.
    Description of "Figure 19-1 Make a Selection Dialog"

  2. Select the Create a new application option and click OK.

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

    Figure 19-2 Selecting a Platform

    Use this dialog to select your mobile platform.
    Description of "Figure 19-2 Selecting a Platform"

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

    Figure 19-3 Application Panel

    Use this dialog to describe your mobile application.
    Description of "Figure 19-3 Application Panel"

    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

    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.

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

    Figure 19-4 Uploading Application Files

    Use this dialog to compile JSP.
    Description of "Figure 19-4 Uploading Application Files"

  6. Click Next till you arrive at the Application Definition Completed Dialog as shown in Figure 19-5.

    Figure 19-5 Application Definition Completed Dialog

    Specify application definition requirements.
    Description of "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.

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

      Figure 19-6 Save the Application Dialog

      Use this dialog to locate your jar file.
      Description of "Figure 19-6 Save the Application Dialog"

      After choosing the JAR file, click OK. The JAR file is created and contains the application files and definition.

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

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

    4. To confirm that the application is published successfully, click OK.

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

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

    Note:

    Replace <mobile_server> with the host name of your Mobile Server.

  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 19-7 displays, the Applications page appears. Locate the Task application, which shows all applications that are published.

    Figure 19-7 Applications Page

    The applications page
    Description of "Figure 19-7 Applications Page"

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 19-8 displays, the Users page appears.

    Figure 19-8 Users Page

    The Users page
    Description of "Figure 19-8 Users Page"

  2. Click Add User. As Figure 19-9 displays, the Add User page appears.

    Figure 19-9 Add User Page

    The Add Users page
    Description of "Figure 19-9 Add User Page"

  3. As described in Table 19-3, enter the following information in the Add User page and click Save.

    Table 19-3 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

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.

    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.

  3. Click the Task application link. As Figure 19-10 displays, the Application Properties page lists application properties and database connectivity details.

    Figure 19-10 Application Properties Page

    The application properties page
    Description of "Figure 19-10 Application Properties Page"

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

    Figure 19-11 Access Page

    The access page lists group names and users
    Description of "Figure 19-11 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 19-12 displays, the Data Subsetting page appears.

    Figure 19-12 Data Subsetting Page

    The data subsetting page
    Description of "Figure 19-12 Data Subsetting Page"

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

    The Data Subsetting parameters page
    Description of "Figure 19-13 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:

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 Mobile Client on a machine which does not host the Mobile Server installation.

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

    Figure 19-14 Mobile Client Setup Page

    The Mobile Client setup page
    Description of "Figure 19-14 Mobile Client Setup Page"

    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.

  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.

  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.

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 19-15, verify that the mfs.exe file is listed in the "File Name" window and click Finish.

    Figure 19-15 Load the MFS.EXE File.

    Files panel
    Description of "Figure 19-15 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 19-16 Republish the Application

    republish application
    Description of "Figure 19-16 Republish the Application"

  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.