Install Nutshell for Palm OS as you would a regular Palm program. You should refer to your Palm User's Guide for information on installing Palm programs.
Main Screen
Nutshell's main screen provides a list of all databases present on your device and expansion cards. (All programs and data are referred to as databases.) Items with a padlock indicator are copy-protected and cannot be beamed.
Categories and Filters
The category selector can used to show only a specific type of database distinguished by Palm OS database "type". For example, you may view all executable PRC programs, all hack modules, all E-Books/Doc Files or all Palm VII PQA modules.
The "Name Filter" category allows you to view all databases containing a particular word, phrase, or series of letter.
The "Type Filter" and "Creator ID Filter" categories allow you to view specific Palm file types.
The "Selected Items" category displays all databases that have been selected for transfer.
The "Last Used" category displays the last files that were added to an installer.
The "Favorites" category is a custom category for frequently used items. Add favorites using the "Add To Favorites" drop-down menu item. While in the "Favorites" category, a "Remove from Favorites" menu item will show up instead.
Choose databases by tapping list items to place checkboxes in the left-hand column. The size of each database in kilobytes is listed to the right of the name.
Including Address and Datebook Items
Use the other tabs to access Datebook items and Address items to add to your Nutshell installer.
Choose Datebook items one day at a time using the date selector, or choose to view an entire month of data at a time, using the "Month View" icon.
Memory Buffer
Nutshell needs room on the Palm device to save the installer that you are about to create. As you choose items, Nutshell will indicate how much data can be added to a new installer. When the memory buffer reaches 100%, you have reached your maximum. This percentage is based upon the amount of memory available on the device.
Batch Beaming Files
You can use the beaming feature to beam any databases to any other Palm device.
To beam databases, mark the databases with checkboxes and tap the "Beam" button.
Batch Deleting Files
To batch delete databases, mark the databases with checkboxes and choose "Delete Selected Items" from the drop-down menu. Use caution when deleting databases that you do not recognize. The Palm uses many hidden files which may contain important information. Before deleting large amounts of files, you can use the "Selected Items" category to review your selected items.
Select All/Deselect All
"Select All" and "Deselect All" are available in the dropdown menus. "Select All" will select all items in the current category. "Deselect All" will deselect all databases in all categories.
Hide/Show System Databases
Nutshell conveniently hides read-only databases and Palm OS 5 "a68k" databases. If you wish to view them, the drop-down menu provides an option called "Show System Databases".
Choosing Files For An Expansion Card
Nutshell provides the ability to install files and directories to an expansion card. Tap the small card icon to the right of the contacts tab to access the expansion card file list. Provide a list of directories and/or file names on your storage card that should be included in the Nutshell. Nutshell will include all directories and files included within the specified directories, and reproduce the directory structure on the expansion card when the installer runs. If no expansion card is present, the expansion card installation phase will be skipped. On devices with internal storage such as the LifeDrive or T5, the internal card will be used for installation.
Settings Screen
Once you have chosen the files to include, tap the "Create Installer" button. The settings screen contains the following options:
Icon Name
The icon name will show up as the application icon in the Palm's main menu. This should be short enough to fit in the small space provided by the launcher.
Database Name
This field sets the installer's database name. A Palm OS database name must be unique on a Palm device. Installing a file with a duplicate database name will replace the existing file. Therefore, you should choose a database name for your installer, and continue to use this name for future versions of your installer. That will ensure that older copies of your installer will be replaced by newer ones. Database names are limited to 31 characters.
Description Text
The "Description Text" will be displayed to the user while the installer is running. If the installer contents is small, this message may not even stay on the screen long enough to be readable.
Automatically Launch
If any of the files that you have selected are executable programs or PQA files, then an "Automatically Launch" checkbox will show up will a list of programs to choose from.
Options Screen
Tap "Options" to access more options:
Installer Can't Be Beamed
This option will prevent the Nutshell installer from being beamed. A padlock icon will be displayed next to the database in beaming applications.
Ask Before Replacing DBs
You may specify whether or not the user is asked about replacing files that already exist during the install process. If this option is chosen, the user must confirm before replacing any database that already exists on the device. A "Replace All" option will be provided
Auto-Delete Installer
Installers will delete themselves after installation. This option is recommended since it is unlikely that a user will need to install your software twice. Installers run from an expansion card will not auto-delete.
Uninstaller
Select "Uninstaller" to create an uninstaller along with your installer. The uninstaller is not installed by the installer, but can be installed separately by the user. The uninstaller program will confirm the process with the user and then delete all files installed by the installer.
Warn User if Different Version is Detected
If this option is selected, the uninstaller will warn the user if it is about to uninstall a different version of an app than was originally installed. Note that in earlier versions of Nutshell, there was no option for this, and it always happened.
the user and then delete all files installed by the installer.
Remove All Files With Included Creator IDs
Use this option if your app creates new PDB files after it is installed. When the uninstaller runs, it will erase all files and databases with your app's creator ID. (Without this option, the uninstaller will just delete exactly what it originally installed.)
Inherit Icon From Auto-Launch App
If you choose an auto-launch application, then you can choose to have your installer automatically use the application's icon.
Creator ID
Since the installer is an actual program, it is necessary for it to have a creator ID. A creator ID is a unique four letter code assigned to Palm programs and databases.
IMPORTANT: If you need multiple Nutshell installers to show up individually in the Palm's main menu or Palm's built-in beaming list, you must assign each Nutshell installer a unique Creator ID. This only applies to some Palm OS versions.
Category
Specifies the default launcher category in which the installer will show up.
Version
This is the version number that will show up in the Palm's Info window. Any text string can be provided.
Extras Screen
More settings are located in the "Extras" screen:
Automatically Run After HotSync or Beam
The installer will run automatically after it arrives on a device, either via HotSync or a beaming transfer.
Use Compression
This option will use ZIP compression to reduce the size of your installer by up to 70%. On slower Palm devices, this may increase the time it takes to install.
Preserve Address Book Categories
When installing new Address Book entries, this feature will put them in the appropriate category. This feature will create a new category if necessary.
Prevent Duplicate Contacts and Appts
When installing Address and Datebook records, this feature will compare incoming records with existing records to ensure that duplicate entries are not created.
Prevent Installation on Palm OS 5/6 or Higher
Check this box if you want to prevent the installer from running on a Palm OS 5 or 6 device. This is only desirable if you are distributing software that is not compatible with Palm OS 5/6.
(Note, Nutshell installers themselves are fully compatible with Palm OS 5 and 6.)
Minimum Palm OS
You may choose a minimum Palm OS version for the installer to run on. When a user attempts to run the installer on an OS version that is too old, they will be presented with an appropriate message, and the installation will not take place.
Languages Screen
You can choose to include installer alerts and messages for Spanish, French, Italian, German and Brazilian Portuguese. The languages will be chosen automatically based on the Palm device's locale. Each language adds about 2K to the installer.
Only Install Overlay DBs for Device Locale
Overlay databases are special Palm OS resource databases which allow developers to add new languages to applications. This checkbox enables a mechanism by which only the appropriate overlay database for a Palm device's locale will be installed. For example, your installer may include overlay databases for French, Spanish and Japanese. When the installer is run on a Spanish Palm, only the Spanish overlay database will be installed. When run on an English Palm, no overlays will be installed.
Saving and Restoring
You can save and restore Nutshell template files from an expansion card using the "Restore/Save" button. This allows you to save all of your configuration settings (included selected files) for later use. Note that an expansion card is necessary for this feature.
Compatibility with Desktop Nutshell
The settings files are compatible with Windows and Mac OS X Nutshell allowing you to type welcome messages, etc. and move settings between platforms. To move settings between the Palm and desktop, simply move the files to and from the /PALM/Nutshell directory on the expansion card.
Exporting an Installer
Once an installer has been created, you will want to move the installer PRC file to the desktop. Various methods can be used:
Using HotSync on a Windows PC
Choose "Custom..." from the HotSync menu on your PC. Set the "System" conduit to "Handheld Overwrites Desktop". HotSync your Palm device as usual. The Nutshell database will be backed up to a directory on your PC. The directory is usually:
(Note that the HotSync ID directory name may be a slightly mangled version of your HotSync ID.)
Using HotSync on Mac OS X
In the "HotSync Manager" application, choose "Conduit Settings" from the "HotSync" menu. Set the "Backup" conduit to "Backup". HotSync your Palm device as usual. The Nutshell archive will be backed up to a folder on your Macintosh.
The folder should usually be:
You can copy Nutshell files to an expansion card using the Palm's built-in copy feature. Files can then be moved to the desktop using a card reader. The installer file will show up in /PALM/Launcher on the card.
Using Palm OS Emulator
Right-click, and choose "Export Database" from the Palm OS Emulator menu. Choose to export the newly created Nutshell archive. Note, the database will have the name that you provided in the "database name" field, but the list of databases will be sorted by the "icon name" field.
Using Palm OS Simulator
To export files from the Palm OS Simulator, you must perform a HotSync operation to the desktop and then following the instructions for Using HotSync on a Windows PC above. For instructon on HotSyncing the Simulator see this page
Compatibility/System Requirements
Nutshell is compatible with Palm OS 3.0 or later. This includes Palm OS 5 and 6.
Nutshell is incompatible with !pZip v1.1. This may be corrected in later versions of !pZip.
