Installating Perl modules for DBIx::Perform
-------------------------------------------
Need a working installation of Informix.

Downloads
---------
ncurses         http://ftp.gnu.org/pub/gnu/ncurses/ncurses-5.6.tar.gz

The downloads below are from http://search.cpan.org/CPAN/authors/id/

Curses		G/GI/GIRAFFED/Curses-1.15.tgz
CursesWidgets	C/CO/CORLISS/CursesWidgets-1.997.tar.gz
CursesForms	C/CO/CORLISS/CursesForms-1.997.tar.gz
CursesApplication	C/CO/CORLISS/CursesApplication-0.2.tar.gz
ExtUtils-AutoInstall	A/AU/AUTRIJUS/ExtUtils-AutoInstall-0.63.tar.gz
Pod-Escapes	S/SB/SBURKE/Pod-Escapes-1.04.tar.gz
Pod-Simple	A/AR/ARANDAL/Pod-Simple-3.05.tar.gz
Test-Simple	M/MS/MSCHWERN/Test-Simple-0.70.tar.gz
Test-Pod	P/PE/PETDANCE/Test-Pod-1.26.tar.gz
DBI		T/TI/TIMB/DBI-1.58.tar.gz 
DBD		J/JO/JOHNL/DBD-Informix-2007.0226.tar.gz
YAML		I/IN/INGY/YAML-0.65.tar.gz
ParseRecDescent		D/DC/DCONWAY/Parse-RecDescent-1.94.tar.gz

Extras needed for HPUX:
Scalar-Utils	G/GB/GBARR/Scalar-List-Utils-1.19.tar.gz
Test-Harness	P/PE/PETDANCE/Test-Harness-2.64.tar.gz
Text-Balanced   D/DC/DCONWAY/Text-Balanced-v2.0.0.tar.gz
version         J/JP/JPEACOCK/version-0.7203.tar.gz

Optional:
Sort-Versions	E/ED/EDAVIS/Sort-Versions-1.5.tar.gz
Time-Hires      J/JH/JHI/Time-HiRes-1.9707.tar.gz

Commands in gory detail
-----------------------

These commands were used on Red Hat Enterprise Linux 4
(Linux kernel version 2.6.9-55.ELsmp) with Informix SE 7.25,
perl 5.8.5, and gcc 3.4.6.

# cd /usr/include
# rm curses.h ncurses.h form.h menu.h panel.h

$ tar xzf Curses-1.15.tar.gz
$ cd Curses-1.15
$ perl Makefile.PL PANELS MENUS FORMS
$ make
$ sudo make install
$ cd ..

$ tar xzf CursesWidgets-1.997.tar.gz
$ cd CursesWidgets-1.997
$ perl Makefile.PL
$ make
$ sudo make install
$ cd ..


$ tar xzf CursesForms-1.997.tar.gz
$ cd CursesForms-1.997
$ perl Makefile.PL
$ make
$ sudo make install
$ cd ..

$ tar xzf CursesApplication-0.2.tar.gz
$ cd CursesApplication-0.2
$ perl Makefile.PL
$ make
$ sudo make install
$ cd ..

$ tar xzf DBI-1.56.tar.gz 
$ cd DBI-1.56
$ perl Makefile.PL
$ make
$ sudo make install
$ cd ..

$ tar xzf ExtUtils-AutoInstall-0.63.tar.gz
$ cd ExtUtils-AutoInstall-0.63
$ perl Makefile.PL; make
$ sudo make install
$ cd ..

$ tar xzf Pod-Escapes-1.04.tar.gz
$ cd Pod-Escapes-1.04
$ perl Makefile.PL
$ make
$ sudo make install
$ cd ..

$ tar xzf Pod-Simple-3.05.tar.gz
$ cd Pod-Simple-3.05
$ perl Makefile.PL
$ make
$ sudo make install
$ cd ..

$ tar xzf Test-Simple-0.70.tar.gz
$ cd Test-Simple-0.70
$ perl Makefile.PL
$ make
$ sudo make install
$ cd ..

$ tar xzf Test-Pod-1.26.tar.gz
$ cd Test-Pod-1.26
$ perl Makefile.PL
$ make
$ sudo make install
$ cd ..

$ dbaccess
Password:
DBACCESS:   Database
DATABASE:   Create
CREATE DATABASE >>stores
CREATE DATABASE:  Exit
EXIT:   Create-new-database

$ tar xzf DBD-Informix-2007.0226.tar.gz
$ cd DBD-Informix-2007.0226
$ perl Makefile.PL
$ make
$ sudo make install

$ tar xzf YAML-0.62.tar.gz
$ cd YAML-0.62
$ perl Makefile.pl
Continue installing YAML.pm? [y]
$ make
$ sudo make install
$ cd ..

$ tar xzf Parse-RecDescent-1.94.tar.gz
$ cd Parse-RecDescent-1.94
$ perl Makefile.pl
$ make
$ sudo make install
$ cd ..


