How to Read a Manual

How to Read a Manual

By Alfredo Rego
Adager
Sun Valley, Idaho
March 1, 1982

What follows is Alfredo's answer to a question from the audience at a RUG meeting. The question was: "Do you have the IMAGE hashing algorithm?" Alfredo detected the question behind the question and made this reply.

You should read manuals like you read love letters.

In a love letter, everything counts. You read between the lines, above the lines, below the lines, and in the margins. You read between the individual letters (is that "i" dotted in an angry way?) You wonder what significance the stamp has. You smell the envelope for any special fragrance. You study the salutation (why "dearest" and not "darling" this time?)

You even try to take the sheets of paper apart!

In a manual, everything counts as well. Your heart may not pound as strongly when you read a manual. But you will certainly have more time for love if you do not have to spend endless hours at the computer doing things that you would not have to do at all had you read the manual lovingly to begin with!

A sample from the IMAGE/3000 manual will warm up you heart:

The manual mentions that DBGET "provides eight different methods for reading the data items of a specified entry". It then specifies these reading methods according to the Mode parameter. Everybody seems to register the first seven modes and everybody seems to ignore the eighth mode, whose action the manual casually describes thus:

"Read the entry occupying the primary address of a synonym chain using the search item value specified in ARGUMENT to locate the entry. If the entry is not a primary entry in a master data set specified by DSET, it is not read."

This apparently innocent paragraph actually says a lot! For instance, it says that you can use a Read-Before-Write approach that can help you minimize the load time of a master data set.

Specifically, if you have to load a large quantity of entries to a master data set, you can do a DBGET mode 8 on the search-item value corresponding to the entry you are about to DBPUT.

If DBGET returns a No Entry error code, then you know that the entry will be a primary entry and will never have to be migrated; therefore, you can do its DBPUT with a clear sense of righteousness.

If, however, DBGET returns a code that means that it found an entry in the spot where your proposed entry belongs, then you know that it would become a secondary somewhere and -- even worse -- you know that it would become a candidate for migration if some primary later on happens to belong in the temporary spot "lent" to it.

With this knowledge, you are then free to choose not to DBPUT this entry on this pass but wait until you have loaded all the primaries. You can then do a second pass loading all the secondaries -- none of which will migrate at all!

The savings in time can be measured in the order of days. Well worth your while during your manual-reading, even though it was not your personfriend who wrote it.

Alfredo Rego