!=============================================================================!
!  DIVISION   I	:				     HELP MODULE DECLARATION  !
!=============================================================================!
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 01 :					 INITIAL VERSION      !
!      -----------------------------------------------------------------      !
!									      !
!      File Specification: ACCSRC_ACC:[HELP]SYMBOL_EXTRACT.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_EXTRACT			      !
!	 Key 2 ........................	Parameters			      !
!	 Key 2 ........................ Operation			      !
!	 Key 2 ........................ Errors				      !
!	   Key 3 ......................   CONFLICT			      !
!	   Key 3 ......................	  IVKEYW			      !
!	   Key 3 ......................   IVLANG			      !
!	   Key 3 ......................   TOOMANY			      !
!	 Key 2 ........................ Examples			      !
!									      !
!=============================================================================!
!  DIVISION III	:					       SPECIAL NOTES  !
!=============================================================================!
!									      !
!									      !
!=============================================================================!
!
!
!=============================================================================!
! Key 1							       SYMBOL_EXTRACT !
!=============================================================================!
!
1 SYMBOL_EXTRACT
Programs written in high-level languages or procedures  in  DCL  often
need  the  values  associated  with a set of system symbols or message
symbols.  SYMBOL_EXTRACT provides an automatic method  of  translating
such symbols and values into a file useable by the program language or
DCL command procedure.

Format:

     SYMBOL_EXTRACT name format [macro-lib] [outfile] [MESSAGE_OBJECT]

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

     $ @ACC_USERCOM:SYMBOL_EXTRACT ...

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

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

  Specifies  the  name of the object to be extracted and formatted for
  use in a programming language or DCL command procedure.  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  extracting from symbol definition macros, you may specify more
  than one macro name.  Simply separate each macro name  by  a  comma.
  The  definitions  from  all  macros  will  be  placed  into the same
  outfile.

  If you are extracting from a  message  object  file,  you  may  only
  specify one such file with each call to SYMBOL_EXTRACT.

  When  a  symbol  definition  macro  is  to  be  extracted, 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_EXTRACT, 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_EXTRACT will terminate.

format

  Indicates  the  format  of  the  resulting outfile.  The symbols and
  values extracted are formatted for a specific  language  or  command
  procedure.  The valid keywords for format are:

    FORTRAN     The  symbols  and  values  are  formatted  as  FORTRAN
                PARAMETER  statements.   The  resulting outfile can be
                included into a FORTRAN  main  program  by  using  the
                statement:

                  INCLUDE 'outfile'

    GLOBALCOM   The  symbols  and  values  are  formatted as a command
                procedure containing global symbol  definitions.   The
                resulting   outfile  can  be  executed  by  using  the
                statement:

                  @outfile

    LOCALCOM    The symbols and values  are  formatted  as  a  command
                procedure  containing  local  symbol definitions.  The
                resulting outfile must  be  physically  placed  within
                another  command procedure for the local symbols to be
                useful.

    PASCAL      The  symbols  and  values  are  formatted  as   PASCAL
                constants   or   external  variables.   The  resulting
                outfile can be included into a PASCAL main program  by
                using one of the following statements:

                  CONST %INCLUDE 'outfile'
                  or
                  VAR   %INCLUDE 'outfile'

                If you specify PASCAL as the format, you  may  specify
                one of two additional qualifiers.  The qualifiers are:

                  /CONST  Requests that  the  symbols  and  values  be
                          formatted for a CONST section.  This is  the
                          default.

                  /VAR    Requests  that  the  symbols  and  values be
                          formatted for a VAR  section.   The  symbols
                          will    be   defined   as   [EXTERNAL,VALUE]
                          UNSIGNED.  If the  symbols  are  not  global
                          system  values,  you  will have to link with
                          the object file which contains them.

  If   you   do   not  specify  the  format  parameter  when  invoking
  SYMBOL_EXTRACT, you will be prompted for the format.

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 an  extract
  from  a  message object file (i.e. parameter MESSAGE_OBJECT has been
  specified).

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

