.nj
.nfl
.ps 2000,80
.lm 2
.rm 70
.SET para 5 0
.i -2
1 help
.blank
.c;*  *  *  *  *  *     N  A  M  E  L  I  S  T     *  *  *  *  *  *  
.c;originally written by Derek Rowell and Douglass Wilson
.c;Joint Computing Facility at MIT       
.blank
.c;augmented by Frederick K. Knight
.c;to be a versatile formated I/O package for VAX Fortran programs
.c;at the Naval Research Laboratory (NRL)
.c;and the Smithsonian Astrophysical Observatory (SAO)
.blank
.p
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.
.i -2
2 What_next
.p
If you are not familiar with the JCF namelist, you could
.list
.le
Print or read NML$DIR:NML.DOC.
.le
Read introduction, data entry, interrogation, error messages 
and usage, in that order, in this help file.
.end list
.p
If you are familiar with JCF namelist, then read modifications and
examples in this help file.
.i -2
2 Topics
.p
The topics in this help file are the following:
.nf
.rm 80
.blank
	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
.f
.rm 70
.i -2
1 Introduction
.p
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.
.p
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.
.i -2
2 example
.p
A
typical line of namelist input might look like:
.blank
.nf
     ENTER VALUES: A(3)=5., NEW=.TRUE., TITLE= 'RESPONSE'
     ENTER VALUES: CMPLX_VAL=(3,4)&
.f
.blank
.p
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.
.i -2
2 Implementation
.p
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.
.i -2
1 data_entry
.p
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.
.i -2
2 input_line
.p
The input line takes the form of:
.blank
.nf
.rm 80
            prompt: var = val list, var = val list,.....&
.blank
     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.
.f
.rm 70
.p
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.
.i -2
2 examples
.p
The following are equivalent:
.nf
.blank
         System Parameters:  A=10.,CVAL=1E36,I=13.& 
.blank
      or System Parameters:  I=13
         System Parameters:  CVAL=1E36, 
         System Parameters:  A=10.3 
         System Parameters:  &
.blank
     Note:  the values may be entered in any order.
.f
.i -2
2 types
.p
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.
.i -2
3 logical
.p
Namelist recognizes the following:
.blank.i +5
t   .true.   .t.   .TRUE.    .T.    T
.i +5
f   .false.   .f.   .FALSE.   .F.    F
.blank
Any mixture of upper and lower case is allowed.
.i -2
3 numeric
.p
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.
.i -2
3 complex
.p
Each complex number must be entered in the form:  
.blank.i +5
(real, imag)
.blank
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).
.i -2
3 character
.p
A  valid  character  string or substring
is enclosed  in  apostrophes, for example:  
.blank.i +5
'THIS IS VALID'
.blank
If   the   string   itself   includes   an
apostrophe, that apostrophe must appear as
a pair of apostrophes, for example:  
.blank.i +5
'ISN''T THIS FUN?'
.blank
is  the  input   specification   for   the
character item:  
.blank.i +5
ISN'T THIS FUN?
.blank
The enclosing quotes are unnecessary unless 
the string contains any of the following
characters:
.blank.i +5
<space> = ? * , & \ ' ! ; % # $
.blank
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.
.f
.rm 70
.i -2
2 arrays
.p
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).  
.p
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.
.p
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.
.i -2
3 example
.p
The following are
valid namelist input lines for the array Y dimensioned (2,2):
.blank.lm +5.lit
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&
.end lit.blank.lm -5
.p
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.
.i -2
1 examples
.p
Here, v and w are variables, simple or array, of any fortran data
type.  The examples are divided into categories as subtopics.
.i -2
2 BASIC
.rm 80.lm +1.lit
; 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.
.end lit.lm -1
.i -2
2 HELP
.lm +1.lit
h topic        ; Asks for help on topic from current help library.
\h topic       ; Asks for special nml help.
.end lit.lm -1
.i -2
2 ADVANCED
.lm +1.lit
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".
.end lit.lm -1
.i -2
2 INTERROGATION & DESCRIPTION
.lm +1.lit
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 ?
.end lit.lm -1
.i -2
2 SPECIAL
.lm +1.lit
\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.
.end lit.lm -1.rm 70.f
.i -2
1 interrogation
.p
VAX namelist allows the user to inquire as to
.blank
.list 0
.le
the names and description of  variables  in  the  current
namelist  -  using "?"
.le
the current value of any item (variable or array) in  the
namelist  -  using "item" or "item=" or "item=?"
.le
the current value of all items in the namelist  -  using 
"=" or "=?"
.end list
.i -2
2 QUESTION_MARK
.p
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.
.blank.lit

      ENTER VALUES:  ?  <CR>

        ALPHA(50)     [REAL*4]
        LOGVAL(10)    [LOGICAL*2]
        BRAVO         [REAL*8]
        CHARLIE       [INTEGER*4]
        PROG_NAME     [CHARACTER*40]
