SUPRTOOL Version 4.3 Database Handyman for the HP 3000 Pre-Release Change Notice Installation Instructions Addendum to 4.2 User Manual Suprtool 4.3 Dbedit 4.3 Suprlink 4.3 STExport 4.3 Speed Demon 4.3 Suprtool2 4.8 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 2000 Program and Manual Copyright Robelle Consulting Ltd. 1981-2001 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 Version 4.3 ü Highlights ü Compatibility ü CPU Serial Number ü Compatibility Mode vs. Native Mode ü Documentation ü Documentation in WinHelp Format Suprtool provides fast access to your data on the HP 3000. With Suprtool, you can perform many necessary DP functions easily, with just a few simple commands. At Robelle we are constantly working on your enhancement requests so that we can include them every year when we release an updated version of Suprtool. This change notice provides you with detailed installation steps and a description of Suprtool's new features. We would appreciate any feedback on any of the new features available in this release of Suprtool. Thank you for agreeing to give this new version of Suprtool a try. Highlights in Version 4.3 Data functions ü Expand any CI variable on the command line (in Suprtool, Suprlink and STExport) using Set Varsub On. ü Compute the absolute value of an expression using the $ABS function. ü Compute the integer portion of an expression using the $TRUNCATE function. ü Pattern strings in the If command can be much larger. Date functions ü Convert any date to a Julian Day Number with the $DAYS function. This allows you to compute the number of days between any two dates. ü New date formats supported: new phdate format in integer fields for versions of PowerHouse 8.19 and higher, EDSDATE and Julian Day number. System functions ü Suprtool, Suprlink and STExport have internal changes to support MPE/iX 6.5. ü Suprlink and STExport now support filenames up to 240 characters in length. ü Get the version number with Verify Version in Suprtool. Compatibility Suprtool, Speed Demon, and Suprlink are compatible with Q-Delta-2, R-MIT, T-MIT, U-MIT, V-MIT, MPE XL, and MPE/iX, including MPE/iX 5.5. CPU Serial Number (HPSUSAN) This program runs only on CPUs whose serial numbers have been encoded ("showvar hpsusan" on MPE/iX). If it fails to run and you get an "invalid HPSUSAN" error message, call Robelle for assistance. Compatibility Mode vs. Native Mode Throughout this change notice and in all of the Suprtool documentation, there are references to compatibility mode and native mode. If you are on a Classic HP 3000 (i.e., not MPE/iX), you can use the compatibility-mode version of Suprtool. Our job streams automatically install the correct version for your machine. We use the terms MPE XL and MPE/iX interchangeably in our documentation. Documentation This release includes updated user manuals for Suprtool and its components. To print these manuals, use the Printdoc program. :run printdoc.pubnew.robelle This is the list of documentation files for Suprtool: NOTE: These file names assume that Install.suprjob has already been performed. suprtool.doc.robelle {Suprtool user manual} stexport.doc.robelle {STExport user manual} suprlink.doc.robelle {Suprlink user manual} dbedit.doc.robelle {Dbedit user manual} demon.doc.robelle {Speed Demon user manual} suprcall.doc.robelle {Calling Suprtool user manual} suprtool.docchg.robelle {this change notice} If you know the file names of other Robelle documents, you can print them with Printdoc or you can include the file name in the :Run command. For example, to print this change notice, type :run printdoc.pub.robelle;info="suprtool.docchg.robelle" 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.3 The following installation instructions are for existing Suprtool users who are installing a new version in the Robelle account. Please use the instructions from this change notice instead of the user manual because the change notice always has the latest version. The whole process should take about 30 minutes, assuming that no one uses Suprtool or its components during the installation. To install this update of Suprtool, follow these steps: 1. Restore the new files from tape. 2. Upgrade the structure of the Robelle account. 3. Install the proper program files (NM or Classic). 4. Install Speed Demon in the system SL (only Classic). 5. Install the Suprtool2 interface in the system SL (only Classic). 6. Limit Suprtool's run time priority (optional). 7. Install WinHelp documentation files (optional). 8. Install QLIB and Bonus programs. 9. Purge the installation files (optional). 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. 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. Important Note About Passwords None of the jobs that we supply have passwords in them. Before streaming a job, you might have to add your system's passwords to the first line. Users of MPE XL 3.0 and later do not have to do this because the operating system prompts for missing passwords. The same is true for some MPE V users who have security software that inserts passwords. Most MPE V users have to edit the jobs. For example, if the system manager logon password is Qwerty, you would do the following: :editor HP32201A.07.22 EDIT/3000 /text robelle.job.robelle FILE UNNUMBERED /modify 1 MODIFY 1 !job robelle,manager.sys,pub;hipri;jobq=SUPRTOOL i/qwerty !job robelle,manager.sys/qwerty,pub;hipri;jobq=SUPRTOOL /keep robtemp /exit END OF SUBSYSTEM :stream robtemp :purge robtemp STREAMX Users Users of STREAMX, a part of SECURITY/3000 from VESOFT Inc., must set a Job Control Word before streaming jobs. This prevents STREAMX from generating an error if the Robelle account does not yet exist. For example, :setjcw streamxtempnonest 1 :stream robelle.job.robelle Step 1: Restore the Files You begin by restoring all the files from the tape. :hello manager.sys :file rtape; dev=tape {use appropriate device} :restore *rtape; @.@.robelle; create {restore everything} The files on the tape require approximately 80,000 sectors. If you are upgrading Suprtool, most of these files will replace existing files because the new version of Suprtool does not take up much more space than the old version. The Suprtool program files are located in the Pubnew group of the Robelle account. At this point in the installation process, the files do not have the correct names. The next step assigns the proper names to the program files. Step 2: Set Up the Robelle Account Even if you already have the Robelle account, you must stream the Robelle job to ensure that the Robelle account and all its groups have the proper security and capabilities. :stream robelle.job.robelle When the job stream is finished, it will send you a message. The job removes the password from the Robelle account. Stay logged on as Manager.Sys and put a password on the Robelle account. If you are upgrading your Robelle account, use the old password. :altacct robelle;pass=hardpass {hard to guess} Please note that during installation we add OP capability to the Robelle account. When the Suprtool installation is finished, you have the option to remove OP capability. Step 3: Install Suprtool into Production Our installation job installs Suprtool, STExport, Suprlink, Speed Demon, and the Suprtool2 interface. No one can use these programs during the installation. Before you stream this installation job, warn people not to use these programs for a while. :hello mgr.robelle :warn @;please exit from Suprtool and Suprlink NOW! :stream install.suprjob Once Suprtool has been installed, check the installation job $stdlist. If anyone was either using Suprtool, STExport, Suprlink, or Speed Demon, or attempting to back them up, the installation job will fail. Chase away any users and ensure that a backup is not in progress, then stream the installation job again. The installation job renames your current versions of Suprtool and its components to the PubOld group of the Robelle account. If you need to move these versions back into production, use the Previous.suprjob job stream. You can now access Suprtool by entering :run suprtool.pub.robelle Optional Installation Steps On MPE/iX your installation should be complete. If you have a copy of Speed Demon or the Suprtool2 interface in your own XL files, you will have to update them with the new versions (use the instructions in the Speed Demon and Calling Suprtool user manuals). To use the new versions on MPE V, you still need to install Speed Demon and Suprtool2 in the system SL. MPE/iX users must also do this if they are calling Speed Demon or Suprtool2 from compatibility-mode programs. With so few changes to Speed Demon and Suprtool2, you can safely ignore them for this version of Suprtool. If you have a Windows PC, you can install all the Suprtool documentation in the popular WinHelp format of Microsoft Windows. Step 4: Speed Demon/V Installation (optional) To use the new features of Speed Demon/V, you must install the latest version in the system SL. You should follow the installation instructions in the Speed Demon user manual. These instructions assume that you have used the Install.suprjob job stream to move Suprtool and its components into the Pubnew group of the Robelle account. :stream demon.suprjob.robelle Step 5: Suprtool2 Interface Installation (only Classic) The Suprtool2 interface has been revised. On MPE V you must re-install the interface. If you do not have the latest Suprtool2 interface, programs that attempt to use totals from Suprtool2 will fail. You can install this interface without recompiling any of your existing programs. System SL Installation To install the latest Suprtool2 interface in the system SL, use our standard installation job: :stream suprcall.suprjob.robelle User SL or XL Files If you have a copy of the Suprtool2 interface in your own SL or XL, you will need to update it. For instructions on how to do this, consult the user manual for Calling Suprtool. Step 6: Limit Suprtool's Run Time Priority (optional) Some system managers like to restrict the amount of resources that Suprtool consumes. One way to do this is by running Suprtool in the D queue, which lets you use HP's Linkedit program. :linkedit >altprog suprtool;maxpri=ds >exit By forcing Suprtool to always run in the lower queue (even when Suprtool runs on-line), it competes less with on-line users because most users run in the C queue. System managers should only restrict the priority of Suprtool if they are familiar with MPE process queues and the Tune command. Step 7: Install WinHelp Documentation Files (optional) The Suprtool documentation for both MPE and HP-UX is now available in the WinHelp file format of Microsoft Windows. You can use these files only 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. This Zip file on the HP 3000 is called Suprhelp.Helpnew.Robelle. Log on as Mgr.Robelle and 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 suprhelp.whelp.robelle 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} Step 8: Install QLIB and Bonus Programs Suprtool comes with an array of contributed software in the QLIB library (in the QLIB groups of the Robelle account). QLIB programs may be used on any CPU and may be given away freely. Your Robelle license may also entitle you to receive our Bonus programs: Compare/iX, HowMessy, Select, Spell, and Xpedit. These programs reside in the Pubnew group of the Robelle account. Bonus programs can only be used on authorized machines, and you may not distribute them to anyone. If you received Bonus programs with this version of Suprtool, use the job stream called Bonus.Job.Robelle to install both the QLIB and Bonus programs. If you did not receive Bonus programs, use the job stream Qlib.Job.Robelle to install the QLIB programs. :hello mgr.robelle :stream bonus.job.robelle {or Qlib.Job.Robelle} If you skip this step, you might end up running old versions of these programs. Step 9: Purge Installation Files (optional) The easiest way to clean up after an installation is to stream the Cleanup.Purgejob.Robelle job. This job saves you disc space by purging the installation files. It does not purge the files that are necessary to run the software. Enhancements Every year we provide Suprtool users with new features. The following section describes the new enhancements to Suprtool since the last major release. Variable Substitution Suprtool, Suprlink and STExport are now capable of CI variable substitution at the command line. This feature is only available in the NM version of these programs and if you turn it on with the following set command: set varsub on Suprtool is able to substitute any CI variables from any command line source, whether thru interactive, use file or batch input. Variable Substitution is not on by default for backward compatibility. Example Since Suprtool now is capable of CI Variable Substitution you no longer need to echo commands out to a file and then subsequently use the file that was created. The following example varies the sort order of an extract with the CI variable of order. !setvar order 'desc' !run suprtool.pub.robelle set varsub on base test get dline sort ord-num,!order output file3y exit Batch The Streams facility (under default setup) will replace any "!" found in the first column of a job stream. Anytime you want to specify an entire line thru Variable Substitution you will need to leave a space before the variable is specified. !setvar a 'base mydb;get orders;output file3x;exit' !run suprtool.pub.robelle set varsub on !a Notes For MPE commands some variables will be resolved twice when passed off to MPE, which will give different values for a variable. Setting variables at the CI level: MPEXL:setvar a 10 MPEXL:setvar b "!!a" MPEXL:showvar [ab] A = 10 B = !a Setting variables within Suprtool with Variable Substitution turned on changes the value of b. >set varsub on >setvar a 10 >setvar b "!!a" >showvar [ab] A = 10 B = 10 Since the problem is that Surptool does one level of Substitution prior to the command being passed off to MPE, we simply recommend that you set the variables prior to running Suprtool, or that you temporarily turn off variable substitution with the set varsub command. >set varsub off >setvar a 10 >setvar b "!!a" >showvar [ab] A = 10 B = !a >set varsub on Variable Substitution is not available in the $read feature of the If command. $Abs function Suprtool supports a $abs function which returns the absolute value of the number. For example if the field credit contains the value -547.83, the $abs function will return 547.83. This function will work on a field or even an expression such as: >if $abs(credit / 100 * 1.07) This function will also work in the extract command: >def newcredit,1,4,double >ext newcredit = $abs(newcredit / 100 * 1.07) $Days function Suprtool supports a $days function which will convert any supported date to a Julian Day number (the number of days since 4713 BC). This allows for Date arithmetic, in which you can calculate the difference between two dates, even if they have dissimilar formats. For example you could find all orders that were not shipped within 30 days of being ordered. >form ordfile File: ORDFILE.SALES.MFG (SD Version B.00.00) Entry: Offset ORDER-DATE x8 1 <> SHIP-DATE X8 9 <> ORDER-NUMBER X6 17 Limit: 10000 EOF: 15 Entry Length: 23 Blocking: 16 >in ordfile >if $days(SHIP-DATE) - $days(ORDER-DATE) >=30 >list >xeq IN=15, OUT=4. CPU-Sec=1. Wall-Sec=1. As with the $stddate function, if a date is not a valid date then the result of the $days function will be zero. Similar to the $stddate function the $days function is also available to the extract command. You can convert any supported date to a Julian day number in the following manner. >in ordfile >def ship-days,1,4,double >def order-days,1,4,double >ext order-no >ext ship-days=$days(ship-date) >ext order-days=$days(order-date) >out neword,link >xeq IN=15, OUT=15. CPU-Sec=1. Wall-Sec=1. If an invalid date is encountered the value that is extracted will be zero. $Truncate function Suprtool supports a $truncate function which returns the number to the left of a decimal place. No rounding will take place. For example if the field stddev contains the value 547.83, the $truncate function will return 547. This function will work on a field or even an expression such as: >if $truncate(stddev / 100 * 1.07) This function will also work in the extract command: >def newdev,1,4,double >ext newdev = $truncate(stddev / 100 * 1.07) If Command The If command previously only supported patterns or fields of only up to 256 characters for a pattern matching operation. This restriction is no longer in effect. >in long >def a,1,1000 >if a=="@Company@" >list >xeq Item Command - Date The Item command now has two new date formats, these date formats are EDSDATE and JulianDay. EDSDATE The Item command now supports a new date format called EDSDATE, which is a date in a format similar to yyymmdd, where the first digit represents the century. The first digit in the EDSDATE is either 0 or 1, where 0 represents a century of 19 and 1 represents a century of 20. These date formats are available as either a double integer or a Packed field. >item order-date,date,edsdate JulianDay Another new date, called JulianDay has been added to the Item command. The JulianDay number is the absolute count of the days that have elapsed since Noon 1 January 4713 BC on the Julian Calendar. Typically Julian Day Numbers refer to integer number corresponding to whole days, while the Julian Date may mean an integer plus decimal that brings the Julian count down to precise parts of a day. Suprtool supports the "JulianDay" number and does not attempt to support an hour or point in the day. This date format is available for a double integer or double logical data type. >item daydate,date,julianday Item Command - PHDate8 PHDate8 PowerHouse versions 8.19 and higher have changed their Phdate format stored in a single integer (j1) container. The allowed range of values for the year is now 00 - 127. The Item command has been enhanced to support this new format: >item daydate,date,phdate8 Given the fact that many users may have a lot of Suprtool code with references to the Item command we have provided a Set command to change: >item daydate,date,phdate to mean: >item daydate,date,phdate8 The set command is: >set date MapToPhdate8 on This Set command only changes the reference to phdate to phdate8 in the Item command, it does not change references that already exist in self-describing files nor does it change the data. MPE/iX 6.5 Suprtool, Suprlink and STExport have had some internal changes made in order to support MPE/iX 6.5. We have tested some of the new features on MPE/iX 6.5, thru early access to this new version of the Operating System. We have done some limited testing on MPE/iX 6.5 and recommend that you use Suprtool version 4.2.55. Some of the tests involved sorting, linking and exporting up to 20Gb of data. We wish to hear from all of you who are planning to move to MPE/iX 6.5 in the near future. Set Command - Date A new Set command has been added to help change any Item command reference to phdate to mean phdate8, for assistance in converting to the newer phdate format found in PowerHouse version 8.19 and higher. The Set command is: >set date MapToPhdate8 on This only changes the reference to phdate8 in the Item command, it does not change references that already exist in self-describing files nor does it change the data. Set Command - Varsub A new Set command has been added to turn on a Variable Substitution at the command line for Suprtool, Suprlink and STExport. The Set command is: >set VarSub On Turning this option on tells Suprtool, Suprlink and STExport to resolve any CI variables in the command line. Suprlink and STExport Suprlink and STExport now support filenames of up to 240 characters in the Input, Output and Link commands. Bugs Fixed Speed Demon. Speed Demon was not properly defaulting to a prefetch value of 2 if the spdeprefetch jcw was not set explicitly. Speed Demon. Speed Demon was not properly handling prefetch on the second chunk of a jumbo dataset. Get Command. Suprtool incorrectly reported that Eof was greater than calculated for the last chunk of Jumbo Master datasets. Heap Space. Suprtool now properly returns heap space after Sort and Table (File Option) operations. Heap Space. Suprtool would fail with Heap chain corruption in one case during a reset all operation. If Command. The If command would incorrectly select records when operating on Real or Long data types. Reset Table. A Reset Table command would fail with an error message unable to Reset Table space in certain situations. $stddate and phdate. The $stddate function will now apply the cutoff rules for the phdate format in small-int (I1 & J1) data fields. QLIB and Bonus Enhancements Qedit comes with an array of contributed tools in the QLIB library. Your Robelle license may also entitle you to receive our five Bonus programs. All of these tools are updated throughout the year, not necessarily in sync with Qedit or any other Robelle product. If you have the Bonus programs, you may use them only on appropriately licensed CPUs. The QLIB programs, however, may be used on any CPU and given away freely. The most recently released Bonus and QLIB tools are as follows: Bonus Contributed Compare/iX 2.6 Helpcomp 2.2 HowMessy 2.6 Printdoc 1.7 Select 3.9 Prose 4.3 Spell 1.8 Pscreen 89C Xpedit 1.7 Qcopy 4.6 Qhelp 2.2 QLIB Programs Since the last major release of Qedit, the following QLIB programs have been enhanced with these new features: Prose 4.3 Prose is the text formatter that we use for all our documentation, from user manuals to on-line help. Prose now formats 20xx dates correctly in the .FORM specifications. Appendix: Non-Robelle Installation Suprtool is usually installed on your HP 3000 in the Robelle account (see the installation instructions earlier in this change notice). However, you can easily install Qedit into another account by following these general steps: 1. Restore the files into your account. 2. Stream the account upgrade job (with modifications). 3. Stream the installation jobs (with modifications). For example, to install Suprtool into an account called Tools and into the same groups as Suprtool would have used in the Robelle account (Pub, Doc, Help, etc.), follow these steps. Step 1: Restore Files Restore the files into your account, which is Tools in this example. :restore *rtape;@.@.@;account=tools Step 2: Stream the account upgrade job (with modifications) With a text editor, change all account references in the Robelle.Job.Tools job from "robelle" to "tools." Don't worry about changes to some of the comments in the job. Note that this job will change the capabilities, access flags, and logon password of the Tools account. Examine the job carefully to ensure that the changes do not cause problems for other software in the Robelle account. :run qedit.pub.tools /text robelle.job.tools /change "robelle"(upshift) "tools" all Step 3: Stream the installation jobs (with modifications) Now log on to the Tools account instead of the Robelle account. :hello mgr.tools :run qedit.pub.tools Before streaming any jobs, you must alter them so that they log on to the Tools account instead of the Robelle account. Make the following change to each job in the Suprjob, Job, and Purgejob groups: /text install.suprjob /change "robelle"(upshift smart) "tools" all /keep /exit :stream install.suprjob We have used Robelle's Qedit text editor to make the required changes to the account name in this example, but you can use any editor. Just make sure that all occurrences of "robelle" are changed, regardless of whether "robelle" is in uppercase, lowercase, or mixed case. Only change "robelle" when it is a separate word, not when it is embedded in a longer word.