!=============================================================================!
!  DIVISION   I	:				     HELP MODULE DECLARATION  !
!=============================================================================!
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 01 :					 INITIAL VERSION      !
!      -----------------------------------------------------------------      !
!									      !
!      File Specification: ACCSRC_ACC:[HELP]SYMBOL_LIST.HLP		      !
!      Author		 : Marlys A. Nelson				      !
!      Initial version	 : 01.00.00 12-JUL-1985	VMS 4.1			      !
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 02 :				    MODIFICATION HISTORY      !
!      -----------------------------------------------------------------      !
!									      !
!									      !
!=============================================================================!
!  DIVISION  II	:				  HELP MODULE SPECIFICATIONS  !
!=============================================================================!
!									      !
!      Key 1 (Command name)............	SYMBOL_LIST			      !
!	 Key 2 ........................	Parameters			      !
!	 Key 2 ........................ Operation			      !
!	 Key 2 ........................ Errors				      !
!	   Key 3 ......................   CMPERR			      !
!	   Key 3 ......................   CONFLICT			      !
!	   Key 3 ......................   ERRACCFIL			      !
!	   Key 3 ......................	  IVKEYW			      !
!	   Key 3 ......................   LSTFILFMT			      !
!	   Key 3 ......................   NULFIL			      !
!	   Key 3 ......................   TOOMANY			      !
!	 Key 2 ........................ Examples			      !
!									      !
!=============================================================================!
!  DIVISION III	:					       SPECIAL NOTES  !
!=============================================================================!
!									      !
!									      !
!=============================================================================!
!
!
!=============================================================================!
! Key 1								  SYMBOL_LIST !
!=============================================================================!
!
1 SYMBOL_LIST
SYMBOL_LIST  provides  the  user  with a method of printing the values
associated with a set of symbols.

Format:

     SYMBOL_LIST name report-type [QUIET] [macro-lib] [MESSAGE_OBJECT]

This procedure is located in the ACC_USERCOM area.  You may call it by
entering the command:

     $ @ACC_USERCOM:SYMBOL_LIST ...

Optionally, you may wish to define a  symbol  to  invoke  SYMBOL_LIST,
such as:

     $ SYMBOL_LIST :== @ACC_USERCOM:SYMBOL_LIST
     $ SYMBOL_LIST ...
!
!=============================================================================!
! Key 2							           PARAMETERS !
!=============================================================================!
!
2 Parameters
name

  Specifies  the  name of the object containing the symbol definitions
  to be listed.  This object may be a symbol definition macro  located
  in  a macro library.  It may also be an object file generated by the
  MESSAGE compiler.

  Unless parameter MESSAGE_OBJECT is specified, name is assumed to  be
  the name of a symbol definition macro.

  When  listing  information  from  symbol  definition macros, you may
  specify more than one macro name.  Simply separate each  macro  name
  by a comma.  The information from all macros will be placed into the
  same report.

  If you are listing information from a message object file,  you  may
  only specify one such file with each call to SYMBOL_LIST.

  When  a symbol definition macro is to be listed, the macro libraries
  SYS$LIBRARY:LIB.MLB, SYS$LIBRARY:STARLET.MLB and SYS$LIBRARY:UML.MLB
  are  automatically  searched to locate the specified macro.  You may
  specify an alternate macro library to search by specifying parameter
  macro-lib.

  If  you do not specify the name parameter when invoking SYMBOL_LIST,
  you will be prompted for the name.  Unless parameter  MESSAGE_OBJECT
  was  specified,  you  will be expected to enter the name of a symbol
  definition macro.  If you  enter  just  a  <return>  when  prompted,
  SYMBOL_LIST will terminate.

report-type

  Indicates  the  type  of report to be generated by SYMBOL_LIST.  The
  following keywords are valid:

    DIABLO      The symbols and values will be formatted, using PROSE,
                into  a  series  of files suitable for printing on the
                DIABLO letter quality printer.  Each page  of  symbols
                and  values  will  be  written to a separate disk file
                according to the standard PROSE conventions.

    DISK        The  symbols  and  values  will be written to two disk
                files.   The  first disk file will be sorted by symbol
                name.  The second disk file will be sorted  by  symbol
                value.  The format of this file is:

                  Columns  1-31     Symbol name
                          32        Blank
                          33-40     Symbol value (hexadecimal)

    LP          The symbols and values will be formatted, using PROSE,
                into  a  disk  file  suitable for printing on the line
                printer.  This is the default if you do not specify  a
                report-type.

  SYMBOL_LIST will not prompt for this parameter.   You  must  specify
  this parameter on the command line invoking SYMBOL_LIST.

QUIET

  An  optional keyword which, if specified, indicates that SYMBOL_LIST
  should not print any "success" or "finished" messages to  the  user.
  Normally,  SYMBOL_LIST  will  display the filespecs of the resulting
  report files.  Keyword QUIET is used to prevent this.  This is  most
  useful  when  SYMBOL_LIST  is  invoked  from  within another command
  procedure, such as SYMBOL_EXTRACT.

  This keyword will not affect the printing of error messages.   These
  will  always  be  printed  regardless  of  the  setting of the QUIET
  parameter.

  SYMBOL_LIST will not prompt for this parameter.   You  must  specify
  this parameter on the command line invoking SYMBOL_LIST.

