README.TXT for /pub/mae/product-trial/3.0
r6: 07-May-97


   RELEASE NOTES FOR MACINTOSH APPLICATION ENVIRONMENT 3.0 UPDATE 4

                              07 May 1997


===================================================================== 
                         ABOUT THIS DOCUMENT
===================================================================== 

REVIEW THIS DOCUMENT CAREFULLY BEFORE INSTALLING OR USING MAE 3.0!

This document is a "road map" to the other MAE documentation as well
as the MAE installation process.  Included are useful tips and
cautions regarding installation of the product.

Information contained in this document may have changed since its
inclusion with the MAE 3.0 product materials.  For the latest
information on MAE, you are strongly encouraged to visit the MAE web
site at

   http://www.mae.apple.com/

You may wish to bookmark this URL for future reference.  We also
suggest that you keep a printed copy of this document with your MAE
3.0 product materials.

Note that for simplicity's sake, we refer to MAE 3.0 Update 4 as MAE
3.0 throughout this document.


===================================================================== 
            SUPPORTED WORKSTATIONS AND OPERATING SYSTEMS
===================================================================== 

MAE 3.0 has been thoroughly tested on Sun SPARC workstations running
Solaris 2.5 and HP series 700 workstations running HP-UX 9.0.5 and
HP-UX 10.10.  MAE is also compatible with other final release versions
of Solaris (2.4 and later) as well as HP-UX (9.0.3 and later) with the
exception of HP-UX 10.01. In the event that you have installed HP-UX
10.01, you must first upgrade to HP-UX 10.10 (or later) if you wish to
use MAE 3.0.

ROSS HyperSPARC processors are supported in this release.  You are
encouraged to verify that you have the latest patches from ROSS
Technology; they maintain a web site at http://www.ross.com/.

A minimum of 32MB of memory must be available on the workstation; we
recommend 48MB for optimal performance.


===================================================================== 
                       WHAT'S NEW IN MAE 3.0
===================================================================== 

** NEW LICENSING PROCEDURE 
You must obtain a license key before you can use MAE 3.0.

- If you have purchased the product, review the documents `About MAE
3.0 License Keys' and `MAE 3.0 License Registration'.  These documents
are included as `LIC_REG.TXT' in the top level directory of the MAE
3.0 CD-ROM as well as in hardcopy form as part of your MAE product
materials.

- If you will be using the MAE 3.0 Free Demo, you must obtain a key
from the MAE web site at

   http://www.mae.apple.com/

For more information on license management, refer to the Appendix of
the ADMINISTRATOR'S MANUAL, "The License Manager".  Note that the
`License Binder' keys from earlier versions of MAE cannot be used with
MAE 3.0.

** NEW FEATURES AND ENHANCEMENTS FOR MAE 3.0 
For a list of new features and product enhancements that we have
incorporated into MAE 3.0, refer to the Frequently-Asked Questions
(FAQ) available from the MAE web site.

** KNOWN ISSUES FOR MAE 3.0 
We strongly encourage you to examine the current list of unresolved
issues that have been identified for this release of MAE 3.0. 
Whenever possible, a workaround or other comment has been included
with each issue.  An up-to-date version is maintained on the MAE web
site.

** UPGRADING FROM PREVIOUS VERSIONS OF MAE 
MAE 3.0 can update existing installations of MAE 2.0.x; it is not
possible to upgrade from MAE 1.0.  Review the section titled "RUNNING
MAE FOR THE FIRST TIME AFTER INSTALLATION" (later in this document)
for details on upgrading your workstation to MAE 3.0.


===================================================================== 
                      DOCUMENTATION FOR MAE 3.0
===================================================================== 

Documentation for MAE 3.0 is supplied as PDF (Adobe Acrobat) files
which can be read from both Unix and from within MAE.  You will need
to install the Adobe Acrobat Reader in order to view the MAE 3.0
documents:

   - USER'S MANUAL, "Macintosh Application Environment User's Manual" 
   - ADMINISTRATOR'S MANUAL, "Macintosh Application Environment System
Administrator's Manual"

These manuals are supplied as `USER.PDF' and `ADMIN.PDF' in the
`/DOCS' directory of the MAE 3.0 CD-ROM.  To install Acrobat Reader
for HP-UX, execute the shell script `INSTALL' found on the MAE 3.0
CD-ROM in the directory `/DOCS/HPUX/'.  For Solaris, use
`/DOCS/SOLARIS/'.  The documents are also available for free from the
MAE web site.

