Chap_directives.tex

\cchapter{OpenMP Directive Syntax}{directives}
\label{chap:directive_syntax}
\index{directive syntax}

OpenMP \plc{directives} use base-language mechanisms to specify OpenMP program behavior.
In C/C++ code, the directives are formed with 
either pragmas or attributes.
Fortran directives are formed with comments in free form and fixed form sources (codes).
All of these mechanisms allow the compilation to ignore the OpenMP directives if
OpenMP is not supported or enabled.


The OpenMP directive is a combination of the base-language mechanism and a \plc{directive-specification},
as shown below. The \plc{directive-specification} consists
of the \plc{directive-name} which may seldomly have arguments, 
followed by optional \plc{clauses}. Full details of the syntax can be found in the OpenMP Specification.
Illustrations of the syntax is given in the examples.

The formats for combining a base-language mechanism and a \plc{directive-specification} are:

C/C++ pragmas
\begin{indentedcodelist}
#pragma omp \plc{directive-specification}
\end{indentedcodelist}

C/C++ attribute specifiers
\begin{indentedcodelist}
[[omp :: directive( \plc{directive-specification} )]]
[[omp :: decl( \plc{directive-specification} )]]
\end{indentedcodelist}

C++ attribute specifiers
\begin{indentedcodelist}
[[using omp : directive( \plc{directive-specification} )]]
[[using omp : decl( \plc{directive-specification} )]]
\end{indentedcodelist}

where the \kcode{decl} attribute may be used for declarative
directives alternatively.

Fortran comments
\begin{indentedcodelist}
!$omp \plc{directive-specification}
\end{indentedcodelist}

where \scode{c$omp} and \scode{*$omp} may be used in Fortran fixed form sources.

Most OpenMP directives accept clauses that alter the semantics of the directive in some way, 
and some directives also accept parenthesized arguments that follow the directive name. 
A clause may just be a keyword (e.g., \kcode{untied}) or it may also accept argument lists 
(e.g., \kcode{shared(\ucode{x,y,z})}) and/or optional modifiers (e.g., \kcode{tofrom} in 
\kcode{map(tofrom: \ucode{x,y,z})}).
Clause modifiers may be ``simple'' or ``complex'' -- a complex modifier consists of a
keyword followed by one or more parameters, bracketed by parentheses, while a simple 
modifier does not. An example of a complex modifier is the \kcode{iterator} modifier, 
as in \kcode{map(iterator(\ucode{i=0:n}), tofrom: \ucode{p[i]})}, or the \kcode{step} modifier, as in 
\kcode{linear(\ucode{x}: ref, step(\ucode{4}))}. 
In the preceding examples, \kcode{tofrom} and \kcode{ref} are simple modifiers.

For Fortran, a declarative directive (such as \kcode{declare reduction})
must appear after any \bcode{USE}, \bcode{IMPORT}, and \bcode{IMPLICIT} statements
in the specification part.


%===== Examples Sections =====
\input{directives/pragmas}
\input{directives/attributes}
\input{directives/fixed_format_comments}
\input{directives/free_format_comments}