-- SystemTools.doc -- last edited by -- JFung.pasa 17-Oct-84 13:23:29 Filed: [Dante]<LispInstallation>Harmony>SystemTools.doc The Lisp SystemTools is a tailored software particularly to meet the installtion of Interlisp-D software on Xerox's Dandelion (1108) machine. It is an integrated package of three softwares, a) the Online-Diagnostics tool, b) the Profile tool and c) the lisp Systetm tool. This document describes the Profile tool and the Lisp SystemTools in detail. The Online-Diagnostics tool came from Versatec and has online help messages so it will not be discussed here. TABLE OF CONTENTS: 1. INSTALLATION FROM FLOPPIES 1.1 PARTITION YOUR DISK FROM FLOPPY 1.2 SET UP YOUR 'SYSTEMTOOLS' VOLUME 1.2.1 INSTALL BOOT FILES AND 'SYSTEMTOOLS' 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 SYSTEMTOOLS 1.6.1 LISP SYSTEMTOOLS WINDOW 1.6.2 TOOL COMMANDS AND PARAMETERS 2. LOADING INTERLISP-D SOFTWARE 2.1 LOADING INTERLISP-D SOFTWARE FROM SYSTEM-TOOLS 2.2 LOADING INTERLISP-D SOFTWARE FROM INSTALLATION UTILITY FLOPPIES 3. INSTALL FROM ETHERNET FOR XEROX INTERNAL USERSS 3.1 PARTITION YOUR DISK FROM ETHERNET 3.2 INSTALL BOOT FILES AND LOADING 'LISP SYSTEMTOOLS' 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 SystemTools volume. 1.2 SET UP YOUR SYSTEMTOOLS 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, RS232 loopback, echo to other hosts on the Ethernet and Ethernet statistics. 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.1 INSTALL BOOT FILES AND 'LISP SYSTEMTOOLS' 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 Files' 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 init.cm <CR>. 9. Type in "@Init <CR>" at your exec window. 9. 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 messages present 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 SystemTools is activated. 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 here. User: Guest.pasa Password: ****** Domain: XSIS Organization: XEROX Device: IFS|FS|FLOPPY NSLisp: [Stash:]<LispCourse>LispCourse.sysout PUPLisp: [Rose]<Lisp>Harmony>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. For PUP users, you should also specify your registry, in here it is "pasa". 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 SystemTols 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 the lisp sysout is to be loaded. The following are the command items: Set Profile! Set Profile will create or overwrite your user profile (user.cm) 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 and turn it into a bootable file. b. Boot volume of both lisp type and non-lisp type. c. Erase capability to erase the contens of a logical volume. d. Scavenge capability to diagnose and fix the indiviual 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. h. Repartition and renaming disk volumes via the MakeScript command. 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: Guest.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 may be used 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 allows you to repartition your disk with names and sizes your provide. This command adds the new configuration together with standard system supplied configurations into the script file which is located in your Installation Utility floppy. You may consider make a duplicate of your Installation Utility floppy before you exercise this command. When partitioning a disk, it is imperative to use all the disk pages available. If this is not done and then later the disk is damaged, the physical volume my be unscavengable. For this reason, the tool explicitly makes the last volume to take the residual pages in the disk. This command pops a new window with the following parameters: DiskType: {10Mb, 29Mb, 42Mb} DriveSize: nnnnn Free Pages: nnnn Volume1 Name: SystemTools 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 write-protected. Volume1 Size: A numeric item which is also write-protected 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!: Deactivate the current window. 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!: Provides extra frloppy features. This command pops up a new window of the following parameters: Pattern: Floppy Name: Info! List! Format! Duplicate! Quit! Info! command will display the floppy attribute information, like density mode(single or double), side mode(single or double), free pages and largest free block on your floppy. It will also stuff the floppy name into the Floppy Name: field. List! command will enumerate the floppy files according to the patten specified in the Pattern field. Wild cards of * and # are supported. Format! command will format the floppy with the floppy name string supplied in Floppy Name: field. You must specify the Floppy Name: field. Duplicate! command will duplicate a floppy. Follow the interaction, the first step is to select a volume with at least 2250 free pages for the buffer space. This space is later cleaned up. Duplicate command will format your floppy if it is unformatted. . Quit!: Deactivate the current window. 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 SYSTEM-TOOLS 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 an NS 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. For all devices, the VMem is automatically expanded to the highest possible extent unless the VMem field is specified. Becuase of this, this method is recommended for installing Interlisp-D software. 2.2 LOADING INTERLISP-D SOFTWARE FROM INSTALLATION UTILITY 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 6 floppies. Note: the floppy sysout name is restricted to Lisp.Sysout, for different sysout names, use the systemTool to load from 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. 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 User/Tajo volume. There are standard command files to partition different kind of disks for users not familiar with the selection of volume sizes. These command files exist at [eris]<Lisp>Harmony>cm>*. For more information refer [eris]<Lisp>Harmony>Doc>GettingStarted.press 3.2 SET UP YOUR TAJO VOLUME After your Tajo/User volume is set up, you may retrieve the 3.2.1 INSTALL BOOT FILES, LISP SYSOUT AND 'SYSTEMTOOLS' FROM ETHERNET After your Tajo/User volume is set up, you may use the XDE's FileTool to retrieve the following file into your Tajo volume. 1. [Dante]<LispInstallation>Harmony>SystemTools.bcd/LispTool.bcd 2. [Dante]<<LispInstallation>Harmony>Diagnostics.msgs into <Msgs>Diagnostics.msgs (for OnlineDiagnostics use only) 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] [LispTool] User: Guest.registry 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: SpeechDemo.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 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. Any other Tajo volume can be booted from the Boot! command in the SystemTools window. In the event if you are partitioned with "SystemTools" volume and you need to boot it, you may supply the password "N0way!" in the password field then select systemTools volume then click the boot command.