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

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

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

2.1 The OnBoard C Distribution

RsrcEdit  

Install the OnBoard Suite 

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

Install the Other Stuff You Need (see above)   

OnBoardCompatibility.h 

Rebuilding OnBoardHeader.h 

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

So What's an OnBoard C Project?   

Creating a Project 

4.1 How is OnBoard C different from ANSI standard C?

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

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.

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.

5.1 Support For Other Editors

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.

	ReturnValue APIcall(Variables) SYS_TRAP(sysTrapAPIcall);

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

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

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.

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

Example 

• 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

	/* 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 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 */
	#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 */
	#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 */
	#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);
	}

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.

• 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).

	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);

OnBoard C -- Main Form 

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.

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

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.

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.

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

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