What's Up, DOCumentation? 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 Date: December 1998 From: Robert M. Green, CEO David J. Greer, President Mike Shumko, Editor pro tem To: Users of Robelle Software Re: News of the HP 3000 and of HP-UX, 1998 #6 What You Will Find in This News Memo: New Suprtool Date Functions Qedit/iX 4.7.01 May Be Unreadable Frequently Asked (and Answered) Questions Y2K Upgrading Your System? Training Opportunities Bug in MPE/iX Powerpatch 5 Newsletter Available by E-Mail Robelle Attends User Meetings Staff Spotlight: Dave Lo User Manual on the Web Qedit Screen Mode Also Works on HP Terminals New Windows Scripting Offers More Power & Choice Windows of the World Will Unite Suprtool Tips Find by Last Letter Search for Binary Data Using ASCII Criteria Part Two of Get vs. Chain Can't Run Your Bonus Programs New Suprtool Date Functions =========================== The new $stddate function in Suprtool, introduced in our June issue, adds flexibility to handling date fields. Now you can: - compare dates with dissimilar formats - update six-digit dates in any format to eight-digit ccyymmdd dates - create extracts with four-digit years from records with two-digit years - compare six-digit dates to system date variables after Dec. 31, 1999 - perform less-than and greater-than comparisons on noncollating dates - sort on six-digit dates by using multiple passes For more examples of each of these $stddate applications, see our Web page at http://www.robelle.com/support/faq/stddate.html. Another new feature in the current pre-release is the Mod operation, which saves the remainder after a division operation. This is useful in selections based on specific digits of packed or binary numeric fields. For example, you can compare the dd portion of a ccyymmdd date against another field or constant: >comment find orders in first half of month >get order-detail >item order-date,date,ccyymmdd >if order-date mod 100 <= 15 >output 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. >comment find orders in Jan or Feb >get order-detail >item order-date,date,ccyymmdd >if order-date / 100 mod 100 <= 02 >output ordbegin >xeq A pre-release of Suprtool with $stddate and Mod is available now. There is no charge for upgrades to customers with support. [Paul Gobes] Qedit/iX 4.7.01 May Be Unreadable ================================= This message is directed to our users in the U.S. who recently received Qedit MPE 4.7.01 software update tapes dated "NOV. 98". These tapes were made using a DDS drive that had hardware compression enabled. This means that on some systems the tapes will not restore; the Restore command will produce an error message. If any computers on which you have licensed Qedit/iX have DDS drives that do not support hardware compression, please let us know so that we can replace your tape. We apologize for the inconvenience this may cause you. [Paul Gobes] Frequently Asked (and Answered) Questions Department ==================================================== Y2K --- Not surprisingly, the most frequently asked questions these days are related to Robelle's products and Year 2000. Most of your questions are answered at http://www.robelle.com/support/faq/year2000.html. Like everybody else, we are undergoing our own Y2K readiness program so that we'll be able to continue doing business with you. The book Year 2000 in a Nutshell from O'Reilly has been very helpful. It looks at the issues from a number of perspectives, including managerial, legal, and technical, and provides a master plan for conversion projects. Upgrading Your System? ---------------------- If you are upgrading your computer system within the same platform (e.g., from a series 9xx to another 9xx), the existing versions of your Robelle products continue to work, free of charge. If you are adding a new system (as opposed to upgrading or swapping), we offer generous licensing discounts on additional systems. If you are upgrading your O/S version, remember to check our Web pages for compatibility information. In general, you need to upgrade your Robelle products only if you want to take advantage of new features introduced in the new O/S. There is no charge for upgrades to customers with support. If you are going to upgrade to a new O/S, we recommend these specific versions of our products: - For MPE/iX 5.5, we recommend Qedit 4.4 or later, and Suprtool 3.8 or later. - For MPE/iX 6.0, we recommend Qedit 4.6.02 or later, and Suprtool 4.1.04 or later. [Mike Shumko] Training Opportunities ====================== Want to find out about Robelle's two-day classes on Suprtool? Get course details at our Web site (http://www.robelle.com/products/courses.html). If you need more information about pricing and scheduling, call Mike Shumko at 1-888-ROBELLE. [Mike Shumko] Bug in MPE/iX 5.5 Powerpatch 5 ============================== MPE/iX 5.5 Powerpatch 5 contained a performance enhancement patch for operations that return unused disc space. Some customers discovered a bug in this patch, however, when they performed a DBUTIL Erase operation, which resulted in problems with their database. A DBUTIL Erase asks the file system to reset the EOF and then fill the file with zeros, from the beginning of the file to the old EOF. It then calls FWRITEDIR to set the EOF. The problem was with the fill disc operation, which was not completely erasing the space properly. Typically, a customer can recognize this error from the following messages on DBPUT operations. For detail datasets: TURBOIMAGE ERROR AT $00016710; RETURN STATUS = -3 DBPUT, MODE 1, ON OF MPE FILE ERROR 0 RETURNED BY FREADDIR ON ROOT FILE For master datasets DBPUT operations fail with DUPLICATE KEY VALUE IN MASTER 3) (dberror 43) Any program that uses a similar strategy to either erase a file or return unused disc space may corrupt the file. The risk is greater with large files or files that have user labels such as database files, KSAM files or QUIZ subfiles. The problem is not limited to MPEKX79 in Powerpatch 5; it also exists in these patches: MPEKXE4, MPEKXB5, MPEKX94, MPEKXE9 and MPEKXG6. The patch that HP has developed to fix this problem (MPEKXJ3) is incorporated in Powerpatch 6. To easily identify the problem in your system, use this simple Qedit script file: /t hpswinfo.pub.sys /list "MPEKX79" /list "MPEKXB5" /list "MPEKXE4" /list "MPEKXE9" /list "MPEKX94" /list "MPEKXG6" [Neil Armstrong] Newsletter Available by E-Mail ============================== You can subscribe to the paperless What's Up, DOCumentation? newsletter by sending a request to support@robelle.com with your name and e-mail address. You can also read the on-line version at http://www.robelle.com/newsletter/. Robelle Attends User Meetings ============================= Robelle was recently invited to attend the Mortech and Software Research Northwest user group meetings for applications that use Suprtool. Mortech's application is Mail Order Cataloging. The users got together with the application developers at Mortech's Little Rock, AK base to discuss the system and how they use it. An impressive demo of ODBC was given by Curtis of Palladin Press. Other presentations were given by Adager, HP and Robelle. Rounding out this great meeting was a tour of the new offices and dinner at a local brewery. A week later in Washington, D.C., the Software Research Northwest (SRN) users group gathered. Their application is used in student administration settings, and many leading U.S. universities and colleges were present. SRN's system has been enhanced to have a Web front-end that allows students, faculty and administrators to enter and review their data. Wayne Holt and his SRN team busily mixed with users throughout the sessions and into the more sociable side of the meeting. I'd like to thank the hosts for inviting Robelle, and thank all those who attended the Suprtool tutorials. [Paul Gobes] Staff Spotlight: Dave Lo ======================== Dave Lo has been with Robelle for nine years now, but only lately has his profile been raised. He started out working on our Bonus and QLIB programs, the Qedit product and UNIX-related projects. A year ago Dave became more well known among Robelle users when he joined the Tech Support team. Now, he co- ordinates our technical documentation and is currently the Robelle Webmaster. Dave came to Canada from Hong Kong in 1974. He earned his Computer Science degree at the University of British Columbia in Vancouver. He then worked on PC psychiatric software ("You don't have to be crazy to work here, but it helps.") before joining Robelle. Dave practices Qigong (pronounced chee-gung) which is similar to the meditative aspects of Tai Chi. He maintains an extensive Qigong Web site at http://www.robelle.com/~dlo/qigong/. [Paul Gobes] Editor's note: You can get on-line information about all your favorite Robellians in the updated company brochure at http://www.robelle.com/ robelle.html. User Manual on the Web ====================== Until now, the only way you could get a Qedit for Windows User Manual or Quick Start Guide was to get a printed copy from Robelle or your distributor. Starting with the latest version of Qedit for Windows, these documents are available for download in Adobe Acrobat PDF format. All you need is the free Adobe Acrobat Reader to view or print the documents. The PDF files can be downloaded from Robelle at http://www.robelle.com/ products/qwin/download.html. [Dave Lo] Qedit Screen Mode Also Works on HP Terminals ============================================ In our previous newsletter we advised that HP was no longer supporting block- mode in HP-UX version 11. (See http://www.robelle.com/library/newsletter/ w1998-05.html#hp-ux.) We suggested using Qedit's screen mode, which had been designed primarily for VT terminals. What we didn't make clear was that screen mode works equally well if you use an HP terminal (or PC software emulating an HP terminal). Screen mode uses character-mode keystrokes in a full-screen environment, and enables features such as "live" scrolling, cutting-and-pasting, splitting and joining lines, etc. Enter Help VT at the Qedit/UX prompt for more information. Screen mode uses the HP-UX curses library to make it terminal-independent. [Hans Hendriks] New Windows Scripting Offers More Power & Choice ================================================ For years, the only scripting language available for MS Windows has been the original MS-DOS batch language. While tools like WinBatch have been available, they are difficult to use and error-prone because they work at the user interface level (simulating user actions such as selecting menu commands). Microsoft has now released its own scripting language: Windows Scripting Host (WSH). Once you have installed WSH, you can write your scripts in either VBScript or JScript. Both VBScript and JScript are much more powerful languages than the old MS-DOS command language. With scripts you can: - automate tasks - access the file system, to create, open, read, or write to files - create instances of COM objects, such as Microsoft Excel (e.g., start Excel, create a new worksheet, and then add data to it) Installing WSH Although WSH is bundled with Windows 98, you must select it as part of the installation. You can download a version for Windows 95 or Windows NT 4.0 from http://msdn.microsoft.com/scripting. After installing WSH, you have two new programs to choose from: Wscript or Cscript. Wscript is short for Windows Script and Cscript is short for Command Script. Both tools accept and run any script. Wscript provides a Windows dialog box for running the script, while Cscript is more appropriate for running a script from the MS-DOS prompt in Windows 95 or 98, or from the command prompt in Windows NT. You can make either Wscript or Cscript the default for running scripts. Files ending in .vbs are assumed to be VBScript and files ending in .js are assumed to be JScript. Because I happen to be a C/C++ programmer, and JScript uses a more C-like syntax than VBScript, the remaining examples in this article are in JScript. But the nice thing about WSH is that you can choose your scripting language; if you are more comfortable in Visual Basic, use VBScript instead. First Example Our first example will echo any command-line parameters. Obtaining the command-line parameters and echoing them require access to the WSH shell object. We'll first show you the script, then explain how it works: /* Sample script to echo command-line parameters. Copyright Robelle Consulting Ltd. 1998 */ // Version number for this script var Version = "Version 1.0"; // Shell object needed for command-line access and echoing var WSHShell = WScript.CreateObject("WScript.Shell"); function Welcome() { WScript.Echo("First Sample WSH Script " + Version); WScript.Echo("Copyright 1998 Robelle Consulting Ltd."); } /* Welcome */ function EchoScriptParameters() { var args = WScript.Arguments; if (args.Count() == 0) WScript.Echo("There are no command-line arguments"); else for (inx = 0; inx < args.Count(); inx++) WScript.Echo(args.Item(inx)); } // Mainline Welcome(); EchoScriptParameters(); Explaining the Example We start the script with a comment. Multi-line comments start with /* and end with */. Single line comments start with // (everything from // to the end of the line is ignored by JScript). The first statement is var Version = "Version 1.0"; This statement creates a variable called Version, which is a string with a value of Version 1.0. You refer to the variable by using its name, Version. Like C, JScript is case-sensitive so that the variable name in title case (Version) is not the same as the variable name in lowercase (version). We then create an object with the statement. var WSHShell = WScript.CreateObject("WScript.Shell"); The WScript.Shell object is part of WSH. This object gives you access to command-line arguments, environment variables, Windows shortcuts, and other useful objects for scripting. Use the WSHShell object to: - echo strings to stdlist - gain access to the command-line arguments object Functions The next group of statements declare a function: function Welcome() { WScript.Echo("First Sample WSH Script " + Version); WScript.Echo("Copyright 1998 Robelle Consulting Ltd."); } /* Welcome */ This function writes lines to stdlist using the WScript.Echo method. We can concatenate two strings together by using the + operator. The first string that we echo concatenates a constant (First Sample WSH Script) with a variable (Version). Although this first example does not contain these features, functions in JScript can have parameters and can return results. Command Line Processing The EchoScriptParameters() function echoes each command-line argument to stdlist: function EchoScriptParameters() { var args = WScript.Arguments; if (args.Count() == 0) WScript.Echo("There are no command-line arguments"); else for (inx = 0; inx < args.Count(); inx++) WScript.Echo(args.Item(inx)); } How do we access the command-line arguments? We have to use an object to do this. We create the args object with var args = WScript.Arguments; The args object has the properties and methods that we need. The Count() method returns the number of command-line arguments. Because we want our script to echo something reasonable, even if no command-line arguments are present, we check to see if there are zero arguments. If there are arguments, we iterate through each of them using for (inx = 0; inx < args.Count(); inx++) WScript.Echo(args.Item(inx)); The for loop uses standard C notation. The interesting part of it is args.Item(inx) Remember that args is the WScript.Arguments object. Each command-line argument is referred to by index. The first argument is args.Item(0), the second is args.Item(1), and so on. We use the variable name inx to loop through each possible argument, passing the value of the argument to the WScript.Echo() method, where it is displayed on stdlist. Invoking Functions We finish our script with the main controlling part. For this script, it is simple-we invoke the Welcome() and EchoScriptParameters() functions that we wrote. Welcome(); EchoScriptParameters(); Note that you must specify parentheses () when invoking a function. Otherwise, JScript assumes you are referring to a variable instead of a function. Invoking the Script Our script is designed to run from Cscript. You can run this script from Wscript, but each Echo() would result in a separate message box (which you would have to dismiss). Assume that this script is in the file called first.js. You would then invoke it as follows (user input is underlined): cscript first.js ---------------- Microsoft (R) Windows Scripting Host Version 5.0 for Windows Copyright (C) Microsoft Corporation 1996-1997. All rights . First Sample WSH Script Version 1.0 Copyright 1998 Robelle Consulting Ltd. There are no command-line arguments Our second example below shows how to invoke Cscript, preventing it from showing the Microsoft banner and passing three parameters called One, Two, and Three: cscript //nologo first.js One Two Three --------------------------------------- First Sample WSH Script Version 1.0 Copyright 1998 Robelle Consulting Ltd. One Two Three Summary With Windows Scripting Host, Microsoft has provided a new set of powerful scripting features for the MS Windows platform. Both JScript and VBScript offer powerful programming features, and the ability of these scripts to control objects makes them very useful. For example, Robelle has been using JScript to automate a number of processes. In our next issue, we'll discuss creating an Excel spreadsheet. [David Greer] Windows of the World Will Unite =============================== Starting in 1999, all versions of Windows will share the same name. Windows 2000 is Microsoft's new name for all upcoming operating systems currently known as Windows 98, Windows NT Workstation, and Windows NT Server. Windows NT 5.0 will now be called Windows 2000, and will start appearing in 1999. There will be one desktop version, called Windows 2000 Professional, and three server versions of Windows 2000. Server versions will support different numbers of processors and clustering. Price options for new versions may be closer to each other than the current pricing of NT Server's standard and enterprise editions, which can differ by a factor of ten. Eventually, a 64-bit version of the O/S will offer increased performance over the 32-bit version. Windows 98 is the final consumer O/S with 16-bit components. A true 32-bit NT-based O/S will replace it in two to two and a half years, and will carry a 200x year designation. [Mike Shumko] Suprtool Tips ============= Find by Last Letter ------------------- Q: Our mail-order company wants to do a mailing to the young-and-hip generation with selection based on the first name (the perfect criteria). Is there a way to find all names that end in a certain letter? For example, all names that end in i (e.g., Nicki, Kerri, Jenni, Tori). A: Use Suprtool's pattern matching capabilities: >if firstname=="@i~" This tells Suprtool to look for any letters, followed by an i, followed only by zero or more blanks. Search for Binary Data Using ASCII Criteria ------------------------------------------- Q: The field in the dataset is in I2 binary integer format, but the external flat file (myfile) with the search values is in ASCII: 123456789 88772 012345 A: Convert the file of ASCII values to binary. >input myfile >define disp-num,1,9,display >define i2-num,1,4,integer >extract i2-num = disp-num >output file2 >xeq Then search the dataset using the binary values. >get my-dset >table tab,my-keyfield,file,file2 >if $lookup( tab,my-keyfield ) >output result >xeq [Dave Lo] Part 2 of Get vs. Chain ======================= In the last issue of this newsletter we discussed how you can determine which Suprtool command, Get or Chain, would be more efficient at reading records with particular key values in a detail dataset. In this article we discuss how to automate the Get vs. Chain choice. Remember that the goal is to find the point at which Get and Chain take the same amount of I/O. The key ingredients in the calculation are: the number of I/Os Suprtool uses to read the entire dataset the average number of records in each chain Number of Suprtool I/Os It is possible to figure out the first number theoretically, but it is far easier to have Suprtool tell us how many I/Os it actually uses. This piece of a job stream can make the necessary calculation: !purge outfile,temp !run suprtool.pub.robelle>outfile set statistics on set progress 0 base mybase get d-notes output $null exit ! !run qedit.pub.robelle text outfile delete "FREAD"(nomatch) change 1/30 "setvar d_notes_suprtool_fread_count " keep outfile1 exit It runs Suprtool, redirecting its $stdlist to a file that we post-process with Qedit (any text editor will do, even POSIX text-processing tools). The result is a command file, outfile1, which contains a Setvar command that sets a variable with the number of I/Os. setvar d_notes_suprtool_fread_count 293 Average Number of Records per Chain HowMessy, a Bonus program that comes free with Suprtool, can tell you the average chain length of a dataset. HowMessy reports this information in two ways: it prints a report, and it writes a self-describing file with the data. The following piece of a job stream shows how to analyze the self-describing file: !run howmessy.pub.robelle;info="p" trial d-notes {blank line = no more datasets} {blank line = no more databases} ! !run suprtool.pub.robelle input loadfile if dataset = "D-NOTES" define integer,1,2,integer extract "setvar d_notes_ios_per_chain " extract integer = avechain extract " + 1" output outfile2,ascii exit The result is another command file, outfile2, which contains a Setvar command that sets a variable with the average number of I/Os needed to read a chain: setvar d_notes_ios_per_chain 42 + 1 The assumption for reading detail datasets by chain is that every record takes one I/O for each DBGET, plus each key value in the chain needs one I/O for every DBFIND. Therefore the number of I/Os is the number of records plus one. Calculate the Break-Even Point With the results of the two prior steps, you can figure out the break-even point at which Get and Chain take about the same amount of I/O. This value is expressed as a number of chains. !outfile1 !outfile2 !setvar d_notes_break_even d_notes_suprtool_fread_count / & ! d_notes_ios_per_chain Don't Recalculate Every Time! The goal of this exercise is for your job streams to work at top efficiency. It would be terribly inefficient to recalculate the break-even point every time you need it. We suggest that you create the command files only once a week, or as often as you normally run HowMessy. Save the final command file with a name that matches the name of the dataset (e.g., dnotes). !echo setvar d_notes_break_even !d_notes_break_even > dnotes !save dnotes Then invoke the following one-line command file as needed: !dnotes ! !setvar number_of_chains,finfo("values",19) ! !if number_of_chains > d_notes_break_even then ! ! {run suprtool with a Get command} ! !else ! ! {run suprtool with a Chain command} ! !endif [Mike Shumko] Can't Run Your Bonus Programs? ============================== We get regular support calls asking: "Qedit or Suprtool is running fine, but HowMessy doesn't want to run because it says it has expired. What's up?" What's up is that you probably didn't quite finish the installation instructions. Robelle distributes update tapes for MPE products with all the necessary files for a full installation of the primary product (e.g., Suprtool), the Bonus programs (e.g., HowMessy), and the QLIB programs (e.g., Prose). But the files have "safe" file names, so that by restoring the files you don't immediately overwrite the production version of the software. Suprtool is on the tape as SuprCM and SuprNM, HowMessy is there as MessyCM and MessyNM, etc. Streaming the installation job copies your current version into the PubOld group and renames the new version (xxCM or xxNM as appropriate) into the Pub group. But there are separate job streams for Suprtool, Qedit and the Bonus programs: Install.Suprjob.Robelle installs Suprtool, Install.Qeditjob.Robelle installs Qedit, and Bonus.Job.Robelle installs the Bonus programs. So if your version of HowMessy (or Spell, Select, Compare or Xpedit) has expired, but your primary products have not, chances are all you need to do is stream Bonus.Job.Robelle. [Hans Hendriks]