-- SystemTools.doc
-- last edited by
--   JFung.pasa	   	  13-Sep-84 14:38:08

Filed: 	[Rose]<Lisp>Harmony>Installation>SystemTools.doc


The Lisp SystemTools is a tailored software particularly to meet the installtion of Xerox'x Interlisp-D software on Xerox's Dandelion (1108) machines.  It is an integrated package of three softwares, a) the Online-Diagnostics tool, b) the Profile Tool and c) the Lisp Installation Tool.  

This document describes the Profile tool and the Lisp SystemTools in detail.  The Online-Diagnostics tool came from Versatec and will not be discussed here.


TABLE OF CONTENTS:

1.	INSTALLATION FROM FLOPPIES
	1.1	PARTITION YOUR DISK FROM FLOPPY
	1.2	SET UP YOUR DIAGNOSTICS VOLUME
		1.2.1	INSTALL BOOT FILES AND 'LISP INSTALLATION TOOL' FROM FLOPPY
	1.3	ACTIVATING INDIVIDUAL TOOLS FROM BASE STATE
	1.4	TOOL WINDOWS AND PARAMETER ITEM TYPES
	1.5	THE PROFILE TOOL
		1.5.1	PROFILE TOOL WINDOW
		1.5.2	PROFILE TOOL COMMANDS AND PARAMETERS
	1.6	THE LISP INSTALLATION TOOL
		1.6.1	LISP INSTALLATION TOOL WINDOW
		1.6.2	TOOL COMMANDS AND PARAMETERS
	
2.	LOADING INTERLISP-D SOFTWARE
	2.1	LOADING INTERLISP-D SOFTWARE FROM FLOPPIES
	2.2	LOADING INTERLISP-D SOFTWARE FROM A FILE-SERVER

3.	INSTALLATION FROM ETHERNET FOR XEROX INTERNAL USERSS
	3.1	PARTITION YOUR DISK FROM ETHERNET
	3.2	INSTALL BOOT FILES AND LOADING 'LISP INSTALLATION TOOL' FROM ETHERNET
	3.3	HOW TO SET UP YOUR USER.CM (PROFILE) FILE
	3.4	ACTIVATING TAJO VOLUME FROM BASE STATE
	
		


1.1	PARTITION YOUR DISK FROM FLOPPY

	The 1108 comes with three different disk configurations: the 10 Megabyte SA1000, the 29 Megabyte SA4000, and the 42 Megabyte Q2000.  You have to partition your disk into logical volumes to accomodate lisp softwares.   To carry out the installation procedures from floppies, you need the following floppies as is distributed as part of the 1108 Software kit:
	
	1.	Insatallation Utility floppy
	2.	System Files floppy
	3.	A set (3 to 6) Lisp Sysout floppies
	
	In addition to these, there are the Lisp Library and User floppies.
	
	To partition your disk follow the follwoing steps:
	
	1.	Load the 'Installation Utility' floppy in the floppy drive and do a 2-boot.  
	(Note: A 2-boot is done by pressing both the B RESET and ALT B buttons on the front panel and releasing the B RESET button immediately.  Release the ALT B button when the front panel reads 0002.)  After about two minutes a menu with list of utility options will be displayed.
	   
	2.	When the menu appears, select item which suits your best for partitioning your disk.
	
	3.	You will be warned that partition will destroy the contents of your disk, reply 'Yes' to continue.
	
	4.	When the menu reappears, you may proceed to next section on setting up your Diagnostic volume.
	



