    The OnBoard Suite User's Guide

    v1.3

Copyright 2002-2004, Wade Guthrie. Permission is granted to copy and redistribute this document so long as it is unmodified (including the section that describes where to get this document for free) and the copyright remains intact. This should really be copyrighted by the OnBoard C group (both Yahoo! and SourceForge) since much of this has been gleaned from that discussion group but I don't know if that would be legally binding. The purpose of the copyright, anyway, is just to make sure that no one charges for the information, such as it is, that we're giving away for free.

Location. The latest version of this document can be obtained (for free) from http://onboardc.sourceforge.net/UsersManual.html. If you have any questions, comments, corrections or suggestions, please don't hesitate to send them to wade@adventure101.com.

Thanks. A special thanks goes to the incredible legion of talented individuals who have contributed to this document. The list (in alphabetical order) can be found at the end of this document. If I've left anyone out, please contact me at the above address.

##

    Table Of Contents

1. Introduction
1.1 Quickstart
1.2 Licensing
1.3 Why Use The OnBoard Suite?
1.4 A Little History
1.5 Requirements
1.6 Where To Go For Help

2. Installation
2.1 The OnBoard C Distribution
2.2 Other Stuff You Might Need
2.3 Install The OnBoard Suite
2.4 A Word or Two About Upgrading (including rebuilding the headers)

3. User's Tutorial
3.1 If You're Not Already A Palm Programmer (in C). . .
3.2 If You're An Old Hand At Writing Palm Code. . .

4. About The Language
4.1 How is OnBoard C different from ANSI standard C?
4.2 stdio vs. Palm api
4.3 Limits

5. Beyond the Basics
5.1 Support For Other Editors
5.2 Some Dirty Internal Details
5.3 Adding New APIs
5.4 Building A Hack
5.5 Multi-Segmented Code
5.6 Using OnBoard C's Auto-Versioning

6. Reference Guide
6.1 Menus Buttons And Check Boxes

7. Answers To A Few Questions
7.1 Can I write code for some Palm platforms and have it work on others?
7.2 Is it possible to compile with a larger stack with OnBoardC?
7.3 How do you generate a header file from RsrcEdit?
7.4 How do you share my OnBoard C projects with CodeWarrior or the PRC-Tools?

8. Common Problems
8.1 Out Of Node Space
8.2 Unknown Identifier <Palm API>

9. Thanks!

##

    1. Introduction

This document is a user's guide for the OnBoard Suite (which is comprised of the OnBoard C compiler, the OnBoard assembler, and the SrcEdit programmer's editor). OnBoard C is a wonderful C compiler written by Roger Lawrence of Individeo. It runs on, as well as builds code for, the Palm handheld platform (with the help of the OnBoard assembler). You can always get the latest version of the tools from the following address:

    	http://sourceforge.net/projects/onboardc/

The OnBoard C compiler creates a Palm executable or (at the programmer's option) a Hackmaster hack. You can beam your new program or hotsync it to another Palm if you like. It requires nothing but a Palm (w/ the Palm OS in ROM so your code can take advantage of the library that's there). It does not need a separate run-time library.

###

    1.1 Quickstart

If you are fully familiar with Palm programming, you might want a quick way to get started with the OnBoard Suite. That's described here. If you're not an expert at this stuff, however, you might want to check out some of the other sections of this document.

In order to get that quick start we talked about, do the following:

- Download the tools.
- Install the tools.
- Create a project.
- Compile and run your program.

###

    1.2 Licensing

The OnBoard C compiler, the OnBoard Assembler, and SrcEdit are provided under the GNU General Public License (GPL). There should be a file in your OnBoard Suite distribution entitled 'COPYING.txt' -- this file provides the entire license. If you can't find this file (or if you just want to), feel free to check out the Free Software Foundation website.

A quick note about this license. This license does NOT constrain code that you write and compile with any portion of the OnBoard Suite. You can write a program with SrcEdit, compile it with OnBoard C/OnBoard Asm, and sell the executable all day long. You do not have to give away the source to your code just because you used OnBoard C. In fact, the SourceForge OnBoard Suite people (i.e., the people who hold the copyright over this stuff) have agreed not to apply the GPL to the skeleton application that is generated by the OnBoard Suite -- you can start commercial applications with the skeleton.

###

    1.3 Why Use The OnBoard Suite?

OnBoard C is a C compiler for the Palm. There are other compilers for the Palm (e.g., CodeWarrior, GCC, PocketC) so why use OnBoard Suite? Here are some of the reasons.

- OnBoard C uses native PalmOS APIs, so most of what you learn can be applied to "professional" tools like CodeWarrior and GCC.
- Further, since OnBoard C uses native APIs, most of the source code you will find in books written about coding Palms will work with OnBoard C, as well as the majority of free samples available online via Palm's website and other websites and Palm programming forums.
- OnBoard C compiles to native assembly, so your code will run FAST.
- OnBoard C programs need no runtime and are thus easier to distribute.
- OnBoard C allows access to native GUI resources.
- OnBoard C runs on your Palm. Although some find this a bit restrictive, others enjoy being able to code during their daily commute on the train, on lunch breaks, etc. Some people just enjoy being able to get away from the traditional workstation they use every day.
- You can compile and test your code immediately.
- Many Shareware and Freeware apps built with OnBoard C have been released to the public. With a little elbow-grease and time, you can produce "professional-level" applications with OnBoard C.

###

    1.4 A Little History

