JJON's StorY

PURPOSE
-------

Provide relinking instructions for Oracle Database software
on UNIX platforms.

 
SCOPE & APPLICATION
-------------------

Anyone who maintains Oracle RDBMS software on a UNIX platform.


Relinking Oracle
================

Background:
Applications for UNIX are generally not distributed as complete executables.  
Oracle, like many application vendors who create products for UNIX, distribute 
individual object files, library archives of object files, and some source 
files which then get "relinked" at the operating system level during 
installation to create usable executables.  This guarantees a reliable
integration with functions provided by the OS system libraries.

Relinking occurs automatically under these circumstances:

 - An Oracle product has been installed with an Oracle provided installer.
 - An Oracle patch set has been applied via an Oracle provided installer.  

The following information has been added to the 'Certify' section of Metalink:

   General Notes For Oracle Database - Enterprise Edition:
   O/S Information: 
   The vendors guarantee operating system binary compatibility; therefore, no 
   reinstall or relink of the Oracle software is required when upgrading these
   operating systems unless specifically stated otherwise.

Relinking Oracle manually is suggested under the following circumstances
(even though the OS vendor may not require it):

 - An OS upgrade has occurred.
 - A change has been made to the OS system libraries.  This can occur during 
   the application of an OS patch.
 - A new install failed during the relinking phase.
 - Individual Oracle executables core dump during initial startup.
 - An individual Oracle patch has been applied (however, explicit relink 
   instructions are usually either included in the README or integrated into 
   the patch install script) 

Customers who want to (or have been advised to) manually relink should follow 
the procedure below.

[Step 1] Log into the UNIX system as the Oracle software owner
==============================================================================
Typically this is the user 'oracle'.
 

[STEP 2] Verify that your $ORACLE_HOME is set correctly:
===============================================================================
For all Oracle Versions and Platforms, perform this basic environment check 
first:
 
 % cd $ORACLE_HOME
 % pwd    

 ...Doing this will ensure that $ORACLE_HOME is set correctly in your current 
    environment.
 

[Step 3] Verify and/or Configure the UNIX Environment for Proper Relinking:
===============================================================================
For all Oracle Versions and UNIX Platforms:
 The Platform specific environment variables LIBPATH, LD_LIBRARY_PATH, & 
 SHLIB_PATH typically are already set to include system library locations like
 '/usr/lib'.  In most cases, you need only check what they are set to first, 
 then add the $ORACLE_HOME/lib directory to them where appropriate.
 i.e.:  % setenv LD_LIBRARY_PATH ${ORACLE_HOME}/lib:${LD_LIBRARY_PATH}
 (see Note 131207.1 How to Set UNIX Environment Variables for help with 
 setting UNIX environment variables)

If on AIX with:
--------------
    
    NOTE: Before relinking, after stopping all required processes, issue the
    following as root to detach all files from memory that are not attached 
    to an active process:

         # /usr/sbin/slibclean

    Oracle 7.3.X:
       - Set LIBPATH to include $ORACLE_HOME/lib
    
    Oracle 8.0.X:
       - Set LIBPATH to include $ORACLE_HOME/lib
       - Set LD_LIBRARY_PATH to include $ORACLE_HOME/lib and 
         $ORACLE_HOME/network/lib (Required when using Oracle products that 
         use Java)
       - Set LINK_CNTRL to L_PTHREADS_D7 if using AIX 4.3. ('oslevel' verifies 
         OS version)
    
    Oracle 8.1.X, 9.X.X, 10.X.X or 11.x.x:
       - For 8.1.5, set LINK_CNTRL to L_PTHREADS_D7
       - If not 8.1.5, ensure that LINK_CNTRL is not set
       - Set LIBPATH to include $ORACLE_HOME/lib
      

If on DATA GENERAL AVIION (DG) with:
-----------------------------------

    Oracle 7.3.X or 8.0.X:
       - Set LD_LIBRARY_PATH to include $ORACLE_HOME/lib
       - ensure TARGET_BINARY_INTERFACE is unset
    
    Oracle 8.1.X:
       - Set LD_LIBRARY_PATH to include 
         $ORACLE_HOME/lib:$ORACLE_HOME/JRE/lib/PentiumPro/native_threads