Additionally, the manuals and Acrobat Reader are installed into the
`docs' subdirectory of `Apple Extras' (located in the Apple directory)
during an `Easy' install or if explicitly selected during a `Custom'
install.  An alias to the `docs' directory is located in the `Apple
Extras' folder for each MAE user.  To install the Acrobat Reader for
Macintosh, simply double-click on its installer file.


===================================================================== 
                 OTHER MAE 3.0 INFORMATION RESOURCES
===================================================================== 

** THIS README FILE 
This document contains important notes on this version of MAE 3.0 and
its related documentation.  Review this document carefully before
installing or using MAE 3.0; it is included as README.TXT on the MAE
3.0 CD-ROM.  For your convenience, a copy is also maintained on the
MAE web site.

** MAE-USERS MAILING LIST 
The MAE Engineering Team has created an unmoderated mailing list named
`mae-users' that encourages informal discussion of the MAE product.
`mae-users' permits our customers to assist each other and distribute
hints and other information about the product.  Although the MAE
Engineering Team monitors all submissions, we generally do not
respond.  As appropriate, we may include fixes in a future patch
and/or update our documentation suite (including our web site). 
Announcements regarding patch availability are made on our mailing
lists as well as on our web site.  For more information on
`mae-users', send a message with the body text `info mae-users'
(without the quotes) to `listproc@solutions.apple.com'.

** THE MAE WEB SITE 
The MAE Engineering Team maintains up-to-date information on the MAE
3.0 product.  We urge you to regularly check the web site for the
latest news on known issues, patches, and bug fixes as well as other
helpful hints and tips.

The following resources are available:

** Frequently-Asked Questions (FAQ)

** Known issues and workarounds

** Updates to the MAE documentation (PDF files)

** Bug reporting

** Feedback facilities

** HyperMail archive of the `mae-users' mailing list

Access to all of these resources is via the MAE web site at

   http://www.mae.apple.com/


===================================================================== 
                           HOW TO PROCEED
===================================================================== 

Before installing MAE 3.0, read (1) this document, (2) Chapter 1 of
the USER'S MANUAL, "Installing the Macintosh Application Environment",
and (3) the web-based resources for current status on known issues and
workarounds.  After completing your installation of MAE, you will find
the information on the MAE web server useful for solving
commonly-encountered situations.


===================================================================== 
                   INSTALLING AND RUNNING MAE 3.0
===================================================================== 

The remainder of this document is functionally organized as follows:

I.    VERIFYING VENDOR PATCHES IN YOUR WORKSTATION SOFTWARE 
II.   INSTALLING STREAMS/UX (HP-UX 9.0.X only) 
III.  RUNNING THE MAE INSTALLER 
IV.   RUNNING MAE FOR THE FIRST TIME AFTER INSTALLATION

Items applicable only to Sun workstations are labeled "(Sun only)";
those applicable only to HP workstations are labeled "(HP only)".  All
other items apply to both workstation types.


I.  VERIFYING VENDOR PATCHES IN YOUR WORKSTATION SOFTWARE
=========================================================

MAE was tested against the OS versions and patch levels as listed
below for all environments (Solaris and HP-UX).  Installation of any
other OS patches (beyond those listed here) is at the sole discretion
of the customer.  Apple Computer, Inc. and the MAE Engineering Team
make no recommendations regarding the administration and maintenance
of workstations on which the MAE product is installed.  You are
strongly urged to verify the latest patch revisions and
recommendations with the respective workstation OS vendors.

- Solaris v2.4 with Sun's Recommended Patch Cluster.

- Solaris v2.5 with Sun's Recommended Patch Cluster.  UltraSPARC
workstations with Creator 3D cards additionally require 103076-08.

- Solaris v2.5.1 with Sun's Recommended Patch Cluster.  UltraSPARC
workstations with Creator 3D cards additionally require 103796-03.

- HP-UX 9.0.x with the following patches: PHKL_9229, PHKL_9868,
PHNE_9100, PHSS_4341.  HP-UX 9.0.x workstations with FDDI also require
one of the following patches, depending upon the FDDI hardware present
in your workstation: PHNE_4717 (built-in FDDI), PHNE_4003 (EISA FDDI).

- HP-UX 10.10 with no additional patches.

- HP-UX 10.20 with no additional patches.

For further information on OS patches for your workstation, contact
your system administrator as well as your authorized Sun or HP support
organizations.

Both vendors maintain web sites that distribute patches and up-to-date
information; you may require a support contract in order to gain full
access to these resources.

For HP-UX information: http://support.mayfield.hp.com

For Solaris information: http://sunsolve.sun.com


II. INSTALLING STREAMS/UX (HP-UX 9.0.x only)
============================================

