Fortran DVM Compiler
User's guide
* March, 2000 *

- last edited 25.09.00 -


Contents

1 Introduction
2 Compiler role
3 Invoking the compiler
4 Compiler options
5 Debugging mode of compilation
6 Compiling HPF-DVM program
7 Compiler messages


1 Introduction

This document describes how to use the Fortran DVM (FDVM) compiler. It is part of general manual describing DVM-system usage.

The following notations for syntax constructs are used in this guide:

::= - is by definition
| - an alternative construct
[x] - encloses optional construct
y-list - list of elements y [ , y ]…

2 Compiler role

Fortran DVM (FDVM) language is an extension of the Fortran 77 language for parallel programming in DVM model. The extension is implemented as special comments (directives) that annotate sequential program in Fortran 77.

The input to the compiler is source code in Fortran DVM and HPF-DVM. The compiler produces the following output programs.

3 Invoking the compiler

The following command line starts FDVM compiler up:

dvm fdv [ <options> ] <file-name>

where:

<options> - specify compilation modes. If some option is omitted, default value is used. If two options contradict each other, the last one in the command line takes precedence;
<file-name> - name (without extension) of source FDVM program file. The file must have .fdv extension. The current directory is searched for the source file.

4 Compiler options

The compiler has some optional features that you select by including options on the command line of the compiler. The format of an option consists of a hyphen followed immediately by the option name. Some options require arguments. To describe option syntax following notations are used. Option names are typed in bold, and option arguments are typed in italics. The compiler options are listed and briefly described below.

-o file Place output in the file file.
-s Produce sequential program;
-p Produce parallel program;
-hpf1 Produce HPF1 program;
-hpf2 Produce HPF2 program;
-v Display the invocations of compiler phases and version number;
-w Display all the warning messages;
-Idir Add directory dir to the list of directories searched for include files;
-bindk Specifies the compatibility of data types between Fortran and C;
-dleveld[:fr-list] Produce additional code for the program debugging;
-elevele[:fr-list] Produce additional code for program performance analyzing.

Output file. Name of output file, the compiler places output program in, is specified by the option

-o file

where file is the file name. If this option is omitted, the default name is <file-name>.f or <file-name>.hpf in mode of producing HPF program. Output file is placed to the current directory.

Produced program type. The type of produced program is specified by following options:

–s sequential program
–p parallel program
–hpf1 HPF1 program
–hpf2 HPF2 program

Parallel program is produced by default.

Directories for include-files. If the source program has INCLUDE statements and not all include-files are in the current directory, it is necessary to use the option

-Idir

where dir is directory name. First, the compiler searches for an include-file in the directories and in the order specified in command line. Then the current directory is searched for file.

Additional information. To display the compiler version and invoking compilation phases, it is necessary to use the option

-v

Use the option

-w

to display all the warning messages.

Compatibility of data types. Compatibility of data types in Fortran and C compilers for the computer the produced program will be executed on is specified by the option

-bindk

where k is an integer pointing to compatibility table number.

k = 0:
Fortran Type C Type Size (bytes)
integer long   4
real float   4
double precision double 8
character char    1
logical long   4
k = 1:
Fortran Type C Type Size (bytes)
integer int     4
real float   4
double precision double 8
character char    1
logical int     4
integer*8 long   8

Compatibility of types is defined by standard C and Fortran compilers for the computer. By default, k = 0.

Note. The –bind, –d, and –e options don’t affect HPF program generation (-hpf1 or –hpf2 mode).

5 Debugging mode of compilation

There are two ways to debug FDVM programs:

Several debug levels are defined for each of them.

Functional debug levels. Functional debug level (leveld) is an integer (from 0 to 4) specifying the events, the Debugger is informed about:

0 - no events;
1 - modification of distributed arrays,
2 - modification and usage of distributed arrays,
3 - modification of all the variables,
4 - modification and usage of all the variables.