The OnBoard Suite was originally produced as a commercial product line (along with the RsrcEdit resource compiler) by Individeo At some point in the Fall of 2000 the developers at IndiVideo went their separate ways and Roger Lawrence, the one who developed OnBoard C, took the source code with him. Later, Roger generously released the binaries for the compiler and assembler to be distributed for free by the members of the OnBoard C community. RsrcEdit went to Quartus.net, developers of an onboard Forth compiler for the Palm, where it continues to be available as commercial software. It remains a key component of the OnBoard C IDE, but if you need support for that you'll have to visit Quartus.

OnBoard C started on it's path to becoming free open source software in March 2002, when Roger released the source to an editor he had built and used personally, but never released. Originally called LED--now renamed SrcEdit to avoid confusion with an existing product--this editor included many features specifically for use with OnBoard C and has been actively developed by the OnBoard C community.

In May, contact was reestablished with Roger, and he was shown the work that had been done on SrcEdit and asked if he might do one last build of OnBoard C for us that would fix a couple of nagging issues we were having. Attached to his email reply was the source code to the compiler and assembler.

That effort resulted in the source to the OnBoard Suite being placed under the GNU Public License (GPL) and put on the SourceForge site as an open source project. Note: a resource compiler (like RsrcEdit) is required to use the OnBoard Suite -- there are currently no GPLed resource editors that work with the OnBoard Suite.

###

    1.5 Requirements

The OnBoard Suite runs on handheld computers running Palm OS 3.x. It may run under other versions of the operating system but it has been tested on these.

When OnBoard C begins the initial compile it builds a 'pre-compiled' version of the header file OnBoardHeader.h - this occupies about 80k, but of course more memory is consumed during a compilation, in both the static and dynamic heaps. After installation, your Palm will still need about 200kb free in order to build the header file, though once it is built the compiler can get by with a lot less (about 40k + size of source file).

###

    1.6 Where To Go For Help

There are two main places to go for help with the OnBoard Suite. Users can access the Yahoo OnBoard C discussion group. It was created to support OnBoard Suite users. There's a files section that contains documentation and other support material. Developers (and users, alike) can access the SourceForge site. The latest version of the OnBoard Suite can always be found there. There is a discussion group (available through the 'Lists' link) available to both users and developers. You can also visit the OnBoard Suite task list.

You can always report bugs and request features on the SourceForge site. When you report a bug, please do the following:

