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 ^TOP^

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 ^TOP^

Use GenerateXRD if:

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

  AND

• you want to use those user interface resources to build applications with the resource tools described in this book.

How GenerateXRD Works ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

-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 is System.prc, you might want to specify "System_" as the prefix so that the generated file names would be System_Bitmap_1000-1.bmp rather than just Bitmap_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 to PRCMerge.

-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 tells GenerateXRD 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:

Bitmap_resID-bitDepth.BMP

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 calling GenerateXRD. 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 a RAW_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 the GenerateXRD 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. The LOCALE attribute is used by PalmRC 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 form xxYY, where xx is a lowercase two-character alphabetic language code and YY 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.

-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 that GenerateXRD 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