LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity
LDP/LDP/howto/docbook/IngresII-HOWTO.sgml

2943 lines
104 KiB
Plaintext
Raw Permalink Blame History

<!doctype article public "-//OASIS//DTD DocBook V3.1//EN">
<article id="index">
<artheader>
<title>Ingres II HOWTO</title>
<author>
<firstname>Pal</firstname>
<surname>Domokos</surname>
<affiliation>
<address><email>pal@palslib.com</email>
</address>
</affiliation>
</author>
<revhistory>
<revision>
<revnumber>V1.1.1</revnumber>
<date>2001/09/05</date>
<authorinitials>pd</authorinitials>
<revremark>E-mail changed; links to further Ingres resources.
</revremark>
</revision>
<revision>
<revnumber>V1.1</revnumber>
<date>2000/06/20</date>
<authorinitials>pd</authorinitials>
<revremark>Extended with material on the full version of Ingres II 2.0
</revremark>
</revision>
<revision>
<revnumber>V1.01</revnumber>
<date>1999/12/23</date>
<authorinitials>pd</authorinitials>
<revremark>Minor fixes</revremark>
</revision>
<revision>
<revnumber>V1.0</revnumber>
<date>1999/11/07</date>
<authorinitials>pd</authorinitials>
<revremark>Original version</revremark>
</revision>
</revhistory>
<abstract>
<para>This document helps install the <application>Ingres II Relational
Database Management System</application> on Linux.
It covers the setup of both the free Software Development Kit and the
full version of <application>Ingres</application>.
Further sections try to make it easier to start working with
<application>Ingres</application>.</para>
</abstract>
</artheader>
<sect1 id="intro" xreflabel="Introduction">
<title>Introduction</title>
<sect2 id="copy" xreflabel="Copyright">
<title>Copyright</title>
<para>Copyright &copy; 1999-2001 by Pal Domokos.</para>
<para>Please freely copy and distribute (sell or give away) this document
in any format.
It is requested that corrections and/or comments be forwarded to the document
maintainer.
You may create a derivative work and distribute it provided that you:</para>
<orderedlist>
<listitem>
<para>Send your derivative work (in the most suitable format such
as <acronym>SGML</acronym>) to the <acronym>LDP</acronym>
(<ulink url="http://www.linuxdoc.org">Linux Documentation
Project</ulink>) or the like for posting on the Internet.
If not the <acronym>LDP</acronym>, then let the
<acronym>LDP</acronym> know where it is available.</para>
</listitem>
<listitem>
<para>License the derivative work with this same license or use
<acronym>GPL</acronym>.
Include a copyright notice and at least a pointer to the license used.
</para>
</listitem>
<listitem>
<para>Give due credit to previous authors and major contributors.
If you are considering making a derived work other than a
translation, it is requested that you discuss your plans with the
current maintainer.</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="discl" xreflabel="Disclaimer">
<title>Disclaimer</title>
<para>To put it briefly: there is no warranty about the validity of any
other statement in this document.
Read and use at your own risk.</para>
<para>Furthermore, I am not an employee of Computer Associates
International and I have no official links with <acronym>CA</acronym>.
This HOWTO is <emphasis>not</emphasis> official documentation.</para>
<para>All copyrights are held by their respective owners.
Use of a term in this document should not be regarded as affecting the
validity of any trademark or service mark.</para>
</sect2>
<sect2 id="newver" xreflabel="New Versions of the HOWTO">
<title>New Versions of the HOWTO</title>
<para>The latest version of this HOWTO can always be found on the
<ulink url="http://www.linuxdoc.org">Linux Documentation Project</ulink>'s
site, in various formats:</para>
<itemizedlist>
<listitem>
<para><ulink url="http://www.linuxdoc.org/HOWTO/IngresII-HOWTO/index.html">
<acronym>HTML</acronym> - multiple pages</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://metalab.unc.edu/pub/Linux/docs/HOWTO/other-formats/html/IngresII-HOWTO-html.tar.gz">
<acronym>HTML</acronym> - multiple pages: tarred and gzipped</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://metalab.unc.edu/pub/Linux/docs/HOWTO/other-formats/html_single/IngresII-HOWTO.html">
<acronym>HTML</acronym> - single page</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://metalab.unc.edu/pub/Linux/docs/HOWTO/other-formats/pdf/IngresII-HOWTO.pdf">
<acronym>PDF</acronym></ulink></para>
</listitem>
<listitem>
<para><ulink url="http://metalab.unc.edu/pub/Linux/docs/HOWTO/other-formats/ps/IngresII-HOWTO.ps.gz">
PostScript - gzipped</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://metalab.unc.edu/pub/Linux/docs/HOWTO/IngresII-HOWTO">
Text</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://metalab.unc.edu/pub/Linux/docs/HOWTO/other-formats/docbook/IngresII-HOWTO.sgml.gz">
<acronym>SGML</acronym> (DocBook) source - gzipped</ulink></para>
</listitem>
</itemizedlist>
<para>The <acronym>LDP</acronym> has many mirrors around the world, as listed on
<ulink url="http://www.linuxdoc.org/mirrors.html">
http://www.linuxdoc.org/mirrors.html</ulink>.
Some of these mirrors may be out of date, though.
Therefore I suggest you check
<ulink url="http://www.linuxdoc.org/"><acronym>LDP</acronym>'s primary
site</ulink> for new versions.</para>
<para>HOWTOs are also bundled with most Linux distributions.
If you are reading this HOWTO from your Linux CD, also take a look at
<ulink url="http://www.linuxdoc.org/"><acronym>LDP</acronym>'s
main site</ulink> to check if a newer version exists.</para>
</sect2>
<sect2 id="credits" xreflabel="Credits">
<title>Credits</title>
<para>I would like to thank for all the feedback I have received so far.
I found especially valuable the contributions of Jorgen Heesche
(on forms-based development tools), and Gerhard Hofmann (on the
automatic startup and shutdown of Ingres).</para>
<para>Last, but not least, my thanks go to <acronym>CA</acronym> for making it
possible for me to examine the
<application>Ingres II 2.0 Enterprise Edition for Linux</application>.</para>
<para>Naturally, I continue to welcome any comments, criticisms and suggestions.
Just email me at <email>pal@palslib.com</email>.</para>
</sect2>
<sect2 id="aud" xreflabel="Audience">
<title>Audience</title>
<para>This HOWTO aims to help install <application>Ingres II</application> on
(Intel) Linux.
As always, help is useful for those who need it and can utilize
it as well.</para>
<para>Therefore:</para>
<itemizedlist>
<listitem>
<para>If you are an <application>Ingres</application> pro familiar
with Linux then you do not really need to read this HOWTO.
Skim through it though if you have time.</para>
</listitem>
<listitem>
<para>If you have no previous background in relational database
management (experience with at least one real <acronym>RDBMS</acronym>,
not some <application>dBase</application>-like file management system),
you do not know <application>UNIX</application> and have
just started using Linux, this HOWTO will not make an easy reading
for you.
Even then, I do not want to persuade you <emphasis>not</emphasis> to
try to install and use <application>Ingres</application>.
Do not give up easy!</para>
</listitem>
</itemizedlist>
<para>If you are not a novice in database management and have some
working knowledge of Linux, this HOWTO is for you!
We are not going to discuss the basics of relational database
management or <acronym>SQL</acronym> in this document, neither are we going
to elaborate on how to edit text files on Linux.
You can find as much information on these topics as you want in
numerous places.
This HOWTO is not an <application>Ingres</application> guide, either: the
<application>Ingres</application> manuals serve that purpose.</para>
<para>The objective of this HOWTO is that the reader can prepare for,
then implement the installation of <application>Ingres II</application> on
Linux, through simple and understandable steps.
It also gives starting points for basic <application>Ingres</application>
system and database administration.</para>
<para>I can only hope that the HOWTO reaches its goal.</para>
</sect2>
</sect1>
<sect1 id="ingres" xreflabel="Ingres">
<title>Ingres</title>
<para>In this section the <application>Ingres II Relational Database
Management System</application> is introduced and you come to know how
to get it.</para>
<sect2 id="univ" xreflabel="University Ingres and Commercial Ingres">
<title>University Ingres and Commercial Ingres</title>
<para>Let us start with an important fact: there are two different types
of <application>Ingres</application>.
The original one, which was designed and developed in the seventies by a
research group led by Michael Stonebraker at the University of California,
Berkeley, was the first open source relational database management system:
it was free to use and distribute, source code included.
In fact, it <emphasis>is</emphasis> still free software, although its
development stopped in 1989.
Its last version (version 8.9) made it into some Linux distributions as well.
If you are interested in it, you can download it from, say, the SuSE site.
The packages are:</para>
<itemizedlist>
<listitem>
<para><ulink url="ftp://ftp.suse.com/pub/suse/i386/current/suse/ap1/ingres.rpm">
The main software</ulink></para>
</listitem>
<listitem>
<para><ulink url="ftp://ftp.suse.com/pub/suse/i386/current/suse/ap1/ingrtool.rpm">
The tools</ulink></para>
</listitem>
</itemizedlist>
<para>In 1979, with the foundation of Relational Technology, the career
of <application>Commercial Ingres</application> started.
Since 1995 it has been distributed by Computer Associates.
Its latest version is <application>Ingres II 2.0</application>.
This HOWTO deals with the installation of this type of
<application>Ingres</application>.</para>
</sect2>
<sect2 id="sdk" xreflabel="The Software Development Kit">
<title>The Software Development Kit</title>
<para><application>Ingres</application>, being commercial software,
is not free to use.
However, <acronym>CA</acronym>, like most <acronym>RDBMS</acronym> vendors,
offers a free version of it
(the Software Development Kit) to everyone who is interested in learning
<application>Ingres</application>.
The <acronym>SDK</acronym> has two variants, one for Windows NT and one
for Linux.
These variants are not quite the same as far as the included components
are concerned.
Obviously, we are engaged in installing the <acronym>SDK</acronym> for
Linux here.
This contains the following elements:</para>
<itemizedlist>
<listitem>
<para>Intelligent DBMS: the database engine.</para>
</listitem>
<listitem>
<para>Internet Commerce Enabled (<acronym>ICE</acronym>):
<application>Ingres</application>' propriatery <acronym>CGI</acronym>
solution to connect a database to the Web.</para>
</listitem>
<listitem>
<para>Enhanced Security: the tool supporting mandatory access
control.</para>
</listitem>
<listitem>
<para>C2 Security Auditing: the possibility of C2 level auditing.</para>
</listitem>
<listitem>
<para>Terminal Monitors: forms-based and command line
<acronym>SQL</acronym> interfaces.</para>
</listitem>
<listitem>
<para>Querying and Reporting Tools: forms-based querying,
report-writing and report-running tools plus a forms editor.</para>
</listitem>
<listitem>
<para>Querying and Reporting Runtime: like the previous one,
but without the forms editor.</para>
</listitem>
<listitem>
<para>Vision Pro: integrated, forms-based development environment
with a code generator.</para>
</listitem>
<listitem>
<para>Embedded <acronym>SQL</acronym> Precompilers: precompilers for
embedding <acronym>SQL</acronym> statements in <acronym>3GL</acronym>
applications.
Supported languages are: C, C++, COBOL, and Fortran.</para>
</listitem>
</itemizedlist>
<para>You can order a free copy of the
<application>Ingres</application> <acronym>SDK</acronym> CD on
<ulink url="http://www.cai.com/registration/cd_ingres.htm">
http://www.cai.com/registration/cd_ingres.htm</ulink>.</para>
<para>Remember that you are not allowed to use the
<acronym>SDK</acronym> in a business environment.
It is for evaluating <application>Ingres</application> and prototyping
applications only.</para>
<para>The <acronym>SDK</acronym> CD contains both the
Windows NT and the Linux versions of the Software Development Kit.
You can find the Linux files in the following directories:</para>
<itemizedlist>
<listitem>
<para><filename class="directory">/doc</filename>: the manuals in
<acronym>PDF</acronym> format, together with the Linux version
of <application>Acrobat Reader</application>
(<filename>linux-ar-40.tar.gz</filename>).
The installer will not copy the documentation to hard disk.
These manuals are also available on
<ulink url="http://www.cai.com/products/ingres/documentation_set.htm">
http://www.cai.com/products/ingres/documentation_set.htm</ulink>.
I will reference some of them later in this document.</para>
</listitem>
<listitem>
<para><filename class="directory">/int_lnx</filename>:
this directory contains <filename>ingres.tar</filename>,
the tarball to be installed.
<filename>ingres.tar</filename> can be installed directly
from the CD or you can copy it to hard disk first.</para>
</listitem>
</itemizedlist>
<para>Do not forget to read the <filename>Readme</filename> file in the
root directory on the CD.</para>
</sect2>
<sect2 id="beta" xreflabel="The Beta Version">
<title>The Beta Version</title>
<para>The freshest beta version of the <acronym>SDK</acronym> can
always be downloaded from
<ulink url="http://www.cai.com/products/betas/ingres_linux/ingres_linux.htm">
http://www.cai.com/products/betas/ingres_linux/ingres_linux.htm</ulink>.</para>
<note>
<para>At the time of writing, the version of the downloadable beta is 2.5.
The next revision of the HOWTO will cover the installation of this
version, too.
The 2.0 beta is still available on
<ulink url="ftp://ftp.cai.com/pub/marketing/ingres/ingresII9808libc6.tar">
ftp://ftp.cai.com/pub/marketing/ingres/ingresII9808libc6.tar</ulink>.</para>
</note>
</sect2>
<sect2 id="full" xreflabel="The Ingres II Full Edition">
<title>The Ingres II Full Edition</title>
<para>In February 2000 Computer Associates announced the general
availability of <application>Ingres II 2.0</application> for Linux.
Besides the components found in the <acronym>SDK</acronym>,
the full edition contains more modules, such as:</para>
<itemizedlist>
<listitem>
<para>Net: this component makes possible for
<application>Ingres</application> utilities and user applications
to access databases residing on different installations.</para>
</listitem>
<listitem>
<para>Replicator: support for replication functions.</para>
</listitem>
<listitem>
<para>Star: for handling distributed databases.</para>
</listitem>
<listitem>
<para>Enterprise Access: communication with different database
management systems and other, non-relational data sources
(used to be called Gateways).</para>
</listitem>
<listitem>
<para>Protocol Bridge: for communicating with clients on different
types of networks.</para>
</listitem>
<listitem>
<para>Spatial Object Library: for handling two-dimensional spatial
objects.</para>
</listitem>
</itemizedlist>
<para>The CD, besides the <filename class="directory">/doc</filename> and
<filename class="directory">/int_lnx</filename> directories that are common
with the SDK, contains <filename>install.sh</filename>, the general
<application>Ingres</application> installer and its files.
More on <filename>install.sh</filename> later, in subsection
<xref linkend="start">.</para>
</sect2>
<sect2 id="tng" xreflabel="The Unicenter TNG Framework">
<title>The Unicenter TNG Framework</title>
<para>At last, let me note that the Linux version of <acronym>CA</acronym>'s
<application>Unicenter TNG Framework</application> also includes
<application>Ingres</application> as its embedded database management system.
For this reason, knowing <application>Ingres</application> may come in
handy when using <application>Unicenter</application>, too.
You can order a free <application>Unicenter TNG Framework</application> CD on
</para>
<itemizedlist>
<listitem>
<para><ulink url="http://www.cai.com/registration/tng_framework_linux/index.htm">
http://www.cai.com/registration/tng_framework_linux/index.htm</ulink>
for RedHat, or</para>
</listitem>
<listitem>
<para><ulink url="http://www.cai.com/registration/tng_framework_linux/suse_linux.htm">
http://www.cai.com/registration/tng_framework_linux/suse_linux.htm</ulink>
for SuSE.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="sysreq" xreflabel="System Requirements">
<title>System Requirements</title>
<para>In this section you will see what hardware and software
requirements must be met before you can install
<application>Ingres</application>.
The ingres user, owner of the installation, makes a debut, too.</para>
<sect2 id="hardware" xreflabel="Hardware">
<title>Hardware</title>
<para>The minimal hardware capable of running <application>Ingres</application>
is:</para>
<itemizedlist>
<listitem>
<para>486x33 processor, Pentium recommended.</para>
</listitem>
<listitem>
<para>16 Mb <acronym>RAM</acronym>, with 32 Mb swap space (64 Mb
<acronym>RAM</acronym> recommended).</para>
</listitem>
<listitem>
<para>200 Mb disk space if you install everything (150 Mb will do
for the <acronym>SDK</acronym>).
You do not need to have this space in one file system: we will discuss
the possibilities in the section <xref linkend="prep">.</para>
</listitem>
</itemizedlist>
<note>
<para>This is the <emphasis>minimum</emphasis> recommended configuration.
<application>Ingres</application>, like most other <acronym>RDBMSs</acronym>,
is a fairly resource-hungry application.
While your development system will probably run beatifully on a 166 MHz
Pentium with 64 Mb <acronym>RAM</acronym>, a live system with
potentially many concurrent users would require more iron.</para>
</note>
</sect2>
<sect2 id="software" xreflabel="Software">
<title>Software</title>
<para>The following software must be present for
<application>Ingres</application> to run:</para>
<itemizedlist>
<listitem>
<para>kernel 2.0.34 or higher.</para>
</listitem>
<listitem>
<para>libcrypt.so - this library is not included in every Linux
distribution.
If this is the case with your system, check your distribution's
Web site: they must have it somewhere.</para>
</listitem>
<listitem>
<para>uncompress - certain
Linux distributions (such as Caldera's Open Linux 2.2) do not
contain the <application>ncompress</application> package.
Again, check your distribution's Web site if you do not have it.</para>
</listitem>
</itemizedlist>
<para>Working glibc versions:</para>
<informaltable frame="all">
<tgroup cols="3">
<colspec colwidth="*" align=center>
<colspec colwidth="*" align=center>
<colspec colwidth="*" align=center>
<thead>
<row>
<entry align=center>glibc
</entry>
<entry align=center>SDK
</entry>
<entry align=center>Full Version
</entry>
</row>
</thead>
<tbody>
<row>
<entry>glibc 2.07 (eg RedHat 5.2)
</entry>
<entry>Yes.
</entry>
<entry>No.
</entry>
</row>
<row>
<entry>glibc 2.1 (eg RedHat 6.0)
</entry>
<entry>Yes but you need the RedHat compatibility packages and an
<application>Ingres</application> patch to be able to use
the forms-based development tools.
See <xref linkend="forms"> for details.
</entry>
<entry>Yes.
</entry>
</row>
<row>
<entry>glibc 2.1.1, 2.1.2 (eg RedHat 6.1)
</entry>
<entry>No.
</entry>
<entry>Yes.
</entry>
</row>
<row>
<entry>glibc 2.1.3 (eg RedHat 6.2)
</entry>
<entry>See glibc 2.1.
</entry>
<entry>Yes.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>If you are unsure of the version of your glibc, check the
<filename class="directory">/lib</filename> directory:</para>
<programlisting>
# ls -l /lib/libc*so
</programlisting>
<para>The output should be something like:</para>
<screen>
-rwxr-xr-x ... /lib/libc-2.1.3.so
</screen>
<para>The version of my glibc is apparently 2.1.3.</para>
<note>
<para>There is no guarantee that if your system meets the above
requirements you will be able to install <application>Ingres</application>
on it.
Sticking to a distribution that is explicitly mentioned in the
release notes of your <application>Ingres</application> version is the
best way to avoid installation problems.</para>
</note>
</sect2>
<sect2 id="kernel" xreflabel="Kernel Parameters">
<title>Kernel Parameters</title>
<para>The default settings of the Linux kernel are adequate for a
development <application>Ingres</application> environment.
For a live system, however, probably to increase the size of the database
cache(s), you may want to change the built-in value of the
<parameter>SHMMAX</parameter> parameter.
This parameter sets the maximum size of a shared memory segment.
By default, it is 32 Mb which allows for a somewhat lesser buffer cache.</para>
<para>You have two choices to change the value of <parameter>SHMMAX</parameter>:
</para>
<para>As root, simply <command>echo</command> the new value into
<filename>/proc/sys/kernel/shmmax</filename>:</para>
<programlisting>
#echo 83886080 &gt; /proc/sys/kernel/shmmax
</programlisting>
<para>In the example above, we set the value of <parameter>SHMMAX</parameter>
to 80 Mb.
The change takes effect immediately but after a reboot, the original value
is restored.</para>
<para>The other possibility is to change <parameter>SHMMAX</parameter>'s
default value in the kernel source (the relevant header file is
<filename>/usr/src/linux/include/asm/shmparam.h</filename> if you have
installed the source).
In this case, you may also have to modify other parameters in the file, then
rebuild the kernel.
I suggest you do it only if you know what you are doing.
For information on how to configure and compile the kernel see
<ulink url="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html">
The Linux Kernel HOWTO</ulink> by Brian Ward.</para>
</sect2>
<sect2 id="inguser" xreflabel="The ingres User and II_SYSTEM">
<title>The ingres User and II_SYSTEM</title>
<para>We need an account called ingres to install and run
<application>Ingres</application>.
He will own the installed software and only he can perform system
management tasks such as starting and stopping
<application>Ingres</application>.</para>
<para>The ingres user may belong to any group.
In the following example, we will create a separate group for him.</para>
<para>The verified (therefore, recommended) shell for the ingres user is
<command>bash</command>.
All examples in this paper apply to this shell.
If you use some other shell (which is probably just as fine),
take into account the differences in syntax.</para>
<para>The binaries, shared libraries, configuration files and
other files which make up the <application>Ingres</application> software,
will be located in a tree structure after installation.
You will set the root of this tree via the shell variable
<envar>II_SYSTEM</envar> in the environment of the ingres user (to be exact,
the root directory will be
<filename class="directory">$II_SYSTEM/ingres</filename>).</para>
<para>If you plan to install the whole software, either the
<acronym>SDK</acronym>, or the full version, make sure you have
the following free space under
<filename class="directory">$II_SYSTEM/ingres</filename>:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colwidth="*" align=center>
<colspec colwidth="*" align=center>
<thead>
<row>
<entry align=center>SDK
</entry>
<entry align=center>Full Version
</entry>
</row>
</thead>
<tbody>
<row>
<entry>70 Mb
</entry>
<entry>90 Mb
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>10 Mb extra free space is needed during installation.</para>
<tip><para>If this is the first time you install
<application>Ingres</application> (I hope you start with the
<acronym>SDK</acronym>, not a live system), I suggest you
keep the whole installation (the <application>Ingres</application> software,
databases, backups, sort areas, etc.) in one place so that you can find
every component easily.
If you have at least 150-200 Mb free space under
<filename class="directory">$II_SYSTEM/ingres</filename>
and you do not plan to create large databases (at least, not
for some time), your system will work without problems.
Should you at any later time run out of space, you will always
have the possibility to relocate some of your databases to other
partitions.</para></tip>
<para>In the following, I will assume that <envar>II_SYSTEM</envar> is set to
<filename class="directory">/opt</filename>.</para>
<para>Logging in as root, execute the tasks mentioned above:</para>
<programlisting>
# useradd -d /opt/ingres -s /bin/bash ingres
# chmod 755 /opt/ingres
# passwd ingres
</programlisting>
<para>The <command>useradd</command> command creates a group with the same
name as the new user if you do not specify the group on the command line.
It also creates the user's home directory.</para>
<para>We set the home directory of ingres to
<filename class="directory">/opt/ingres</filename>
(<filename class="directory">$II_SYSTEM/ingres</filename>).
This is not mandatory but convenient.
</para>
<para>Finally, append the following lines to the <filename>.bashrc</filename>
file of ingres:</para>
<programlisting>
umask 022
export II_SYSTEM=/opt
export PATH=$II_SYSTEM/ingres/bin:$II_SYSTEM/ingres/utility:$PATH
export LD_LIBRARY_PATH=/lib:/usr/lib:$II_SYSTEM/ingres/lib
export ING_EDIT=/bin/vi
if [ -n "$DISPLAY" ]
then
export TERM_INGRES=vt100fx
else
export TERM_INGRES=vt100f
fi
</programlisting>
<para><envar>ING_EDIT</envar> sets the editor that can be called from
<application>Ingres</application> utilities or application programs.
Naturally, you can use any editor, not just <command>vi</command>.
You must, however, specify the whole access path to the program.
(If you stick to <command>vi</command>, check if it is under
<filename class="directory">/bin</filename>: it may be somewhere else
in your system.)</para>
<note>
<para>If the <envar>EDITOR</envar> shell variable is set, it overrides
the value of <envar>ING_EDIT</envar>.</para>
</note>
<para>Setting <envar>TERM_INGRES</envar> is necessary for the terminal to
work properly.
Forms-based <application>Ingres</application> utilities, such as the
installer itself, and also applications created with traditional
<application>Ingres</application> development tools
(<acronym>ABF</acronym>, Vision) make heavy use of function keys.
The <filename>.bashrc</filename> above sets <envar>TERM_INGRES</envar>
according to the terminal type (X, or VT100-like).</para>
<para>These settings must be included in the <filename>.bashrc</filename>
file of every <application>Ingres</application> user.</para>
</sect2>
</sect1>
<sect1 id="prep" xreflabel="Preparing for the Installation">
<title>Preparing for the Installation</title>
<para>This is the longest section and so it should be: after
careful planning the installation itself should be an easy task.</para>
<sect2 id="ingenv" xreflabel="Ingres Environment Variables">
<title>Ingres Environment Variables</title>
<para>You will use <application>Ingres</application> environment variables
to determine where to put further elements (besides the software itself)
of the <application>Ingres</application> installation.
These variables, unlike <envar>II_SYSTEM</envar>, are not shell variables
but rather parameters of <application>Ingres</application> stored in a file.
Some of them can be changed at any time after the installation, but altering
the value of others requires a whole re-install.
Later you will see which of them are of this "stable" nature.</para>
<para>During installation, you can choose between setting these variables
manually or letting the installer set them to their default values
(<guimenuitem>Express Install</guimenuitem> option).</para>
<para>In the following, we will take the relevant
<application>Ingres</application> environment variables one by one and see
what each of them is good for.
It may help if you put their planned values on paper.
You can find an Installation Worksheet in the
<citetitle>Getting Started Guide</citetitle> which you can print out and
use for this purpose.</para>
</sect2>
<sect2 id="iilog" xreflabel="II_LOG_FILE and II_DUAL_LOG">
<title>II_LOG_FILE and II_DUAL_LOG</title>
<para><application>Ingres</application> uses an installation-wide
transaction log file to record information on all changes made to any database.
This information broadly consists of:</para>
<itemizedlist>
<listitem>
<para><emphasis>Before images</emphasis> of updated or deleted rows.
These are necessary for rolling back uncommitted transactions,
should it be required <emphasis>(undo)</emphasis>.</para>
</listitem>
<listitem>
<para>The changes made to database objects.
Recording them makes it possible to <emphasis>redo</emphasis>
committed transactions after a system crash if the new data
had not been written to the database prior the crash.</para>
</listitem>
</itemizedlist>
<para>The transaction log resides in the
<filename class="directory">II_LOG_FILE/ingres/log</filename> directory,
where <envar>II_LOG_FILE</envar> is an <application>Ingres</application>
environment variable.
The name of the log file is <filename>ingres_log</filename>.</para>
<para><guimenuitem>Express Install</guimenuitem> creates a log file
of the minimum possible size, 16 Mb.
Such a log file may not be large enough even in a development system.
If you have free disk space and choose manual install (in which
case you can specify the size of the log), set it to something much
larger.</para>
<para>Both the location and the size of the log file can be changed
at any time after installation.
The method of doing this is described in the
<citetitle pubwork=book>System Reference Guide</citetitle>.</para>
<para>You also have to decide if you want dual logging (mirroring the
transaction log).
If the log gets corrupted for any reason, <application>Ingres</application>
stops and you have to recover your databases from backup.
Therefore, in a live system, it is almost compulsory either to have
some type of <acronym>RAID</acronym> protection of the log or to have
it mirrored by <application>Ingres</application>.
If you use dual logging, the copy of the log file can be found under
<filename class="directory">II_DUAL_LOG/ingres/log</filename>.
Its name is <filename>dual_log</filename>.</para>
<para>In a development or test environment, mirroring the log is not
always necessary.</para>
</sect2>
<sect2 id="loc" xreflabel="Database Locations">
<title>Database Locations</title>
<para>There can be any number of databases in an
<application>Ingres</application> installation.
A database, on the other hand, consists of files of different types.
These are:</para>
<itemizedlist>
<listitem>
<para>Control file: it stores certain basic information about the
database.
You can see this information with the <command>infodb</command>
command after you have completed the installation.</para>
</listitem>
<listitem>
<para>Data files: every system table, user table, and also every
index goes in a separate file.</para>
</listitem>
<listitem>
<para>Checkpoint files: checkpoint is the term
<application>Ingres</application> uses for a database backup.
A backup can consist of more than file.</para>
</listitem>
<listitem>
<para>Dump files: online backups are possible in
<application>Ingres</application>, that is, the database may be in
use while the backup program is running.
For this reason, the database may change while it is being checkpointed.
<application>Ingres</application>, so that it can restore the database
to the state it was in at the <emphasis>beginning</emphasis> of
the backup, saves the before images of those data blocks (pages)
that have changed during the backup process.
These pages are saved in the dump files.</para>
</listitem>
<listitem>
<para>Journal files: from time to time,
<application>Ingres</application> writes the records of committed
transactions from the log file to
journal files (at least, this is the default behavior: journalling may
be set off at the database or table level).
The frequency of the journalling activity is a tunable function of the
amount of information that is written to the transaction log.
Journalling protects the installation against media failures:
if the disk containing the database crashes, you can restore
the last (just before the failure occurred) committed state
of the database using a backup (checkpoint) of the database
and the journals created after that checkpoint was taken.
If you lose the log disk, you can restore the last committed
state the database was in at the time the last journal file
was written.</para>
</listitem>
<listitem>
<para>Work files: <application>Ingres</application>, if it needs to
sort large volumes of data, creates temporary files on disk.</para>
</listitem>
</itemizedlist>
<para>The files constituting a database reside in different directories,
according to their types.
These directories are specified indirectly, by means of
<application>Ingres</application> <emphasis>locations</emphasis>.</para>
<para>There are five location types:</para>
<itemizedlist>
<listitem>
<para>Data location: place for data files of a database.
A database can have more than one data location (adding data locations
to a database is called <emphasis>extending</emphasis> the database).
However, every database has a <emphasis>primary</emphasis> data
location.
The system tables and the control file always reside in the primary
location.
When creating a table, if you do not specify the location(s) to put
it in, it will be placed in the primary data location of the
database.</para>
</listitem>
<listitem>
<para>Checkpoint location: by default, backups are created here.
Not necessarily, however: the <command>ckpdb</command> command
allows you to specify an arbitrary place for the backup, this way you
can checkpoint a database directly to tape as well.</para>
</listitem>
<listitem>
<para>Dump location: for dump files.</para>
</listitem>
<listitem>
<para>Journal location: this is where the journal files for a
database reside.</para>
</listitem>
<listitem>
<para>Work location: <application>Ingres</application> creates
temporary sort files in this location.
Just like with data locations, a database may have more than one
work location.
If this is the case, <application>Ingres</application>, by default,
uses all of them for each sort operation.</para>
</listitem>
</itemizedlist>
<para>Let us see how these locations work in practice.
Say we have a database, called <database>test</database>, with the
following locations:</para>
<itemizedlist>
<listitem>
<para><envar>DATALOC1</envar>: data location --&gt;
<filename class="directory">/opt</filename></para>
</listitem>
<listitem>
<para><envar>CKPLOC</envar>: checkpoint location --&gt;
<filename class="directory">/opt</filename></para>
</listitem>
<listitem>
<para><envar>DMPLOC</envar>: dump location --&gt;
<filename class="directory">/opt</filename></para>
</listitem>
<listitem>
<para><envar>JRNLLOC</envar>: journal location --&gt;
<filename class="directory">/opt</filename></para>
</listitem>
<listitem>
<para><envar>WORKLOC1</envar>: work location --&gt;
<filename class="directory">/opt</filename></para>
</listitem>
</itemizedlist>
<para>Every location of the <database>test</database> database points to the
<filename class="directory">/opt</filename> directory.
Elements of the database go in these directories:</para>
<itemizedlist>
<listitem>
<para>data files:
<filename class="directory">/opt/ingres/data/default/test</filename>
</para>
</listitem>
<listitem>
<para>checkpoint files:
<filename class="directory">/opt/ingres/ckp/default/test</filename>
</para>
</listitem>
<listitem>
<para>dump files:
<filename class="directory">/opt/ingres/dmp/default/test</filename>
</para>
</listitem>
<listitem>
<para>journal files:
<filename class="directory">/opt/ingres/jnl/default/test</filename>
</para>
</listitem>
<listitem>
<para>temporary files:
<filename class="directory">/opt/ingres/work/default/test</filename>
</para>
</listitem>
</itemizedlist>
<para>Let us suppose now, that we <emphasis>extend</emphasis> the database
to the following locations:</para>
<itemizedlist>
<listitem>
<para><envar>DATALOC2</envar>: data location --&gt;
<filename class="directory">/opt</filename></para>
</listitem>
<listitem>
<para><envar>DATALOC3</envar>: data location --&gt;
<filename class="directory">/disk2</filename></para>
</listitem>
<listitem>
<para><envar>WORKLOC2</envar>: work location --&gt;
<filename class="directory">/disk2</filename></para>
</listitem>
</itemizedlist>
<para>The database is effectively extended to the following directories:</para>
<itemizedlist>
<listitem>
<para>data files:
<filename class="directory">/disk2/ingres/data/default/test</filename>
</para>
</listitem>
<listitem>
<para>temporary files:
<filename class="directory">/disk2/ingres/work/default/test</filename>
</para>
</listitem>
</itemizedlist>
<para><envar>DATALOC2</envar> points to
<filename class="directory">/opt</filename>, just like <envar>DATALOC1</envar>.
Tables to be created in location <envar>DATALOC2</envar> will go to
<filename class="directory">/opt/ingres/data/default/test</filename>,
the same directory where tables created in location <envar>DATALOC1</envar>
reside.</para>
<para>As is apparent from the example, we could have created just one
location for <envar>DATALOC1</envar>, <envar>DATALOC2</envar>,
<envar>CKPLOC</envar>, <envar>DMPLOC</envar>, <envar>JRNLLOC</envar>,
and <envar>WORKLOC1</envar>.</para>
<para>Summarizing the main points about locations:</para>
<itemizedlist>
<listitem>
<para>Every location points to the root of a directory tree.</para>
</listitem>
<listitem>
<para>More than one location can point to the same directory.</para>
</listitem>
<listitem>
<para>A location can be used for storing different types of files.
</para>
</listitem>
<listitem>
<para>Databases can share locations.
You can see from the example why this is true: the name of the
database becomes part of the directory tree, hence files of
different databases never mix.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="iidbdb" xreflabel="The iidbdb Database">
<title>The iidbdb Database</title>
<para>Every <application>Ingres</application> installation has a master
database called <database>iidbdb</database>.
<application>Ingres</application> stores information about users, locations
and user databases in this database.
<database>iidbdb</database> is created by the installer.</para>
<para>You have to set the locations for <database>iidbdb</database> during
installation.
These locations are stored in the following
<application>Ingres</application> environment variables:</para>
<itemizedlist>
<listitem>
<para><envar>II_DATABASE</envar>: data location</para>
</listitem>
<listitem>
<para><envar>II_CHECKPOINT</envar>: checkpoint location</para>
</listitem>
<listitem>
<para><envar>II_DUMP</envar>: dump location</para>
</listitem>
<listitem>
<para><envar>II_JOURNAL</envar>: journal location</para>
</listitem>
<listitem>
<para><envar>II_WORK</envar>: work location</para>
</listitem>
</itemizedlist>
<para>These variables determine the default locations for every user database
as well, if you do not override them when creating those databases.
See <xref linkend="createdb"> for more information.</para>
<warning>
<para>Changing the value of <envar>II_DATABASE</envar>,
<envar>II_CHECKPOINT</envar>, <envar>II_DUMP</envar>,
<envar>II_JOURNAL</envar>, or <envar>II_WORK</envar> requires a complete
re-install of <application>Ingres</application>.</para>
</warning>
<para>Let us see these variables one by one.</para>
</sect2>
<sect2 id="iidatab" xreflabel="II_DATABASE">
<title>II_DATABASE</title>
<para><envar>II_DATABASE</envar> determines the data location of
<database>iidbdb</database>.
Its default value is <envar>$II_SYSTEM</envar> (in case of a manual
install you can enter a different value for <envar>II_DATABASE</envar>,
while <guimenuitem>Express Install</guimenuitem> inevitably sets it to
<envar>$II_SYSTEM</envar>).</para>
<para>The size of <database>iidbdb</database> after the installation is
somewhat more than 5 Mb.
It can only grow significantly if you create hundreds of
<application>Ingres</application> users, databases or locations.</para>
</sect2>
<sect2 id ="iicheck" xreflabel="II_CHECKPOINT">
<title>II_CHECKPOINT</title>
<para><envar>II_CHECKPOINT</envar> contains the value for the checkpoint
location of <database>iidbdb</database>.
By default, it is also set to <envar>$II_SYSTEM</envar>.</para>
<para>The size of a checkpoint is just about the same as that of the database
itself (at least until you modify the template file of the checkpoint program:
it is possible, as you will see in <xref linkend="backup">).
The installer takes the first checkpoint of <database>iidbdb</database>.</para>
<para>If you plan to place checkpoints of user databases under
<envar>II_CHECKPOINT</envar> then you have to provide for more space here.
</para>
<para>A further factor that must be taken into account is how long you want
to keep backups.
When starting the checkpoint program, you can request the deletion of older
backups if you do not have too much free space.</para>
</sect2>
<sect2 id="iidump" xreflabel="II_DUMP">
<title>II_DUMP</title>
<para><envar>II_DUMP</envar> determines the dump location of the
<database>iidbdb</database> database.
By default, its value equals to that of <envar>II_CHECKPOINT</envar>.</para>
<para>By the end of the installation process, <envar>II_DUMP</envar> will
contain a very small amount of data.
If you always create checkpoints off-line then you will not need much space
here.</para>
</sect2>
<sect2 id="iijrnl" xreflabel="II_JOURNAL">
<title>II_JOURNAL</title>
<para><envar>II_JOURNAL</envar> contains the value for the journal location
of the <database>iidbdb</database> database.
Its default value is the same as <envar>II_CHECKPOINT</envar>'s.</para>
<para>The first checkpoint, taken by the installer causes the first, small
journal file to appear here.
If you do not use different journal locations for user databases then the
necessary amount of free space under <envar>II_JOURNAL</envar> depends on
three factors:</para>
<itemizedlist>
<listitem>
<para>Whether you want <application>Ingres</application> to journal
at all.
If you take checkpoints of your databases regularly and do not mind
losing the changes you have made to them since the latest checkpoint,
you may switch off journalling.
Naturally, running a live system without journalling is usually not
acceptable.</para>
</listitem>
<listitem>
<para>If journalling is switched on, then the growth rate of the
journal area is determined by the volume of changes made to the
databases.
Frequent, large updates require quite a bit of space under
<envar>II_JOURNAL</envar>.</para>
</listitem>
<listitem>
<para>The third factor is, how long you wish to keep old journal files.
If, when taking a checkpoint, you instruct <command>ckpdb</command>
to delete the old checkpoints, then previous journal files will be
removed as well.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="iiwork" xreflabel="II_WORK">
<title>II_WORK</title>
<para><envar>II_WORK</envar> determines the work location of the
<database>iidbdb</database> database.
It also defaults to <envar>II_CHECKPOINT</envar>.</para>
<para>The problem of sizing the work location only arises if
<envar>II_WORK</envar> serves as a work location for user databases as well.
It is next to impossible to estimate the temporary disk space that will be
needed here; however, having the size of the largest table multiplied by three
should work as a starting point.</para>
<para>Remember that a database can have more than one work location.
If the original location turns out too small, you can always extend the
database to further work locations.</para>
</sect2>
<sect2 id="other" xreflabel="Other Ingres Environment Variables">
<title>Other Ingres Environment Variables</title>
<para>Besides the <application>Ingres</application> environment variables
that determine locations there are a couple more that you have to set
during installation (or have <guimenuitem>Express Install</guimenuitem>
set them to their default value). These are:</para>
<itemizedlist>
<listitem>
<para><envar>II_INSTALLATION</envar>: a two-character code,
identifying the installation.
Every <application>Ingres</application> installation on a machine
must have its own, unique, installation code.
The default value for <envar>II_INSTALLATION</envar> is
<constant>II</constant>.
Once set, it cannot be changed.</para>
</listitem>
<listitem>
<para><envar>II_NUM_OF_PROCESSORS</envar>: number of processors in
the machine.
By default, it is <constant>1</constant>.
If you set it to a higher value, <application>Ingres</application>
will use spin-locks when accessing the database cache.
If you do not know what spin-locks are, do not bother.
The point is to set <envar>II_NUM_OF_PROCESSORS</envar> to
<constant>2</constant> if you have a multiprocessor machine.
Its value can be changed at any time later.</para>
</listitem>
<listitem>
<para><envar>II_CHARSET</envar>: this variable determines the code
set of all character data stored in all databases you will create in
the installation.
Its default value is <constant>ISO88591</constant>.
Perhaps it is not surprising that changing it to a different value
after installation may corrupt data stored in your existing databases.
Since the <database>iidbdb</database> database is created by the
installer program, you should not choose
<guimenuitem>Express Install</guimenuitem> if
<constant>ISO88591</constant> does not suit you.</para>
</listitem>
<listitem>
<para><envar>II_TIMEZONE_NAME</envar>: name of the time zone, by
default <constant>NA-PACIFIC</constant>.
During manual install you can select its value from a list of valid
codes.
<application>Ingres</application> stores all date and time values
in <acronym>GMT</acronym> and adjusts them according to
<envar>II_TIMEZONE_NAME</envar> when communicating with the client.
Therefore, if you set <envar>II_TIMEZONE_NAME</envar> to a different
value, you will see all date-time values in the databases change.
For this reason, set this variable to its final value before creating
the first user database.</para>
</listitem>
</itemizedlist>
<para>The (manual) installer prompts you for the value of two further
parameters which are not <application>Ingres</application> environment
variables:</para>
<itemizedlist>
<listitem>
<para>Expected number of concurrent users in the system: this is
<constant>32</constant> by default.
Based on this number, the installer sets the value of a number of
other parameters, such as the size of the database cache.
These derived parameters can later be adjusted.</para>
</listitem>
<listitem>
<para><acronym>SQL-92</acronym> compatible databases: by default,
<application>Ingres</application> databases differ from the
<acronym>SQL-92</acronym> standard in some ways.
For example, object names not protected by single or double quotes
are converted to lower case rather than upper case.
You can find the other differences in the
<citetitle>SQL Reference Guide</citetitle>.</para>
</listitem>
</itemizedlist>
<para>After you have made up your mind on the values of all installation
parameters, you know whether the default values for those variables that
cannot be changed after installation are acceptable to you.
If they are, you can choose <guimenuitem>Express Install</guimenuitem>.</para>
</sect2>
</sect1>
<sect1 id="install" xreflabel="The Installation Process">
<title>The Installation Process</title>
<para>In this section, the actual installation of
<application>Ingres</application> takes place.</para>
<sect2 id="start" xreflabel="Starting the Installation Program">
<title>Starting the Installation Program</title>
<para>In the following I will presume that you install directly from the CD
which is mounted under <filename class="directory">/cdrom</filename>.
Depending on whether you install the <acronym>SDK</acronym> or the full
version of <application>Ingres</application>, you have to start the installation
differently.</para>
<para>For the <acronym>SDK</acronym>:</para>
<orderedlist>
<listitem>
<para>Log in as <emphasis>ingres</emphasis>.</para>
</listitem>
<listitem>
<para><command>cd</command> to
<filename class="directory">$II_SYSTEM/ingres</filename> if it is not
your home directory.</para>
</listitem>
<listitem>
<para>Unpack the <filename class="directory">install</filename>
subdirectory from the tar file.</para>
</listitem>
<listitem>
<para>Start the <command>ingbuild</command> program.</para>
</listitem>
</orderedlist>
<programlisting>
$ cd $II_SYSTEM/ingres
$ tar xf /cdrom/int_lnx/ingres.tar install
$ install/ingbuild
</programlisting>
<para>For the full version:</para>
<orderedlist>
<listitem>
<para>Log in as <emphasis>root</emphasis>.</para>
</listitem>
<listitem>
<para>Start the installer.</para>
</listitem>
</orderedlist>
<programlisting>
# /cdrom/install.sh
</programlisting>
<para>In this latter case, you have to let the installer know the owner of
the installation (ingres), and the value of <envar>II_SYSTEM</envar>.
After that, <command>install.sh</command> starts <command>ingbuild</command>
for you.</para>
<para>From this point on, the installation process is the same for both
options.</para>
<para>On the starting screen of <command>ingbuild</command> you have to
specify the path to the tar file and select the type of install:
<guimenuitem>Custom</guimenuitem> or <guimenuitem>Package</guimenuitem>.
I suggest you go for <guimenuitem>Custom Install</guimenuitem>
to be able to choose exactly those elements you want to install.</para>
<para>After choosing <guimenuitem>Custom Install</guimenuitem>, a table on
the next screen shows all components of your <application>Ingres</application>
version together with their respective sizes.
Because of common parts in different components, the sizes added up indicate
much more disk space than is really needed for the installation.</para>
<para>By default every component is set to be installed.
If you want to exclude some of them, write <constant>"No"</constant>
in their <varname>"Install?"</varname> field.</para>
<para>You had previously decided if the default values for the "stable"
<application>Ingres</application> environment variables were acceptable
for your installation.
If this is the case, you can choose <guimenuitem>Express Install</guimenuitem>
here.
Remember that you can alter the value of <envar>II_LOG_FILE</envar> as well as
the size of the transaction log at any time later.</para>
<tip>
<para>If this is your first <application>Ingres</application> install,
you have the necessary space under
<filename class="directory">$II_SYSTEM/ingres</filename>
and the "stable" parameters' default values are OK, I suggest you choose
<guimenuitem>Express Install</guimenuitem>.</para>
</tip>
<para>Therefore, let us see this option first.</para>
</sect2>
<sect2 id="express" xreflabel="Express Install">
<title>Express Install</title>
<para>In the case of <guimenuitem>Express Install</guimenuitem>, the installer
executes the following tasks:</para>
<itemizedlist>
<listitem>
<para>It untars all chosen components from the
<filename>ingres.tar</filename> file to the
<filename class="directory">$II_SYSTEM/ingres/install/tmp</filename>
directory.</para>
</listitem>
<listitem>
<para>Checks the integrity of the components.</para>
</listitem>
<listitem>
<para>Puts the components in appropriate subdirectories under
<filename class="directory">$II_SYSTEM/ingres</filename>.</para>
</listitem>
<listitem>
<para>Sets the <application>Ingres</application> environment
variables to their default values.</para>
</listitem>
<listitem>
<para>Starts <application>Ingres</application>.</para>
</listitem>
<listitem>
<para>Creates the <database>iidbdb</database> database.</para>
</listitem>
<listitem>
<para>Takes a checkpoint of <database>iidbdb</database>.</para>
</listitem>
<listitem>
<para>Stops <application>Ingres</application>.</para>
</listitem>
<listitem>
<para>Sets up those components that require this (<acronym>ABF</acronym>,
Enhanced Security, etc).</para>
</listitem>
</itemizedlist>
<para>If the installation process went OK, the program tells you that every
installed component is ready to use.
In the table on the screen the <varname>"Install?"</varname> column shows
<constant>"Ready"</constant> for every selected component.</para>
<para><application>Ingres</application> is installed on your machine.
Jump to <xref linkend="compl">.</para>
</sect2>
<sect2 id="manual" xreflabel="Manual Install">
<title>Manual Install</title>
<para>If you choose <guimenuitem>Install</guimenuitem> rather than
<guimenuitem>Express Install</guimenuitem>, the installer untars
<filename>ingres.tar</filename>, checks the integrity of the components
and puts them in their respective directories.
Then it asks you if you want to setup these components now.</para>
<para>If you decide to do the setup later, the installer stops.
In the table containing the components the <varname>"Install?"</varname>
column shows <constant>"Not Set Up"</constant> for every
selected component.
You can run <command>ingbuild</command> again at any time and choose one of
the options <guimenuitem>Setup All</guimenuitem> or
<guimenuitem>Setup</guimenuitem> to set up all or one of the components.
A component cannot be used until it has been set up.</para>
<para>Let us see what happens if you choose to set up the components.</para>
<para>First, you have to set up the <acronym>DBMS</acronym> server.
On the screens to follow you will see a fair amount of explanatory text about
the parameters we have covered earlier.</para>
<para>During the setup phase, the installer prompts you for the values of
the <application>Ingres</application> environment variables and the other
necessary parameters:</para>
<itemizedlist>
<listitem>
<para><envar>II_INSTALLATION</envar>.</para>
</listitem>
<listitem>
<para><envar>II_DATABASE</envar>.</para>
</listitem>
<listitem>
<para><envar>II_CHECKPOINT</envar>: if you set it to the same value
as <envar>II_DATABASE</envar>, the installer warns you of the dangers
of losing a database and its backup at the same time.
You have to repeat <envar>II_CHECKPOINT</envar>'s value for the
program to accept it.</para>
</listitem>
<listitem>
<para><envar>II_JOURNAL</envar>.</para>
</listitem>
<listitem>
<para><envar>II_DUMP</envar>.</para>
</listitem>
<listitem>
<para><envar>II_WORK</envar>.</para>
</listitem>
<listitem>
<para><envar>II_LOG_FILE</envar>: the installer reminds you of
<application>Ingres</application>' capability of mirroring the
transaction log.
Naturally, it only makes sense if the mirrored log file is on a
different disk than the primary log file.
The installer asks you if you want to <emphasis>disable</emphasis>
dual logging.
Then you have to specify the size of the log (16 Mb by default,
make it bigger if you have free disk space as I suggested earlier).
After this you have to tell the installer where to put the primary
log file, and, if you did not switch off dual logging, the dual log
file (<envar>II_DUAL_LOG</envar>).</para>
</listitem>
<listitem>
<para><envar>II_NUM_OF_PROCESSORS</envar>.</para>
</listitem>
<listitem>
<para><envar>II_TIMEZONE_NAME</envar>.</para>
</listitem>
<listitem>
<para><envar>II_CHARSET</envar>.</para>
</listitem>
<listitem>
<para>Expected number of concurrent users.</para>
</listitem>
<listitem>
<para><acronym>SQL-92</acronym> compatible databases.</para>
</listitem>
</itemizedlist>
<para>At every prompt, enter the appropriate parameter's previously decided
value.</para>
<para>The installer may also ask you about other components you have chosen
to install.
Accept the defaults for these.</para>
<informaltable frame="all">
<tgroup cols="1">
<colspec colwidth="*" align=center>
<thead>
<row>
<entry align=center>Full Version
</entry>
</row>
</thead>
<tbody>
<row>
<entry>If you requested the installation of Net,
make <command>ingbuild</command> set it up.
Do not bother setting an <emphasis>installation password</emphasis>,
unless you know what it is: we will complete Net's
configuration later, in its own section (<xref linkend="net">).
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2 id="compl" xreflabel="Completing the Initial Configuration">
<title>Completing the Initial Configuration</title>
<para>After an <guimenuitem>Express Install</guimenuitem> (but perhaps after
a manual install as well), you may want to change the values of some of the
<application>Ingres</application> environment variables.
You will see how to do this here.
Stay logged in as ingres.</para>
<para>You can view the current values of <application>Ingres</application>
environment variables with the <command>ingprenv</command> command:</para>
<programlisting>
$ ingprenv
</programlisting>
<para>You can change the value of any variable with the
<command>ingsetenv</command> command:</para>
<programlisting>
$ ingsetenv II_TIMEZONE_NAME GMT1
</programlisting>
<para>In the example we set <envar>II_TIMEZONE_NAME</envar> to
<constant>GMT1</constant> (Greenwich Mean Time + 1 hour),
which happens to be the time zone Hungary is placed in.
You can find all possible values for <envar>II_TIMEZONE_NAME</envar> in the
file <filename>$II_SYSTEM/ingres/files/tz.crs</filename> (look for the lists
beginning with the word <constant>VALID</constant>).</para>
<para>You can change the value of any other <application>Ingres</application>
environment variable in a similar way.
<command>ingprenv</command> and <command>ingsetenv</command> do not require a
running <application>Ingres</application> server.</para>
<para>The <citetitle>System Reference Guide</citetitle> contains the
description of every <application>Ingres</application> environment variable.
Let me mention two of those that we have not covered yet.</para>
<para><envar>II_DATE_FORMAT</envar> determines the display format of dates.
By default, its value is <constant>US</constant> which provides the format
<constant>dd-mmm-yy</constant>.</para>
<note>
<para>The setting of <envar>II_DATE_FORMAT</envar> has no effect on
the way dates are stored in the database.
<application>Ingres</application> always stores full date values,
century included.
Hence, you can change the setting of <envar>II_DATE_FORMAT</envar> without
the risk of corrupting data.
In order to avoid <acronym>Y2K</acronym> problems in your applications,
you should use a date format that contains the century, such as
<constant>MULTINATIONAL4</constant> (<constant>dd/mm/yyyy</constant>)
or <constant>FINLAND</constant> (<constant>yyyy-mm-dd</constant>).
The latter seems especially proper under Linux :-)</para>
</note>
<para>Another <application>Ingres</application> environment variable that
has a good chance to be changed from its default value is
<envar>II_MONEY_FORMAT</envar>.
This one is responsible for how values of money type are displayed.</para>
<note>
<para>Just like with dates, the value of <envar>II_MONEY_FORMAT</envar>
has no impact on the storage format of money columns.</para>
</note>
<para><envar>II_MONEY_FORMAT</envar> consists of two parts: the first part
tells whether the currency sign precedes the amount (<constant>L</constant>
= Leading or <constant>T</constant> = Trailing), the second part describes
the currency itself (<constant>$</constant>, <constant>DM</constant>,
<constant>Ft</constant>, etc.: this part is a string of maximum 4 characters).
The two parts are separated by a colon.
<envar>II_MONEY_FORMAT</envar> defaults to <constant>L:$</constant>.</para>
<para>Only the ingres user is allowed to use <command>ingsetenv</command>,
since these <application>Ingres</application> environment variables apply to
the whole installation.
However, some <application>Ingres</application> environment variables
(including <envar>II_DATE_FORMAT</envar> and <envar>II_MONEY_FORMAT</envar>)
can be overridden in the users' shell, via Linux variables of the same name.
You can check the <citetitle>System Reference Guide</citetitle> about which
other variables fall into this category.</para>
<warning>
<para>Be careful: <application>Ingres</application> will not prevent
you from changing the value of any <application>Ingres</application>
environment variable, including <envar>II_DATABASE</envar>,
<envar>II_CHECKPOINT</envar>, <envar>II_CHARSET</envar>, etc.
(the "stable" parameters as we saw earlier).
However, if you change one of these, prepare for the nastiest possible
consequences, the mildest one of which is that
<application>Ingres</application> will not run.</para>
</warning>
<para>You can find information on how to setup Net and <acronym>ICE</acronym>
in separate sections (<xref linkend="net">, and <xref linkend="ice">,
respectively).</para>
</sect2>
<sect2 id="reinst" xreflabel="Re-installation">
<title>Re-installation</title>
<para>If you want to re-install <application>Ingres</application> for
any reason, remember to do the following first:</para>
<itemizedlist>
<listitem>
<para>Backup everything you need from
<filename class="directory">$II_SYSTEM/ingres</filename>
(user databases, source code of applications stored there, etc.).
Also backup any other databases you want to keep that are stored in
different locations.
You can use the <command>unloaddb</command> utility for creating
portable copies of databases.
On <command>unloaddb</command> see the <citetitle>System Reference
Guide</citetitle>.</para>
</listitem>
<listitem>
<para>Stop <application>Ingres</application>.</para>
</listitem>
<listitem>
<para>Remove everything under
<filename class="directory">$II_SYSTEM/ingres</filename>.
Also remove the contents of every other location where you stored any
part of any database.</para>
</listitem>
</itemizedlist>
<warning>
<para>Databases that are not completely removed can cause problems
when you try to re-create them.</para>
</warning>
</sect2>
<sect2 id="command" xreflabel="Command Line Install">
<title>Command Line Install (SDK)</title>
<para>For installing the <acronym>SDK</acronym>, you can run
<command>ingbuild</command> in batch mode as well.
The easiest way to do an <guimenuitem>Express Install</guimenuitem> is to start
<command>ingbuild</command> in the following way (logged in as ingres):</para>
<programlisting>
$ cd $II_SYSTEM/ingres
$ tar xf /cdrom/int_lnx/ingres.tar install
$ install/ingbuild -express /cdrom/int_lnx/ingres.tar
</programlisting>
<para>In this case a regular <guimenuitem>Express Install</guimenuitem> takes
place without having to press another key.</para>
</sect2>
<sect2 id="cliinst" xreflabel="Client Installation">
<title>Client Installation (Full Version)</title>
<para>If you have the full <application>Ingres</application> version, you may
want to set up a client installation.
If your application will run on a different machine than the database
server, all you need on the application server is a client
<application>Ingres</application> installation.</para>
<para>For a client install, choose <guimenuitem>PackageInstall</guimenuitem>
in <command>ingbuild</command>, then mark
<guimenuitem>"Ingres Networked Client"</guimenuitem> to be installed.
After the installation has been finished, go to section <xref linkend="net">
to set up Net.</para>
</sect2>
<sect2 id="instlog" xreflabel="The Installer's Log">
<title>The Installer's Log</title>
<para>No matter which type of install you have chosen (Express or Manual),
you can find all of <command>ingbuild</command>'s messages in
<filename>$II_SYSTEM/ingres/files/install.log</filename>.
I suggest you check this file after an
<guimenuitem>Express Install</guimenuitem> to see what happened during the
installation process.
On the other hand, if <command>ingbuild</command> stops with an error message,
also check this log for possible clues to the cause of the error.</para>
</sect2>
<sect2 id="check" xreflabel="Checking the Installation">
<title>Checking the Installation</title>
<para>After you have installed and configured
<application>Ingres</application>, it is time to check if it works properly.
Supposing you are still logged in as ingres, start the
<application>Ingres</application> system:</para>
<programlisting>
$ ingstart
</programlisting>
<para>Create a new database:</para>
<programlisting>
$ createdb test
</programlisting>
<para>Start the command line <acronym>SQL</acronym> interface:</para>
<programlisting>
$ sql test
</programlisting>
<para>Create a table, insert a row into it and query the table's contents:
</para>
<programlisting>
create table t1 (col1 char(10));
insert into t1 values ('abcde');
select * from t1;
\g
</programlisting>
<para>If everything went OK, you should see something like the following:</para>
<screen>
$ sql test
INGRES TERMINAL MONITOR Copyright (c) 1981, 1998 Computer Associates Intl, Inc.
Ingres Linux Version II 2.0/9808 (lnx.us5/95)libc6 login
Sun Oct 3 03:43:54 1999
continue
* create table t1 (col1 char(10));
* insert into t1 values ('abcde');
* select * from t1;
* \g
Executing . . .
(1 row)
col1
abcde
(1 row)
continue
*
</screen>
<para>You can leave <command>sql</command> with the command
<command>\q</command>.</para>
</sect2>
</sect1>
<sect1 id="admin" xreflabel="Basic System and Database Administration">
<title>Basic System and Database Administration</title>
<para>In this section I outline some of the basic tasks of the
<application>Ingres</application> system administrator and the
<application>Ingres</application> database administrator.
You will also see what tools <application>Ingres</application> provides
to perform these tasks.
In the following I suppose you are logged in as ingres.</para>
<sect2 id="startstp" xreflabel="Starting and Stopping Ingres">
<title>Starting and Stopping Ingres</title>
<para>You have already seen how to start <application>Ingres</application>:
</para>
<programlisting>
$ ingstart
</programlisting>
<para>To stop <application>Ingres</application>, use the
<command>ingstop</command> command:</para>
<programlisting>
$ ingstop
</programlisting>
<para><command>ingstop</command> only stops <application>Ingres</application>
if the are no active user sessions.
If you want to stop the system regardless of user sessions, use the following
form:</para>
<programlisting>
$ ingstop -force
</programlisting>
<para>In this case, after you have killed <application>Ingres</application>,
check if it released all shared memory segments and semaphores it had used:
</para>
<programlisting>
$ ipcs -a
</programlisting>
<para>If you see shared memory segments or semaphores in
<command>ipcs</command>'s output that are still attached to the ingres user,
release them with <application>Ingres'</application>
<command>ipcclean</command> utility:</para>
<programlisting>
$ ipcclean
</programlisting>
<warning>
<para>Take care: forcing <application>Ingres</application> to stop
might make your databases inconsistent.</para>
</warning>
</sect2>
<sect2 id="newusers" xreflabel="New Ingres Users and Locations">
<title>New Ingres Users and Locations</title>
<para>In order for any user to have access to the
<application>Ingres</application> installation, you have to define them as
<application>Ingres</application> users with the <command>accessdb</command>
utility.</para>
<para>Start <command>accessdb</command>:</para>
<programlisting>
$ accessdb
</programlisting>
<para>Select the <guimenuitem>Users</guimenuitem> option, then
<guimenuitem>Create</guimenuitem>.</para>
<para>Here, enter the name of the user.
You do not have to modify permissions.</para>
<para><guimenuitem>Save</guimenuitem>, then <guimenuitem>End</guimenuitem>,
and <guimenuitem>End</guimenuitem>.</para>
<para>You can also use <command>accessdb</command> to create new locations,
change their types or extend databases to new locations.
The usage of <command>accessdb</command> is covered in the
<citetitle>System Reference Guide</citetitle> and in the
<citetitle>Database Administrator's Guide</citetitle>.</para>
<para>As an alternative to <command>accessdb</command>, you can maintain
users and locations by running <acronym>SQL</acronym> commands on
<database>iidbdb</database> (<command>create user</command>,
<command>create location</command>, etc.).
The syntax of these commands can be found in the
<citetitle>SQL Reference Guide</citetitle>.</para>
<warning>
<para>Since the ingres user has unlimited power of changing
and possibly destroying any element of an
<application>Ingres</application> installation, it is highly
advisable that you only use this account for carrying out administrative
tasks.
Create another Linux user and set its environment to that of ingres.
Register it as an <application>Ingres</application> user via
<command>accessdb</command> and use this account for everyday work.</para>
</warning>
</sect2>
<sect2 id="createdb" xreflabel="Creating and Destroying Databases">
<title>Creating and Destroying Databases</title>
<para>In subsection <xref linkend="check"> you created a new database.
You did not specify any options in the</para>
<programlisting>
$ createdb test
</programlisting>
<para>command. Therefore the values stored in <envar>II_DATABASE</envar>,
<envar>II_CHECKPOINT</envar>, etc., became locations for the
<database>test</database> database.
You could have specified each location explicitly:</para>
<programlisting>
$ createdb test -d&lt;data location&gt; -c&lt;checkpoint location&gt; -j&lt;journal location&gt;
-b&lt;dump location&gt; -w&lt;work location&gt;
</programlisting>
<para>You can remove a database with the <command>destroydb</command>
command:</para>
<programlisting>
$ destroydb test
</programlisting>
<warning>
<para>Be careful, because <application>Ingres</application> will not
prompt you before destroying the database.</para>
</warning>
</sect2>
<sect2 id="coll" xreflabel="Collation Sequences">
<title>Collation Sequences</title>
<para>The collation sequence determines which of any two character strings
should be considered less than the other.
In <application>Ingres</application>, every database can have its own sort order.
You can specify the collation sequence when creating the database:</para>
<programlisting>
createdb test -lhun
</programlisting>
<para>If you omit the <option>-l</option> parameter, the database will have
the default collation sequence which is determined by the implicit sort order
of the code set of the <application>Ingres</application> installation
(<envar>II_CHARSET</envar>).</para>
<para>If you want to use your own collation sequence (it is
<constant>hun</constant> in the example above), you have to create a definition
file first.
The structure of this file must obey to simple rules by which you specify the
absolute or relative ordering of letters and/or strings in your language.
This file must then be compiled by the <command>aducompile</command> utility
for <application>Ingres</application> to be able to use it.</para>
<para>The Spanish collation sequence and the collation based on the
<acronym>DEC</acronym> Multinational Character Set are available both in source
(<filename>spanish.dsc</filename> and <filename>multi.dsc</filename>), and
compiled form (<filename>spanish</filename> and <filename>multi</filename>).
</para>
<para>You specify these collation sequences in the following way:</para>
<programlisting>
createdb test -lspanish
</programlisting>
<para>or</para>
<programlisting>
createdb test -lmulti
</programlisting>
<para>The compiled definition files for a collation sequence must be in the
<filename class="directory">$II_SYSTEM/ingres/file/collation</filename>
directory.
The syntax rules of the definition files can be found in the
<citetitle>System Reference Guide</citetitle>.
It may also be useful to examine the definition files for the Spanish and the
<acronym>DEC</acronym> Multinational collations.</para>
</sect2>
<sect2 id="backup" xreflabel="Backup and Recovery">
<title>Backup and Recovery</title>
<para>You can back up an <application>Ingres</application>
database or certain tables in it with the <command>ckpdb</command> utility.
The following command backs up the <database>test</database> database:</para>
<programlisting>
$ ckpdb test
</programlisting>
<note>
<para>Checkpoints can be taken online.</para>
</note>
<para>Restoring a database can be done with the
<command>rollforwarddb</command> command:</para>
<programlisting>
$ rollforwarddb test
</programlisting>
<para>By default, <command>rollforwarddb</command>, using the latest
checkpoint and all journal files created since that checkpoint, restores the
database to its last committed state.
However, you can specify a point in time to restore the database to the state
it was in at that time.
You can go back as far as 16 checkpoints
(<application>Ingres</application> stores data for the last
16 checkpoints in the control file of the database).</para>
<para>Both <command>ckpdb</command> and <command>rollforwarddb</command>
accept many parameters.
You can read more about these commands in the
<citetitle>System Reference Guide</citetitle>.
Besides, you should read Michael Leo's paper on
<application>Ingres</application> backup and recovery at
<ulink URL="http://www.naiua.org/papers/backup99.zip">
http://www.naiua.org/papers/backup99.zip</ulink>.</para>
<para>Both <command>ckpdb</command> and <command>rollforwarddb</command> use a
template file (<filename>$II_SYSTEM/ingres/files/cktmpl.def</filename>).
By modifying this file, you can customize the Linux commands that do the
physical backup and restore of the data files.
Consult the <citetitle>Database Administrator's Guide</citetitle> for the
syntax of this file.</para>
</sect2>
<sect2 id="config" xreflabel="Configuring Ingres">
<title>Configuring Ingres</title>
<para>Most <application>Ingres</application> parameters can be set via the
<command>cbf</command> utility.
This is the program by which you can specify the number of
<acronym>DBMS</acronym> servers, the sizes of different caches and a lot of
other variables.
The usage of <command>cbf</command> is detailed in the
<citetitle>System Reference Guide</citetitle>.</para>
</sect2>
<sect2 id="monit" xreflabel="Monitoring Ingres">
<title>Monitoring Ingres</title>
<para>You can use the <command>ipm</command> utility to monitor a running
<application>Ingres</application> system
(<application>Visual DBA</application> only runs on Win32).
With <command>ipm</command>, you can monitor and manage user sessions, and
also the locking and logging subsystems.</para>
</sect2>
<sect2 id="message" xreflabel="Message Files">
<title>Message Files</title>
<para>The <application>Ingres</application> message files reside in the
<filename class="directory">$II_SYSTEM/ingres/files</filename> directory.
The most important of these is <filename>errlog.log</filename>.
Should any problems arise during the running of
<application>Ingres</application>, this is the file to check first.</para>
</sect2>
</sect1>
<sect1 id="net" xreflabel="Ingres/Net">
<title>Ingres/Net</title>
<para>Ingres/Net is not part of the <acronym>SDK</acronym>.
You only get it with the full version of <application>Ingres</application>.
It allows applications (<application>Ingres</application> utilities and user
programs alike) to access <application>Ingres</application> databases on
other installations (usually on different machines as well).
On the machine where the application runs, a client
<application>Ingres</application> installation must be set up.
We covered the installation of the client in subsection
<xref linkend="cliinst">.
(Naturally, the client can also be a full <application>Ingres</application>
installation.)
</para>
<para>In this section you will see how to set up Net on both the client
and server to provide remote access to the <acronym>DBMS</acronym> server.
For a complete description of Ingres/Net I suggest you consult the
<citetitle>Ingres/Net User Guide</citetitle>.
</para>
<para>Before starting with Net, however, we need some information on how
<application>Ingres</application> authenticates its users.</para>
<sect2 id="userauth" xreflabel="User Authentication">
<title>User Authentication</title>
<para>We saw earlier that only valid <application>Ingres</application> users
can access an <application>Ingres</application> installation.
<application>Ingres</application> keeps information on its users in the
<database>iidbdb</database> database.
But how does <application>Ingres</application> authenticate users?</para>
<para>In case of local access, the answer is simple:
<application>Ingres</application> asks the operating system who the user is.
</para>
<para>There is an exception to this rule: certain users may be granted
the privilige to <emphasis>impersonate</emphasis> other
<application>Ingres</application> users when starting an
<application>Ingres</application> utility or application.
That is why it is not necessary for every <application>Ingres</application>
user to have an <acronym>OS</acronym> account.
This privilege, however, can only be granted as all-or-none: if you give
it to somebody, he/she will be able to impersonate
<emphasis>any</emphasis> other <application>Ingres</application> user,
including the ingres account.
Therefore, never grant it to anyone.</para>
<para>Leaving the authentication of users to the operating system works
fine for local access.
But what about users who want to use the database from a remote machine?
They do not log in to the machine the database resides on (the
<emphasis>server</emphasis>), therefore the server's operating system will
not authenticate them (they may not even have an <acronym>OS</acronym>
account on the server machine).</para>
<para>There are two possible ways <application>Ingres</application> can
authenticate these users.
We will cover them in the next two subsections.</para>
</sect2>
<sect2 id="logacct" xreflabel="Login Account Passwords">
<title>Login Account Passwords</title>
<para>The first solution to the remote user authentication problem is to
require that the client provides a local (to the server machine) user name
and password.
Then the <application>Ingres</application> server authenticates these
through standard <acronym>OS</acronym> facilities, just like the operating
system would do with real local accounts.</para>
<para>In this case, you do not have to set anything in Net on the server.
The only thing you will need is the <command>ingvalidpw</command>
<application>Ingres</application> utility.
It will check (by using the <function>getspnam</function> and
<function>crypt</function> <acronym>OS</acronym> functions) if the user's
name and password are valid on the server machine.
On how to install <command>ingvalidpw</command>, see subsection
<xref linkend="ingvalid">.</para>
</sect2>
<sect2 id="instpass" xreflabel="Installation Passwords">
<title>Installation Passwords</title>
<para>The other way of authenticating remote users is that the server
accepts their user <acronym>ID</acronym> <emphasis>on the client
machine</emphasis>.
In this case, the remote users do not have to be known to the
<acronym>OS</acronym> on the server.</para>
<para>How will the server validate clients in this case?
It is obvious that we need some kind of authentication: anybody can
create an ingres account on a client machine, then he/she could connect
to the installation as the ingres super-user.</para>
<para>This is where the <emphasis>installation password</emphasis> comes in:
you set an installation password on the server.
You then set this password on the client machines <emphasis>for those
accounts</emphasis> that you want to allow to access the server under their
name on the client.</para>
<para>The <application>Ingres</application> server can then authenticate
the client by simply checking its installation password.</para>
</sect2>
<sect2 id="ingvalid" xreflabel="ingvalidpw">
<title>ingvalidpw</title>
<para>As <command>ingbuild</command> apparently does not bother installing
<command>ingvalidpw</command>, you have to build it yourself.</para>
<para>Login as root, set the environment as that of ingres, then simply
type</para>
<programlisting>
# mkvalidpw
</programlisting>
<para>This script builds and installs <command>ingvalidpw</command>.</para>
</sect2>
<sect2 id="cliset" xreflabel="Setting up the Client">
<title>Setting up the Client</title>
<para>You will use the <command>netutil</command> utility to set up Net
on the client side, and, in the case of installation passwords, also on the
server.
Let us see the client side first.
Log in as the account you want to grant access to, or ingres, if you want
to set up general access.
Then type:</para>
<programlisting>
$ netutil
</programlisting>
<para>You can see three tables on <command>netutil</command>'s screen.
Let us see what fields each of them contains:</para>
<itemizedlist>
<listitem>
<para>Virtual Node Name: this is the name by which you identify
the remote <application>Ingres</application> installation,
similarly as you would define an <acronym>ODBC</acronym> data
source name.
The name is of local scope and has nothing to do either with the server
machine's name or the remote installation's code.</para>
</listitem>
<listitem>
<para>Login/Password Data: one or two entries of the following:</para>
<itemizedlist>
<listitem>
<para>Type: can be <constant>Global</constant>, or
<constant>Private</constant>.
If <constant>Private</constant>, the entry will only
pertain to the current account.
If <constant>Global</constant>, it will be used for all
users on the client machine, except for those with a
<constant>Private</constant> entry.</para>
</listitem>
<listitem>
<para>Login: the user account on the server machine.
In case of an installation password, it should be
<constant>*</constant>.</para>
</listitem>
<listitem>
<para>Password: the password on the server machine (the
above user's password, or the installation password).</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Connection Data: at least one entry of the following:</para>
<itemizedlist>
<listitem>
<para>Type: can be <constant>Global</constant>, or
<constant>Private</constant>.
The same applies as in Login/Password Data.</para>
</listitem>
<listitem>
<para>Network Address: the server machine's address.</para>
</listitem>
<listitem>
<para>Protocol: the network protocol.
On Linux, it is probably <constant>tcp_ip</constant>.</para>
</listitem>
<listitem>
<para>Listen Address: listen address of the communication
server as set up by <command>cbf</command>.
By default, it is the same as the installation code.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="servset" xreflabel="Setting up the Server">
<title>Setting up the Server</title>
<para>If you want to use an installation password, you have to configure
Net on the server, too.
In <command>netutil</command>, create a virtual node with the following
data:</para>
<itemizedlist>
<listitem>
<para>Virtual Node Name: must be the machine's name.</para>
</listitem>
<listitem>
<para>Login/Password Data</para>
<itemizedlist>
<listitem>
<para>Type: <constant>Global</constant>.</para>
</listitem>
<listitem>
<para>Login: <constant>*</constant>.</para>
</listitem>
<listitem>
<para>Password: enter the installation password.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Connection Data: you do not have to enter any data here.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="usingn" xreflabel="Using Net">
<title>Using Net</title>
<para>After you have configured Net with <command>netutil</command> on the
client, and, if necessary, on the server, use <command>netutil</command>'s
<guimenuitem>Test</guimenuitem> menu option to see if the connection works.
If it does, you can access a remote database in the following manner
(let us suppose the name of the database is <database>test</database>,
the virtual node name for the remote <application>Ingres</application>
installation is ingserv1):</para>
<programlisting>
$ sql ingserv1::test
</programlisting>
</sect2>
</sect1>
<sect1 id="ice" xreflabel="ICE">
<title>ICE (Internet Commerce Enabled)</title>
<para><application>ICE</application> is <application>Ingres'</application>
proprietary gateway to the Web.
Basically, it is a <acronym>CGI</acronym> program that can talk to an
<application>Ingres</application> server through the
native <application>Ingres</application> <acronym>API</acronym>.
<acronym>ICE</acronym> supports a couple of macro commands which you
can embed in <acronym>HTML</acronym> documents.
When rendering such a document, <acronym>ICE</acronym> first
executes the macros then outputs the resulting web page.</para>
<para>On other platforms you can configure <acronym>ICE</acronym> as
a server extension to the <application>Spyglass</application> web server
which is bundled with <application>Ingres</application>.
The Linux version of <application>Ingres</application> does not include
<application>Spyglass</application>.
Therefore, in this section I will show you how to setup
<acronym>ICE</acronym> as a standalone <acronym>CGI</acronym> program under
<application>Apache</application>, the world's most popular web server.</para>
<para>You need the <command>ingvalidpw</command> program for
<acronym>ICE</acronym> to work.
See subsection <xref linkend="ingvalid"> on how to install it.</para>
<sect2 id="apache" xreflabel="Configuring Apache">
<title>Configuring Apache</title>
<para>Building, installing and configuring <application>Apache</application>
is beyond the scope of this HOWTO.
(You had better learn <application>Apache</application> if you are putting
your databases on the Web, with <acronym>ICE</acronym> or otherwise.)</para>
<para>I suggest to download the newest stable version of
<application>Apache</application> in source and build it yourself for
maximum flexibility.
I also suggest you keep a separate <application>Apache</application>
installation just for <acronym>ICE</acronym>.</para>
<para>In this subsection I will only cover those parameters of
<application>Apache</application> that are important from
<acronym>ICE</acronym>'s point of view.</para>
<para>Things to watch out for:</para>
<itemizedlist>
<listitem>
<para>The installed software should be owned by the ingres user.
This is not strictly necessary but will make things easier.</para>
</listitem>
<listitem>
<para>Compile the mod_env module into the server, preferably
statically (do not use <acronym>DSOs</acronym> unless you have to:
they make <application>Apache</application> slower).</para>
</listitem>
</itemizedlist>
<para>After you have compiled and installed <application>Apache</application>,
set the following parameters in <filename>httpd.conf</filename>:</para>
<programlisting>
Port 8000 -- must be greater than 1023
User ingres -- all server processes run as ingres
Group ingres -- the ingres user's group
PassEnv II_SYSTEM
PassEnv LD_LIBRARY_PATH
</programlisting>
<para>The last two lines must be added to <filename>httpd.conf</filename>.
These variables will be passed from the environment of the ingres user to the
environment of <acronym>CGI</acronym> programs started by
<application>Apache</application> (specifically <command>iceinst</command>
and <command>ice</command>, the two executables of <acronym>ICE</acronym>).
</para>
</sect2>
<sect2 id="icesetup" xreflabel="ICE Setup">
<title>ICE Setup</title>
<para>Now you can configure <acronym>ICE</acronym> and its Tutorials.
You can do this with a browser and the <command>iceinst</command> program.
Let us suppose that your <acronym>CGI</acronym> directory is
<filename class="directory">/opt/ingres/apache/cgi-bin</filename> and
<application>Apache</application> is listening on port 8000.
Let the name of your machine be ingserv1.
Then you can start <command>iceinst</command> in the following manner:</para>
<programlisting>
$ iceinst -d/opt/ingres/apache/cgi-bin -u/cgi-bin -shttp://ingserv1:8000
-b/opt/netscape/netscape
</programlisting>
<para>Option <option>-d</option> is the full path to the
<acronym>CGI</acronym> directory, <option>-u</option> is this directory's
address within the site, <option>-s</option> is the Internet address of the
server, while <option>-b</option> is the full path to the browser.
If you omit option <option>-b</option> and write <option>-remote</option>
instead, then <command>iceinst</command> will not try to start the browser.
You can configure <acronym>ICE</acronym> from another machine then,
directing your browser to <ulink URL="http://ingserv1/cgi-bin/iceinst">
http://ingserv1/cgi-bin/iceinst</ulink>.</para>
<para>First the program asks for the value of <envar>II_SYSTEM</envar>.
Then you should visit every screen and set all parameters presented on them.
Have <command>iceinst</command> install the
<citetitle>Dynamic SQL Tutorial</citetitle> and the
<citetitle>Macro Processor Tutorial</citetitle> as well.
These show the usage of <acronym>ICE</acronym> via applications and a database
(<database>icedb</database> by default).</para>
<para>It is important to create a directory under
<application>Apache</application>'s
<envar>DocumentRoot</envar> where <acronym>ICE</acronym> can store the output it
creates for clients' requests.
<acronym>ICE</acronym> will not start until you create this directory and
specify its name in <command>iceinst</command>.</para>
<para>After you have completed every form, choose the
<guimenuitem>Install</guimenuitem> option.
If you have set everything properly, the configuration of
<acronym>ICE</acronym> and the installation of the tutorials take place.
<acronym>ICE</acronym> is ready to use.</para>
</sect2>
</sect1>
<sect1 id="misc" xreflabel="Miscellaneous Topics">
<title>Miscellaneous Topics</title>
<para>Further hints to the use of <application>Ingres</application>.</para>
<sect2 id="autom" xreflabel="Automatic Startup and Shutdown">
<title>Automatic Startup and Shutdown</title>
<para>If you want <application>Ingres</application> to start automatically
whenever Linux boots and stop when you shutdown or reboot the system, do
the following:</para>
<para>Log in as root.</para>
<para>Check if your Linux variant has System V or <acronym>BSD</acronym> style
<command>init</command> (<command>init</command>'s <command>man</command>
page will tell that).</para>
<para>If your system conforms to System V, the
<filename class="directory">/etc/rc.d/init.d</filename> directory must exist.
Create a file there (call it <command>ingres</command> or any other name you
wish).
The file should contain at least the following:</para>
<programlisting>
#!/bin/sh
case $1 in
start)
echo "Starting <application>Ingres</application>"
su - ingres -c "ingstart"
;;
stop)
echo "Stopping <application>Ingres</application>"
su - ingres -c "ingstop"
;;
*)
echo "Usage: ingres {start|stop}"
exit 1
;;
esac
exit 0
</programlisting>
<para>Link the file as <filename>K01ingres</filename> to the directories
that correspond to the run levels in which <application>Ingres</application>
should <emphasis>stop</emphasis>:</para>
<programlisting>
# ln -s /etc/rc.d/init.d/ingres /etc/rc.d/rc0.d/K01ingres
# ln -s /etc/rc.d/init.d/ingres /etc/rc.d/rc1.d/K01ingres
# ln -s /etc/rc.d/init.d/ingres /etc/rc.d/rc6.d/K01ingres
</programlisting>
<para>Also link it as <filename>S99ingres</filename> to the directories
that correspond to the run levels in which <application>Ingres</application>
should <emphasis>start</emphasis>:</para>
<programlisting>
# ln -s /etc/rc.d/init.d/ingres /etc/rc.d/rc2.d/S99ingres
# ln -s /etc/rc.d/init.d/ingres /etc/rc.d/rc3.d/S99ingres
# ln -s /etc/rc.d/init.d/ingres /etc/rc.d/rc4.d/S99ingres
# ln -s /etc/rc.d/init.d/ingres /etc/rc.d/rc5.d/S99ingres
</programlisting>
<para>It is not important to call the links <filename>K01ingres</filename>
and <filename>S99ingres</filename>, the point is that the name starting with
<constant>K</constant> should contain a small number (so that
<application>Ingres</application> stops early when changing to a lower
runlevel) and the name starting with <constant>S</constant> should contain
a large number (so that <application>Ingres</application> starts after
everything else has started).
Naturally, the file names must not clash with names of existing files.</para>
<para>If you have a <acronym>BSD</acronym> style <command>init</command>,
put the following lines into <filename>/etc/rc.d/rc.local</filename>:</para>
<programlisting>
echo "Starting <application>Ingres</application>"
su - ingres -c "ingstart"
</programlisting>
<para>This will start <application>Ingres</application>.
(As a matter of fact, you can use <filename>/etc/rc.d/rc.local</filename>
even if you have a System V style <command>init</command>.)</para>
<para>To stop <application>Ingres</application> automatically, create a file in
<filename class="directory">/etc/shutdown.d</filename>
(call it, say, <command>ingres</command>) that contains the commands:</para>
<programlisting>
echo "Stopping <application>Ingres</application>"
su - ingres -c "ingstop"
</programlisting>
<para>No matter which type your system is, the files you create must be
executable files, owned by root.</para>
<para>Naturally, if your system provides a utility for configuring programs
to start and stop automatically (such as <command>chkconfig</command> in
RedHat), use that if you wish.</para>
</sect2>
<sect2 id="ingmenu" xreflabel="ingmenu">
<title>ingmenu</title>
<para>The easiest way to access an <application>Ingres</application> database
(at least, for beginners) is via the <command>ingmenu</command> program.
From <command>ingmenu</command>, you can reach
<application>Ingres</application>' forms-based utilities, by which you can
create, update and query tables, create, edit and run reports and
<acronym>ABF</acronym> or <application>Vision</application> applications.
Its usage is:</para>
<programlisting>
$ ingmenu test
</programlisting>
<para><database>Test</database> is the name of the database.</para>
</sect2>
<sect2 id="circum" xreflabel="Circumventing Ingres Net">
<title>Circumventing Ingres Net</title>
<para>Without Ingres/Net, in theory it is not possible for
<application>Ingres</application> applications to access databases on
different machines.
However, there exists a method, not supported by <acronym>CA</acronym>, by which
sometimes you can come around this problem.</para>
<para>Let us suppose your application runs on host ingdev and the database
(called <database>test</database>) you would like to update or query resides
on host ingserv.
Your first task is to find out the port number of the appropriate
<acronym>DBMS</acronym> server running on ingserv.
You can use <command>ipm</command> for this purpose: as ingres, start
<command>ipm</command> on ingserv and choose option
<guimenuitem>Server List</guimenuitem>.
In the list of servers select one that is of type <constant>INGRES</constant>
and handles the <database>test</database> database (you have to see either
<constant>test</constant> or <constant>ALL</constant> in column
<varname>Connecting to Databases</varname>).
You find the port number of the <acronym>DBMS</acronym> server in the
first column.
Let us suppose it is 1259.</para>
<para>On machine ingdev, set the shell variable <envar>II_DBMS_SERVER</envar>
in the following way:</para>
<programlisting>
$ export II_DBMS_SERVER='ingserv::1259'
</programlisting>
<para>Now run the command:</para>
<programlisting>
$ sql test
</programlisting>
<para>If it works, you have access to the <database>test</database> database
on host ingserv.</para>
<para>This solution is applicable only if both machines are of the same
architecture, the same operating system is running on both of them, the
character set is the same in both <application>Ingres</application>
installations, and so on: I do not know the full list of necessary conditions.
Therefore, I cannot guarantee that this trick will work.</para>
<para>On the other hand, if you restart <application>Ingres</application>
on host ingserv, the <acronym>DBMS</acronym> server process will get a
different <acronym>TCP/IP</acronym> port, therefore you probably have to
automate the fetching of the current port number to the application server.
You can use the <command>show</command> command of the
<command>iinamu</command> utility for this purpose.
The following command line gives the port number of the <acronym>DBMS</acronym>
server if there is only one server running:</para>
<programlisting>
$ echo show | iinamu | grep INGRES | tr -s ' ' '\t' | cut -f4
</programlisting>
</sect2>
<sect2 id="forms" xreflabel="Forms-Based Development Tools">
<title>Forms-Based Development Tools</title>
<para>The <application>Ingres</application> installation includes a sample
application, created by <acronym>ABF</acronym>,
the traditional development tool of <application>Ingres</application>.
You can load it with the <command>abfdemo</command> command.
Unfortunately, the manuals of <acronym>ABF</acronym>
and <application>Vision</application> cannot be found either
on the <application>Ingres</application> CD or on the
<acronym>CA</acronym> site.</para>
<para>There is a problem with the <acronym>SDK</acronym> under glibc 2.1:
applications created by <acronym>ABF</acronym> or
<application>Vision</application> cannot be either compiled or run directly
from the database.
This problem is solved in the full <application>Ingres</application> version.
For the <acronym>SDK</acronym>, install the RedHat glibc 2.0 compatibility
packages.
If you do not have RedHat, download them from the following
<acronym>URLs</acronym>:
</para>
<itemizedlist>
<listitem>
<para><ulink URL="ftp://ftp.redhat.com/pub/redhat/redhat-6.0/i386/RedHat/RPMS/compat-binutils-5.2-2.9.1.0.23.1.i386.rpm">
ftp://ftp.redhat.com/pub/redhat/redhat-6.0/i386/RedHat/RPMS/compat-binutils-5.2-2.9.1.0.23.1.i386.rpm</ulink></para>
</listitem>
<listitem>
<para><ulink URL="ftp://ftp.redhat.com/pub/redhat/redhat-6.0/i386/RedHat/RPMS/compat-egcs-5.2-1.0.3a.1.i386.rpm">
ftp://ftp.redhat.com/pub/redhat/redhat-6.0/i386/RedHat/RPMS/compat-egcs-5.2-1.0.3a.1.i386.rpm</ulink></para>
</listitem>
<listitem>
<para><ulink URL="ftp://ftp.redhat.com/pub/redhat/redhat-6.0/i386/RedHat/RPMS/compat-glibc-5.2-2.0.7.1.i386.rpm">
ftp://ftp.redhat.com/pub/redhat/redhat-6.0/i386/RedHat/RPMS/compat-glibc-5.2-2.0.7.1.i386.rpm</ulink></para>
</listitem>
<listitem>
<para><ulink URL="ftp://ftp.redhat.com/pub/redhat/redhat-6.0/i386/RedHat/RPMS/compat-libs-5.2-1.i386.rpm">
ftp://ftp.redhat.com/pub/redhat/redhat-6.0/i386/RedHat/RPMS/compat-libs-5.2-1.i386.rpm</ulink></para>
</listitem>
</itemizedlist>
<para>Besides the compatibility packages, you need an
<application>Ingres</application> patch.
It was posted on the <ulink url="news:comp.databases.ingres">
<application>Ingres</application> newsgroup</ulink> in September, 1999.
I have a copy of it, email me if you wish to install it.</para>
<para>The compatibility packages and the patch probably do not work for all
Linux distributions.
I only tested them on RedHat and Caldera Open Linux.</para>
</sect2>
<sect2 id="perl" xreflabel="Ingperl and Perl DBI">
<title>Ingperl and Perl DBI</title>
<para>Previous <application>Perl</application> versions, version 4 included,
made <application>Ingres</application> access possible via libraries known
as ingperl.
You can find information on ingperl at
<ulink url="http://www.contrib.andrew.cmu.edu/~lfm/ingperl.html">
http://www.contrib.andrew.cmu.edu/~lfm/ingperl.html</ulink>.</para>
<para>In <application>Perl 5</application> a new, unified database
interface, called <application>Perl</application> <acronym>DBI</acronym>,
appeared.
Its site is
<ulink url="http://www.symbolstone.org/technology/perl/DBI/index.html">
http://www.symbolstone.org/technology/perl/DBI/index.html</ulink>.</para>
<para>You can download the <application>Ingres</application>
module of <acronym>DBI</acronym> from that site.</para>
</sect2>
<sect2 id="links" xreflabel="Ingres links">
<title>Ingres links</title>
<para>I leave you with a few pointers to important
<application>Ingres</application> sites:</para>
<itemizedlist>
<listitem>
<para><ulink url="http://www.cai.com/ingres/">
http://www.cai.com/ingres/</ulink>:
home page of the <application>Ingres RDBMS</application> on
<acronym>CA</acronym>'s site.</para>
</listitem>
<listitem>
<para><ulink url="http://support.cai.com/ingressupp.html">
http://support.cai.com/ingressupp.html</ulink>:
<application>Ingres</application> Technical Support.</para>
</listitem>
<listitem>
<para> <ulink url="http://www.cai.com/ingres/inquire/">
http://www.cai.com/ingres/inquire/</ulink>:
inquire_ingres: <application>Ingres</application> technical
magazine.</para>
</listitem>
<listitem>
<para><ulink url="http://www.naiua.org/faqs.html">
http://www.naiua.org</ulink>: the North American Ingres Users
Association's site.
Check the <acronym>FAQ</acronym> page, and the
<filename class="directory">/papers</filename> directory.</para>
</listitem>
<listitem>
<para><ulink url="news:comp.databases.ingres">
news:comp.databases.ingres</ulink>: the
<application>Ingres</application> newsgroup.</para>
</listitem>
<listitem>
<para><ulink url="http://www.deja.com/group/comp.databases.ingres">
http://www.deja.com/group/comp.databases.ingres</ulink>: the
archived <application>Ingres</application> newsgroup on Deja.</para>
</listitem>
<listitem>
<para><ulink url="http://munkora.cs.mu.oz.au/~yuan/Ingres/ingres.html">
http://munkora.cs.mu.oz.au/~yuan/Ingres/ingres.html</ulink>: William
Yuan's <application>Ingres</application> Reference Page with lots of
<application>Ingres</application> information.</para>
</listitem>
<listitem>
<para><ulink url="http://www.mercurie.co.uk/ingres/">
http://www.mercurie.co.uk/ingres/</ulink>: Prijesh Patel's Unofficial
<application>Ingres</application> Web Page with edited posts from the
<application>Ingres</application> newsgroup.</para>
</listitem>
<listitem>
<para><ulink url="http://www.palslib.com/Ingres_II/Ingres_II.html">
http://www.palslib.com/Ingres_II/Ingres_II.html</ulink>: the
<application>Ingres</application> section of Pal's Linux RDBMS
Library.</para>
</listitem>
</itemizedlist>
<para>Have fun!</para>
</sect2>
</sect1>
</article>
View Git Blame Copy Permalink