What's Up, DOCumentation? 1999 # 6

December 1999

From:

• Robert M. Green, President
• David J. Greer, Vice President
• Ken Robertson, Editor pro tem

To: Users of Robelle Software

Re: News of the HP 3000 and of HP-UX, 1999 #6

What You Will Find in This News Memo:

• Join David Greer and Ron Seybold in a Live Chat on 3kworld.com
• Qedit for Windows Scripting Language is Released
• Robelle Year-End Support Hours
• 3kworld: This Dot Com Is for You
• Qedit Scripting Language
• Suprtool Is Ready for MPE/iX 6.5 Large Files
• A Look at HP 3000 Time Zones, the TZ Variable, and HP's Clocks
• Staff Spotlight: Paul Gobes
• Off-Site Suprtool Training
• Robelle Products: Problems, Solutions, and Suggestions
• Suprtool: UNIX Script Tip Updated
• Suprtool: Y2K Quick Fix
• Suprtool: Y2K Documentation Errata
• Suprtool and Qedit: Working with Non-Printing and Extended Characters
• Qedit: A Setting for QCTerm Users
• Gotchas for MPE Fingers
• Disaster Recovery Planning
• Ken's Y2K Workaround
• Contributors to This Issue

Join David Greer and Ron Seybold in a Live Chat on 3kworld.com

The December net event at 3kworld.com features David Greer, president of Robelle, in an on-line interactive discussion with the HP 3000 community, hosted by Ron Seybold of The 3000 NewsWire. On December 7 at 11:00 a.m. PST / 2:00 p.m. EST, David will be answering your questions on development tools and techniques and new resources for customized programming solutions. This is a great opportunity to ask questions and get advice from Robelle's senior software architect. Go to http://www.3kworld.com/ to join the discussion.

If you miss the event, a transcript of the chat will be posted on 3kworld in the "Net Events" section.

[Nicky Gunther]

---

 Qedit for Windows Scripting Language is Released

With Qedit Scripting Language (QSL) you can customize Qedit to meet the specific needs of your end-users, adding your own features to Qedit, and automating the processing of local and host text files from within Windows.

QSL is an easy-to-learn, full-featured, object-oriented language. You can write scripts yourself from scratch, or you can start with scripts from Robelle's script libraries. Scripts can be loaded automatically and even executed automatically when Qedit is run. Scripts are available to end-users via flexible drop-down menus.

Qedit for Windows with Scripting will be available for general distribution in version 4.8.04, but if you are eager to get started, you can get a copy right now by calling Robelle technical support.

[Ken Robertson]

Robelle Year-End Support Hours

People have been asking us if we are increasing our support staff and hours of operation over the year-end. Knowing that you will already have a lot of things to think about at year-end, we want to assure you that Robelle will be available to help you if you need us.

We have identified the potential busy time as being the last week of December through to mid-January. Robelle technical support people and people in the other departments will be on call during these peak days.

If you phone us on weekends or on the Canadian statutory holidays of Monday, December 27, Tuesday, December 28, or Monday, January 3, you can get Y2K support by telling the answering service operator that it is an emergency.

As always, you may contact us by telephone or fax, or by e-mail at support@robelle.com. We recommend that you periodically visit us on the Web at http://www.robelle.com/year2000 for the latest information on the Year 2000 readiness of our products and services.

[Kerry Lathwell]

3kworld: This Dot Com Is for You

If you haven't heard yet, there is a new web site serving the HP 3000 community at http://www.3kworld.com/. As one of the founding sponsors of 3kworld.com, Robelle sees this innovative forum as a cornerstone in leveraging the HP 3000 forward into the next century.

3kworld.com is an on-line virtual community providing a single point of contact to collect and deliver news, information, products and services tailored specifically to the needs and interests of HP 3000 users. Client Systems, the sole distributor of the HP 3000 in North America, developed 3kworld.com. As a member (a "Colleague" in 3kworld-speak), you gain access to a variety of interactive services:

• Keep up to date with the latest press releases, white papers, case studies and articles posted in the 3kworld.com Newsroom.
• Learn about the latest events, training classes, conferences and seminars from HP 3000 suppliers in the Event Center.
• Learn from the expertise of your peers by posting questions to 3kworld Message Boards and Chat Rooms.
• Shop for HP 3000 hardware, software, and services in a convenient and secure e-Store.
• Participate in on-line surveys which compile data about hot topics in the community.
• Take advantage of job postings focused on your area of expertise.
• Communicate directly with leading experts interviewed in 3kworld chat events.

Membership in 3kworld is free. 3kworld Colleagues include systems operators/administrators, programmers, CIO's, IS managers, technical support employees, consultants, and end users. To join as a Colleague, go to http://www.3kworld.com/ and click on "Join 3kworld.com".

