.PS58,65
.LM5
.C
^&JCF NAMELIST INPUT FOR VAX FORTRAN IV-PLUS\&
.b2;.LM 5
1.##^&INTRODUCTION\&
.p6,1
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. A typical line of namelist
input might look like:
.B;.LM5;.LIT
ENTER VALUES: A(3)=5., NEW=.TRUE., TITLE= 'RESPONSE'
ENTER VALUES: CMPLX__VAL=(3,4)_&
.ELI;.P6,1;.LM 5
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.
.P6,1
The JCF 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. This document describes the grammar and syntax of
input lines, and the incorporation of namelists into user programs.
.B3;.PG
2.#^&DATA ENTRY THROUGH THE JCF NAMELIST:\&
.p0,1
2.1##^&THE NAMELIST INPUT LINE\&
########In interactive mode, an input line takes the form of:
.B
.lit
#######prompt: var = val list, var = val list,....._&
.eli
.B;.LM23;.I-18
where ^&prompt\&....is a user supplied prompting message
printed at the terminal to indicate that the system is awaiting input.
.B;.I-18
######^&var\&.......is a variable name, array element, or an array name
.B;.I-18
######^&val list\&..is a set of one or more numerical, logical, or character data values
to be entered into the variable or array.
.B;.I-18
######^&_&\&.........is  the namelist terminator, specifying that there are
no more variables to be entered. Each NAMELIST input must be ended
with a terminator.
.B;.LM 5
########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.
.B2;
^&Examples of equivalent namelist input formats:\&
.B;.LM9
^&System Parameters:\&##A=10.,CVAL=1E36,I=13._& 
.B;.I-3
or#^&System Parameters:\& I=13
.B
^&System  Parameters:\& CVAL=1E36,   
.B
^&System Parameters:\& A=10.3   
.B
^&System Parameters:\& _&
.B;.LM 5
Note:  the values may be  entered in any order.
.B3
2.2##^&DATA TYPES SUPPORTED:\&
The JCF NAMELIST supports LOGICAL*1, LOGICAL*2, LOGICAL*4, 
INTEGER*2, INTEGER*4, REAL*4, REAL*8, COMPLEX and CHARACTER data 
types. The syntax of data items in the input line should be:
.B2;.LM23;.I-18;.tp5
^&Logical Data\&######The following are recognized:
.B
#####.TRUE.####.T.####T
.B
#####.FALSE.###.F.####F
.B;.I-18
^&Numeric Data\&######Numeric data is interpreted as a double 
precision number and is converted to the appropriate mode. (The
equivalent format field specification ic D<NCHAR>.0, where NCHAR
is the length of the input string).
.B;.I-18
^&Complex Data\&######Must be entered in the form: 
.B;.I16
(real, imag)
.B;.LM 5;.LM23
where real and imag are valid numerical quantities. The real and
imaginary parts must be seperated by a comma, e.g., (3.,4) or
(IE-2,17.36).
.B;.I-18
^&Character Data\&####A valid character string enclosed in 
apostrophes, for example: 
.B;.I16
'THIS IS VALID'
.B;.LM 5;.LM23
If the string itself
includes an apostrophe, that apostrophe must appear as a pair of
apostrophes, for example: 
.B;.I16
'ISN''T THIS FUN?'
.B;.LM 5;.LM23
is the input
specification for the character item: 
.B;.I16
ISN'T THIS FUN?
.B;.LM 5
2.3##^&ENTERING DATA INTO 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). The following are valid namelist input lines for the 
array 
Ydimensional(2,2):
.B
####^&ENTER VALUES:\& Y(1,1)=38., Y(2,2)=0_& 
.B
####^&ENTER VALUES:\& Y = 1.,2.,3.,4_&
.B
####^&ENTER VALUES:\& Y(2,1)=-3,-4_&
.p6,2;.LM 5
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(2,2) = -4.
.P6,1
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. For example, if A is dimensioned
A(100) the input line
.B
####^&ENTER VALUES:\& A=50*10, 50*-10_&
.B
will set the first 50 elements of A to the value 10, and the second 50 to the value -10.
.P6,1
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.
.B2
3.0##^&INTERROGATING THE STATE OF THE NAMELIST\&
.B
###VAX NAMELIST allows the user to inquire as to
.B
.LM8;.I-3
1) the names and description of variables in the current namelist
.B;.I-3
2) the current value of any item (variable or array) in the namelist
.B;.I-3
3) the current value of all items in the namelist
.LM 5;.B2
3.1##^&THE ? COMMAND:\&
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.
.B;.LM8;.I-2;.TP5
ENTER VALUES: ? <CR>
.B
ALPHA(50)#####[REAL*4]
.B
LOGVAL(10)####[LOGICAL*2]
.B
BRAVO#########[REAL*8]
.B
CHARLIE#######[INTEGER*4]
.B
PROG__NAME#####[CHARACTER*40]
.B
.I-2
ENTER VALUES:
.B;.LM 5
3.2##^&THE VAR NAME = ? COMMAND:\&
The current value of an individual namelist variable, or a whole 
array may be interrogated by entering a "var name = ?" in the
input stream
.B
.lit
##ENTER VALUES: ALPHA=3,4;5,10*-15,BRAVO=33.,CHARLIE=? <CR>
.eli
.b
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.
.P6,1
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).
.B2
3.3##^&THE =? COMMAND:\&
The current value of all variables in the namelist may be typed 
by simply issuing the command =?, for example
.B
##ENTER VALUES: A=0.1,2,3,=? <CR>
.B
will set three new values into A and then type out the value of all
namelist items.
.B2
4###^&ERROR MESSAGES\&
.P6,1
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:
.B
##ENTER VALUES: A=3,4,5,10*0,B=3,C45.6,D=13,E=-12_&
.B
contains an error in that the entry for C does not have an = between the 
name and the value.
The message 
.B
#########NAMELIST ERROR : INVALID INPUT : NO'=' GIVEN
.B
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.
.B2
5###^&USING THE VAX NAMELIST SUBROUTINES:\&
.B
5.1##^&AN OVERVIEW OF THE IMPLEMENTATION:\& (May be skipped by the
casual user)
The NAMELIST feature is designed around the fact that the VAX Fortran
IV - Plus 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.
.P6,1
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.
.B
5.2##^&INCORPORATING NAMELIST INTO A PROGRAM:\&
The program (or subprogram) that uses JCF VAX Namelist must declare
and initialize the two arrays used by the subroutine NAMELIST. 
Consider, for example, a simple namelist containing 5 entries:
.B
##^&Step 1:\&###Declare a CHARACTER*15 array to contain the names
and an INTEGER*4 array to contain the descriptor block addresses.
.B;.LM12
PARAMETER NUM=5
.BR
CHARACTER*15 NAMES(NUM)
.BR
INTEGER*4 IDESC(NUM)
.B;.LM 5
##^&Step 2:\&###Initialize the character array with the names.
.B
####a) Using a DATA statement, for example
.B;.LM12
DATA NAMES/'ALPHA','BETA','GAMMA','DELTA'/
.B;.LM 5
or###b) Using the subroutine NML$NAME__SET
.B;.LM12
CALL NML$NAME__SET(names, string)
.B;.LM 5;.LM19;.I-14
where names...is the CHARACTER*15 array to receive the names
.B;.I-8
string..is a character string (constant or variable) containing the
list of names separated by commas.
.B;.LM 5
For example:
.P6,1
CALL NML$NAME__SET(NAMES,'ALPHA,BETA,GAMMA,DELTA')
.B
The subroutine will parse the string, using commas as delimiters and
enter the names into the array.
.B
##^&Step 3:\&###Initialize the descriptor address array by calling
the subroutine NML$DES__STUF
.B
######CALL NML$DES__STUF(array,%DESCR(name1),
.BR
#####*###########%DESCR(name2),...)
.B
where array........is the INTEGER*4 array
.BR
######name1,etc....are the names of the variables
.B
For example:
.B
####CALL NML$DES__STUF(IDESC,%DESCR(ALPHA),%DESCR(BETA),
.br
###*####%DESCR(GAMMA),%DESCR(DELTA),%DESCR(EPSILON))
.B
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.
.B
##^&Step 4:\&###After the above initialization, Namelist input may
be invoked by calling the subroutine NAMELIST:
.B
####CALL#NAMELIST(promptstring,names,desc,number,
.BR
###*##############indev,echodev,promptdev).
.B;.LM27;.I-22
where promptstring....is a character sring to be written on logical
unit promptdev as a user prompt.
.B;.I-16
names...........is the CHARACTER*15 array containing the names of
entities in the namelist.
.B;.I-16
desc............is the INTEGER*4 array containing the descriptor 
block pointers as initialized by NML$DES__STUF.
.B;.I-16
number..........is the number of items in the namelist.
.b;.I-16
indev...........is the logical unit number for the namelist input.
.B;.I-16
echodev.........is the logical unit onto which the input string 
and prompt will be echoed. Ths is useful for recording the namelist
dialog.
.B;.I-16
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.
.B;.LM 5
In the above example, the call would be
.B
####CALL NAMELIST('TYPE VALUES:',NAMES,IDESC,5,95,96,95)
.B2
5.3##^&A SAMPLE PROGRAM\&
The example below shows a very simple program to demonstrate the use of 
JCF VAX Namelist. A sample terminal session to demonstrate some
of the features has also been included.