outfile

  Specifies the name of the resulting output  file.   This  file  will
  contain  the  symbols  and  values  formatted as appropriate for the
  specified format.

  If you do not specify an output filespec, SYMBOL_EXTRACT will use  a
  default   filespec.   For  extracts  from  macros,  the  device  and
  directory will be the  same  as  your  current  default  device  and
  directory.   The  filename  will be the name parameter.  If multiple
  macro names are specified, the name of the first macro will be used.
  The filetype will be determined by the format selected.

  The  default output filespec for extracts from a message object file
  will use the device, directory and name of the message object  file.
  The filetype will be determined by the format selected.

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

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_EXTRACT will not prompt for this parameter.  You must specify
  this parameter on the command line invoking SYMBOL_EXTRACT.
!
!=============================================================================!
! Key 2								    OPERATION !
!=============================================================================!
!
2 Operation
VAX/VMS uses many symbols to indicate success or failure  of  actions.
These symbols are readily available to programmers writing in assembly
language (MACRO).  SYS$LIBRARY contains three macro libraries STARLET,
LIB  and  UML  (the first two are supplied by Digital, the third, UML,
contains locally  developed  macros).   Macro  programs  can  directly
include any macros from these libraries.

FORTRAN  and  PASCAL  programmers  often have the same needs to access
these  symbol  values.   Also,  application-dependent  message   files
generate  symbols  and  values  which  are  often  needed  within  the
application program.  SYMBOL_EXTRACT provides  a  way  to  incorporate
needed  symbols and values into programs written in FORTRAN or PASCAL.
Also, DCL command procedures can use the symbols and values as  global
or local symbols.

SYMBOL_EXTRACT extracts symbols  and  values  from  symbol  definition
macros  and  message  files  by  calling  SYMBOL_LIST.   A  disk  file
containing an alphabetical list of  symbols  and  values  is  created.
This  file  is then formatted into the appropriate high-level language
statements by SYMBOL_EXTRACT.
!
!=============================================================================!
! Key 2								       ERRORS !
!=============================================================================!
!
2 Errors
Errors detected by SYMBOL_EXTRACT are prefixed with the facility  name
%SYMBOL_EXTRACT.   These  errors  are  described  in  sub-topics which
follow.  Since SYMBOL_EXTRACT invokes the SYMBOL_LIST  procedure,  you
may  also receive error messages specific to SYMBOL_LIST (see the help
topic SYMBOL_LIST for a discussion of these errors).

SYMBOL_EXTRACT 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_EXTRACT,  check  that the object you have specified as the name
parameter exists and that you have sufficient disk quota and privilege
to  create  a  new  outfile.   If  the  problem  persists, contact the
Academic Computing Center for assistance.
!
!=============================================================================!
! Key 3								     CONFLICT !
!=============================================================================!
!
3 CONFLICT
%SYMBOL_EXTRACT-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  extraction 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								       IVKEYW !
!=============================================================================!
!
3 IVKEYW
%SYMBOL_EXTRACT-E-IVKEYW, unrecognized keyword -
                          check validity and spelling

One of the parameter keywords you have entered is not  correct.   This
will  occur  if the format parameter is not one of the valid languages
(FORTRAN, PASCAL, GLOBALCOM or LOCALCOM).  This will also occur if the
MESSAGE_OBJECT  parameter  is  not  entered correctly.  SYMBOL_EXTRACT
will print the unrecognized keyword on the line following  this  error
message.  Reenter the command correctly.

You may also receive this error if the qualifier entered on the format
parameter is incorrect.  A qualifier may only follow the PASCAL format
type.  The only valid qualifiers for PASCAL are /CONST and /VAR.
!
!=============================================================================!
! Key 3								       IVLANG !
!=============================================================================!
!
3 IVLANG
%SYMBOL_EXTRACT-E-IVKEYW, unrecognized language -
                          check validity and spelling

