VESOFT 13 Help Subsystem

Inside VESOFT #13 (Help system and other stuff)
by
Shawn Gordon

Last month I had a slam on the help system in the VESOFT product line, but this month I want to talk about its strengths, and a number of issues that people probably don’t even know are there.

At its most basic you say “HELP keyword”, this acts as a partial key search based on the keywords that have been indexed, so if I say something like “HELP COPY” you will get a list of topics that match your request, here is a partial list as an example:

1. VESOFTDEFAULTCOPY, MPEX variable
2. Security: %COPY
3. %COPY, MPEX command
4. KEEPATTR, %COPY keyword
5. %COPY using %ALTFILE keywords
6. KEYFILE, %COPY keyword
7. DEV, %COPY keyword
8. BUFFERSIZE, %COPY keyword
9. KEEPAMDATES, %COPY keyword

For some topics you will get a huge list to choose from, for example, the keyword “FILE” is probably a bad choice. You can reach the help facility for each of the sub products like Security and VEAUDIT by prefacing your help directive, so

%SEC HELP ADD
Or
%VEAUDIT HELP COPYACCT

Now way back when I worked at VESOFT, we had gotten a number of support calls asking for us to integrate the help facilities so that you could just issue the directive, and it would be found. We ended up hacking something together that was later streamlined and made an official part of the product, so how I could type:

%help copygroup

Linking to VEAUDIT HELP…

And you can see it indicate going to the other help facility. What happened next was the the MPE help facility was also linked in, and this was great because you had much better indexing than is provided by the standard interface to MPE Help. So now if you entered a command it would search the VESOFT products, then look in the MPE help facility. You can control it by using the %MPE HELP [command] syntax, just like with the other products. You can also say %HELP :command, the colon also tells MPEX to look at the MPE help.

As I mentioned in an older column, the POSIX help system can also be linked into the engine, this is really handy and fun, especially the way the help system seems to know what to display. For example, if I say:

%HELP CP

I will get the following:

  1. Link to POSIX's man cp(1)  copy files
  2. Link to MPE's :HELP COPY
  3. Link to POSIX's man cpio(1)  archiver to copy and back up files
  4. Link to POSIX's man cpio(2)  format of cpio archives
  5. CPULIMIT, job/session attribute variable

The reason this is interesting is because the posix “cp” command, is the COPY command, and you can see how item 2 knew enough about the type of command to also bring this up as a topic. You can’t force a search of the posix help library with “%POSIX HELP [command]” however, since it isn’t officially supported, but you can say HELP POSIX and get the posix help library directly.

A very handy feature has been in MPEX for many years, but many people didn’t know they were there. The first was the function ABORTMPEF, and is still there, but no longer documented and supported. Essentially it took an FSERROR and CIERROR as parameters and would display the catalog message. This got replaced by the more generic function:

WRITEMPEMESSAGE (I1, I2)

		Outputs the MPE error message I2 in message set I1.  
		CIERRs are in message set 2, FSERRs are in message set 8.  
		E.g.  WRITEMPEMESSAGE(2,980)
                        writes "COMMAND GREATER THAN 278 CHARACTERS LONG.
                        (CIERR 980)" to your terminal;
                        WRITEMPEMESSAGE(8,52) would write "NONEXISTENT
                         PERMANENT FILE  (FSERR 52)".

The problem I had with this was that you had to know the message set number, and they tell you two of them in the help that are the most common, but it’s easy to forget. Eventually some direct interface that was easy to understand was added, consider the following:

          %HELP CIERR number             Displays CI error messages     
          %HELP FSERR number             Displays FILE SYSTEM messages  
          %HELP LOADERR number           Displays LOADER error messages 

This is going to cover your most common situations, and if they don’t, then you can always fall back on WRITEMPEMESSAGE.

Many people don’t take proper advantage of the help system. I see questions all the time that if people had just spent a few moments in asking the questions in the help system, they would have solved their problem much quicker. I hope this was helpful for you, and keep those questions and suggestions coming.