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

1.2 Licensing

• 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

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

2.2 Other Stuff You Might Need

RsrcEdit  

2.3 Install The OnBoard Suite

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)   

2.4 A Word or Two About Upgrading

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.

4.2 stdio vs. Palm api

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

5.2 Some Dirty Internal Details 

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

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

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?

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?

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.

8.1 Out Of Node Space

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

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

8.2 Unknown Identifier <Palm API>