Eloquence B.07.10 Release Notes

Overview / Eloquence QUERY3K

Eloquence QUERY3K

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.

This version differs substantially from the B.07.00 QUERY3K version that is available on HP-UX. The original source code is now fully converted to C and was enhanced/fixed to be portable across different platforms. Also some minor bugs were fixed.

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

Please send any feedback or problem reports to the Eloquence support at support@marxmeier.com.

This document describes the differences from the original QUERY version.

The documentation for QUERY/iX is available from the HP web site at the location below:

PDF format:
http://docs.hp.com/en/32650-90889/32650-90889.pdf
HTML format:
http://docs.hp.com/en/32650-90889/index.html

Contents:

Running QUERY3K
Redirecting the output
Using file equations (file name aliases)
File equations in QUERY3K (:FILE, :LISTEQ, :RESET commands)
Example QUERY script
Known problems/limitations
History of Changes

Running QUERY3K

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:

 :RUN QUERY.PUB.SYS;STDIN=file

The QUERY3K equivalent is one of the options below:

redirect stdin
```
 $ query3k < file
```
specify QSIN
```
 $ QSIN=file query3k
```
XEQ the named file
```
 $ query3k xeq file
```

In any case the input is read from the specified file.

For interactive usage simply run the query3k executable:

 $ query3k
 B.07.10 Eloquence QUERY3K  WED, MAR 16, 2005,  5:23 PM
 Copyright 2004-2005 Marxmeier Software AG
 Copyright 2004 Hewlett-Packard Development Company, L.P.

 >

Redirecting the output

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.

Using file equations (file name aliases)

Aliases to file and database names in QUERY3K may be established in two ways:

An environment variable may be specified that defines the file name.
For example:
```
 $ export REPORT=report.q
 $ query3k
 > XEQ REPORT
```
This accesses the file "report.q"
```
 $ export DB=sample
 $ query3k
 > b=DB
 PASSWORD = >>
 MODE = >>5
```
This accesses the database "sample"
The QUERY3K :FILE command may be used to specify an alias for a file or database name.
For example:
```
 $ query3k
 > :FILE REPORT=report.q
 > XEQ REPORT
```
This accesses the file "report.q"
```
 $ query3k
 > :FILE DB=sample
 > b=DB
 PASSWORD = >>
 MODE = >>5
```
This accesses the database "sample"

For additional information on the :FILE command please refer to the section on file equations below.

File equations in QUERY3K (:FILE, :LISTEQ, :RESET commands)

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.

For example:

 export QSLIST=">> report.txt"
 export QSLIST="|pr -2 -h "QUERY3K output"|lp -s 2>/dev/null"
 export LP="|lp -onb -s 2>/dev/null"

Note that any environment variables must be set (and possibly exported by the shell) before starting QUERY3K. It is not possible to define an environment variable from QUERY3K.

Example QUERY script

Original script:

:PURGE SNPEDCR
:FILE QSLIST=SNPEDCR;DEV=DISC;DISC=20000;NOCCTL
XEQ EDCOPEN.QEDDB
FO SETS
FO PATHS
O=TERM
EXIT

Equivalent QUERY3K script using the POSIX rm instead of the MPE PURGE command (note: the initial rm is not strictly necessary as QUERY3K by default overwrites existing files):

:rm -f SNPEDCR
:FILE QSLIST=SNPEDCR;DEV=DISC
XEQ EDCOPEN.QEDDB
FO SETS
FO PATHS
O=TERM
EXIT

$ query3k < SNPEDC

Please note that EDCOPEN.QEDDB is a file in the local directory. Specifying a group in the file name has no special meaning.

Converted to a shell script:

# execute with the POSIX shell
QSLIST=SNPEDCR query3k <<!!
XEQ EDCOPEN.QEDDB
FO SETS
FO PATHS
O=TERM
EXIT
!!

Known problems/limitations

The following problems/limitations are currently known:

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.
The current QUERY3K implementation does not support user defined procedures in the REPORT statement (see Appendix F of the QUERY/iX manual for details).
http://docs.hp.com/en/32650-90889/apfs01.html
We may consider to add this functionality to QUERY3K in a future version. Please send us some feedback if you depend on this function.
The current QUERY3K implementation does not support NLS and is limited to the NATIVE-3000 language equivalent (see Appendix D of the QUERY/iX manual for details).
http://docs.hp.com/en/32650-90889/apd.html
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).
QUERY3K does not support the Eloquence item type 'B' (binary) unless it is mapped to another item type.

History of Changes

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.

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

Fixed a problem causing QUERY3K to terminate unexpectedly when sorting required an internal merge operation.
Fixed a problem causing QUERY3K to terminate unexpectedly on a FREADDIR failure when sorting required a merge operation.
Fixed a problem causing a subsequent IMAGE failure ("SUB-SYSTEM FAILURE") after sorting.
Fixed a sort order problem with packed/zoned decimals where unsigned and positive values could compare differently.
Handle floating point underflow/overflow exceptions in register arithmetic.
Fixed a problem caused by a compiler bug affecting packed decimals. A value of -9223372036854775808 was not considered a valid I4 value.
A native IA64 version was released.
The QUERY3K version number was changed to 20050331, the Windows file revision was changed to 1.0.0.3.

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

Progress reporting should now work as expected. The default reporting interval is 30 seconds and may be changed with the HP_QUERY_PROGRESS_INTERVAL environment variable.
The QUERY3K version number was changed to 20050316, the Windows revision is 1.0.0.1.
Fixed a problem with sort order of E2/E4 fields.
Fixed a problem with a sort operation aborting when opening a temporary file.
A report specifying a format with an E4 field will no longer be corrupted.
Fixed some join problems using E2/E4 fields.
Specifying a floating point constant in a report register will no longer result in a warning message.
Fixed a join problem with K2 and P12.
Fixed memory corruption problem with command lines longer than 512 bytes.
Changed the ^Y behavior during a find to abort the find when not running interactive.
The FIND ... MATCH function no longer removes leading or trailing spaces before comparison.