.end lit.blank
.p
In addition descriptions of variables can be added
using the "%" option in setup files (cf % and logical names NML$SETUP).
.i -2
2 item,item=,item=QUESTION_MARK
.p
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,
.blank.i +5
ENTER VALUES: ALPHA=3,4;5,10*-15,BRAVO=33.,CHARLIE=? <CR>
.blank
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.
.p
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).
.i -2
2 =QUESTION_MARK
.p
The current value of all variables in
the  namelist may be typed by simply issuing the command =? or =.
For example,
.blank.i +5
ENTER VALUES:  A=0.1,2,3,=?  <CR>
.blank
will set three new values into A and then type out the values
of all namelist items.
.p
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 #).
.i -2
1 nml_options
.p
Here is a list of the internal namelist variables accessed
through the nml character (shown here as \).
.lm 1
.rm 80
.nf
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>
.lm 2
.rm 70
.f
.i -2
2 prompt
.nf
	FORMAT: \prompt='new prompt'
.f
.blank
.p
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=' '".
.i -2
2 instat
.nf
	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')
.f
.blank
.p
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".
.i -2
2 promptstat
.nf
	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')
.f
.blank
.p
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".
.i -2
2 echostat
.nf
	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')
.f
.blank
.p
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".
.i -2
2 outstat
.nf
	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')
.f
.blank
.p
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".
.i -2
2 examples
.list 0
.le
The end character can be changed from its default value of "&" to any
new end_char by typing "\end_char=<new end_char>".
.le
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.
.le
Typing "\promptfile=nl:"  or "\prompt=' '" eliminates
the prompt.
.le
Typing "\outfile=output.dat" allows writing current
values to "output.dat" with subsequent listing requests, for example,
typing "=?" or "var_name".
.end list
.i -2
2 end_char
.nf
	FORMAT: \end_char=<single char> (D=&)
.f
.blank
.p
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>".
.i -2
2 nml_char
.nf
	FORMAT: \nml_char=<single char> (D=&)
.f
.blank
.p
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.
.i -2
2 on_eof
.nf
	FORMAT: \on_eof=continue (D)
		\on_eof=stop
		\on_eof=return
	or    :	CALL NML$SET_ON_EOF('option')
.f
.blank
.p
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.
.i -2
2 library
.nf
	FORMAT: \library=<filespec> (D=SYS$HELP:HELPLIB.HLB)
	        \help_library=<filespec>
	or    :	CALL NML$SET_LIBRARY('<file spec>')
.f
.blank
.p
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
.nf.i +5
\LIBRARY=<filespec>
or
.i +5
\HELP_LIBRARY=<filespec>
.f
No blanks can be embedded in the <filespec>.
.i -2
2 infile
.nf
	FORMAT: \infile=<file spec> (D=calling value)
.f
.blank
.p
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".
.i -2
2 promptfile
.nf
	FORMAT: \promptfile=<file spec> (D=calling value)
.f
.blank
.p
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".
.i -2
2 echofile
.nf
	FORMAT: \echofile=<file spec> (D=calling value)
.f
.blank
.p
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.
.p
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".
.p
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
.blank.lm +5.lit
\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.
.end lit.lm -5
.i -2
2 outfile
.nf
	FORMAT: \outfile=<file spec> (D=promptfile)
.f
.blank
.p
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".
.i -2
2 nml_library
.nf
	FORMAT: \nml_library=<file spec> (D=NML$HELP)
	or    :	CALL NML$SET_NML_LIBRARY('<file spec>')
.f
.blank
.p
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
.i +5
\NML_LIBRARY=<filespec>.
.br
No blanks can be embedded in the <filespec>.
.i -2
2 stop
.nf
	FORMAT: \stop='string' (D=stop)
	or    :	CALL NML$SET_STOP('string')
