Eloquence QUERY3K release notes =============================== Revision: 1.4 - 2005-03-31 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 HP-UX environment. 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: - HP-UX version 11.11 (or above) - 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://eloquence.marxmeier.com/download/B0700/patch/ Additional information on Eloquence patches is available on the Eloquence web site http://eloquence.marxmeier.com/support/B07/patch-B0700.html The Eloquence QUERY3K utility is currently only available on HP-UX (PA-RISC based systems). It is also known to work on Itanium based HP-UX systems using the builtin PA-RISC emulation. Porting QUERY3K to other platforms is in progress. ============ Installation ============ The Eloquence QUERY3K software is distributed as a compressed tar archive from the Eloquence web site. HTTP download: http://eloquence.marxmeier.com/download/B0700/hpux/ FTP download: ftp://marxmeier.com/eloq/B0700/hpux 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-B0700-4-hpux.tar.gz This creates the QUERY3K-B0700-4-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-B0700-4-hpux.tar This installs the following files (relative to the current directory): bin/query3k - QUERY3K executable lib/QMSG000 - default message file share/doc/QUERY3K.README - this readme file ============== Uninstallation ============== Please logon as root, change to the /opt/eloquence6 directory and remove the QUERY3K files. # cd /opt/eloquence6 # rm bin/query3k lib/QMSG000 share/doc/QUERY3K.README ============== 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-B0700-4: - Fixed a problem with the FIND MATCH function not handling leading and trailing spaces correctly. Previous versions removed any leading and trailing spaces before comparing with the match expression (#2664). - Fixed a problem related to sorting results that could cause an abort of QUERY3K with an internal error when a temporary file was created (#2659). - Fixed a problem related to sorting of floating point values that could cause improperly ordered floating point values. - 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 possible memory corrpution if the length of a command exceeded 512 characters. - Fixed an improper conversion related to report registers. This problem could either cause spurious "ARITHMETIC OVERFLOW" messages or corrupted register results. - Corrected handling of floating point underflow/overflow exceptions in register arithmetic. - Fixed a JOIN problem with P and Z fields that could result in missed results when a @ was present to indicate an outer join. - Fixed a JOIN problem with P12 and K2. The type conversion function did not properly convert P12 values to K2 and could result in missing some result records. This problem is likely also present on MPE (JAGaf57450). - Fixed a problem with report display formats and E4 fields potentially resulting in a corrupted value. This problem is likely also present on MPE (JAGaf57450). - Fixed a JOIN problem with E2 and E4 fields. This problem was caused by improper rounding when converting an E4 value to an E2 value. - Removed extra CR that was output after entering the password - The QUERY3K version number was changed to "20050331 p1" - The archive file name was changed from QUERY3K-B0700-3-hpux.tar.gz to QUERY3K-B0700-4-hpux.tar.gz The following changes were incorporated in QUERY3K-B0700-3: - Positioning report fields past column 80 could result in the error message END PRINT POSITION ERROR and the fields were not printed. - The QUERY3K version number was changed to 20040728 p2 - The archive file name was changed from QUERY3K-B0700-2-hpux.tar.gz to QUERY3K-B0700-3-hpux.tar.gz The following changes were incorporated in QUERY3K-B0700-2: - Fixed a build problem that resulted in an expiring Intrins/iX package. - Fixed the message catalog to use $MISSING (instead of dollarMISSING) - The archive file name was changed from QUERY3K-B0700-1-hpux.tar.gz to QUERY3K-B0700-2-hpux.tar.gz =============== 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 HP-UX 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 on HP-UX, simply run the query3k executable: $ query3k B.07.00 Eloquence QUERY3K WED, JUN 16, 2004, 10:52 AM Copyright 2004 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). 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). A typical definition for the LP environment variable on HP-UX would be something like below: LP="lp -onb -s -dprinter 2>/dev/null" 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 HP-UX 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 HP-UX shell (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. * Progress reporting is not functional. This will be fixed in a future QUERY3K version. * 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 on HP-UX. Converted to a shell script: # execute with the POSIX shell QSLIST=SNPEDCR query3k <