Notes on installing A-Shell/OpenServer from the web       29 Mar 2004
=====================================================================

Overview
--------
The release is packaged as a compressed (.Z) file containing a 
single cpio (.bin) file.  It can be used for both new installations and 
updates of existing installations; the procedure is the same in either 
case.  An update will not overwrite existing miame.ini and ersatz.ini 
files, but it will update message files, function key translation 
tables, lit files, etc.  It will save copies of your old function key
translation tables (using "s" as the last character of the extension) but
if you have concerns about other files you may have customized, see
the notes under step 5 below for customizing the installation.)

The name of the compressed file is ashell-version-osr5.bin.Z where
the "version" is replaced by the current A-Shell version in dotted
notation (e.g. 4.8.837.1).

The "bin" in the file extension indicates that it is a complete binary 
release in cpio format.  The "Z" indicates that it is then compressed
using the compress command.  

Note that we may make patches to the release available on our 
http://www.a-shell.net site.  These will typically be in the form of 
compressed tar (.tar.Z) files containing just the ashell executable 
(possibly along with a few other auxiliary files.)  These should be 
untarred into a temp directory and then copied on top of the 
corresponding files from the full release.

DOWNLOAD NOTE:  In most browsers, the way to download any of these files is
to right-click on the highlighted text and then select "Save As".  


Procedure for unpacking and installing
--------------------------------------

1.  Log in as a non-root user, then use su to change to root.

2.  Place the file(s) in a convenient temporary location, such as /tmp

3.  Unpack the file into the /tmp directory.  (You can put it in 
    any directory - just specify it in the following commands in place
    of /tmp)

	# cd /tmp
	# uncompress ashell-#.#.###-osr5-bin.Z

    Replace "#.#.###" with the correct version from the actual 
    package filename.  This will replace the compressed Z file 
    with the uncompressed version, removing the .Z extension.

4.  Extract the ash_install script from the cpio (bin) file.

	# cpio -icuB ash_install < /tmp/ashell-#.#.###-osr5.bin
				(e.g. /tmp/ashell-4.8.837.1-osr5.bin)

5.  If this is an update, and you are concerned about it overwriting 
    files that you may have customized, then besides making sure you
    have a backup, you may want to check the README.TXT file in the 
    $MIAME/custom subdirectory.  They describe how to activate and 
    customize a pair of special scripts that will be called by the 
    installer before and after the process of copying the new files,
    thus allowing you to perform your own special pre-update and 
    post-update processing.  (If you don't have a custom subdirectory,
    it is because you haven't previously installed A-Shell 4.8.  If you
    want to use the pre and post install customization scripts anyway,
    then proceed with the ash_install procedure described in the 
    following steps, but install to a new temporary directory.  
    The move the custom subdirectory from that installation to the 
    directory tree where you want to perform the update, modify
    the scripts as appropriate, and then restart this update operation
    at step 4.)

	# ./ash_install

6.  Following the instructions, specifying a target directory (typically
    /vm/miame for both the runtime and object paths.)  For the source
    device, specify /tmp/ashell-#.###-osr5.bin (e.g. 
    /tmp/ashell-4.8.837.1-osr5.bin), replacing the device with another 
    path if you saved it elsewhere.

7.  If this is a new installation and you didn't install to /vm/miame,
    then you will need to manually edit the <install path>/miame.ini 
    file and replace all occurrences of /vm/miame with the actual target
    path you used.  Also, you will need to create an environment variable:

	MIAME=/vm/miame
	export MIAME
	
    This should point to where you actually installed the software.  You
    may also want to update your PATH environment variable to add 
    /vm/miame/bin to your search path.

    Typically setting up the MIAME and PATH environment variables is done
    in your logon profile.  

8.  You can use the # exit command to return to your normal login.


Adding an entry for am62a terminals in the TERMINFO database
------------------------------------------------------------
If you are using am62a, am65, or am75 terminals or emulators, you should 
add a TERMINFO definition for them.  To do this, log in (or su) to root
and execute:

	# tic -v /vm/miame/am62a.tis

(Again, replace /vm/miame with the actual directory you installed in.)
Note that a TERMINFO definition is not needed for A-Shell, but will be
handy if you want to run any UNIX utilities outside of A-Shell.  

Make sure when you set up your TERM variable, that you use lower case,
such as am62a, am62c, am65 or am75.

If this operation is not successful, don't worry too much.  Some Linux
utilities (such as vi) may require a valid working TERM definition, but
A-Shell itself has its own internal drivers for am62a, am62c, am65, and
am75, wyse50, vt220, vt420, and a few others; as long as your TERM 
definition matches one of those, it will work fine.


Launching A-Shell
-----------------

Launch A-Shell with a command such as:

	$ ashell
or
	$ /vm/miame/bin/ashell

The first format assumes that /vm/miame/bin has been added to the PATH.


Additional Documentation
------------------------
Please refer to the A-Shell User's Guide (available on the Download
page at http://www.microsabio.com) for additional details on configuring
A-Shell.  Also look in the doc subdirectory (e.g. /vm/miame/doc) for
readme.txt, which contains some useful pointers are getting started.