README for SETIXD and Related Programs
======================================

This software is made available to the IIUG following a discusion in the
comp.databases.informix news group in February 2005, under the subject
'Recommended Install Order'.

Jonathan Leffler wrote:
Have you considered using two separate INFORMIXDIRs - one for the
server, and a separate one for the tools?  This obviates the install
order issue - you install the tools in whatever order you like in their
INFORMIXDIR, and IDS in its own separate INFORMIXDIR.

David Grove asked:
Then what about the INFORMIXDIR environment var?  One would then have to
set it every time, depending on what one purposed to do during a
specific user session, right?

Jonathan Leffler responded:
Yes.  The ordinary users would set INFORMIXDIR to the tools directory
and never need the administration tools.

Administrators have to think more carefully - but database and system
administrators are paid (in general) to think carefully.   Generally
speaking, if you are administering the system, and if you have I-Connect
installed along with the server, and you have any home-built toolsstored
in a suitable alternative directory (like $HOME/bin, or
$INFORMIXDIR/adm, or /usr/local/bin -- somewhere that is on your PATH),
then you can use those anyway.  If you're building applications, then
you are (for the time being) a user and not an administrator.   This is
called 'role separation'; it involves the administrator recognizing that
even though they are one individual, they have more than one role with
respect to the database, and those different roles can require different
settings.

And it is not (all that) hard to set things up so that switches between
the various environments are simple.  I do it all the time.

$ . 9.40.UC5 
...work with IDS 9.40.UC5 
$ . 10.00.UC1 
...work with IDS 10.00.UC1 
$ . 7.31.UD7 
...work with IDS 7.31.UD7

And each time, the environment is clean - that is, setting the 10.00.UC1
environment cleans out all the stuff related to 9.40.UC5, rather than
continuously growing the environment.

OK - that took me some effort to set up a number of years ago.  But I'm
still using the same basic code that I created in, oh, 1997.  I changed
it in 2003 to add version reporting (-V) and tracing (-t); the prior
change was in 1999.  (The version posted here recognizes IDS 10.00 and
was therefore changed in 2005.)

It's a bigger set of programs than at first meets the eye - my tools use
my other tools - but the set is finite and (for me) stable.
  * any of the scripts listed above (they're close to being clones).
  * escape - a C program to preserve spaces in argument lists. 
  * setixd - a complex shell script to set Informix environment. 
  * clnpath - a PATH variable editor script (cleans up duplicates).
  * dbenv - report (key, aka ancient) Informix-related env vars. 
There are some interesting bits of legacy stuff in there - support for
OnLine/SE 4.x, NewEra, ON-Archive environment variables, and others.

The code unpacks into a new directory setixd-3.2.  Running 'make escape'
should build the escape executable (no makefile needed).  It actually
comes with a man page.

Note that the code assumes (by default) that the ONCONFIG file for
server abc is onconfig.abc.  If this is not the way you work, you have
to override the default - you can do so with the command line - or you
have to modify the scripts to follow your local conventions (you do have
a convention, don't you?).

I have a series of non-executable files in $HOME/bin such as 9.40.UC1.
Each one carefully preserves the argument list of the shell (that's
where escape figures), runs setixd with new arguments (casually
destroying the old arg list - it was a puzzle for a while why scripts
that were run by cron completely screwed up when they set the Informix
environment), and then reinstates the previous argument list.

You may be better off basing the names of the top-level environment
setting scripts on the database server rather than the version.  My work
makes version far more important than the server name, but it is not
representative of other people's work.  There's no significance to the
name used in those scripts.

Trivial combinations of these scripts can deal with 64-bit vs 32-bit
versions of CSDK installed separately from the IDS server, and other
such problems.

Several customers who have used separate client and server software is
that although the majority of the applications do not need access to the
IDS commands and utilities, there are typically two that are used:
dbaccess and onstat.  How to work around this?  The first part of the
answer is to keep the server and client INFORMIXDIR separate and clean.
The second part is to create a script in the Client INFORMIXDIR, called
totherixd (for "the other INFORMIXDIR") that contains commands to set
the environment for the Server INFORMIXDIR.  It should then execute the
corresponding command based on the name it is invoked by, remembering to
relay arguments if there are any.  Roughly:

#!/bin/ksh 
# 
# Set INFORMIX environment and execute command. 

# Set IXD to the other INFORMIXDIR
# Use the correct environment-setting script
IXD=/usr/informix/server
. $IXD/etc/server.env

command=$(basename $0 .sh) 
case "$command" in 
dbaccess|onstat) 
    exec $IXD/bin/$command "$@";; 
esac 
echo "Unknown or disallowed command $0" 1>&2 
exit 1 

Note that it is crucial that the server.env script does not interfere
with the command-line options passed to this script.  The case statement
'ensures' that only the commands you want are executed - primarily, it
ensures that if the user tries to run 'totherixd', they get an error
from the tail of the script.  You could not regard this as a security
measure - there is no real enforcement and there are a myriad ways
around it.  Obviously, you could perfectly well locate the environment
setting script in another location altogether - separate from either the
client or server INFORMIXDIR, for example; juggle the details to suit
your environment.  Nevertheless, the general idea is valid - the script
'knows' how to set the server-side INFORMIXDIR (and PATH, and
LD_LIBRARY_PATH, and maybe other variables too), and then runs the real
command from that INFORMIXDIR.

You now create two links (symbolic or hard) in the Client INFORMIXDIR: 
        cd $INFORMIXDIR/bin 
        ln totherixd dbaccess 
        ln totherixd onstat 

Users with the environment pointing to the client INFORMIXDIR now have
commands dbaccess and onstat that actually point to the server
INFORMIXDIR.  The only time users could have problems is if they do a
shell escape from within the DB-Access program (or use vi to edit some
SQL) - the environment would be set to use the server INFORMIXDIR
instead of the client INFORMIXDIR.  Depending on circumstances (such as
'does the server INFORMIXDIR have I-Connect installed') this may or may
not cause minor irritation.  One possibility is to have the converse
script in the Server INFORMIXDIR that points to the Client INFORMIXDIR.

This is a general technique - create surrogate (or wrapper) commands
that set the environment correctly and then run the real program.


Jonathan Leffler <jleffler@us.ibm.com>

@(#)$Id: setixd.README,v 1.1 2006/02/14 19:03:28 jleffler Exp $