What's Up, DOCumentation? 1998 # 6
December 1998
From:
- Robert M. Green, President
- David J. Greer, Vice 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
- 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
- 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 the $stddate Web page.
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 on the Robelle Y2K Web page.
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.
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 <dataset> OF <database>
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.
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.
[Paul Gobes]
Editor's note: You can get on-line information about all your favorite Robellians in the updated company brochure.
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.
[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. 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 Solutions Technology Inc. 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 Solutions Technology Inc.");
} /* 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 Solutions Technology Inc.");
} /* 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 Solutions Technology Inc.
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 Solutions Technology Inc.
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 was 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]