[Nicky Gunther]

 Qedit Scripting Language

Qedit for Windows now has a scripting language of its own. We call it Qedit Scripting Language, or QSL for short. QSL allows you to add functionality to Qedit for Windows, automate edit tasks, and a lot more.

Here is a short sample script that allows Cobol programmers to easily insert their name on the "Author." line of a Cobol program.

    NAME "Insert Cobol &Author";

    currentfile = qedit.activefile;

    findresult = currentfile.FIND(pattern: "~author.~",
                                  ignorecase: true,
                                  entirefile: true,
                                  leftcolumn: 1,
                                  rightcolumn: 66);
    if findresult then
       WRITELOG("Author. is at " + currentfile.selection);
       foundstring = {};
       foundstring.line = currentfile.SELECTION.start.line;
       foundstring.column = currentfile.SELECTION.end.column
                            + 1;
       currentfile.INSERT(at: foundstring,
                          text: " Francois Desrochers.");
    else
       result = DIALOG('"Author." was not found in the file.');
    endif

Although the script is short, with only twelve QSL statements, it shows a number of nice QSL features. We will briefly go over the main features, using object-oriented terminology to describe some of the underlying QSL concepts and design. We will not explain them in detail at this point because these are covered in the QSL documentation.

The NAME statement assigns a name to the script. This looks innocent enough but it actually hides a very useful feature. Once this script is loaded in the Qedit scripting environment, the script name becomes a new command name under the Script menu. This means that you will be able to execute the script simply by selecting it from the menu. This script adds only one command to the menu, but it's very easy to add submenus with any number of commands. Notice that the name contains an ampersand. This special character identifies the shortcut for this command. The character that immediately follows the ampersand, in this case "A", can then be combined with an ALT-key sequence to execute the script. In this example, you could type ALT+S (access the Script menu) +A (execute the script).

QSL is an object-oriented language with methods and properties. "Currentfile" is a file object assigned to the document you are currently working on. From that point, we edit the file using methods (FIND, INSERT), and look at attributes of the file using properties (SELECTION).

The script first searches for a line that contains only the string "Author." surrounded by spaces. This ensures that the script does not modify a comment line or a line where the author has already been filled in. Of course, this assumes that the author name is not on a separate line. To do all this, we specify a number of search options when calling the FIND document method. We use a pattern match instead of a simple string. We do a caseless search, and we search the entire file to make sure the search starts from the beginning. We also specify a column window so that Qedit does not look at the Cobol tags, if there are any.

If a string matches that definition, the script captures its location and inserts the author's name (in this case, "Francois Desrochers") immediately after it, by calling the INSERT document method.

The script uses two built-in functions to provide feedback to the user. WRITELOG sends a short message with the string coordinates to the Script Control Panel. By default, the panel is invisible. The information is written anyway, just in case the script does not seem to behave correctly. If the operation is successful, it's going to be pretty obvious because the cursor on the document window will be at that location. We also use the DIALOG built-in function to display a message window in case Qedit can not find the string. These two functions are very useful for debugging scripts and providing feedback to users.

This is a very simple script that barely scratches the surface of what QSL can do. We have shipped Qedit for Windows with Scripting to beta testers. If you are interested in being one of the first to discover the power of QSL, please contact us.

[François Desrochers]

 Suprtool Is Ready for MPE/iX 6.5 Large Files

The Suprtool development team spent part of the month of November at Hewlett-Packard, testing large file support in MPE/iX 6.5. We spent much of the time ensuring that new prefetch logic worked properly with these new huge files.

We also tested sorting and linking of files in the 20-gigabyte range, and extracting more than 4 gigabytes from Jumbo Datasets and sorting into a single file.

Robelle would like to thank Craig Fairchild, MPE File System Architect, for his help during our visit to HP CSY. Also thanks to Winston Prather, Karin Mule, and Kevin Cooper.

Please call for the latest Suprtool pre-release to test on MPE/iX 6.5.

[Neil Armstrong]

A Look at HP 3000 Time Zones, the TZ Variable, and HP's Clocks

Editor's note: there is a follow-up and correction to this story in the next issue of What's Up Doc.

During September, the following message was posted on the Robelle-L discussion list:

I've started to do a little Y2K testing with Qedit for Windows, and I discovered something a little odd: when I call up a directory from my client, the last modified date is correct, but the last modified time is 3 hours earlier than is reported by the operating system.

Timestamps are a common area of confusion for HP 3000 users, because it is really difficult to find this documented clearly anywhere. Here are the facts:

