SUPRTOOL Version 4.5 Database Handyman for the HP e3000 Change Notice Installation Instructions Addendum to 4.3 User Manual Suprtool 4.5 Dbedit 4.5 Suprlink 4.5 STExport 4.5 Speed Demon 4.5 Suprtool2 4.8 Robelle Solutions Technology Suite 201, 15399-102A Ave. Surrey, B.C. Canada V3R 7K1 Phone: (604) 582.1700 Fax: (604) 582.1799 E-mail: support@robelle.com Web: www.robelle.com December 2001 Program and Manual Copyright Robelle Solutions Technology Inc. 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 Solutions Technology Inc. Other product and company names mentioned herein may be the trademarks of their respective owners. Introducing Suprtool Version 4.5 * Highlights * Compatibility * CPU Serial Number and CPU Name * Compatibility Mode vs. Native Mode * Documentation * Documentation Formats Suprtool provides fast access to your data on the HP e3000. 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 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.5 * Support for "well-formed" XML in STExport. * Suprtool, STExport and Suprlink can now have warnings turned off when run from batch with the set warnings off command. * CM to NM switches in Suprtool have been decreased significantly. * Suprtool now has the ability to load and extract data from a Table. * Loading a Table is now up to 28% faster than previous versions. * Table lookup operations are now up to 33% faster than previous versions. Highlights in Version 4.4 * Suprtool now supports string expressions in both the Extract and If commands. String expressions allow users to select and format their byte-type data in numerous new ways. This includes combining byte-type fields together, upshifting and downshifting data, and trimming blanks. These new features combine to reduce the number of tasks needed to select and format the data the way you need it. * Suprtool, Speed Demon and HowMessy now support the new database limits of 1,200 items, 240 sets and 64 paths for a master dataset. * Suprtool now supports the new Entrynumber format for databases available in IMAGE version C.09.00 and later. * Suprtool now supports 5,100 bytes of constants to be extracted. (only NM and HP-UX) * Suprtool, Suprlink and STExport now have the ability to create their own persistent redo stacks. The contents of these stacks can be recalled not only in the current session, but also in a future session. Compatibility Suprtool, Speed Demon, STExport, Suprcall and Suprlink are compatible with MPE/V, MPE XL, and MPE/iX, including MPE/iX 6.5 and MPE/iX 7.0. CPU Serial Number and CPU Name (HPSUSAN & HPCPUNAME) This program runs only on CPUs whose serial numbers have been encoded ("showvar hpsusan" on MPE/iX). This program may also be encoded with your HPCPUNAME values. If it fails to run and you get an "invalid HPCPUNAME" or "invalid HPSUSAN" error message, contact 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 e3000 (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.pub.robelle This is the list of documentation files for Suprtool (NOTE: These file names assume that Install.Suprjnew 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 Formats The user manuals for Suprtool and its components are also available in the several popular formats such as PDF and HTMLHelp at: http://www.robelle.com/library/manuals/ Installation of 4.5 If you need to install this upgrade in an account other than the Robelle account, use the installation instructions in the appendix at the end of this change notice. 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 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 QLIB and Bonus programs. 8. Purge the installation files (optional). Ecometry Users Users of the Ecometry application need to use the installation instructions supplied by Ecometry Corporation. Those instructions have extra steps for updating the Ecometry code accounts. You will find the Ecometry version of these instructions at http://www.robelle.com/ecometry/ 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. Technical support can also be obtained via e-mail at: support@robelle.com 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.pub.sys 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.pub.sys 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 120,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 Pub group of the Robelle account. At this point in the installation process, the files do not yet have the correct names. The install job 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} Note that during installation we add OP capability to the Robelle account. After installing Suprtool, 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 few changes to Speed Demon and Suprtool2, you can safely ignore them for this version of Suprtool. 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 Pub 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 limit the amount of resources that Suprtool consumes. One way to do this is by running Suprtool in the D queue. You can configure this using 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 restrict the priority of Suprtool only if they are familiar with MPE process queues and the Tune command. Step 7: 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 Pub 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 8: 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 in Version 4.5 We constantly provide Suprtool users with new features. The following section describes the new enhancements to Suprtool since the last major release. CM to NM Switches Decreased Suprtool has dramatically decreased the number of CM to NM switches. In our internal testing we have seen reductions from between 8 and 24 times, depending on the task. Set Warnings Off Suprtool, STExport and Suprlink have a new command called Set Warnings which when turned off will no longer print warning messages if you are running in batch. In Suprtool, you can simulate batch mode with the command Set Interactive off. If Set Warnings is off, Suprtool will honour the value of the Interactive setting, provided Set Warnings off is set after the Set Interactive command. This feature is for those customers that have software packages that do analysis of your $STDLISTs. By preventing the "Warning:" messages from being printed, these Suprtool scripts will not get flagged as jobs that failed. Loading Tables Performance Improvement Suprtool has the ability to load key-values into a table via the Table command. The loading of the key-values into the table has been improved by up to 28%. If $Lookup Performance The performance of tasks with an if $lookup operation have had a performance boost of up to 33%. Extract from a Table Suprtool now has the ability to load data into a table via the Table command, and extract that data out of the table using the Extract command. The Table command (MPE/iX only) now allows for data to be loaded along with matching key values. >table table-name,key-field,file,filename,& data(field1,field2,...) An example of loading two data fields called cost and desc along with the key field of part into a table would be: >table partab,part,file,partin,data(cost,desc) You can specify up to 20 data fields as long as the total size of the key fields and data does not exceed 256 bytes. The Table file must be Self-Describing (Link) in order to use the data option. When loading data into a table, Suprtool will eliminate the duplicate entries based on the key value, so the associated data values may not be loaded into the table. The Extract command can utilize the $lookup function to return data. The syntax for the $lookup function would look as follows: >extract target = $lookup(table-name,key-field,data-field) The Table name, key-field and data-field are all defined by the Table command, which must be input before the Extract command. A classic example: your boss comes to you with a list of new prices and descriptions for certain parts for your Part-Master dataset. The basic steps to do this are to load the new prices and descriptions into a Table, index by the product number (prodno), then Extract the price field from each record and replace it with a $lookup on the table. Here is the Suprtool code: >table newprices,prodno,file,bosslist,data(price,desc) >get part-master >if $lookup(newprices,prodno) >update >extract price = $lookup(newprices,prodno,price) >extract desc = $lookup(newprices,prodno,desc) >xeq We do the If $lookup to select only the parts which have new prices, then do Extract with $lookup to replace the existing price with a new one. The Update command forces a database update on each selected record and must come before the Extract command. If you did not specify the If $lookup, then records that did not qualify under the $lookup function in the extract field, will result in zeroes for any numeric field and spaces for any byte type fields. XML Command STExport will now generate "well-formed" XML output with just a few commands. :run stexport.pub.robelle $input file1sd $xml $output myxml $xeq These four simple commands will generate the following file that packages such as XMLSpy will consider to be "well-formed" XML. The result of such an STExport task will look as follows: Los Altos 100000 4003302 20 Ralph Perkins CA Room 655 Los Altos 040033022 93002 By default STExport will add the simplest version tag at the beginning of the file, then it inserts a and matching at the beginning and the end of the file. Then STExport encloses each record from the input file in a and tag. Finally, the Self-Describing tags are added around each field's data values and edited appropriately. Naturally users would want options to customize and specify the various options and tags themselves, in order to generate a file that is acceptable to their tools. You can specify the "version" tag at the beginning of the XML file with the following command: xml version "?xml version='1.0' encoding='ISO-8859-1'?" STExport will put the "<" and ">" around what is specified in the version string. In addition, you can customize the "file" and "record" tags with the following simple commands: xml file "orders" record "orderdetail" You can enter multiple XML commands per task to set the XML options you require. $in file1sd $xml version "?xml version='1.0' encoding='ISO-8859-1'?" $xml file "Orders" record "Details" $out myfile An example of the output generated by the above commands is as follows:
Los Altos 100000 4003302 20 Ralph Perkins CA Room 655 Los Altos 040033022 93002
In XML the tags that surrounded the data can not have any special characters other than hyphen, underscore and period ("-","_", "."). So STExport replaces any of the invalid special characters with a "." by default. You can change the default character to be something else with the following set command: $Set xmltagchar "_" STExport will only allow the hyphen, underscore and period to be set with this command. A Document Type Declaration can be made at the beginning of the file via the !DOCTYPE specification. This typically tells whatever tool that is parsing the xml file where the DTD for the file resides. In STExport you can specify simple one-line doctype specs with the following command: xml doctype '!DOCTYPE address-book SYSTEM "address-book.dtd"' This will write the doctype specification at the top of the output file, directly after the XML version specification. More complicated and lengthy doctype specifications can be implemented by using the filename option, whereby STExport will append the contents of a named file directly after the version specification. The syntax can be simply: xml doctype myfile.xml All of STExport's XML command options (version, doctype, file and record) allow for a string to be passed via surrounding quotes. The quotes may be either single or double, but keep in mind that if the string is to contain double quotes, then you should surround the entire string with single quotes. So to summarize this new feature the following commands have been added for XML support. The XML command has the following options: XML VERSION "string" DOCTYPE "string" | FILE "string" RECORD "string" The following set command has been added to aid in the conversion of special characters in the tag: set xmltagchar "." Bugs Fixed in Version 4.5 Dividing Zero by Zero. Some division operations would result in a large number when dividing zero by zero if the target type was zoned, packed or quad integer. Divide Operations. Suprtool could not properly convert the result of a division operation if the target was zoned or packed, in one specific case. Extract Character Constant. If you had a extract of a character constant, and if the constant specified was not completely filled in for all of the positions in the length of the field, Suprtool would would produce strange results. Error Message. The error message on a failure to open the $stdin file has been improved. Define Command. A warning message has been added in the case where fields defined as non-standard integers, will be treated as strings. Extract Command The error message that prints when the expression specified cannot be coerced/converted into the target has been improved. If $Read Operations. Suprtool would incorrectly put commands entered thru the $read facility into the redo file or stack when executed thru a Use file. Table Command. Suprtool would not hold on to a table in some cases when the hold option was specified in the table command. The CM and HP-UX versions of Surptool would not hold on to the correct table in some cases. Verify Command. Verify Define will now show the correct information when defining non-standard integers. Variable Substitution. Suprtool did not handle resolving of system variables that are defined with no value. Variable Substitution. Suprtool did not properly handle a variable that was only a comment. Enhancements in Version 4.4 Every year we provide Suprtool users with new features. The following section describes the new enhancements to Suprtool since the last major release. IMAGE Limits Starting with MPE/iX 6.5 Express 2, a new version of IMAGE, C.09.00, will be available. This version of IMAGE, as well as later versions, now supports 1,200 items, 240 datasets and 64 paths from a master dataset. The previous limits for a master were 1,023 items, 199 datasets and 16 paths. Suprtool, Speed Demon, Dbedit and HowMessy now support this new version of IMAGE. Large Datasets IMAGE now supports datasets larger than 80 GB. In order to do this, the IMAGE label was changed to keep track of records and the pointers that hold them together. Prior to version C.09.00, IMAGE stored records in what is known as Entryname format. In IMAGE version C.09.00 and later, you can now select a new option called the Entrynumber format. This change to IMAGE must be invoked either by building a new database or by converting a database with an HP-supplied utility called Dbbigset.Pub.Sys. You can read more about this change in the MPE/iX 6.5 Express 2 Communicator (available at www.docs. hp.com) or get more details from the Robelle Web site. Suprtool has been enhanced to support this new internal change to IMAGE. HowMessy currently returns an error when you attempt to report on a dataset with this feature enabled, because the block number calculations are no longer relevant for this type of database. We are currently reviewing how best to report on the efficiency of databases that use this new format. Extracting Constants Until now, Suprtool was limited to 1,530 bytes of constants for MPE/iX and HP-UX versions of Suprtool. This limit has now been increased to 5,100 bytes. The MPE/V version of Suprtool is still limited to 1,275 bytes. Persistent Redo Commands entered at the Suprtool prompt are saved in something called the redo stack. You can recall commands from this stack by using other commands such as Before, Do and Redo. By default, the redo stack is stored in a temporary file and discarded as soon as you exit Suprtool. This temporary stack is not preserved across Suprtool invocations. The new Set Redo command assigns a permanent file to the redo stack, allowing the stack to become available for future Suprtool invocations. For example, to assign the Myredo file as a persistent redo stack, enter >set redo myredo If the file does not exist, Suprtool creates it. Otherwise, Suprtool uses the existing file. All subsequent commands are written to the persistent redo stack. This setting is valid for the duration of the Suprtool session. As soon as you exit Suprtool, the setting is discarded. Next time you run Suprtool, you will get the temporary stack. If the file name is not qualified, the redo stack is created in the logon group and account. This may be desirable if you want to have separate stacks. If you want to always use the same persistent stacks, you should qualify the name. The Verify command shows which stack is currently in use. If it shows , then Suprtool is using the default stack. Anything else is the name of the file used on the Set Redo command. If a file with the specified name already exists, it must be specifically created by a Set Redo command. Suprtool, Suprlink and STExport do not overwrite an existing file. Concurrency When Suprtool uses the default temporary stack, it is accessible only to that particular instance of Suprtool. You can run as many Suprtool instances as you need and each one gets its own redo stack. With temporary stacks, you will never have concurrency problems. If you start using a persistent redo stack, however, you might start running into concurrency problems. A persistent redo stack can be used by only one Suprtool instance at a time. If you try to use a persistent redo stack that is already in use, you will get the following message: >set redo myredo EXCLUSIVE VIOLATION: FILE BEING ACCESSED (FSERR 90) Unable to open file for REDO stack In this situation, Suprtool continues to use the redo stack active at the time and lets you continue working as normal. Qedit can also have permanent redo stacks. To prevent products from writing to each other's redo stack, it is advisable to have separate stacks for each product by giving them different file names. For example, if you use >set redo myredo you will have a redo stack called Myredo for your Suprtool commands. If you exit Suprtool, then run Qedit and supply the same Set Redo command, your Qedit commands will be written to the same file that was used for your Suprtool commands. String Expressions Both the Extract and If commands have been enhanced to allow string expressions, which can be used to: 1. Combine two fields together (using the + operator). 2. Remove spaces (using the built-in trim functions). 3. Upshift or downshift characters. String expressions reduce the number of tasks required for many common operations involving byte-type fields. Fewer tasks means that Suprtool delivers data to your applications faster than ever before. These changes are so extensive that string expressions are described separately for the Extract and If Commands. See the sections below for specific details and examples of string expressions. Extract Command You can now use string expressions in the Extract command. They allow you to combine byte-type fields together (using the + operator) or operate on byte-type fields with special functions. In many cases, you can now reduce the number of tasks required to format your data the way you want. Fewer tasks means that Suprtool delivers the data where you need it faster than ever before. To extract a string expression, use this syntax: EXTRACT target-field = expression Target-Field The target-field determines the byte-length of the expression. The data-type must be Byte or Char. The expression is extracted during the output phase and cannot be used by other Suprtool commands that accept fields (e.g., Sort). Examples >extract id-no = warehouse-no + bin-no >extract full-name = first-name + last-name Constants vs. Expressions If you have a string expression that starts with a string, Suprtool assumes that you are attempting to extract a single string value and not a string expression. To specify a string expression that starts with a constant, surround the expression with parentheses. For example, Incorrect >extract name = " " + product-desc Error: Missing comma or invalid arithmetic expression Correct >extract name = (" " + product-desc) Variable Length Strings String expressions use variable-length strings. Suprtool keeps track of the length of every string, and all operations are done using the actual string length. For fields, the length of the string is the length of the field. If you do not want to retain all the spaces in a field, use one of the built-in trimming functions. String constants are created with the exact length of the constant. For example, the string "abc" is three characters long and the string "a" is one. When assigning the string expression to the target field, Suprtool pads the final string value with spaces to fill out the target field. String expressions longer than the target field generate an error. >in testfile >def a,1,10,byte >ext a="I'm too long for this container" Error: String is too long for the specified item String Truncation Suprtool produces an error if the string expression is longer than the target field. You cannot override this error with Set Ignore On. To help avoid the error, you may want to trim trailing spaces from the expression before assigning it to the target field. For example, >extract new-field = $trim(a + b + c) Upshifting Strings ($Upper) Use the built-in function $upper to upshift all the characters of a string expression into uppercase characters. This function can be used to upshift a single field, a complicated string expression, or any subpart of an expression. Both ASCII and Roman-8 characters are upshifted by $upper. For example, >extract city-up = $upper(city) >extract full-name = $upper(first + last) >extract desc = desc-1 + $upper(desc-2) Downshifting Strings ($Lower) If you want to downshift all characters of a string expression to lowercase, use the built-in function $lower. This function can be used to downshift a single field, a complicated string expression, or any subpart of an expression. Both ASCII and Roman-8 characters are downshifted by $lower. For example, >extract city-lower-case = $lower(city) >extract city-state = $lower(city + state) >extract desc = desc-1 + $lower(desc-2) Trimming Spaces ($Trim, $Ltrim, $Rtrim) Use one of three built-in string functions to remove leading or trailing spaces from a string expression. The three functions are: $Trim: Remove leading and trailing spaces from the string expression. $Ltrim: Remove leading spaces. $Rtrim: Remove trailing spaces. If Command You can do comparisons with byte-type fields in numerous ways using Suprtool. These powerful features minimize the number of tasks you must execute in order to select the data you need. The fewer the number of tasks, the faster your data is delivered to the users and applications that need it. You can combine byte-type fields together and use the built-in string functions to create string expressions. String expressions involve the + operator and any of the built-in string functions, which are $lower, $upper, $trim, $ltrim and $rtrim. Fixed vs. Variable Length Strings String comparisons are done using fixed- and variable-length strings. For most users, there should be no difference between the two types of strings. When doing string comparisons, Suprtool always pads shorter strings with spaces, with the one exception of comparing two fixed-length fields (see "Byte Fields" below). String expressions involving the + operator or the $lower, $upper, $trim, $ltrim and $rtrim built-in functions are done using variable-length strings. Suprtool keeps track of the length of every string, and all operations are done using the actual string length. For fields, the length of the string is the length of the field. If you do not want to retain all the spaces in a field, use one of the built-in trimming functions. When creating string expressions, string constants are created with the exact length of the constant. For example, the string "abc" is three characters long and the string "a" is one. Byte Fields For historical reasons, comparing two byte-type fields to each other is a special case. If the two fields are exactly the same length, Suprtool compares them completely. If one field is shorter, the comparison is done for the length of the shortest field. Suprtool does not check for spaces in the trailing characters of the longer field. For example, >define short, 1,10 {10-character field} >define long ,11,15 {15-character field} >if short = long In this example, Suprtool compares the 10 bytes in the short field with the first 10 bytes of the long field, but ignores the last five bytes of the long field. If the expression on either side of the equal sign consisted of more than one field (using the + operator) or involved any of the built-in string functions, such as $lower, $upper, $trim, $ltrim and $rtrim, Suprtool would have compared both sides of the equal sign by padding the shorter field with spaces. It is only the case where you are directly comparing one byte-type field to another that Suprtool uses the length of the shortest field for the comparison. Trimming Spaces ($Trim, $Ltrim, $Rtrim) Use one of three built-in string functions to remove leading or trailing spaces from a string expression. The three functions are: $Trim: Remove leading and trailing spaces from the string expression. $Ltrim: Remove leading spaces. $Rtrim: Remove trailing spaces. Because Suprtool pads shorter strings with spaces when doing comparisons, trimming spaces is most useful when creating a combined string with several fields. For example, you might want to combine a person's first and last name (including a space between the two): >if $trim(first) + " " + $trim(last) = "Joe Smith" Mixed Case ($Upper and $Lower) By default, Suprtool does an exact match when comparing two string expressions. If the expressions vary in the capitalization of characters, Suprtool finds them to be unequal. To do caseless string comparisons or pattern matches, use the $upper or $lower functions. Both ASCII and Roman-8 characters are shifted by $upper and $lower. For example, >if $upper(city) = "VANCOUVER" >if $lower(city) = "edmonton" Note that if you use the $upper or $lower functions, Suprtool does not shift any constants in the comparison. You must explicitly specify the constants in the correct case or you can use $upper or $lower with the constant: >if $upper(city) = $upper("vancouver") Use the $upper or $lower functions for caseless pattern matching. As with other comparison operators, you must specify constants in the correct case when doing pattern matching: >if $upper(city) == "VAN@" >if $lower(city) == "ed@" You can use $upper and $lower with string expressions that combine many fields and string functions as shown in the following example: >if $read - $upper($trim(first) + - " " + - $trim(last)) - = "JOE SMITH" - Bugs Fixed in Version 4.4 Arithmetic Operations. Suprtool now has a better error message when an arithmetic operation has an invalid decimal operand length. Extract Command. When extracting constants, Suprtool no longer incorrectly reports that the constant limit has been reached. Extract Command. When extracting one field into another, invalid data is no longer produced if the two fields are exactly the same length and type, but have a different number of implied decimal places. Extract Command. When the maximum limit of extracted constants is reached, Suprtool no longer incorrectly reports the following message: Error: Number of constants in >EXTRACT exceeds maximum This error message has now been changed to Error: Total size of constants in >EXTRACT exceeds maximum Get Command and Speed Demon. Suprtool no longer incorrectly determines the highwater mark if the dataset is non-Jumbo, the capacity is large, and the blocking factor is one or two. Prefetch'point Failure. Suprtool no longer fails with a prefetch'point failure if the input file has an odd record size and the record being selected is the last record in the file. Set Ignore On. Suprtool now honors the Set Ignore On flag when encountering an illegal packed decimal number in the $stddate function. Suprmgr Commands. Suprtool no longer prints a blank line for every command in the Suprmgr.Pub.Sys file.