.f
.blank
.p
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')".
.i -2
1 Summary
.p
Typical inputs are the following.  v and w are variables or arrays.
.ts 25
.nf
.rm 80
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
.lm 2
.rm 70
.f
.i -2
1 usage
.i -2
2 overview
.p
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.
.p
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.
.i -2
2 linking
.p
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
.blank.i +5
LINK ...,NML$LIB/LIB
.blank
where ... stands for all the other object modules needed by the program.
.i -2
2 calling
.p
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.
.i -2
3 1_Step
.p
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:
.lit

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

.end lit
.p
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).
.i -2
3 2_Step
.p
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,
.lit

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

.end lit
.p
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.
.i -2
3 3_Step
.p
Third, the calling program must initialize  
the  descriptor  address  array  by
calling the subroutine NML$DES_STUF
.lit

     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))

.end lit
.p
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.
.i -2
3 4_Step
.p
After the above initialization,  namelist  input
may be invoked by calling the subroutine NAMELIST:
.lm +5
.blank
CALL NAMELIST(prompt,names,desc,num,indev,echodev,promptdev).
.lm -5
where
.lm +20
.i -15
prompt........is a character sring to be written  on
logical   unit  promptdev  as  a  user prompt.
.i -15
names.........is the CHARACTER*(*)  array containing
the names of entities in the namelist.
.i -15
desc..........is the INTEGER*4 array containing  the
descriptor     block    pointers    as
initialized by NML$DES_STUF.
.i -15
number........is  the  number  of   items   in   the namelist.
.i -15
indev.........is the logical  unit  number  for  the
namelist input.
.i -15
echodev.......is the logical  unit  onto  which  the
prompt, input, and error messages  are
echoed.  This is useful for  recording
the namelist dialog.
.i -15
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.
.lm -20
.i -2
4 example
.p
In the above example, the call might be
.lit

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

.end lit
where 95 and 96 have been opened to the desired units.
.i -2
4 devices
.p
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.
.i -2
3 Options
.p
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.
.blank.list
.le
CALL NML$SET_OPEN_STAT(N,'STATUS_NAME')
.LE
CALL NML$SET_ON_EOF('OPTION')
.LE
CALL NML$SET_LIBRARY('LIBRARY_NAME')
.LE
CALL NML$SET_NML_LIBRARY('LIBRARY_NAME')
.LE
CALL NML$SET_STOP('STRING')
.LE
CALL NML$SET_AUTOSUBS(.TRUE.)
.END LIST
.i -2
1 logical_names
.p
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.
.i -2
2 NML$DIR
.p
This directory contains all the files associated with namelist, namely
.blank.lit
     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."
.end lit
r.i -2
3 making_changes
.p
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.
.p
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.
.i -2
2 NML$HELP
.p
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).
.i -2
2 NML$SETUP
.p
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 "%".
.p
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.  
.i -2
2 example
.p
Here is an
example: the file called SETUP.NML contains
.blank.rm 80.lit
     \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
.end lit.rm 70
.i -2
2 assigning NML$SETUP
.p
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
.blank.lit
     INTEGER*4 SYS$CRELOG,ISTAT
     ...
     ISTAT=SYS$CRELOG(%VAL(2),'NML$SETUP','SETUP.NML',)
     CALL NAMELIST('PROMPT:'...
.end lit
.blank
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.
.i -2
1 errors
.p
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:
.blank.i +5
ENTER VALUES:  A=3,4,5,10*0,B=3,C45.6,D=13,E=-12&
.blank
contains an error in that the entry for C does not have an =
between the name and the value.  The message 
.blank.i +5
NAMELIST ERROR :  INVALID INPUT :  NO'=' GIVEN
.blank
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.
.i -2
1 $
.p
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.
.p
There are restrictions. For example,
the current directory cannot be changed with SET DEFAULT.
.i -2
1 per_cent
.p
% 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
.blank.lit
     %variable description
.end lit.blank
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.
.i -2
2 example
.p
For example, if
.blank.lit
     %x array of independent variables
.end lit.blank
appeared in the file assigned to NML$SETUP and x(100) is a real*4 array,
then the output of the ? command would contain
.blank.lit
     X(100)       [REAL*4] array of independent variables
.end lit.blank
.i -2
1 #
.p
# 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.
.i -2
2 format
.p
The format of the line is
.blank.lit
     #variable=value ;comment to serve as prompt
.end lit.blank
and forces namelist to print
.blank.lit
     comment to serve as a prompt: variable=value
.end lit.blank
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
.blank.lit
     Confirm w/ CR or give new value & CR:variable=value
.end lit
.i -2
2 examples
.literal 
     #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
.end literal
.i -2
1 subscripts
.p
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.
.p
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.).
.i -2
2 examples
.p
For example, this
.blank.lit
     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  .
