Unix Install Routine - Functional Specification

Description

Starting from InterBase V6.0, we'll ship a UNIX-based InterBase kit called "InterBase Client Only" (don't be confused with the InterClient product). The contents of this kit are as follows (might be slightly rearranged later to incorporate the deprecated files, replication, tools etc.) :

HP-UX ( InterBase60_Client_HUS.tar )
interbase/bin/gbak
interbase/bin/gdef
interbase/bin/gfix
interbase/bin/gpre
interbase/bin/iblicense
interbase/bin/isql
interbase/bin/qli
interbase/doc/*
interbase/examples/*       (Note: *.gdb files are not included)
interbase/include/*
interbase/install.ksh         (Note: new install script)
interbase/interbase.msg
interbase/lib/
interbase/lib/gds.sl
interbase/license.txt
interbase/install.txt

Solaris (interbase/* -- package format software)

The same set of the files as for the HP-UX platform (NOTE: library file names are different).

In order for us to install both "InterBase Client and the Server" and the "InterBase Client Only" kits, we need to change the install script accordingly.

Also, we additionally ship free software (InterClient and Acrobat Reader) that a customer may also want to install. Currently the installation of that additional software is a completely separate action for  the customer. To simplify the overall installation process we'll provide the "setup.ksh" script that is 'similar' to the Setup Launcher on the NT platform. The setup script is a menu of different software the customer can install from the CD-ROM.

User Interface/Usability

1. setup.ksh

In order to install software from the CD-ROM, the customer will need to do following:
 

  • Log in to the machine as root.
  • Mount the CD-ROM  on any existing empty directory on the system.
  • Run the "setup.ksh" setup script

The setup.ksh script brings up the following menu:

  • 1. Install InterBase Client and Server software
    2. Install InterBase Client Only software
    3. Install InterClient JDBC software
    4. Install Adobe Acrobat Reader software
    5. Exit

    Enter selection. (default 1) [1-5] :

Depending on the selection, the setup script either starts installation or exits. You can only install one element at a time. When the installation of that element is complete, the menu screen reappears and an other element can be chosen for installation.

If one of the Install options is chosen then the setup script prints out the corresponding message, starts the installation, checks out the return status (when the install is finished), and depending on the return value, prints out one of the following messages:

  • The installation completed successfully
  • *** The installation failed
  • *** The installation is not complete

In case of the "Install InterBase Client and Server software" the setup script does following:

  • Print out following message "Starting InterBase Client and Server Install, please wait..."

HP-UX

  • cd /tmp
  • Extract "install.ksh" install script from the CD_ROM_DIR/InterBase60_ClientServer_HUS.tar file
  • Run install.ksh script
  • Depending on the return status, print out the corresponding message

Solaris

  • pkgadd -d LocationAndNameOfThePackage (TBD)
  • Depending on the return status, print out the corresponding message

In case of the "Install InterBase Client Only software" the setup script does following:

  • Print out following message "Starting InterBase Client Only Install, please wait..."
  • HP-UX
  • cd /tmp
  • Extract "install.ksh" install script from the CD_ROM_DIR/InterBase60_Client_HUS.tar file
  • Run install.ksh script
  • Depending on the return status, print out the corresponding message
  • Solaris
  • pkgadd -d LocationAndNameOfThePackage (TBD)
  • Depending on the return status, print out the corresponding message

In case of "Install InterClient software" the setup scripts does following:

Print out following message "Starting InterClient Install, please wait..."

  • cd /tmp
  • Extract files from the CD_ROM_DIR/InterClient*.tar file
  • cd /interclient_install_temp_dir
  • Run install.sh script
  • Depending on the return status, print out the corresponding message

In case of "Install Adobe Acrobat Reader software" the setup script does following:

Print out following message "Starting Adobe Acrobat Reader Install, please wait..."

  • Run CD_ROM_DIR/Adobe/INSTALL script
  • Depending on the return status, print out the corresponding message

2. install.ksh

This script is used to install "InterBase Client and Server software" or "InterBase Client Only software".

Syntax: install.ksh [ -s | -c ] AbsolutePathNameOfTheArchiveFile,

  • -s install server and client
  • -c install client only

If neither '-s' nor '-c' option is specified then the install script checks for the interbase/bin/ibserver file in the tar file. If the file exists then the install script installs "InterBase Client and Server software" otherwise it installs "InterBase Client Only software".

The Install script may return following status codes:
 

  • 0 - completed successfully
  • 1 - completed with errors
  • 2 - installation is not complete

Install script logs all the output to the /tmp/ibinstall.log log file (see example here ). If the installation is completed successfully then the log file is moved to the /usr/interbase/ibinstall.log. If an old one exists then it is renamed to /usr/interbase/ibinstall.log.old

When install script starts, it checks for the IBINSTALL environment variable. If the variable is defined then it is used as a default install directory. If the variable is not defined then install script asks to specify the install directory (HP-UX only):

Enter the absolute path name of the install directory
[/opt] :

Notes:

  • The default install directory has been changed from /usr to /opt to be consistent with OS's conventions.
  • The install script automatically creates "interbase" subdirectory so you don't have to specify it as a part of the install directory path

During installation, the following messages may appear:

messages requesting input info

Directory "SomeDir" does not exist.
        Do you want to create it now? (default: y) [y, n, q] :
Directory "SomeDir/interbase" already exists.
        Do you want to continue? (default: n) [y, n, q] :
Please enter the license certificate id:
Please enter the license certificate key:

info messages

Extracting files...
Updating access permissions...
Creating symbolic links...
Updating service name database...
Updating configuration file for inetd...
Creating the ibmgr shell script...
Creating the license file...
Creating a 90-day evaluation license...
We need the license key which matches your license id.
Creating the license...
Creating /usr/interbase symbolic link...
*** Install completed with errors ***
Install completed successfully
Install is not complete.
        You may run the install at a later time to complete the installation.
Install log can be found at SomeLogFile

error and warning messages

ERROR: Invalid response, expected "y", "n" or "q"
ERROR: The specified pathname "PathName" is not the absolute. Please try again.
ERROR: No permissions to perform operation. Log in as root and try again.
ERROR: Detected another Interbase server running on the system.  Shutdown the InterBase server and try again.
ERROR: too many parameters.

  • Usage: install.ksh [-c | -s] AbsolutePathOfTheTarFile

ERROR: Syntax error, expected archive file.

  • Usage: install.ksh [-c | -s] AbsolutePathOfTheTarFile

ERROR: File "File" not found.
ERROR: Can't extract the files from the archive.
ERROR: No license created. Please see the release notes to create a license file.
WARNING: Can't create symbolic link "/usr/interbase"
WARNING: "/usr/interbase" already exists
WARNING: You should create a symbolic link

from "/usr/interbase"
to "InstallDirectory"
before using InterBase software.

3. Example

Here is an example for the "InterBase Client and Server software" installation (HP-UX).
NOTE: example is based on InterBase V5.5 tar file.

Dialog screen

# mount /dev/dsk/c1t2d0 /usr/gds.install
# /usr/gds.install/setup.ksh

        1. Install InterBase Client and Server software
        2. Install InterBase Client Only software
        3. Install InterClient JDBC software
        4. Install Adobe Acrobat Reader software
        5. Exit

Enter selection. (default 1) [1-5] :

Starting InterBase Client and Server Install, please wait...

Enter the absolute path name of the install directory
[/opt] : /opt/test

Directory "/opt/test/interbase" already exists.
Do you want to continue? (default: n) [y, n, q] : n

Enter the absolute path name of the install directory
[/opt] : /opt/newtest

Directory "/opt/newtest" does not exist.
Do you want to create it now? (default: y) [y, n, q] : y

Extracting files... Done
Updating access permissions... Done
Creating symbolic links... Done
Updating service name database... Done
Updating configuration file for inetd... Done
Creating the ibmgr shell script... Done

Please enter the license certificate id: eval
Creating a 90-day evaluation license...
The operation was completed successfully.  Please restart the server for the
changes to take effect. (NOTE: the message is  output of iblicense utility so it is not under the install script control)
Creating /usr/interbase symbolic link... Done

Install completed successfully
Install log can be found at /opt/newtest/interbase/ibinstall.log
The installation completed successfully

        1. Install InterBase Client and Server software
        2. Install InterBase Client Only software
        3. Install InterClient JDBC software
        4. Install Adobe Acrobat Reader software
        5. Exit

Enter selection. (default 1) [1-5] : 5
#umount /usr/gds.install
#

Log File

Old /tmp/ibinstall.log moved to /tmp/ibinstall.log.old

***********************************************
InterBase Install in progress
Wed Nov  4 12:36:47 PST 1998
***********************************************

Enter the absolute path name of the install directory
[/opt] : /opt/test
Directory "/opt/test/interbase" already exists.
Do you want to continue? (default: n) [y, n, q] : n
Enter the absolute path name of the install directory
[/opt] : /opt/newtest
Directory "/opt/newtest" does not exist.
Do you want to create it now? (default: y) [y, n, q] : y
mkdir -p /opt/newtest
----------------------------

Extracting files
x interbase/bin/ibserver, 1821142 bytes, 3557 tape blocks
x interbase/bin/fred, 230049 bytes, 450 tape blocks
x interbase/bin/gbak, 197024 bytes, 385 tape blocks
x interbase/bin/gdef, 271052 bytes, 530 tape blocks
x interbase/bin/gds_lock_print, 115024 bytes, 225 tape blocks
x interbase/bin/ibguard, 20538 bytes, 41 tape blocks
x interbase/bin/gfix, 61606 bytes, 121 tape blocks
x interbase/bin/gpre, 788675 bytes, 1541 tape blocks
x interbase/bin/gsec, 32847 bytes, 65 tape blocks
x interbase/bin/gsplit, 32850 bytes, 65 tape blocks
x interbase/bin/gstat, 41051 bytes, 81 tape blocks
x interbase/bin/ibmgr.bin, 32852 bytes, 65 tape blocks
x interbase/bin/isc4.gbak, 3072 bytes, 6 tape blocks
x interbase/bin/iblicense, 123247 bytes, 241 tape blocks
x interbase/bin/isql, 180589 bytes, 353 tape blocks
x interbase/bin/qli, 575190 bytes, 1124 tape blocks
x interbase/doc/APIGUIDE/APIGUIDE.PDF, 3296862 bytes, 6440 tape blocks
x interbase/doc/DATADEF/DATADEF.PDF, 2289493 bytes, 4472 tape blocks
x interbase/doc/IB5INDEX/MORGUE/ACROCAT.CAT, 3 bytes, 1 tape blocks
x interbase/doc/IB5INDEX/PARTS/00000000.DID, 795648 bytes, 1554 tape blocks
x interbase/doc/IB5INDEX/PARTS/00000001.DDD, 16384 bytes, 32 tape blocks
x interbase/doc/IB5INDEX/PARTS/00000001.DID, 844800 bytes, 1650 tape blocks
x interbase/doc/IB5INDEX/PARTS/00000000.DDD, 16384 bytes, 32 tape blocks
x interbase/doc/IB5INDEX/PDD/00000002.PDD, 7168 bytes, 14 tape blocks
x interbase/doc/IB5INDEX/PDD/00000001.PDD, 7168 bytes, 14 tape blocks
x interbase/doc/IB5INDEX/STYLE/STYLE.DID, 768 bytes, 2 tape blocks
x interbase/doc/IB5INDEX/STYLE/STYLE.PDD, 373 bytes, 1 tape blocks
x interbase/doc/IB5INDEX/STYLE/STYLE.PLC, 1767 bytes, 4 tape blocks
x interbase/doc/IB5INDEX/STYLE/STYLE.STP, 31 bytes, 1 tape blocks
x interbase/doc/IB5INDEX/STYLE/STYLE.WLD, 561 bytes, 2 tape blocks
x interbase/doc/IB5INDEX/STYLE/STYLE.DDD, 1914 bytes, 4 tape blocks
x interbase/doc/IB5INDEX/TEMP/ACROCAT.CAT, 3 bytes, 1 tape blocks
x interbase/doc/IB5INDEX/TEMP/T91C05F8.ABT, 1132 bytes, 3 tape blocks
x interbase/doc/IB5INDEX/TRANS/DATA.TRN, 99 bytes, 1 tape blocks
x interbase/doc/IB5INDEX/TRANS/ACROCAT.CAT, 3 bytes, 1 tape blocks
x interbase/doc/IB5INDEX/WORK/ACROCAT.CAT, 3 bytes, 1 tape blocks
x interbase/doc/IB5INDEX/ASSISTS/00000002.WLD, 151552 bytes, 296 tape blocks
x interbase/doc/IB5INDEX/ASSISTS/00000005.ABT, 1131 bytes, 3 tape blocks
x interbase/doc/IB5INDEX/ASSISTS/00000006.ABT, 1132 bytes, 3 tape blocks
x interbase/doc/IB5INDEX/ASSISTS/ACROCAT.CAT, 3 bytes, 1 tape blocks
x interbase/doc/IB5INDEX/ASSISTS/00000001.WLD, 143360 bytes, 280 tape blocks
x interbase/doc/IB5INDEX/TOPICIDX/ACROCAT.CAT, 3 bytes, 1 tape blocks
x interbase/doc/IB5INDEX.PDX, 1071 bytes, 3 tape blocks
x interbase/doc/LANGREF/LANGREF.PDF, 2684361 bytes, 5243 tape blocks
x interbase/doc/OPGUIDE/OPGUIDE.PDF, 2473873 bytes, 4832 tape blocks
x interbase/doc/PROGGD/PROGGD.PDF, 2910297 bytes, 5685 tape blocks
x interbase/doc/TUTORIAL/INSERTS.SQL, 37142 bytes, 73 tape blocks
x interbase/doc/TUTORIAL/PROCS.SQL, 8450 bytes, 17 tape blocks
x interbase/doc/TUTORIAL/TABLES.SQL, 9584 bytes, 19 tape blocks
x interbase/doc/TUTORIAL/UPDATES.SQL, 2626 bytes, 6 tape blocks
x interbase/doc/TUTORIAL/DOMAINS.SQL, 1674 bytes, 4 tape blocks
x interbase/doc/TUTORIAL/TUTORIAL.PDF, 762121 bytes, 1489 tape blocks
x interbase/doc/TUTORIAL/TRIGGERS.SQL, 1792 bytes, 4 tape blocks
x interbase/examples/README, 4316 bytes, 9 tape blocks
x interbase/examples/align.h, 915 bytes, 2 tape blocks
x interbase/examples/api1.c, 3769 bytes, 8 tape blocks
x interbase/examples/api10.c, 5421 bytes, 11 tape blocks
x interbase/examples/api11.c, 5436 bytes, 11 tape blocks
x interbase/examples/api12.c, 10300 bytes, 21 tape blocks
x interbase/examples/api13.c, 5105 bytes, 10 tape blocks
x interbase/examples/api14.e, 5595 bytes, 11 tape blocks
x interbase/examples/api15.c, 6114 bytes, 12 tape blocks
x interbase/examples/api16.c, 6143 bytes, 12 tape blocks
x interbase/examples/api16t.c, 4469 bytes, 9 tape blocks
x interbase/examples/api2.c, 4215 bytes, 9 tape blocks
x interbase/examples/api3.c, 3953 bytes, 8 tape blocks
x interbase/examples/api4.c, 3960 bytes, 8 tape blocks
x interbase/examples/api5.c, 3156 bytes, 7 tape blocks
x interbase/examples/api6.c, 6723 bytes, 14 tape blocks
x interbase/examples/api7.c, 4901 bytes, 10 tape blocks
x interbase/examples/api8.c, 4228 bytes, 9 tape blocks
x interbase/examples/api9.c, 4350 bytes, 9 tape blocks
x interbase/examples/api9f.c, 7005 bytes, 14 tape blocks
x interbase/examples/api9f.sql, 295 bytes, 1 tape blocks
x interbase/examples/apifull.c, 11242 bytes, 22 tape blocks
x interbase/examples/dyn1.e, 2340 bytes, 5 tape blocks
x interbase/examples/dyn2.e, 2950 bytes, 6 tape blocks
x interbase/examples/dyn3.e, 2670 bytes, 6 tape blocks
x interbase/examples/dyn4.e, 3020 bytes, 6 tape blocks
x interbase/examples/dyn5.e, 2376 bytes, 5 tape blocks
x interbase/examples/dynfull.e, 6384 bytes, 13 tape blocks
x interbase/examples/employe2.sql, 1331 bytes, 3 tape blocks
x interbase/examples/employee.gbk, 71680 bytes, 140 tape blocks
x interbase/examples/employee.gdb, 472064 bytes, 922 tape blocks
x interbase/examples/example.h, 402 bytes, 1 tape blocks
x interbase/examples/ib_udf.sql, 14958 bytes, 30 tape blocks
x interbase/examples/intlemp.gbk, 79872 bytes, 156 tape blocks
x interbase/examples/intlemp.gdb, 493568 bytes, 964 tape blocks
x interbase/examples/makefile, 6733 bytes, 14 tape blocks
x interbase/examples/stat1.e, 1456 bytes, 3 tape blocks
x interbase/examples/stat10.e, 3221 bytes, 7 tape blocks
x interbase/examples/stat11.e, 3090 bytes, 7 tape blocks
x interbase/examples/stat12.e, 2510 bytes, 5 tape blocks
x interbase/examples/stat12t.e, 1436 bytes, 3 tape blocks
x interbase/examples/stat2.e, 1300 bytes, 3 tape blocks
x interbase/examples/stat3.e, 1765 bytes, 4 tape blocks
x interbase/examples/stat4.e, 2798 bytes, 6 tape blocks
x interbase/examples/stat5.e, 2085 bytes, 5 tape blocks
x interbase/examples/stat6.e, 1972 bytes, 4 tape blocks
x interbase/examples/stat7.e, 1799 bytes, 4 tape blocks
x interbase/examples/stat8.e, 2527 bytes, 5 tape blocks
x interbase/examples/stat9.e, 3014 bytes, 6 tape blocks
x interbase/examples/udf.sql, 2477 bytes, 5 tape blocks
x interbase/examples/udflib.c, 11069 bytes, 22 tape blocks
x interbase/help/help.gbak, 101888 bytes, 199 tape blocks
x interbase/help/help.gdb, 391168 bytes, 764 tape blocks
x interbase/include/iberror.h, 26495 bytes, 52 tape blocks
x interbase/include/gds.h, 198213 bytes, 388 tape blocks
x interbase/include/gds.hxx, 49271 bytes, 97 tape blocks
x interbase/include/perf.h, 1889 bytes, 4 tape blocks
x interbase/include/ibase.h, 79847 bytes, 156 tape blocks
x interbase/include/gds.f, 157972 bytes, 309 tape blocks
x interbase/include/interbase.ada, 248907 bytes, 487 tape blocks
x interbase/include/ib_util.h, 293 bytes, 1 tape blocks
x interbase/install, 7204 bytes, 15 tape blocks
x interbase/interbase.msg, 124476 bytes, 244 tape blocks
x interbase/isc4.gdb, 248832 bytes, 486 tape blocks
x interbase/isc_config, 185 bytes, 1 tape blocks
x interbase/isc_ins_hlp.dat, 2069 bytes, 5 tape blocks
x interbase/lib/gds.sl, 452256 bytes, 884 tape blocks
x interbase/lib/ib_util.sl, 12300 bytes, 25 tape blocks
x interbase/lib/gds_pyxis.a, 248148 bytes, 485 tape blocks
x interbase/lib/gdsintl, 680469 bytes, 1330 tape blocks
x interbase/lib/ib_udf, 24680 bytes, 49 tape blocks
x interbase/license.txt, 18144 bytes, 36 tape blocks
x interbase/install.txt, 5139 bytes, 11 tape blocks
x interbase/services.isc, 80 bytes, 1 tape blocks
x interbase/ReleaseNotes.pdf, 465150 bytes, 909 tape blocks
x interbase/install.ksh, 16312 bytes, 32 tape blocks
----------------------------

Updating access permissions
chmod 777 /opt/newtest/interbase
chmod uog=rw /opt/newtest/interbase/isc4.gdb
chmod uog=rw /opt/newtest/interbase/help/help.gdb
chmod uog=rw /opt/newtest/interbase/examples/employee.gdb
chmod uog=rw /opt/newtest/interbase/examples/intlemp.gdb
chmod 4755 /opt/newtest/interbase/bin/gstat
----------------------------

Creating symbolic links
rm -f /usr/include/gds.h
ln -s /opt/newtest/interbase/include/gds.h /usr/include/gds.h
rm -f /usr/include/ibase.h
ln -s /opt/newtest/interbase/include/ibase.h /usr/include/ibase.h
rm -f /usr/include/iberror.h
ln -s /opt/newtest/interbase/include/iberror.h /usr/include/iberror.h
rm -f /usr/include/ib_util.h
ln -s /opt/newtest/interbase/include/ib_util.h /usr/include/ib_util.h
rm -f /usr/lib/libgds.sl
ln -s /opt/newtest/interbase/lib/gds.sl /usr/lib/libgds.sl
rm -f /usr/lib/libgds_pyxis.a
ln -s /opt/newtest/interbase/lib/gds_pyxis.a /usr/lib/libgds_pyxis.a
rm -f /usr/lib/libib_util.sl
ln -s /opt/newtest/interbase/lib/ib_util.sl /usr/lib/libib_util.sl
----------------------------

Updating service name database
cat /etc/services /opt/newtest/interbase/services.isc > services
mv services /etc/services
----------------------------

Updating configuration file for inetd
cat /etc/inetd.conf | grep -v gds_db > inetd.conf
mv inetd.conf /etc/inetd.conf
----------------------------

Creating the ibmgr shell script
----------------------------

Creating the license file

Please enter the license certificate id: Creating a 90-day evaluation license...
Creating /usr/interbase symbolic link
ln -s /opt/newtest/interbase /usr/interbase
----------------------------

Install completed successfully

Requirements and Constraints

The InrerBase 6.0 "setup.ksh" script will support HP-UX and Solaris platforms only and is placed on the top level of the CD-ROM tree. The setup script depends on the CD-ROM structure so it most be updated in case if the structure (especially file names) is changed.

The setup script makes the following assumptions:

Naming conventions for the software on the CD-ROM:
 

HP-UX

Solaris

IB Client and Server software

InterBase*_ClientServer_HUS.tar

TBD

IB Client Only software

InterBase*_Client_HUS.tar

TBD

Adobe Acrobat Reader software

Adobe/*

 Adobe/*

InterClient software

InterClient*.tar

InterClient*.tar

Naming convention for the install scripts:

HP-UX

Solaris

IB Client and Server Install

install.ksh

N/A

IB Client Only software

install.ksh

N/A

Adobe Acrobat Reader software

Adobe/INSTALL

Adobe/INSTALL

InterClient software

install.sh

install.sh

Migration Issues

  • The new installation process on UNIX is slightly different from what it used to be before. The Operations Guide should be updated accordingly.