1.2	SET UP YOUR DIAGNOSTICS VOLUME

	It is necessary to set up your 'SystemTools' volume prior to install any Interlisp software.  The SystemTools volume supplies the following functions:
	
	a.	It acts as the Physical volume in your disk, and contains the system microcode and boot loader files.  When you 'logout' from your Interlisp the system you are switched back to this volume.
	
	b.	The online-diagnostics software for trouble shooting your dandelion.  The online-diagnostics tool allows one to diagnose your keyboard, mouse, display, floppy drive as well as echo to other hosts on the Ethernet.
	
	c.	The Profile tool which allows you to set up user specific information
	
	d.	The Lisp SystemTools for easy installation of your Interlisp software.
	
	The online-diagnostics tool, Profile tool are all bound together into the Lisp SystemTools. 
	
		
	1.2	INSTALL BOOT FILES AND 'LISP INSTALLATION TOOL' FROM FLOPPY

	1.  Load the 'Installation Utility' in the floppy drive and do a 2-boot.  
	
	2.  When the menu appears, select item labeled as 'Initialize SystemTools'.

	3.  Unload the floppy drive and load the 'System File' floppy.

	4.  Respond to the prompt on the display with 'Y'.

	5.  When the menu reappears, select item labeled as 'Boot SystemTools'.

	6.  In about 2 minutes, you will see the SystemTools volume name appear in the top line on your screen.  Activate the Exec window in the 
lowerleft hand corner by moving your mouse on top of the letter 'cu' of excCUtive and click the right button.  The screen will be configured to accept typein.  Press any mouse button to activate the input cursor.  

	7.  Unload the floppy drive and insert the 'Installation Utility' floppy.

	8.  Type in  'Floppy Read SystemTools.bcd'.  You should be able to hear the floppy drive, as the file SystemTools.bcd is transferred from the floppy disk to the rigid disk.  

	9.  Type SystemTools <CR> at your exec window.

	10. After about couple minutes you will see the screen turn black and a white box bouncing around.  This is here now refered to as the 'base state' of your machine.


	1.3	ACTIVATING INDIVIDUAL TOOLS FROM BASE STATE

	By now, if you don't have the bouncing box, then you need to revisit previous section to make sure you follow each steps correctly, you may repeat previous steps if necessary.  Contact your support person, for help if you still can not get to this base state.  ARPA net users may send mail to 1100Support.pasa@Xerox.arpa requiring for help.

	The Interlisp bouncing box is the primary keyborad interface to your various Lisp systems tools and may be viewed as the top-level user interface on your 1108. It is bounicng so to avoid the burn out of the phosphorous on your CRT.  It has the current Day-Time-TimeZone displayed at the top few line.  It also show what keys or mouse-buttons are defined to active the tool.  For example, the Left-button on the mouse may activate the Lisp SystemTools, and the 'STOP' key on your keyboard my activate your 'LISP' volume.   

	Users unfamiliar with mouse and window operations should first activate the Online-Diagnositcs tool and read its Help function.  The Online-Diagnositcs Help messagespresent detailed instructions for their usages.
	
	
	1.4	TOOL WINDOW AND PARAMETER ITEM TYPES
	
	Both the Profile tool and Lisp SystemTools are window based and are composed of five regions,  the 1) Herald name, 2) Message Subwindow, 3) Parameter Subwindow, 4) Command Subwindow and 5) File Subwindow.

	The Herald name appears at the top line and merely indicates the tool's name and creation date.  A 5-line message subwindow is used to post error messages.  The Command and Parameter subwindow is used to invoke comands and provide parameters.  The File subwindow is ued to post the event messages relevant to that command.


	The command and parameter items together provides the interaction to the tool to carry out the specified tasks.   Certain parameters are relevant to certain commands.   

	Three types of parameter items are used in the tool, they are a) Enumerated items, b) String items and 3) Numeric items.  The Enumerated items are lists of string items and choosing an item is done via menu prompts.  Hidden menu is prompted by pressing the middle button over the keyword.  Choosing one of the values from the menu sets the enumerated item to that value.  The String items are strings filled in by the user, Numeric items are like string items, except that only strings representing the numbers are permitted.  A flushing screen will indicate invalid type in if occurs.
	  


