Fortran DVM compiler. User's guide

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.

Parallel program in Fortran 77 language including runtime system function calls (Lib-DVM) for parallel execution. This program can be executed in the pseudo-parallel mode on a single processor (work station) and in parallel mode on a multiprocessor system.
Sequential program in Fortran 77 language, which includes calls of functions accumulating information for debugging and performance analyzing. The program is executed on a single processor in sequential mode.
HPF program.

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:

Functional debugging, that allows to test correctness of program execution;
Program performance debugging that allows testing efficiency of parallel execution.

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:

interval execution always starts with first statement,
interval execution always ends with last statement.

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 f₁ denotes the set of statements that compose surrounding fragment, l₁ denotes the debug level specified in DEBUG directive for the fragment, and f₂ , l₂ denote the set of statements and debug level of enclosed fragment. Then maximal allowed level is l₁ for set f₁ – f₂ and l₂ for set f₂.

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 directiv*e
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*