1. The HP 3000's hardware clock can be set only from the ISL CLKUTIL utility at boot time.
2. The system (software) clock is initialized from the hardware clock at boot time. It decides what the current time is, based on the value of the Time Zone setting:

       :showclock
   
       SYSTEM TIME: FRI, NOV 19, 1999,  2:32:41 PM
       CURRENT TIME CORRECTION:            0 SECONDS
       TIME ZONE:    8 HOURS  0 MINUTES WESTERN HEMISPHERE
   

   So changing to and from daylight savings involves only changing the Time Zone setting. Here is a sample from one of our jobstreams that runs daily:

       !IF HPMONTH = 10 AND HPDATE > 24 THEN
       !    ECHO We are going back to Standard Time
       !    SETCLOCK TIMEZONE = W8:00
       !ENDIF
       !IF HPMONTH = 4 AND HPDATE < 8 THEN
       !    ECHO Setting clock for Daylight Savings Time
       !    SETCLOCK TIMEZONE = W7:00
       !
       !ENDIF
   

3. Programmatic calls for system time are also based on the system (software) clock, but they use the TZ variable value to calculate current time, rather than the SHOWCLOCK TIMEZONE setting. You can use the SHOWCLKS utility to show you the different values:

       :SHOWCLKS.PUBXL.TELESUP
       SHOWCLKS/XL  A.10.00
       DEBUG/iX C.16.01
   
       HPDEBUG Intrinsic at: b1d.00007258 PROGRAM+$198
       PRIV=$3 := $0
   
       ********************************************************
       ***  Greenwich Mean Time : FRI, NOV 19, 1999, 10:45 PM
       ***  GMT/MPE offset      : -8:00:00
       ***  MPE System Time     : FRI, NOV 19, 1999,  2:45 PM
       ********************************************************
   
                  **** C Library Information ****
   
       Current value of Time Zone(TZ) variable : PST8PDT
       CTIME function return :  Fri Nov 19 14:45:24 1999
   

   The values in the box show what the system (software) clock has, while the last two lines show what the C Libraries return, based on the TZ variable's value.

   The TZ variable is used internally to lookup the current time offset on the TZTAB file, which takes account of daylight savings changes, thus this variable should not be changed with the TIMEZONE setting.

   It is generally set for sessions at logon time, via a UDC or command file. For programmatic logons (such as Qedit for Windows connections) no logon UDCs are executed, so it is imperative that the TZ variable be set in the applications (such as Qedit's QEDITMGR file), so that time calculations are performed correctly.

   So if the offset (TZ) used by the C Runtime Library was different from the TIMEZONE setting, this would explain why the wrong "file modified time" is shown in the Qedit for Windows directory listing, as the Qedit for Windows server relies on the C libraries to return this value.

   (Investigations into this also unearthed a bug in our server code that generates the file list, which is fixed in the latest version of the host.)

Confused yet? Let me summarize:

• SETCLOCK and SHOWCLOCK set and display the system software clock. The software clock is initialized from the hardware clock at boot time.
• Changes in Daylight Savings should be made only by changing the TIMEZONE value via SETCLOCK.
• The TZ variable must be set correctly for programmatic time calls to return the correct time.
• The TZ variable needn't be changed for Daylight Savings Time.
• The TZ variable must be set in the QEDITMGR file for Qedit for Windows to calculate the correct time.

[Hans Hendriks]

Staff Spotlight: Paul Gobes

Paul is our technical support manager and has been working the phones since he started with Robelle in 1991. He is well known to many of our customers who have attended user group meetings and Suprtool training sessions.

Paul is another of the 'foreigners' at Robelle. Born in Australia, Paul came to Canada with his parents in 1968. He attended Simon Fraser University near Vancouver where he excelled at non-academic activities. Paul started working in accounting, but in 1980 met his first HP 3000 and quickly changed to programming.

Outside the office Paul plays a mean game of volleyball, hikes with the Chilliwack Outdoor Club, and is an avid Vancouver Canucks hockey fan.

[Mike Shumko]

 Off-Site Suprtool Training

The next off-site training session for Suprtool will be in March 2000. Once again we will be hosted by Lund Performance Solutions in Albany, Oregon. Call Robelle or e-mail training@robelle.com for details.

Lund is holding System Performance Training around the same time. For more information call Lund Performance Solutions at 1-541-926-3800.

Robelle Products: Problems, Solutions, and Suggestions

 Suprtool: UNIX Script Tip Updated

In our last newsletter we suggested the need to prefix any Suprtool '$' function like $LOOKUP with a backslash to avoid having the script interpret it as a variable.

One of our customers, Randy Medd from Telamon, pointed out a more common, better approach:

    /opt/robelle/bin/suprtool << '!EOD'

Quoting the end-of-file tag ('!EOD'), has a secondary effect that prevents the shell from evaluating the contents of the here-is text.

Thanks, Randy!

 Suprtool: Y2K Quick Fix

It's December 1999 month-end, and you thought everything was Y2K-OK. Then an obscure but necessary job, which has worked for the last several years, suddenly fails with the following Suprtool commands:

    >item ship-date,date,yymmdd
    >if ship-date < $date(2000/01/31)
                          ^
    Error:  Cannot use a date beyond 1999 for this format

The ship-date field is not Y2K compliant because it does not have century information, and Suprtool will not continue processing this incorrect data when spanning centuries because the results would be incorrect (991231 as a number is not less than 000131).

The best solution is to make all your dates Y2K compliant by changing the data format to include the century. If that solution is not available, then Suprtool 4.2 can help you out. All you need to do is add the $Stddate function to the non-compliant date:

    >if $stddate(ship-date) < $date(2000/01/31)

The $Stddate function adds a century component for comparison purposes, so that internally the comparison becomes 19991231 < 20000131. $Stddate by default assumes that

• 00 to 09 means 2000 to 2009
• 10 to 99 means 1910 to 1999

You can change this "window" value by Set Date Cutoff nn.

Of course everyone has known about the Y2K issue for decades, and has had ample time to prepare. So none of this is really needed, right? :-)

