Namelist formatting

Namelist formatting allows you to use the NAME= specifier as part of the NAMELIST statement to assign a name to a collection of variables. This name represents the entire collection of variables for input and output. You can also use namelist formatting to include namelist comments with input, making the data more user accessible.

• In Fortran 90 and Fortran 95, you can only use namelist formatting with sequential access.
• The Fortran 2003 Standard allows you to use namelist formatting with sequential and stream access.
• The Fortran 2003 Standard allows you to use namelist formatting with internal files.

Namelist input

The form of namelist input is:

1. Optional blanks and namelist comments.
2. The ampersand character, followed immediately by the namelist group name specified in the NAMELIST statement.
3. One or more blanks.
4. A sequence of zero or more name-value subsequences, separated by value separators.
5. A slash to terminate the namelist input.

Blanks at the beginning of an input record that continues a delimited character constant are considered part of the constant.

If you specify the NAMELIST=OLD run-time option, the form of input for a NAMELIST statement is:

1. Optional blanks
2. An ampersand or dollar sign, followed immediately by the namelist group name specified in the NAMELIST statement.
3. One or more blanks.
4. A sequence of zero or more name-value subsequences separated by a single comma. You can insert a comma after the last name-value subsequence.
5. &END or $END to terminate the namelist input.

The first character of each input record must be a blank, including those records that continue a delimited character constant.

Namelist comments

In Fortran 95 and higher, you can use comments in namelists.

You must not specify comments in stream input.

If you specify the NAMELIST=NEW run-time option:

• If you specify an exclamation point after a value separator that is not a slash, or in the first non-blank position of a namelist input record, you initiate a comment. You can not initiate comments inside character literal constants.
• The comment extends to the end of the input record, and can contain any character in the XL Fortran character set.
• The comment is ignored.
• A slash within a namelist comment does not terminate execution of that namelist input statement.

If you specify the NAMELIST=OLD run-time option:

• If you specify an exclamation point after a single comma or in the first non-blank position of a namelist input record that is not the first character of that record, you initiate a comment. You must not initiate a namelist comment within a character literal constant.
• The comment extends to the end of the input record, and can contain any character in the XL Fortran character set.
• The comment is ignored.
• An &END or $END within a namelist comment does not terminate execution of the namelist input statement.

Name-value subsequence

The form of a name-value subsequence in an input record is:

>>-name-- = --constant_list------------------------------------><
 

name

is a variable

constant

has the following forms:

>>-+------+--literal_constant----------------------------------><
   '-r--*-'
 

r

is an unsigned, nonzero, scalar, integer literal constant specifying the number of times the literal_constant occurs. You must not specify a kind type parameter for r.

literal_constant

is a scalar literal constant of intrinsic type, or null value. You must not specify a kind type parameter for the constant. The constant evaluates with the same kind type parameter as the corresponding list item.

You must specify delimiting apostrophes or quotation marks if literal_constant is of type character.

You can specify T or F if literal_constant is of type logical.

Rules for namelist input

Any subscripts, strides, and substring range expressions that qualify name must be integer literal constants with no kind type parameter.

If name is not an array or an object of derived type, constant_list must contain a single constant.

Variable names you specify in the input file must appear in the variable_name_list of a NAMELIST statement. Variables can appear in any order.

If a name that you specify in an EQUIVALENCE statement shares storage with name, you must not substitute for that name in the variable_name_list.

You can use one or more optional blanks before or after name, but name must not contain embedded blanks.

In each name-value subsequence, the name must be the name of a namelist group item with an optional qualification. The name with the optional qualification must not be a:

• zero-sized array.
• zero-sized array section.
• zero-length character string.

If you specify the optional qualification, it must not contain a vector subscript.

If name is an array, array section without vector subscripts, or a structure, name expands where applicable into a sequence of scalar list items of intrinsic data type according to the rules outlined in Effective list items.

If name is an array or structure, the number of constants in constant_list must be less than or equal to the number of items specified by the expansion of name. If the number of constants is less than the number of items, the remaining items retain their former values.

You can specify a null value using:

• The r* form that indicates r successive appearances of the null value.
• Blanks between two consecutive value separators following an equal sign.
• Zero or more blanks preceding the first value separator and following an equal sign.
• Two consecutive non-blank value separators.

A null value has no effect on the definition status of the corresponding input list item. If the namelist group object list item is defined, it retains its previous value; if it is undefined, it remains undefined.

If decimal comma mode is in effect, a semicolon acts as a value separator instead of a comma.

You must not use a null value as the real or imaginary part of a complex constant. A single null value can represent an entire complex constant.