1.5	THE PROFILE-TOOL

	The Profile Tool enables the user to preset a number of parameters to be used by Lisp SystemTools.  Theses settings will appear in the Lisp SystemTools window everytime when LIT is activated unless changed otherwise.  
	
		
	1.5.1	TOOL WINDOW
	
	The following command items exist in the Command subwindow:
	
	Set Profile!		Quit!
	
	The following parameter items exist in the Parameter subwindow, for illustration purpose some sample values are used.
	       
	User: JFung.pasa		Password: ******		 
	Domain:	XSIS			Organization: XEROX	Device: FS
	NSLisp: [Stash:]<LispCourse>LispCourse.sysout
	PUPLisp: [Rose]<Lisp>Carol>Lisp.sysout
	FloppyLisp: Demo.sysout
	
	
	
	1.5.2	TOOL COMMANDS AND PARAMETERS
	
	The following are the parameter items:

	User:		A String item which is your PUP/NS registered user name.
	
	Password: 	A String item which is your associated password for login.  You do not have to supply this here, and you may type it into the LIT's window.
	
	Domain:		A String item which is your domain name as defined in your Clearinghouse database, and is necessary for NS service.
	
	Organization:	A String item which is your organization name as defined in your Clearinghouse server, and is necessary for NS service.
	
	FileServer:	An enumerated item which specifies the default file server to be selected, i.e IFS, FS or FLOPPY.
	
	NSLisp: 	A String item which specifies the complete file pathname from your product file server.
	
	PupLisp:	A String item which specifies the complete file pathname from your interim file server.
	
	FloppyLisp:	A String item which specifies The file name on the floppy disks where lisp sysout is to be loaded. 	
	 
	 
	 
	The following are the command items:

	Set Profile!	Set Profile will create or overwrite your user profile file on your disk. Note:  Internal users should avoid using this tool and instead should refer section 3.4 on how to set up these entries.
	
	Quit!:		Quit will deactivate the tool and return you to the 'Base State'.



