


1 help

        *  *  *  *  *  *     N  A  M  E  L  I  S  T     *  *  *  *  *  *
             originally written by Derek Rowell and Douglass Wilson
                        Joint Computing Facility at MIT

                        augmented by Frederick K. Knight
        to be a versatile formated I/O package for VAX Fortran programs
                     at the Naval Research Laboratory (NRL)
              and the Smithsonian Astrophysical Observatory (SAO)

       This help file gives information on the JCF namelist submitted
  through decus and the modifications by Frederick K.  Knight at NRL
  and SAO.  As such, it is both a primer to using namelist and a
  detailed description of namelist.  The topics in this help file are
  listed under TOPICS.  For options of what to do next try WHAT_NEXT.
2 What_next
       If you are not familiar with the JCF namelist, you could
  1.  Print or read NML$DIR:NML.DOC.
  2.  Read introduction, data entry, interrogation, error messages and
      usage, in that order, in this help file.

       If you are familiar with JCF namelist, then read modifications
  and examples in this help file.
2 Topics
       The topics in this help file are the following:

        introduction    includes a basic example
        data_entry      describes input, data types with examples
        examples        one-line examples of namelist input
        interrogation   ? and =? sequences
        nml_options     describes sequences following '\'
        summary         one-screen list of sample inputs
        usage           how to implement namelist in a program
        logical names   describes NML$HELP, NML$SETUP, NML$LIB & NML$DIR
        error messages
        $               It's simple to execute any DCL command.
        per_cent        How to describe variables without a help file
        #               How to initialize a program
        subscripts      describes (*) sequence
        modifications   a summary of the FKK changes
        subroutines     list of all (I think) namelist routines
        future          possible future modifications
1 Introduction
       Namelist input is a non-standard, but very useful, method of
  selectively inputting values to a Fortran program.  It is most
  useful when a small number of variables out of a larger group are to
  be changed for each run.  For example, suppose that a particular
  program has 20 different input values, but on any one run only two
  or three are to be changed.  If the standard Fortran I/O statements
  are to be used, (READ, ACCEPT, WRITE, TYPE, PRINT), all twenty data
  items must be supplied.  Using the namelist feature, the name and
  value of only those items to be changed is entered, the value of all
  other items will remain unchanged.
       This document describes the grammar and syntax of input lines,
  the incorporation of namelists into user programs, and the auxiliary
  features of namelist that allow variable inititialization with
  defaults, on-line help, access to DCL commands, and options that can
  be personalized.
2 example
       A typical line of namelist input might look like:

       ENTER VALUES: A(3)=5., NEW=.TRUE., TITLE= 'RESPONSE'
       ENTER VALUES: CMPLX_VAL=(3,4)&

       Here the names A, NEW, TITLE, and CMPLX_VAL are a part of a
  namelist which may include many more variables.  The system prompts
  ENTER VALUES and enters values into the specified variables until an
  ampersand (&) is encountered.  In the above example, numeric,
  logical, character, and complex data types are demonstrated.
2 Implementation
       VAX namelist is implemented as a set of three user callable
  subroutines.  Two of these are used to initialize namelists,
  (specify variables to be included in the namelists), the third
  performs namelist input.  Additional subroutines may be called to
  set namelist options.
1 data_entry
       Namelist is character-based, but the user interacts via an
  input line described below.  <CR> signals namelist to process all
  new input.  However, continuation lines and automatic subscript
  recall, if enabled, allow input to continue past the <CR> without
  special effort.  All fortran data types can be entered;  the format
  is versatile.
2 input_line
       The input line takes the form of:

              prompt: var = val list, var = val list,.....&

       where prompt....is a user supplied prompting message printed
                         at  the  terminal  to  indicate  that  the
                         system is awaiting input.
             var.......is a variable name,  array  element,  or  an
                        array name
             val list..is a set of one or more numerical,  logical,
                         or  character  data  values  to be entered
                         into the variable or array.
             &.........is the namelist terminator, specifying  that
                         there are no more variables to be entered.
                         Each namelist input must be ended  with  a
                         terminator.
       The input string may be broken into more than one line at
  positions where a comma appears.  A comma at the end of each line is
  optional.
2 examples
       The following are equivalent:

           System Parameters:  A=10.,CVAL=1E36,I=13.& 

        or System Parameters:  I=13
           System Parameters:  CVAL=1E36, 
           System Parameters:  A=10.3 
           System Parameters:  &

       Note:  the values may be entered in any order.
2 types
       Namelist supports LOGICAL*1, LOGICAL*2, LOGICAL*4, INTEGER*2,
  INTEGER*4, REAL*4, REAL*8, COMPLEX and CHARACTER data types.  The
  subtopics describe the syntax of data items in the input line.
3 logical
       Namelist recognizes the following:

       t .true.  .t.  .TRUE.  .T.  T
       f .false.  .f.  .FALSE.  .F.  F

  Any mixture of upper and lower case is allowed.
3 numeric
       Each numeric datum is interpreted as a double precision number
  and is converted to the appropriate mode (integer, real or part of
  complex).  The equivalent format field specification is D<NCHAR>.0,
  where NCHAR is the length of the input string.
3 complex
       Each complex number must be entered in the form:

       (real, imag)

  where real and imag are valid numerical quantities.  The real and
  imaginary parts must be seperated by a comma, for example, (3.,4) or
  (IE-2,17.36).
3 character
       A valid character string or substring is enclosed in
  apostrophes, for example:

       'THIS IS VALID'

  If the string itself includes an apostrophe, that apostrophe must
  appear as a pair of apostrophes, for example:

       'ISN''T THIS FUN?'

  is the input specification for the character item:

       ISN'T THIS FUN?

  The enclosing quotes are unnecessary unless the string contains any
  of the following characters:

       <space> = ?  * , & \ ' !  ;  % # $

  and probably some others I forgot.  When in doubt, use quotes.
  However, the feature to omit the quotes is great for filespecs.  The
  trailing quote can be omitted at the end of the input line.