[Dave Lo]

 Suprtool: Y2K Documentation Errata

Some parts of the Suprtool 4.x documentation contained an error in explaining how the Set Date Cutoff function worked. The correct explanation is:

"With Set Date Cutoff, Suprtool assumes the following: a century value of 20 if the two-digit year specified in the $Date or $Stddate functions is less than the value of Set Date Cutoff; and a century value of 19 if the two-digit year is greater than or equal to Set Date Cutoff." The incorrect portions of the printed manual and help files said "a value of 20 if the two-digit year ... is less than or equal to the value of Set Date Cutoff". If you have Suprtool code that is based on this incorrect information, you can simply adjust your Set Date Cutoff value to be one higher.

For example, Set Date Cutoff 10 will generate 2000-2009,1910-1999. If you had assumed that it would generate 2000-2010,1911-1999, you only need to change the setting to Set Date Cutoff 11.

[Dave Lo]

Suprtool and Qedit: Working with Non-Printing and Extended Characters

Of late, we have received a number of tech support calls asking how to edit or select non-printing characters (e.g., bell, CR, LF, null, escape). Both Qedit and Suprtool support non-printing characters, each in their own way.

    /set decimal on
    /change '27 "#" all  {change the escape chars to "#"}
    /set decimal off

    /list "Francois"
       21     Hello Francois,
    /set decimal on
    /change "c" '181
       21     Hello François,
    1 line changed

    >if firstchar = ^7

    >if firstchar = ^G

    >extract firstchar = ^27    {escape}

[Hans Hendriks]

 Qedit: A Setting for QCTerm Users

QCTerm is a free terminal emulator available from Wirt Atmar of AICS Research. You can get a copy of QCTerm from http://www.aics-research.com/emulate.html.

The emulator uses the telnet protocol to connect to the HP 3000 instead of the more common VT-MGR proprietary protocol. We recommend that QCTerm users add the following setting to their HP 3000 Qeditmgr file:

    set visual ignorelf on

This allows Qedit full-screen visual mode to work correctly in this telnet environment.

[Paul Gobes]

Gotchas for MPE Fingers

I now use Qedit for Windows for most of my editing. But occasionally I will find myself in Qedit full-screen mode in a HP 3000 Reflection terminal session, where my Windows-adapted fingers insist on trying to do things the Windows way. For example:

• trying to scroll using the Page Up and Page Down buttons on the keyboard instead of Qedit's F5 and F6 keys,
• trying to copy and paste using Ctrl-C and Ctrl-V, instead of using Reflection's Edit menu items or the right-click mouse menu,
• using Ctrl-Tab to switch to another file instead of using Qedit's Open * command, and
• the worst offender: using Ctrl-S to save my file instead of using Qedit's Keep command.

This last mistake is the worst because in Reflection the Ctrl-S key means to suspend all output from the HP 3000. This locks up the screen until I realize that I need to do a Ctrl-Q to resume the communications again.

[Mike Shumko]

Disaster Recovery Planning

We recommend adding the HP 3000 file Disaster.Pub.Robelle to your company's Disaster Recovery Plan. It explains how to get Robelle MPE-based products up and running on a recovery computer in the case of a major disaster hitting your site.

[Paul Gobes]

Ken's Y2K Workaround

Set your calendar to 1972. The months are the same and no one will notice. Just kidding. :-)

[Ken Robertson]

Contributors to This Issue

In alphabetic order:

• Neil Armstrong, Product Manager
• François Desrochers, Senior Programmer
• Paul Gobes, Technical Support Manager
• Nicky Gunther, Account Executive
• Hans Hendriks, Technical Support Engineer
• Kerry Lathwell, Senior Manager
• Dave Lo, Technical Support Engineer
• Ken Robertson, IT Manager
• Mike Shumko, Senior Manager