- go to the bug reporting site and search (there's a search box on the left) to see if someone else has submitted the bug,
- include a detailed description including the version number of the compiler,
- explain the problem you see -- does the compiler crash, does the compiler generate an error message, does your code crash?
- include a piece of code that will allow us to reproduce the problem.

Back to TOC

##

    2. Installation

###

    2.1 The OnBoard C Distribution

For any particular OnBoard Suite release, you can download one of four different files from the SourceForge site. You can download the source or just the executables and, for each of those, you can download a .zip archive or a .tar.gz archive. If you download just a source archive, you'll have to build it (with the PRC tools or one of the other supported environments) to get the PRCs.

###

    2.2 Other Stuff You Might Need

There will be some things other than the OnBoard Suite download that you'll need to be able to create code.

####

    RsrcEdit

RsrcEdit (RsrcEdit.prc). RsrcEdit builds the forms for the user interface. Quartus, by the way, is grandfathering-in previously registered owners of RsrcEdit. You can get it from here.

####

    Documentation

- This User's Guide.
- Some C language reference.
- Palm's docs.
- Hackmaster docs (only if you're going to build a hack).

####

    Helpful Source Code

Sometimes nothing helps like looking at someone else's code. Here are some resources for Palm source code.

- Palm's docs.
- Palm Open Source.
- SourceForge.
- Code Beach.

####

    Other Support Software

None of this is absolutely necessary but the following code (all of it is free software, by the way) may make your OnBoard programming experience a little better.

- Crash Hack automatically resets your palm when it crashes (rather than having to find a paperclip to punch the reset button). Crash Hack is Palm OS5 friendly.
- Filez is a file manager that allows you to view and change
attributes of files on your Palm or expansion card.
- Plucker allows Palm users to view web pages on their handheld. This is especially useful to OnBC programmers since Palm's API manual and programmer's reference guide are both in Plucker format on the Yahoo! Discussion Group. It is a bit of work to install the first time but it's worth it.

###

    2.3 Install The OnBoard Suite

####

    Install the OnBoard Suite

In order to install the OnBoard Suite, unpack your distribution (e.g., onboard_2_0_1b.zip). On a MS-Windows platform, you can do this with WinZip, StuffIt, or even (with WinME, at least) with MS-Windows, itself. On a Linux (or other Unix) platform, use 'tar' and 'gzip'. Once you get things unpacked, install the following:

- OnBoardC.prc. This is the C compiler. OnBoardC manages the project files and compiles the C code into 68k Assembly language.
- OnBoard.prc. The OnBoard Assembler links the resources during the compilation process (so in its most common use it is a utility used by OnBoardC, rather than a program that needs to be executed by the user.)
- SrcEdit.prc. SrcEdit is a programmer's editor that allows you to edit DOC files for use as source files for your OnBoard C projects.
- Pick one OnBoardHeader_h.pdb. There are several versions of the OnBoardHeader.h file. OnBoard C uses one of these files to prototype the Palm OS Functions. In general, you'll want to choose the most recent version number unless you're upgrading and trying to stay compatible with old code (more about that, below). The OnBoardHeader files come in the OnBoard C distribution file and you'll have to remember to install one of them with the executables. Install OnBoardHeader_h.pdb to support PalmOS v3.3, OnBoardHeaderV35_h.pdb to support PalmOS v3.5, or the appropriate header for more recent versions. Note that regardless of the name on the host (OnBoardHeaderV35.h or whatever), it'll be called OnBoardHeader.h when it gets to the Palm.

On MS-Windows, you can do this by double clicking on each of the files (assuming that you've installed the Palm Desktop). There are operating-system-specific ways to install Palm applications for many other host systems -- use whatever is appropriate.

####

    Install the Other Stuff You Need (see above)

Unfortunately, the OnBoard Suite requires a component that's not free (it's shareware). In order to use the OnBoard Suite, you need to create resource files. The software that does that is RsrcEdit.prc. Get a copy of this software and install it like the other prc files.

####

    Bring It Up

Now that you've installed everything, go to your Palm and tap the OnBoard C icon. When you do this for the first time, OnBoard C automatically goes to New Project dialog. When this happens, do the following.

- Give your project a name.
- Check the 'generate skeleton' checkbox.
- Tap the 'Doc' button on the right (to select the type of file for the skeleton).
- Tap 'ok'.

Then, in the OnBoard C mainform, do the following.

- Check the 'execute' checkbox.
- Tap 'build'.

And you're off and running!

###

    2.4 A Word or Two About Upgrading

It's okay to upgrade a distribution just like you'd install a new distribution. Unless the release notes say so, you don't have to remove the old version first. There are, however, a couple of points to keep in mind.

####

    OnBoardCompatibility.h

First, the Palm OS syntax changed slightly with version 2.2 of OnBoard C (that corresponds to OnBoardHeader40_h). If you've got OnBoard C source code from before this time, you'll want to either stick with a pre-OnBoardHeader40_h or add the OnBoardCompatibility.h file (which is part of post v2.2 OnBoard C distributions) and include it in your source code.

####

    Rebuilding OnBoardHeader.h

After you sync a new header onto your handheld, don't forget to rebuild the header. To do this, select Options off the OnBoard C menubar and then select Delete Header. The next time you build some code, OnBoard C will rebuild the header.

Back to TOC

##

    3. User's Tutorial

###

    3.1 If You're Not Already A Palm Programmer (in C). . .

Depending on your current programming knowledge, you may want to attack the learning process differently. Feel free to choose your own route -- the OnBoard community will be happy to help you no matter what your level of experience is. The suggestions, here, are intended only to make your path to programming in OnBoard C as painless as possible.

Shameless Plug Alert: If you're just starting out with the Palm API, you might want to check out the Palm Programming Cookbook. It goes through learning about event driven programming, discusses a skeleton Palm program, provides step-by-step procedures for building and handling many of the GUI items (buttons and menus, for example), and (best of all) does it from the point-of-view of an OnBoard suite programmer.

Below, you'll find a guess at the level of difficulty you may encounter using OnBoardC based on various levels of programmer experience.

1. If you've never programmed anything before, well, there are easier languages to start with than C and, frankly, easier platforms to program than the Palm. Even though the tenacious programmer *could* start with C, he'd probably do better to tackle this a bit at a time. If you're intent on Palm programming, A great place to start is with Basic (HotPaw Basic or SmallBasic are good Palm Basic interpreters).
2. If you have programming experience, but have no C experience, you might consider concentrating on vanilla C before you get into targeting the Palm platform. The complexities of event driven code and the troubles of the Palm API will probably only complicate matters. Some have suggested working with PocketC (even though it is not 100% C) before starting with OnBoard C.
3. If you have experience in C but have never programmed for PalmOS and do not know anything about event-driven programming, you'll need to read the PalmOS Companion guide (not a bad idea, anyway) in Palm's documentation. You'll also want to learn how event-driven applications work by writing some test/experimentation apps to first familiarize yourself with this way of writing code.
4. If you have experience in C but have never programmed for PalmOS but have good knowledge about event-driven programming, you will only need to read the PalmOS Companion guide to familiarize your self with the Palm environment. You will probably need to write some test apps first, to get the feel of the PalmOS architecture.
5. If you're already programming for PalmOS using the standard desktop tools, you won't have trouble at all using OnBoardC. Skip to the next section.

###

    3.2 If You're An Old Hand At Writing Palm Code. . .

After you install the tools, you need to create source files as part of a project and get the project compiling.

####

    So What's an OnBoard C Project?

A project is a collection of source code (.c filename extension), header code (.h extension), and resource code (.rsrc extension)--that are the ingredients to any Palm OS application written in C. Headers list the declarations of all the native Palm OS functions that your source code may make calls to. The resource files (created in RsrcEdit) are the most convenient way to build the user interface for your program. Thus, the OnBoardC project defines which source, header, and resource files will be compiled and linked together to create a Palm executable. For those familiar with the CodeWarrior development environment, OnBoardC's use of the word "project" is essentially the same.

####

    Creating a Project

In OnBoard C:

- From the OnBoard C menu bar, project->new project.

- Give your project a name.
- Check 'generate skeleton'.
- Pick an editor (DOC if you don't have a preference).

- Check 'execute'.
- Tap 'build'.

####

    Creating and Editing Source Files

You'll eventually want to have more than one source file in a project. To create another file, bring-up SrcEdit (or another of the supported editors) and create a new file. Doc files have their own filenames but for other editors, you should name the file by making the first line a comment containing only the file name:

    	/* foo.c */

Then, in the main form of OnBoard C, tap the 'Add' button. Select the file type (DOC Source for SrcEdit files), tap the file name, tap the 'Add' button, and (when you've added all the files you wanted to), tap 'Done'.

Note: you don't have to add header (.h) files to your project. They'll get included through the #include directive in your source (.c) files.

####

    Building and Running Your Code

You can either build and run in the same step...

From the OnBoard C main form:

- Tap the 'execute' checkbox.
- Tap the 'build' button.

...or you can do it in two steps. First, you build it:

- Uncheck the 'execute' checkbox.
- Tap 'build' and wait for the compiler to finished building.

Then, you run it (this is how you'll run your program when you're not in the process of working on it):

- Find your new application in your Palm launcher. Tap the 'home' icon in the silkscreen area and look in the 'Unfiled' folder (if you've used your application launcher to put a previous version of your program in a different folder, the new one will probably be in the same folder). Note that the name of your application is the one you gave it on the OnBoard C main form under 'PRC name'.
- Launch your application (this is a launcher-specific thing but usually this is accomplished by tapping on the launcher icon).

####

    Working with Your OnBoard C Program

Now that you've built and run your skeleton code, you'll want to modify your program. You can edit your file by tapping on its name in the OnBoard C mainform and tapping the 'Edit' button. An editor appropriate to the file's type (you selected this when the skeleton was created) will be launched with your file.

Once you're done editing your file, you'll want to get back to OnBoard C. SrcEdit has an icon to do this and pEdit also has a button for this purpose. With any other editor, you can go through your application browser or use one of the many hacks (e.g., McPhling) that bounces you back and forth between applications.

At this point, tap 'build' again.

If there are compile errors, a dialog box will appear explaining the error. If you tap the 'goto' button on the dialog box, OnBoard C will launch your editor with the offending file at the offending line.

####

    Debugging

There are several tools you can use to help with OnBoard C debugging.

First, there's a debugger called OBDebug and you can get it (and some documentation describing how to use it here. NOTE: This software is only a Beta release -- it was never completed and has been known to crash your Palm. You can include symbols in your OnBoard C program by checking the 'Debug' box on the OnBoard C's main form.

Next, you can get disassembly of any Palm program using RsrcEdit. Just open RsrcEdit, select your application and tap 'open', select a 'code' resource and tap 'open', tap the 'Disasm' box and you've got disassembly. Remember that this is a Dragonball processor -- you can get documentation for it here. Finally, you can always use dialog boxes & printing to the screen.

Back to TOC

##

    4. About The Language

OnBoard C is pretty much vanilla C with a few caveats (most of which have been described elsewhere in this document). You're writing GUI code, so you're writing event-driven code with a mainloop. OnBoard C uses the Palm APIs rather than the stdio.h. And, of course, OnBoard C isn't precisely ANSI.

###

    4.1 How is OnBoard C different from ANSI standard C?

OnBoard C differs from the ANSI standard in a few ways:

- Preprocessor. Only the following things are supported:
  - #define
  - #include
  - #ifdef ... #endif
  - #ifndef ... #endif
  - #if ... #endif
- Language. The following things aren't supported.
  - Floating point support. Actually, there seems to be some floating-point support if you pound on your code hard enough (trying different approaches to things). More work was done on 'double' than 'float'. When it doesn't work, it often crashes the Palm. You should probably steer clear of this.
  - 'const' and 'volatile'.
  - 'static' may not be fully supported (though it may be -- sometimes the information available to me is pretty sketchy).
- Subtle Issues. These subtle differences are probably just little bugs or corners of the language no one ever got around to testing.
  - Some complex expressions don't work. Examples include a = b = c and if ((a=foo()) == 0). You'll have to break them into two, separate, assignments.
  - statics aren't limited to the scope in which they are defined. Declare two static ints (with the same name) in different functions -- you'll find that there's a name conflict that shouldn't be there.
  - Curly braces, for that matter, don't limit scope. The compiler complains, for instance, about 'foo' being declared twice in the following construct:

        		     	{
        				int foo;
        				{
        					int foo;
        					//...
        				}
        				// ...
        			}

- Standard Libraries. None of the hosted ANSI libraries (e.g. stdio.h or string.h) are supported. Use the Palm libraries instead.
- Some of the deeper corners of ANSI C, for example trigraphs and multi-byte characters, aren't supported.

None of the C99 extensions to ANSI C have been included in OnBoard C (yet).

###

    4.2 stdio vs. Palm api

Palm programming uses the Palm APIs for input and output rather than vanilla C's fgets and printf. The Palm documentation provides a complete list of what can be found in ROM but check out the file 'OnBoardHeader_h.pdb' in the OnBoard.zip for a list of APIs that are readily supported by OnBoard C.

Note that you can get support for the Palm APIs that aren't in this header but there's a bit more work involved. The method for using those APIs is explained further, below.

###

    4.3 Limits

OnBoard C has some limitations in what it can support. Those limits are described, here.

There is an overall memory limit of 64K for any one file. There is now a limit of 32 files that can be included. At one time there was a limit to the number of source files that could be part of a project but that has been removed.

There is a limit of 512 ints of inline code. When you run into this, you'll see the following error "Too many inline values, line xx".

There's a de facto limit brought on by the fact that you can't branch over 32K. When the linker part of the OnBoard assembler generates the error message "XXX beyond 32K displacement" you'll have to start rearranging your code (in order to minimize branch distance) to get it to link. As your code gets bigger, it'll become increasingly difficult to get it to fit.

OnBoard C expects OnBoardHeader.h to be in main memory rather than on a memory stick or something like that. It does work fine in Flash ROM, though.

Back to TOC

##

    5. Beyond the Basics

###

    5.1 Support For Other Editors

OnBoard C recognizes three different formats for source files. All source files in a project do NOT have to be in the same format. Those formats (and the programs for editing files in them) are as follows.

- Doc format. There are several programs for editing files in the Palm DOC format including our own SrcEdit. Others include QED. This link points you to a local copy of version 2.62 because the newest version _may_ not work correctly with OnBoard C.
- Memo pad. The editor for this is free and already on your Palm. It limits your file size to 4k, though, and you'll quickly get tired of this limitation.
- pEdit32. This is a really good programmer's editor with lots of features to make coding easier. pEdit32 has no 4k limit and can import from the doc file format. pEdit04 can import from memo pad. pEdit is not a free editor, however. It can be downloaded from www.paulcomputing.com.

###

    5.2 Some Dirty Internal Details

Traveling with OnBoardC is an assembler that is launched by the compiler to perform the final compile step and linking of the output. The assembler can be invoked separately to assemble from MemoPad or Doc files but is invoked by the compiler using an internal tokenized format.

OnBoardC always automatically includes the contents of the supplied header file, OnBoardHeader.h, before any compilation. When launched, OnBoardC looks for a database 'CompilerData.OnBC' which contains a compressed version of the header. If it is found, all of the declarations in that database are added to the symbol table - as if OnBoardHeader.h had been included, only faster and using less memory. If it is not found, the compiler searches for OnBoardHeader.h, compiles it and builds the compressed header.

###

    5.3 Adding New (or Unsupported) APIs

The header file contains only a subset of the Palm's ROM API entry points, in order to access others you'll need to either add them to your source code or to the OnBoardHeader itself. If you make any changes to "OnBoardHeader.h", select 'Delete Header' from the Options menu, the next build will cause the header to get rebuilt (actually, re-compressed). Note that, even though only a subset of Palm APIs are defined in the OnBoardHeader header files, most of the SysTrap names _are_ pre-defined (they are actually in a resource in the assembler application). You can get the declaration you need from the Palm Reference Manual, then add the SYS_TRAP value - like this:

    	ReturnValue APIcall(Variables) SYS_TRAP(sysTrapAPIcall);

For example, to add access to the ROM routine 'StrCaselessCompare', you'd add the following to either your source or the OnBoardHeader.h file you're using:

    	Int16 StrCaselessCompare(const Char *s1, const Char *s2) SYS_TRAP
    	(sysTrapStrCaselessCompare);

The only extra trick there is that you will have to add a #define sysTrapPalmOSCall to the number specified in the Palm documentation.

If you want to make it available in all of your programs, you can add the calls to OnBoardHeader.h. (Be sure to follow the directions to blow off the precompiled version the first time after you add it, so your additions get found.)

###

    5.4 Building A Hack

To build a HackMaster hack extension, set the output type signature to 'HACK'. Don't use any global data (including string literals at this point, sorry). Include the line '#pragma segment 1000' before the function that will implement the hack, and don't have a PilotMain routine. There's a sample hack included with the download; 'casehack' - it simply forces all keyEvents to lower case, not very exciting I know, but hopefully it'll be enough of a help to get started.

Back to TOC

###

    5.5 Multi-Segmented Code

The bad news is that there's a limit of 32K to the size of a single branch in Palm code -- this can seriously limit the size of your programs. The good news is that you can get around this limit by creating multiple segments in your code. This section will describe how OnBoard C can be used to build a multi-segment application.

A segment is an island of code that doesn't have any branches greater than 32K inside of it. Function pointers are used as bridges between segments. Multiple segments, connected by these bridges, allow an application to grow to an arbitrarily large size. There's also a mechanism for accessing global variables between segments.

In order to build a multi-segment application in OnBoard C, do the following.

- One project per segment. Make a separate OnBoard C project for each segment in your application. Each project must have the same PRC name, type and creator; this will put all the generated code segments in the same PRC. Only one project/segment has a PilotMain in it -- that's your primary segment. Secondary segments are the ones without PilotMain.
- #pragma segment n. In each of the secondary segment source files, include the directive #pragma segment 2 (or #pragma segment 3 or so on -- each segment gets a different number). When you specify a '#pragma segment' directive, OnBoard C creates a separate code segment (with the number you specified) without any data segments. The code segment will cohabitate with code segements from other projects in the same PRC database.
- globals.c, globals.h.

  Create a file for globals (e.g. "globals.c") and include this file in each of the projects. This file includes the declaration of ALL global variables and a pointer to each function that will be called from one segment to another. You also have to define a corresponding "globals.h" file where the global variables are declared as "extern" and a MemHandle for each secondary code segment. All the "*.c" files in the project must include this header file.

  Note: do NOT define any static variables (either global or local) in your application. Because static variables are allocated in memory alongside globals, statics in one file will throw-off the position of globals in that project resulting in Palm system crashes.

  Note also that you may also define functions in the main 'code 1' segment which may be called by other segments by the same process.

- Setup the links. The first function in each secondary project must dynamically link the global function pointers to the segment's exported functions. This function (again, one per secondary project) must be called in a portion of code executed when application starts. This function has to be first in the segment so that the main segment can call this function with a known offset (i.e., zero) into the secondary segment.
- Dynamically link the secondary segments. In the main segment, define a memory handle to access each of the secondary code resources, lock it as a pointer to a void function and call it to perform dynamic link. This pointer must remain locked until the application stops.

In this way, you may define separately compiled units (it's faster to compile each unit). All the units may access the same global variables and all the units may call functions defined in other units.

The projects in a multi-segment can be compiled in any order.

####

    Example

Here is an example multiple segment application. It contains three segments, hence three projects. The files in our example are shown below:

- project 1 : seg_globals.c and seg_main.c
- project 2 : seg_globals.c and seg2_code2.c
- project 3 : seg_globals.c and seg3_code3.c

These files, themselves, are shown, below.

seg_globals.h This file is included by any "c" file that uses or defines a cross-segment function or global variable.
    	/* seg_globals.h */

    	// to be included in sources
    	// corresponding to "globals.c" defs

    	extern int x;
    	extern int (*incr_x)(int);
    	extern int (*decr_x)(int);
    	extern MemHandle Code2Handle,Code3Handle;

seg_globals.c This file is part of every project.
    	/* seg_globals.c */
    	// this file is included in all projects

    	// global variables shared by all units

    	int x;

    	// functions defined in various segments

    	int (*incr_x)(int);
    	int (*decr_x)(int);

    	// handle to code 2 and code 3 resources
    	MemHandle Code2Handle,Code3Handle;

seg2_code2.c This file, along with seg_globals.c, is part of project 2.
    	/* seg2_code2.c */
    	#pragma segment 2
    	#include "seg_globals.h"

    	// prototype definition
    	int incr_x_local(int);

    	// dynamic link function called in main.  This function MUST
    	// be the first function defined in the first file of the project

    	void Code2Init() { incr_x = incr_x_local; }

    	// definition of function called from another segment

    	int incr_x_local(int a)
    	{
    		x+=a;
    		return x;
    	}

seg3_code3.c This file, along with seg_globals.c, is part of project 3.
    	/* seg3_code3.c */
    	#pragma segment 3
    	#include "seg_globals.h"

    	// prototype definition
    	int decr_x_local(int);

    	// dynamic link function called in main.  This function MUST
    	// be the first function defined in the first file of the project

    	void Code3Init() { decr_x = decr_x_local; }

    	// definition of 'code 3' functions
    	int decr_x_local(int a)
    	{
    		return incr_x(-a);
    	}

Following is the complete seg_main.c. Much of the code isn't necessary for illustration of multi-segment programming but it has the advantage of being complete -- cut and paste and you have a running, multi-segment, OnBoard C program. All code in this function that is required for multi-segment programming is commented with the string 'MULTI-SEG' and is highlighted in red.

seg_main.c This file is part of project 1.
    	/* seg_main.c */
    	#include "seg_globals.h"

    	#define MainForm	1000
    	#define UpButton	1001
    	#define DnButton	1002

    	// MULTI-SEG: need this API but it's not in OnBoardHeader.h
    	#define sysSysCurAppDatabase 0xa0ac
    	Err SysCurAppDatabase (UInt16	*card, LocalID	*id)
    		SYS_TRAP(sysSysCurAppDatabase);

    	void showX(void);

    	static Boolean	appHandleEvent (EventPtr event);
    	static void	mainFormInit (FormPtr form);
    	static Boolean	mainFormEventHandler (EventPtr event);

    	/*
    	 * MULTI-SEG: This function sets up the dynamic links to the function
    	 * pointers used to communicate across segments.  It does that by
    	 * calling the first function in every other segment (remember that
    	 * we carefully made each secondary segment's first function the
    	 * dynamic link function).
    	 */

    	static void startApp()
    	{

    		UInt16		cardno;
    		LocalID		id;
    		DmOpenRef	db;
    		void		(*DynLink)(void);

    		// get handle to code 2 and 3 resources in our application's
    		//  database
    		SysCurAppDatabase(&cardno,&id);
    		db=DmOpenDatabase (cardno,id,dmModeReadOnly);
    		Code2Handle=DmGetResource ('code',2);
    		Code3Handle=DmGetResource ('code',3);
    		DmCloseDatabase(db);

    		// get ptr to 'code 2' dynamic lnk function and call it

    		DynLink=MemHandleLock (Code2Handle);
    		DynLink();

    		// same for 'code 3'

    		DynLink=MemHandleLock (Code3Handle);
    		DynLink();

    		// set the global, x

    		x=16;

    		return;
    	}

    	// MULTI-SEG: gotta unlock the code handles

    	static void stopApp()
    	{

    		MemHandleUnlock(Code2Handle);
    		MemHandleUnlock(Code3Handle);

    		return;
    	}

    	/*
    	 * Completely normal PilotMain
    	 */

    		UInt32
    	PilotMain	(UInt16	cmd,
    			 void		*cmdPBP,
    			UInt16	launchFlags)
    	{
    	  EventType	event;
    	  UInt16	error;
    	  if (cmd == sysAppLaunchCmdNormalLaunch)
    	  {
    	    startApp();
    	    FrmGotoForm(MainForm);
    	    do
    	    {
    		EvtGetEvent (&event, evtWaitForever);

    		if (!SysHandleEvent (&event))
    		if (!MenuHandleEvent (0, &event, &error))
    		if (!appHandleEvent (&event))
    			FrmDispatchEvent (&event);
    	    } while (event.eType != appStopEvent);

    	    stopApp();
    	    FrmCloseAllForms();
    	  }
    	  return 0;
    	}

    	/*
    	 * Completely normal appHandleEvent
    	 */

    	static Boolean appHandleEvent (EventPtr event)
    	{
    	  FormPtr	frm;
    	  UInt16	formId;
    	  Boolean	handled = false;

    	  if (event->eType == frmLoadEvent)
    	  {
    	    // Load the resource for the form

    	    formId	= event->data.frmLoad.formID;
    	    frm		= FrmInitForm(formId);
    	    FrmSetActiveForm(frm);

    	    // install a form-specific event hdlr

    	    if (formId == MainForm)
    		FrmSetEventHandler (frm, mainFormEventHandler);

    	    handled = true;
    	  }
    	  return handled;
    	}

    	/*
    	 * Only slightly abnormal mainFormEventHandler.  This function
    	 *
    	 */

    		static Boolean
    	mainFormEventHandler (EventPtr event)
    	{
    	  Boolean	handled	= false;
    	  FormPtr	frmP	= FrmGetActiveForm();
    	  switch (event->eType)
    	  {
    	    /*
    	     * the first event received by a form's event handler is the
    	     * frmOpenEvent.
    	     */
    	  case frmOpenEvent:
    		FrmDrawForm(frmP);
    		mainFormInit(frmP);
    		showX();
    		handled = true;
    		break;

    	case ctlSelectEvent:
    		switch (event->data.ctlSelect.controlID)
    		{
    		case UpButton:

    			// MULT-SEG: call function in another segment
    			x= (*incr_x)(4);

    			showX();
    			handled	= true;
    			break;
    		case DnButton:

    			// MULT-SEG: call function in another segment
    			x= (*decr_x)(2);

    			showX();
    			handled	= true;
    			break;
    		} // switch which button
    		break;

    	  } // switch event type
    	  return handled;
    	}

    	static void mainFormInit (FormPtr frmP) { }

    	// Other Useful Bits

    	void showX(void)
    	{
    		Char	bar[40];
    		StrPrintF (bar, "num %03d", x);
    		WinDrawChars(bar, StrLen(bar), 60, 30);
    	}

###

    5.6 Using OnBoard C's Auto-Versioning

You can get OnBoard C to automatically number your versions (actually, your builds) for you. With this feature enabled, OnBoard C increments a build number each time you compile. Here's how you do this.

First, you need to enable the feature. On OnBoard C's main form, there's a checkbox marked 'Auto Version'. Check the checkbox.

Now, you need a version for OnBoard C to update. This is in the form of a tVer resource. Starting in OnBoard C, do the following:

- tap on the .rsrc file in your file list
- tap the 'RsrcEdit' button; this will bring-up RsrcEdit.

In RsrcEdit, do the following:

- tap the 'menu' silkscreen button,
- tap 'new'->'Version String'; this will open the version form,
- enter a string that has digits for the last 4 characters. I typically like something like 'v1.0 build 0000',
- under 'ID', write '1000' -- REMEMBER THIS NUMBER,
- tap the 'okay' button.
- tap the 'OnBoardC' (or 'QuartusC') button; this will take you to OnBoard C (note that this button will only be available if you invoked RsrcEdit from OnBoard C -- if you got here via the Palm application launcher, you'll have to get back to OnBoard C via the application launcher).

Now, OnBoard C will automatically update your version number but I'll bet you want this information to appear someplace in your code. Have no fear, we can do that. In your code, do the following:

    	MemHandle	hVer	= DmGetResource ('tver',
    						1000);	// that's the number
    							// you remembered
    	char		*pVer	= MemHandleLock (hVer);

    	// Now, you have a string that points to your version --
    	// use the string as you would like to

    	MemHandleUnlock (hVer);
    	DmReleaseResource (hVer);

Back to TOC

##

    6. Reference Guide

###

    6.1 Menus Buttons And Check Boxes

####

    OnBoard C -- Main Form

The 'Build' button begins the compile process.

The 'Add' button adds files into the project.

The 'Remove' button allows for removing the selected file from the project.

The 'Edit' button launches the appropriate editor for the selected file.

The 'Type' field specifies the 4 character database type signature of the output. This is usually set to 'appl' for an application, or 'HACK' for a HackMaster hack.

The 'Creator' field specifies the 4 character database creator signature of the output, set at the user's whim to uniquely identify the output database. All lower case creator signatures are reserved for the Palm system files.

The 'PRC name' field specifies the name of the output database. This is not necessarily the same as the application name shown in the launcher (which is whatever string is stored in resource 'tAIN' #1000)

The 'Execute' checkbox, when checked, signals OnBoardC to launch the application after it's been successfully built.

The "Always Rebuild' checkbox, when checked, causes OnBoardC to delete it's intermediate files after compilation. As a result, OnBoardC will always recompile every source file whether it's been modified since the last build or not - this saves space on the Palm and handles cases where an editor might not have updated the modification date for the source file.

The 'Auto version' checkbox causes OnBoard C to bump-up a version count every time a project is compiled. For details on how to use this feature, check out the section on using OnBoard C's auto-versioning.

The 'Debug' checkbox...

####

    OnBoard C -- 'Add To Project' Form

This form includes a list of all the available files of either pEdit, Doc, Memo or Resource type. Doc files are identified by type 'TEXt', creator 'REAd', Memo files are the records in the MemoPad database that begin with a line formatted as "/* filename.[ch] */ to designate the name of the source file (e.g. /* Foo.c */ or /* Foo.h */). Resource files have type 'Rsrc' or an extension '.Rsrc' or '.rsrc', they can be generated with RsrcEdit

####

    From the 'Options' menu :

'Delete Header' - deletes the pre-compiled header that OnBoardC uses for speedy access to the Palm ROM API, this is only used when making changes to the header file (see 'Some dirty internal details' below).

'Choose Editor' - provides a dialog box to specify which editor to launch for the Memo or Doc source files when either the 'edit' button is pressed or 'Goto' selected from the compile-error alert.

####

    From the 'Project' menu :

'Delete Object Code' - deletes any intermediate files for the current project. This frees up the space they occupy and forces each source file to be re-built when 'Build' is pressed rather than depending on the source file modification timestamp.

'New Project' - launches a dialog that prompts for the new project name. It also provides a checkbox 'Generate Skeleton' which populates the new project with the necessary files to build an empty application. For example creating a new project named 'Cardiff' will produce the project file 'Cardiff.proj', a source file 'Cardiff.c' and resource file 'Cardiff.Rsrc'. When built, the application 'Cardiff' has an empty main form with a single 'About Cardiff' menu item and dialog.

'Open Project' - opens a dialog to select from the other OnBoardC projects.

'Rename Project' - opens a dialog to change the name of the current project.

'Delete Project' - opens a dialog to delete existing OnBoardC projects.

Back to TOC

##

    7. Answers To A Few Questions

###

    7.1 Can I write code for some Palm platforms and have it work on others?

Yup, things work across platforms that run the PalmOS (e.g., Visor, Handera, Palm, Clie, etc.) Just don't put calls that are specific to one device (e.g., Springboard calls on a Visor or enhanced resolution stuff on a Clie) and expect your program to run on a different platform.

Note: your code will only work on Palm platforms -- not PocketPC, or Blackberry, or other handheld devices. Also note that an application built for one major processor type (i.e., Dragonball/68K or ARM) won't work on a Palm platform running the other major processor type.

###

    7.2 Is it possible to compile with a larger stack with OnBoardC?

There may be a resource that is part of an app that specifies what size stack you get but it is not part of OnBoard C per se.

###

    7.3 How do you generate a header file from RsrcEdit?

Get into the top-level form of resource edit (if you're editing a specific resource file, hit the 'done' button in the lower right hand corner of the screen). In the top-level form, select the relevant '.rsrc' file. Off the menu bar, select 'Build Resource List'. It'll ask you if you want a DOC file or a Memo file. You'll then have a '.h' file with marginally useful defines for all the resources in the file.

###

    7.4 How do you share my OnBoard C projects with CodeWarrior or the PRC-Tools?

The 'Sherpa' tool, part of the OnBoard Suite, ports code from the Palm to the host to be built with the PRC tools. In future incarnations, Sherpa will also port code back from the host (PRC tools) to the Palm. Sherpa currently requires that the doc format is used for source files on the Palm.

There still may be some portability issues. No two compilers are 100% compatible so there may be some differences that you have to address. The most probable problem is a mismatch in data types. Another compatibility problem is that OnBoard C doesn't have the error checking that host- based compilers do. Instead of investing effort documenting the known differences, the OnBoard Suite development team will put their effort into making the two compilers more compatible.

Sherpa is designed to make the OnBoard Suite compatible with the PRC tools. If you're using CodeWarrior, there's a good tutorial at http://www.xpinneret.com/OBC_and_CW.html.

Note: OnBoard C has very little code optimization and no register allocation. The same code that may have worked with GCC or CodeWarrior very well could be generated too large by OnBoard C.

Back to TOC

##

    8. Common Problems

8.1 Out Of Node Space

###

    8.1 Out Of Node Space

This is caused by complex 'if' statements with lots of conditions and expressions. Things should work better if you rewrite that line of code to be more than one statement:

             if (a || (b && c)) foo();       // instead of this

             if (a) foo(); else if (b&&c) foo();     // try this

###

    8.2 Unknown Identifier <Palm API>

If OnBoard C tells you that you have an Unknown Identifier in your code and you know that this is a Palm API, then you've probably picked a Palm API that is not in OnBoardHeader.h. Check out section 5.3 Adding New APIs to learn how to add the API that you need to your code.

Back to TOC

##

    9. Thanks!

I'm going to try to get everyone. If you contributed or know someone who did that's not in here, please let me know.

    	Keithen and Roger at individeo DOT net
    	"Alice Campbell" <acampbell AT scsengineers DOT com>
    	"davidsvisor" <david AT xpinneret DOT com>
    	"Dinesh Ramalingam (IE10)" <Dinesh DOT Ramalingam AT honeywell DOT com>
    	"drawitpalm" <andrew AT drawit DOT co DOT nz>
    	"gomezbenz" <gomezbenz AT yahoo DOT com>
    	"gubihu" <gubi AT icss DOT hu>
    	"Haemish Graham" <haemish AT astraware DOT com>
    	"hkonstas2001" <hkonstas AT total DOT net>
    	"jdhedden" <jdhedden AT yahoo DOT com>
    	"John P. Pywtorak" <jpywtora AT calpoly DOT edu>
    	"John Wilund" <orlando AT runbox DOT com>
    	"Laurent THALER" <lthaler AT free DOT fr>
    	"Mike LaFleur" <lafleur911 AT yahoo DOT com>
    	"Philippe Guillot" <ph DOT guillot AT wanadoo DOT fr>
    	"William F. Hostman" <aramis AT gci DOT net>
    	"yogsototh76" <yogsototh76 AT yahoo DOT fr>

Back to TOC