The STREAMS package is required for MAE to function with HP-UX 9.0.x;
it is not required for HP-UX 10.x.  The STREAMS filesets are supplied
on the CD in a `tar' file in the directory `/STREAMS'.  Do not attempt
to un-tar this file; the /etc/update program understands how to read
the tar format.  Two STREAMS packages are included: 3STREAMS.TAR and
5STREAMS.TAR.  You should install 3STREAMS.TAR on HP-UX 9.0.3 and
5STREAMS.TAR on HP-UX 9.0.5 or 9.0.7.  The following filesets are
included:

STREAMS 
STREAMS-DLPI 
STREAMS-MAN 
TLI-XTI-MAN

To install STREAMS:

- mount the CD-ROM on your workstation 
- install all four filesets by using the /etc/update command.

WARNING: installing STREAMS will reboot your workstation.

In the following example, it is assumed that the MAE CD-ROM was
mounted at `/cdrom':

/etc/update -rs /cdrom/STREAMS/3STREAMS.TAR '*'

-or-

/etc/update -rs /cdrom/STREAMS/5STREAMS.TAR '*'


III.  RUNNING THE MAE 3.0 INSTALLER 
===================================

** Read Chapter 1 of the USER'S MANUAL, "Installing the Macintosh
Application Environment" before running the MAE Installer.

** BACK UP ALL IMPORTANT FILES ON YOUR WORKSTATION!  If you have a
previous MAE installation, be sure to back up or rename your MAE
files.  This includes resources for each user (System Folder, .mac,
and any additional directories such as `Apple Extras') as well as the
Apple directory (appledir).  IMPORTANT: some UNIX backup utilities are
not compatible with Macintosh file names, which contain spaces and
8-bit special characters.  Ensure that your backup utility will handle
these conditions before proceeding.

** The most straightforward way to install MAE is to run the Installer
while logged onto your workstation as `root'.  If you run as an
ordinary user, it will not be possible to install system-level
facilities such as the AppleTalk kernel modules.

** If you choose an `Easy' install or select the AppleTalk package as
part of a `Custom' installation, MAE 3.0 AppleTalk resources will be
installed on your workstation.  If a previous version of MAE AppleTalk
resources exist, they will be updated.  The MAE 3.0 AppleTalk
resources will work with your existing MAE 2.0.x installations, but
note that the reverse is NOT true (i.e., MAE v2.0.x AppleTalk is not
compatible with MAE 3.0).  As a precaution, we suggest that you copy
the files that will be updated by the Installer to a safe place prior
to installing MAE 3.0.  The names of the files are as follows:

- For HP-UX 9.0.x, it is the kernel itself: /hp-ux

- For HP-UX 10.x, it is the kernel itself: /stand/vmunix

- For Solaris, the AppleTalk components are comprised of several
files:

  /kernel/strmod/adsp 
  /kernel/strmod/at_atp 
  /kernel/strmod/at_sig 
  /usr/kernel/drv/atalk

** (HP only) The Installer will not install MAE 3.0 on HP-UX 10.01.
You must upgrade to HP-UX 10.10 or later BEFORE installing MAE 3.0.

** The Installer will upgrade your existing appledir to version 3.0
resources. The installer archives your existing appledir during the
MAE installation process, but removes the archived files upon
successful completion of the installation.

** A new directory named `/man' will be created in the Apple directory
for the man (manual) pages.  It contains the `man1' and `man1m' pages
for MAE 3.0. For more information on the man pages, see Chapter 2 of
the USER'S MANUAL, "Starting and Quitting MAE".

** IMPORTANT: The MAE binaries for HP-UX 9.0.x, HP-UX 10.x and Solaris
are not interchangeable.  If you have more than one type of system at
your site, ensure that you run the Installer for each OS.  The MAE
Installer must be run on the same OS that you are trying to install
for (e.g., you cannot run the Installer on Solaris to extract binaries
for HP-UX).

** You may experience problems when attempting to install MAE on an
AFS volume.  MAE cannot be installed on an AFS volume at all unless
the installing user is the super user and has AFS administration
privileges.  Possible workarounds for residual difficulties: (1)
upgrade to the latest release of AFS, which supports 8-bit characters
in file names (2) install MAE onto a local or NFS-mounted volume and
then copy the MAE Apple directory (appledir) onto your AFS volume.
(Remember: if you move the appledir, you must use the `-appledir'
command line option to start MAE.)

** (Sun only):  During installation of MAE 3.0 into an AFS file
system, very long AFS pathnames or very large AFS volumes may cause
the Installer to fail. The Installer parses the output from the
command `df -k'; the failure condition occurs when the pathname or
volume size fields run together without an intervening space.  Before
executing the Installer, execute a `df -k' command to verify that
these two fields are properly separated by at least one space.

** (HP only) If you are running automounter and install MAE 3.0 into
an automounted directory, specify the path in /tmp_mnt rather than
/net (e.g. `/tmp_mnt/net/lukas/apple' instead of `/net/lukas/apple').