1.6	THE LISP SYSTEM-TOOLS

	The Lisp SystemTools integrates several system functions to allow the easy installation of Interlisp softwares on your 1108.  
	
	It supports the following features:
	
	a.	File retrieval capability from both IFS and FS servers implementing PUP and NS protocols appropriately and turn it into a bootable file.
	b.	Boot capability to boot the microcode and boot loader that was intalled on your volume. 
	c.	Erase capability to erase the contens of a logical volume.
	d.	Scavenge capability to diagnose the validity of a logical volume.
	e.	Set VMem capability to set the Interlisp's virtual memory backing store.
	f.	Copy Virtual memory capability from one logical volume to another.
	g.	Some floppy features.
	

	1.6.1	LISP SYSTEM-TOOLS WINDOW
	
	The following command items exist in the Command subwindow:

	Install File!	Boot!		Erase!   	Set VMem!	Make Script!  Help!
	Remote List!	Copy VMem!	Scavenge!	Floppy!		Quit!
	
	
	The following parameter items exist in the Parameter subwindow, for illustration purpose some sample values are used.
	       
	Document: {General, ErrorMsg}	Device: {IFS, FS, FLOPPY}	VMem Size = nnnnn
	File: [Host]<Directory>SubDirectory>fileName.sysout
	Volume Menu: Lisp		Volume Size = nnnnn		Free Size = nnnn
	User: JFung.pasa		Password: ******		 
	Domain:	XSIS			Organization: XEROX

	
	
	1.6.2	LISP SYSTEM-TOOLS COMMANDS AND PARAMETERS
	
	The following are the parameter items:
	
	Document:	An enumerated item and is used in conjunction with the Help! command.  It is used to select which online document is to be displayed in the file subwindow for a quick reference.  'General' displays the overall features of the tool, while the 'ErrorMsg' displays the semantics of the error messages in the tool.

	Device:		Another enumerated item which gives the user the selection of the type of device where the lisp sysout file is located.  Currently, two types of file servers, the interim file server(IFS) and the product file server(FS) are supported.  An additional Floppy device on your Dandelion is planned for reading sysout floppies into the lisp volume.

	File:		A string item, specifies the pathname of the file to be installed.  The syntax of the complete pathname depends on the particular file system on your host machine.
	
	For example, on a Xerox's IFS the pathname looks like [Host]<Directory>SubDirectory>FileName.ext!version.  
	A typical example would be [Rosebowl]<Lisp>Fugue>Lisp.sysout.

	On a Xerox's product file server the pathname looks like [Host:Domain:Organization]<Directory>FileName.ext!version.  
	A typical example would be [Phylex:XSIS North:Xerox]<Demo>Demo.sysout
	An equivalent but shorter way would be [Phylex:]<Demos>Demo.sysout

	On a Unix file server the pathname looks like [host]</directory/subdirectory/>filename.ext  
	A typical example would be [safe]</a/lisp/fugue4/>lisp.sysout
	
	On a VAX-VMS file server the pathname looks like [Host]<Directory.SubDirectory>FileName.ext;version.  
	A typical example would be [Taos]<DEIProd.Prior]Lisp.sys

	On a DEC-2060 TOPS-20 file server, the pathname looks like [Host]<Directory.SubDirectory>FileName.Sys.version.  
	A typical example would be [Sumex-2060]<Dolphin.Fugue6.BetaTest>Lisp.sysout.


  	Volume Menu:	An enumerated item which only gets popped by chording your mouse button(presing both buttons on a 2-button mouse or middle button on a 3-button mouse).  This menu contains the exact volume names as configured in your machine.  If 'Lisp' volume is present in your machine, it gets selected as the default volume, else nothing is selected.  To choose one of the values from your menu, simply move your mouse to the item desired and lift the button.  NOTE: DSK will not appear in the Volume Menu once Interlisp local directory is set.

	VMem Size:	A numeric item which dynamically shows the size of virtual memory backing store in pages(1 page=512 bytes).  This parameter is only meaningful to a lisp-type volume, non-lisp volumes or an empty lisp volume will show zero pages.
	
	
	Volume Size:	A numeric item which dynamically shows the volume size in pages.
		
	Free Size:  	A numeric item which dynamically shows the available pages in the volume.

	User:		A String item which is your PUP/NS registered user name.
	
	Password:	A String item which is your associated password for login.
	
	Domain:		A String item which is your domain name as defined in your Clearinghouse database, and is necessary for NS service.
	
	Organization:	A String item which is your organization name as defined in your Clearinghouse server, and is necessary for NS service.



	The following are the command items:

	Install File!:  Install file will fetch and load the file specified in the file parameter into the volume selected.  This command is to be used in conjunction with the device parameter in selecting the type of device where the file is located.  A confirming mouse 'icon' will appear in the file sub-window with the name of the volume to which the file will be installed.
	
	During processing, two positive indications are provided.  First, your command subwindow will be redisplayed by some twiddler graphic symbol, here a star-symbol is used.  Secondly, the message subwindow will display the number of bytes which have been transferred to your disk.  This gives you an idea of how much longer the transfer will take.  Usually for a 3 mega bytes file in a local net, it takes in the neighborhood of 2-3 minutes.  This command is abortable by depressing the STOP key (the red key located on the right hand corner).

	Boot!: 	Boot command is used to boot the volume selected. 

     	Erase!:  Erase command is used to erase the contents of the logical volume specified by the Volume parameter. 
	 
     	Set VMem!: Set VMem command is used to vary the size of the Interlisp's vitual memory backing store.  This command is driven by the size specified on the VMem Size parameter.  A warning message will be posed if you are trying to 'shrink' your virtual memory backing store.  If no size is specified on an empty volume, the maximum VMem Size will be approximated.

     	Make Script!: Make Script gives user the tool to name their own volume names and sizes and then re-partition his/her disk accordingly.  This command adds the user's definiton together with standard system supplied options into the script file which is located in your Installation Utility floppy.  This command pops a new window with the following parameters:

	DiskType: {10Mb, 29Mb, 42Mb}	DriveSize: nnnnn	Free Pages: nnnn
	Volume1 Name: Diagnostics		Volume1 Size: 3500
	Volume2 Name: 				Volume2 Size: 0
	Volume3 Name: 				Volume3 Size: 0
	Volume4 Name: 				Volume4 Size: 0
	Volume5 Name: 				Volume5 Size: 0
	Volume6 Name: 				Volume6 Size: 0
	Volume7 Name: 				Volume7 Size: 0
	Volume8 Name: 				Volume8 Size: 0
	Volume9 Name: 				Volume9 Size: 0
	Volume10 Name: 				Volume10 Size: 0
	
	Make Script!				Quit!

