Introduction

The upgrade from EMu Version 3.2 to EMu 4.0 involves a number of steps. Please follow the instructions below carefully. You cannot skip any steps under any circumstances.
Before proceeding with the update please ensure that a complete backup of the EMu server exists and is restorable.

There are four main components that require upgrading:

• Texpress (the database engine)
• TexAPI (web services)
• EMu Server (the application)
• EMu Client (the client)

The notes below detail how to upgrade all systems. Check the Releases table for Client specific notes.  Upgrading comprises the following steps:

• Stopping EMu services
• Installing Texpress
• Upgrading TexAPI
• Upgrading EMu Server
• Starting EMu services
• Upgrading EMu Client

In the notes below clientname refers to the name of the client directory for the current installation. The term ~emu is used to refer to user emu's home directory. This is normally /home/emu.

Requirements

• Texpress version 8.3.001 or greater
• TexAPI version 6.0.003 or greater
• EMu Server version 4.0.03 or greater
• EMu Client version 4.0.03 or greater
  Installing EMu Version 4.0.01 or 4.0.02 requires Texpress 8.2.007. 
• Perl version 5.8 or greater

Stopping EMu services

1. Log in as emu.
2. Enter client clientname
3. Enter ls  -l  loads/*/data*
   A check should also be made for local loads (ls  -l  local/loads/*/data*) if present.
   
4. Check each data file is empty and no data.t files exist.
   If this is not the case, please wait for the loads to drain before proceeding.
5. Enter emuload  stop
6. Enter emuweb  stop
7. Enter texlicstatus
   Make sure no-one is using the system.
   The upgrade will not complete successfully if users are accessing data.

Record Session

Each step in the upgrade process produces detailed output. In most cases this output will exceed the size of the screen. It is strongly recommended that the output of the upgrade session is recorded, so if errors occurs the output can be examined.

1. Enter script /tmp/output-4-0-01

A new shell will start and all output recorded until the shell is terminated.

Installing Texpress

Installing Texpress 8.3 is only required for the first client upgraded to EMu 4.0. Once Texpress 8.3 has been installed this section may be skipped for subsequent upgrades.

1. Enter cd  ~emu
2. Enter mkdir  -p  texpress/8.3.xxx/install where xxx is the version of Texpress being installed.
3. Enter cd  texpress/8.3.xxx/install
4. Obtain the appropriate Texpress version for your Unix machine via the KE Texpress hyperlink above. Save the release in ~emu/texpress/8.3.xxx/install, calling it texpress.sh.
5. Enter sh  texpress.sh
   The Texpress release will be extracted.
6. Enter .  ./.profile
7. Enter bin/texinstall  ~emu/texpress/8.3.xxx (expand the ~emu)
   The Texpress installation script will commence.
8. Enter cd  ~emu/texpress/8.3.xxx
9. Enter .  ./.profile
10. Enter texbldperms
11. Enter bin/texlicinfo. Obtain your Texpress licence code and place it in a file called .licence.
12. Enter bin/texlicset  <  .licence to install the licence.
13. Enter \rm  -fr  install
14. Enter cd  ~emu/texpress
15. Enter ln  -s  8.3.xxx  8.3

Upgrading KE TexAPI

Installing TexAPI is only required for the first client upgraded to EMu 4.0. Once KE TexAPI has been installed this section may be skipped for subsequent upgrades.

1. Enter cd  ~emu/texpress
2. Enter mkdir 6.0.xxx where xxx is the version of TexAPI being installed.
3. Obtain the appropriate TexAPI version for your Unix machine via the KE TexAPI hyperlink above.
   Save the release in ~emu/texpress, calling it texapi.sh.
4. Enter sh  texapi.sh  -i  ~emu/texpress/6.0.xxx (expand the ~emu).
5. Enter \rm  -f  texapi
6. Enter ln  -s  6.0.xxx  texapi
7. Enter \rm -f  texapi.sh

