Importing and Exporting Programs into and from Free42

If you're familiar with the original HP-42S calculator, you will remember what a chore it could be to enter long programs using the keyboard. Since typing was the only way to get programs into the calculator, you just had to put up with this.
Free42, on the other hand, can save programs to files, so you can create back-up copies, load them on another computer, or share them with other Free42 users. The process of saving programs to files (exporting) and loading programs from files (importing) is explained in detail in the following sections.

The program files used by Free42 are compatible with several other HP calculator emulators, including Emu42 and V41. These files usually have names ending in ".raw". However, note that not all programs will actually work in all emulators, since those emulators don't all support the same instruction set; e.g. the HP-41 (and V41) does not have named variables, so instructions like STO "Q" will not work, and Emu42 does not provide printer and Time Module support, so instructions like PRX or DATE will not work.
Generally speaking, programs that stick to the basic HP-41C instruction set and that do not depend on the 24-character ALPHA register length nor any plug-in modules or peripherals, will work on the HP-42S, and in Emu42 and Free42, and of course on all the HP-41 series calculators and V41. Programs that stick to the basic HP-42S instruction set, and do not rely on printer emulation nor any of the Free42 extensions, will work on the HP-42S, and in Emu42 and Free42.

Contents

The Basics
All versions except iPhone / iPod touch / PalmOS / Mac OS X Dashboard
iPhone & iPod touch
PalmOS
   Using an SD Card
   Using the Free42 Filesystem
Mac OS X Dashboard

The Basics

First of all, we need to clarify just what is meant by "a program". On the HP-42S, just like its predecessor, the HP-41 series, there can be multiple programs in the calculator's memory, and each program ends with an END instruction. A program starts just after the previous program's END (except, of course, for the first program), and ends with its own END (except for the last program, which ends with .END., but that is really also just an END; it just looks different, so you can tell where program memory ends).
Thus, every program has exactly one END instruction, which is always the last instruction in the program.

Programs also usually include one or more "global labels", that is, LBL instructions like LBL "HELLO". There are also "local labels", LBL 00 through LBL 99, LBL A through LBL J, and LBL a through LBL e; these are different in that they can only be called from within the same program.
The global labels and the END instructions are shown in the PGM catalog. You can see the PGM catalog by pressing CATALOG (Shift +) and then pressing the PGM menu key. You will also see the PGM catalog when you press XEQ.
Note that the PGM catalog will not show any END (or .END.) instructions for programs that contain one or more global labels. Also note that the order in which the global labels and END instructions appear in the PGM catalog is the reverse of the order in which they appear in program memory.

When you tell Free42 to export a program, by selecting its END or any of its global labels, it will always export the entire program, from just after the previous program's END (or, in the case of the first program, from the start of program memory) until its own END.
If you select multiple programs for export, they will all be written to one file, in the same order that they are in in program memory; when you import that file later, all those programs will be imported, still in the same order, and they will appear at the end of program memory, after any programs that were already there.

All versions except iPhone / iPod touch / PalmOS / Mac OS X Dashboard

To export: select "Export Programs" from the "File" menu:

A dialog box will appear that shows all the programs that currently exist in Free42's program memory. There will be exactly one line per program; if a program contains multiple global labels, they will all appear together on one line. If a program contains no global labels, you will see an END (or .END.). You can tell a global label named "END" or ".END." from an END or .END. instruction because label names are always in double quotes, while END and .END. instructions are not.

You can select multiple programs; the exact way in which to do this depends on which version you're using. In the Windows version, you can use dragging, shift-clicking, or control-clicking, for example, which is the usual behavior of list boxes on that platform; in the Mac version, you will see check boxes, which you select or deselect by clicking, etc.
When you've selected the programs you want to export, click OK. A standard file selection dialog will then appear:

Select the name and location where you want the file to be saved, and click Save... and you're done.

To import: select "Import Programs" from the "File" menu. A standard file selection dialog will appear; select the *.raw file you want to import, and click Open... and you're done.
(Sorry, no illustrations -- this is just like opening a file in any other application. You know how to do this.)

iPhone & iPod touch

