SUPRTOOL Version 4.2 Database Handyman for HP-UX Change Notice Installation Instructions Addendum to 4.2 User Manual Suprtool 4.2 Suprlink 4.2 STExport 4.2 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 March 1999 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.2 ü Highlights ü Known Problems ü Compatibility ü CPU Serial Number (uname) ü Documentation ü Documentation in WinHelp Format 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. Highlights in Version 4.2 More Date and Data Manipulation ü With the new $stddate function, you can use the popular "date windowing" Y2K technique in the If and Extract commands. ü You can compare dates with dissimilar formats or data-types by using the new $stddate function. ü The If and Extract commands now support the Mod arithmetic operator, allowing more flexible manipulation of numeric data, especially numeric date data. New Date Formats ü Suprtool now supports more new date formats: mmyyyy, yyyymm, yyddd, ccyyddd, aamm, mddaa, ddmmaa and HPCalendar. The ddd date component is a count of the "day of the year," which is sometimes referred to as a Julian date. ü The $date function now permits you to enter a date without a month or day, depending on your date format. Staying Current with HP-UX ü Suprtool has been enhanced to support files greater than 2 gigabytes. ü Suprtool and STExport now allow you to specify whether the output file has line feeds. ü Suprlink and STExport now support the ROBELLE variable. Known Problems There are no known problems at this time. Compatibility Suprtool/UX is compatible with HP-UX 9.0, all versions of HP-UX 10.x, as well as Oracle version 7.1.3.2.0. On HP-UX 10.x, Suprtool/UX creates all of its temporary and scratch files in /var/tmp, unless you have overridden the temporary directory with the TMPDIR environment variable. Suprtool for HP-UX typically comes with two versions in two different directories on your tape. The version of Suprtool in /opt/robelle is compatible with HP-UX 10.20 and later. The version of Suprtool in /usr/robelle is compatible with versions earlier than HP-UX 10.20. Item Command and Date Format In earlier versions of Suprtool, the Item command default allowed an abbreviated name of the date format. Now this default expects the full mnemonic for the date format. To change the default, you can use the new Set ItemAbbreviateDate On command. For example, >def a,1,4,double >item a,date,hpcal Error: The Item command did not recognize HPCAL as a valid date keyword >set itemabbreviatedate on >do item >item a,date,hpcal To enable this feature globally for all Suprtool tasks, add >set itemabbreviatedate on to the file /usr/robelle/suprmgr. 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 get an "invalid HPSUSAN" error message, call Robelle for assistance. Documentation The user manuals for Suprtool and its components are available on-line. 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 can 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. Installation of 4.2 The following instructions describe the installation process 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. Replace Any Pre-Release If you are currently running a pre-release version of Suprtool, you should replace it with this new official release. Pre-release versions expire within two years of their creation date, whereas this new release has no expiry date. You can easily recognize a pre-release by the words "Pre-Release" next to the version number. Summary of Installation Steps To install Suprtool, follow these steps: 1. Log in as root. 2. Create the correct directory structure. 3. Restore Suprtool/UX and its associated files from the distribution tape. 4. Set up variables to let Suprtool know where its supporting files are. 5. Install WinHelp documentation files. (optional) Installation Assistance If you have any questions or run into any problems, please call us. Technical support is available on weekdays from 7 a.m. to 4 p.m. Pacific time at 1-888-ROBELLE (1-888-762-3553). You can also receive emergency support outside of these hours by calling our regular phone number and asking the operator to page a support person for you. 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 Before restoring files, you must first create the directory where Suprtool/UX will reside: For HP-UX 10.20 and later, mkdir /opt/robelle For HP-UX 10.10 and earlier, mkdir /usr/robelle Step 3: Restore Files Use the following command to restore the Suprtool/UX files from the distribution tape: For HP-UX 10.20 and later, tar xv /opt/robelle For HP-UX 10.10 and earlier, tar xv /usr/robelle This command assumes your tape device is /dev/rmt/0m. If it is not, you need to specify your tape device using the f option in the tar command. For example, if your tape device is /dev/rmt/1m, you need to use the following command to restore the files: tar xvf /dev/rmt/1m /opt/robelle Step 4: Set the ROBELLE Variable You must set the ROBELLE environment variable so that Suprtool can find its Help and Suprmgr files. Bourne and Korn Shells For HP-UX 10.20 and later, export ROBELLE=/opt/robelle For HP-UX 10.10 and earlier, export ROBELLE=/usr/robelle C Shell For HP-UX 10.20 and later, setenv ROBELLE /opt/robelle For HP-UX 10.10 and earlier, setenv ROBELLE /usr/robelle Step 5: Install WinHelp Documentation Files (optional) The Suprtool documentation for both MPE and HP-UX is now available in the WinHelp format of Microsoft Windows. You can only use these files if you have Windows 3.1 or later. To install the WinHelp files on a PC, follow these instructions. 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 If you use the floppy diskette that is included in the Suprtool User Manual to copy the Help files to your hard drive, proceed to "Run the Setup Program" below. Otherwise, use Reflection to download the self-extracting Zip file to your PC and continue with these steps. The file on the HP 9000 is /usr/robelle/winhelp/suprhelp.exe From the /usr/robelle/winhelp directory, press Alt-Y to go to the Reflection Command Line window. Then download the file as a binary transfer. receive c:\robtemp\suprhelp.exe from /usr/robelle/winhelp/suprhelp.exe binary Expand the Compressed Files You only need the following commands to extract the files because we provide both the Setup program and the Help files in one self-extracting Zip file. From the DOS prompt, type the following commands: cd \robtemp {go to the new Robtemp directory} suprhelp.exe {extract the Help files} Run the Setup Program From the Program Manager, run the Setup program by choosing the Run option from the File menu. Then enter c:\robtemp\setup in the Command Line window and follow the instructions in the Setup program. You can now access all of the Suprtool documentation by selecting any of the icons in the "Robelle Help" Program Manager Group. Remove the Robtemp Directory Before you remove the WinHelp files, you can copy them to a diskette and distribute them to other Suprtool users. To delete all the WinHelp files and remove the Robtemp directory, use either the File Manager or the following DOS commands: cd \robtemp del *.* {delete all the files in Robtemp} cd .. rmdir robtemp {remove the Robtemp directory} Enhancements Every year we provide Suprtool/UX users with new features. This year the major enhancements include more date control functions in the If and Extract commands, more date formats for the Item command and a new Mod arithmetic operator. The following sections describe the new enhancements to Suprtool since the last major release. Large File Support Suprtool had been enhanced to read, sort and write files greater than 2 gigabytes. Although Suprtool is currently limited to 2.1 billion records, in testing it has read, sorted and written out a 6.3 gigabyte file. This support is available only on versions of HP-UX (10.20 and later) that support large files. Decimal Command - STExport Use the Decimal command to specify the symbol for the decimal place in STExport. DECimal PERIOD | COMMA (Default: Period) The Decimal command specifies what separator will be used to indicate the decimal place in numeric fields. In North America, the custom is to indicate the decimal place in numbers with a period (.). Outside North America, the custom is to indicate the decimal place with a comma (,). If the decimal place indicator is incorrect, it is harder to import files into other applications. The Decimal command does not apply to floating-point fields. If Command - $Stddate Suprtool now has a new $stddate function available in the If and Extract commands. This function can compare dates of dissimilar formats or data-types by converting any date format in nearly any data-type container and internally converting it to the ccyymmdd format in a double-integer container. For example, > get order-detail > item order-date,date,ccyymmdd > item bill-date,date,mmddyyyy > if $stddate(bill-date) <= order-date > output badords,link > xeq This feature is also available for those dates that have two-digit years. The century portion of the date is applied to $stddate by using the normal cutoff rules that use the value in Set Date Cutoff. > get invoice-detail > set date cutoff 20 > item invoice-date,date,yymmdd > item close-date,date,mmddyyyy > if $stddate(close-date) <= $stddate(invoice-date) > out badinvs,link > xeq In this case all invoice-date values with a yy portion between 20 and 99 will have 19 as the century. All invoice-date values with a yy portion of less than 20 will have 20 in the date generated by the $stddate function. Invalid Dates A date must be valid before $stddate can convert it to the ccyymmdd format. Otherwise, a value of 0 will be returned for any invalid dates. An invalid date is a number in a date format whose date equivalent cannot be found on a calendar. This includes dates selected by the $invalid function. We can eliminate the invalid dates from the above task by changing the If command slightly. > get invoice-detail > set date cutoff 20 > item invoice-date,date,yymmdd > item close-date,date,mmddyyyy > if (not $invalid(close-date) & or not $invalid(invoice-date)) & and $stddate(close-date) <= $stddate(invoice-date) > out badinvs,link > xeq In this example, if either the close-date or the invoice-date are invalid, then they will not be evaluated by the $stddate function and will not be selected. Although your requirements may be different, you need to remember that invalid dates evaluated by the $stddate function will return a 0 value. Extract Command - $Stddate Similar to the If command, the Extract command is also capable of utilizing the $stddate function, which can convert any of the supported Suprtool date formats into the ccyymmdd format in a double-integer container. For example, > get sales-detail > def new-ship-date,1,4,double > item ship-date,date,mmddyyyy > ext order-no / sales-amount > ext new-ship-date = $stddate(ship-date) > out salesinfo,link > xeq Invalid Dates A date must be valid before $stddate can convert it to the ccyymmdd format. Otherwise, a value of 0 will be returned for any invalid dates. An invalid date is a number in a date format whose date equivalent cannot be found on a calendar. If you use the $stddate funcion to extract a value that is not a valid date, the extracted value will be 0. $Date Function The $date function for the If and Extract commands has been enhanced to have more flexible parsing of the year, month and day portions for the yymm, yyyymm, ccyymm, ccyy, aamm, mmyyyy and ccyymm date formats. For example, in earlier versions the ccyy date format had to specify all three components (year, month and day). Now the $date function needs only the relevant portion of the date. >item year-date,date,ccyy >if year-date = $date(*) For compatibility reasons, we also accept all three portions of the date in the $date function. >item year-date,date,ccyy >if year-date = $date(*/*/*) Item Command - Date Format In earlier versions of Suprtool, the Item command default allowed an abbreviated name of the date format. Now this default expects the full mnemonic for the date format. To change the default, you can use the new Set ItemAbbreviateDate On command. For example, >def a,1,4,double >item a,date,hpcal Error: The Item command did not recognize HPCAL as a valid date keyword >set itemabbreviatedate on >do item >item a,date,hpcal To enable this feature globally for all Suprtool tasks, add >set itemabbreviatedate on to the file /usr/robelle/suprmgr. Item Command - mmyyyy The Item command now supports the date format of mmyyyy in X6, Z6, J2, K2 and P8 or greater data-types. Item Command - yyddd The Item command now supports the date format of yyddd in X5, Z5, J2, K2 and P8 or greater data-types. Because you cannot have uneven byte fields in IMAGE databases, you may need to redefine your date field for these types of dates, depending on where your date is padded with spaces. If your date is an X6 field, you can redefine your date field. This particular date pads a yyddd-type date with a space at the end of the field. >def newdate,date-field[1],5 >item newdate,date,yyddd >if newdate <= $today Item Command - ccyyddd The Item command now supports the date format of ccyyddd in X7, Z7, J2, K2 and P10 or greater data-types. Because you cannot have uneven byte fields in IMAGE databases, you may need to redefine your date field for these types of dates, depending on where your date is padded with spaces. If your date is an X8 field, you can redefine your date field. This particular date pads a ccyyddd-type date with a space at the beginning of the field. >def newdate,date-field[2],7 >item newdate,date,ccyyddd >if newdate <= $today Item Command - HPCalendar The Item command now supports the date format of HPCalendar in J2 and K2 data-types. Item Command - yyyymm The Item command now supports the date format of yyyymm in X6, Z6, J2, K2 and P8 or greater data-types. Item Command - aamm The Item command now supports the date format of aamm in an X4 data-type. The Item command also supports mmddaa and ddmmaa date formats in an X6 data-type. If Command - Mod Operator Suprtool now has a new Mod arithmetic operator that returns the remainder between a dividend and a divisor. Practical uses of the Mod operator allow for extractions of the rightmost numbers from numeric fields. You can use the Mod operator to do a comparison on the rightmost numbers of a given numeric field. For example you could compare the dd portion of a ccyymmdd date against another field or constant. > get order-detail > item order-date,date,ccyymmdd > if order-date mod 100 <= 15 > out ordbegin > xeq Using the same concept and data, you can also compare the month portion of a given date by using divide (/) and Mod together. > get order-detail > item order-date,date,ccyymmdd > if order-date / 100 mod 100 <= 02 > out ordbegin > xeq The Mod operator has the same precedence in the order of operations as multiply and divide. Extract Command - Mod Operator The Mod operator is also available to the Extract command. It returns the remainder between a dividend and a divisor. Practical uses of the Mod operator allow for extractions of the rightmost numbers from numeric fields. > get order-detail > item order-date,date,ccyymmdd > def order-date-day,1,4,double > ext order-no > ext order-date-day = order-date mod 100 > out ordday,link > xeq Using the same concept and data, you can also extract the month portion of a given date by using divide (/) and Mod together. > get order-detail > item order-date,date,ccyymmdd > def order-date-day,1,4,double > ext order-no > ext order-date-day = order-date / 100 mod 100 > out ordmonth,link > xeq The Mod operator has the same precedence in the order of operations as multiply and divide. Output Command - Suprtool Suprtool's Output command has been enhanced with new formatting options that allow you to specify whether the output file has line feeds. The LF and NOLF options on the Output command control whether line feeds are written to the output file. By default Suprtool writes out a line feed if the input file has a line feed. Alternatively, Suprtool does not write out a line feed if the input source does not have a line feed. To ensure that a file is written out with line feeds, you can specify the LF formatting option. >select * from user.account@emp >sort ename >out employ,lf >xeq To ensure that no line feeds are written out to the file, you can specify the NOLF option. Output Command - STExport STExport's Output command now allows the user to specify whether line feeds are written to the output file. Normally STExport determines whether to write out line feeds from the self-describing file. If the self-describing file does not have line feeds, then the resulting file from the STExport task will not have line feeds. This caused problems for some programs that imported the file or for some browsers that used the HTML option. You can now specify line feeds in the output file by using the LF option. $in ora.customer $out file1ex,lf $exit To ensure that no line feeds are written out to the file, you can specify the NOLF option. $in ora.customer $out file1ex,nolf $exit Output Command - Suprlink Suprlink's Output command now supports the Link option. Although this option was already the default output file, some users found themselves typing the Link option on the Output command. This would cause an error, even though linked files can be written by Suprlink. We now allow the Link option to be specified. Bugs Fixed ROBELLE Variable. STExport and Suprlink now support the ROBELLE variable. If Command. The If command now reports "Error: Missing symbol" when using the $date function for ccyymm, yyyymm, and ccyy date formats. If Command. The If command's $invalid function now reports yymmdd and yymm dates as invalid in numeric containers such as J2. If Command. Suprtool no longer incorrectly evaluates an expression with two constants. Input Command. The Input command no longer gives incorrect error messages in some cases. List Command. The List command and the time 2 format in Set List no longer incorrectly report a.m. when the time is between 12:00 to 12:59 p.m. List Command. The List command no longer aborts when listing odd-length integers in Hex. STExport Command. STExport now supports ASK dates in all cases. Verify Command. The Verify item command now always prints the date type.