This chapter describes how to use GenerateXRD
to convert 68K Palm OS® PRC files and Macintosh RSRC files into the XML format that can be compiled by PalmRC
, the Palm OS XML resource compiler.
- "Introducing GenerateXRD" describes the basic functions of the
GenerateXRD
tool. - "Using GenerateXRD" documents how to use
GenerateXRD
to produce XRD files.
Introducing GenerateXRD
GenerateXRD
is a migration tool for resource files.
Prior to Palm OS Garnet, user interface resources were saved in Macintosh-format binary resource files (RSRC files). The Palm OS resource tools now support an XML-based file format called XRD files. To learn more about the XRD file format, see the book Exploring Palm OS: Resource File Formats.
GenerateXRD
provides a one-way conversion from 68K resource files to the XRD file format. You can use XRD files in applications targeted for any Palm OS release.
When to Use GenerateXRD
- you have user interface resources in RSRC file format (that is, if you have resource files created by Constructor for Palm OS) or in PRC files created with other resource tools,
- you want to use those user interface resources to build applications with the resource tools described in this book.
How GenerateXRD Works
GenerateXRD
produces a new XRD resource file by reading existing resource files:
- Macintosh binary resource files (RSRC files)
- Palm OS binary resource files (PRC files)
- Existing XRD files
Figure 2.1 GenerateXRD Overview

