Rules for Namelist Sequential READ Statements

Developer Guide and Reference

Download PDF

ID 767251

Date 10/31/2024

Version

Public

Visible to Intel only — GUID: GUID-00A22D3B-39F4-46A6-8A6F-BF484EFE19CB

View Details

Rules for Namelist Sequential READ Statements

Namelist, sequential READ statements translate data from external to internal form by using the data types of the objects in the corresponding NAMELIST statement to determine the form of the data. The translated data is assigned to objects in the namelist group by specifying the name of the object to which the data is to be assigned.

The order of the object name and data pairs in the input records need not match the order of the objects in the namelist var-list. The input need not specify all objects in the namelist var-list. They may specify a part of an object more than once. Namelist group names and object names are case insensitive.

If a slash ( / ) is encountered during execution, the READ statement is terminated, and any remaining input list items are unchanged. An ampersand (&) encountered during input is treated the same as a slash (/).

If the file is connected for unformatted I/O, namelist data transfer is prohibited.

Namelist Records

A namelist external record takes the following form:

&group-name object = value [{, | ;} object = value] .../

group-name

Is the name of the group containing the objects to be given values. The name must have been previously defined in a NAMELIST statement in the scoping unit. The name cannot contain embedded blanks and must be contained within a single record.

object

Is the name (or subobject designator) of an entity defined in the NAMELIST declaration of the group name. The object name must not contain embedded blanks except within the parentheses of a subscript or substring specifier. Each object must be contained in a single record.

value

Is any of the following:

A constant

Each constant must be a literal constant of type integer, real, complex, logical, or character; or a delimited or nondelimited character string. Binary, octal, hexadecimal, Hollerith, and named constants are not permitted.

In general, the form of the constant must be acceptable for the type of the list item. The data type of the constant determines the data type of the value and the translation from external to internal form. The following rules also apply:
- A numeric list item can correspond only to a numeric constant, and a character list item can correspond only to a character constant. If the data types of a numeric list element and its corresponding numeric constant do not match, conversion is performed according to the rules for arithmetic assignment (see the table in Numeric Assignment Statements). Logical list items and logical constants are not considered numeric, unless the compiler option assume old_logical_ldio is specified. The decimal point in a numeric constant can either be a period if DECIMAL='POINT' or a comma if DECIMAL='COMMA'.
- A complex constant has the form of a pair of real or integer constants separated by a comma if DECIMAL='POINT' or a semicolon if DECIMAL='COMMA' and enclosed in parentheses. Blanks can appear between the opening parenthesis and the first constant, before and after the separating comma or semicolon, and between the second constant and the closing parenthesis.
- A logical constant represents true values (.TRUE. or any value beginning with T, .T, t, or .t) or false values (.FALSE. or any value beginning with F, .F, f, or .f).
Normally, a character string in a NAMELIST statement must be delimited to be read. A delimited string is denoted by apostrophes (DELIM=APOSTROPHE), or quotes (DELIM=QUOTE).

Intel® Fortran also allows setting DELIM=NONE, which is the default for both input and output. In this case, non-delimited strings are allowed under certain circumstances.

A character string does not need delimiting apostrophes or quotation marks if the corresponding NAMELIST item is of type default character and it complies with the following rules:
- The character string cannot contain a blank, tab, equal sign (=), dollar sign ($), slash ( / ), new line, ampersand (&), or exclamation point(!). A nondelimited character string is terminated if one of these is encountered.
- Normally, a comma will also cause termination of the nondelimited character string. However, if DECIMAL=COMMA is specified, then the character string cannot contain semicolons but it can contain commas. In this case, if a semicolon is encountered the nondelimited character string is terminated.
A null value

A null value is specified by two consecutive value separators (such as two adjacent commas ",,") or a nonblank initial value separator. (A value separator before the end of the record does not signify a null value.)

A null value indicates that the corresponding list element remains unchanged. A null value can represent an entire complex constant, but cannot be used for either part of a complex constant.
A repetition of a null value (r*) or a constant (r*constant), where r is an unsigned, nonzero, integer literal constant with no kind parameter, and no embedded blanks.

Blanks can precede or follow the beginning ampersand (&), follow the group name, precede or follow the equal sign, or precede the terminating slash.

Comments (beginning with ! only) can appear anywhere in namelist input. The comment extends to the end of the source line.

If an entity appears more than once within the input record for a namelist data transfer, the last value is the one that is used.

If there is more than one object = value pair, they must be separated by value separators.

A value separator is any number of blanks, a slash, or a comma if DECIMAL='POINT' or a semicolon if DECIMAL='COMMA', preceded or followed by any number of blanks. When any of these appear in a character constant, they are considered part of the character constant, not value separators.

The end of a record is equivalent to a blank character, except when it occurs in a character constant. In this case, the end of the record is ignored, and the character constant is continued with the next record (the last character in the previous record is immediately followed by the first character of the next record).

Blanks at the beginning of a record are ignored unless they are part of a character constant continued from the previous record. In this case, the blanks at the beginning of the record are considered part of the constant.

When the name in the input record is an array variable or a variable of derived type, the effect is as if the variable represented were expanded into a sequence of scalar list items of intrinsic data types. Each input value following the equal sign must comply with format specifications for the intrinsic type of the list item in the corresponding position in the expanded sequence.

The number of values following the equal sign must be equal to or less than the number of list items in the expanded sequence. In the latter case (less than), the effect is as if null values have been added to match any remaining list items in the expanded sequence.

The string length in the NAMELIST statement is not checked against the size of the CHARACTER variable to which it will be assigned. This means that an array of n elements written in a NAMELIST statement with DELIM=NONE may not be read back as n values. For example, consider a three-element array ARR of three-character elements with values "ABC","DEF","GHI". In DELIM=NONE form, it prints to the data file as follows:

ARR = ABCDEFGHI

If your program reads that data file, the value will be interpreted as one non-delimited string with the value "ABCDEFGHI" because termination is caused by the trailing blank, tab, or new line.

In some cases, values can be read as more than one string; for example, if the values themselves have final or internal blanks, tabs, or new lines. Consider that ARR contains strings "WX ","Y\tR", "S\nQ", where "\t" is a tab character and "\n" is a newline character. In this case, the data file contains:

ARR = WX Y\tRS\nQ

The NAMELIST processing will interpret this as four non-delimited strings: "WX", "Y", "RS" and "Q".

NOTE:

In NAMELIST declarations, you may get unexpected results if all of the following are true:

DELIM=NONE is in effect on input.
A character variable is followed by another variable.
The other variable is either an array variable that is subscripted or a string variable that is a substring.
That subscript or substring expression contains blanks.

In Intel® Fortran, a list of values may follow the equal sign when the object is a single array element. In this case, values are assigned to the specified array element and subsequent elements, in element sequence order. For example, suppose the following input is read:

&ELEM
ARRAY_A(3)=34.54, 45.34, 87.63, 3*20.00
/

New values are assigned only to array ARRAY_A elements 3 through 8. The other element values are unchanged.

Prompting for Namelist Group Information

During execution of a program containing a namelist READ statement, you can specify a question mark character (?) or a question mark character preceded by an equal sign (=?) to get information about the namelist group. The ? or =? must follow one or more blanks.

If specified for a unit capable of both input and output, the ? causes display of the group name and the objects in that group. The =? causes display of the group name, objects within that group, and the current values for those objects (in namelist output form). If specified for another type of unit, the symbols are ignored.

For example, consider the following statements:


  NAMELIST /NLIST/ A,B,C
  REAL                :: A = 1.5
  INTEGER             :: B = 2
  CHARACTER(LEN=5)    :: C 'ABCDE'
  READ (5,NML=NLIST)
  WRITE (6,NML=NLIST)
  END

During execution, if a blank followed by ? is entered on a terminal device, the following values are displayed:

  &NLIST
     A
     B
     C
  /

If a blank followed by =? is entered, the following values are displayed:

  &NLIST
      A  =   1.500000,
      B  =           2,
      C  = ABCDE
  /

Examples

Suppose the following statements are specified:


  NAMELIST /CONTROL/ TITLE, RESET, START, STOP, INTERVAL
  CHARACTER*10 TITLE
  REAL(KIND=8) START, STOP
  LOGICAL(KIND=4) RESET
  INTEGER(KIND=4) INTERVAL
  READ (UNIT=1, NML=CONTROL)

The NAMELIST statement associates the group name CONTROL with a list of five objects. The corresponding READ statement reads the following input data from unit 1:

  &CONTROL
         TITLE='TESTT002AA',
         INTERVAL=1,
         RESET=.TRUE.,
         START=10.2,
         STOP =14.5
 /

The following values are assigned to objects in group CONTROL:

Namelist Object	Value Assigned
TITLE	TESTT002AA
RESET	T
START	10.2
STOP	14.5
INTERVAL	1

It is not necessary to assign values to all of the objects declared in the corresponding NAMELIST group. If a namelist object does not appear in the input statement, its value (if any) is unchanged.

Similarly, when character substrings and array elements are specified, only the values of the specified variable substrings and array elements are changed. For example, suppose the following input is read:

&CONTROL TITLE(9:10)='BB' /

The new value for TITLE is TESTT002BB; only the last two characters in the variable change.

The following example shows an array as an object:


  DIMENSION ARRAY_A(20)
  NAMELIST /ELEM/ ARRAY_A
  READ (UNIT=1,NML=ELEM)

Suppose the following input is read:

&ELEM
ARRAY_A=1.1, 1.2,, 1.4
/

The following values are assigned to the ARRAY_A elements:

Array Element	Value Assigned
ARRAY_A(1)	1.1
ARRAY_A(2)	1.2
ARRAY_A(3)	Unchanged
ARRAY_A(4)	1.4
ARRAY_A(5)...ARRAY(20)	Unchanged

Nondelimited character strings that are written out by using a NAMELIST write may not be read in as expected by a corresponding NAMELIST read. Consider the following:

NAMELIST/TEST/ CHARR
CHARACTER*3 CHARR(4)
DATA CHARR/'AAA', 'BBB', 'CCC', 'DDD'/
OPEN (UNIT=1, FILE='NMLTEST.DAT')
WRITE (1, NML=TEST)
END

The output file NMLTEST.DAT will contain:

&TEST CHARR   = AAABBBCCCDDD/

If an attempt is then made to read the data in NMLTEST.DAT with a NAMELIST read using nondelimited character strings, as follows:

NAMELIST/TEST/ CHARR
CHARACTER*3 CHARR(4)
DATA CHARR/4*'   '/
OPEN (UNIT=1, FILE='NMLTEST.DAT')
READ (1, NML=TEST)
PRINT *, 'CHARR read in >', CHARR(1),'<  >',CHARR(2),'<  >',
1       CHARR(3), '<  >', CHARR(4), '<'
END

The result is the following:

CHARR read in >AAA<  >   <  >   <  >   <

The 12 characters of input were read, truncated to 3 characters, and stored in CHARR(1). The other 3 elements of CHARR were unchanged.

Parent topic: Forms for Sequential READ Statements

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Guide and Reference

Rules for Namelist Sequential READ Statements

Namelist Records

Prompting for Namelist Group Information

Examples

See Also