If on HP-UX with:
----------------

    Oracle 7.3.X, 8.0.X, 8.1.X;
       - Set SHLIB_PATH to $ORACLE_HOME/lib
       If using 64bit 8i Oracle, also
       - Set LD_LIBRARY_PATH to $ORACLE_HOME/lib64
       - ensure LPATH is unset
 
    Oracle 9.X.X, 10.X.X or 11.x.x;
       - ensure LPATH is unset

If on NCR with:
--------------

    Oracle 7.3.X, 8.0.X or 8.1.X:
       - Set LD_LIBRARY_PATH to include $ORACLE_HOME/lib:/usr/ccs/lib

If on SCO UNIXware with:
-----------------------

    Oracle 7.3.X or 8.0.X:
       - Set LD_LIBRARY_PATH to include $ORACLE_HOME/lib
    
    Oracle 8.1.X:
       - Set LD_LIBRARY_PATH to include 
         $ORACLE_HOME/lib:$ORACLE_HOME/JRE/lib/x86at/native_threads

If on SGI with:
--------------

    32bit Oracle 7.3.X or 8.0.X:
       - Set LD_LIBRARY_PATH to include $ORACLE_HOME/lib
       - Set SGI_ABI to -32  

    64bit Oracle 8.0.X or 8.1.X (8i is only available in 64bit):
       - Set LD_LIBRARY_PATH to include $ORACLE_HOME/lib
       - Set SGI_ABI to -64
       - If one does not already exist, create the file compiler.defaults and 
         set the COMPILER_DEFAULTS_PATH variable:

     In the Oracle software owner's $HOME directory, create a file called
     'compiler.defaults':
  
        % cd $HOME
        % echo "-DEFAULT:abi=64:isa=mips3:proc=r10k" > compiler.defaults

     Then set the environment variable COMPILER_DEFAULTS_PATH to point to the
     $HOME directory.
  
        % setenv COMPILER_DEFAULTS_PATH $HOME
  
     If this is not set, relinking will fail because the compiler defaults to
     MIPS4 objects although Oracle requires MIPS3.
       - Set LD_LIBRARY64_PATH to include the $ORACLE_HOME/lib and the 
         $ORACLE_HOME/javavm/admin directories. 
       - Set LD_LIBRARYN32_PATH to include the $ORACLE_HOME/lib32 directory. 
         NOTE: LD_LIBRARY64_PATH & LD_LIBRARYN32_PATH must be undefined when 
         installing software with Oracle Universal Installer. 

If on SOLARIS (Sparc or Intel) with:
------------------------------------

    Oracle 7.3.X, 8.0.X, or 8.1.X:
       - Ensure that /usr/ccs/bin is before /usr/ucb in $PATH  
         % which ld   ....should return '/usr/ccs/bin/ld'

       If using 32bit(pre 9i) Oracle, 
       - Set LD_LIBRARY_PATH=$ORACLE_HOME/lib

       If using 64bit(pre 9i) Oracle, 
       - Set LD_LIBRARY_PATH=$ORACLE_HOME/lib
       - Set LD_LIBRARY_PATH_64=$ORACLE_HOME/lib64

    Oracle 9.X.X or higher:
       - LD_LIBRARY_PATH & LD_LIBRARY_PATH_64 do not need to be set to include
         a reference to $ORACLE_HOME/lib or $ORACLE_HOME/lib64 for a generic database
         software installation. 
         (However they should not contain a reference to the ORACLE_HOME of another Oracle version)

If on Digital/Tru64, IBM/Sequent PTX, Linux or any other UNIX Platform not 
mentioned above with:
------------------------------------------------------------------------------

    Oracle 7.3.X, 8.0.X, 8.1.X, 9.X.X, 10.X.X or 11.x.x:
       - Set LD_LIBRARY_PATH to include $ORACLE_HOME/lib


