BKUP by Bob Apodaca 1 Contents 1 Description 3 1.1 Features . . . . . . . . . . . . . . . . . . . . . 3 1.2 Cost . . . . . . . . . . . . . . . . . . . . . . . 4 2 Requirements 4 2.1 HP48G(X) REV L and REV M . . . . . . . . . . . . . 4 2.2 HP48S(X) . . . . . . . . . . . . . . . . . . . . . . 4 2.3 Finding Suggested Programs . . . . . . . . . . . . . 4 3 Installation 5 4 Configuring BKUP 5 5 Reserved Variables 6 5.1 BKPAR . . . . . . . . . . . . . . . . . . . . . . . 6 5.2 STK . . . . . . . . . . . . . . . . . . . . . . . . 6 5.3 ARCD . . . . . . . . . . . . . . . . . . . . . . . . 7 6 "Special" Programs 7 6.1 Using STOFIX with BKUP . . . . . . . . . . . . . . 7 6.2 Using X-YModem 2.2 with BKUP . . . . . . . . . . . . 8 6.3 Using FXRECV with BKUP . . . . . . . . . . . . . . . 8 7 Backing-Up your HP48 9 8 Restoring a backed up file 9 9 Streamlining BKUP 10 10 Trouble Shooting 11 10.1 Trouble with Kermit . . . . . . . . . . . . . . . . 11 10.2 Trouble with XYSRVR . . . . . . . . . . . . . . . . 11 11 Bugs 12 11.1 HP48GX Covered Port Bugs . . . . . . . . . . . . . . 12 11.2 HP48S(X) Bugs . . . . . . . . . . . . . . . . . . . 13 12 Thanks 13 12.1 Description of BKPAR . . . . . . . . . . . . . . . . 14 2 13 Revision History 15 13.1 Improvements in Version 4.6 . . . . . . . . . . . 15 13.2 Improvements in Version 4.5 . . . . . . . . . . . 15 13.3 Improvements in Version 4.2 . . . . . . . . . . . 16 13.4 Improvements in Version 4.1 . . . . . . . . . . . 16 13.5 Improvements in Version 4.02 . . . . . . . . . . 16 13.6 Improvements in Version 4.01 . . . . . . . . . . 17 13.7 Improvements in Version 4.0 . . . . . . . . . . . 17 13.8 Improvements in Version 3.01 . . . . . . . . . . 17 13.9 Improvements in Version 3.0 . . . . . . . . . . . 18 13.10Improvements in Version 2.0 . . . . . . . . . . . 18 3 BKUP Version 4.6 by Bob Apodaca (bapodaca@mit.edu) Release Date: 08-95 Size: 3,315.5 bytes Checksum: # 8D34h This program can be distributed freely provided that the orig- inal instructions remain intact and unaltered. 1 Description BKUP is written entirely in system-rpl and is intended to make a backup of any port(s) the user specifies. There are options to save the stack and LASTARG, supplying a default name for the backup file, backing up flags, backing up HOME, as well as xmodem support. These options are selectable by a menu system similar to the IOPAR menu. BKUP has been tested on an HP48GX Rev M I believe BKUP works safely, but I do not assume responsibility for anything. Before you use this program for the first time, please make a backup of your HP48 using a proven method. 1.1 Features 1. Compatible with all versions of the HP48 series. 2. Only backs up the port(s) specified by the user. 3. Can be executed from any subdirectory, it is not confined to HOME. 4. Sends all libraries and backup objects to the serial port. If these libraries or backup objects have names greater than 8 characters, only the first 8 characters of the name are sent. 5. Can also backup the entire stack and LASTARG so they can also be restored when your HP is restored. 6. Simple-to-use user interface to configure options. 7. Supports more than one transfer protocol. 8. Reminds you when you made the your last backup. 9. Automatically does a warmstart if any libraries are restored. 4 1.2 Cost There is no monetary cost for using BKUP. However, if you use it on a regular basis I would be thrilled to hear about it. Please send me e-mail to "bapodaca@mit.edu". Feel free to comment about the program, the documentation, or features. Arrangements can also be made to receive a very nice postscript hardcopy of this document (providing that I am paid for copying and mailing costs). 2 Requirements BKUP requires memory to store the user's flags, a list of all the variables sent, the stack, and room for the BKUP program itself (except for the HP48GX with ports 2 or higher, see "Bugs" section). The user also needs a computer that can run kermit in server mode or an PC that can run a program called XYSERVER. If you do not wish to use kermit or XYSERVER, then BKUP will not be of any use to you. 2.1 HP48G(X) REV L and REV M If you have an HP48G or HP48GX you may wish to use STOFIX (Library 1222) to deal with problems involving storing objects in ports. You may also wish to use FXRECV to deal with problems with the built-in Xmodem. 2.2 HP48S(X) If you have an HP48S or HP48SX you may wish to use X- Ymodem 2.2 (Library 1275). This library contains xmodem com- mands that will enable you to make quicker backups. 2.3 Finding Suggested Programs The aforementioned programs are available (as of July 1995) at the following locations: 5 Program__ Location_ Path_ Name__ STOFIX cbs.cis.com pub/hp48g/utilities stofix.zip FXRECV Goodies Disc 9 HP fxrecv XYSRVR ftp.cis.com pub/hp48g/uploads xysrvr17.zip Kermit 3.01 HP Back to Sch fileman kermit.exe X-YMODEM 2.2 Goodies Disc 9 utils xymodem2.lib 3 Installation 1. Download the BKUP directory to your HP48. 2. Go into the BKUP directory. There should be six programs in the following order: BKUP, RESTO, CNFG, FLNM, BKPAR, ARCD. 3. If you wish to verify the checksum # 8D34h, recall the BKUP directory, then type BYTES. 4. You are finished installing BKUP. 4 Configuring BKUP Press the softkey associated with CNFG. You should see the current settings. The following are the default settings: DAY MM/DD/YY HH:MM:SSA BACK UP PORT(S): { } SAVE STACK & LASTARG: YES USE DEFAULT FILENAME: YES SAVE FLAGS: YES ARCHIVE HOME: YES PROTOCOL: HP48 KERMIT Press the corresponding key to toggle through program options. Press ATTN to exit the program. Any other key will give a BadKey beep. PORT can be any value between 0 and 33, inclusive. BKUP will attempt to back up any ports that are in this list. BKUP expects the numbers to be real integers. 6 SAVE can have a value of zero (corresponding to NO), or a nonzero value (corresponding to YES). If YES is selected, the stack and the last argument(s) will be saved. Otherwise, the stack will be left alone. FLNM can be YES (nonzero real integer) or NO (zero). If YES, the FLNM program will be used to generate a filename in the form of "HP48MMMDD.BAK" where MMM is the current month and DD is the current day. If YES is selected and the FLNM program doesn't exist, "HP48.BAK" is used. If NO is selected the user is prompted for a name. FLAG can be YES (nonzero real integer) which will save the flags. If NO is selected, the flags are not saved. If HOME is YES (nonzero real integer), the home directory is archived. If NO, home is not archived, but the stack, flags, any and port objects will be archived. PROT can be Kermit or a version of Xmodem. There are four supported protocols. HP48 Kermit (0), HP48 Xmodem (1), HP48 Xmodem and FXRECV (2), and X-Ymodem 2.2 (3). 5 Reserved Variables BKUP uses three reserved variables: BKPAR, STK, and ARCD. In order to use BKUP the way it was intended, the user should not use these three names to store any data, unless the data pertains to the BKUP program. 5.1 BKPAR BKPAR is a list that contains configuration information. If this variable is not present, BKUP will not execute. Please see Section 12.1 for a complete description of BKPAR. 5.2 STK The variable STK is created when the "Save Stack & Lastarg" option is selected. This variable is a user-rpl program that will restore the stack and the last argument(s) when executed. This program is stored in the home directory so that the user can restore the stack after a warmstart. 7 5.3 ARCD The variable ARCD should be a list of global variables. When you back up your HP48, BKUP will check to see if ARCD exists, and if ARCD exists it will append the contents of ARCD to a list so that the contents can be restored when the HOMEDIR is restored. ARCD was intended to save the user time when backing up the HP48. I often do not change the objects stored in port 0 and do not need to back them up everytime that I backup my HOMEDIR. So, I back up the objects in port 0 once, then put the names that BKUP sent into a list and store this list as ARCD. When I restore my HP48, all of the objects in port 0 will be restored. As stated previously, the contents of the list stored as ARCD should be global variables. These global variables are the library numbers and names of the backup objects to be restored. A library object should have the following name: 'L###.#' where the first three or four numbers are the library number and the number on the right of the decimal point is the port in which the library should be stored. For example, the JAZZ library has a number of 992 and I store JAZZ in port 0 so in order to restore JAZZ I should put 'L992.0' in the list that is stored as ARCD. A backup object should have the following name: 'BKOBNAME.#' where BKOBNAME is the first eight characters of the name of the backup object and # is the port in which the object will be stored. 6 "Special" Programs There are three programs that can be used in conjunction with BKUP: STOFIX (library 1222), X-Ymodem 2.2 (library 1275), and FXRECV. 6.1 Using STOFIX with BKUP The STOFIX library is one way to work around the STO bug present in the version M of the HP48GX ROM. This library allows the user to store object in ports greater than port 1. BKUP does not use STOFIX when sending port objects to a computer. However, BKUP does look for STOFIX when objects 8 are being restored. If STOFIX exists, BKUP uses the sto command from STOFIX to store all the port objects. If you recall, in order to use a library the user must download the library to the HP48, store the library, then turn the HP48 off and then back on. Since there is no way to make the HP48 download the STOFIX library, then turn itself off and back on, the user must do this. For these reasons, STOFIX is backed up by BKUP, but it will not be restored by BKUP. The user must restore the STOFIX library before the rest of the HP48 can be restored. 6.2 Using X-YModem 2.2 with BKUP X-YModem is a convenient way for users with an HP48S(X) to use the Xmodem transfer protocol. Generally, Xmodem transfers are much faster than kermit transfers. When the user selects the transfer protocol of "X-YModem 2.2" BKUP attempts to use the SENDM command from the X- YModem 2.2 library. If the library is not present, BKUP will give a "Undefined XLIB" error and stop executing. In order to use the Xmodem commands in the X-YModem library, the following steps must be done. First, the library must be downloaded to the HP48. Next, the library has to be stored in a port and then the HP48 must be turned off and then on. Now the commands in the X-YModem library are available for use by the user. Since there is no way to program the aforementioned proce- dure, X-YModem 2.2 must be restored by the user before the user attempts to restore the rest of the ports. BKUP sends all objects in port 0, if it finds X-YModem 2.2 stored in port 0, a copy of the library is sent to your computer, but BKUP does not record that a copy was sent and therefore does not try to restore X-YModem 2.2. 6.3 Using FXRECV with BKUP If you have an HP48G with the XRECV bug, you may want to use the FXRECV program so that you can download large files to your HP48. When the selected protocol is "HP48 XMo- dem/FXRECV", BKUP uses XSEND to send objects and uses 9 FXRECV to receive objects. BKUP will also send a copy of FXRECV so that the user can use the FXRECV program when restoring the HP48. What I suggest is that you use XRECV to download FXRECV to your HP48, then use FXRECV to download your backup HOMEDIR. BKUP will automatically use FXRECV to download your port objects. 7 Backing-Up your HP48 1. Load the Kermit or XYServer software up on your computer. 2. Make sure that the baud and parity of Kermit or XYServer match the baud and parity of your HP48. Also make sure that your HP48 is configured for wire transfers. 3. Using the CNFG program, make sure that BKUP transfer protocol is configured to match the software you are using on your computer. Also make sure the other options are set correctly. 4. Press the softkey associated with the BKUP program. 5. If you are using an HP48S(X), send a copy of X-Ymodem 2.2 to your computer using kermit. When you restore your calculator, send this file to your calculator, then the backup of the HOMEDIR. 8 Restoring a backed up file 1. Make sure IOPAR is set correctly. 2. If you are restoring your HP48S(X) and were using X- Ymodem 2.2, then send X-Ymodem 2.2 to your HP48 using kermit, do a warmstart, then continue. If you are using the STOFIX library, send STOFIX to your HP48, do a warm- start, then continue with these instructions. If you are using FXRECV, download it to your HP48 so that you can down- load your HOMEDIR (if HOMEDIR is larger than half of your available memory). 10 3. Download the backed up file (let's call it HP48.BAK) to your HP. If you Archived HOME, this will be a backup HOMEDIR. After you restore your HP48 using the RE- STORE command, go to the BKUP directory and look for a variable called HP48.BAK. This variable contains your flags, stack, and the names of the libraries BKUP sent to your computer. If you did not Archive HOME, then download HP48.BAK to your HP48. It will be a list of your flags, stack, and library numbers. 4. If you Archived HOME, recall 'HP48.BAK' to the stack. You should see "Backup HOMEDIR" on level one of the stack. Execute RESTORE (the user-rpl command). 5. Go into the BKUP directory and put 'HP48.BAK' on the stack. Note: this is the name 'HP48.BAK' on the stack, NOT the contents of 'HP48.BAK'. Put your computer is Kermit server mode or double check that XYSRVR is ready. 6. Execute the RESTO program. 7. You are finished. If you selected to have the stack saved, after a Warmstart, press the STK softkey and your stack will be restored. 8. If you wish to remove libraries or objects from your com- puter, and these objects were from port "p", simply deleted all files with a suffix of "p". 9 Streamlining BKUP If you have only a small amount of memory and or don't wish to use all the features built into BKUP then do the following: 1. Select the port(s) you wish to backup. If you wish you use the default filename of "HP48.BAK", then leave "Use default filename" set to "Yes". If you wish to input a name everytime you back up your HP48, then set this variable to "No". 11 2. Now, PURGE the following list: { CNFG FLNM } This is the absolute smallest (about 1800 bytes) you can make BKUP, if you delete anything else the program will not work properly (if at all). 10 Trouble Shooting Sometimes there are problems using BKUP. This is my attempt to help with these problems. If you have any problems that are not mentioned here, please contact me and describe the problem as completely as possible. The first thing I would like to emphasize is that the software your computer uses is important. This software must be Kermit in server mode, or the XYSRVR program. If you do not wish to use these programs, then you will not be able to use BKUP. If you have a favorite program that has a kermit server mode, you may be able to use it, you will have to experiment to see if you can get it to work. 10.1 Trouble with Kermit If you have trouble using kermit, there are several things you should double check. 1. Make sure that the baud, parity, and transfer type of your HP48 match the corresponing settings on Kermit. 2. Make sure that the communication port your HP48 is con- nected to is the communication port that Kermit is using. 3. Make sure Kermit is in server mode (do this by typing "server"). 4. You may wish to type "set xflow none" in kermit. This turns off flow control in kermit. 10.2 Trouble with XYSRVR If you have trouble using XYSRVR, please read the documen- tation that is supplied with the program. If you still have trouble, 12 you may wish to double check these items: 1. Make sure the communication port is the communication port that your HP48 is connecten. Also, make sure the parity, protocol, and baud rate of XYSRVR and your HP48 match. 2. Once, I had trouble using XYSRVR. When BKUP would transmit to tell the program what to do, a garbled string would appear on the screen. The way I solved this problem was to use a XYSRVR.CFG file. You may wish to try this as well. Read the documentation of XYSRVR for more details. This is the file I use for my XYSRVR.CFG: COM 1 METHOD X BAUD 9600 LENGTH 8 STOP 1 PARITY NONE 3. I often have a problem with XYSRVR receiving the strings that BKUP transmits. What I usually have to do is quickly press the spacebar, then the rest of the string will show up on the screen. I do not know any other way to work around this problem. 4. Make sure that the software flow control of your HP48 is turned on. Do this by making the third and fourth numbers in IOPAR ones. 11 Bugs There are two bugs that I am aware of and I will do my best to describe them in the following sections. 11.1 HP48GX Covered Port Bugs If a user has a RAM card in ports 2 or higher, and the largest object in this port is greater than the amount of free memory, 13 you will get an insufficient memory error and BKUP will halt in execution. You have a few options. First, you can skip this port and not back it up at all. Another option is to back up everything this else, clear your main memory, then back up the port. I am going to try to learn how to correct this problem, however my machine language isn't this sophisticated yet. A future verion of BKUP will hopefully correct this situation. 11.2 HP48S(X) Bugs I tested the program on an HP48S, but I found that it was difficult to get a consistant transfer. The program would work, but it seemed that there were communication conflicts with XYSRVR and XY-Modem 2.2. 12 Thanks Jason Olson (antioch@mit.edu) for help with testing. Bernd Hendel (BHENDEL@vmprofs.estec.esa.nl) for all his testing, suggested improvements, and time. Keith Maddock (madd0118@nova.gmi.edu) for bringing some bugs to my attention, suggesting some improvements, and testing. Randy Ding (randyd@alpha2.csd.uwm.edu) for his tireless system-rpl help. Ken Tobias (ktobias@amgen.com) for testing. Jim Daniels (diamond@eskimo.com) for XYSRVR. The authors of X-Ymodem 2.2. Cary McCallister (sysop@hpcvbbs.external.hp.com) for FXRECV. Detlef Mueller (detlef@dmhh.hanse.de) for STOFIX (Li- brary 1222). Mika Heiskanen (mheiskan@alpha.hut.fi) for JAZZ and for ML help. 14 Andre Schoorl (aschoorl@engr.uvic.ca) for pointing out that BKUP doesn't work so well when the HP48 is not in STD mode. Dick Metzler (dmetzler@math.unm.edu) for a whole lot of testing using his HP48GX and ports 0 through 4. Yoneda Kiyoshi (yoneda@ssel.toshiba.co.jp) for bringing a bug to my attention and for helping me resolve the software flow control problem in kermit. 12.1 Description of BKPAR If you decide that you do not want to use the CNFG program to configure BKUP, then you may wish to read this section. This section describes the valid objects that can be within the BKPAR variable. BKPAR is a list that contains seven objects. The first object is a list that contains the ports that the user would like to back up. These ports must be real, non-negative integers. This list may be as long as you like and you may also put the same port (e.g. port 0) as many times as you wish, although I don't know why you would. Items two through five are non-negative, integers. These corre- spond to "Save Stack & Last Argument", "Use Default Filename", "Save Flags", and "Archive HOME". In each case, a value of zero indicates that you do not wish to use the feature while a nonzero (positive) integer indicates that you do want to use the feature. The sixth item in BKPAR indicates the protocol you wish to use. A value is 0 indicates Kermit, a value of 1 indicates HP48G Xmodem, a value of 2 indicates HP48G Xmodem and the FXRECV program, and a value of 3 indicates you wish to use the X-YModem 2.2 library. The last item is a string that indicates when the last backup was made. If you decide to replace this string with something else, make sure it is a string and that it is no longer than 22 characters. 15 13 Revision History 13.1 Improvements in Version 4.6 The first changes to version 4.6 were made in August of 1995. 1. Jeff McClure (jhmcclu1@au1vm.ua.edu) was having prob- lems making back ups. I traced it to a bug within the ARCD routine. When the list in ARCD was null, BKUP screwed up things. 2. Yoneda Kiyoshi (yoneda@ssel.toshiba.co.jp) was having problems using kermit. Turns out that I DROPped the name of the back up object to be sent. 13.2 Improvements in Version 4.5 Version 4.5 was released for testing in May and June of 1995. After learning some machine language, I could program in system rpl much better. I rewrote the program to be more efficient. 1. I figured out how to make local variables that can be named the same name as the port object being sent. This enabled me to use the Ymodem features of X-YModem 2.2. Previously, I could not control the name that Ymodem would transmit. 2. I added the ARCD variable so that users can back up objects one time, but still be able to restore them every time the HOMEDIR is restored. 3. Eliminated the TG2NM program that converted tagged ob- jects into global variables. New routines do this inside of the BKUP and RESTO program. 4. I don't use PVARS any more. PVARS is slow and and there are better system rpl commands that can be used instead. 5. I added a routine that checks the battery before an object is sent. My battery was low one time and I got a strange error because of the low battery condition. 6. The CNFG program was changed. It now contains my e- mail address, the version, and the release date information. 16 7. Changed BKPAR so that the user can specify the ports that should be backed up. The old style was to specify the start port and the end port. 8. Changed the routine that saves the stack and last argument. The old routine would clear the stack if the user did not want to save it. 9. The STOFIX library is only required for the RESTO part of the program. In previous versions, it was needed to recall objects from ports greater than port 1. 10. Made the CNFG always leave a copy of BKPAR on the stack, until the user exits the program. This made CNFG smaller and faster. 11. Found out that previous versions of BKUP didn't work un- less the HP48 was in STD mode. It turns out that this version works fine except for a problem in the FLNM program that was fixed. 13.3 Improvements in Version 4.2 1. When there was an error sending the HOMEDIR, it would not be re-rooted. So, the program would exit leaving the HOMEDIR unattached and the next keypress would wipe out everything. This was fixed by adding a forgotten "::" and ";" after an ERRSET. 13.4 Improvements in Version 4.1 1. Fixed the BKUP program so that it will check to see is a port is present, if it is present it checks to see if it is merged. 2. Trimmed the CNFG program to reduce some overhead. 3. Changed from Library 555 to 1275 for xmodem protocol. 13.5 Improvements in Version 4.02 1. Fixed a bug in the RESTO program that would not allow the calculator to warmstart after libraries were loaded onto the 17 HP48. The problem occurred because the user flags were saved after user flag 1 was turned on, causing user flag 1 to be turned off not allowing the warmstart. 2. Made the BKUP program look for Library 1222 and, if it was in port 0, execute the pinit command before recalling any libraries from any port (for Rev M bugs). 13.6 Improvements in Version 4.01 1. Changed BKUP program so that it would not abort when PVARS was executed on a merged memory card. 2. Fixed a bug in CNFG program that would cause the clock to come on after the beginning and end port were changed. 13.7 Improvements in Version 4.0 1. Complete translation from user-rpl to system-rpl. This has made the program more compact and fast. 2. Made the program look for STOFIX, I finally realized that not everyone is going to own a rev. R HP48GX. 3. The program can now send libraries without having to store them in a global variable. This eliminated the need to have enough memory to move the largest library into a global variable. 4. The ports to be backed up are entirely determined by the user. These are specified in BKPAR. 5. Add multi-protocol capability; kermit gets to be very slow when you have a lot of memory to backup. 6. Abandoned the "ATLIB" program and associated programs. 13.8 Improvements in Version 3.01 1. Removed an EVAL command that would execute programs when trying to put them back in the correct port. 18 13.9 Improvements in Version 3.0 1. Added BKPAR to allow user to set program features. 2. Added a user interface to allow user to select BKUP features. 3. This interface is similar to the ones built into the HP48 series. 4. Made the library attaching program so it will work anytime a warmstart occurs. 5. Rewrote code so that libraries in any other port than 0 are sent to the IO port to be backed up. 6. Added capability to back up backup objects. If these backup objects have a name greater than 8 characters, only the first 8 characters are sent to the IO port. 7. Feature to check to see if there will be enough memory to make a backup. 8. Added capability to backup stack and LASTARG. 13.10 Improvements in Version 2.0 1. The program no longer assumes that if port 1 is unavailable that port 2 will also be unavailable. However, it assumes that if port 3 is unavailable, any ports after it will be unavailable. 2. It distinguishes between merged RAM, independent RAM, and ROM. 3. After detaching all libraries, it reorganizes the current di- rectory. This is handy when you actually have to use the backed up file: you don't have to search around the directory to execute RESTO. 4. It checks the objects returned by PVARS to make sure they are libraries before it tries to store them in the current direc- tory. 19 5. There is now a feature to attach libraries to a user specified directory. This is useful for those libraries that automati- cally attach themselves to HOME and for libraries that don't automatically reattach after a warmstart. 6. When the program is finished, it makes four tones to notify the user that the backup process is finished. 7. LASTARG is disabled eliminating a DROP error in the IFEER loop. 8. The method of storing the libraries was improved so now a list of the variables that the libraries was stored in is no longer needed. 9. If there are no libraries on your HP48, a backup can still be made successfully. 10. Because of improvements 1, 3, 4, and 5 the execution time is longer and the code is longer as well. 20