Oracle9i Lite Developers Guide for Windows 32
Part No. A95912-01
This document discusses the Packaging Wizard utility of the Mobile Development Kit. Topics include:
The Packaging Wizard is a graphical tool that you can use to perform the following:
Create a new Mobile Server application.
Edit an existing Mobile Server application.
Publish an application to the Mobile Server Repository.
When you create a new Mobile Application, you define its components and files. In some cases you may want to edit the definition of an existing Mobile Application's components. For example, if you develop a new version of your application, you can use the Packaging Wizard to update your application definition. The Packaging Wizard also enables you to package application components in a .jar file which can be published using the Control Center. A secondary use for the Packaging Wizard is to create SQL scripts which can be run to create base tables on the Oracle 8 database.
To launch the Packaging Wizard, type the following from a DOS prompt:
The Packaging Wizard appears and defaults to the Welcome panel. The Welcome panel enables users to create, edit, or open a packaged application using the following features:
Figure 4-1 Welcome Panel
Table 4-1 Welcome Panel Options
|Create a new application||When selected, this option enables users to define a new application.|
|Edit an existing application||When selected, this option enables users to edit a existing application. Users can select an existing application from the adjacent drop-down list.|
|Delete the existing application||This options removes all references to the specified application from the file. This option does not remove the application from the Mobile Server Repository if the application has been previously published. That must be done using the Control Center.|
|Open a packaged application||When selected, this option enables users to select an application that has been packaged as a .jar file. You can enter the name of the packaged application in the adjacent field or use the Browse button to search for the application you wish to edit.|
You can select which platforms your application will be packaged for using this screen. You must select a minimum of one platform, but you can select several if your application runs on more than one kind of client. Highlight the platform of choice from the upper list of Available Platforms and use the down-arrow button on the right to select and move it to the Selected Platforms list.
Figure 4-2 Platform Selection
Use the Application panel to name the Mobile Server application and to specify where you want to store it on the Mobile Server server. This panel includes the following fields:
Figure 4-3 Application Panel
Table 4-2 Application Panel Options
|Virtual Path||This provides the application with a unique identity. A path that is mapped from the root directory of the Mobile Server Repository to the location of the application itself. The virtual path eliminates the need to refer to the application's entire directory structure.||Yes|
|Application Name||The display name of the application when you log into Mobile Server.||Yes|
|Description||A brief description of the Windows application.||Yes|
|Local Application Directory||The directory on the local machine that contains all of the components for this application. You can type this location or select it by clicking the Browse button. See Section 4.4.1, "Locating Platform Files" for the format required in this directory.||Yes|
The Local Application Directory is required. If the application contains Win32, Palm, EPOC, or Windows CE files, place the files in the following subdirectories of the Local Application Directory:
Place files for any Windows 32 application in a subdirectory named "win32".
Place files for any Windows CE application in a subdirectory named "wince".
Place files for any Palm application in a subdirectory named "palm".
Place files for any EPOC application in a subdirectory named "epoc".
Any files not placed in a directory for a specific device are expected to be used for a Web-to-Go application. No specific directory is needed for Web-to-Go files they may reside at the root level in the Local Application Directory.
Mobile Server allows multiple versions of the same application to be published and managed in the Mobile Server repository. This means that multiple implementations of the same application exists, each of them accessing the same application tables in the Oracle database server. For example, you could have a C/C++ application for both Windows 32 and Compaq iPAQ. Although you may be able to reuse some or all the C++ source code, you need to recompile the files for each target platform and create different executables for Windows 32 and iPAQ. Two application versions of the same application exists, each of them using the same database tables. It is paramount that application files are stored in a dedicated subdirectory which must have a distinct name. The Local Application Directory is the directory on the Windows development system where the different application versions are stored. Packaging Wizard recursively reads the application files under this application (root) directory.
A Local Application Directory called 'Applications' stores the different application versions.
The executable files for Windows 32 must be stored under the \win32 subdirectory.
C:\Applications\win32 The executable files for iPAQ must be stored under the \wince\Pocket_PC\us\arm subdirectory.
The Local Application Directory is C:\Applications but it has two subdirectories.
C:\Applications - This is the string which must be entered in the Local Application Directory field. Adding a subdirectory in this field will cause the packaging process to fail.
C:\Applications\win32 - This is the application subdirectory for Windows 32 version.
C:\Applications\wince\Pocket_PC\us\arm - This is the application subdirectory for the StrongArm version of CE.
For Windows 32 applications, the only subdirectory needed is \win32. For a list of directories for other platforms, see the appropriate companion Developer's Guide.
Use the Files panel list your application files and to specify where they are located on the local machine. The Packaging Wizard analyzes the contents of the Local Application Directory and displays each file's local path. The panel contains the following fields:
Figure 4-4 Files Panel
Table 4-3 Files Panel Options
|File Name entry||The absolute path of each Mobile Server application file. Each entry on the list includes the complete path of the individual file or directory.||Yes|
You can add, remove, or load any of the files listed in the Files panel. If you are creating a new application, the Packaging Wizard automatically analyzes and only loads files listed under the local directory when you view the Files panel. Only files deployed in the appropriate subdirectory, for example \win32, are recognized by Packaging Wizard. Files added by any other method will generate an error message.
You can sort the files by their extensions or by the directory in which they are located. To sort files, click the By Extension or By Directory radio buttons.
When you click the Load button, the Input dialog box appears. You can use the Input dialog box to create a comma-separated list of filters that either include or exclude application files from the upload process. To exclude a file, type a preceding minus sign (-) before the file name. For example, to load all files but exclude files with the .bak and .jar suffixes, type the following:
Figure 4-5 Filter Dialog Panel
Use the Database panel to specify which database on the Oracle server the data is to be replicated from.
Figure 4-6 Database Tab Screen
Table 4-4 Database Panel Options
|Database Username||The user name for the database used by the application to synchronize the data.||Yes|
|Database Name||The name of the database you are connecting to on the Mobile Client device. This should be the name used in your application. If left blank, a name is generated automatically.||Yes|
Use the Snapshots panel to create replication snapshot definitions for your application. A snapshot name must be unique across all applications.
The panel includes the following fields:
Figure 4-7 Snapshots Panel
Table 4-5 Snapshot Parameters
|All Platforms||A drop-down list of the platforms of the current snapshots. The drop-down list may include all of the following platforms:
Selecting a platform from the drop-down list displays only the snapshots for that platform in the Snapshots panel. For example, selecting Win32 from the All Platforms drop-down list displays only Win32-based snapshots. Selecting the All Platforms option from the drop-down displays all snapshots by the platforms currently in use. The drop-down list displays additional platforms as users add new snapshots.
|Name||The name of the snapshot definition associated with the Mobile Server application. This name must be the same as the database table that exists or must be created on the Oracle Lite database.||Yes|
|Template||The template is a SQL statement that is used to create the snapshot. The template may contain variables. After you publish the template to the Mobile Server server, you can specify user-specific template variables using the Mobile Server Control Center. However, you cannot modify a snapshot definition template in the Mobile Server Control Center.||Yes|
|Platform||The platform for the snapshot definition. Users can create snapshot definitions for different platforms. When users synchronize data from the client, they get only the snapshot definitions appropriate to the platform running the client application.||Yes|
|Weight||This is a positive integer value which determines the synchronization order of database tables. For tables with a "master"/ "detail" relationship, the master table must have a lower weight so that is replicated before the detail table.||Yes|
You can add or remove snapshots from the Snapshots panel by clicking the New or Delete button. You can also import or edit snapshots.
Note:You can import multiple snapshots from the Snapshots panel or import one when you create a new table from the New Table Dialog box.
To create new snapshots, click the New button. The New Snapshots screen appears.
Figure 4-8 New Snapshot Panel
Create a new snapshot by modifying the following features of the New Snapshot screen:
Table 4-6 New Snapshot Panel Options
|Platform||These tabs display the platforms based on the selection made on the Platform screen.|
|Snapshot Name||The name of the database server table upon which the snapshot definition is based.|
|Generate SQL||When selected, the Packaging Wizard will collect information that is output to a SQL script that enables you to create a database table on the database associated with Mobile Server. If the base table exists on the database and does not need to be created using a SQL script, clear this checkbox.|
|Weight||Allows you to set the table weight for this table. Table weight is used to resolve conflicts when synchronizing. See Section 220.127.116.11, "Using Table Weight" for more information.|
|SQL||Displays the create table SQL statement that defines the named table. You can modify this statement. This SQL statement will be included in the SQL script created if the "Generate SQL" box is checked.|
To import snapshots from an Oracle8 database or an Oracle Lite database, click the Import button. The database connection window appears if you have not specified a connection.
Note:Once you have specified a database connection it is used for the remainder of your Packaging Wizard session. If you need to switch between an Oracle8 database and an Oracle Lite database but have alread established a connection you must quit the Packaging Wizard application completely and run wtgpack.exe again.
Figure 4-9 Database Connection Panel
Enter the user name, password, and database URL for the Oracle8i database from which you are importing your snapshot(s). Click "OK" to continue. The Tables window appears.
Note:Use the following format when entering the database URL for an Oracle8i database: jdbc:oracle:thin:@o8host:o8 port:SID. For example, jdbc:oracle:thin:@o8-db:1521:orcl. For Oracle Lite, use jdbc:polite:webtogo.
Figure 4-10 Table Selection Panel
Select the publicaton item from which you want to import your table(s), and then select the table(s). Click Add and then click Close. The table appears in the Snapshots panel of the Packaging Wizard.
To edit a snapshot definition, select the snapshot from the Snapshots panel and click Edit. The Edit Snapshot window appears. The tabs display the platforms you selected in the beginning. Snapshots must be defined for each platform using the tabs, although they may be identical snapshots.
Figure 4-11 Edit Snapshots Panel
Edit the snapshot definition by modifying the following features of the Edit Snapshot window:
Table 4-7 Edit Snapshots Panel Options
|Create on Client||When selected, the check box allows you to perform the following:
|Updateable||This check box defines the snapshot to be created as updatable.|
|Conflict Resolution||This option defines whether the server or the client wins all conflicts. The default setting is "Server Wins." See Section 3.1.8, "Replication Errors and Conflicts" for more information on Conflict Resolution.|
|DML Procedure||You can use this field to specify a DML procedure in the form:
Adding a DML procedure overrides the selection in the Conflict Resolution option.
See Section 3.4.4, "Defining Customized DML Operations" for complete details on creating a DML procedure.
|Refresh Type||The two choices for this option are:
|Template||Displays the snapshot template for the named table. You can modify the snapshot template. Administrators can instantiate variables for different users to this template using the Mobile Server Control Center. See Section 4.7, "Defining Snapshots For Replication" for more information about template variables.|
When you complete all of the Packaging Wizard panels, the Application Definition Completed window appears with the following options:
Publish the current application
Figure 4-12 Application Definition Panel
The Packaging Wizard automatically saves all of your application information to a file. The Packaging Wizard retains the file on the local machine and provides you with the option of publishing it to the Mobile Server, among others. You can only publish the application file to the Mobile Server when the server is running.
Once the application has been packaged, the Packaging Wizard creates a .jar file. Anyone with administrator privileges on the Mobile Server instance can publish to the Mobile Server Repository using the Control Center.
The Create Files option allows you to package your application components in a .jar file. To package your application components in a .jar file, click Create Files, and then click "Package applications in a JAR file". You are prompted to specify the location for the .jar file.
To generate SQL scripts, click Create Files, and then click "Generate SQL scripts for database objects". The generated script will be placed in a SQL subdirectory under the application's local root directory. The SQL script, which make use of the information you supplied about the snapshots and sequences, it can be executed on the database to create these database objects.
The Restart Wizard option enables you to restart the Packaging Wizard. Using this option returns you to the Welcome panel of the Packaging Wizard. To restart the Packaging Wizard, click Restart Wizard and then click OK.
The Publish Current Application option enables you to publish the application that you created and defined in the Packaging Wizard. To publish the Mobile Server application, click the Publish Current Application button and then click "OK". The Publish Application window appears.
Figure 4-13 Publish Application Window
Enter the required information in the specified fields of the Publish Application window.
Table 4-8 Publish Application Window Options
|Mobile Server URL||The Mobile Server server's URL including the server name and port number. The server name and port number have the following format:
where mobileserver is the hostname of the Mobile Server and port is the TCP/IP port. The defaul port is port 80.
|Mobile Server Username||The name of the Mobile Server user.||Yes|
|Mobile Server Password||The password for the Mobile Server user.||Yes|
|Repository Directory||The destination directory of the Mobile Server Repository. The Packaging Wizard publishes your application files to this directory and maintains the directory structure on the local application directory.||Yes|
|Public||Select this to have this application published as a public application. All users have access to public applications.||No|
Note:You must have the publish privilege to publish applications to the Mobile Server server. The Mobile Server administrator assigns privileges using the Mobile Server Control Center.