This chapter describes how to use hOverlay
to create localized versions of a Palm OS application (PRC file).
- "Introducing hOverlay"
- "Preparing to Use hOverlay"
- "Understanding the hOverlay Process"
- "Using the hOverlay Command Line Tool"
Introducing hOverlay
The hOverlay
command line tool (hoverlay.exe
) simplifies the process of localizing a Palm OS application (PRC file). It lets you create a base PRC that is not locale-specific, and then combine the base PRC with an "overlay" PRC that contains locale-specific information.
When localizing an application for a new locale, you need only create a new overlay PRC. The base PRC remains unchanged.
NOTE: Before reading this chapter, you need to know how to create a PRC. Specifically, you need to be familiar with XRD files,
PalmRC
, and PRCMerge
. For information on PalmRC
, see Chapter 3, "Compiling XML Resource Files." For information on PRCMerge
, see Chapter 4, "Building a Palm OS Application." For information on XRD files, see the book Exploring Palm OS: Resource File Formats.
Preparing to Use hOverlay
Before using hOverlay
, you need to split your PRC into multiple, separate PRC files:
- a PRC that is not locale-specific (this is the non-localized PRC)
- a locale-specific PRC for each desired locale (these are the localized PRC files)
Steps to Split your PRC
- Organize your application resources into multiple XRD files rather than just one:
- The first XRD file should contain non-locale-specific resources such as the application icon and the version number; name this file something like
MyApp_nonlocalized.xrd
. - The second XRD file should contain locale-specific resources such as forms for one locale. For example, if this XRD file contain United States English resources, you might name it
MyApp_enUS.xrd
. - The third XRD should contain locale-specific resources for another locale. For example, if this XRD contains resources for France, you might name it
MyApp_frFR.xrd
. - If you wish, create more locale-specific XRD files (such as, for example,
MyApp_jaJP.xrd
for Japan,MyApp_deDE.xrd
for Germany, and other locales).
- The first XRD file should contain non-locale-specific resources such as the application icon and the version number; name this file something like
- Use
PalmRC
to compile each XRD file, creatingMyApp_nonlocalized.trc
,MyApp_enUS.trc
,MyApp_frFR.trc
, and other locales. - Use
PRCMerge
to link the TRC files with the appropriate code resources, creating PRC files namedMyApp_nonlocalized.prc
,MyApp_enUS.prc
,MyApp_frFR.prc
, and other locales.
You now have a non-localized PRC and multiple localized PRC files which hOverlay
can use.
An alternative way to create a non-localized PRC and localized PRC files is to create a single XRD file for all your application resources, using the LOCALE
attribute to indicate resources that pertain to a specific locale. You can then use the PalmRC
overlayFilter parameter to create multiple, separate TRC files (a non-localized TRC and one or more overlay TRC files). Then use PRCMerge
to link each TRC file with the appropriate code resources.
For detailed information on the LOCALE
attribute, see Exploring Palm OS: Resource File Formats.
Understanding the hOverlay Process
hOverlay
takes as input the non-localized PRC and localized PRC files that you created, and uses them to create a base PRC (BPRC
) and overlay PRC files (OPRC
). You can then install the base PRC (containing non-locale-specific information) and the appropriate overlay PRC (containing locale-specific information) on your device, and they work together like a single PRC.
The Palm OS Launcher application knows to treat the base PRC and overlay PRC files as a single application because they share the same database type and creator, and have the database bundle flag set. hOverlay
uses the base PRC file's database header values (type, creator, version, and flags) to set the database header values in the output files. When hOverlay
builds an OPRC
file, it creates the database name automatically by appending the locale value to the base PRC file's database name. Also, hOverlay
automatically sets the bundle flag for all the overlay database headers.
hOverlay
can perform three different operations, which correspond to three different modes, described in the sections that follow.

Mode 1: Creating a Base PRC
The first operation mode constructs the base PRC (BPRC
). As input, it takes one non-localized PRC and one localized PRC (for information on creating these inputs, see "Preparing to Use hOverlay").
The locale of the localized PRC that you choose to use in mode 1 becomes the locale of the primary overlay PRC in Mode 2.
For example, you might choose to create your base PRC using the enUS
(U.S. English) locale as the primary locale for this base PRC:
hOverlay -mode1 MyApp_nonlocalized
.prc MyApp_enUS
.prc enUS
myApp
.bprc
This example creates a base PRC using enUS
as the primary locale.

Mode 2: Creating a Primary Overlay PRC
The second operation mode constructs an overlay PRC (OPRC
) for the same primary locale used with Mode 1. The parameters are the same, except that the output file name is the same as the name of the localized PRC for the primary locale.
hOverlay -mode2 MyApp_nonlocalized.prc MyApp_enUS.prc enUS myApp_enUS.oprc
This example creates an overlay PRC for the primary locale enUS.

Mode 3: Creating Overlays for Other Locales
The third mode is used to construct overlay PRC files (OPRC
) for locales other than the primary one. You must supply the following parameters as input:
- the same non-localized PRC file that you used in modes 1 and 2
- the same primary localized PRC file that you used in modes 1 and 2 (for example, if your primary locale is U.S. English, specify
enUS
here) - the localized PRC file for the specific locale (for example, if you are creating an overlay PRC for Japanese, specify
jaJP
here) - the name of the output overlay PRC file; this name is the same as the name of the localized PRC file for the specific locale. For example, if the localized PRC file that you used as input is
MyApp_frFR.prc
, the name of the output overlay PRC isMyApp_frFR.oprc
.
Example
hOverlay -mode3 MyApp_nonlocalized.prc MyApp_enUS.prc MyApp_frFR.prc frFR MyApp_frFR.oprc
This example creates an overlay PRC for the frFR locale.
Using the hOverlay Command Line Tool
hOverlay
is a Windows command line tool. hOverlay
can be called from a batch file when building a PRC.
The command line syntax is as follows (in this example, the primary locale is enUS but you can use a different locale as your primary locale, if you wish):
hOverlay -mode1 nonlocalized.prc primary_locale.prc llCC output.bprc
Specifying Command Line Options
-
-mode1
- This mode,
-mode1
, generates only the base PRC, which contains only the non-locale-specific resources. -
-mode2
- This mode,
-mode2
, generates only the primary locale's overlay PRC. -
-mode3
- This mode,
-mode3
, generates a specified locale's overlay PRC. -
nonlocalized.prc
- A PRC file containing only the non-locale-specific resources.
-
primary_locale.prc
- A PRC file containing only the localized resources for the primary locale (in this example, the primary locale is
enUS
, but it could be any locale). -
secondary_locale.prc
- A PRC file containing localized resources for some locale other than the primary locale.
-
llCC
- The primary locale associated with the
primary_locale.prc
file. In most of the examples, this primary locale isenUS
for United States English. -
xxYY
- The secondary locale associated with the
secondary_locale.prc
file. -
output.bprc
- The filename of the base PRC to be generated by
hOverlay
. For example, this could bemyprc.bprc
. -
output_llCC.oprc
- The filename of the primary locale's overlay PRC, to be generated by
hOverlay
. The output name should always include the locale. For example, this could bemyprc_enUS.oprc
. -
output_xxYYY.oprc
- The file name of another locale's overlay PRC, to be generated by
hOverlay
. The output file name should always include the locale. For example,myprc_frFR.oprc
for French, ormyprc_jaJP.oprc
for Japanese. -
-noOvlyWarn
- Turns off warning messages when overlay resources already exist in the source BPRC and OPRC files. This flag works in mode3 only.
-