Resources may be selectively filtered from the source files depending on the GenerateXRD
parameters specified. For example, you could specify to only extract menu and form resources, but not bitmap or code resources.
In addition, the data for some resources (such as bitmaps) may be optionally extracted into secondary data files (such as BMP files) that are then referenced from the resource descriptions in the XRD file.
GenerateXRD
is integrated into Palm OS Developer Suite. When you use Developer Suite's function File > Import and select the Import Palm OS Resource File wizard, the wizard calls GenerateXRD
to convert your existing Palm OS resource file into an XRD file.
GenerateXRD
is available as a Windows command line tool. A subset of GenerateXRD
's features are also available in the tool GenerateXRD
Wizard.
Using GenerateXRD Wizard
GenerateXRD Wizard provides a simple interface to the GenerateXRD
tool. GenerateXRD Wizard provides a subset of the most commonly-used features of the GenerateXRD
command line tool in a simple, step-by-step, Wizard interface.
Using GenerateXRD
GenerateXRD
is a command line tool. The command syntax for GenerateXRD
is:
GenerateXRD input_files -o output_file [options]
-
input_files
- One or more input resource files.
-
Palm OS PRC file format
- The file name extensions recognized are PRC, OPRC, BPRC, and TRC.
-
Macintosh resource file containing PalmRez / Constructor for Palm OS resources
- The file name extensions recognized are RSRC, RSR, and PLR.
-
XRD file format
- The only file name extension recognized is XRD.
-
output_file
- The
-o
option is required to specify where the XRD output file is written. You should use the file extension XRD for your filename. The file specified is overwritten automatically if it already exists. -
options
- Additional command line options, as described in the following section "Specifying Command Line Options."
Specifying Command Line Options
-
-bitmaps
bitmapFmt - When
GenerateXRD
generates bitmaps as external files, the default bitmap format is BMP (Microsoft Windows Bit Map file format). BMP format is a commonly-used, cross-platform format. -
-bitmapFilePrefix
prefixValue - When
GenerateXRD
generates bitmaps as external files, you can specify a name prefix for the external bitmap filenames. For example, if then input file isSystem.prc
, you might want to specify"System_"
as the prefix so that the generated file names would beSystem_Bitmap_1000-1.bmp
rather than justBitmap_1000-1.bmp
. - This option can help you organize files, especially if there are multiple XRD files in the same directory and you want to make the association of bitmap files with parent XRD file explicit in the filename.
- For more information on how bitmap filenames are generated, see the
-externDataFiles
option. -
-d
- The attributes of the input PRC database header is stored as a
DATABASE_HEADER
element in the output XRD file. For this option, the input file specified must be exactly one PRC format file; otherwise, the results are undefined. - The
DATABASE_HEADER
element is primarily used for testing and debugging; it is not part of normal application development. Normally, when the resource tools build a PRC file, the database header of the output PRC is initialized with values specified toPRCMerge
. -
-encoding
utfvalue - Controls the character encoding of the output XRD file. utfvalue must be one of the following:
-
"UTF8"
- Specifies the Unicode UTF-8 encoding. This is the default.
-
"UTF16"
- Specifies the Unicode UTF-16 encoding.
- UTF-8 is the most compatible encoding with legacy text editors and text processing such as source control and comparison tools.
- Almost all Unicode aware text editing and processing tools accept either UTF-8 or UTF-16 interchangeably.
-
-externDataFiles
- When
GenerateXRD
creates an XRD file, all data is included in the XRD file by default. Some data, such as bitmaps and MIDI sounds, may be more easily edited and managed if the resources are stored as individual files with a standard format (such as BMP for a bitmap). The-externDataFiles
option tellsGenerateXRD
to place resource data in external data files when possible, which is then referenced by the XRD file. - Note: The file names for external data files are automatically generated based on the resource type, resource ID, and resource type specific information.
- For example, for bitmap resources, the bitmap file names are generated as:
- where resID and bitDepth are filled in as decimal integers using the resource ID and logical bitmap element depth.
- After you have created an XRD file using
GenerateXRD
, you can rename the output data files as long as you update the file reference in the XRD file to match. -
-externFilesDir
directory - When generating resource data as external data files,
GenerateXRD
creates the files in the same directory as the output XRD file by default. If there are a large number of external data files, or if there are multiple XRD files in the same directory, you might want to place the external data files in another directory. Use the option-externFilesDir
to specify a particular directory where external files is created. - Generally, you should specify a subdirectory of the directory where the XRD is output, in which case the XRD file uses a relative file path for the external data files.
- Note: The directory you specify for the
-externFilesDir
option must exist before callingGenerateXRD
.GenerateXRD
does not create the directory for you. -
-help
-
GenerateXRD
displays help information and ignores any other options.
-
GenerateXRD
displays information about supported targets and ignores any other options. -
-helpVersion
-
GenerateXRD
displays the tool's version information and ignores any other option. -
-inlineData
- For all resources in the input XRD files that specify data using external data files,
GenerateXRD
integrates the data into the output XRD file. - You can use this option to reverse the -
externDataFiles
option, if you decide you don't want external data files. -
-knownRawResType
resType - When
GenerateXRD
converts an unknown resource type, it outputs a message indicating that the unknown resource is being converted into aRAW_RESOURCE
type. The binary data of the resource is preserved in the XRD file - If you have created a resource type that you want treated as a
RAW_RESOURCE
type but don't want theGenerateXRD
message, then use the-knownRawResType
option to suppress these messages. - The variable resType specifies a four-letter resource type code of the input resource type. You can specify the
-knownRawResType
option multiple times, one for each resource type. -
-locale
"xxYY" - Tags output resources with a
LOCALE
attribute. TheLOCALE
attribute is used byPalmRC
to determine whether resources go into the base PRC (that is, the locale-independent resources) or into the overlay PRC (that is, the locale-specific resources). - The locale xxYY is either an empty string (""), to indicate forcing base locale, or a specific locale code.
GenerateXRD
recognizes the following specific locale codes: -
enUS
- English
-
frFR
- French
-
itIT
- Italian
-
deDE
- German
-
esES
- Spanish
-
jaJP
- Japanese
-
zhCN
- Simplified Chinese
-
zhTW
- Traditional Chinese
-
koKR
- Korean
- If you are using
GenerateXRD
to input resources that may be used to build overlays, or if you plan to store multiple localized versions of a resource in a single XRD file, you should specify the-locale
option with the appropriate locale code. -
GenerateXRD
requires that the locale value specified be in the formxxYY
, wherexx
is a lowercase two-character alphabetic language code andYY
is an uppercase two-character alphabetic country code. - When you specify a non-standard locale value (a locale value that is not defined by Palm OS), then you must specify the
-noLocaleCheck
option. See the description of-noLocaleCheck
below for more information.
NOTE: When the input files are Macintosh resources, the resource name overlay flags (such as
strip
, nostrip
, ovlyAdd
) are used in conjunction with the locale and resource type to determine whether the output resource is marked with an empty (base) locale or with the localized locale and overlay attributes.
-
-mapInvalidChars
- When you use this option,
GenerateXRD
maps any invalid character it finds to'?'
. -
-noLocaleCheck
- When the
-locale
option is used, if the specified locale code is not one of the currently recognized codes,GenerateXRD
issues a warning message. This warning guards against accidentally specifying an incorrectly locale code (for example, by mistyping a locale code). When you need to specify a non-standard locale code, you should also specify the-noLocaleCheck
option to suppress the warning message. -
-noRsrcNameInfo
- Specifies that
GenerateXRD
should not input Macintosh resource names as resource comment fields when generating the XRD file. This is primarily useful when generating XRD files from Macintosh resource files and the corresponding PRC files for comparison. - When generating the XRD file from the PRC file, the comments are not available. In order to generate matching XRD from the Macintosh resources, you need to suppress the comment generation using this option so that the XRD files could be compared without the comments showing as differences.
-
-noSort
- All resources are placed in the XRD file in the same order as they were read from the input files. If you do not specify this option, all resources are sorted according to XRD resource type, ID, and locale. Normally, resources are kept sorted in canonical order. This canonical order makes it easier to locate resources in the XRD file when you edit the file, and makes it easier to use source control and comparison tools to manage changes to the XRD file.
-
-noUnknown
- Any resource types that are not recognized are not included in the output XRD file. A warning message is displayed for each unknown resource that is skipped.
- This option should rarely be needed. In most cases, if an application is being converted from PRC or RSRC format to XRD, it is necessary to preserve any custom resources used by that application as
RAW_RESOURCE
elements in the XRD file. -
-omit
type - Indicates that you want to omit a particular resource or resources of a particular type. This option is followed by a resource type expression:
-
type
- A resource type to indicate all resources of that type.
-
type (id)
- A resource type followed by a resource ID to indicate a specific resource.
-
type (id:id)
- A resource type followed by an ID range to indicate all matching resources.
- The -
omit
option may be specified more than once; if you use multiple-omit
options, the options are combined. For example,"-omit Talt -omit tFRM"
indicates that the output XRD contains all resources except for alert resources and form resources. -
-only
type - Indicates that you want to input only a particular resource or resources of a particular type. This option is followed by a resource type expression:
-
type
- A resource type to indicate all resources of that type.
-
type (id)
- A resource type followed by a resource ID to indicate a specific resource.
-
type (id:id)
- A resource type followed by an ID range to indicate all matching resources.
- The
-only
option may be specified more than once; if you use multiple-only
options, the options are combined. For example,"-only Talt -only tFRM"
indicates that the output XRD contains both alert and form resources. -
-q /-quiet
-
GenerateXRD
suppresses the tool description (tool name and version number) and copyright information. -
-raw
- All resources that included in the output XRD file are created as
RAW_RESOURCE
elements that preserve the binary input data exactly. Normally, you want the logical XML element that corresponds to the input resource to be created. However, for debugging purposes or for compatibility purposes, you may want to output the raw data. - This option is intended for PRC input files. The output behavior is undefined for Macintosh resource or XRD input files.
-
-remapChars
-
GenerateXRD
maps single-byte instances of special characters (the ellipsis character, ®, ©, and the bullet character) to their equivalent Unicode sequences, when they are found in a double-byte character stream. -
-resInfo
rsrcFile - rsrcFile specifies a Macintosh resource file containing PalmRez or Constructor for Palm OS resources.
GenerateXRD
collects Macintosh resource names, but does not extract resource data from the input file. - You can use this option to specify the Macintosh resource file that
GenerateXRD
should scan in order to find comment information while decompiling a PRC file. - PRC files do not retain comment information; so when
GenerateXRD
decompiles a PRC file, it does not find any comment information to propagate into the output XRD file. However, if you have a comparable RSRC file, you can specify it so thatGenerateXRD
can extract comment information from the RSRC file. - For example, say you have an overlay PRC file (OPRC) that was built using Constructor for Palm OS and the 68K-based localization tool PRC2OVL. When you convert this OPRC file into an XRD file, you may want to retain the resource symbolic names as comments, which can be extracted from the original RSRC file.
-
-s
- Any "segment" resources from the input files are output to the XRD file, usually as
RAW_RESOURCE
elements. Segment resources are executable code resources or support resources that are typically generated by the compiler and/or linker. PRC resource types that are considered segment resources are'code'
,'data'
,'libr'
, and 'ovly'
. - Generating segment resources in the XRD is primarily used for testing and debugging; it is not a part of normal application development. Normally, when you build a Palm OS executable file (a PRC file), the C/C++ compiler and linker tools generate the code or related resources, not
GenerateXRD
. -
-target
palmOS - Specifies the text encoding of the input resources. palmOS must be one of the following targets:
-
4.0
- Indicates Palm Latin R2 text encoding. This is the default.
-
4.0J
- Indicates Palm ShiftJIS (Japanese) text encoding. When working with Japanese resource files, it is important to specify the
"-target 4.0J"
option. Otherwise, the Japanese text is corrupted in the output file. -
4.0CT
- Indicates Traditional Chinese text encoding.
-
4.0KR
- Indicates Korean text encoding.
- For locales that are not explicitly supported, you can specify a Microsoft Windows code page.
- If you do not specify a target setting that matches the input files text encoding, the text in the output XRD is garbage.
- When the input file is a Macintosh resource file, the target setting is also used to specify the fonts that are used to calculate the width of menus and certain controls.
-
-types customTypesFile
-
GenerateXRD
uses custom resource types that are defined in the XRT file specified by customTypesFile. - If you have a PRC file that includes custom resource types, the only way to decompile those custom resources is to specify the custom resource types description file (XRT file) that originally defined those custom resources.
- To specify more than one XRT file, use multiple
-type
options (one for each XRT file). -
-xrdMatchLocale "xxYY"
- Allows filtering resources based on the locale attribute. Only resources with locale attributes that match the specified locale xxYY are included in the output XRD file. All other resource types are filtered silently.
- xxYY specifies a four-character alphabetic locale value or an empty string ("") to match the empty (base) locale.
- You can use the
-xrdMatchLocale
option to split resource files that have combined base and localized resources in one XRD file into separate output XRD files for base and localized resource: - 1. Run
GenerateXRD
once to produce the base XRD file: -
GenerateXRD input_combined.xrd
-xrdMatchLocale "" -o output_base.xrd - 2. Run
GenerateXRD
for each locale-specific XRD file: -
GenerateXRD input_combined.xrd
-xrdMatchLocale "enUS" -o output_enUS.xrd