The end of a record following a value separator, with or without intervening blanks, does not specify a null value.

      INTEGER A(100)
      NAMELIST /FOO/ A
      READ (5, FOO)

 &FOO
 A(3) = 2, 10, 15, 16
 /

A slash appearing as a value separator terminates the input statement after assignment of the previous value. Any additional items in the namelist group object receive null values

Example of namelist input data

File NMLEXP contains the following data before execution of the READ statement.

Character position:

         1         2         3
1...+....0....+....0....+....0

File contents:

 &NAME1
 I=5,
 SMITH%P_AGE=27
 /

NMLEXP contains four data records. The program contains the following:

TYPE PERSON
  INTEGER P_AGE
  CHARACTER(20) P_NAME
END TYPE PERSON
TYPE(PERSON) SMITH
NAMELIST /NAME1/ I,J,K,SMITH
I=1
J=2
K=3
SMITH=PERSON(20,'John Smith')
OPEN(7,FILE='NMLEXP')
READ(7,NML=NAME1)
! Only the value of I and P_AGE in SMITH are
! altered (I = 5, SMITH%P_AGE = 27).
! J, K and P_NAME in SMITH remain the same.
END

Character position:

         1         2         3         4
1...+....0....+....0....+....0....+....0

File contents:

 &NAME1 I= 5, SMITH%P_AGE=40 /

An example of a NAMELIST comment when you specify NAMELIST=NEW. The comment appears after the value separator space.

&TODAY I=12345         ! This is a comment. /
X(1)=12345, X(3:4)=2*1.5, I=6,
P="!ISN'T_BOB'S", Z=(123,0)/

An example of a NAMELIST comment when you specify NAMELIST=OLD. The comment appears after the value separator space.

&TODAY I=12345,        ! This is a comment.
X(1)=12345, X(3:4)=2*1.5, I=6,
P="!ISN'T_BOB'S", Z=(123,0) &END

Namelist output

The WRITE statement outputs data from the variable_name_list in a NAMELIST statement according to data type. This data can be read using namelist input except for non-delimited character data.

You must not specify a single long character variable for namelist output.

Each output record that is not continuing a delimited character constant from a previous record begins with a blank character that provides carriage control.

The output data fields become large enough to contain all significant digits, as shown in the Width of a Written Field table.

The values of a complete array output in column-major order.

If the length of an array element is not sufficient to hold the data, you must specify an array with more than three elements.

A WRITE statement with a variable_name_list produces a minimum of three output records:

• One record containing the namelist name.
• One or more records containing the output data items.
• One record containing a slash to terminate output.

To output namelist data to an internal file, the file must be a character array containing at least three elements. If you use the WRITE statement to transfer data to an internal file, the character array can require more than three elements.

You can delimit character data using the DELIM= specifier on the OPEN or READ statements.

Namelist character output

The output of character constants can change depending on the DELIM= specifier on the OPEN or READ statements.

For character constants in a file opened without a DELIM= specifier, or with a DELIM=NONE:

• Values are non-delimited by apostrophes or quotation marks.
• Value separators do not occur between values.
• Each internal apostrophe or double quotation mark outputs as one apostrophe or quotation mark.
• XL Fortran inserts a blank character for carriage control at the beginning of any record that continues a character constant from the preceding record.

Nondelimited character data that has been written must not be read as character data.

Double quotation marks delimit character constants in a file opened with DELIM=QUOTE, with a value separator preceding and following each constant. Each internal quote outputs as two contiguous quotation marks.

Apostrophes delimit character constants in a file opened with DELIM=APOSTROPHE with a value separator preceding and following each constant. Each internal apostrophe outputs as two contiguous apostrophes.

Rules for namelist output

You must not specify a single character variable to output namelist data to an internal file, even if it is large enough to hold all of the data.

If you do not specify the NAMELIST run-time option, or you specify NAMELIST=NEW, the namelist group name and namelist item names output in uppercase.

Example of namelist output data

TYPE PERSON
  INTEGER P_AGE
  CHARACTER(20) P_NAME
END TYPE PERSON
TYPE(PERSON) SMITH
NAMELIST /NL1/ I,J,C,SMITH
CHARACTER(5) :: C='BACON'
INTEGER I,J
I=12046
J=12047
SMITH=PERSON(20,'John Smith')
WRITE(6,NL1)
END

After execution of the WRITE statement with NAMELIST=NEW, the output data is:

    1         2         3         4
1...+....0....+....0....+....0....+....0
 &NL1
 I=12046, J=12047, C=BACON, SMITH=20, John Smith
 /

After execution of the WRITE statement with NAMELIST=OLD, the output data is:

    1         2         3         4
1...+....0....+....0....+....0....+....0
 &nl1
 i=12046, j=12047, c='BACON', smith=20, 'John Smith          '
 &end