The  second  parameter, format, is not correct.  The only valid format
types are FORTRAN, PASCAL,  GLOBALCOM  and  LOCALCOM.   SYMBOL_EXTRACT
will print the unrecognized language format type on the line following
this error message.  Reenter the command correctly.

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_EXTRACT  will
attempt  to  interpret  the additional macro names as the format type,
resulting in this error message also.  In this case, remove the  extra
spaces between the macro names and reenter the command.
!
!=============================================================================!
! Key 3								      TOOMANY !
!=============================================================================!
!
3 TOOMANY
%SYMBOL_EXTRACT-E-TOOMANY, too many parameters

SYMBOL_EXTRACT 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_EXTRACT
may incorrectly count the number  of  parameters,  resulting  in  this
error message.  Reenter the command correctly.
!
!=============================================================================!
! Key 2								     EXAMPLES !
!=============================================================================!
!
2 Examples
(1) You wish to use the CLI (command language interface) symbols  from
    within  your  PASCAL  program.   These  symbols are defined in the
    macro $CLIMSGDEF in SYS$LIBRARY:STARLET.MLB.   To  create  a  file
    suitable  for  including  in  a  PASCAL program CONST section, you
    could invoke SYMBOL_EXTRACT as follows:

      $ @ACC_USERCOM:SYMBOL_EXTRACT $CLIMSGDEF PASCAL

    The  resulting  output  filespec  will be $CLIMSGDEF.PAS.  You can
    then insert the lines

      CONST
          %INCLUDE '$CLIMSGDEF.PAS'

    into  your  PASCAL  program.   All  the  CLI$_ symbols will now be
    available for use within the program.

(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.   When
    linking   the  ZIMZAM  application  you  will  also  link  in  the
    ZIMZAM_MESSAGES.OBJ file.

    Now,  you  would like to use the message symbols inside the ZIMZAM
    PASCAL program.  For example,  when  printing  the  error  message
    associated with the ZIMZAM message symbol ZIMZAM_INVCMND, it would
    be nice to write a call to the $GETMSG system service as  follows:

      status := %GETMSG( ZIMZAM_INVLCMND, Buf_Len, Buffer );
      WRITELN( Buffer );

    Before you can do this, you must declare the  message  symbols  as
    variables  in  the  PASCAL  program.  SYMBOL_EXTRACT can be invoke
    with the command:

      $ EXTRACT :== @ACC_USERCOM:SYMBOL_EXTRACT
      $ EXTRACT ZIMZAM_MESSAGES PASCAL/VAR "" "" MESSAGE_OBJECT

    The  resulting  file, ZIMZAM_MESSAGES.PAS, will contain statements
    for the VAR section of the ZIMZAM program.  You  need  to  include
    this file by using the statement:

      VAR
          %INCLUDE 'ZIMZAM_MESSAGES.PAS'

    The ZIMZAM_MESSAGES.PAS file contains statements such as:

      ZIMZAM_INVLCMND           : [VALUE,EXTERNAL] UNSIGNED;

(3) When writing command procedures, it may become necessary to access
    messages  contained  within  process  message  files.  The lexical
    function F$MESSAGE can be used to print any such  message  if  you
    provide  the  message  symbol value.  Again, SYMBOL_EXTRACT can be
    used to obtain these values.

      $ EXTRACT :== @ACC_USERCOM:SYMBOL_EXTRACT
      $ EXTRACT MYMSGS GLOBALCOM "" "" MESSAGE_OBJECT

    The file MYMSGS.COM will contain a series of global DCL symbol
    definitions such as:

      $ MYMSGS_YESORNO == %X0801C032

    From within your command procedure, you must  do  several  things.
    First,  you must set the message file as your process message file
    and define the global DCL symbols containing  the  message  symbol
    values.

      $ SET MESSAGE MYMSGS
      $ @MYMSGS.COM

    Then, when you wish to print a message, you can  use  a  statement
    such as:

      $ WRITE SYS$OUTPUT "''F$MESSAGE(MYMSGS_YESORNO)'"
!
!=============================================================================!
!							   END OF HELP MODULE !
!=============================================================================!
