Contributed by Michael J. Verive, author of NS BASIC Programming for Palm OS

NSBasic for Palm provides the ability to add databases, libraries, and applications to your application's PRC as resources.  You can then extract these resources into their original databases on the Palm OS device. There are a few notes, however, and we'll cover those in a minute.

In order to add a database, library, or application as a resource to your PRC, you'll need to select "Add Resource" in the NSBasic IDE:

When the resource is added, it's given a resource ID automatically by the compiler (1004 in this example), and a Resource Type (DBIM by default):

NOTE: The Palm API used by dbCreateDatabaseFromResource was created to allow the Palm devices to extract sample databases to RAM from the Palm's ROM-based resources.  If you fail to check for the presence of a database prior to extracting it from your program's PRC, and the database already exists, the dbCreateDatabaseFromResource statement will return an error code of 537 (database exists), and the existing database will remain unchanged. The preferred method is to check for the presence of the database, and only extract it if it doesn't already exist:

Dim res as integer
Dim testdb as database
'now, attempt to open the database to see if it's there and available for read/write access
res=dbOpen(testdb,"PICULV-pdb",0)
If res =0 then ' it's available...
  res=dbClose(testdb) ' ...so we'll close it if we don't need to leave it open
Else ' database can't be opened for read/write access, so we'll attempt to create it from a resource
  res=dbCreateDatabaseFromResource("DBIM",1004) ' use resource type and ID from the IDE
  If res <>0 then ' can't extract it
    MsgBox "Unable to extract database"
  End If
End If

Notes

1. Once in the PRC, the database is identified by its Resource ID (generated automatically by the IDE), and Resource Type (defaults to DBIM, but can be set to anything you like).  If you change the Resource Type, be sure to also change the Resource Type used in the dbCreateDatabaseFromResource statement.

2. The maximum size of a resource is 64KB, so any databases, libraries, or applications > 64K each that you wish to include with the application will not be able to be bundled as a resource in the IDE.

3. Be EXTREMELY careful when using dbCreateDatabaseFromResource.  It's all too easy to assume that a database doesn't exist, attempt to extract it, and then also assume that the "new" database on the device was the one extracted from the resource. If the database was modified in any way, your application would then expect the unmodified data, and unexpected application behavior could occur. If you need to overwrite the existing database, you will probably want to delete the existing database, then extract the original database from the resource.

4. If you're including a shared library in your PRC, you'll need to use dbCreateDatabaseFromResource to extract the library before using LoadLibrary to load the library.

5. As in #3 above, be EXTREMELY careful when bundling shared libraries with your application, especially if these libraries are used by other applications as well, such as any shared library provided by NSB.  If you attempt to extract an early version of a shared library as a resource, and the device has a more recent version, your application may not function as intended. There currently is no version-checking built into the dbCreateDatabaseFromResource statement or its underlying API.

6. Creating a database from a resource does NOT remove the resource from the PRC, so the amount of memory required for the database or other resources you include will effectively be twice what it would have been had you distributed the resources separately.  Keep this in mind if you are using large resources (or many smaller ones), especially if your users' devices have limited memory.

As you can see, dbCreateDatabaseFromResource can be a powerful tool for making your applications easier to distribute (and beam from one user to another).  This power has a price, however, so be sure that you understand all of the ramifications of using dbCreateDatabaseFromResource before using it.