** When running the Installer, do not use destination directory names
ending in special characters such as +, -, or &.

** Customizing the Install process for mass installation: Some sites
have installed MAE on a central NFS or AFS server.  Before undertaking
support of such an installation, read Chapter 2 of the ADMINISTRATOR'S
MANUAL, "Customizing MAE and Your Workstation".  You should also
review the configuration and contents of the file `/etc/mae_fileshare'
which can be used to limit access to files via MAE Filesharing.  For
more information, read Chapter 5 of the ADMINISTRATOR'S MANUAL,
"AppleTalk Administration".


IV.  RUNNING MAE FOR THE FIRST TIME AFTER INSTALLATION
======================================================

** Read Chapter 2 of the USER'S MANUAL, "Starting and Quitting MAE"
before running MAE 3.0 for the first time.

** Before you can run MAE successfully, you must configure license
management for MAE.  Refer to the document `MAE 3.0 License
Registration', which is included as `LIC_REG.TXT' in the top level
directory of the CD-ROM as well as with your product distribution
package in hardcopy form.  For more information on license management,
refer to the Appendix of the ADMINISTRATOR'S MANUAL, "The License
Manager".

** When MAE 3.0 is launched for the first time and encounters a System
Folder from MAE 2.0.x, it automatically updates the System Folder
resources to MAE 3.0.  Only the Macintosh OS resources that are
required by MAE will be changed; third party resources (e.g.,
user-installed extensions) will not be affected.  Note that a backup
copy of these files will not be made; you should make a copy of your
System Folder and .mac directory before running a new version of MAE.

In the unlikely event that you have trouble running MAE after the
System Folder update occurs, follow this procedure:

- quit MAE (Shutdown) 
- rename your System Folder and `.mac' directory; for example:

  mv System\ Folder old.system.folder 
  mv .mac old.mac

- relaunch MAE to create a new System Folder and `.mac' directory. 
- if you need Extensions or other files from the renamed System
Folder, copy them to the new System Folder one at a time, restarting
MAE after each new file is added to verify correct operation.

Note that as a result of using MAE 3.0, several new directories will
be added to your existing .mac directory.

** The first time MAE is launched for a new user, the following
directories will be created:

System Folder 
.mac 
Apple Extras

Both the `System Folder' and `.mac' directories are required for MAE
and will be placed by default in each user's home directory.  You can
change the location of these two directories by using the `-sysfol'
and `-macdir' command line options; see Appendix C of the USER'S
MANUAL, "Command Options and X Resources" for more information on
command line options.  The `Apple Extras' folder contains aliases to
useful Macintosh utilities and other resources.  It replaces the
`demos', `Tools', and `man1' aliases that were created as part of MAE
2.0.  The following resources are placed in the `Apple Extras' folder:

- AppleScript 1.1 
- HyperCard Player 2.3.5 
- MoviePlayer 2.5 
- SimpleText 1.3.1

- Shareware/freeware, located in the folder `Third Party':
  - Disinfectant 3.6
  - Stuffit Expander 4.0.1 
  - DropStuff w/EE 4.0 
  - Fetch 3.0.1

Ensure that you read the document `Disclaimer-Please Read' before
using any of the shareware/freeware applications.  We ask that you
honor any shareware fees, as appropriate.

** New for MAE Update 4: Since the original inclusion of CFM-68K,
OpenDoc, and Cyberdog on the MAE 3.0 product CD-ROM, a problem was
discovered with CFM-68K that can cause reliability issues.  As a
result, those products are no longer included on the MAE 3.0 product
CD-ROM.  However, you can obtain newer versions of the software for
free from the following Apple web sites: 

   - http://www.opendoc.apple.com   for OpenDoc and Cyberdog 
   - http://www.macos.apple.com     for CFM-68K. 