On the iPhone (and iPod touch and iPad -- but I'll just say "iPhone" for the sake of brevity in the following), the challenge is not just getting programs into and out of Free42; you also need to get them onto and off the device somehow. Since the iPhone has no SD card slot, and does not support third-party Sync extensions for iTunes, the only remaining option is to use some form of wireless communication.

Free42 does this with a built-in web server. When the server is running, you can connect to it using a web browser on your Mac or PC, and upload and download programs just like you would in any other web site. To start the server, tap in the top part of the screen, just below the status bar:

This brings up the main menu. Tap "Program Import & Export":

This brings up the Import & Export menu. Tap "HTTP Server":

This starts the web server; your screen should now look like this:

NOTE: While the web server is active, the idle timer, which normally turns off your iPhone after some period of inactivity, is disabled. Be sure to stop the web server by pressing Done when you no longer need it, to prevent accidentally running down the battery.

Next, point a web browser on your PC or Mac at the URL shown in the HTTP Server screen (see above):

You will see the top-level directory of Free42's private file area. It contains three directories: config, where the emulator stores its persistent state; memory, where you can see the emulator's program memory; and skins, where Free42 looks for additional skins.
You can upload files into the currently selected directory by clicking Browse, selecting the file, and then clicking Upload, and you can download files simply by clicking on them.

When you select memory, you will see a view like this:

The file listing shows one line per program. You may notice that the program sizes shown in this listing are always 3 bytes larger than the sizes shown in Free42 itself; the reason for this is that I wanted the program size shown in the web server to match the sizes of the files that are created when you download programs; the byte count shown in Free42 (and the HP-42S) does not include the 3 bytes for the END instruction, but since that instruction is included in *.raw files, they are always 3 bytes larger.

Note that memory isn't really a directory, it just looks like one. Free42 fakes it to allow you to load programs directly from program memory to files on your PC and vice versa, without needing the intermediate step of creating files on the iPhone first.

To import and export programs to local files on the iPhone, you use the Import Programs and Export Programs commands in the Import & Export Menu. Read the instructions for the other versions to learn how this works.
You will still need to use to use the HTTP Server to get the local files onto or off the device, but having programs in local files can be useful if you want to be able to have local backups that you can restore after CLALL, or when you have made modifications to a program and want to roll them back.

PalmOS

Using an SD Card

To export: select "Export Programs" from the "File" menu:

A dialog box will appear that shows all the programs that currently exist in Free42's program memory. There will be exactly one line per program; if a program contains multiple global labels, they will all appear together on one line. If a program contains no global labels, you will see an END (or .END.). You can tell a global label named "END" or ".END." from an END or .END. instruction because label names are always in double quotes, while END and .END. instructions are not.

You can select one or more programs by checking the corresponding check boxes. When you've selected the programs you want to export, click OK. A file selection dialog will then appear:

In the <volumes> list, the top entry is always called Free42, with a small PDA icon next to it; this is the built-in Free42 filesystem, which is covered in the next section. The following items in the list are VFS filesystems, with small SD card icons next to them. Select your SD card by clicking on its name, and select the name and location where you want the file to be saved, and click Save... and you're done.

To import: select "Import Programs" from the "File" menu. A file selection dialog will appear; select the *.raw file you want to import, and click Open... and you're done.
(Sorry, no illustrations -- this is just like opening a file in any other application. You know how to do this.)

Using the Free42 Filesystem

In case using an SD card is not an option, such as on the Palm V, m100, or Z22, you can use the built-in Free42 filesystem instead. (You can use the Free42 filesystem on all PalmOS devices, actually, but SD cards are often more convenient.) Within Free42, the Free42 filesystem looks just like an SD card, except that it is always named Free42 and it is shown with a little PDA icon instead of an SD card icon.

In order to get files from the Free42 filesystem to your PC or vice versa, you will need a Windows PC with HotSync Manager installed. The file transfer between the Free42 filesystem on the Palm and the PC is performed by the Free42 Conduit, which is included in the Free42 package. In order to install it, unzip the Free42PalmOS.zip package, and double-click Free42ConduitInstaller.exe. The Free42Conduit.dll, condmgr.dll, and HSAPI.dll files must be present in the same directory as Free42ConduitInstaller.exe. When prompted, select "Install Free42 Conduit", and click "Make It So". Once installation completes successfully, click Exit to finish the installer.

When you next perform a HotSync operation, the contents of the Free42 filesystem are copied to C:\Free42FileSys on the PC. If you want to use a different location, you can change it as follows:
Click on the HotSync Manager icon in the task bar...

Select "Custom" from the menu. A dialog box will appear, showing all the installed Conduits.

Select the Free42 Conduit and click Change.

Select the directory where you want the Free42 filesystem to be downloaded, and click OK; in the Custom window, click Done.

When you perform a HotSync, all the files on the Free42 filesystem that were created or modified since the last HotSync, will be downloaded to the PC. If you want to download the entire Free42 filesystem, regardless of file modification dates, select Util -> Force Download in Free42 on the Palm before HotSyncing.

When the HotSync completes, you will see any files that were downloaded by the Conduit, in the HotSync log. To view the log, click the HotSync Manager icon in the task bar, and in the menu, select View Log -> Your Username. You will see a log somewhat like this:

The Conduit can also upload files. To do this, put them in a directory called Upload at the top level of the download directory. When a HotSync is performed, all the files from the Upload directory are transferred to the Free42 filesystem on the Palm, but without the Upload directory itself, i.e. <DOWNLOADDIR>\Upload\path\to\file.raw on the PC will become /Free42/path/to/file.raw on the Palm:

After the upload is finished, the Upload directory is renamed to "Uploaded YYYY.MM.DD HH.MM.SS" so the files in it will not be uploaded again.

Note that only files from the Upload directory are uploaded. When a file is uploaded whose name matches that of an existing file in the Free42 filesystem, the new file replaces the old one. When a name collision occurs during a download, on the other hand, the existing file is first renamed by appending a sequence number to its name (.001, .002, etc., whichever number does not clash with any existing file).

Since the Free42 filesystem is not recognized by any of the Palm file managers, managing the files in it is a bit difficult. Free42 offers some support for this; in the Util menu, there are commands for copying and deleting files, removing directories, and erasing the entire filesystem. You can create new directories from any file selection dialog, by entering the desired directory name in the Name field and clicking MkDir.

Mac OS X Dashboard

Alas, the Mac OS X Dashboard version does not support import and export, and I have no plans to implement this functionality. I recommend using the Mac OS X application instead.

Go back.