Eloquence QUERY3K utility

&nbsp

The Eloquence QUERY3K utility is intended as a replacement for the
MPE QUERY/iX utility. QUERY3K is designed to be closely compatible
and to require only minimal changes to existing QUERY scripts.
However, as QUERY3K does not run on top of MPE some minor changes
may be required to adapt your existing QUERY scripts to the system
environment.

Please refer to the section titled "Known problems/limitations" below
for any known issues and platform-specific notes.

The Eloquence QUERY3K executable is called query3k and located
in the bin subdirectory of your Eloquence installation. The Eloquence
installation should have added this directory to your PATH.

With QUERY3K as with the original QUERY commmands are passed
through stdin, either interactively or by redirecting stdin from
a file. As with QUERY input files must in ASCII format and may
have line numbers. Any information past column 72 is ignored.

On MPE QUERY may be used interactively or with a script file as
below:

The QUERY3K output may be redirected by using the QSLIST or
LP environment variables. If both are specified the QSLIST
environment variable takes precedence.

The QSLIST environment variable by default specifies the name
of an output file. The LP environment variable by default
specifies a process to send the output to (such as the spooler).
If neither is defined, any O=LP output is sent to the default
printer queue (equivalent to LP=lp or LP=qlp on Windows).

This is a rough equivalent to file equations on MPE. Any of
the environment variables may be set as below:

QSLIST=">outfile"

This causes the output (in case of O=LP) to be redirected
to the file outfile. In case the file exists it is replaced.

QSLIST=">>outfile"

This causes the output (in case of O=LP) to be appended
to the file outfile. In case the file does not exist it
is created.

QSLIST="|lp"

This causes the output (in case of O=LP) to be sent to the
specified command (using a pipe). On the Windows platform
the qlp command may be used as a replacement for lp.

A typical definition for the LP environment variable on HP-UX
or Linux would be something like below:

LP="lp -onb -s -dprinter 2>/dev/null"

On the Windows platform the equivalent is:

LP="qlp -s -dprinter"

This sends the output to the printer queue "printer", suppresses
the printing of banner pages, does not output the print job id
on the screen and discards any spooler error messages.

Please note that environment variables need to be set before
executing query3k (possibly marked as "exported" by the command
shell) and cannot be defined in the QUERY script.

QUERY3K performs a partial evaluation of the :FILE command
and supports a limited equivalant of the MPE "file equation".
This might be used to specify the QUERY3K output (QSLIST) or
file access from QUERY3K (eg. through XEQ).
The :RESET and :LISTEQ commands are also supported in addition
to :FILE.

The following syntax is recognized:

:FILE <designator>=<file reference>[;DEV={DISC|LP}]

Where <designator> specifies a logical file name
and <file reference> specifies the path/name of a file (with an
optional open mode). It may also specify an operating system
command that any output is sent to.
Additional parameters may be present and are ignored.

Unless specified with a DEV=LP clause, any file equation will
default to specify a file (DEV=DISC is implied).

The following examples specify different targets for the QSLIST
file that is used by QUERY3K to specify the printer output.

:FILE QSLIST=report.txt

Send the output to the file report.txt

:FILE QSLIST=report.txt;DEV=DISC

Same as above

:FILE QSLIST=">>report.txt"

Append the output to the file report.txt

:FILE QSLIST="|pr -2 -h 'QUERY3K output'|lp -s 2>/dev/null"

Send the output to the specified command. This example causes
output to be formatted in two columns and then printed.

:FILE QSLIST=lp;DEV=LP

Send the output to the printer (as specified with the LP
environment variable).

A similar result may be achieved by specifying environment
variables _before_ starting QUERY3K.

Any QUERY command starting with a colon (:) is passed to the
command processor (with the exception of the :FILE end related
commands). Consequently, any MPE commands that are used in a
QUERY script are unlikely to work and must be replaced with their
POSIX equivalents.

For example:

:PURGE SAREPORT
:PAUSE 5

would become

:rm SAREPORT
:sleep 5

File equations defined with the :FILE command are not
accessible to operating system commands.

The following won't work:

:FILE REPORT=report.txt;DEV=DISC
:rm REPORT

In this example, the rm command will attempt to remove the
file REPORT.

However environment variables defined before starting QUERY3K
are accessible to operating system commands and may be used
in QUERY3K as well. For example:

$ export REPORT=report.txt
$ query3k
XEQ REPORT
:rm $REPORT

Defining environment variables does not work in a QUERY3K script
(for example using the :set or :env commands).
As environment variables are process specific (not session
specific) and may only be passed from parent to a child process
a subshell can't define environment variables for its parent
(such as QUERY3K). Any environment variables must be set before
QUERY3K is started.

Limitations for database names and file names are the same
as on MPE. A database name may only have 6 chanacters (plus
8 for a group and account, separated by a dot). The same
limitation applies for any file names specified in QUERY3K.
As on MPE, POSIX file names currently can typically not be used.

Using environment variables or file equations may be used as a
workaround.

As on MPE, the command line is truncated after 71 characters.

An error message like below is returned in case a problem is
detected passing the O=LP output as specified by the QSLIST
and LP environment variables.

