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:


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.


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:

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  


Helpful Source Code  

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


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.


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: 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. Then, in the OnBoard C mainform, do the following. 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:


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:

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

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


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: 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.


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.

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:

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:

In RsrcEdit, do the following:

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