Segmenting an Application

A Palm OS application is a collection of resources packed together into a resource database. Because of limitations in the current HotSync architecture, no single resource can be larger than roughly 64K. If a resource is larger than 64K, your application fails to load into either the Palm OS Emulator or onto a Palm OS handheld via HotSync Manager.
Each application includes a resource of type 'CODE'. This is the resource that stores your application's compiled code and is the most likely resource to exceed the 64K resource size limit. When this happens, you need to segment your application. The process of segmenting an application breaks a large CODE resource into multiple, smaller CODE resources. An application that has been broken in to multiple CODE resources is called a multi-segment application.
There are two ways to create a multi-segment application. If you are using Metrowerks CodeWarrior and creating an application from scratch, you can select "Palm OS Multi-Segment App" from the "New Project" window. This stationery includes the necessary library and linker settings to build a multi-segment application.
If you are converting an existing single-segment application to a multi-segment application, you need to replace the "StartupCode.lib" file with a "MSL Runtime Palm OS (xx).lib". Additionally, you need to disable the "Link Single Segment" flag in the "68K Linker" settings of your project's settings. If you have enabled the 4-byte ints option in the "68K Processor" preferences in your project, then you need to use the "MSL Runtime Palm OS (4I).lib"; otherwise use the "MSL Runtime Palm OS (2I).lib".
To create a new segment, click on the "Segment" tab in your project window. You can then create a new segment by selecting "Create New Segment" from the "Project" menu. Name your segment as appropriate and click "OK". Once you have multiple segments you can simply drag files from one segment to another as appropriate. Note that all segmentation takes place under the "Segment" tab and not the "Files" tab.
There are a few important points to keep in mind. The first segment MUST contain the "MSL Runtime Palm OS (xx).lib", your application's PilotMain() function, and any code that is executed when PilotMain() receives a launch command other than sysAppLaunchCmdNormalLaunch. This stipulation is is necessary because A5-relative data is not relocated when the application is called with any other launch code, causing all global variable addresses to be incorrect.
All other files in your application can be placed in any segment you wish.
If you intend to use functions defined in another segment, they must be declared as "extern" in the segment you are calling from so that the compiler knows that function exists in another segment.
Note to Codewarrior users The best way to determine which files can go into segments other than segment 1 is to:
comment out the code in PilotMain() that handles the sysAppLaunchCmdNormalLaunch command
select the "Generate Link Map" option from the "68K Linker" preferences in your project
rebuildAny file that shows up in the link map on a line beginning with "Code:" must be in the first segment. The link map file is created in the same folder as your project and ends in ".map". Double-click its icon to view the link map. The map includes some functions that the OS usees, you can ignore these functions (most begin and end with two underscore characters ie: __)