Description of RACHELP

Download count: 13 this month, 2051 altogether.
Downloads for RACHELP :
  VMARC archive: v-14K

RACHELP package

The z/VM product includes a comprehensive help system with help files for all of the components of z/VM -- except one!  The RACF component includes help, but most of it is not part of the CMS help system.  You get help for RACF commands by issuing RAC HELP command, which displays the help information on your terminal in line mode and writes it to file RACF COMMAND A (just the same as the RAC EXEC does for any RACF command.)  This output is not very easy to read, scroll through, and search.  (Enter RAC HELP HELP on your system to find out more about how to use the standard RACF help facility.)

The text for the RACF help facility is stored in a CMS file named SYS1 HELP on the RACFVM 305 server code disk.  The RACHELP EXEC in this package reads that file and processes it to create individual CMS help files.  In addition, it creates RACF HELPMENU, RACF HELPTASK, and RACF HELPABBR files which provide menu and task help for RACF commands and allows you to look up commands by their abbreviations.  There is no help text from the RACF product included in this package (nothing copyrighted has been copied.)  All the exec does is read the existing RACF help that is already on your system and reformats it to create files in CMS help format.  The existing RACF help facility is not changed in any way.

Here is the syntax of the exec. All arguments are optional. 

>>-RACHELP-.--------------------------.-.--------------.--------------------><
           |             .-A--------. | '-(-.--------.-'
           '-.-A-------.-+----------+-'     '-SYSTEM-'
             '-outmode-' '-workmode-'
Where:

  • outmode is the file mode where the output files are placed.  The default is to use the A disk.

  • workmode is the filemode used for work space.  If it is not specified, the same filemode as the outmode is used.  The temporary files written on that filemode are automatically cleaned up unless there is an error.

  • SYSTEM is an option to also have the exec update the system disks.  See the notes below for more about this option.

If the file SYS1 HELP is found on an accessed filemode, it is used to extract the help files.  Otherwise, the exec will link to RACFVM 305 in read mode to read SYS1 HELP.

Some notes about the help files created by the exec:

  1. If you apply service to RACF or upgrade to a new z/VM release, the exec must be run again to update the CMS help files.  IBM may change the format of the SYS1 HELP file so there is no assurance that the current exec will produce correct help files in the future without modifications.  However, the exec has been tested on several z/VM releases.

  2. The help files for most z/VM components are stored on the help disk, which is MAINT 19D.  This disk is automatically accessed by the CMS help command.  However, help files can be stored on any accessed disk and the HELP command will find them using the normal CMS search order.

  3. The RACF component of z/VM already includes 3 CMS help files that are placed on the Y disk (MAINT 19E) and 3 additional files on the RACF code disk as part of the standard install.  These are RACF HELPMENU, RACFLIST HELPRACF, and RACFPERM HELPRACF on the Y disk and RACFADU HELPRACF, RACFDBU HELPRACF, and RACFSVRS HELPRACF on the RACF disk.  This exec creates an updated RACF HELPMENU file that references all of the RACF help files that it finds.  However, it conflicts with the same file installed on the Y disk.  Therefore, the RACF HELPMENU file on the Y disk should be erased or renamed so that the HELPMENU file created by this exec is used instead.  The SYSTEM option of this exec automatically renames the RACF HELPMENU Y file to hide it so that the menu file on the help disk is used.

  4. RACF can control permissions to Shared File System (SFS) resources, but most systems that use RACF do not use this function.  Help text for these functions are included in the RACF help.  The exec creates all the help files for the SFS specific commands also.  However, since they are not used as often, the exec creates separate menu and task help files named RACFSFS for the SFS only RACF commands.  These separate files are referenced in the main menu and task files. 

  5. The SYSTEM option automatically copies the new help files to the standard help disk (MAINT 19D.)  It also copies the 3 help files from the RACF code disk to the help disk.  It will also update the Y disk (MAINT 19E) if the RACF HELPMENU file needs to be hidden on that disk.  If the Y disk is updated, you will want to re-save CMS.  Here are the steps performed by the exec when the SYSTEM option is specified:

    • Extract all the help members on the work disk and create the help files.  If this step fails, the exec quits and no system disks are updated.

    • Link the help disk in write mode and use VMFCOPY to copy the help files to that disk.  VMFCOPY is used so the inventory file is updated with the correct component name.

    • If additional help files were found on the RACF code disk, also copy those files to the help disk.

    • If RACF HELPMENU is visible on the Y disk (it has filemode Y2), then link the Y disk in write mode and rename that file to filemode Y1.  This will hide the file from the normal CMS access of the Y disk which only shows filemode Y2 files.  The file is still on the disk so that the service process will not fail.

    • If all steps worked successfully, clean up all of the work files and release any read/write links and accesses to the help and Y disks.

  6. If you have an SSI cluster of systems, remember that this exec must be run on each member of the cluster, because each member has its own help disk and Y disk.

As of z/VM 6.3, the work disk requires at least 600 4K blocks (4 cyl 3390) and the output disk requires at least 350 4K blocks (2 cyl 3390). If the output disk is used as the work disk, 5 cyl of 3390 space is needed.

Feedback: Bruce Hayden IBM Washington Systems Center

Versions:

  • 1.3.1 - Include IBM copyright statement in file (avoids help error)
  • 1.3.0 - Create HELPABBR file, require uplevel (6.4) pipelines
  • 1.2.9 - Create separate menu and task file for SFS commands
  • 1.2.8 - Improve clean up and debug output
  • 1.2.7 - Also include all included help files in the menu
  • 1.2.6 - Original download version