This chapter describes the overlay manager API as declared in the header file OverlayMgr.h. It discusses the following topics:
Overlay Manager Data Structures
Overlay Manager Constants
Overlay Manager Functions
For more information on the overlay manager, see the section "Maintaining Backward Compatibility" in the "Localized Applications" chapter of the Palm OS Programmer's Companion, vol. I.
Overlay Manager Data Structures

OmLocaleType

The OmLocaleType struct specifies a locale.
typedef struct {
UInt16 language;
UInt16 country;
} OmLocaleType;
Field Descriptions
language |
The language spoken in the locale. This value is one of the LanguageType constants. |
country |
The country or region where the language is spoken. This value is one of the CountryType constants. |
Compatibility
If Palm OS® 4.0 New Feature Set is present, the LmLocaleType replaces OmLocaleType. For backward compatibility, OmLocaleType is mapped to LmLocaleType.
Overlay Manager Constants

Constant |
Value |
Description |
omOverlayRscType |
'ovly' |
Symbolic name of an overlay resource that is contained in both the base database and the overlay database. |
omOverlayRscID |
1000 |
Resource ID of the overlay resource in both the base database and the overlay database. |
omFtrCreator |
'ovly' |
Creator value used for the omFtrShowErrorsFlag feature. |
omFtrDefaultLocale |
1 |
Feature that specifies the default locale stored in the ROM. The default locale is used in cases where the system is attempting to open a "stripped" database (one that requires an overlay) and an overlay matching the current locale cannot be found. In this case, the system then looks for an overlay matching the default locale. Use FtrGet and FtrSet to retrieve and set this value. |
omFtrShowErrorsFlag |
0 |
Feature that controls the number of error messages displayed by the overlay manager. If this feature is set to true, the overlay manager may display several more error messages when validating an overlay against its base database. This feature only takes effect when the error checking level is set to full (common on debug ROMs, not on release ROMs). Use FtrGet and FtrSet to retrieve and set this value. |
Overlay Manager Functions

OmGetCurrentLocale

Purpose
Return the current locale.
Prototype
void OmGetCurrentLocale (LmLocaleType *currentLocale)
Parameters
<- currentLocale | Points to an LmLocaleType struct that identifies the current locale. |
Result
Returns nothing.
Comments
This function returns the current locale. The current locale controls which overlays are used for resource databases. For example, suppose you have one application and two associated overlays installed, one for US English and one for British English. In this case, if the country specified in the locale returned by this function is cUnitedKingdom, the British English overlay is used for the application. If the country returned is cUnitedStates, the US English overlay is used.
Compatibility
Implemented only if 3.5 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call OmGlueGetCurrentLocale. For more information, see Chapter 76, "PalmOSGlue Library."
See Also
OmGetSystemLocale
OmGetIndexedLocale

Purpose
Return a system locale by index.
Prototype
Err OmGetIndexedLocale (UInt16 localeIndex, LmLocaleType *theLocale)
Parameters
-> localeIndex | Zero-based index of the locale to return. |
<- theLocale | Points to an LmLocaleType struct that identifies the locale at that index. |
Result
Returns errNone upon success, or omErrInvalidLocaleIndex if the index is out of bounds.
Comments
OmGetIndexedLocale is used in a loop to discover how many system overlays are installed for system resources.
If the 4.0 New Feature Set is present, use OmGetNextSystemLocale instead of this function. OmGetIndexedLocale can be slow on ROMs that contain many valid system locales.
Compatibility
Implemented only if 3.5 New Feature Set is present.
In Palm OS 3.5, this function would not return a system overlay that was located in RAM. The Palm OS 4.0 version of this function does return system overlays located in RAM.
See Also
OmGetSystemLocale, OmGetNextSystemLocale
New OmGetNextSystemLocale

Purpose
Return a system locale.
Prototype
Err OmGetNextSystemLocale (Boolean iNewSearch, OmSearchStateType *ioStateInfoP, LmLocaleType *oLocaleP)
Parameters
-> iNewSearch | true if this function call is starting a new search, or false if this function call is a continuation of a search. |
<-> ioStateInfoP | If iNewSearch is false, this must point to the same data used for the previous invocation. |
<- oLocaleP | The found locale. |
Result
Returns errNone if no error or omErrNoNextSystemLocale if no matches were found.
Comments
You can call this function successively to discover how many system overlays are installed for system resources. Each system overlay found determines a separate valid system locale. Any locale returned by this function can be sent to OmSetSystemLocale to change the system locale.
To start the search, pass true for iNewSearch. Allocate an OmSearchStateType structure and pass its address as ioStateInfoP. OmGetNextSystemLocale stores private information in ioStateInfoP and uses it if the search is continued.
To continue a search where the previous one left off, pass false for iNewSearch and pass the same ioStateInfoP that you used during the previous call to this function.
When called successively, this function eventually returns all system overlays that are in ROM or RAM.
Compatibility
Implemented only if 4.0 New Feature Set is present.
OmGetRoutineAddress