2 arrays
       When the variable name VAR is an array element or an array name
  some extra features apply.  It is possible to enter a group of
  values into sequential elements of an array by including a list of
  values following the equals sign (=).  In this case, the array name
  or element specifies a base for the sequential entry of data items
  in the value list.  In the case of linear arrays, the values are
  placed sequentially in ascending elements, in the case of multiple
  dimensional arrays the values are entered from the base specified by
  the name or element with the first subscript varying most rapidly
  (the normal Fortran convention).
       If a group of sequential array elements are to be set to the
  same value, the * repeat factor may be used.  The item n*val is
  equivalent to a list of val repeated n times.
       Any valid set of subscripts, (including negative subscripts),
  may be used for the base for sequential data storage, provided no
  attempt is made to exceed the array bounds specified in the
  dimension statement for the array.
3 example
       The following are valid namelist input lines for the array Y
  dimensioned (2,2):

       ENTER VALUES:  Y(1,1)=38., Y(2,2)=0& 
       ENTER VALUES:  Y = 1.,2.,3.,4&
       ENTER VALUES:  Y(2,1)=-3,-4&
       ENTER VALUES:  Y(*)=-5& ; cf. subscripts
       ENTER VALUES:  Y = 4*1&

       In the first line two specific elements of Y have been entered
  as though they were normal variables.  In the second case the whole
  array has been entered and Y(1,1) = 1, Y(2,1) = 2, Y(1,2) = 3, and
  Y(2,2) = 4.  The third line uses the element Y(2,1) as the base for
  the entry of two sequential elements Y(2,1) = -3, Y(1,2) = -4.  The
  fourth line requires auto subscripts to be enabled (cf.  subscripts)
  and fills the element following the last filled, in this case,
  Y(2,2)=-5.  The fifth line sets all four elements of Y to 1.
1 examples
       Here, v and w are variables, simple or array, of any fortran
  data type.  The examples are divided into categories as subtopics.
2 BASIC
   ; comment or
   ! comment can start anyplace on line.
   v=1.,v=1,v=1e0 ; All these set v to 1; v is integer or real here.
   v=1,w=3.       ; Separater is always a comma.
   v=1,2,3        ; Also between elements of an array.
   v(1,1)=1,2,3   ; Equivalent to last line when v is a 2-dim array.
   v=string       ; Quotes are needed only with special characters,
   v=' %#?=+&*()!;' ; like all these.  No doubt I forgot some.
   v(3:6)=ring    ; Substrings can also be input.
2 HELP
   h topic        ; Asks for help on topic from current help library.
   \h topic       ; Asks for special nml help.
2 ADVANCED
   v=1,2,3        ; That's staightforward, but I forgot 4, so...
   v(*)=4         ; v(4) becomes 4.  NML$SET_AUTOSUBS called 1st.
   v(2,3)=4,5,,,,7; Starts filling at (2,3) and skips 3 elements.
   v(2,3)=4,5,3*,7; Like last line. Read "3*" as "skip 3" or "keep 3".
2 INTERROGATION & DESCRIPTION
   v              ; Prints current contents of v.
   v(2,3)         ; Prints single element.
   v(2:3)         ; Prints substring.
   =              ; Prints ALL values of ALL variables.
   ?              ; Prints names of ALL variables.
   v(*)           ; Prints element to be changed to 6 by "v(*)=6".
   #v=6;set volume value
        ; Forces special prompt and allows default or new value.
   %v volume number for data
        ; Describes variable, stored in NML$SETUP, output with ?
2 SPECIAL
   \nml_char=\    ; Changes the special nml character to \.
   \end_char=&    ; Changes the ending character to & (the default).
   \infile=f.dat  ; Starts reading from f.dat.
   \promptfile=nl:; Outputs prompt to the null file.
   \promptfile=-  ; Resets promptfile to previous value.
   \echofile=f.log; Sets echofile to f.log.
   \outfile=f.out ; Sets outfile to f.out.
   \prompt=picky-picky ; Sets prompt to picky-picky; reset with \prompt=-.
   \on_eof=stop   ; If an eof =ctrl Z is read, namelist stops program.
   \library=f.hlb ; Help library becomes f.hlb.
   \nml_library=f.hlb; Changes the nml_library - all this explanation.
   \instat=old    ; Sets the open status for new infiles to old.
   \promptstat=old; Sets the open status for new promptfiles to old.
   \echostat=old  ; Sets the open status for new echofiles to old.
1 interrogation
       VAX namelist allows the user to inquire as to

  1.  the names and description of variables in the current namelist -
      using "?"
  2.  the current value of any item (variable or array) in the
      namelist - using "item" or "item=" or "item=?"
  3.  the current value of all items in the namelist - using "=" or
      "=?"

2 QUESTION_MARK
       A "?" typed at the keyboard will generate a summary of all the
  names and attributes of the current variables in the namelist.  This
  is a useful feature to remind users of the names and dimensions to
  be used.


        ENTER VALUES:  ?  <CR>

          ALPHA(50)     [REAL*4]
          LOGVAL(10)    [LOGICAL*2]
          BRAVO         [REAL*8]
          CHARLIE       [INTEGER*4]
          PROG_NAME     [CHARACTER*40]

       In addition descriptions of variables can be added using the
  "%" option in setup files (cf % and logical names NML$SETUP).