.end lit.blank
.p
A specific use is to read values separately and allow
them to be in any order, eg data from different experiments.
For example,
.blank.lit
     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  .
.end lit.blank
But in the second case, the lines could be interchanged without
changing the subscripts.
.i -2
2 usage
.p
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".
.i -2
1 Modifications
.p
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.
.list 0
.le
ALLOW HELP FILES WITH THE RESERVED CHARACTER H OR h 
(nml_options help_library).
.le
ALLOW =? ON A VARIABLE BY SIMPLY TYPING THE VARIABLE NAME -
ALONE ON A LINE (interrogation).
.le
ALLOW COMMENTS EITHER ON ENTIRE LINE OR AT END OF INPUT LINE
USING EITHER ; OR !
.le
ALLOW NO PROMPT BY EITHER GIVING A BLANK PROMPT STRING
OR PLACING AN ASCII NULL AT THE START OF THE STRING.
(nml_options prompt).
.le
ALLOW OMISSION OF TRAILING QUOTE FOR LAST VARIABLE ON LINE.
.le
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).
.le
ALLOW 3 OPTIONS IF AN EOF IS READ: STOP, RETURN OR CONTINUE
(nml_options on_eof).
.le
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.
.le
ALLOW SEQUENCES FOLLOWING A SPECIAL CHARACTER, THE
NML-CHARACTER WHOSE DEFAULT VALUE IS BACK SLASH, "\"
(nml_options).
.le
ALLOW LEADING BLANKS OR TABS ON ANY LINE, INCLUDING A 
CONTINUATION, WITHOUT ANY EFFECT ON THE INPUT.
.le
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).
.le
MODIFY THE OUTPUT FORMAT TO BE LESS VERBOSE AND HAVE A FORM
COMPATIBLE WITH SUBSEQUENT NAMELIST INPUT.  THIS
MODIFICATION COULD USE FURTHER WORK.
.le
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).
.le
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.
.le
ALLOW ACCESS TO DCL COMMANDS VIA THE RESERVED CHARACTER $ IN
THE FIRST NON-BLANK CHARACTER ($).
.le
MAKE THE SEQUENCE "VAR(*)" MEAN 'PRINT THE CURRENT VALUE OF
THE ELEMENT OF V TO BE CHANGED BY THE SEQUENCE
"V(*)=<value>"' (subscripts).
.le
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).
.le
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).
.le
Allow user initialization by assigning the logical name NML$SETUP to
any file containing namelist input (logical_names NML$SETUP).
.le
Define one more logical unit for writing namelist-readable output
(D=echofile; nml_options outfile)
.le
Reserve another special character, #, to enable special prompts for
setting individual variables, for example, at the start of a program.
(#)
.le
Reserve another special character, %, to supply descriptions of
individual variables in the NML$SETUP file. (% and logical_names NML$SETUP)
.le
Allow input of substrings with bounds checking as well as output of
substrings by typing the variable name and the substring range.
.end list
.i -2
1 future
.p
Frederick K. Knight would like to make the following changes in
namelist.
.list 0
.le
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.
.le
ALLOW LISTING OF PARTS OF ARRAYS.
.le
ALLOW CONTROL C INTERRUPTS TO DO VARIOUS THINGS LIKE CONTROL Z.
.end list
.i -2
1 subroutines
.p
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.
.rm 80
.nf
*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
.rm 70
.f
.i -2
2 GET_CHAR
.p
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).
.list 0
.le
Prompts user.
.le
Accepts input line.
.le
Echos input line to echo unit.
.le
Strips comments and leading blanks and tabs.
.le
Checks for leading # or h or $ or % and processes these options immediately.
.le
Adds =? to <v> alone on a line.
.le
Adds  ? to <v>= or to =.
.le
Loads character buffer with next character to process.
.le
Translates character to upper case if outside a string.
.le
If output character is the nml_char, 
processes nml_option & strips nml_option string.
.le
Passes character buffer to NML$GET_STR.
.end list
.i -2
2 SET_AUTOSUBS
.p
The calls
.nf
	CALL NML$SET_AUTOSUBS(.TRUE.)
	CALL NML$SET_AUTOSUBS(.FALSE.)
.f
determine whether the subcript sequence (*) is used by namelist.
This is described in the help topic subscripts.