Upgrading EMu Server

1. Enter cd  ~emu
2. The install bundle must be unarchived into a new temporary directory.
   It is recommended that a new temporary directory named ~emu/clientname/install is used.
   Enter mkdir  clientname/install
3. Enter cd  clientname/install
4. Obtain the appropriate KE EMu server version bundle via the KE EMu Server hyperlink above.
   Save the release bundle file in the ~emu/clientname/install temporary directory.
5. Extract the client release by using the name of the actual release file.
   Enter sh  emu-clientname-yymmddv.sh
   The KE EMu release will be extracted.
6. Enter .  ./.profile
7. Enter bin/emuinstall  -u  clientname. The KE EMu installation script will commence.
8. Enter cd  ~emu/clientname
9. Enter cp  .profile.parent  ../.profile
10. Enter .  ../.profile
11. Enter client  clientname
12. Enter cd  ~emu/clientname/data
13. Enter texupgrade  *
    Each table will be upgraded to Texpress 8.3 format. The upgrade may take some time as all tables need to be re-indexed.
14. Enter cd  ~emu/clientname
15. Enter emubldinstall
16. Enter emubldlinks
17. Removal of the temporary directory (and its contents) is recommended:
    Enter \rm  -fr  install
18. Enter upgrade-4-0-01
    The client will now be upgraded to EMu 4.0. If you are upgrading from a version prior to EMu 3.2.04, you must run the upgrade scripts for all versions after the old version before running the EMu 4.0 upgrade.
19. Enter upgrade-4-0-01.audit
    The audit upgrade removes empty values from existing audit trail records.
20. Enter upgrade-4-0-01.georef
    The geo-referencing upgrade is required by all clients who use either Sites or Collection Events to hold geo-referencing data (that is, latitude and longitude data).
    As the upgrade proceeds, keep track of which table (esites or ecollectionevents) has data manipulated. Replace dbname with the table upgraded in the reloaddata instruction (see point 22). If ecollectionevents and esites are not present the next two instructions may be skipped.
21. Enter emureindex  ecollectionevents  esites
22. Enter reloaddata  dbname
23. Enter EDITOR=vi  crontab  -e
    Add the following entries:
    #
    #  Optimise range buckets
    #
    0 21 1 * * ~emu/clientname/bin/emurun emurangeupdate -r 2>&1 | ~emu/clientname/bin/emurun emulogger -t "KE EMu Range Update Report" reindex
    #
    #  Run periodic tasks
    #
    30 * * * * ~emu/clientname/bin/emurun emuperiodic hourly 2>&1 | ~emu/clientname/bin/emurun emulogger -t "KE EMu Periodic Tasks Report" periodic
    0 6 * * * ~emu/clientname/bin/emurun emuperiodic daily 2>&1 | ~emu/clientname/bin/emurun emulogger -t "KE EMu Periodic Tasks Report" periodic
    30 6 * * 0 ~emu/clientname/bin/emurun emuperiodic weekly 2>&1 | ~emu/clientname/bin/emurun emulogger -t "KE EMu Periodic Tasks Report" periodic
    0 7 1 * * ~emu/clientname/bin/emurun emuperiodic monthly 2>&1 | ~emu/clientname/bin/emurun emulogger -t "KE EMu Periodic Tasks Report" periodic
    
    All cron commands must be entered on one line (even if they appear wrapped on the screen)! The start times of commands may need to be varied to fit in with existing maintenance jobs.

Starting EMu services

1. Enter emuload  start
2. Enter emuweb  start

Record Session

The recording of the upgrade session can now be terminated.

1. Enter exit

The session output is available in /tmp/output-4-0-01.

Upgrading EMu Client

When upgrading to EMu 4.0 the Windows client should be upgraded on each individual machine. The client upgrade installs new DLLs on each individual machine required by the upgrade to Crystal Reports XI Release 2. To upgrade the EMu Client follow the Installing EMu Client notes.