Selecting the DiskType will yield the total disk drive size in pages and the free pages count less the Volume1 size.  Volume1 has been predefined for you.  When editing the Volume Name field, it will dynamically updates the 'Free Pages' field, this lets you know your current free pages count.  When you are all done with the specification, then click the 'Make Script' command, which will prompt you for a confirmation and ask for Installation Utility floppy.  At the end of the floppy operation, do a 2-boot on your floppy you should see your definition appears as the first item in the menu.


	Parameter items for 'Make Script!':
		
		DiskType: An enumerated item indicates the type of disk to be used.  Selecting the DiskType will yield the total disk drive size in the DriveSize parameter.	
		DriveSize: A numeric item which shows the total disk pages available on the disk selected.
			
		Free Pages: A numeric item which dynamically displays the free pages left after each logical volume name being edited.
		
		Volume1 Name: A string item which is read-only and has the value 'Diagnostics' assigned to it.	
			
		Volume1 Size: A numeric item which is read-only and has the value 3500 assigned to it.
		
		Volume2 Name - Volume10 Name:  A string item and shows the name of the volume to be configured.  When this Name field is edited, the 'Free Pages' field will be dynamically updated.
		
		Volume2 Size - Volume10 Size:  A numeric item and shows the disk size in pages corresponding to that volume name.
		
	Command items for 'Make Script!':

		Make Script!;	Starts the operation.  It will prompt for confirmatation and ask for 'Installation Utitlity' floopy to be inserted into the floppy drive.  When confirmed will first delete the file from floppy and writes this new file back in.  When this is done, doing a 2-boot on the 'Installation Utitlity' floopy will bring the menu up.  The first item is labeled as "Partition Disk according to user definition'.  Select item 1 will repartition your disk as you specified.  
		
		Quit!:	Deactivates the tool window.
		

	Copy VMem!: Copy VMem performs a cross-volume copy of the virtual memory backing store from one logical volume to another logical volume. Copy VMem pops up a separate window with the following parameter items and command items:

	Source Volume:	Lisp			Destination Volume: xxxx
	
	Start!					Quit!
	

	'Start!' starts the copy operation.
	
	'Quit!' deactivates the option window.    
	
	WARNING: The Copy VMem! command will only copy the size of VMem specified on the source volume, not the entire volume.

		Parameter items for 'Copy VMem':
	
		Source Volume: An enumerated item from which the Interlisp virtual memory will be copied.
	
		Destination Volume: An enumerated item to which the Interlisp virtual memory will be copied.
		 
		 
		Command items for 'Copy VMem':
	
		Start!: Does the obvious.  File subwindow asks for confirmation of Source and Destination with the mouse icon.  When the virtual memory has been copied, the user can respond to the confirmation mesage to boot the Designation  volume, or can cancel the confirmation and Quit!.  Two positive indicators are provided for this operation. They are the 'twiddling' Yin-Yang graphic and the 'Pages Transferred' information displayed on message-subwindow.
	
		Quit!: Returns you to the bouncing box.

	Scavenge!: Scavenge performs a file-scavenge on the volume selected.  This command is be used whenever you suspect the integrity of your disk volume.  It is recommended whenever you encounter strange behaviors on your system.  At the end of this operation, it produces an MSScavenge.log file in that volume.  Reading this file will reveal the damaged files which have been repaired if any.

	Floppy!:  Floppy command supports floppy feaures on your Dandelion.  This is yet to be implemented.

	Quit!:	Quit deactivates the window and returns the tool to the 'Base State'.
       
	

2.	LOADING INTERLISP-D SOFTWARE

	There are two ways to load your Interlisp-D software.  One way is to load from you floppy disketts and the other way is to load from file server.


