BKUP Version 3.0 by Bob Apodaca (bapodaca@mit.edu)     Release Date: 03/94

Size:  3343.5 bytes  Checksum: # 2B3Fh

This program can be distributed freely provided that the original 
instructions remain intact and unaltered.

This program is written entirely in user-rpl and is intended to make a backup 
of any port that the user specifies.   This program contains some SYSEVALS,
however they are all supported.  There are options to save the stack  
and LASTARG, supplying a default name for the backup file, backing up flags,
and checking to see if there is enough memory to make a backup.  These
options are selectable by a menu system similar to IOPAR.  A utility
is also included that will attach libraries to any directory specified by
the user every time a warmstart is done.  It has been tested on an HP48GX 
rev M and a HP48SX rev J with a 32K MERGEd RAM card.  It is believed to 
fulfill its task, but the author does not assume any responsibility for 
*anything*.

Requirements:

	This program has the following memory requirements:

	N = number of objects in specified port to be backed up 
	L = largest object in specified port
	S = size of all stack objects plus LASTARG (S can be 0)

	Req_Mem = 1184 + (15 + 11.5) * N + L + 6.5 + S

	If your machine cannot meet this requirement you will be told by
	the program or you will see "STO error: insufficient memory".

Features:

	1. Compatible with all versions of the HP48 series.
	2. Only backs up the port specified by the user.
	3. Can be executed from any subdirectory, it is not confined to HOME.
	4. 3431 bytes as is, but can be trimmed to down to 1224.5 bytes.
	5. Can attach libraries that are do not auto-attach and it can make 
	   those libraries that auto-attach to HOME be attached to any 
	   directory specified by the user.  This process can be done 
	   automatically after *every* warmstart.
	6. Sends libraries that are not in port 0 to output, if these 
	   libraries have names greater than 8 characters, only the first 8 
	   characters of the name are sent.
	7. Can also backup the entire stack and LASTARG so they can also be
	   restored when your HP is restored.
	8. Simple-to-use user interface.

Revision History: 
  
  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 
	   directory.  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 directory.
	5. There is now a feature to attach libraries to a user specified
	   directory.  This is useful for those libraries that automatically
	   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 enliminating 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.

  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.  
	   This interface is similiar to the ones built into the HP48 series.
	3. Made the library attaching program to it will work anytime a 
	   warmstart occurs.
	4. Rewrote code so that libraries in any other port than 0 are sent
	   to the IO port to be backed up.  
	5. Added capibility 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.
	6. Feature to check to see if there will be enough memory to make 
	   a backup.
	7. Added capibility to backup stack and LASTARG.  

Future Versions:

	As soon as I have enough time, I plan to translate this program to
	system RPL.  I'm hoping that this will reduce the size of the program
	and the execution time.  If you have any comments at all, please
	send me e-mail at: bapodaca@mit.edu   I would really like to know 
	how many people use my program and what they think about it.

Installation: 

	1. Download the BKUP directory to your HP48.
	2. Go into the BKUP directory.  There should be thirteen programs in 
	   the following order:
	   
	   |BKUP | |RESTO| |CNFG| |ATLIB| |ARLIB| |INFO |

	   |BKPA | |LIBDS| |FLNM| |TG->N| |MEM? | |AUTOE|

	   |AUTOP| |     | |    | |     | |     | |     |

	3. If you would like to use the auto-attaching libraries feature,
	   then recall 'AUTOPORT' to the stack, PURGE the 'AUTOPORT'  
	   variable, then press 0 STO.  Recall the variable 'AUTOEXEC' and
	   edit it.  It should look like this:
	   
	   \<< { HOME UTIL BKUP3 
	   ATLIB } EVAL 
	     IFERR 'STK' RCL
	     THEN DROP
	     ELSE OBJ\-> DROP
	     'STK' PURGE
	     END HOME \>>

	   This tells library 1531 to go to HOME, then into the UTIL 
	   directory, then into the BKUP3 directory, to execute ATLIB, and
	   then to restore the stack and LASTARG if they exist.  You should 
	   edit this program and change the { HOME UTIL BKUP3 ATLIB } list
	   so it will work on your HP48.  Be sure to leave ATLIB as the last 
	   file in the curly braces and HOME as the first.  Once you have 
	   finished editing this program put it on the stack and put a  
	   tagged object on level one in the following form:

	   P:AUTOEXEC

	   Where P is any port that you choose.  For example, on my HP I use
	   0:AUTOEXEC .  After this is in level one and the program is in 
	   level two, press STO.
	    
	   Use ARLIB to add the library numbers and directories where you
	   would like libraries to be attached at every warmstart (more 
	   instructions on using ARLIB follow).

	   If you do not wish to use this feature then PURGE the following
	   files: 'ATLIB', 'ARLIB', 'AUTOEXEC', 'LIBDST', and 'AUTOPORT'.

	   You are finished installing BKUP.

Using CNFG:

	   Press the softkey associated with CNFG.  You should see the 
	   current settings.  The following are the default settings:

	   Back Up Port:                    0
	   Save Stk & Lastarg:              Yes
	   Include DATE.BAK:                Yes
	   Backup Flags:                    Yes
	   Mem Available Chk:             _ Yes 
	   |PORT||WMST||DATE||FLAG||MAC?||IOPAR|

	   To change the port you wish to backup, put that port number on
	   the stack and press PORT.  To change the other options, simply
	   press the corresponding softkey.  If you wish to check or set
	   IOPAR press the IOPAR softkey.

	   NOTE: Backup Flags is only used when backing up port 0.