$ tar xjf DBIx-Perform-0.692.tar.bz2
$ cd DBIx-Perform-0.692.tar.bz2
$ perl Makefile.pl
$ make
$ sudo make install
$ cd ..


------------------------------------------------------------------------
HP-UX installation

The setup used for this installation may be atypical and much of the
following may not apply to another HP-UX system.

The system is HP-UX 11.11, with Informix (IBM Informix Dynamic Server
Version 10.00.HC4) in /usr/informix, and perl 5.6.1.
gcc 3.4.6 and ncurses are installed in /usr/local/bin.

Ncurses can be built with the native compiler.  But, must make one change.
NCURSES_INLINE does not work with the native compiler.  The configuration
script detects that the compiler does support "inline" and sets
NCURSES_INLINE=inline, which causes a compiler error on any line
in the ncurses source that contains NCURSES_INLINE.
Editing the ncurses configuration script to remove the test for inline is
one way around this problem.


$ gzip -d < ncurses-5.6.tar.gz
$ cd ncurses-5.6

Delete these lines from "configure":

if test "$ac_cv_c_inline" != no ; then
        cat >>confdefs.h <<\EOF
#define CC_HAS_INLINE_FUNCS 1
EOF

        NCURSES_INLINE=inline
fi

$ ./configure;make;make
$ su
# make install
$ cd ..



# cd /usr/include
# rm curses.h ncurses.h form.h menu.h panel.h

$ export PATH=/usr/local/bin:$PATH
$ export CURSES_CFLAGS="-I/usr/local/include/ncurses"
$ export CURSES_LDFLAGS="-L/usr/local/lib -lncurses"

$ gzip -d < Curses-1.15.tar.gz | tar xf -
$ cd Curses-1.15
$ perl Makefile.PL PANELS MENUS FORMS
$ make
$ su
# make install
$ cd ..

$ gzip -d < Scalar-List-Utils.tar.gz | tar xf -
$ cd Scalar-List-Utils
$ perl Makefile.PL
For HP-UX "make", edit line 282 of Makefile, changing
  XSUBPPARGS +=  -typemap mytypemap
to
  XSUBPPARGS = $(XSUBPPARGS) -typemap mytypemap
$ make
$ su
# make install
$ cd ..

Need Test-Harness before Test-Simple.
Need Test-Simple before DBI.

$ gzip -d < DBI-1.56.tar.gz | tar xf -
$ cd DBI-1.56
$ perl Makefile.PL
$ make
$ make
$ su
# make install
$ cd ..

Need "version" before Text-Balanced.

Now things get strange.  /usr/informix/bin/esql uses the native compiler.
To use gcc, I backed up /usr/informix/bin/esql to /usr/informix/bin/esql.hp
and copied esql from an installation of Informix 7.25 on a Linux system
to /usr/informix/bin/esql.gcc and modified it.
(Point esql to esql.gcc with ln -s or just copy esql.gcc to esql.)
The differences from /usr/informix/bin/esql.hp are:


$ diff /usr/informix/bin/esql.gcc /usr/informix/bin/esql.hp
26,30c26,30
< CC="${INFORMIXC=/usr/local/bin/gcc} -lxti -lsec"
< CC_TH="${INFORMIXC=/usr/local/bin/gcc} -lxti -lsec"
< CPP="${INFORMIXCPP=CC} "
< CPP_TH="${INFORMIXCPP=CC} "
< STATICFLAGS=""
---
> CC="${INFORMIXC=cc} +DS2.0 +DA1.1"
> CC_TH="${INFORMIXC=cc} +DS2.0 +DA1.1"
> CPP="${INFORMIXCPP=aCC} +DS2.0 +DA1.1"
> CPP_TH="${INFORMIXCPP=aCC} +DS2.0 +DA1.1"
> STATICFLAGS="-Wl,+n"
36c36
< CC_AMD32="-m32"
---
> CC_AMD32=""
215,217c215,217
< SYSLIB="-lc -lm -lcrypt "
< SYSNLIB=""
< TLILIB="/usr/lib/libnsl.a /usr/lib/libnsl.so"
---
> SYSLIB="-lm -lsec -lnsl_s "
> SYSNLIB="-lnsl_s "
> TLILIB="/usr/lib/libnsl_s.a  /usr/lib/libnsl_s.sl"
350c350
<                THRLIB="$TLIB -lpthread"
---
>                THRLIB="$TLIB "
378,379c378,379
<             SYSTHRLIB="-lc -lm -lcrypt "
<             SYSTHRNLIB="-lpthread"
---
>             SYSTHRLIB="-lm -lsec -lnsl_s "
>             SYSTHRNLIB=""
439c439
<             THRLIB="$TLIB -lpthread"
---
>             THRLIB="$TLIB "
442c442
<                 if [ ! -f /usr/lib/lib$THLIB_SUB.so ]
---
>                 if [ ! -f /usr/lib/lib$THLIB_SUB.sl ]
804c804
<                 cpinput=$base.pcp.c
---
>                 cpinput=$base.pcp
808c808
<                 cpinput=$base.pcp.c
---
>                 cpinput=$base.pcp
825c825
<                 rm -f $base.tmp $base.pcp.c
---
>                 rm -f $base.tmp $base.pcp