Performance debug levels. The performance debug level (levele) is an integer (from 0 to 4) specifying which program segments are examined as execution intervals. The performance characteristics may be estimated for each of these intervals.

0 - no intervals;
1 - parallel loops and surrounding sequential loops;
2 - statement intervals, specified in the program by INTERVAL and END INTERVAL directives;
3 - combination of the level 1 and 2;
4 - all the loops and intervals specified by INTERVAL and END INTERVAL directives.

A sequence of statements is declared as interval by the following directives:

CDVM$  INTERVAL [<integer-expression>]
  
   <statement-sequence>
CDVM$  END INTERVAL

Each interval must satisfy statement block conditions:

In other words transfer of control from outside the interval into it and from within the interval to a statement outside it is prohibited.

Program fragments. A program may be divided into separate statement fragments to be debugged. The fragment is specified by the following directives:

CDVM$  DEBUG <fragment-number> [( <parameter> )]
       <statement-fragment>
CDVM$  END DEBUG <fragment-number>

<fragment-number> ::= <integer>
<parameter> ::= -d<leveld>
  | -e<levele>
  | -d<leveld> -e<levele>

where:

-d specifies maximal allowed level of functional debugging for the fragment,
-e specifies maximal allowed level of performance debugging for the fragment,
<leveld> – integer number (from 0 to 4),
<levele> – integer number (from 0 to 4).

Each fragment must satisfy statement block conditions.

The enclosed fragments are permitted. Let f1 denotes the set of statements that compose surrounding fragment, l1 denotes the debug level specified in DEBUG directive for the fragment, and f2 , l2 denote the set of statements and debug level of enclosed fragment. Then maximal allowed level is l1 for set f1  f2 and l2 for set f2.

By default, whole program is the fragment with number 0 and its maximal allowed debugging level is -D4, -E4.

Let the following structure of fragments in program unit is specified:

                 SUBROUTINE SUB(…)
                         S1
CDVM$  DEBUG 1 (D = 4 , E = 1)
                         S2
CDVM$  DEBUG 2 (D = 1 , E = 3)
                         S3
CDVM$  END DEBUG 2
                         S4
CDVM$  END DEBUG 1
                         S5
                END

The maximal allowed levels of debug for this structure are:

Set of statements

Debug level

{ S1, S5 } D = 4 , E = 4
{ S2, S4 } D = 3 , E = 1
{ S3 } D = 1 , E = 3

Debug levels specified by compiler options.

The debug level for whole program is defined by options:

-dleveld - for functional debug,
-elevele - for performance debug.

The default options are –d0 and –e0.

The debug levels for fragments of program are defined by options:

-dleveld [:fr-list]
-elevele [:fr-list]

where:

fr ::= Lfr [ - Hfr ]
Lfr ::= <fragment-number>
Hfr ::= <fragment-number>

The condition Lfr Hfr must be satisfied.

fr-list is a list where each element is a fragment number or a range of fragment numbers. Let m be the debug level that is specified for some fragment in DEBUG directive. If the level l is specified for this fragment by compiler option, then the fragment debug level is min( m, l ).

If the options

-d2:1-2  -e2

are specified in compiler command line, then the following debug levels are assigned to the subroutine SUB:

Set of statements

Functional debug level

Performance debug level

{ S1, S5 } 0 2
{ S2, S4 } 2 1
{ S3 } 1 2

For details see "DVM-program debugging. User's guide" and "Debugging DVM-program performance. User's guide".

Tracing Lib-DVM function execution. To set on and set off accumulation of trace of Lib-DVM calls, the following debug directives may be used:

CDVM$  TRACE ON
CDVM$  TRACE OFF

6 Compiling HPF-DVM program

To compile HPF-DVM program type:

dvm fdv [ <options> ] <file-name>.hpf

In addition to options described above in section 3, the following compiler options may be used to improve the performance of output program. They specify the features of source HPF-DVM program.