>O=LP
>O=TERM
lp: standard input is empty
lp: request not accepted

In this case the lp command complains about that it did not receive any
data and returns an error.

Hint: Specifying the option -s to lp or redirecting stderr for the
lp command will suppress this message (QSLIST="|lp -s").

The current QUERY3K implementation does not support
user defined procedures in the REPORT statement (see Appendix F
of the QUERY/iX manual for details).

We may consider to add this functionality to QUERY3K in a
future version. Please send us some feedback if you depend on
this function.

On Windows the qlp program may be used as a replacement for the
HP-UX/Linux lp command. It works similar and submits either stdin
or any named files to the spooler in a raw format.
By default, printing will use the default Windows printer. A different
printer may either be specified with the -d command line option to qlp
or by setting the QLPDEST or LPDEST environment variables.

The QUERY3K SAVE command (to create SD files) is currently only
supported on HP-UX. The file created is endian and character set
specific and not portable across platforms. As the SD file
format does not specify charcter set encoding or byte order this
is unlikely to change.

QUERY3K currently uses a fixed default character set encoding for
each platform. On HP-UX this is HP-Roman8, on Linux ISO-8859-1
and on Windows CP1252 (Latin1) is used.
We consider to add an option to allow specifying the character
set encoding in a future release.

On Windows it is required to set the console font to a TrueType
font (such as "Lucida Console") to get the correct output for
non-ASCII characters. By default the console Window uses a
bitmapped font that does not support the CP1252 code page.
To change the font, please start QUERY3K, open the settings and
change the font. Then apply the change to all windows of that
name.

If the printer is configured for a different character set than
used by QUERY3K the output of any non-ASCII characters will be
wrong.

Windows 95 has a limitation that prohibits switching the command
window to a different code page. If necessary this could be
done with the mode command like below:

Switch to CP1252 encoding:

> mode con: cp select=1252

Restore console to use CP850 or CP437 encoding:

> mode con: cp select=850
> mode con: cp select=437

The FIND ... MATCH function is currently inconsistent among the
different platforms and NLS configurations. It depends on the
locale settings if non-ASCII characters (Umlaute) are considered
letters or not and if lower/upper case characters are considered
seperate.

If the Backspace key does not work on Linux then please verify
your stty erase settings. It must match your terminal
configuration (for example erase="^H").

QUERY3K returns a nonzero exit code when it was terminated due
to an error (similar to the MPE JCW).

Entering a password in query3k does not have any effect (#2598).
While specifying a password with a username should be possible it
is not accepted query3k.
Please use the EQ_DBUSER and/or EQ_DBPASSWORD environment
variables as an alternative.

QUERY3K is based on the original Query/iX sources that were converted to C
(using Splash!) and
modified for portability. We would like to thank Allegro Consultants for their help.

This software and documentation is based in part on HP software and
documentation under license from Hewlett-Packard Company.
HP is a trademark of Hewlett-Packard Company.
Parts of this software are Copyright 2004 Development Company, L.P.

Fixed a number of problems related to the JOIN command and
using indexed access on Little Endian platforms (Linux, Windows).

Fixed a problem with calling DBINFO 812 improperly that might
result in returning a status -21 on little endian platforms.

Fixed a problem where some E4 values could result in
a field overflow during output (#3287).
Some values (such as -1000) could in some cases result in a
field overflow due to a rounding problem while estimating the
number of significant digits.

The FORM SETS command was changed to suppress outputting the
MAXIMUM CAPACITY if the output would be the Eloquence default.
As all Eloquence data sets are considered to have a dynamic
"capacity" this would otherwise clutter the output without
providing any additional information.

QUERY3K was enhanced to improve support of the Eloquence
database limits that exceed the previous TurboIMAGE limits.

This release should now support

Record size of up to 5120 bytes

2048 items per database

500 data sets

1024 items per set.

The item type 'B' (binary) is now mapped to 'X'.

String items with more than 255 bytes per subitem are not yet
fully supported and may result in undefined behavior.

The QUERY3K version number was changed to B.07.10.04 (20070216),
the Windows file revision was changed to 7.10.0.4

The following changes were incorporated in the B.07.10 QUERY3K release:

QUERY3K was changed to use documented image3k entry points.

The QUERY3K version number was changed to 20060112, the Windows
file revision was changed to 7.1.0.2.

The following changes were incorporated in QUERY3K-B0710-B4:

Fixed a problem with the SD file format (#2819). The SD file
created with the save command was incorrect and caused SUPRTOOL
to abort.
NOTE: SD files are currently incompatible across platforms
(byte order dependend) and were only tested on HP-UX.

The QUERY3K version number was changed to 20050922, the Windows
file revision was changed to 1.0.0.5.

The following changes were incorporated in QUERY3K-B0710-B3:

Fixed a problem in the report ADD function that could lead to
an arithmetic overflow (#2800). This could result in an error
message like below:

PAC failure, call 5, status 1
ARITHMETIC OVERFLOW ON R0

This problem was caused by a bug in the HPPACADD intrinsic
replacement that could lead to an arithmetic overflow with
certain values.

The QUERY3K version number was changed to 20050909, the Windows
file revision was changed to 1.0.0.4.