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

Contents

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

Reference Documentation

This document covers the differences from the original QUERY/iX version. The reference documentation for QUERY/iX applies to query3k and is available from the HP web site at the location below:

• PDF format:
  http://docs.hp.com/en/32650-90889/32650-90889.pdf
  (local copy)

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

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"

QSLIST=">>outfile"

QSLIST="|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"

LP="qlp -s -dprinter"

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:

1. 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"

2. 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}]

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

:FILE QSLIST=report.txt;DEV=DISC

:FILE QSLIST=">>report.txt"

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

:FILE QSLIST=lp;DEV=LP

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"

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

Reporting problems

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

Please include the output of the query3k command with the versions commandline option (or the query3k version command) as shown below:

$ query3k versions

QUERY3K application revision:
     B.07.10.04 (20070216)

Eloquence library revision:
     IMAGE3K B.07.10.03
     ELOQDB  B.07.10.07

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.

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

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

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

Acknowledgment

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.

QUERY3K uses the INTRINS/iX toolkit from Allegro Consultants, Inc and the SORT intrinsics replacement from Redstone Technologies, Inc.

History of Changes

The following user visible changes were incorporated in QUERY3K since the original B.07.10 release (patch PE71-0703290):

• Fix a bug related to JOINS using more than two data sets that could perform wrong evaluation of the JOIN condition in some cases.

  J DETAIL2.KEYE2 @ TO DETAIL4.E4ITEM, &
  DETAIL4.E4ITEM @ TO DETAIL3.E2ITEM
  

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

• Fixed a problem with QUERY3K crashing when printing string items with a size beyond 255 bytes (#3267).

  This problem was caused by a buffer overflow. As a temporary solution, string items with a size beyond 255 characters are no longer considered printable and will result in a message like below:

  ILLEGAL ITEM LENGTH X500, ITEM ID-DATA-500-1 IGNORED
  

• Fixed a memory corruption with the FIND command when entering an item with more than 16 characters (#3296). For example:

  > find skldjflskjflskdjflskjdflskjflskdjlskdjf
  PROCEDURE NAME TOO LONG
  > exit
  ** Cought signal 11 ...
  

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

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.