** If you choose to install MAE 3.0 into the same home directory as an
existing MAE 2.0.x installation, some of the 2.0.x aliases may point
to resources that are not present or were changed in 3.0.  This is
particularly true if you subsequently remove your Apple directory
(appledir) for 2.0.x. Example: the aliases for `tools' points to
resources in the 2.0.x appledir that are in different locations in
3.0.  Similarly, if the `Apple Extras' folder exists from a previous
version of MAE, the aliases in it may no longer function properly
after installing MAE 3.0.  You should rename the `Apple Extras' folder
before executing MAE 3.0 for the first time.

** If you wish to move items from previous installations of MAE
(2.0.x) from saved System Folders to MAE 3.0:

- Some aliases may no longer work; if so, they will need to be
recreated. 
- Some applications (e.g., Microsoft Office) store information within
the product itself that contains the path to the directory into which
it was originally installed.  Therefore, you may need to reinstall
these applications.

** With the exception of `.MIV_file', do not delete or change any of
the files or folders located in the `.mac' directory for each MAE
user.  You may irrecoverably damage your installation of MAE if you
attempt to do so.  More information on `.MIV_file' can be found in
Chapter 2 of the ADMINISTRATOR'S MANUAL, "Customizing MAE and Your
Workstation".

** Do not manually create a MIV specifically for any of the three
critical directories needed by MAE to function: (1) .mac, (2) System
Folder, and (3) Apple directory (appledir).  If these directories are
not contained within one of the startup MIVs (i.e., via an entry in
the .MIV_file located in each user's .mac directory), MAE
automatically creates a MIV of the parent directory containing the
critical resource.

Example: if the appledir is `/opt/apple' and `/' is not a startup MIV,
then `/opt' will automatically be created as a MIV.

Problems can arise if a MIV entry is created directly for one of the
critical directories named above (or one of their subdirectories)
rather than contained in a parent MIV.  The MacOS does not expect the
System Folder to be a volume (as opposed to a folder within a volume).
 Similarly, having `/opt/apple' be a volume (rather than `/opt') may
also cause problems.

** If you are upgrading from MAE 2.0.x, the following section will be
useful in retaining association of documents with their creator
applications in MAE 3.0.  We suggest that you review it carefully
before running MAE 3.0 for the first time.  If you prefer not to
perform the steps outlined below, your documents will be associated
with their creator applications gradually (as you access the
applications in the Finder).

In MAE 2.0.x, the entire filesystem for your workstation environment
was shown on the Finder Desktop as a disk named `/'.  This has changed
for MAE 3.0.  By default, you will now see:

- a disk representing your home directory 
- a disk that contains your Apple directory (appledir)

If you wish to see other directories represented on the Desktop
(beyond the defaults listed above), you will need to create a static
MIV entry in your `.MIV_file.  For more information on MIVs, review
Chapter 2 of the ADMINISTRATOR'S MANUAL, "Customizing MAE and Your
Workstation".  If you make any changes to the `.MIV_file', you should
also rebuild your Desktop (as detailed in the next paragraph).

Similarly, Desktop rebuilds may have been problematic in MAE 2.0 since
(in some cases) the entire volume `/' was being searched.  (A rebuild
is performed the very first time MAE is launched for a new user or if
specifically requested with the `-rebuild' command line option.)

With MAE 3.0, the default behavior is to search only the appledir
during a rebuild.  In order to retain association of documents with
their creator applications, you are strongly encouraged to set the
Unix environment variable `APPLEPATH' to the location (directory) of
your Macintosh applications. Multiple directories can be specified and
are colon-separated (as with other Unix path variables).  Note that
NFS boundaries are not crossed during a Desktop rebuild; if you wish
to include several NFS directories that are contained within one
parent directory, you must specify each NFS directory individually. 
As mentioned above, each of these directories should also exist as
static `.MIV_file' entries.  For more information on the `APPLEPATH'
environment variable, review Chapter 2 of the ADMINISTRATOR'S MANUAL,
"Customizing MAE and Your Workstation".

Example: your home directory is `/usr/ste' and your applications are
installed in `/usr/ste/MacApps' and the NFS directory
`/net/jaime/Applications'.  You would create the static `.MIV_file'
entry

   /net/jaime/Applications Applications

and set `APPLEPATH' (using `csh' as an example)

   setenv APPLEPATH /usr/ste/MacApps:/net/jaime/Applications

Your applications directory would then appear on the Desktop as a
volume named `Applications'.  Both the `MacApps' subdirectory of your
home directory and the applications directory would be searched during
a Desktop rebuild.

** Demo software: MAE 3.0 includes four Claris demo applications:

- ClarisWorks 4.0 
- FileMaker Pro 3.0 
- ClarisImpact 2.0 
- ClarisDraw 1.0

More information on installing the demo applications can be found in
Chapter 1 of the USER'S MANUAL, "Installing the Macintosh Application
Environment".  You are encouraged to visit our web site at
www.mae.apple.com for the latest versions of these products as well as
additional demo software packages.

