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

%---------------------------
\subsection{Timing Routines}
\label{subsec:get_wtime}

The \scode{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 \scode{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}

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

A more flexible or controllable approach is to call 
the \scode{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 \plc{verbose} argument.
A value of 0 or .false. (for C/C++ or Fortran) indicates
the required OpenMP ICVs associated with environment variables be displayed,
and a value of 1 or .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
\scode{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 \scode{OMP_DISPLAY_ENV} to \code{TRUE} or \code{VERBOSE}.

\cexample[5.1]{display_env}{1}

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

\emph{Note}: 
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{\code{error} Directive}
\label{subsec:error}

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

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

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