Once the modified esql is in place, then can make the DBD-Informix
Perl module in HP-UX:

$ tar xzf DBD-Informix-2007.0226.tar.gz
$ cd DBD-Informix-2007.0226
$ perl Makefile.PL
$ make
$ su
# make install


=========================================================================
"make test" has not been updated, and will likely print many errors.

=========================================================================

USAGE
"make install" installs scripts "pformbld" and "perform".
To run a Perform script "example.per", 1st have appropriate environment
variables set for the database.  The crucial one is DB_NAME.


Here is an example of the environment variables needed for Informix 7.2:
$ export DB_HOST=$(hostname)
$ export DBPATH=/usr/informix
$ export DB_NAME=mydatabase
$ export DB_CLASS=Informix
$ export DB_USER=informix
$ export DB_PASSWORD=mydbpasswd
$ export DBD_INFORMIX_USERNAME=informix
$ export DBD_INFORMIX_PASSWORD=$DB_PASSWORD
$ export DBD_INFORMIX_PASSWORD2=$DB_PASSWORD
$ export DBD_INFORMIX_USERNAME2=informix

Might also need to set the terminal:
$ export TERM=vt100

And these are optional:
$ export BGCOLOR=blue
$ export FIELDBGCOLOR=blue
$ export DBDATE="Y4MD-"


The 2nd step need only be done once.  Create "example.yml" with:

$ pformbld example.per


3rd, run the script with:

$ perform example


Lastly, if the script calls external C functions, will need to build
a C executable.  For details, read the comments at the head of 
Perform/src/perl_perform_tools.c.  Once a source file "cfuncs.ec" with
the external functions is compiled to an executable "cfuncs", the
Perform script can be run with those functions with an extra parameter:

$ perform example cfuncs

=========================================================================

Known problems
==============

problems
--------

On scripts that have "forests", (meaning, 2 or more groups of tables which
are not joined to one another in any of the field associations), and which
lookup data from the same tables, there can be "spillover".  That is,
suppose there are 3 tables t1, t2, and t3.  t1 and t2 are not joined,
but both t1 and t2 "lookup" data from t3.  Then if the user does a query on
t1, data for fields associated with looking up t3 when joined to t1 may be
displayed in both fields that join t1 and t3 in a lookup, and fields that join
t2 and t3 in a lookup.

Joins aren't always looked up.  (May only be composite joins, not sure.)
Lookups are done whenever the user enters data in an associated field.
That is, suppose there are tables, t1 and t2, with various columns, and
2 fields f1 and f2.  Take the following:
f1 = t1.c1 lookup f2 = t2.c2 joining t1.c1 = t2.c1
When the user enters a value in f1, the program checks the join for a
value from t2.c1 that matches the user's newly entered value for t1.c1 and
if found, "looks up" t2.c2 from the same row where the matching t2.c1 was
found and fills in f2 with the value from t2.c2.  This part works.
A composite join is merely a join between more than one column of 2 tables.
It seems the program is also supposed to fill in values on
composite joins that are not lookups, as in this:
f1 = t1.c1 = t2.c1;
f2 = t1.c2 = t2.c2;
f3 = t2.c3
When the user enters data in f1 and f2, the program should fill in f3,
but does not.

minor problems
--------------
After a big slow query, the next query is slow.  After fetching something
like 100,000 rows, the next query will be as slow even if it only fetches
1000 rows.  If instead, only the smaller query is run, it will be fast.
If the 1st query is run and then the 2nd query is run twice, the 2nd
time on the 2nd query will be fast.

Some queries with lookups can be slow.  Each query can actually result
in several queries being made, and some of those fetch all rows from
another table to do a lookup.  If the looked up table has many rows,
then the process can be slow.

May have different behavior on fields with the "picture" attribute.
Sperform does not do the "picture" attribute correctly.

trivial problems
----------------
Different behavior if wildcards are put in a "serial only" field for
a query.  sperform gives "Error in field" and stays in the field.
DBIx::Perform tries to run the query, gets and reports a DB error,
and returns to the main menu.

Reverse color fields on any screen but the first aren't always displayed
reversed.  Depends on the TERM environment variable.  (And yet the reverse
coloring always works on the first screen?)

When running under another user acct, somehow Perl was including my
sandbox in its libraries path, @INC.  Worked around this by removing
all group and world permission to that directory of mine.  Think it's not
a problem with DBIx::Perform, but with the environment.