Using ARLIB:
	   
	   To execute ARLIB, simply press the softkey associated with ARLIB.
	   You should see the following softkeys:

	   |ADLIB||RMLIB||EXIT ||     ||     ||     |    
	   
	   ADLIB: ADd LIBrary - use this utility to add a library and 
				directory to the list of those libraries to
				be attached when a warmstart is done.

	   RMLIB: ReMove LIBrary - take a library and the corresponding 
				   directory off the the list of those to be
				   attached.

	   EXIT: exit - Exits ARLIB 

Using ATLIB:

	   To attach the libraries you have specified by using ARLIB, 
	   simply press the softkey associated with ATLIB.

Making a backup:  

	1. Use CNFG to set the options that you wish BKUP to use.  You can
	   also set IOPAR using CNFG.  If you are backing up any port other
	   than 0, put your computer in server mode.
	
	2. If you have anything on the stack that you wish to save, store it 
	   in a variable so you can recall it later.

	3. Execute BKUP.

	4. After a bit, you will be prompted for a filename.  If you are 
	   backing up port 0, put your computer in recieve mode. If you are
	   backup up something other than port 0, go to the next step.

	5. Enter a filename and press enter.

	6. Your HP will be uploading.  When it is finished it will store all 
	   libraries.    
	
Restoring a backed up file:        

	1. Make sure IOPAR is set correctly.

	2. Download the backed up file (let's call it P?DATE.BAK) to your HP.
	   If this is a backup of a port other than 0, it will just be a list
	   of the files that were backed up.  

	3. If you backed up port 0, recall 'P?DATE.BAK' to the stack.  You 
	   should see "Backup HOMEDIR"  on level one of the stack.  Execute
	   RESTORE (the user-rpl command).  

	   If you backed up a port other than 0, make sure 'P?DATE.BAK' is
	   in the BKUP directory.  
	
	4. Put 'P?DATE.BAK' on the stack.  Note: this is the name  
	   'P?DATE.BAK' on the stack, NOT the contents of 'P?DATE.BAK'.

	   If you backed up a port other than 0, put your computer in
	   server mode.  
	
	5. Execute the RESTO (the BKUP program).
	
	6. You are finished.  After your HP warmstarts the stack will be 
	   restored and your LASTARGs will be on level one (and possibly
	   level two).

	Note: If you backed up port 0, 1, and 2, you may restore them all at
	      the same time.  Just combine the list of library names and 
	      object names and place them in a single variable.  Be sure to
	      put your computer in server mode if you are restoring a port
	      other than 0.  RESTO will do everything else for you.
			
	      If you wish to get rid of libraries or objects affiliated with
	      a port, simply go to your dos prompt and type:

	      > del *.p

	      Where p is the port number of the backed up objects.  This will
	      make cleaning up your hard drive a snap.

Streamlining BKUP:        

	  If you have only a small amount of memory and or don't wish to use
	  all the feature built in to BKUP then do the following:

	  Execute CNFG to configure BKUP.  Set all options to "No".  Select
	  the port you wish to backup.  After you have completed the 
	  following instructions, and you wish to change the port to be 
	  backed up, it is just the first number in the 'BKPAR' variable.

	  Now, PURGE the following list:
	  
	  { CNFG ATLIB ARLIB INFO LIBDST FLNM MEM? }

	  If you haven't already done it, also purge the following:

	  { AUTOEXEC AUTOPORT }

	  This is the absolute smallest you can make BKUP, if you delete 
	  anything else the program will begin to give you errors.

Thanks to:

	Joe Horn for making his AUTOPORT program.
	Jason Olson (antioch@mit.edu) for his testing.
	Bernd Hendel (BHENDEL@vmprofs.estec.esa.nl) for all his testing, 
	     suggested improvements, and time.


Description of Programs:

Softkey Name    Variable Name   Description           
------------    -------------   -----------
BKUP            BKUP            BacKUP - the main program that backs up any 
					 port that the user desires.

RESTO           RESTO           RESTOre - restores the HP48 to it's original
					  state.

CNFG            CNFG            CoNFiGure - Lets the user select the options
					    that he/she would like BKUP to 
					    use.

ATLIB           ATLIB           ATtach LIBraries - attaches the libraries in
						   LIBDST to the directories
						   specified by the user.

ARLIB           ARLIB           Add/Remove LIBrary - lets the user remove            
						     a library from LIBDST.

INFO            INFO            INFOrmation - my name, BKUP release date,
					      Version number, and my e-mail
					      address.

BKPA            BKPAR           BacKup PARameters - the file that BKUP uses
						    to know whether or not
						    to execute certain 
						    features.

LIBDS           LIBDST          LIBrary DeSTination - the file that tells 
						      ATLIB where to attach
						      what libraries.

FLNM            FLNM            FiLeNaMe - Checks the date then spits out 
					   P?MMMDD.BAK, where MMM is a three                                                
					   letter abbreviation of the month,
					   DD is the date, and ? is the port
					   that is being backed up.

TG->N           TG->NM          TaGged to NaMe - takes a tagged object on
						 level 1 and outputs a name
						 in the form of: L#.?
						 where # is the library
						 number or backup object name
						 and ? is the port number the
						 object is stored in.

MEM?            MEM?            MeMory? - Returns 1 if there is enough memory
					  to run BKUP and 0 is there is not.
					  Also takes into account the fact 
					  that you may have objects on the
					  stack.

AUTOE           AUTOEXEC        AUTOEXECute - A file that belongs in HOME and
					      tells Library 1531 where to 
					      look for ATLIB.  Also puts the
					      stack and LASTARG 

AUTOP           AUTOPORT        AUTOPORT - Library 1531 by Joe Horn taken 
					   from the Utilities directory of 
					   Goodies Disc #7.
					   It looks for the file P:AUTOEXEC
					   at warmstart of executes it.