-Hshwwidth Specifies the maximum shadow edges width of all distributed arrays used in program, width is a positive integer, by default width = 1;
-Honeq Permits a single execution of inquiry about kind of data access;
-Honlyl Specifies that the operands in sequential branches (outside the INDEPENDENT loop) are local, i.e. there are no remote access data in sequential branches.

7 Compiler messages

If the compiler detects an error in source program, it displays a message of the following form:

< message-kind> < message-number> on line < line-number> of < file-name> : < message-text>

where:

< message-kind> - Warning warning message, that do not prevent producing output program.
  - Error unrecoverable error, output program can't be produced.
< line-number> - line number in file < file-name> , where the error was detected.
< message-text> - message text in English.

Error numbers, message texts and comments are listed below.

000 Compiler bug
This message indicates an error in the compiler, not a user error. Internal errors should be reported to compiler developers.
001 Unknown option option is ignored
Warning. The compiler did not recognize the option as command line option.
002 Invalid option argument arg is ignored
Warning. The compiler did not recognize the arg specified with command line option.
003 No source file specified
On the command line, source file name should be specified after all options.
004 Illegal command line format
On the command line, all options should be placed before source file name.
005 Can't open file filename
Source file is not in current working directory, or file is read protected. Include file is missing, or read protected.
006 Can't open file filename for write
Probably, user does not have write permission for the current working directory.
007 Null program
Source input file does not contain any Fortran statements.
008 Missing final end statement or unclosed construct
009
Illegal continuation card ignored
A continuation card does not follow an initial line.
010 Unclassifiable statement
The compiler did not recognize any key word of FDVM language.
011 Non digit in statement number field
The label field (first five characters) of the indicated line contains a non-numeric character.
012 Unbalanced quotes; closing quote supplied
013 Unbalanced parentheses, statement skipped
014 Syntax error
A syntax error was found while parsing the Fortran statement or DVM directive.
015
Comment too long. Truncated to 160 characters
Warning.
016
Inconsistent declaration of identifier identifier
An attempt was made to define a symbol in a manner inconsistent with an earlier definition of the same symbol.
017 Inconsistent constant declaration identifier
An attempt was made to declare a symbol as a PARAMETER, which was previously declared to be another object.
018 Inconsistent array declaration of identifier identifier
An attempt was made to declare a symbol as an array, which was previously declared as another object.
019 Inconsistent function identifier
An attempt was made to declare a symbol as a FUNCTION or ENTRY, which was previously declared in inconsistent manner.
020 Inconsistent procedure identifier
An attempt was made to declare a symbol as EXTERNAL which was previously declared as another global object.
021 Inconsistent subroutine identifier
An attempt was made to declare a symbol as SUBROUTINE, which was previously declared as a COMMON, FUNCTION, or PROGRAM.
022 Inconsistent program declaration identifier
An attempt was made to declare a symbol as PROGRAM, which was previously declared as a COMMON, FUNCTION, or SUBROUTINE.
023
Inconsistent common declaration identifier
An attempt was made to declare a symbol as COMMON, which was previously declared as a FUNCTION, PROGRAM, or SUBROUTINE.
024 Function has the same name as a common block identifier
Warning.
025 Common block has the same name as a function identifier
Warning.
026 Inconsistent operands to boolean operation
027 Inconsistent operands to arithmetic operation
028 Non-logical expression in IF statement
029 Statement order error: declaration after DATA or function statement
030 Declaration among executables
The statement order is incorrect. Specification statement must precede an executable statement.
031 ELSEIF out of place
An ELSEIF statement cannot be matched with a preceding IF-THEN statement.
032 ELSE out of place
An ELSE statement cannot be matched with a preceding IF-THEN statement.
033 Misplaced PROGRAM statement
034 Misplaced SUBROUTINE statement
035 Misplaced ENTRY statement
036 Statement cannot be reached
Warning.
037 IMPLICIT item must be single letter
038 Label out of range
039 Label already that of a FORMAT
040 Label label already defined
041 Non character entity identifier has length specification
042 No dimensions in DIMENSION statement
043 Too many dimensions
The number of specified array dimensions exceeded the maximum (7) allowed.
044 Can't subscript identifier
Subscripts are specified for non-array variable.
045 Can't take substring of identifier
046 No backward DO loops
The label in DO statement was previously defined.
047 Symbolic constant not allowed as DO variable
048 Must go to label or assigned variable
049 Missing DVM directive prefix
DVM directive prefix (CDVM$ or *DVM$) is not precede the DVM directive.
050 Explicit shape specification is required
Explicit shape specification is required for processor array and template in PROCESSORS and TEMPLATE directive.
051 Distribution format list is omitted
052 Unexpected END statement read
Wrong Fortran-program structure.
053 Illegal use of PROCESSORS name identifier
Processor array references may only appear in DISTRIBUTE, REDISTRIBUTE, or MAP directives. They may not appear, for example, in expressions.
054 A distributee may not have the ALIGN attribute: identifier
055 Distribution format BLOCK(n) is not permitted in FDVM
056 Illegal shadow width specification
057 An alignee may not have the DISTRIBUTE attribute: 'identifier'
058 The alignee identifier isn't an array
059 'identifier' hasn't the DYNAMIC attribute
060 'identifier' hasn't the ALIGN attribute
061 The align-target identifier isn't declared as array
062 The align-dummy identifier isn't a scalar integer variable
063 Illegal combination of attributes
064 'identifier' has the DISTRIBUTE and ALIGN attribute
065 No shape specification
066 'identifier' isn't array
067 'identifier' is not processor array
Processor array reference must appear after ONTO in MAP directive.
068 'identifier' is not remote group name
069 'identifier' is not declared as reduction group
070 Illegal reduction operation name
071 Illegal use of task array name identifier
Task array references may only appear in TASK_REGION, ON, parallel-task-loop-directive
, REDISTRIBUTE, or MAP directives.
072 'identifier' isn't distributed array
073 Multiple declaration of identifier 'identifier'
074 'identifier' is not declared as group
075 No dimension in TASK directive
076 Illegal rank of 'identifier'
077 'identifier' is not task array
078 Illegal interval number
In INTERVAL directive, interval number must be specified by integer expression.
079 Template 'identifier' is in COMMON
080 Template may not be a dummy argument: identifier
081 ENTRY among specification statements
Warning.
082 Duplicate aligning of the array 'identifier'
083 POINTER 'identifier' is not integer variable
084 POINTER may not have SAVE attribute: identifier
085 POINTER 'identifier' is not distributed object
086 Object 'identifier' has neither TEMPLATE nor PROCESSORS attribute
087 Illegal shape specification in DIMENSION attribute
Illegal array declarator occurs in DIMENSION attribute of combined directive.
088 Length of shadow-edge-list is not equal to the rank of array 'identifier'
089 attribute attribute appears more than once in the combined-directive
090 The number of BLOCK/GENBLOCK elements of dist-format-list is greater than the rank of PROCESSORS 'identifier'
091 Missing HEAP declaration
Dynamic memory pool HEAP is not declared.
092 Alignment tree root 'identifier' is not distributed
093 PAUSE statement is not permitted in FDVM
094 Illegal statement in the range of parallel loop
095 Only a value of ALLOCATE function or other POINTER may be assigned to a POINTER
096 Nested PARALLEL directives are not permitted
097 Directive PARALLEL must be followed by DO statement
098 The directive is inside the range of PARALLEL loop
099 Misplaced REMOTE_ACCESS directive
100 Nested TASK_REGION are not permitted
101 Statement is outside of on-block
The statement is inside a task region but it is not inside an on-block.
102 No matching TASK_REGION
This message indicates that an END TASK_REGION directive occurred without a preceding TASK_REGION.
103 Misplaced directive
104 Nested ON-blocks are not permitted
105 ON directive is outside of the task region
106 No matching ON directive
This message indicates that an END ON directive occurred without preceding ON.
107 Parallel-task-loop directive is outside of the task region
108 Missing END TASK_REGION directive
109 Missing END ON directive
110 Rank of array identifier is not equal to the length of the dist-format-list
111 Saved object may not have the DYNAMIC attribute: identifier
112 Object in COMMON may not have the DYNAMIC attribute: identifier
113 'identifier' hasn't the DYNAMIC attribute
114 'identifier' does not appear in DISTRIBUTE/INHERIT directive
116 Template 'identifier' appears as an alignee
117 Dummy argument 'identifier' is aligned with local array
118 Aligned array 'identifier' is in COMMON but align-target is not
119 Aligned array 'identifier' has SAVE attribute but align-target has not
120 'identifier' does not appear in ALIGN or INHERIT directive
121 'identifier' is a duplicate dummy argument
122 Descriptor array error
123 Rank of pointer identifier is not equal to the length of the dist-format-list
124 Array 'identifier' may not be allocated
125 Array 'identifier' may not be aligned
126 Illegal aligning of 'identifier'
127 Distributed object 'identifier' is not array
The object has DISTRIBUTE, ALIGN, or INHERIT attribute but it is not declared as array.
128 Rank of aligned array identifier isn't equal to the length of align-source-list
129 GEN_BLOCK and WGT_BLOCK in format-list
GEN_BLOCK format and WGT_BLOCK format may not appear together in format list of DISTRIBUTE/REDISTRIBUTE directive.
130 Wrong align-subscript expression
If align-dummy is operand of align-subscript expression then this expression must be of the following kind: a*I + b, where I – align-dummy, a, b – constant, variable, or expression enclosed in parenthesis.
132 Rank of align-target 'identifier' isn't equal to the length of align-subscript-list
133 More one occurrence of do-variable 'identifier' in iteration-align-subscript-list
134 More one occurrence of align-dummy 'identifier' in align subscript list
135 More one occurrence of a do-variable in do-variable-use expression
136 More one occurrence of an align-dummy in align-subscript expression
137 Illegal group name use: 'identifier'
138 Illegal POINTER reference: 'identifier'
139 Owner-computes rule
Warning. The assignment statement execution conforms to the owner-computes rule.
140 Wrong number of subscripts specified for identifier
The number of subscripts specified for the array reference is not equal to the array rank.
141 Illegal type of 'identifier'
142 Low shadow width of 'identifier' is greater than the corresponding one specified in SHADOW directive
143 High shadow width of 'identifier' is greater than the corresponding one specified in SHADOW directive
144 Low shadow width of 'identifier' is greater than 1
145 High shadow width of 'identifier' is greater than 1
146 NEW_VALUE directive must be followed by REDISTRIBUTE or REALIGN directive
147 Illegal operand list of MAXLOC/MINLOC
148 'identifier' is distributed array
149 Wrong operand of MAXLOC/MINLOC: identifier
150 Illegal clause
Only NEW clause is allowed in parallel-task-loop directive.
151 Wrong reduction variable 'identifier'
152 Wrong type of reduction variable 'identifier'
153 Double NEW clause
More than one NEW clause occurs in PARALLEL directive
154 Double REDUCTION clause
More than one REDUCTION clause occurs in PARALLEL directive
155 Double SHADOW_RENEW clause
More than one SHADOW_RENEW clause occurs in PARALLEL directive
156 Double REMOTE_ACCESS clause
More than one REMOTE_ACCESS clause occurs in PARALLEL directive
157 Double ACROSS clause
More than one ACROSS clause occurs in PARALLEL directive
158 Length of do-variable list in PARALLEL directive is greater than the number of nested DO statements
159 Illegal do-variable-list in PARALLEL directive
In PARALLEL directive, do-variable list must include only the do-variable names of the following DO nested loops in the same order.
160 Wrong iteration-align-subscript in PARALLEL
If do-variable is operand of iteration-align-subscript expression then this expression must be of the following kind: a*I + b, where I – do-variable, a, b – constant, variable, or expression enclosed in parenthesis.
161 Rank of array 'identifier' isn't equal to the length of iteration-align-subscript-list
162 Assumed-size array: identifier
An assumed sized array was used as an item to be read or written or as a remote variable in REMOTE_ACCESS directive. In these contexts the size of the array must be known.
163 Reverse is not supported
A do-variable-use/align-dummy-use expression in PARALLEL/ALIGN directive must not specify reverse. For example, 2-I is not allowed in current version.
164 Wrong regular subscript expression
165 Length of remote-subscript-list is not equal to the rank of remote variable
166 HEAP limit is exceeded
Wrong use of dynamic array pointers. The message is displayed in execution time.
167 Illegal template reference: 'identifier'
Template references may only appear in ALIGN, REALIGN, or PARALLEL directives. They may not appear, for example, in expressions.
168 Illegal variable in new-clause: identifier
169 ENTRY of program unit distributed arrays are in
Warning
170 Name 'identifier' too long, truncated to 29
Warning.
171 No subscripts: identifier
Subscripts omitted from indicated array.
172 POINTER 'identifier' in left part of assign statement has DISTRIBUTE or ALIGN attribute
173 Pointers are of different rank
On both sides of assignment statement, the pointers must be of the same rank.
174 Pointers are of different type
On both sides of assignment statement, the pointers must be of the same type.
175 Wrong number of subscripts specified for 'identifier'
The number of subscripts specified for the array reference is not equal to the array rank.
176 'identifier' hasn't PROCESSORS/TASK attribute
177 Associated actual arguments must be aligned
Warning.
178 Illegal type of do-variable 'identifier'
179 Wrong dependence length of distributed array 'identifier'
The dependence length specified in ACROSS clause is not integer constant.
180 Wrong dependence length list of distributed array 'identifier'
The number of elements in dependence length list specified for indicated array (in ACROSS clause) is not equal to the rank of array.
181
Illegal fragment number
The indicated number is not unsigned integer constant.
182 Unmatched directive
END DEBUG directive was encountered with no preceding DEBUG directive.
183 Buffer limit is exceeded
More than five remote references are specified for distributed array.
184 Illegal I/O statement in the range of parallel loop
185 Illegal elements in control list
186 END= and ERR= specifiers are illegal in FDVM
187 IOSTAT= specifier is illegal in I/O of distributed array
189 Invalid format specification
Illegal value is indicated for FMT = specifier in control information list.
190 Illegal I/O list
FDVM allows only restricted form of input/output statements. Either input/output list contains only replicated variable references, or the I/O list contains one input/output item that is name of distributed array.
191 I/O of distributed array controlled by format specification or NAMELIST is not supported in FDVM
The following rule constraint I/O of distributed arrays:
Only “*” format specifier may be used in formatted I/O statement.
192 Illegal I/O list item: identifier
FDVM allows only restricted form of input/output statements. Distributed array may be read or wrote only as whole array. Input/output of some elements of distributed array is not permitted.
193 Array shape declaration error: 'identifier'
194 Can't calculate array length: identifier
The size of the input/output array must be known.
195 Can’t find the corresponding MAP directive
196 Incorrect call of ALLOCATE function
197 Can’t use pointers in HPF1
FDVM-program that contains POINTER variables can't be converted into HPF1.
222 Can’t find a descriptor for POINTER
The dynamic array descriptor declaration is absent.
250 Illegal nesting INDEPENDENT directive
Nested INDEPENDENT loops must satisfy tightly nested loop condition.
251 More one occurrence of do-variable 'identifier' in subscript list
Repeated
occurrence of the do-variable in left side reference of assignment statement inside INDEPENDENT loop.
252 More one occurrence of a do-variable in subscript expression
Repeated occurrence of a do-variable in left side reference subscript expression of assignment statement inside INDEPENDENT loop.
254 No target for independent loop
There is not alignment target for INDEPENDENT loop index space.
255 Reduction statement inside the range of INDEPENDENT loop, 'identifier' is reduction variable