Chapter 1. Better use of CMS HELP

Why this topic ?

You probably don't have the reference manuals handy all the time, unless you have a CD-Rom installed on your Personal Workstation and the VM Collection CD loaded.

Even if you had all the books, walking to your library and looking up a command in the proper manual, can cost you more than just asking CMS for help. CMS indeed provides you all information through the online help. We think that the HELP command is not understood completely and therefore not used enough, so, that's why we expand on it here.

What is HELP ?

HELP is a CMS command. It shows information about commands at your terminal. It contains also details about error messages, and even CMS Macros for Assembler or CSL routines, just as you can find it in the manuals.

A first thing you should know about HELP is that it uses xedit to display the help. This makes that you can use all the possibilities of XEDIT to work with the displayed data, whereby searching is probably the most useful here.

HELP does not allow you to enter all XEDIT commands on the command line. It uses a REXX procedure to control the help process and wants to protect the environment it so created. The LOCATE command, however, is one of the permitted XEDIT subcommands in this environment.

Now, if you remember that LOCATE normally takes search criteria as parameters, but also allows the search arguments to be followed by another XEDIT command, then, it becomes possible to execute any editor command from the command line.

Let's practice it via a (less useful) example :

   issue   HELP XEDIT LOCATE (ALL
   issue   SET COLOR FILEAREA YELLOW        (forbidden by the HELP EXEC)
   issue   L +0 SET COLOR FILEAREA YELLOW   (this works !)

The last command uses LOCATE with a target +zero - meaning advance zero lines, hence don't move at all - followed by the SET COLOR subcommand. You can even reduce the command to

    0 [SET] COLOR FILEAREA YELLOW

And, while you are viewing the help information for XEDIT's LOCATE command, it's an excellent occasion to read it completely so that you'll be able to answer the questions below. We bet that 90% of you don't know all possibilities of this powerful XEDIT subcommand. The help for LOCATE also explains the concept of targets which you can use in many XEDIT commands.

Which of the following targets give the stated result ?

+10	Advance 10 lines in the file (downwards to end of file)
10	Advance 10 lines in the file
:10	Go to the 10th record of the file
/do/	Search for the next occurrence of string do
-/do/	Search for the previous occurrence of string do
*-3	Go to the last but 3rd line of the file
¬/do/	Search for the first record not containing the string do
/ do /	Search for the first occurrence of the word do surrounded by spaces (hence not at the beginning of a record)
/do/ & ¬/i=/	Search for the first record containing string do but not string i=
/do/ \| /if/	Search for the first record containing either the string do or the string if
.do	Go to the record named .do
.do 3	Go to the 3rd record following the record named (pointed to by) .do

As EXECIO and PIPE behave similarly, we take the occasion to highlight the main difference between the FIND and the LOCATE subcommand. FIND limits its search to the beginning of the zone (defaults to whole record), while LOCATE searches for occurrences anywhere in the specified zone. FIND is for example, most useful to search for a label in a program.

Who provides help files ?

Files that can be displayed by the CMS HELP command are provided by :

VM itself of course. You get help files for all commands (CMS, CP, XEDIT, REXX statements and functions, Assembler macros, CSL routines, CMS Pipelines, etc.).
Some program products implement their own help facility (e.g. SQL/DS, RACF/VM), but more and more products give help through the CMS HELP command. Examples are RSCS and DIRMAINT.

What can you find in the online HELP files ?

For the VM product, the help is very complete : each command is described in exactly the same wordings as in the corresponding reference manual.

Even stronger, if a PTF (Program Temporary Fix, a correction provided by the lab) changes a command, the help file is immediately updated too, while the manual gets only updated with the next edition (next VM release). Hence, the online help information is normally more up-to-date than the paper or CD-Rom version.

Each help file can be structured (like the structure you have in the manuals). The paragraphs making up this structure are:

BRIef	(optional) short description and example
DESCript	where the command can be used for
FORMat	format of the command and its parameters and options
PARMs	description of the command parameters
OPTIons	description of the command options
NOTEs	usage notes, can be very enlightening
ERROrs	list of return codes and error messages
RELated	(optional) list of related commands

The names of the paragraphs as listed above are in fact options that you can specify when invoking the HELP command. That is, if you want to look immediately at the parameters for the Listfile command, then you'd issue:

   HELP [CMS] LISTFILE (PARMS

By default, the BRIEF paragraph is displayed (if available in the file), otherwise the complete file is displayed. Nevertheless, this default can be changed by the user, so...

Now find out how to change the default for HELP from BRIEF to DETAIL (we do recommend this setting as the BRIEF help is often too short to find what you're looking for). The underlying question is where your default settings are saved ?

Note: if you find where your defaults are stored, don't change them via XEDIT, unless you want to have trouble later !

We hope that previous question has also let you discover why the peek command only shows you the first 200 records of a file, unless you already had changed this default...

HELP structure.

Homonym commands can be found for different environments. For example, both CP and CMS have a start command. There is thus a need to classify the help files into environments. The consequence is that you have to be explicit in your query for help in many occasions. You have to indicate the environment for which you want help. For example, parse belongs to REXX, so, you should use :

    HELP  REXX   PARSE

The general format for the HELP command is :

    HELP  environment  command

On the other hand, there are special environments :

    Help  envir  MENU      shows a menu of all the commands for the
                           specified environment
    Help  envir  TASK      shows guidance to find a command specific
                           to the environment
    Help  MENUS            shows all menus (good when desperate)
    Help  TASKS            Default: shows all first level tasks
    Help  [MSG]  msgid     shows help about message msgid

The msgid is based on VM's message format:

   cccmmmnnnt    e.g.  "DMSXDC546E Target not found"

   where : ccc   is the component or environment (e.g. DMS for CMS)
           mmm   is the abbreviated module name
           nnn   is the message number (3 or 4 digits)
           t     is the message type (e.g. W is warning).

When asking for help you can omit the mmm part. For example,

   Help DMS546E
   Help DMSXDC546E and
   HELP DMSfdr546E

are equivalent queries. HELP just drops characters 4 to 6 if they are not numeric.

Note also that different commands can produce the same message number (but the mmm part will be different to indicate the origin of the message). This is for example the case for most messages indicating DMSmmm002E File not found. Type will produce DMSOPN002E, while rename will display DMSRDN002E when a file is not found. The mmm characters may sometimes be useful, for example when communicating a problem to the support center so that they know which command exactly did produce the message.

The grouping in environments creates a new problem when looking for help : What is the environment for command XYZ ? To illustrate this problem, try to get help for the xautolog or the filepool command.

We'll provide the solutions to this problem later, as for this we need to understand the help file naming conventions first. This is as follows:

  envir   HELPMENU     menu of all commands for environment envir
  xxxx    HELPTASK     help per activity
  command HELPenvi     file for single command of environment envir
  msgid   HELPMSG      help for messages
  envir   HELPABBR     help for abbreviated commands.

The environments needed most by end-users are:

  XEDIT, PREFIX, QUERY, SET, REXX, CMS, CMSQUERY, CMSSET,
  CP, CPQUERY, CPSET, and maybe RSCS or other products.

Other, not so common environments, are:

  SFSASDIN, CPOTHER, ROUTINE, MACRO, ....

The xautolog command, for example, is part of the cpother environment, as it is a class A CP command, only used and allowed by authorized users, such as the system operator.

Remarks:

The environments SET and QUERY the corresponding XEDIT subcommands as XEDIT was the first environment to provide the online help, and so reserved four environments for its own use, namely XEDIT, SET, QUERY and PREFIX.
When asking for help from within an XEDIT session, HELP first searches for XEDIT subcommands. So, if you want to be sure to search for help for a CMS command, even if you are in XEDIT, be sure to issue
```
     CMS HELP command
  or HELP CMS command
```
The first form directs XEDIT to pass the command to CMS, while the second form signals to HELP that you want to work with the CMS environment. Can you imagine what would happen if you would issue CP HELP QUERY from the XEDIT command line ?

Where are the HELP files stored ?

In addition to the standard CMS search order (more on this in chapter 4), the HELP command also looks on your 19D minidisk (this is normally a minidisk owned by MAINT). This means that all help files do not need to be placed on MAINT's 19D, some can be on any other accessed disk.

What's important to understand here is that the HELP module uses a special search method to find a file on the 19D disk (it will find files that you don't see with FILELIST or LISTFILE). If you want to see all the files on the 19D disk, you may have to issue the access 19D mode command explicitly.

As we want to learn you more about VM, and not just REXX, let's explain what's the trick used by HELP.

CMS allows to place the directory or, to use the correct term, the File Status Table of a minidisk in a shared segment. This directory contains more or less the same information you see with the Filelist command, plus the pointers to where the files reside on the disk. This directory can be saved in a shared segment by the systems administrator via the savefd command (or implicitly via the seggen utility).

Every time something is changed on the disk, the system administrator has to re-save the shared segment. You should know that ACCESSing the disk in R/W mode and RELEASEing the disk is enough to rewrite the disk directory with a new date- and time-stamp so that the content is considered different from the shared segment, and thus it must be re-saved.

Using a shared segment has 2 benefits : the storage for the directory is shared by all users accessing this mini-disk (less paging), and response-time of the ACCESS command is shorter (CMS has not to do I/O to read the directory). (footnote) If you issue the Query segment command, you will see the list of shared segments your virtual machine currently has access to (note that not all are for mini-disk directories).

3	Is there a segment for the 19D disk on our system ? What is its name ?

4	Is it active just after you IPL CMS ?

If you ACCESS a disk in R/O, ACCESS will test if a shared segment for the directory of that disk exists, and, if it is not out-dated, load and use it. Else, ACCESS will read the directory from the minidisk and store it in the user's private virtual storage. Remark also (for the people among you that are responsible for a system, that the ACCESS command will not warn you when the segment is out-dated...).

Hint: if you are a systems administrator, you could include the command ACCESS 19D Z/Z (SAVEONLY in MAINT's profile and test the return code. If it is not zero, it means the shared segment is not available or out-dated.

HELP knows this, but also tries not to use too much private storage. So,

when the shared segment exists and is valid, HELP will use it, and so all HELP files are visible to FILELIST, XEDIT, etc. This gives you the optimum performance.
else, HELP will issue the command access 19D fm/fm * * fm2. This means that only files with a filemode digit equal to 2 will be accessed, while other files will thus remain 'invisible' to the normal user.

In general, filemode 2 help files are the menu and task files. To read the invisible files, HELP uses non-standard CMS interfaces.