Eloquence B.07.10 - QUERY3K release notes ========================================= Revision: Beta4 - 2005-09-22 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 system environment. This version differs substentially 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 accross different platforms. Also a some minor bugs were fixed. Please refer to the section "known problems" below for any known limitations. Please send any feedback or problem reports to the Eloquence support at support@marxmeier.com. ============= Prerequisites ============= The following prerequisites must be met before installing the Eloquence QUERY3K utility: - System environment - HP-UX version 11.11 (or above) - Windows 95 or above - Linux x86, glibc2.2 compatible system - Eloquence B.07.00 with the hp3k license option - Required Eloquence patches (or newer) - PE70-0406240 (eloqdb6 server) - PE70-0406220 (image3k library) - PE70-0406021 (eloqdb library) Eloquence patches are available for download from http://www.hp-eloquence.com/download/B0700/patch/ Additional information on Eloquence B.07.00 patches is available on the Eloquence web site http://www.hp-eloquence.com/support/B07/patch-B0700.html ============ Installation ============ HP-UX and Linux platform ------------------------- The Eloquence QUERY3K software is distributed as a compressed tar archive from the Eloquence web site. HTTP download: http://www.hp-eloquence.com/download/beta/B0710/query3k/ FTP download: ftp://ftp.hp-eloquence.com/eloq/beta/B0710/query3k Please download the distribution archive and place it in a temporary directory. The archive file is compressed (gzip) and needs to be uncompressed before installation. Please logon as root. # gunzip QUERY3K-B0710-B4-hpux.tar.gz This creates the QUERY3K-B0710-B4-hpux.tar archive file and removes the compressed archive file. Please change in the Eloquence directory and unpack the QUERY3K archive file. # cd /opt/eloquence6 # tar xvf /tmp/QUERY3K-B0710-B4-hpux.tar This installs the following files (relative to the current directory): bin/query3k - QUERY3K executable lib/nls/QMSG000.cat - default message file share/doc/QUERY3K.README - this readme file Windows platform ---------------- The Eloquence QUERY3K software is distributed as a ZIP file archive (QUERY3K-B0710-B4-win32.zip) from the Eloquence web site. HTTP download: http://www.hp-eloquence.com/download/beta/B0710/query3k/ FTP download: ftp://ftp.hp-eloquence.com/eloq/beta/B0710/query3k Please download the distribution archive and copy the files to their target locations to install the QUERY3K beta test release. This archive provides the following files (relative to the Eloquence product directory): bin/query3k.exe - QUERY3K executable bin/qlp.exe - QUERY3K printer filter lib/nls/QMSG000.cat - default message file share/doc/QUERY3K-README.txt - this readme file It is strongly recommended to change the QUERY3K console properties. - 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. As a result, non-ASCII characters are displayed wrong. To change the font, please start QUERY3K open the console settings and change the font to a TrueType font. Then apply the change to all windows of that name. While you are in the settings, please consider changing the font size and text foreground/background color to have a more convenient display. ============== Uninstallation ============== HP-UX and Linux platform ------------------------ Please logon as root, change to the /opt/eloquence6 directory and remove the QUERY3K files. # cd /opt/eloquence6 # rm bin/query3k lib/nls/QMSG000.cat share/doc/QUERY3K.README Windows platform ---------------- Please open a command line window, change to the Eloquence product directory and remove the files below: > cd "C:\Program Files\Eloquence" > del bin\query3k.exe > del bin\qlp.exe > del lib\nls\QMSG000.cat > del share\doc\QUERY3K.README.txt ============== Documentation ============== 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: http://docs.hp.com/en/32650-90889/32650-90889.pdf http://docs.hp.com/en/32650-90889/index.html ================== History of Changes ================== 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 accross 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 =============== Running QUERY3K =============== The Eloquence QUERY3K executable is called query3k and located in the /opt/eloquence6/bin directory. 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 files access from QUERY3K (eg. through XEQ). The :RESET and :LISTEQ commands are also supported in addition to :FILE. The following syntax is recognized: :FILE =[;DEV={DISC|LP}] Where specifies a logical file name and 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. ========================== Known problems/limitations ========================== The following problems/limitations are currently known: * Any QUERY command starting with a colon (:) are 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 it did not receive any data and returns an error. * The current QUERY3K implementation currently 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 currently 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. This may either be specified with the -d command line option to qlp or by setting the QLPDEST/LPDEST environment variable to specify the printer. * 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 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/CP437 encoding: > mode con: cp select=850 (or 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. ==================== 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 using the POSIX rm instead of the MPE PURGE command. The 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 notice 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 <