SUPRTOOL Version 4.0.17 Database Handyman for HP-UX Change Notice Installation Instructions Addendum to 4.0 User Manual Suprtool 4.0.17 Suprlink 4.0.17 STExport 4.0.17 Robelle Consulting Ltd. Unit 201, 15399-102A Ave. Surrey, B.C. Canada V3R 7K1 Toll-free: 1-888-ROBELLE (1-888-762-3553) Phone: (604) 582-1700 Fax: (604) 582-1799 E-mail: support@robelle.com Web: www.robelle.com February 9, 1998 Program and Manual Copyright Robelle Consulting Ltd. 1981-2002 Permission is granted to reprint this document (but not for profit), provided that copyright notice is given. QEDIT and SUPRTOOL are trademarks of Robelle Consulting Ltd. Other product and company names mentioned herein may be the trademarks of their respective owners. Introducing Suprtool/UX Version 4.0.17 ü Highlights ü Known Problems ü Compatibility ü HP-UX 10.0 Compatibility ü CPU Serial Number (uname) ü Documentation ü Documentation in WinHelp Format ü Bugs Fixed in New Features Use Suprtool/UX to read, select, and sort data from Oracle and Allbase databases and from data files with fixed-length records. Suprtool/UX is designed to be similar to Suprtool for MPE while providing necessary HP-UX features. Suprlink/UX provides high-speed data-file linking based on a sort key. Use STExport to convert fields in a self-describing input file into an output file that can be imported into different applications. We appreciate you trying Suprtool/UX. Let us know how Suprtool/UX meets your HP-UX data needs. Highlights in Version 4.0.17 ü The Item command with the SRNChronos date format now checks the size of the field. Highlights in Version 4.0.16 ü A new Set date ifyy2000error command has been added to control whether or not Suprtool considers dates with two-digit years an error if they go beyond 1999 during a relative operation. Highlights in Version 4.0.15 ü Oracle error messages were not printing properly. ü Numerous documentation fixes were made to the Suprtool manual. Highlights in Version 4.0.14 ü STExport was trimming the first character of some zoned decimal fields. ü The Duplicate command now allows an alternate sort level to be specified. ü STExport was failing when an phdate date type was in an SD file and sign none was specified. Highlights in Version 4.0.13 ü Suprtool now supports the ROBELLE variable. ü STExport was not properly processing Zoned Decimal fields with zeroes leading. Highlights in Version 4.0.12 ü Suprtool now has a readonly mode of operation whereby adds to Oracle databases are disabled. ü Suprtool was not processing any commands in the Suprmgr file. Highlights in Version 4.0.11 ü Suprtool now supports the Software Research Northwest Chronos date format. ü Suprtool's if command did not abort when doing a compare against a date beyond 1999 when being entered interactively. ü Suprtool's if command did not produce an error if a relative $date or $today function was specified beyond 1999. ü Suprtool now allows use files to be nested. ü The Add command for Oracle did not add all the records from a file in all cases. ü Reset Add and Verify Add now work as documented. ü STExport did not properly set the Delimiter option when using HTML Table command in all cases. ü STExport did not always build an output file with the proper record size when the Heading Column option was used. Highlights in Version 4.0.10 ü There are currently no changes in Suprtool for HP-UX. Known Problems There are no known problems at this time. Compatibility Suprtool/UX is compatible with both HP-UX 9.0 and Oracle version 7.1.3.2.0. HP-UX 10.0 Compatibility and Installation Suprtool/UX is compatible with all versions of HP-UX 10.x. If you want to use the new HP-UX 10.x naming conventions for Suprtool/UX, you need to perform the following steps while logged in as root: 1. Get the files off the tape: tar xv 2. Move the files to /opt/robelle: mv /usr/robelle /opt 3. Set the ROBELLE environment variable to the new directory export ROBELLE=/opt/robelle Suprtool/UX creates all its temporary and scratch files in /var/tmp, unless you have overriden the temporary directory with the TMPDIR environment variable. [4.0.12] CPU Serial Number (uname) This program runs only on CPUs whose serial numbers have been encoded (the "uname" on HP-UX). If it fails to run and you see an "invalid HPSUSAN" error message, call Robelle for assistance. Documentation Although we do not include a revised user manual with pre-release versions of Suprtool, we do provide updated Help files. You can access these files from within Suprtool by simply typing "help." We also distribute all three user manuals as a Windows Help file. If you are already familiar with Suprtool, you may want to access only the Suprtool/UX topics that are different from those of Suprtool/MPE. The "Running" section of the help file has been updated for Suprtool/UX. You can access it with this help command: >help running Documentation in WinHelp Format The user manuals for Suprtool and its components are all available in the popular WinHelp file format of Microsoft Windows. Your tape includes a WinHelp file, which is a self-extracting compressed file that contains all five Help files and a Setup program. Use the installation instructions in this change notice to install the WinHelp files on your PC. Bugs Fixed in New Features. STExport. STExport was trimming off the first character in some zoned-decimal fields. [4.0.13] Installation of 4.0.16 The following general notes describe the installation of a new Suprtool release. The new version overwrites an existing version of Suprtool on your HP-UX system. Who Should Use These Instructions? The system manager should use the following instructions to install Suprtool/UX. During the installation, which should take only a few minutes, no one can use Suprtool/UX. This Tape Will Expire All Robelle pre-release software has an expiration date because it should be replaced with our official major releases. Suprtool/UX pre-release tapes expire eighteen months after they are made. The software warns you when you are within sixty days of the expiry date. The exact expiry date is on the tape label. Summary of Installation Steps Installing Suprtool involves the following steps: 1. You must log in as root. 2. You must create the correct directory structure. 3. You must restore Suprtool/UX and its associated files from the distribution tape. 4. You can set up a PATH for Suprtool/UX or copy the program to an existing directory in your PATH. (optional) 5. You can install WinHelp documentation files. (optional) 6. You can set the ROBELLE variable if you installed Suprtool into a directory other than /usr/robelle. (optional) Step 1: Log In as Root There are two ways you can log in as root: a. Exit from HP-UX and log in with root as the user name. b. If you are already logged in, you can execute this command: su - In either case, you have to know and supply the user password for root. Step 2: Create Robelle Directory Suprtool/UX is installed in /usr/robelle. Before restoring its files, you must first create /usr/robelle: mkdir /usr/robelle Step 3: Restore Files Use the following command to restore the Suprtool/UX files from the distribution tape: tar xv /usr/robelle After successfully restoring the files, you can run the new version of Suprtool/UX. /usr/robelle/bin/suprtool Step 4: Set Up PATH (optional) You can now invoke Suprtool with the following command: /usr/robelle/bin/suprtool If you want to just type suprtool to invoke Suprtool/UX, you must either add /usr/robelle/bin to your PATH or copy /usr/robelle/bin/suprtool to a directory that is currently on your PATH. Similarly, the man pages for Suprtool are in /usr/robelle/man/man1/suprtool.1. To make the man pages available to everyone, you can either add /usr/robelle/man to your MANPATH or copy the man pages to a directory that is currently on your MANPATH. If you adjust your PATH and MANPATH environment variables, you can also invoke Suprlink/UX with suprlink Step 5: Install WinHelp Documentation Files (optional) All of the Suprtool documentation is now available in the WinHelp format of Microsoft Windows. You can only use these files if you have a Windows PC. Make a Temporary Directory for the Setup Program Create a directory for the installation file on your PC. You can remove this directory after installing the WinHelp files. At the DOS prompt for example, type mkdir \robtemp Download the Compressed File In the next step, download the self-extracting Zip file to your PC. If you are using Reflection to download the Zip file, follow these instructions. The file on the HP 9000 is called /usr/robelle/winhelp/suprhelp.exe From the /usr/robelle/winhelp directory, press Alt-Y to go to the Reflection Command Line window. Make sure that you use the binary transfer. receive c:\robtemp\suprhelp.exe from suprhelp.exe binary Expand the Compressed File You need only the following commands to extract the files because we provide the Setup program and the Help files in one self-extracting Zip file. From the DOS prompt, type these commands: cd \robtemp {go to the new Robtemp directory} suprhelp.exe {extract the Help files} Run the Setup Program Now you can run the Setup program. In Windows 95, select Run from the Start menu and enter c:\robtemp\setup in the Run dialog box. Then follow the instructions in the Setup program. Once the Setup program is finished, you can access all the Suprtool documentation by selecting any of the "Robelle Help" icons. Remove the Robtemp Directory You can now remove all the files from the Robtemp directory either from Explorer or by using the following DOS commands: cd \robtemp del *.* {delete all the files} cd .. rmdir robtemp {remove the Robtemp directory} You can also copy the files in Robtemp to a diskette and distribute them to other Suprtool users. Step 6: Set the ROBELLE Variable (optional) Suprtool/UX is normally installed in /usr/robelle. If you install Suprtool/UX in any other directory, you need to perform another step so that Suprtool can find its help and suprmgr files. This additional step involves setting the ROBELLE environment variable. If you install Suprtool into /opt/robelle for example, you must set the ROBELLE environment variable in the following manner: export ROBELLE="/opt/robelle" Enhancements Nested Usefiles [4.0.11] Suprtool now allows usefiles to be nested; in other words, one usefile can contain references to another usefile. You can nest the usefiles up to ten levels. For example, if the contents of the usedef usefile had a references to useext, both usefiles would be executed: >open oracle store.suprtool >select * from d_sales >use usedef define delivered,deliv_date define purchased,purch_date item delivered ,date ,yymmdd item purchased ,date ,yymmdd use useext ext cust-account ext deliv-date ext product-no ext product-price ext purch-date ext sales-qty ext sales-tax ext sales-total >xeq Care must be taken when entering use commands with a stacked command after the usefile reference. For example, if you enter use usedef;def j,1,6,byte the define command will not be executed until after the usedef and any other nested use commands are finished. Duplicate Command [4.0.14] The keys num option determines the level at which Suprtool compares sort keys. This option controls which duplicate records get included in (or excluded from) the output file. In the following example we sort by agent and by bill-date (in descending order), but only check for duplicates at the agent level. >sort agent {sort by agent} >sort bill-date,desc {sort by date } >duplicate none keys 1 {only check for duplicate agents} >output agents {create roster of agents} ROBELLE Environment Variable [4.0.13] Suprtool looks for the files it needs in the /robelle directory (normally /usr/robelle). For example, Suprtool expects to find its help files in a subdirectory called help/suprtool. The absolute filename would be /usr/robelle/help/suprtool If you install Suprtool in a directory other than /usr/robelle, you need to set the ROBELLE environment variable to the new directory. For example, ROBELLE=/usr/robhome export ROBELLE There are two limitations to the path name: the full path name of the file must be no more than 36 characters, and the path name to the /robelle directory must be no more than 22 characters. A slash mark (/) is optional at the end of your ROBELLE environment variable. Set Date Ifyy2000Error On | Off [4.0.16] By default Suprtool considers Dates with a two-digit century from the $date and $today functions to be invalid when they resolve to be greater than 1999 and the if operation is a relative operation. (ie. greater than or equal to) You can control whether or not Suprtool considers this an error or not by making the following Set command: >set Date Ifyy2000Error Off Following is an example of what is considered to be and error by the if command and how the Set command can turn off the error check: >def a,1,6 >item a,date,yymmdd >if a >= $today(+2000) ^ Error: Cannot use a date beyond 1999 for this format >set date ifyy2000error off >if a >= $date(2000/01/03) We have chosen this to be an error by default because if a date that is in yymmdd format and resolves to be 000102 from the $date function in the if command is likely to resolve to be all of the records for a given selecction task, which is of course, logically incorrect. Set Limits ReadOnly On [4.0.12] Suprtool normally allows any user with the proper access capabilities to add records to an Oracle database. To prevent users from accidentally updating their database, we provide the following setting within Suprtool: >set limits ReadOnly On The readonly setting, once turned on, cannot be turned off for the current run of Suprtool, which disallows all commands that potentially change data for a given database. If set limits readonly is enabled, the add command in Suprtool will return an appropriate error message. You can enable set limits readonly from the command line by using the -c option. For example, the following command file can be used to restrict who has write access to a given database. In this example only the root user is allowed write access: if [ $USER = "root" ] then /usr/robelle/bin/suprtool else /usr/robelle/bin/suprtool -c'set limits readonly on' fi Bugs Fixed If Command. The if command did not produce an error when a relative $date or $today function were specified beyond 1999. [4.0.10] Oracle. Error messages were not being reported properly from the Oracle interface. [4.0.15] STExport Program. The following problems in STExport have been fixed: 1. STExport would not properly set the Delimiter to None on a second task when setting the HTML option to Table. [4.0.11] 2. STExport would fail if the total length of the Heading Column commands exceeded the total size of the fields. [4.0.11] 3. STExport was failing with an invalid write-length error if a phdate field was in the SD file and sign none option was specified. [4.0.14] Suprlink. Suprlink would not properly link files by a Quad integer key. (I4 or J4). [4.0.11] Suprmgr File. Suprtool 4.0.11 did not process any of the commands in the Suprmgr file. [4.0.12]