macro-lib

  Specifies the name of an alternate macro library to search  for  the
  symbol  definition  macro(s)  named as the first parameter.  If this
  parameter    is    not    specified,     the     macro     libraries
  SYS$LIBRARY:STARLET.MLB,         SYS$LIBRARY:STARLET.MLB         and
  SYS$LIBRARY:UML.MLB will be automatically searched.

  You may not specify this parameter if you are requesting a list from
  a message  object  file  (i.e.  parameter  MESSAGE_OBJECT  has  been
  specified).

  SYMBOL_LIST  will  not  prompt for this parameter.  You must specify
  this parameter on the command line invoking SYMBOL_LIST.

MESSAGE_OBJECT

  An optional keyword which, if specified,  indicates  that  the  name
  parameter  refers  to  a  message object file.  By default, the name
  parameter is assumed to be  one  or  more  symbol  definition  macro
  names.

  SYMBOL_LIST  will  not  prompt for this parameter.  You must specify
  this parameter on the command line invoking SYMBOL_LIST.
!
!=============================================================================!
! Key 2								    OPERATION !
!=============================================================================!
!
2 Operation
One basic philosophy of the operation of the VAX/VMS  system  involves
the  use  of  symbols  to  represent  message values, structure sizes,
offsets, etc.  These symbols are defined in macro libraries for use in
Macro  assembly  language  programs.   Many  high-level languages also
offer some mechanism for using the more common symbols, i.e the PASCAL
SYS$LIBRARY:STARLET.PEN environment.

In  most  cases,  the values which correspond to these various symbols
are not listed in any of the existing documentation.  If you  need  to
know  a  value  associated  with  a specific symbol, you must find the
location in which the symbol is defined (macro library  definition  or
message file).

SYMBOL_LIST  provides  an  easy  way  to  list   symbols   and   their
corresponding  values.  SYMBOL_LIST will format the list into a report
suitable for printing on the line printer  or  DIABLO  letter  quality
printer.  This report can be saved for future reference.

Two  symbol/value  reports are generated by SYMBOL_LIST.  The first is
an alphabetical listing by symbol name.  The  second  is  a  numerical
listing by symbol value.  Names for these reports are derived from the
first parameter, name.  In general, the name of the report  file  will
correspond  to  the  name  parameter, or the first name parameter if a
list of macro names is entered.  The file type will be  .NAM  for  the
alphabetical  listing  and  .NUM  for  the numerical listing.  Reports
formatted for printing on the DIABLO letter quality printer will  have
a  slightly  different name due to the addition of the page numbers by
the PROSE text processor.

If multiple macro names are entered for the first parameter, name, all
symbols/values defined by all macros specified will be placed into the
same report.  You WILL NOT receive individual reports.   If  you  wish
individual  reports for each macro name, enter the SYMBOL_LIST command
multiple times, specifying only one macro name each time.
!
!=============================================================================!
! Key 2								       ERRORS !
!=============================================================================!
!
2 Errors
Errors detected by SYMBOL_LIST are prefixed  with  the  facility  name
%SYMBOL_LIST.   These errors are described in sub-topics which follow.

SYMBOL_LIST is a DCL command  procedure.   This  means  that  you  may
receive  a  DCL  error  message if an unexpected error occurs.  If you
should receive such an error, check that you  have  correctly  invoked
SYMBOL_LIST,  check  that  the  object  you have specified as the name
parameter exists and that you have sufficient disk quota and privilege
to  create  new  report  files.   If the problem persists, contact the
Academic Computing Center for assistance.
!
!=============================================================================!
! Key 3								       CMPERR !
!=============================================================================!
!
3 CMPERR
%SYMBOL_LIST-E-CMPERR, MACRO compiler error - check macro name

When  you request a list of symbols from one or more symbol definition
macros, SYMBOL_LIST must internally compile  a  small  macro  program.
SYMBOL_LIST  enters  into  this  macro program the names of the symbol
definition macros you have supplied.  This error results if the  Macro
compiler  cannot  locate  one or more of the symbol definition macros.
Check that you have correctly specified the macro names.   Also,  make
sure  that  the  macros  are  defined  in  the  macro  libraries to be
searched.      The      default      library      search      includes
SYS$LIBRARY:STARLET.MLB,  SYS$LIBRARY:LIB.MLB and SYS$LIBRARY:UML.MLB.
If you have specified your own alternate macro library, make sure that
you have specified it correctly.
!
!=============================================================================!
! Key 3								     CONFLICT !
!=============================================================================!
!
3 CONFLICT
%SYMBOL_LIST-E-CONFLICT, macro library not allowed -
                check documentation