2.1	LOADING INTERLISP-D SOFTWARE FROM FLOPPIES

	1.	Place the 'Installation Utility' disk in your floppy disk drive and do a 2-boot.

	2.	When the Installation menu comes up, select the item labelled 'Install Interlisp on Lisp/x volume'. Note for the 29MB and 42MB disks, you may have multiple lisp volumes, for the 10MB disk you only have one Lisp volume.

	3.	Follow through the dialog to load your Interlisp-D floppies.  For different Lisp sysout files you may have different number of floppies.  Currently, the script allows upto 5 floppies.

	4.   Select the 'Boot SystemTools volume' option which will return you to the 'Base State'.  Click the left mouse button putting you into the Lisp SystemTools.

	5.   Select the Set VMem! command and confirm with the left mouse button.  After about couple minutes, the message: 'Approximate maximum VMem Size = X pages' will appear.  Enter the value of X for the new value of the VMem Size parameter, in the PARAMETER WINDOW.

	6.   Select the Set VMem! command and confirm with the left mouse button once again in order to set the new VMem Size.

	7.   Select the Boot! command to start Interlisp-D or Quit! to return to the base state.

 
       
2.2	LOADING INTERLISP-D SOFTWARE FROM A FILE-SERVER

	1.	Activate Lisp SystemTools from 'base state'.
	
	2.	First select the input device from the 'Device' parameter, and then specify the 'File' parameter.  'File' parameter specifies the file pathname on the device if the device is a file server, else it specifies the floppy file name if the device is floppy.
		For file server device you need to specify User and Password entries, and optionally you may need to specify Domain and Organization parameters if it is a product file server.
	
	3.	Click the 'Install File!' command item, and confirm with the left button.  
	
	4.	During File Transfer, two indicators are posted, one is the twiddling 'star' graphic symbole and the other is the actual bytes being transferred.  When it is completed, 'Done' will be posted on the file subwindow. 

3.	NOTES FOR XEROX INTERNAL USERS

	This section contains information that are relevant and applicable only to Xerox internal users and should not be disclosed to outside commercial customers.
	
	3.1	PARTITION YOUR DISK FROM OTHELLO
	
	Users may partition their disk to their own specification and install the necessary boot files from file server by using Othello.   Section 3 of Mesa Users Guide presents the detailed instrunction on doing this.  Users must have a 'Tajo' volume to accomodate the Lisp SystemTools package.  For non-programmers a 3500 pages will be sufficient for this Tajo volume.
	
	3.2	SET UP YOUR TAJO VOLUME
	
		3.2.1	INSTALL BOOT FILES, LISP SYSOUT AND 'SYSTEMTOOLS' FROM ETHERNET
	
	
	3.3	HOW TO SET UP YOUR USER.CM FILE
	
		The Lisp SystemTools parses your user.cm file for some default setting upon coming up.  In specific 'User', 'Password', 'Domain', 'Organization' 'Device' and 'File' parameters will be set if their corresponding entry is present in the user.cm file.  Below is a sample user.cm,  you should modify the appropriate fileds for your convenience. For users using Tajo volume instead of SystemTools, change [SystemTools:System] merely to [System].
	
	
	[User.cm]
	[System]
	User: JFung.pasa
	Password: YourPassword
	Domain: XSIS
	Organization: XEROX
	FileServer: IFS or FS or FLOPPY
	NSFile: [Server:Domain:Organization]<Directory>SubDirectories>FileName.Sysout
	PUPFile: [Server]<Directory>SubDirectories>FileName.Sysout
	FloppyFile: Lisp.sysout
	Screen: White
	Debug: FALSE

	[SystemTools:System] or [Tajo:System]
	InitialCommand: SystemTools 

	
	3.4	ACTIVATING 'TAJO' VOLUME FROM BASE STATE
	
		For users convenience, the User/Tajo volume may be activated from the 'base state' by pressing the 'UNDO' key situated on top of the 'STOP' key.  This is NOT documented inside the bouncing box for product rlease reason.