[Step 4] For all Oracle Versions and UNIX Platforms: 
===============================================================================
Verify that you performed Step 2 correctly:

 % env|pg  ....make sure that you see the correct absolute path for 
   $ORACLE_HOME in the variable definitions.
 

[Step 5] For all Oracle Versions and UNIX Platforms: 
===============================================================================
Verify umask is set correctly:

 % umask

This must return 022.  If it does not, set umask to 022.

 % umask 022
 % umask

[Step 6] Run the OS Commands to Relink Oracle: 
===============================================================================
Important Note:  Before relinking Oracle, shut down both the database and the 
                 listener.
Important Note:  The following commands will output a lot of text to your 
                 session window.  To capture this output for upload to support,
                 redirect the output to a file.
Important Note:  If relinking a client installation, it's expected that some 
                 aspects of the following commands will fail if the components
                 were not originally installed.

For all UNIX platforms:

Oracle 7.3.x 
------------
 For executables:  oracle, exp, imp, sqlldr, tkprof 

      % cd $ORACLE_HOME/rdbms/lib 
      % make -f ins_rdbms.mk install

 For executables:  svrmgrl, svrmgrm 

      % cd $ORACLE_HOME/svrmgr/lib 
      % make -f ins_svrmgr.mk linstall minstall      <- linstall is for svrmgrl, 
                                                        minstall is for svrmgrm

 For executables:  sqlplus 

      % cd $ORACLE_HOME/sqlplus/lib 
      % make -f ins_sqlplus.mk install

 For executables:  dbsnmp, oemevent, oratclsh 

      % cd $ORACLE_HOME/network/lib 
      % make -f ins_agent.mk install

 For executables:  names, namesctl 

      % cd $ORACLE_HOME/network/lib 
      % make -f ins_names.mk install

 For executables:  tnslsnr, lsnrctl, tnsping, csmnl, trceval, trcroute 

      % cd $ORACLE_HOME/network/lib 
      % make -f ins_network.mk install


Oracle 8.0.x 
------------
 For executables:  oracle, exp, imp, sqlldr, tkprof, mig, dbv, orapwd, rman, 
                   svrmgrl, ogms, ogmsctl 

      % cd $ORACLE_HOME/rdbms/lib 
      % make -f ins_rdbms.mk install

 For executables:  sqlplus 

      % cd $ORACLE_HOME/sqlplus/lib 
      % make -f ins_sqlplus.mk install

 For executables:  dbsnmp, oemevent, oratclsh, libosm.so 

      % cd $ORACLE_HOME/network/lib 
      % make -f ins_oemagent.mk install

 For executables:  tnslsnr, lsnrctl, namesctl, names, osslogin, trcasst, 
                   trcroute 

      % cd $ORACLE_HOME/network/lib 
      % make -f ins_network.mk install


