\chapter{Utility API Reference}

\section{mx\_get\_record}
%
\begin{description}
  \mxname
    \mxfn{mx\_get\_record}
    	- Get an MX\_RECORD object from the MX database.
%
  \mxsynopsis
    MX\_RECORD *\mxfn{mx\_get\_record}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *mx\_database\_record, \\
			char *record\_name ); \\
		\end{tabular}
%
  \mxdescription
    \mxfn{mx\_get\_record()} searches the MX database specified by
    \textit{mx\_database\_record} for the MX\_RECORD object
    that has a name that matches the \textit{record\_name} argument.
    Although it is conventional to supply a pointer to the MX list head
    record called \textit{mx\_database}, you can actually supply a pointer
    to any of the records in the running database and it will find the
    record with the matching name if it exists.
%
  \mxreturnvalue
    If successful, \mxfn{mx\_get\_record()} returns a pointer to
    the MX\_RECORD object with the specified name.  If no record
    with that name exists in the MX runtime database,
    \mxfn{mx\_get\_record()} returns a NULL pointer.
%
  \mxseealso{
    \mxfn{mx\_setup\_database()},
    \mxfn{mx\_setup\_database\_from\_array()}
  }
    
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_setup\_database}
%
\begin{description}
  \mxname
    \mxfn{mx\_setup\_database}
    	- configures and initializes the MX runtime database
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_setup\_database}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD **mx\_database\_record, \\
			char *database\_filename ); \\
		\end{tabular}
%
  \mxdescription
    \mxfn{mx\_setup\_database()} is a utility function that does
    all of the work necessary to create an MX runtime database
    that is ready to be used by application programs.  In outline,
    \mxfn{mx\_setup\_database()} does the following:
    \begin{itemize}
      \item Initialize the MX runtime environment using
        \mxfn{mx\_initialize\_runtime()}.
      \item Initialize the MX device drivers using
        \mxfn{mx\_initialize\_drivers()}.
      \item Create an empty MX runtime database using
        \mxfn{mx\_initialize\_record\_list()}.
      \item Setup all of the records in the MX runtime database using
        \mxfn{mx\_read\_database\_file()}.
      \item Finish initialization of record data structures using
	\mxfn{mx\_finish\_database\_initialization()}.
      \item Initialize connections to the data acquisition hardware
        and remote servers using
	\mxfn{mx\_initialize\_hardware()}.
    \end{itemize}
%
    After the MX runtime database has been initialized, you may
    get pointers to individual records in it using the function
    \mxfn{mx\_get\_record()}.

%    \textit{\FIXME\ -\ In principle, there is a lot of other stuff one
%    could say about mx\_setup\_database().  You could mention that, in general,
%    it is better to store MX scan records in separate files.  You could
%    mention the various ways in which you can customize the runtime 
%    environment after mx\_setup\_database() finishes.  There are many
%    other things that could be mentioned here.}
%
%    \textit{However, it is probably best to not mention all of that stuff
%    in a manual that is intended primarily for area detector users.}
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_get\_record()},
    \mxfn{mx\_setup\_database\_from\_array()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_setup\_database\_from\_array}
%
\begin{description}
  \mxname
    \mxfn{mx\_setup\_database\_from\_array}
    	- configures and initializes the MX runtime database
	from an in memory database
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_setup\_database\_from\_array}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD **mx\_database\_record, \\
			long num\_records, \\
			char **record\_description\_array ); \\
		\end{tabular}
%
  \mxdescription
    \mxfn{mx\_setup\_database\_from\_array()} is a variant of
    \mxfn{mx\_setup\_database()} that reads the database records
    from an in memory array rather than a disk file.

    See Section~\ref{subsec:mxsetupdatabasefromarrayexample}
    for an example of how to use
    \mxfn{mx\_setup\_database\_from\_array()}.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_get\_record()},
    \mxfn{mx\_setup\_database()}
  }

\end{description}