2 item,item=,item=QUESTION_MARK
       The current value of an individual namelist variable, or a
  whole array may be interrogated by entering a "var name" or "var
  name=" or "var name = ?" in the input stream.  For example,

       ENTER VALUES:  ALPHA=3,4;5,10*-15,BRAVO=33.,CHARLIE=?  <CR>

  will enter the new values into ALPHA and BRAVO and then type the
  current value of the variable CHARLIE.  The user can then make a
  decision whether or not to modify this value.
       In the case of an array name, a particular element may be
  interrogated by specifying a set of subscripts;  if no subscripts
  are given the values of all array elements will be typed, in the
  order of storage in the array (first subscript varying most
  rapidly).
2 =QUESTION_MARK
       The current value of all variables in the namelist may be typed
  by simply issuing the command =?  or =.  For example,

       ENTER VALUES:  A=0.1,2,3,=?  <CR>

  will set three new values into A and then type out the values of all
  namelist items.
       Alternatively, the calling program can force a sequence of
  variables to be set using lines beginning with "#".  Here, namelist
  prompts the user and allows either default or new values (cf #).
1 nml_options
       Here is a list of the internal namelist variables accessed
  through the nml character (shown here as \).
 Option                  Default     Description
 ---------------------   -------     ---------------------------------
 \?                                  print all the internal variables
 \echofile=<filespec>    init value  change the echo file
 \echostat=<option>      new         change the open status of new echofiles
 \end_char=<single char> &           change end character
 \h topic                            access the namelist help
 \infile=<filespec>      init value  change the read file
 \instat=<option>        old         change the open status of new infiles
 \library=<filespec>     system help change the accessed help library
 \nml_char=<single char> \           change the nml character
 \nml_library=<filespec> NML$HELP    change the accessed nml help library
 \on_eof=<option>        continue    change action at eof
 \outfile=<filespec>     promptfile  change the namelist-readable outfile
 \outstat=<option>       new         change the open status of new outfiles
 \prompt=<new prompt>    init value  change the prompt to <new prompt>
 \promptfile=<filespec>  init value  change the prompt file
 \promptstat=<option>    new         change the open status of new promptfiles
 \stop=<string>          STOP        change stop string to <string>
2 prompt
        FORMAT: \prompt='new prompt'

       Typing the sequence "\prompt='new prompt'" changes the prompt
  to "new prompt".  This is useful when you want to output values to a
  file using "var_name" but do not want any intervening prompts.  You
  can do this by typing "\prompt=' '".
2 instat
        FORMAT: \instat=old (D)
                \instat=new
                \instat=unknown
        or    : CALL NML$SET_OPEN_STAT(1,'old') (D)
                CALL NML$SET_OPEN_STAT(1,'new')
                CALL NML$SET_OPEN_STAT(1,'unknown')

       When new infiles are opened the status key word is set to old.
  This can be changed to new by typing, e.g., "\instat=unknown".
2 promptstat
        FORMAT: \promptstat=old
                \promptstat=new (D)
                \promptstat=unknown
        or    : CALL NML$SET_OPEN_STAT(2,'old')
                CALL NML$SET_OPEN_STAT(2,'new') (D)
                CALL NML$SET_OPEN_STAT(2,'unknown')

       When new promptfiles are opened the status key word is set to
  new.  This can be changed to new by typing, e.g.,
  "\promptstat=unknown".
2 echostat
        FORMAT: \echostat=old
                \echostat=new (D)
                \echostat=unknown
        or    : CALL NML$SET_OPEN_STAT(3,'old')
                CALL NML$SET_OPEN_STAT(3,'new') (D)
                CALL NML$SET_OPEN_STAT(3,'unknown')

       When new echofiles are opened the status key word is set to
  new.  This can be changed to unknown by typing, e.g.,
  "\echostat=unknown".
2 outstat
        FORMAT: \outstat=old
                \outstat=new (D)
                \outstat=unknown
        or    : CALL NML$SET_OPEN_STAT(4,'old')
                CALL NML$SET_OPEN_STAT(4,'new') (D)
                CALL NML$SET_OPEN_STAT(4,'unknown')

       When new outfiles are opened the status key word is set to new.
  This can be changed to unknown by typing, e.g., "\outstat=unknown".
2 examples
  1.  The end character can be changed from its default value of "&"
      to any new end_char by typing "\end_char=<new end_char>".
  2.  Typing "\infile=input.dat" would change the input file to
      input.dat immediately, and read from it until another change of
      infile or an eof.  Namelist opens an unused fortran unit on
      "input.dat" and starts reading from that file.
  3.  Typing "\promptfile=nl:" or "\prompt=' '" eliminates the prompt.
  4.  Typing "\outfile=output.dat" allows writing current values to
      "output.dat" with subsequent listing requests, for example,
      typing "=?" or "var_name".

2 end_char
        FORMAT: \end_char=<single char> (D=&)

       The end_char ends input to namelist and returns control to the
  calling program.  The default end_char is "&", and can be changed by
  entering "\end_char=<single char>".
2 nml_char
        FORMAT: \nml_char=<single char> (D=&)

       The nml_char starts input to special sequences called
  nml_options.  The default nml_char is "\", and can be changed by
  entering "\nml_char=<single char>".  If you hate \, choose another
  character and put it in a setup file.
2 on_eof
        FORMAT: \on_eof=continue (D)
                \on_eof=stop
                \on_eof=return
        or    : CALL NML$SET_ON_EOF('option')

       Namelist has three options when it reads an eof (that is, ^Z).
  The default action is to continue reading data but from the previous
  file rather than the current one (where the eof was encountered).
  If namelist is reading from the initial unit, namelist stops by
  default.  The two options to replace this default are (1) stop and
  (2) return, that is, exit from namelist and return to the calling
  program.  After "\on_eof=stop" is entered, reading an eof exits the
  program.  After "\on_eof=return" is entered, any eof, including one
  read from the initial unit, becomes the end_char.
2 library
        FORMAT: \library=<filespec> (D=SYS$HELP:HELPLIB.HLB)
                \help_library=<filespec>
        or    : CALL NML$SET_LIBRARY('<file spec>')

       Namelist has a reserved character "h" to allow access to a help
  file.  If "h topic name" is entered, namelist calls the help utility
  with the enabled help library.  The default help library is the
  system help library:  SYS$HELP:HELPLIB.HLB.  The user can change the
  help library in two ways.  In the calling program, there can be a
  call to NML$SET_LIBRARY, for example, CALL
  NML$SET_LIBRARY('<filespec>').  During namelist operation, the help
  library can be changed using
       \LIBRARY=<filespec>
  or
       \HELP_LIBRARY=<filespec>
  No blanks can be embedded in the <filespec>.
2 infile
        FORMAT: \infile=<file spec> (D=calling value)

       Infile is the input file for namelist.  It can be changed at
  any time by typing "\infile=<file spec>".  When an eof is read
  namelist will return to the previous unit by default, cf.  on_eof.
  To assign infile to promptfile, type "\infile=promptfile".  To
  assign infile to echofile, type "\infile=echofile".
2 promptfile
        FORMAT: \promptfile=<file spec> (D=calling value)

       The user prompt, error messages, and, by default, all output
  from information requests (?  and =?  commands) are sent to the
  prompt unit.  If the outfile is reassigned, then the prompt unit no
  longer receives the output from the =?  commands.  The prompt unit
  can be changed at any time by typing "\promptfile=<file spec>".  It
  may also be convenient to eliminate the prompt with "\prompt=' '".
  To revert to previous promptfile, enter "\promptfile=-".  To assign
  promptfile to infile, type "\promptfile=infile".  To assign
  promptfile to echofile, type "\promptfile=echofile".
2 echofile
        FORMAT: \echofile=<file spec> (D=calling value)

       The echo unit receives all input typed at the terminal or read
  from an input file and error messages.  Thus, it acts as a journal
  of namelist dialog.
       The echo unit can be changed at any time by typing
  "\echofile=<file spec>".  To revert to previous echofile, enter
  "\echofile=-".  To assign echofile to promptfile, type
  "\echofile=promptfile".  To assign echofile to infile, type
  "\echofile=infile".
       The echofile can be assigned to the promptfile to display
  namelist input being read from an external file.  For example an
  input file could contain

       \echofile=promptfile     ! to echo to the prompt unit.
       \promptfile=nl:          ! to kill prompts temporarily.
       ...                      ! input displayed on terminal.
       \echofile=-              ! to recover original echofile.
       \promptfile=-            ! to recover original promptfile.
2 outfile
        FORMAT: \outfile=<file spec> (D=promptfile)

       In its default state, the outfile receives prompts, error
  messages, and all informational output from the =?  commands.
  However, if it is reassigned, it receives only namelist-readable
  output, namely the input lines and the output from the =?  commands.
  This allows a replay of input or a method to save the current state
  of any variables for future reference.  It can be changed at any
  time by typing "\outfile=<file spec>".  To assign outfile to
  promptfile, type "\outfile=promptfile".  To assign outfile to
  echofile, type "\outfile=echofile".
2 nml_library
        FORMAT: \nml_library=<file spec> (D=NML$HELP)
        or    : CALL NML$SET_NML_LIBRARY('<file spec>')

       Namelist has a reserved sequence "\h" to allow access to the
  namelist help file.  The default is the logical name, NML$HELP.  If
  "\h topic" is entered, namelist calls the help utility with the
  enabled help library.  The user can change the help library in two
  ways.  In the calling program, there can be a call to
  NML$SET_NML_LIBRARY, for example, CALL
  NML$SET_NML_LIBRARY('<filespec>').  During namelist operation, the
  help library can be changed using
       \NML_LIBRARY=<filespec>.
  No blanks can be embedded in the <filespec>.
2 stop
        FORMAT: \stop='string' (D=stop)
        or    : CALL NML$SET_STOP('string')

       The stop command (D=stop) stops namelist.  This means you can
  exit with ^C,^Y,stop, ^Z if \ON_EOF=STOP, and ^Z if \ON_EOF=CONTINUE
  and there are no more input files available.  The default (stop) can
  be changed to any string by \stop=<string> where <string> is up to
  20 characters in length.  For example, you can type "\stop=quit" to
  make the stop command string be "quit".  This also means you can
  type ahead and exit namelist with stop and not interrupt your
  program with ^Y.  You can also set the stop command in the calling
  program with "CALL NML$SET_STOP('string')".
1 Summary
       Typical inputs are the following.  v and w are variables or
  arrays.
  v or v= or v=?         ;to show the current values of v
  ?                      ;to list all variables & their types
  = or =?                ;to list current values of variables
  v=v0,w=w0              ;to set v to v0 and w to w0
  v(2)=v1,v2,v3,...      ;to set v(2)=v1,v(3)=v2,v(4)=v3,...
  ,v8,v9                 ;to continue input from previous line
  h topic ...            ;to get help on topic ...
  v(*)=v10,v11,...       ;to continue input from previous point
  \nml_option=value      ;to input an internal variable
  \h                     ;to get namelist help
  \?                     ;to view current nml options
  &                      ;to end input
  $ DCL COMMAND          ;to execute a DCL command
  %v description         ;to describe v in ? command
  #v=v0;prompt           ;to force a special prompt and set v
1 usage
2 overview
       The namelist feature is designed around the fact that the VAX
  Fortran compiler can be forced to generate a "descriptor block" for
  variables and arrays in any program.  The descriptor block is a
  small block of memory that contains all of the information about the
  variable.  Among other things it contains - the data type, the
  location in memory, the subscript bounds information, and the number
  of dimensions.
       VAX namelist requires two arrays in the calling program.  The
  first is initialized to contain the character strings of the names
  of the variables, the second is initialized to contain the address
  of the descriptor block for the variables.  Two subroutines are
  provided to perform this initialization.  The namelist subroutine
  searches the names array for a match with the name supplied in the
  input string, and then accesses all of the information required
  through the corresponding entry in the descriptor array.
2 linking
       The namelist object code is contained in the library
  NML$DIR:NML.OLB and is assigned the logical name NML$LIB.  To link
  namelist with the calling program, use

       LINK ...,NML$LIB/LIB

  where ...  stands for all the other object modules needed by the
  program.
2 calling
       The program (or subprogram) that uses VAX namelist must declare
  and initialize the two arrays used by the subroutine namelist,
  namely the array holding the variable names and the array containing
  the descriptor block addresses and optionally the last-filled
  element in the variable.  This is described in Steps 1-3.  Then the
  program must call namelist, described in Step 4.  There are also
  auxiliary routines, which set options and which can be called at any
  time.  These are described in options.
3 1_Step
       First, the calling program must declare a CHARACTER*(*) array
  that will contain the variable names and an INTEGER*4 array to
  contain the descriptor block addresses.  Consider, for example, a
  simple namelist containing 5 entries:

       PARAMETER NUM=5
       CHARACTER*15 NAMES(NUM)
       INTEGER*4 IDESC(NUM) ! or IDESC(NUM,2) - cf subscripts

       Notice that the NAMES array is declared so that variable names
  are limited to 15 characters.  This limit is at the programmer's
  discretion.  The second dimension in IDESC is used for remembering
  last-filled elements and is necessary only when automatic subscript
  remembering has been enabled (cf.  options and subscripts).
3 2_Step
       The second step is initialize the character array with the
  names using either a data statement or a call to NML$NAME_SET.  For
  example,

       DATA NAMES/'ALPHA','BETA','GAMMA','DELTA'/
  or
       CALL NML$NAME_SET(NAMES,'ALPHA,BETA,GAMMA,DELTA')

       NML$NAMES_SET takes two parameters, the CHARACTER*(*) array to
  hold the names and the string.  The variable names must be upper
  case letters and separated by commas.
3 3_Step
       Third, the calling program must initialize the descriptor
  address array by calling the subroutine NML$DES_STUF

       CALL NML$DES_STUF(array,%DESCR(name1),%DESCR(name2),...)

  where array..........is the INTEGER*4 array
        name1,name2,...are the names of the variables

  For example:
           CALL NML$DES_STUF(IDESC,%DESCR(ALPHA),%DESCR(BETA),
          *    %DESCR(GAMMA),%DESCR(DELTA),%DESCR(EPSILON))

       Note that NML$DES_STUF takes a variable number of arguments
  depending on the size of the namelist.  The VAX Fortran function
  %DESCR( ) forces the compiler to generate a descriptor block for
  each function.
3 4_Step
       After the above initialization, namelist input may be invoked
  by calling the subroutine NAMELIST:

       CALL NAMELIST(prompt,names,desc,num,indev,echodev,promptdev).
  where
       prompt........is a character sring to be written on logical
                      unit promptdev as a user prompt.
       names.........is the CHARACTER*(*) array containing the names
                      of entities in the namelist.
       desc..........is the INTEGER*4 array containing the descriptor
                      block pointers as initialized by NML$DES_STUF.
       number........is the number of items in the namelist.
       indev.........is the logical unit number for the namelist
                      input.
       echodev.......is the logical unit onto which the prompt, input,
                      and error messages are echoed.  This is useful
                      for recording the namelist dialog.
       promptdev.....is the logical unit for the prompt message issued
                      each time a namelist string is to be read.  For
                      keyboard operation promptdev would normally be
                      directed at the console.
4 example
       In the above example, the call might be

       CALL NAMELIST('TYPE VALUES:',NAMES,IDESC,5,95,96,95)

  where 95 and 96 have been opened to the desired units.
4 devices
       Namelist uses four logical units, three of which (indev,
  echodev, and promptdev) are parameters in the call to namelist.  The
  fourth, outdev, defaults to the prompt unit, but can be assigned to
  any file inside namelist.  Indev is the unit from which all data are
  read, and can be the terminal or a file.  Echodev receives the
  prompt, the input, and error messages, so it acts as a journal.
  Promptdev receives the prompt, all informational output, and error
  messages.  If outdev is reassigned from its default, it receives
  only output that can be read by namelist, namely the input lines and
  the output from the =?  commands.  Thus, outdev can be used to
  replay input or store the current state of variables.  There is more
  detailed information under nml_options.
3 Options
       The namelist user can set options using either subroutine calls
  or special sequences while inputting to namelist.  These are
  described in detail in nml_options.  Here is a short list of the
  subroutines with dummy arguments.

  1.  CALL NML$SET_OPEN_STAT(N,'STATUS_NAME')
  2.  CALL NML$SET_ON_EOF('OPTION')
  3.  CALL NML$SET_LIBRARY('LIBRARY_NAME')
  4.  CALL NML$SET_NML_LIBRARY('LIBRARY_NAME')
  5.  CALL NML$SET_STOP('STRING')
  6.  CALL NML$SET_AUTOSUBS(.TRUE.)

1 logical_names
       There are four logical names associated with namelist.
  NML$HELP should be assigned to the file containing the help library,
  NML.HLB.  NML$SETUP can be assigned to any file containing namelist
  input.  Namelist reads this file initially to setup options
  different from the defaults (cf.  nml_options).  NML$LIB is the
  namelist object library.  NML$DIR is the directory containing all
  namelist files.
2 NML$DIR
       This directory contains all the files associated with namelist,
  namely

       AAAREADME.RNO  - the runoff input file for AAAREADME.TXT
       AAAREADME.TXT  - the synopsis of namelist files
       NML.FOR        - the Fortran code
       NML.DOC        - the current namelist document
       NMLORIG.DOC    - the original DECUS document
       NMLHLP.RNO     - the runoff input file for NML.HLP
       NMLDOC.JOU*    - the EDT script to convert NMLHLP.RNO to NMLDOC.RNO
       NMLDOC0.RNO*   - the runoff input for the NML.DOC introduction
       NMLNEWDOC.COM* - the DCL script to make NML.DOC from NMLDOC.RNO
       NML.HLP        - the help library input file
       NML.HLB        - the namelist help library, NML$HELP
       NML.OBJ        - the object code
       NML.OLB        - the namelist object library, NML$LIB
       NML.MAR        - the macro code

       * see also the NML$HELP topic "logical_names NML$DIR."
  r.i -2 3 making_changes
       Making changes in namelist is possible;  all the source code is
  supplied.  Making the accompanying changes in the documentation is
  possible also.  Here is a recipe to modify the help file and then
  the document.
       The source for the help file, NML.HLP is a runoff input file,
  NMLHLP.RNO.  Edit NMLHLP.RNO, create NML.HLP ($ RUNOFF
  NMLHLP/OUT=NML.HLP), and modify the library ($ LIB/HELP NML NML).
  The EDT script to modify NMLHLP.RNO to become the runoff input file
  for NML.DOC is called NMLDOC.JOU.  To remake NML.DOC, run EDT to
  create a new NMLDOC.RNO ($
  EDIT/EDT/RECOVER/JOURNAL=NMLDOC.JOU/OUT=NMLDOC.RNO NMLHLP.RNO
  followed by exit/save), create NML.DOC with runoff ($
  RUNOFF/CONTENTS/OUTPUT=NML.DOC NMLDOC.RNO), create a new table of
  contents ($ RUN SYS$SYSTEM:TOC and use the input file NMLDOC.BTC),
  recreate NML.DOC with the new table of contents ($
  RUNOFF/OUTPUT=NML.DOC NMLDOC.RNO) and clean up the trash files.
2 NML$HELP
       The namelist help library is accessed through the special
  sequence "\h topic" where topic is optional.  This library must be
  assigned the logical name NML$HELP.  The library can be modified by
  editting the input file NMLHLP.RNO, using runoff to create a new
  NML.HLP, and then using the VAX librarian utility (cf
  making_changes).
2 NML$SETUP
       As part of its initialization, namelist reads input from the
  file assigned to the logical name NML$SETUP.  If this logical name
  does not exist, namelist uses the default settings listed under
  nml_options in this help file.  The ?  command also checks NML$SETUP
  for descriptions of individual variables prefaced by "%".
       The user can assign the logical name NML$SETUP within a program
  using the system service SYS$CRELOG or assign it in DCL to a setup
  file.
2 example
       Here is an example:  the file called SETUP.NML contains

       \stop=quit           ! Use quit instead of stop to exit.
       \on_eof=return       ! Exit namelist when an eof is read.
       \echofile=output.nml ! Create a journal file in output.nml.
       \?                   ! Display the current nml options.
       %x array of independent variables
                            ! Describe variables for use with ? command
       #x=1,2,3 ; set independent variable
                            ! Force a special prompt for input
2 assigning NML$SETUP
       All you need to do is type "ASS SETUP.NML NML$SETUP" in DCL and
  run the program that calls namelist.  Namelist will start by reading
  the contents of SETUP.NML.  Alternatively you can make the
  assignment in fortran by using

       INTEGER*4 SYS$CRELOG,ISTAT
       ...
       ISTAT=SYS$CRELOG(%VAL(2),'NML$SETUP','SETUP.NML',)
       CALL NAMELIST('PROMPT:'...

  This internal assignment using SYS$CRELOG is temporary;  it exists
  only while the program is running.  ISTAT may indicate error (=/= 1)
  after the call, but I think this works, cf.  system services
  reference manual.
1 errors
       VAX namelist contains an extensive set of syntax checking
  functions.  In interactive mode syntax errors in the input stream
  are generally non-fatal.  A diagnostic message will be typed and new
  input requested.  All valid entries up to the point of the error
  will be made, but once a syntactical error is detected the rest of
  the line will be disregarded.  For example:

       ENTER VALUES:  A=3,4,5,10*0,B=3,C45.6,D=13,E=-12&

  contains an error in that the entry for C does not have an = between
  the name and the value.  The message

       NAMELIST ERROR :  INVALID INPUT :  NO'=' GIVEN

  will be printed.  The new values for A and B will be entered but the
  values for C,D, and E will have to be re-entered.  The ampersand (&)
  at the end of the line is ignored and new input requested.  If input
  is taken from a non-interactive device, errors are generally fatal.
1 $
       A DCL command can be executed by putting $ at the start of an
  input line.  For example, typing "$ dir" after the namelist prompt
  would do a directory list on the default directory.
       There are restrictions.  For example, the current directory
  cannot be changed with SET DEFAULT.
1 per_cent
       % is a reserved character at the start of a line.  The line is
  a comment unless it appears in the file assigned to NML$SETUP where
  it is used to describe a variable for use in the ?  command.  If the
  line has the format

       %variable description

  then description follows the variable type in the output of the ?
  command.  You can place a semicolon in front of the description.
  Then, if you remove the leading %, the line simply becomes command
  to display the contents of X.  Also, the descriptions contained in
  NML$SETUP can be used by many programs if the variables are the
  same, allowing effective on-line documentation without the overhead
  associated with help files.  These descriptions are a quick
  alternative to help files.  However, the description is meant to be
  short and can be only ~200 characters in length.
2 example
       For example, if

       %x array of independent variables

  appeared in the file assigned to NML$SETUP and x(100) is a real*4
  array, then the output of the ?  command would contain

       X(100)       [REAL*4] array of independent variables

1 #
       # is a reserved character at the start of a line and forces a
  second prompt to allow the user to accept a default value for a
  variable or else input a new value.  This method allows a forced
  sequence of setting variables anytime during a program's operation,
  for example, to initiialize the program.  Any namelist line can have
  this format, including arrays and nml_options.  Removing the #
  leaves a regular namelist input line.
2 format
       The format of the line is

       #variable=value ;comment to serve as prompt

  and forces namelist to print

       comment to serve as a prompt: variable=value

  The user can respond with a carriage return and the variable is set
  to value or can input a new value for the variable (followed by a
  CR).  If the comment is missing, namelist prints

       Confirm w/ CR or give new value & CR:variable=value
2 examples
       #x =6;set the number of data points
       produces
       set the number of data points: x=6

       #plb=1,1,1,3*-1
       produces
       Confirm w/ CR or give new value & CR: PLB=1,1,1,3*-1

       #output=[goose.rhymes]maryslamb.txt; choose a nursery rhyme
       produces
       choose a nursery rhyme: output=[goose.rhymes]maryslamb.txt
1 subscripts
       Here I describe the automatic remembering of subscripts
  implemented by the "(*)" sequence.  The motivation is to allow
  namelist to fill many arrays partially, then return to each and
  start filling at the next available location without remembering its
  subscripts.  This is a useful alternative to continuation lines if
  you want to intersperse other variables.
       To use this capability, the parent program must make the
  descriptor address array 2-dimensional, eg, INTEGER*4 IDESC(NUM,2)
  and call NML$SET_AUTOSUBS(.TRUE.).
2 examples
       For example, this

       prompt: a=1,2,3,4
       prompt: ,5,6
       prompt: b=1,2,3,4
  will be equivalent to
       prompt: a=1,2,3,4
       prompt: b=1,2,3,4
       prompt: a(*)=5,6  .

       A specific use is to read values separately and allow them to
  be in any order, eg data from different experiments.  For example,

       prompt: a(1)=1,2,b(1)=1,2
       prompt: a(3)=3,4,b(3)=3,4
  will be equivalent to
       prompt: a(*)=1,2,b(*)=1,2
       prompt: a(*)=3,4,b(*)=3,4  .

  But in the second case, the lines could be interchanged without
  changing the subscripts.
2 usage
       To use the remember subscripts option, namelist needs some more
  space from the user, namely one more integer for each variable.  The
  space is provided by making the descriptor address array
  2-dimensional, eg.  INTEGER*4 IDESC(NUM,2).  This is only necessary
  if you want the option of using (*).  Old versions of namelist
  remain unaltered.  You will have to call one more namelist routine
  to initialize using (*).  The call is CALL NML$SET_AUTOSUBS(.TRUE.).
  The default is as if this call were made with .FALSE.  argument.
  After you make this call, namelist will access the second half of
  the IDESC array, so the declaration must be the 2-dimensional
  version.  Also, you can find what would be changed using the
  sequence "a(*)".  This displays the value and subcripts of the next
  element in a, that is, the element that would be changed to 6 by
  typing "a(*)=6".
1 Modifications
       Frederick K.  Knight at NRL and SAO has made changes in
  namelist.  Most of these are summarized within the summary topic in
  this help.  Here is a list of the most of the changes as of February
  1984.  In parentheses are associated help topics.
  1.  ALLOW HELP FILES WITH THE RESERVED CHARACTER H OR h (nml_options
      help_library).
  2.  ALLOW =?  ON A VARIABLE BY SIMPLY TYPING THE VARIABLE NAME -
      ALONE ON A LINE (interrogation).
  3.  ALLOW COMMENTS EITHER ON ENTIRE LINE OR AT END OF INPUT LINE
      USING EITHER ;  OR !
  4.  ALLOW NO PROMPT BY EITHER GIVING A BLANK PROMPT STRING OR
      PLACING AN ASCII NULL AT THE START OF THE STRING.  (nml_options
      prompt).
  5.  ALLOW OMISSION OF TRAILING QUOTE FOR LAST VARIABLE ON LINE.
  6.  ALLOW "VARIABLE=" OR "VARIABLE=," OR "VARIABLE=&" TO BE REQUEST
      TO DISPLAY CURRENT VALUE OF VARIABLE, THAT IS, AS IF "=?" WAS
      TYPED INSTEAD OF SIMPLY "=".  THIS FORM CAN BE EMBEDDED WITHIN A
      LINE (interrogation).
  7.  ALLOW 3 OPTIONS IF AN EOF IS READ:  STOP, RETURN OR CONTINUE
      (nml_options on_eof).
  8.  ALLOW CONTINUATION LINES WITH AN INITIAL COMMA.  ACTUALLY, I
      THINK THE ORIGINAL NAMELIST ALLOWED THIS BUT THE FIRST FORM OF
      MY MODIFICATION 2.  MADE THIS FORM AMBIGUOUS.
  9.  ALLOW SEQUENCES FOLLOWING A SPECIAL CHARACTER, THE NML-CHARACTER
      WHOSE DEFAULT VALUE IS BACK SLASH, "\" (nml_options).
 10.  ALLOW LEADING BLANKS OR TABS ON ANY LINE, INCLUDING A
      CONTINUATION, WITHOUT ANY EFFECT ON THE INPUT.
 11.  CONSTRUCT A HELP FILE FOR NAMELIST ACCESSED THROUGH THE SPECIAL
      CHARACTER OF 9.  FOR EXAMPLE, TYPE "\H" (nml_options
      nml_library;  logical_names NML$HELP).
 12.  MODIFY THE OUTPUT FORMAT TO BE LESS VERBOSE AND HAVE A FORM
      COMPATIBLE WITH SUBSEQUENT NAMELIST INPUT.  THIS MODIFICATION
      COULD USE FURTHER WORK.
 13.  ALLOW A NEW SUBSCRIPT SPECIFICATION, (*), TO ENABLE AUTOMATIC
      SUBSCRIPT RECALL.  MOTIVATION IS TO ALLOW INPUT INTO PORTIONS OF
      ARRAYS SEPARATED BY OTHER INPUT WITHOUT HAVING TO KNOW WHERE THE
      NEXT ELEMENT IS (subscripts).
 14.  ALLOW MORE GENERAL INPUT TO ARRAYS BY TREATING MULTIPLE COMMAS
      AS SKIPS IN INPUT.  WHENEVER THE INPUT IS NO CHARACTERS, THE
      ARRAY ELEMENT RETAINS ITS CURRENT VALUE.  THE MULTIPLE COMMAS
      CAN EITHER BE EXPLICIT, LIKE ",,,,", OR COUNTED WITH A STAR,
      LIKE "3*,".  THESE TWO RESULT IN THE SAME THING:  A SKIP OF
      THREE ELEMENTS IN THE ARRAY.
 15.  ALLOW ACCESS TO DCL COMMANDS VIA THE RESERVED CHARACTER $ IN THE
      FIRST NON-BLANK CHARACTER ($).
 16.  MAKE THE SEQUENCE "VAR(*)" MEAN 'PRINT THE CURRENT VALUE OF THE
      ELEMENT OF V TO BE CHANGED BY THE SEQUENCE "V(*)=<value>"'
      (subscripts).
 17.  Form 3 open status variables for the 3 units because the infile
      usually wants OLD, promptfile wants NEW, and echofile wants NEW
      (nml_options instat - promptstat - echostat).
 18.  Allow a stop command whose default value is STOP.  This means
      you can exit with ^C,^Y,STOP, and ^Z if \ON_EOF=STOP.  The
      default (STOP) can be changed to any string by \stop=<string>
      where <string> is up to 2O characters in length.  This also
      means you can type ahead and exit namelist with STOP, so you
      don't interrupt your program with ^Y (nml_options stop).
 19.  Allow user initialization by assigning the logical name
      NML$SETUP to any file containing namelist input (logical_names
      NML$SETUP).
 20.  Define one more logical unit for writing namelist-readable
      output (D=echofile;  nml_options outfile)
 21.  Reserve another special character, #, to enable special prompts
      for setting individual variables, for example, at the start of a
      program.  (#)
 22.  Reserve another special character, %, to supply descriptions of
      individual variables in the NML$SETUP file.  (% and
      logical_names NML$SETUP)
 23.  Allow input of substrings with bounds checking as well as output
      of substrings by typing the variable name and the substring
      range.

1 future
       Frederick K.  Knight would like to make the following changes
  in namelist.
  1.  ALLOW SPECFICATION OF OPEN PARAMETERS WHEN CHANGING INPUT FILE.
      FOR EXAMPLE, TYPE "\STATUS=UNKNOWN" FOR LATER OPEN STATEMENTS.
      THE EXAMPLE IS DONE, BUT ALLOWING CHANGES IN OTHER OPEN
      PARAMETERS MAY BE HELPFUL.
  2.  ALLOW LISTING OF PARTS OF ARRAYS.
  3.  ALLOW CONTROL C INTERRUPTS TO DO VARIOUS THINGS LIKE CONTROL Z.

1 subroutines
       All namelist subroutine names, except the top routine called
  namelist, begin with NML$ to avoid confusion with other utilities
  and programs.  Here is a list of the namelist subroutines, functions
  and entries with *'s marking the ones needed by a user.
  *NAMELIST
   NML$PRINT_NAMES         NML$PRINT_ALL           NML$NOLEAD
   NML$INT4_VAL            NML$REAL8_VAL           NML$OP_MODE
   NML$PACK                NML$MOVE_BYTES          NML$PUT_VALUE
  *NML$NAME_SET           *NML$DES_STUF            NML$HEAD
   NML$GET_STR             NML$GET_CHAR           *NML$SET_ON_EOF
   NML$MATCH               NML$UPCASE              NML$UNIQUE_UNIT
   NML$OPENF               NML$CLOSEF              NML$OPENUP
  *NML$SET_OPEN_STATUS     NML$GET_OPEN_STATUS
   NML$GET_HELP           *NML$SET_LIBRARY         NML$GET_LIBRARY
   NML$NML_HELP           *NML$SET_NML_LIBRARY     NML$GET_NML_LIBRARY
  *NML$SET_AUTOSUBS       *NML$SET_STOP
2 GET_CHAR
       This is the input and preprocessor routine.  Originally it did
  only steps 1-3,7,8,10 below, but Frederick K.  Knight added his
  features mostly within NML$GET_CHAR.  Hence, the name GET_CHAR is
  misleading.  Here is what it does, in the order of the routine.  <v>
  is a variable name, including subscripts, eg, A,A(*),A(1,2,3).
  1.  Prompts user.
  2.  Accepts input line.
  3.  Echos input line to echo unit.
  4.  Strips comments and leading blanks and tabs.
  5.  Checks for leading # or h or $ or % and processes these options
      immediately.
  6.  Adds =?  to <v> alone on a line.
  7.  Adds ?  to <v>= or to =.
  8.  Loads character buffer with next character to process.
  9.  Translates character to upper case if outside a string.
 10.  If output character is the nml_char, processes nml_option &
      strips nml_option string.
 11.  Passes character buffer to NML$GET_STR.

2 SET_AUTOSUBS
       The calls
                         CALL NML$SET_AUTOSUBS(.TRUE.)
                         CALL NML$SET_AUTOSUBS(.FALSE.)
  determine whether the subcript sequence (*) is used by namelist.
  This is described in the help topic subscripts.