Oracle 8.1.X, 9.X.X, 10.X.X or 11.x.x
-------------------------------------
  *** NEW IN 8i AND ABOVE ***

   A 'relink' script is provided in the $ORACLE_HOME/bin directory.
     % cd $ORACLE_HOME/bin
     % relink      ...this will display all of the command's options.
       usage: relink <parameter>
       accepted values for parameter: all, oracle, network, client, 
       client_sharedlib, interMedia, precomp, utilities, oemagent, ldap 
  
  Note: ldap option is available only from 9i. In 8i, you would have to manually relink
  ldap.

  You can relink most of the executables associated with an Oracle Server Installation
  by running the following command:
     % relink all    
  This will not relink every single executable Oracle provides(you can
  discern which executables were relinked by checking their timestamp with
  'ls -l' in the $ORACLE_HOME/bin directory).  However, 'relink all' will 
  recreate the shared libraries that most executables rely on and thereby
  resolve most issues that require a proper relink. 

 
 -or-

  Since the 'relink' command merely calls the traditional 'make' commands, you 
  still have the option of running the 'make' commands independently:

 For executables:  oracle, exp, imp, sqlldr, tkprof, mig, dbv, orapwd, rman, 
                   svrmgrl, ogms, ogmsctl 

      % cd $ORACLE_HOME/rdbms/lib 
      % make -f ins_rdbms.mk install

      NOTE: After relinking the oracle executable, make sure that the 
      permissions on the executable are 6751 (-rwsr-s--x). If they are
      not, run the following command as the Oracle software owner:

      % cd $ORACLE_HOME/bin
      % chmod 6751 oracle

 For executables:  sqlplus 

      % cd $ORACLE_HOME/sqlplus/lib 
      % make -f ins_sqlplus.mk install

 For executables:  isqlplus   (Oracle9i and higher versions)

      % cd $ORACLE_HOME/sqlplus/lib 
      % make -f ins_sqlplus.mk install_isqlplus

 For executables:  dbsnmp, oemevent, oratclsh 

      % cd $ORACLE_HOME/network/lib 
      % make -f ins_oemagent.mk install

      NOTE: After relinking the dbsnmp executable, it is necessary to run
      the following commands as root (so that the ownership/permissions on
      the executable are correct):

      # cd $ORACLE_HOME/bin
      # chown root dbsnmp
      # chmod 6750 dbsnmp

      @ References: Note 233559.1 and Bug 2858326

 For executables:  names, namesctl 

      % cd $ORACLE_HOME/network/lib 
      % make -f ins_names.mk install

 For executables:  osslogin, trcasst, trcroute, onrsd, tnsping 

      % cd $ORACLE_HOME/network/lib 
      % make -f ins_net_client.mk install

 For executables:  tnslsnr, lsnrctl 

      % cd $ORACLE_HOME/network/lib 
      % make -f ins_net_server.mk install

 For executables related to ldap (for example Oracle Internet Directory):

      % cd $ORACLE_HOME/ldap/lib
      % make -f ins_ldap.mk install

How to Tell if Relinking Was Successful:
===============================================================================
If relinking was successful, the make command will eventually return to the OS 
prompt without an error. There will NOT be a 'Relinking Successful' type
message.


If You Receive an Error Message During Relinking:
===============================================================================
Confirm that the message you received is an actual fatal error and not a 
warning. Relinking errors usually terminate the relinking process and contain 
verbage similar to the following:
'Fatal error', 'Ld: fatal', 'Exit Code 1'
While warnings will look similar to: 'ld: warning: option -YP appears more than
once, first setting taken' and can most often be ignored.

If you receive an error that terminates the relinking process, your first step 
should be to extract the relevant information about the error from the make 
output:

This can be broken down into three basic steps:
 1. Identify the OS utility that is returning the error.
    'ld', 'make', 'cc', 'mv', 'cp', 'ar' are common sources.
 2. Identify the type of error:
    'Permission Denied', 'Undefined Symbol', 'File Not Found' are common types.
 3. Identify the files or symbols involved.

Using the information from above as keywords, search Oracle's Metalink 
repository ( http://metaLink.oracle.com ) for previous occurrences of the same 
error. If no previous occurances are found or a solution is not provided, 
generate an iTAR that includes the complete error text.

Help setting environment variables.
==============================================================================
See Note 131207.1 How to Set UNIX Environment Variables 
for help with setting UNIX environment variables.


Relinking with Orainst:
===============================================================================
For Oracle7 & Oracle8 only, the following document illustrates how to relink 
with the 'orainst' utility:
   Note 1032747.6 HOW TO RELINK ORACLE USING THE 7.3.X INSTALLER
While 'orainst' will run the same commands as [Step 4], performing [Step 4] 
manually from a UNIX shell is the preferred approach.


RELATED DOCUMENTS
-----------------

Note 131207.1   How to Set UNIX Environment Variables
Note 109621.1   HP/UX: LD_LIBRARY_PATH and SHLIB_PATH
Note 1032747.6  HOW TO RELINK ORACLE USING THE 7.3.X INSTALLER
Bug 1337908     THE $ORACLE_HOME/BIN/RELINK SCRIPT DOES NOT RELINK EXP, IMP 
                  SQLLOADER