\pagebreak
\section{Utilities}
\label{sec:utilities}
This section contains examples of utility routines and features.

%---------------------------
\subsection{Timing Routines}
\label{subsec:get_wtime}
\index{routines!omp_get_wtime@\kcode{omp_get_wtime}}
\index{omp_get_wtime routine@\kcode{omp_get_wtime} routine}
\index{routines!omp_get_wtick@\kcode{omp_get_wtick}}
\index{omp_get_wtick routine@\kcode{omp_get_wtick} routine}

The \kcode{omp_get_wtime} routine can be used to measure the elapsed wall
clock time (in seconds) of code execution in a program.
The routine is thread safe and can be executed by multiple threads concurrently.
The precision of the timer can be obtained by a call to
the \kcode{omp_get_wtick} routine. The following example shows a use case.

\cexample{get_wtime}{1}

\ffreeexample{get_wtime}{1}


%---------------------------
\subsection{Environment Display}
\label{subsec:display_env}
\index{environment display!OMP_DISPLAY_ENV@\kcode{OMP_DISPLAY_ENV}}
\index{environment variables!OMP_DISPLAY_ENV@\kcode{OMP_DISPLAY_ENV}}
\index{OMP_DISPLAY_ENV@\kcode{OMP_DISPLAY_ENV}}
\index{environment display!omp_display_env routine@\kcode{omp_display_env} routine}
\index{routines!omp_display_env@\kcode{omp_display_env}}
\index{omp_display_env routine@\kcode{omp_display_env} routine}

The OpenMP version number and the values of ICVs associated with the relevant
environment variables can be displayed at runtime by setting 
the \kcode{OMP_DISPLAY_ENV} environment variable to either 
\vcode{TRUE} or \vcode{VERBOSE}.
The information is displayed once by the runtime.

A more flexible or controllable approach is to call 
the \kcode{omp_display_env} API routine at any desired
point of a code to display the same information.
This OpenMP 5.1 API routine takes a single \ucode{verbose} argument.
A value of 0 or \bcode{.false.} (for C/C++ or Fortran) indicates
the required OpenMP ICVs associated with environment variables be displayed,
and a value of 1 or \bcode{.true.} (for C/C++ or Fortran) will include
vendor-specific ICVs that can be modified by environment variables.

The following example illustrates the conditional execution of the API
\kcode{omp_display_env} routine.  Typically it would be invoked in
various debug modes of an application. 
An important use case is to have a single MPI process (e.g., rank = 0) 
of a hybrid (MPI+OpenMP) code execute the routine,
instead of all MPI processes, as would be done by 
setting the \kcode{OMP_DISPLAY_ENV} to \vcode{TRUE} or \vcode{VERBOSE}.

\cexample[5.1]{display_env}{1}

\ffreeexample[5.1]{display_env}{1}
\clearpage

A sample output from the execution of the code might look like:
{\small\begin{verbatim}
 OPENMP DISPLAY ENVIRONMENT BEGIN
    _OPENMP='202011'
   [host] OMP_AFFINITY_FORMAT='(null)'
   [host] OMP_ALLOCATOR='omp_default_mem_alloc'
   [host] OMP_CANCELLATION='FALSE'
   [host] OMP_DEFAULT_DEVICE='0'
   [host] OMP_DISPLAY_AFFINITY='FALSE'
   [host] OMP_DISPLAY_ENV='FALSE'
   [host] OMP_DYNAMIC='FALSE'
   [host] OMP_MAX_ACTIVE_LEVELS='1'
   [host] OMP_MAX_TASK_PRIORITY='0'
   [host] OMP_NESTED: deprecated; max-active-levels-var=1
   [host] OMP_NUM_THREADS: value is not defined
   [host] OMP_PLACES: value is not defined
   [host] OMP_PROC_BIND: value is not defined
   [host] OMP_SCHEDULE='static'
   [host] OMP_STACKSIZE='4M'
   [host] OMP_TARGET_OFFLOAD=DEFAULT
   [host] OMP_THREAD_LIMIT='0'
   [host] OMP_TOOL='enabled'
   [host] OMP_TOOL_LIBRARIES: value is not defined
 OPENMP DISPLAY ENVIRONMENT END
\end{verbatim}}


%---------------------------
\subsection{\kcode{error} Directive}
\label{subsec:error}
\index{directives!error@\kcode{error}}
\index{error directive@\kcode{error} directive}
\index{error directive@\kcode{error} directive!at clause@\kcode{at} clause}
\index{clauses!at@\kcode{at}}
\index{at clause@\kcode{at} clause}
\index{error directive@\kcode{error} directive!severity clause@\kcode{severity} clause}
\index{clauses!severity@\kcode{severity}}
\index{severity clause@\kcode{severity} clause}

The \kcode{error} directive provides a consistent method for C, C++, and Fortran to emit a \kcode{fatal} or
\kcode{warning} message at \kcode{compilation} or \kcode{execution} time, as determined by a \kcode{severity}
or an \kcode{at} clause, respectively. When \kcode{severity(fatal)} is present, the compilation 
or execution is aborted. Without any clauses the default behavior is as if \kcode{at(compilation)} 
and \kcode{severity(fatal)} were specified.

The C, C++, and Fortran examples below show all the cases for reporting messages.

\cexample[5.2]{error}{1}
\ffreeexample[5.2]{error}{1}