Purpose
Return the address of an overlay manager function.
Prototype
void *OmGetRoutineAddress (OmSelector inSelector)
Parameters
-> inSelector | One of the routine selectors defined in OverlayMgr.h. |
Result
Returns the address of the corresponding function. Returns NULL if an invalid routine selector is passed.
Comments
You typically use this function to determine whether an overlay manager function exists on the device. As future releases of Palm OS add new functions, older devices with earlier versions of the overlay manager will not implement these newer functions. If OmGetRoutineAddress returns NULL, the function is unavailable.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
IntlGetRoutineAddress, SysGetTrapAddress
OmGetSystemLocale

Purpose
Return the system locale.
Prototype
void OmGetSystemLocale (LmLocaleType *systemLocale)
Parameters
<- systemLocale | Points to an LmLocaleType struct that identifies the system locale. |
Result
Returns nothing.
Comments
You typically don't use this function. Instead, use OmGetCurrentLocale, which returns the locale that determines which overlays are used.
The system locale is saved in the storage heap header and persists across soft resets. When the device is reset, the system locale is used to set the current locale.
Compatibility
Implemented only if 3.5 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call OmGlueGetSystemLocale. For more information, see Chapter 76, "PalmOSGlue Library."
See Also
OmGetCurrentLocale
OmLocaleToOverlayDBName

Purpose
Return the overlay database's name given the base database name and the locale.
Prototype
Err OmLocaleToOverlayDBName (const Char *baseDBName, const LmLocaleType *targetLocale, Char *overlayDBName)
Parameters
-> baseDBName | The name of the base resource database associated with the overlay. |
-> targetLocale | The locale to which this overlay applies. See LmLocaleType. Pass NULL to use the current locale. |
<- overlayDBName | The overlay database name given the base database name and the target locale. This buffer must be at least dmDBNameLength bytes. |
Result
Returns errNone upon success, or omErrUnknownLocale if the targetLocale parameter is invalid.
Comments
The appropriate overlay database name is currently:
baseDBName_llCC
where:
baseDBName | The name of the base database as you passed it in. |
ll | A two-character code identifying the language. |
CC | A two-character code identifying the country. |
The base database name is truncated if necessary to allow for this suffix.
For example, the base database "MemoPad" might have an overlay for US English named "MemoPad_enUS".
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
OmOverlayDBNameToLocale
OmOverlayDBNameToLocale

Purpose
Return an overlay database's locale given its name.
Prototype
Err OmOverlayDBNameToLocale (const Char *overlayDBName, LmLocaleType *overlayLocale)
Parameters
-> overlayDBName | The name of the overlay database. |
<- overlayLocale | Points to an LmLocaleType structure identifying the overlay's locale. |
Result
Returns errNone upon success, omErrBadOverlayDBName if the string overlayDBName is not long enough to have a locale suffix, or omErrUnknownLocale if the locale cannot be determined.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
OmLocaleToOverlayDBName
OmSetSystemLocale

Purpose
Set the system locale and reset the device.
Prototype
Err OmSetSystemLocale (const LmLocaleType *systemLocale)
Parameters
-> systemLocale | An LmLocaleType structure specifying the locale to switch the system to. |
Result
Returns errNone upon success, or one of the following if an error occurs:
omErrUnknownLocale | There is no system overlay for systemLocale. |
omErrInvalidLocale | The system overlay for systemLocale has been found but is invalid. |
dmErrInvalidParam | An error occurred while opening the overlay. |
dmErrMemError | A memory error occurred while opening the overlay. |
dmErrDatabaseOpen | The system overlay was already open. |
Comments
This function changes the system locale to the specified locale if it exists. It first determines that the system overlay exists for the requested locale and that it matches the base system database. If so, it updates the system locale information saved in the storage heap header and resets the device. After the device is reset, the current locale is set to the system locale.
A Palm PoweredTM device has a default locale hard-coded into the ROM. This locale is used to set the system locale after a hard reset or any time that the storage heap header is invalid. The storage heap header is typically only invalid when the device is turned on for the first time.
Compatibility
Implemented only if 3.5 New Feature Set is present.
In Palm OS 3.5, this function would not switch to a system overlay that was located in the RAM. The Palm OS 4.0 version of this function does return system overlays located in the RAM.
See Also
OmGetSystemLocale
|