Tech Note 05f: A PP Compiler Shared Library Example

Tech Note 05f: A PalmOS Pascal Compiler Shared Library Example for NSBasic

November 26, 2003

© NSB Corporation. All rights reserved.

This very small and simple tech note is meant to be a template for creating other Shared Libraries using free PalmOS Pascal Compiler. This project really doesn't do much of anything useful but it should serve as a good starting point. You will see that it is *very* easy to create a SL for NSBasic using PP Compiler.

First, you should download the needed files:

1) PPNSBasicLib.pas - It's our PP source code in Palm DOC format (PDB).
2) PPNSBLibTest.prj - It's our NSBasic project to test our new SL.
3) PPNSBLib.inf - It's our "inf" file, describing each function as an interface between SL and NSBasic.
4) PP Compiler Enviroment - It's a merged enviroment in a SSF file.

You can download all of them clicking here (252 Kb).
You can see a brief description of them here.

I adapted this example from the Shared Library example that comes with PP Compiler.
If you wish to take a look at PP source code before continue reading, click here.

As I said, it is meant to be a template for other SL and you will verify that is quite simple to insert your own functions using this template.

The two functions in the shared library example demonstrate just an addition and a multiplication. I tried to make this example both simple and comprehensive enough to be useful.

Important: Anything starting with "THIS" means that it belongs to "this" library. Since this example is only meant for use with NSBasic programs, you can safely leave the "THIS" in your own libraries because NSBasic uses the information in the .inf file and not any identifiers in the code itself.

In order to make things straight forward our objectives, I created a special PP Compiler enviroment using a SSF file that you can open with your PalmOS Simulator. Last version should be installed with NSBasic 4.0. If you don't have Simulator 5.3, please, download it here.

As soon as you have it running, you would see these three icons in "Unfiled" category: Piaf, PP Shell and PPNSBLibtTest.

Following these screenshots, you will be able to compile your first Shared Library. After, using some Pascal knowlegde, you will be able to, sooner than you can imagine, try some modifications or even a total new Shared Library. Hope you share it with us :)

Later, if you wish to create your own PP enviroment, using your own Palm device, for example, just follow this link. Or, if you wish to edit your SL in a Windows IDE, you may use Fozzy.

There are some curiosities, just in case you would like to know. You don't need.

Well, that is enough to get started. Don't forget to study our template. Print it as a quick reference.

Descriptions

PPNSBasicLib PAS File - PalmOS Pascal Compiler Library source code

function This_LibAdd(refnum:UInt16;a,b:integer;result:resultP):Err;
begin
result^:=a+b;
This_LibAdd:=0;
end;

function This_LibMul(refnum:UInt16;a,b:integer;result:resultP):Err;
begin
result^:=a*b;
This_LibMul:=0;
end;

PPNSBasicLib INF File - NSBasic INF source code

[General]
ExtensionName=PPNSB
PrcName=PPNSBasicLib.prc
Version=1.0
Manufacturer=Adrian Nicolaiev - http://www.niconnect.com
InfVers=2.0

[GlobalMethods]
PPNSB_ADD=1, func, 2, "PPNSB_ADD(in a as integer, in b as integer) as integer"
PPNSB_MUL=2, func, 2, "PPNSB_MUL(in a as integer, in b as integer) as integer"

PPNSBLibTest PRJ File - NSBasic Project source code

Startup()
LoadLibrary PPNSBasicLib.inf

Object()
result = PPNSBasicLib.PPNSB_ADD(aa,bb)
MsgBox Str(result)
result = PPNSBasicLib.PPNSB_MUL(aa,bb)
MsgBox Str(result)

Some ScreenShots that may help


Screenshot 01 After starting Piaf, click on "O" and choose PNSBasicLib.pas. Click OK.	Screenshot 02 You should see this source code.

Screenshot 03 These lines show the two simple functions Add and Mul. Here you can see the Shared Library name too.	Screenshot 04 Here, you see the last lines of our Shared Library. Add and Mul are the last ones, after Open, Close, Sleep and Wake (internal functions - don't worry about them - just KISS)

Screenshot 05 To compile, just click on "B". It took 0.32 seconds to compile 568 lines in my computer.	Screenshot 06 Next step: Go to Launcher Applications menu and choose "Copy...".

Screenshot 07 Choose PPNSBasicLib. Verify that "Copy To:" is set to POSESlot1, your simulated Expansion Card. So, look at \Card1\PALM\Launcher\ folder in your Simulator folder. PPNSBasicLib.prc should be there after "Copy".	Screenshot 08 Are you read to test? Start our PPNSBLibTest program. That one you compiled in NSBasic.

Screenshot 09 Choose your numbers and get a MUL result	Screenshot 10 Choose your numbers and get an ADD result

Some curiosities


Curiosity 1 Q.: But, how is PPNSBasicLib inside? A.: It just has our famous "libr" resource	Curiosity 2 Q.: And PPNSBasicLib.pas? A.: It is just a Palm DOC file, with a header and our Pascal source code in the second record. If you wish, you may open this file in any Palm DOC reader.

Curiosity 3 As I said, here it is our Pascal source code...	Curiosity 4 Here, we have an inside view of our PPNSBLibTest program created with NSBasic.

Fozzy is a free IDE for PP Compiler. You may download the latest version here.

After that, you will be able to start creating your own libraries.

Good luck ! (You won't need :)

Adrian Nicolaiev
http://www.niconnect.com