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
• Other Enhancements
• Acknowledgment

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 commands 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.08.00.01 Eloquence QUERY3K  MON, OCT 20, 2008,  3:52 PM
Copyright 2004-2008 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 equivalent 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.08.00.01 (20081001)

Eloquence library revision:
     IMAGE3K B.08.00.00
     ELOQDB  B.08.00.02

The following problems/limitations are currently known:

• Database names in query3k are still limited to 6 characters although Eloquence does not have this limitation (#3479). The recommended workaround is to use a file equation to specify the database.

  :FILE db=DATABASE.TEST
  b=db
  

• Any QUERY command starting with a colon (:) is passed to the command processor (with the exception of the :FILE and 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 characters (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) works on all platforms, but is only expected to be useful 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 character set encoding or byte order this is unlikely to change.

  For details on SD files, see Appendix E of the QUERY/iX manual, and the white paper "Adopting Self-Describing Files" by David J. Greer from Robelle Consulting Ltd:

  http://docs.hp.com/en/32650-90889/ape.html
  http://www.robelle.com/ftp/papers/sd.txt

• 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 whether non-ASCII characters (Umlaute) are considered letters or not and if lower/upper case characters are considered separate.

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

Other Enhancements

• 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. To prevent query3k from crashing with an internal buffer overflow, 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
  

• Progress reporting works as expected. The default reporting interval is 30 seconds and may be changed with the HP_QUERY_PROGRESS_INTERVAL environment variable.

• QUERY3K was changed to use the /var/tmp directory as a default location to create temporary files (#3461). Previous QUERY3K versions used the /tmp directory by default. The environment variable TMPDIR may be used to specify a custom directory.

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.