You have specified that the first parameter, name, refers to a message
object  file.   You  have  done  this  by   specifying   the   keyword
MESSAGE_OBJECT  as  the  last  parameter.   You have also specified an
alternate macro library  file,  parameter  macro-lib.   The  macro-lib
parameter  is  not  allowed  when  the list object is a message object
file.  Reenter the command without the macro library name,  or  remove
the  MESSAGE_OBJECT  keyword  parameter  if the object is a macro name
located in the specified macro library.
!
!=============================================================================!
! Key 3								    ERRACCFIL !
!=============================================================================!
!
3 ERRACCFIL
%SYMBOL_LIST-E-ERRACCFIL, error accessing internal file !AS

SYMBOL_LIST  uses  many  internal,  temporary  files to accomplish the
listing of symbols and values.  An unexpected error has occurred while
attempting  to access, read or write one of these files.  The specific
file is shown in the error message.  Check that  you  have  sufficient
disk  quota.   If  your  disk quota is near its limit, free up so disk
space and re-attempt the command.   Also,  make  sure  that  you  have
sufficient  privilege  to  create files in your current default device
and directory.  If the error continues to occur, contact the  Academic
Computing Center for assistance.
!
!=============================================================================!
! Key 3								       IVKEYW !
!=============================================================================!
!
3 IVKEYW
%SYMBOL_LIST-E-IVKEYW, unrecognized keyword -
                       check validity and spelling

One  of  the parameter keywords you have entered is not correct.  This
will occur if the report-type parameter is not one of the valid  types
(DIABLO,  DISK  or  LP).   This  will  also  occur  if  the  QUIET  or
MESSAGE_OBJECT parameters are not entered correctly.  SYMBOL_LIST will
print  the  unrecognized  keyword  on  the  line  following this error
message.  Reenter the command correctly.
!
!=============================================================================!
! Key 3								    LSTFILFMT !
!=============================================================================!
!
3 LSTFILFMT
%SYMBOL_LIST-E-LSTFILFMT, list file format mismatch

SYMBOL_LIST  relies  upon  the format of the listing file generated by
the Macro compiler.  The listing file is not in the  expected  format.
SYMBOL_LIST cannot continue.  Please report this error to the Academic
Computing Center.
!
!=============================================================================!
! Key 3								       NULFIL !
!=============================================================================!
!
3 NULFIL
%SYMBOL_LIST-E-NULFIL, missing or invalid file specification -
                       respecify

This error can occur for two reasons.  First, if you requested a  list
from  a  message  object file, SYMBOL_LIST will print this error if it
cannot locate the specified  message  object  file.   Second,  if  you
specified  an  alternate macro library to search for the named macros,
SYMBOL_LIST will print this error if it cannot  locate  the  specified
macro library.
!
!=============================================================================!
! Key 3								      TOOMANY !
!=============================================================================!
!
3 TOOMANY
%SYMBOL_LIST-E-TOOMANY, too many parameters

SYMBOL_LIST allows only five parameters.  You have specified more than
five.   If  you  are  specifying  multiple  macro  names  as the first
parameter, make sure that the macro names are separated by commas only
-  no  extra  spaces.  If you do insert additional spaces, SYMBOL_LIST
may incorrectly count the number  of  parameters,  resulting  in  this
error message.  Reenter the command correctly.
!
!=============================================================================!
! Key 2								     EXAMPLES !
!=============================================================================!
!
2 Examples
(1) You have been writing  a  program  which  uses  many  of  the  RMS
    routines.  These routines can return any of several hundred symbol
    values.  During the  development  of  your  program  you  want  to
    quickly  know  what  error  has  occurred simply by displaying the
    value returned by the routine.  A numerical listing of all the RMS
    symbol  values  (located  in  the  macro  $RMSDEF)  would  be very
    helpful.  To generate such a listing, enter the following command:

      $ @ACC_USERCOM:SYMBOL_LIST $RMSDEF

    The  resulting  report  files  will  be  named   $RMSDEF.NAM   and
    $RMSDEF.NUM.   You can print the numerical listing by entering the
    command:

      $ PRINT/FORM=PROSE $RMSDEF.NUM

(2) You have  developed  a  message  file  containing  all  the  error
    messages  for  your  application   program   ZIMZAM.    You   have
    successfully  compiled the message source file ZIMZAM_MESSAGES.MSG
    and produced the message object  file  ZIMZAM_MESSAGES.OBJ.

    Now, you would like a listing of ZIMZAM  the  message  symbols  to
    include  in  the reference manual.  This listing should be printed
    on the DIABLO.   This  can  be  done  by  entering  the  following
    commands:

      $ LIST :== @ACC_USERCOM:SYMBOL_LIST
      $ LIST ZIMZAM_MESSAGES DIABLO "" "" MESSAGE_OBJECT

    The  resulting  files  ZIMZAM001.NAM  and  ZIMZAM001.NUM  can   be
    submitted to the DIABLO for printing by entering:

      $ DIABLO ZIMZAM001.NAM
      $ DIABLO ZIMZAM001.NUM

    Note that the report filenames are changed by  PROSE  to  fit  its
    single  page per file convention.  This also assumes that only one
    page is necessary for all the  message  symbols  and  values.   If
    additional  pages were required, the filenames would be ZIMZAM002,
    ZIMZAM003, etc.
!
!=============================================================================!
!							   END OF HELP MODULE !
!=============================================================================!
