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

Downloads
---------
All downloads 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

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.

# 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
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" copies scripts "pformbld" and "perform" to /usr/local/bin.
To run a Perform script "example.per", 1st have appropriate environment
variables set for the database.  If the environment is not set may get an
error message similar to:

install_driver(PG) failed: Can't locate DBD/PG.pm in @INC ...


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 (either blue or black give good results):
$ export BGCOLOR=blue
$ export FIELDBGCOLOR=blue


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
--------

The Table button does not change screens.  This is, of course, only
relevant on scripts that have 2+ screens and 2+ tables.  It's not always
clear why sperform chooses a particular screen.  Going to the first screen
that has a field that is associated with the newly focused table results
in picking the same screen as sperform in most cases but not all.  In
the case that differed, the script has a field on the first screen
that joins the 2 tables in question, then the rest of the fields on that
screen are associated with the 1st table.  The first field associated with
only the 2nd table is on the 2nd screen.  There is also an instruction that,
upon an attempt to manipulate the 2nd table, moves the focus to a field on
the 2nd screen.  And lastly, the field on the first screen that joins the
2 tables is duplicated on the 2nd screen.
So there are at least 3 alternatives that would result
in landing on the 2nd screen-- go to the first screen containing a field
associated with only the 2nd table, or go to the screen that contains the
first field entered when the user tries to manipulate the 2nd table, or
go to the first screen that contains a field associated with the
2nd table that is not duplicated on all previous screens.

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.

Concurrency checks.  Seems the original utility at times checks the
data it retrieves to make sure it hasn't been changed by anything else,
such as another invocation of the utility operating on the same tables.
Hard to know when these checks are made, but is more often than upon
trying to do Update or Add.  Checking is also done when the user tries
Next or Previous.  Currently, no checking is done.  Presumably the
database will catch all such problems, but this should be tested more.

minor problems
--------------
Comments are converted to uppercase.

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.

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?)

On the main menu, up and down arrow keys should go to the first menu item
on the previous and next menu row respectively.  DBIx::Perform does nothing.

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.

