Notes on RB plugin and Test application for accessing Newton 2.x OS data using Apple's DIL 2.0 Disclaimers ----------- The RB plugin was originally written and is copyrighted by Thomas Tempelmann, in January 2001. This software, including its source code, is free for anyone's use as long as the software using this code is available for free, too. In case the software using this software is commercially used (including shareware), permission has to be granted by me, the author, first. Contact: Thomas Tempelmann Updates of this software should always be available here: Version Information ------------------- Current Version: 1.5.2, built Feb 25, 2001 Usage ----- Ą On the Newton side the "Dock" (or "Connection") app is used for communication. Run the "Newton DIL Tester" on a Mac or Windows computer first, select the type of connection you want to use, and then open the "Dock" (or "Connection") app on the Newton and connect to the waiting desktop computer as you would do if you used Apple's NCU. The Newton should then build a connection with your desktop computer. From that point on, you can use the buttons in the windows as well as the menu to perform a lot of actions, mostly designed to view your Newton's data. For instance, press the "Browse Soups" button, then select the "Names" soup and press the "Find" button to search for a particular text in your Names file. Ą You can now also connect via IrDA (Macs with IrDA-Port only, such as newer PowerBooks and some iMac models) and TCP/IP, which works even on Windows - so, if you have a Ethernet PCMCIA card in your Newton, and connect it to a hub within the reach of your PC/Mac, you can make a high-speed connection to it as it was formerly only possible with the Mac-only AppleTalk protocol! For IrDA, it should work right out of the box. For TCP/IP, you have to have NIE (your basic Internet connection software for your Newton) installed, plus you have to install "DockTrnspTCPIP.pkg" on your Newton. With that installed, the Dock app will offer a new "TCIP/IP (TT)" selection on its "Connect via" popup. The first time you use the TCP/IP connection, you have to use the "Setup" button and enter the IP address of the computer that runs the DIL Tester. The address can be either a name if your computer has one (such as newtondock.xxx.org) or a raw IP number, such as "192.168.1.3". Ą This tool is giving you all the power to mess your Newton's data really up! So, don't use the "Edit" or "Delete" functions unless you really know what you're doing - anyone who can program the Newton should know enough to take care here. If you did not learn to program the Newton, then be careful before you experiment. To protect you from messing with your Newton's data I have added a preference that you have to enabled in order to be able to use the modification functions. To enable it, choose menu Edit->Preferences. I suggest you back up all your Newton data before trying to modify anything on it using this tool. However, as long as you only look at the data (using the "Open") buttons, you should be pretty safe (of course, something bad can always happen in software, although I'd not expect it - so make a backup first in any case, please!) Ą Currently, only data on the Internal Store can be viewed. Support for other stores will be added soon (Using REALbasic, you can easily change the line "storeNumber = 0" to any additional store if you wish. Ą The "Nick's Fort Knox" option is only useful for you if you use that app on the Newton. If that's the case, you can enter your PIN in the preferences dialog and then use the "Decode Knox" button to view all your Fort Knox data decoded (text only, however). I plan to add more convenient support to easier convert that data into a plain text file so that you can handle your "secret" data on your desktop computer then. Note that you need version 1.2.2 of FortKnox to get this working. You can download it here: Ą New in v1.5.2: You can now store any soups on your hard disk and then open & browse them later, without the need of your Newton being connected. This is the first step to making backups of your Newton data and being later able to access the data if your Newton should ever get lost or broken. (Leep in mind that Apple'S NCU does not let you do this: You can not access the backup files in order to export the data without having the Newton connected!) To store soups on your hard disk, first create a folder, when browse the soups, select some soups, and choose "Soups->Retrieve..." from the menu. Then you get to select the folder. After that, all the selected soups will be retrieved from the Newton and stored as folders and files in the chosen folder. Once you have these soup files stored on your computer, you can use "File->Open" from the menu to open and browse them. I plan to soon add a feature to export the data from common soups (Names, Dates, Notes) into better readable formats so that they can be further processed by your favourite desktop applications. Known Issues ------------ Ą Don't try to abort a data tranfer operation using the "Stop" button on the Newton. It'll probably freeze both the Newton and the Desktop computer. Ą Do not try to perform several data access tasks at the same time! For instance, while one soup is being opened, do not try to open another one. It'll cause errors. I will to block these actions from happening eventually, but for now just pay attention. Ą If you use the "Evaluate" function or the "Run Code" command, do not evaluate expressions that take more than a few seconds on the Newton, or otherwise the connection between the Newton and the Desktop computer may die. Whether this happens, also depends on the used transport. For example "GetGlobals" may work or work not depending on whether you try it on a Mac or on Windows, and whether you use Serial or AppleTalk. Ą If you delete a soup, sometimes an error (-50) occurs. I have not found out under what particular circumstances this happens. If you have an idea, please let me know. Ą If you delete a soup entry, windows of arrays or frames that were part of that entry will not automatically closed yet. If you continue to use them you may get errors. Ą Reconnecting without quitting the app should work, but does actually not work in some cases. If you get an error trying to connect, quit the app and try again. Ą The "Memory used by DIL" display appears to constantly increase under Windows, even if you close windows with Newton data in them, while under Mac OS the memory decreases again if you do that. Additionally, when quitting the Tester under Windows, a message appears saying "The DIL leaked". Seems to be a problem with REALbasic. I will look into this later. Ą When using the "TCP/IP (TT)" connection method in the Dock, sometimes the connection does not get closed when the Dock is closed. This seems to happen only if there was a communications error (the Newton would tell you with an alert message). In this case, you need to manually close the connection, e.g. by putting the Newton to sleep. Programming information ----------------------- Ą 68K CPU support is not possible because the only 68K DILs available use the register A5 for globals access. To work as RB plugins, however, A4 or "far" access to the globals is required. One could maybe hack this by creating a sufficient A5 space (one would have to find out how much A5 space the lib requires) and then switching to this special A5 space before calling any DIL functions. [Update] I tried the aforementioned, but it did not lead to success yet. Maybe I'll try again later. Ą Compiling the REALbasic application requires RB 3.0 - RB 2.1 will not work because some newer features are used in the plugin. And, of course, REALbasic is only available for Mac OS systems, although it can create both Mac and Windows applicatiosn, as this tool shows. No, I won't make may code compilable on other systems. However, Paul Guyot is working on an open-source multi-platform library, only that you'd still have to write your own UI for all the platforms. See: Acknowledgements ----------------- I want give my special thanks to Jim Anderson, who jumped in and wrote the User Interface for the TCP/IP tool after I asked for help on the NewtonTalk and nmap101 mailing lists about this. Laurent Daudelin and Paul Guyot were very helpful in getting the IrDA communications working. EOT