\newcommand{\mxfn}[1]{\textbf{#1}}

\part{C Application Programming Summary}

\chapter{API Introduction}

The C language application programming interface (API) for MX
is defined by the header
files in the \textit{mx/libMx} directory of the source distribution
with names of the form \textbf{mx\_*.h}.
In these files, any function declared using the macro MX\_API is intended
to be available to normal user programs.  Functions declared in these header
files using the macro MX\_API\_PRIVATE are \textit{not} intended for use by
typical user programs.
For a binary distribution of MX installed at \textbf{/opt/mx},
these files are found in the directory \textbf{/opt/mx/include}.
There are other header files in the \textbf{mx/libMx} directory with names
like \textbf{d\_*.h}, \textbf{i\_*.h}, and so forth, but they are mostly 
intended to be used by MX device drivers.  

%****************************************************************************

\chapter{Common Functions}

%----------------------------------------------------------------------------

\section{MX Record Functions}

\subsection{Setting up an MX database}

\begin{description}
    \item[\mxfn{mx\_setup\_database()}] -
	A simplified MX startup routine that reads
	an MX database file and then automatically initializes all the
	hardware connections.  Many application programs will only need
	to call this one function at startup time to be ready to use
	MX controlled devices.
\end{description}

\subsection{Finding a record in the database}

\begin{description}
    \item[\mxfn{mx\_get\_record()}] -
	Used to find a record in the database by its name.
\end{description}

\subsection{Displaying the status of a record}

\begin{description}
    \item[\mxfn{mx\_print\_structure()}] -
	Writes a formatted report of the status
	of the record to the supplied FILE pointer.
\end{description}

Most simple programs will only use the preceding three functions to manipulate
a running MX database.  However, if the programmer wants more control over
the setting up and shutting down of the database, the following lower level
functions are also available.

\subsection{Setting up an MX database (the long way)}

An MX database can also be set up by using the following lower level functions
essentially in the order show.  \mxfn{mx\_setup\_database()} itself
is implemented by calling these functions.

\begin{description}
    \item[\mxfn{mx\_initialize\_drivers()}] -
    	Initializes all of the MX device drivers.
    %
    \item[\mxfn{mx\_initialize\_record\_list()}] -
    	Creates an empty MX record list.
    %
    \item[\mxfn{mx\_read\_database\_file()}] -
	Reads an MX database file and adds the
	listed MX records to the running database.
    %
    \item[\mxfn{mx\_finish\_database\_initialization()}] -
	Performs MX database
	initialization steps that can only be performed after all of the
	records in the database have been created.
    %
    \item[\mxfn{mx\_initialize\_hardware()}] -
	Makes the original connections to the
	control system hardware and initializes the devices.
    %
\end{description}

\subsection{Shutting down an MX database}

Often, an MX client that does not need to preserve a local copy of database
parameters can simply call \mxfn{exit()} when it finishes running.
However, if preserving the local copies is required or if devices that need
careful shutdown are in use, the following functions are available.

\begin{description}
    \item[\mxfn{mx\_write\_database\_file()}] -
	Writes some or all of the MX records out to an MX database file.
    %
    \item[\mxfn{mx\_shutdown\_hardware()}] -
	Shuts down the connections to the control system hardware.
    %
\end{description}

\subsection{Creating a single MX record}

\begin{description}
    \item[\mxfn{mx\_create\_record\_from\_description()}] -
	Uses a character string description of an MX record to create
	the data structures for the record in the running database.
    %
    \item[\mxfn{mx\_finish\_record\_initialization()}] -
        Finishes setting up the data structures for the new record.
    %
    \item[\mxfn{mx\_open\_hardware()}] -
        Makes the initial connection to the hardware controlled by this record.
    %
    \item[\mxfn{mx\_write\_parms\_to\_hardware()}] -
        Writes initial device settings to the hardware.
	\newline
	\textit{(This function is deprecated.
	Use \mxfn{mx\_open\_hardware()} instead.)}
    %
\end{description}

\subsection{Creating a record description from a current MX record}

\begin{description}
    \item[\mxfn{mx\_create\_description\_from\_record()}] -
        Creates a character string description of the record
	in the format used by MX database files.
\end{description}

\subsection{Destroying a single MX record}

\begin{description}
    \item[\mxfn{mx\_read\_parms\_from\_hardware()}] -
        Reads device settings from the hardware.
	\newline
	\textit{(This function is deprecated.
	Use \mxfn{mx\_close\_hardware()} instead.)}
    %
    \item[\mxfn{mx\_close\_hardware()}] -
        Shuts down the connection to the hardware.
    %
    \item[\mxfn{mx\_delete\_record()}] -
        Deletes the record.  \mxfn{mx\_close\_hardware()} should be performed
	first to shutdown the associated hardware.
\end{description}

\subsection{Communication error recovery}

\begin{description}
    \item[{mx\_resynchronize\_record()}] -
        This function attempts to resynchronize
	communication with a hardware controller.  It is intended for use
	when errors from other functions indicate that the handshake between
	MX and the remote controller is out of sync.  For example, this
	would be used to resynchronize an RS-232 connection if somehow a
	few characters were lost.
\end{description}

There are a number of other MX functions that operate on generic records,
but they are less commonly used and are not mentioned in this summary.
However, they will be described in the API reference document.

\section{MX Network Functions}

\subsection{Socket functions}

At present, TCP sockets and Unix domain sockets are supported.

\begin{description}
    \item[\mxfn{mx\_socket\_open\_as\_client()}] - Makes a client connection
	to a TCP server.
    %
    \item[\mxfn{mx\_socket\_open\_as\_server()}] - Creates a server TCP socket
	that is ready for connections from clients.
    %
    \item[\mxfn{mx\_socket\_close()}] - Closes an already open TCP socket.
    %
    \item[\mxfn{mx\_socket\_is\_open()}] - Checks to see if the specified socket
	corresponds to an open connection.
    %
    \item[\mxfn{mx\_socket\_mark\_as\_closed()}] -
        Replaces the socket value with
	a value that indicates that this is an invalid socket.
    %
    \item[\mxfn{mx\_socket\_get\_last\_error()}] -
        Gets the error code corresponding
	to the last socket error.  This returns either \textit{errno}
	or \textit{WSAGetLastError()} depending on the operating system
	platform.
    %
    \item[\mxfn{mx\_socket\_strerror()}] - Returns the error text corresponding
	to a given socket error code.
    %
    \item[\mxfn{mx\_socket\_check\_error\_status()}] - Socket related functions
	may return any of three different kinds of values for indicating
	an error, namely NULL, 0, or -1 (INVALID\_SOCKET on Win32).
	This function figures out whether the value returned by 
	a socket function corresponds to an error or not.
    %
    \item[\mxfn{mx\_socket\_get\_inet\_address()}] - Converts a character string
	hostname to a numerical internet address represented as
	an unsigned long.
    %
\end{description}

\subsection{MX Network I/O}

The MX network I/O functions are used by a number of MX device drivers
to communicate with devices controlled by a remote MX server.  Examples
of such drivers include the \textit{network\_motor}, \textit{network\_scaler},
\textit{network\_scaler}, \textit{network\_mca},
\textit{network\_rs232}, and \textit{network\_gpib} drivers.
%
However, the underlying functions can be used if you want to directly 
modify individual record fields in a remote MX server.

\subsubsection{Network Server Functions}

In order to use the API for MX network I/O, you must have a pointer
to the MX server record that manages the connection to the remote server.
If you have started an MX database using one of the variants of 
\mxfn{mx\_setup\_database()}, then all you need to know is the name
of the server record.  For example, if you know that the server is
named \textit{mono\_server} in the running database, then all you have
to do is something like this:
%
\begin{verbatim}
...
server_record = mx_get_record( record_list, "mono_server" );
...
\end{verbatim}

If you know the server's hostname and port number, but are not
running an MX database, then you can use \mxfn{mx\_connect\_to\_mx\_server()}
to start a new MX database with a predefined server record.  In this case,
you have to do something like this:
%
\begin{verbatim}
...
mx_status = mx_connect_to_mx_server( &server_record,
				"server.example.com", 9727, 8 );
...
\end{verbatim}
where 9727 is the remote port number (this is the standard MX port number),
and 8 is the default display precision used to format floating point
numbers from MX.


\subsubsection{Network Fields}

The MX network API makes use of MX network field structures.
The MX\_NETWORK\_FIELD structure is defined in a manner equivalent to this:
\begin{verbatim}
typedef struct {
    char nfname[MXU_RECORD_FIELD_NAME_LENGTH+1];
    MX_RECORD *server_record;
    long record_handle;
    long field_handle;
} MX_NETWORK_FIELD;
\end{verbatim}
%
The members of this structure are
\begin{description}
  \item[{\bf nfname}] - This is an ASCII representation of the record
     field name in the remote MX server.  An example of this would be
     \textit{theta.position}.
  \item[{\bf server\_record}] - This is a pointer to an MX\_RECORD
     in the currently running database
     that manages the connection to a remote MX server.  Typically,
     this will be a record of type \textit{tcpip\_server} or
     \textit{unix\_server}.
  \item[{\bf record\_handle}] - This is a 32-bit integer that uniquely
     identifies the record specified by \textit{nfname} in the remote
     MX server.
  \item[{\bf field\_handle}] - This is a 32-bit integer that uniquely
     identifies the field specified by \textit{nfname} in the remote
     MX server.
\end{description}
%
The combination of a record handle with a field handle is typically
referred to collectively as an MX network field handle.

\subsubsection{Network Handle Functions}

The following are the preferred network handle functions.

\begin{description}
   \item[\mxfn{mx\_network\_field\_init()}] -
      This function initializes the \textit{server\_record} and the
      \textit{nfname} members of the MX\_NETWORK\_FIELD structure.
      The \textit{record\_handle} and \textit{field\_handle} members
      are not initialized here.  Instead, they are initialized by
      a record handle and field handle lookup procedure in the server
      that is performed during the
      first time that the MX\_NETWORK\_FIELD structure is used by
      one of the family of \mxfn{mx\_get()} and \mxfn{mx\_put()}
      functions described below.  On subsequent calls, the network
      API functions use the already cached record and field handles.
   \item[\mxfn{mx\_network\_field\_connect()}] - Performs an 
      immediate lookup of the record and field handles.  Normally,
      calling this function directly is not necessary, since it
      will automatically be invoked when needed by the functions
      below.
   \item[\mxfn{mx\_get()}] - Reads a single value from a remote
      MX server using the specified MX network field.
   \item[\mxfn{mx\_put()}] - Writes a single value to a remote
      MX server using the specified MX network field
   \item[\mxfn{mx\_get\_array()}] - Reads a multidimensional array
      from a remote MX server using the specified MX network field.
   \item[\mxfn{mx\_put\_array()}] - Writes a multidimensional array
      to a remote MX server using the specified MX network field.
\end{description}

There are also older non-handle versions of these functions such as
\mxfn{mx\_get\_by\_name()}, but those functions should be avoided
since they perform a record handle lookup and field handle lookup
for each and every call.

\subsubsection{Examples of MX Network I/O}

Here is an example of using these functions to read the current position
of the motor $\theta$.
\begin{verbatim}
...
MX_NETWORK_FIELD nf;
...
server_record = mx_get_record( record_list, "mono_server" );

mx_status = mx_network_field_init( &nf, server_record, "theta.position" );

mx_status = mx_get( nf, MXFT_DOUBLE, &theta_position );

fprintf(stderr, "The current position of theta = %g degrees\n",
				theta_position );
...
\end{verbatim}
%
For a real program, you would need to check the return values from
each of the functions above.

Here is a similar example of writing to the 2-dimensional network field
\textit{controller.params}.
\begin{verbatim}
...
MX_NETWORK_FIELD nf;
long dimension[2];
long params_array[3][2];
...
server_record = mx_get_record( record_list, "mono_server" );

mx_status = mx_network_field_init( &nf, server_record, "controller.params" );

for ( i = 0; i < 3; i++ ) {
    for ( j = 0; j < 3; j++ ) {
        params_array[i][j] = 10 * i + j;
    }
}

dimension[0] = 2;
dimension[1] = 3;

mx_status = mx_put_array( nf, MXFT_LONG, 2, dimension, params_array );

...
\end{verbatim}


\subsection{Foreign Control Systems}

\subsubsection{EPICS}

The following functions provide a client-side interface to
EPICS Channel Access.  They have been
repackaged such that they return standard MX status structures.

\begin{description}
    \item[\mxfn{mx\_caget()}] - Gets a process variable from an EPICS IOC.
    %
    \item[\mxfn{mx\_caput()}] - Sends a process variable to an EPICS IOC and
	waits until the data transfer is complete.
    %
    \item[\mxfn{mx\_caput\_nowait()}] - Sends a process variable to an EPICS IOC
	without waiting for the data transfer to be complete.
    %
    \item[\mxfn{mx\_epics\_get\_debug\_flag()}] -
        Finds out whether or not MX debugging
	of EPICS channel access I/O is turned on.
    %
    \item[\mxfn{mx\_epics\_set\_debug\_flag()}] - Turns on or off MX debugging
	of EPICS channel access I/O.
    %
\end{description}

These functions convert the integer flags used to stand
for individual data types between MX data types and either
EPICS Channel Access data types or EZCA data types.

\begin{description}
    \item[\mxfn{mx\_epics\_convert\_mx\_type\_to\_epics\_type()}]
    %
    \item[\mxfn{mx\_epics\_convert\_epics\_type\_to\_mx\_type()}]
    %
    \item[\mxfn{mx\_epics\_convert\_mx\_type\_to\_ezca\_type()}]
    %
    \item[\mxfn{mx\_epics\_convert\_ezca\_type\_to\_mx\_type()}]
    %
\end{description}

The following functions support EPICS groups.

\begin{description}
   \item[\mxfn{mx\_epics\_start\_group()}] - Starts an EPICS synchronous group.
   %
   \item[\mxfn{mx\_epics\_end\_group()}] - Ends an EPICS synchronous group.
   %
   \item[\mxfn{mx\_epics\_delete\_group()}] - Deletes an existing
   	synchronous group.
   %
   \item[\mxfn{mx\_group\_caget()}] - Queues up an EPICS caget to be
   	performed when the group is ended.
   %
   \item[\mxfn{mx\_group\_caput()}] - Queues up an EPICS caput to be
   	performed when the group is ended.
\end{description}

\section{MX Utility Functions}

\subsection{Array allocation}

\begin{description}
    \item[\mxfn{mx\_allocate\_array()}] -
        Allocate a multi-dimensional array composed
	either of intrinsic types like long, double, etc., or of C structures.
    %
    \item[\mxfn{mx\_free\_array()}] -
        Frees a multi-dimensional array allocated by
	\mxfn{mx\_allocate\_array()}].
    %
    \item[\mxfn{mx\_array\_add\_overlay()}] -
    	This function takes a 1-dimensional data buffer and constructs
	a multidimensional array on top of it.  This will only work
	correctly if the 1-dimensional buffer contains values in
	row rank order using standard C conventions.
    %
    \item[\mxfn{mx\_array\_free\_overlay()}] -
    	This function frees the overlay array created by
	\mxfn{mx\_array\_add\_overlay()}, but does not free
	the 1-dimensional buffer.
    %
\end{description}

\subsection{Clock functions}

The following clock tick handling functions are used by the MX server
for the scheduling of events.  They use operating system dependent functions 
like \textit{times()} on several versions of Unix or \textit{timeGetTime()} on 
Win32.  Clock tick values are represented using the MX\_CLOCK\_TICK C structure.

\begin{description}
    \item[\mxfn{mx\_clock\_ticks\_per\_second()}] - Reports the number of clock
	ticks per second.
    %
    \item[\mxfn{mx\_initialize\_clock\_ticks()}] - Performs any operating system
	dependent initialization required for handling operating system
	clock ticks.
    %
    \item[\mxfn{mx\_current\_clock\_tick()}] - Gets the current time in units
	of clock ticks.
    %
    \item[\mxfn{mx\_convert\_seconds\_to\_clock\_ticks()}] -
        Converts a time interval
	in seconds into the equivalent number of clock ticks.
    %
    \item[\mxfn{mx\_convert\_clock\_ticks\_to\_seconds()}] -
        Converts a time interval
	in clock ticks into the equivalent number of seconds.
    %
    \item[\mxfn{mx\_add\_clock\_ticks()}] -
        Since MX\_CLOCK\_TICK is a C structure,
	a function is required to add two clock tick values.
    %
    \item[\mxfn{mx\_subtract\_clock\_ticks()}] - Subtracts one clock tick value
	from another.
    %
    \item[\mxfn{mx\_compare\_clock\_ticks()}] -
        Reports whether a given clock tick
	value corresponds to an earlier or a later time than another
	clock tick value.
    %
\end{description}

\subsection{Coprocess handling functions}

These functions create a coprocess connected to the current process by
a pair of pipes.  One pipe is used to send to the coprocess and the
other pipe is used to receive from the coprocess.

\begin{description}
    \item[\mxfn{mx\_create\_coprocess()}] -
        Creates a coprocess using the specified command \textit{argv[]} array.
    %
    \item[\mxfn{mx\_kill\_coprocess()}] - Shuts down the coprocess.
    %
\end{description}

\subsection{Delay functions}

The following functions implement programmable delays.  Applications must
be prepared for the possibility that the delay may last longer than
requested.

\begin{description}
    \item[\mxfn{mx\_sleep()}] - Tells the operating system to pause the process
	for the requested number of seconds.
    %
    \item[\mxfn{mx\_msleep()}] - Tells the operating system to pause the process
	for the requested number of milliseconds.
    %
    \item[\mxfn{mx\_usleep()}] - Tells the operating system to pause the process
	for the requested number of microseconds.
    %
\end{description}

\subsection{Handle table functions}

MX handles are integer numbers that are used as indices into a table
of C pointers.  This feature exists so that programming languages that
cannot directly manipulate MX objects using C pointers can refer to
the objects via handle numbers.  MX network communications normally uses
handles to refer to record fields in remote MX servers.

\begin{description}
    \item[\mxfn{mx\_create\_handle\_table()}] - Creates a handle table of the
	specified size.
    %
    \item[\mxfn{mx\_resize\_handle\_table()}] - Increases the size of an already
	existing handle table.
    %
    \item[\mxfn{mx\_delete\_handle\_table()}] - Destroys a currently existing
	handle table.
    %
    \item[\mxfn{mx\_create\_handle()}] - Adds a new handle to a handle table.
    %
    \item[\mxfn{mx\_delete\_handle()}] - Removes an already existing
	handle from a handle table.
    %
    \item[\mxfn{mx\_get\_handle\_from\_pointer()}] - Converts a handle into the
	corresponding C pointer.
    %
    \item[\mxfn{mx\_get\_pointer\_from\_handle()}] -
        Converts a C pointer into the corresponding handle.
    %
\end{description}

\subsection{Log file support}

\begin{description}
    \item[\mxfn{mx\_log\_open()}] - Opens a log file.
    %
    \item[\mxfn{mx\_log\_close()}] - Closes the log file.
    %
    \item[\mxfn{mx\_log\_message()}] - Writes a message to the log file.
    %
    \item[\mxfn{mx\_log\_timestamp()}] - Writes a timestamp to the log file.
    %
\end{description}

\subsection{Math functions}

\begin{description}
    \item[\mxfn{mx\_divide\_safely()}] - Divides one \textit{double} value by
	another while testing for and avoiding division by zero.
    %
    \item[\mxfn{mx\_difference()}] - Computes a relative difference function.
    %
    \item[\mxfn{mx\_round()}] - Rounds a \textit{double} value to the nearest
	\textit{long} value.
    %
    \item[\mxfn{mx\_round\_up()}] -
        This function rounds up to the next higher
	\textit{long} value.  A small threshold value is subtracted from
	the number before rounding to prevent getting the wrong number
	due to previous roundoff errors.
    %
    \item[\mxfn{mx\_round\_down()}] -
        This function rounds down to the next lower
	\textit{long} value.  A small threshold value is added to
	the number before rounding to prevent getting the wrong number
	due to previous roundoff errors.
    %
    \item[\mxfn{mx\_byteswap()}] - Swaps the low order and high order bytes
	of a 16 bit integer.
\end{description}

\subsection{String functions}

\begin{description}
    \item[\mxfn{strlcpy()}] - A replacement for \textit{strncpy()} that ensures
	that the string fits into the buffer and is NULL terminated.
    %
    \item[\mxfn{strlcat()}] - A replacement for \textit{strncat()} that ensures
	that the string fits into the buffer and is NULL terminated.
    %
    \item[\mxfn{mx\_match()}] - Performs a simple wildcard match of a pattern
	to a string.  It does not implement full regular expressions.
    %
    \item[\mxfn{mx\_skip\_string\_fields()}] - Skips over the requested number
	of fields in a character string that are separated by standard
	MX record field separators (space, tab, newline).
    %
\end{description}

\subsection{Syslog support}

\begin{description}
    \item[\mxfn{mx\_install\_syslog\_handler()}] - Arranges for messages from
	MX output handlers to be sent to the Unix syslog daemon.  The
	output may be configured to be instead of or in addition to
	messages to \textit{stderr}.
    %
\end{description}

\subsection{Version number reporting functions}

These functions return information about the version of MX that is running.

\begin{description}
    \item[\mxfn{mx\_get\_major\_version()}] -
        For MX version 1.4.1, this would return 1.
    %
    \item[\mxfn{mx\_get\_minor\_version()}] -
        For MX version 1.4.1, this would return 4.
    %
    \item[\mxfn{mx\_get\_update\_version()}] -
        For MX version 1.4.1, this would return 1.
    %
    \item[\mxfn{mx\_get\_version\_date()}] - This returns the date of the last 
	modification to the MX library such as ``May 15, 2007''.
    %
    \item[\mxfn{mx\_get\_version\_string()}] -
        This returns a complete version string
	for MX such as ``MX version 1.4.1 (May 15, 2007)''.
    %
\end{description}

\subsection{Miscellaneous utility functions}

\begin{description}
    \item[\mxfn{mx\_free()}] -
        Calls \textit{free()} and then makes sure that the
	pointer we just freed has been set to NULL.
    %
    \item[\mxfn{mx\_username()}] -
        Returns the alphanumeric name of the current user.
    %
    \item[\mxfn{mx\_get\_max\_file\_descriptors()}] -
        This finds out the maximum
	number of file descriptors that the current process is allowed
	to use.
    %
    \item[\mxfn{mx\_current\_time\_string()}] -
        Returns an alphanumeric representation of the current time.
	This is essentially the output of \textit{ctime()}
	with the newline at the end removed.
    %
    \item[\mxfn{mx\_standard\_signal\_error\_handler()}] -
        This function is used by
	many MX programs to provide a standard response to a program crash.
    %
    \item[\mxfn{mx\_stack\_traceback()}] -
        This function does its best to provide
	a traceback of the function call stack at the time of invocation.
	The stack traceback may be incorrect if the crash was messy enough
	to corrupt the stack frames.  This function is not supported
	on all MX platforms.
    %
\end{description}

%--------------------------------------------------------------------------

\section{User I/O Functions}

\subsection{Keyboard handling functions}

These functions are often used to allow user's to interrupt long
running operations.

\begin{description}
    \item[\mxfn{mx\_getch()}] -
        Gets a single character from the user's keyboard.
    %
    \item[\mxfn{mx\_kbhit()}] -
        Checks to see if the user has typed a character on the keyboard.
    %
\end{description}

\subsection{User interrupt functions}

\begin{description}
    \item[\mxfn{mx\_user\_requested\_interrupt()}] - Checks to see if the user
	has requested to interrupt the operation that is currently
	in progress.
    %
    \item[\mxfn{mx\_set\_user\_interrupt\_function()}] -
        Can be used to check for
	user interrupts from an alternate source.  Generally used
	by GUIs to allow an ``Abort'' button to be set up.
    %
    \item[\mxfn{mx\_default\_user\_interrupt\_function()}] -
        This is the default
	function used by \mxfn{mx\_user\_requested\_interrupt()}.
	It uses \mxfn{mx\_kbhit()} and \mxfn{mx\_getch()}].
    %
\end{description}

\subsection{Debugging functions}

\begin{description}
    \item[\mxfn{MX\_DEBUG()}] - A C macro that is used extensively to generate
	debugging messages.  It uses a trick to get something equivalent
	to a varargs macro since ANSI C does not explicitly support
	varargs macros.  See the description in \textbf{libMx/mx\_util.h}
	for more information.
    %
    \item[\mxfn{mx\_set\_debug\_level()}] - Sets the current debugging level.
    %
    \item[\mxfn{mx\_get\_debug\_level()}] - Gets the current debugging level.
    %
\end{description}

\begin{description}
    \item[\mxfn{mx\_set\_debug\_output\_function()}] - Can be used to redirect
	debugging output to an alternate destination.  Generally used
	by GUIs to capture the text.
    %
    \item[\mxfn{mx\_debug\_default\_output\_function()}] - This is the default
	function used by \mxfn{MX\_DEBUG()} output.  It merely sends
	the output to \textit{stderr}.
    %
\end{description}

\subsection{Information display functions}

\begin{description}
    \item[\mxfn{mx\_info()}] - Displays an informational message to the user.
    %
    \item[\mxfn{mx\_info\_dialog()}] - Displays an informational message to the
	user and waits for the user to acknowledge the message.  For
	text mode clients, the user hits a key on the keyboard, while
	for GUI clients, the user typically clicks on an ``OK'' button.
    %
\end{description}

\begin{description}
    \item[\mxfn{mx\_set\_info\_output\_function()}] - Can be used to redirect
	informational output to an alternate destination.  Generally used
	by GUIs to capture the text.
    %
    \item[\mxfn{mx\_info\_default\_output\_function()}] - This is the default
	function used by \mxfn{mx\_info()} output.  It merely sends
	the output to \textit{stderr}.
    %
\end{description}

\begin{description}
    \item[\mxfn{mx\_set\_info\_dialog\_function()}] - Can be used to redirect
	a user dialog to an alternate destination.  Generally used
	by GUIs to display a dialog box with an ``OK'' button.
    %
    \item[\mxfn{mx\_info\_default\_dialog\_function()}] - This is the default
	function used by \mxfn{mx\_info\_dialog()}].  It merely sends
	the output to \textit{stderr} and waits for the user to
	hit a key using \mxfn{mx\_kbhit()}.
    %
\end{description}

\subsection{Warning message functions}

\begin{description}
    \item[\mxfn{mx\_warning()}] - Displays an warning message to the user.
    %
    \item[\mxfn{mx\_set\_warning\_output\_function()}] - Can be used to redirect
	warning messages to an alternate destination.  Generally used
	by GUIs to capture the text.
    %
    \item[\mxfn{mx\_warning\_default\_output\_function()}] - This is the default
	function used by \mxfn{mx\_warning()} output.  It merely sends
	the output to \textit{stderr}.
    %
\end{description}

\subsection{Error reporting functions}

These functions use an \textit{mx\_status\_type} structure which contains
an error code, the name of the function that the error occurred in,
and a programmer specified error message.

\begin{description}
    \item[\mxfn{mx\_error()}] - Used by most MX functions to report errors
	to the calling routine.  It also displays an error message
	to the user.
    %
    \item[\mxfn{mx\_error\_quiet()}] - Used occasionally to report an error
	back to the calling routine \textit{without} displaying an
	error message to the user.
    %
    \item[\mxfn{mx\_strerror()}] - Converts an MX error code to a verbose
	error description.
    %
    \item[\mxfn{MX\_SUCCESSFUL\_RESULT}] - This is a macro that is used by
	MX functions to return a success status to the calling routine.
	This almost always takes the form of
	``\texttt{return MX\_SUCCESSFUL\_RESULT;}''
	in the source code.
    %
\end{description}

\begin{description}
    \item[\mxfn{mx\_set\_error\_output\_function()}] - Can be used to redirect
	error messages to an alternate destination.  Generally used
	by GUIs to capture the text.
    %
    \item[\mxfn{mx\_error\_default\_output\_function()}] - This is the default
	function used by \mxfn{mx\_error()} output.  It merely sends
	the output to \textit{stderr}.
    %
\end{description}

%****************************************************************************

\chapter{Device API}

%-----------------------------------------------------------------------------

\section{MX Amplifier Functions}

\begin{description}
    \item[\mxfn{mx\_amplifier\_get\_gain()}] - Get the amplifier gain.
    %
    \item[\mxfn{mx\_amplifier\_set\_gain()}] - Set the amplifier gain.
    %
    \item[\mxfn{mx\_amplifier\_get\_offset()}] -
        Get the amplifier offset in units of the output voltage.
    %
    \item[\mxfn{mx\_amplifier\_set\_offset()}] -
        Set the amplifier offset in units of the output voltage.
    %
    \item[\mxfn{mx\_amplifier\_get\_time\_constant()}] -
        Get the amplifier time constant in units of seconds.
    %
    \item[\mxfn{mx\_amplifier\_set\_time\_constant()}] -
        Set the amplifier time constant in units of seconds.
    %
    \item[\mxfn{mx\_amplifier\_get\_gain\_range()}] -
        Reports the minimum and maximum allowed gains for this amplifier.
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX Analog Input Functions}

\begin{description}
    \item[\mxfn{mx\_analog\_input\_read()}] -
    	Reports the ADC value in user units.
    %
    \item[\mxfn{mx\_analog\_input\_read\_raw\_long()}] -
    	Returns the raw value from an ADC as a \textit{long} integer.
    %
    \item[\mxfn{mx\_analog\_input\_read\_raw\_double()}] -
    	Returns the raw value from an ADC as a \textit{double} value.
    %
    \item[\mxfn{mx\_analog\_input\_get\_dark\_current()}] -
    	Returns the MX ADC dark current as a \textit{double} value.
	If the 0x1000 bit
	is set in the \textit{analog\_input\_flags} field, then this
	function returns the dark current per second.
    %
    \item[\mxfn{mx\_analog\_input\_set\_dark\_current()}] -
    	Sets the MX ADC dark current to the supplied \textit{double} value.
	If the 0x1000 bit
	is set in the \textit{analog\_input\_flags} field, then the
	supplied value is expected to be the dark current per second.
\end{description}

%-----------------------------------------------------------------------------

\section{MX Analog Output Functions}

\begin{description}
    \item[\mxfn{mx\_analog\_output\_read()}] -
        Reads the setpoint for a DAC in user units.
    %
    \item[\mxfn{mx\_analog\_output\_write()}] - Write to a DAC in user units.
    %
    \item[\mxfn{mx\_analog\_output\_read\_raw\_long()}] -
        Reads the raw setpoint for a DAC as a \textit{long} integer.
    %
    \item[\mxfn{mx\_analog\_output\_write\_raw\_long()}] -
        Sets the raw setpoint for a DAC to the supplied \textit{long} integer.
    %
    \item[\mxfn{mx\_analog\_output\_read\_raw\_double()}] -
        Reads the raw setpoint for a DAC as a \textit{double} value.
    %
    \item[\mxfn{mx\_analog\_output\_write\_raw\_double()}] -
        Sets the raw setpoint for a DAC to the supplied \textit{double} value.
\end{description}

%-----------------------------------------------------------------------------

\section{MX Area Detector Functions}

\subsection{Image size and format functions}

\begin{description}
    \item[\mxfn{mx\_area\_detector\_get\_image\_format()}] -
        Returns the currently configured image format of the area detector
	using the MXT\_IMAGE\_FORMAT definitions from
	\textbf{mx/libMx/mx\_image.h}.
    %
    \item[\mxfn{mx\_area\_detector\_get\_image\_format()}] -
        Changes the image format for the area detector
	using the MXT\_IMAGE\_FORMAT definitions from
	\textbf{mx/libMx/mx\_image.h}.
	This function is not supported for many types of area detectors.
    %
    \item[\mxfn{mx\_area\_detector\_get\_maximum\_framesize()}] -
        Returns the maximum allowed framesize for the area detector.
    %
    \item[\mxfn{mx\_area\_detector\_get\_framesize()}] -
        Returns the current framesize for the area detector.
    %
    \item[\mxfn{mx\_area\_detector\_set\_framesize()}] -
        Sets the current framesize for the area detector.
	If the requested framesize is not available, the new framesize
	will be the nearest available framesize.
    %
    \item[\mxfn{mx\_area\_detector\_get\_binsize()}] -
        Returns the current binsize for the area detector.
    %
    \item[\mxfn{mx\_area\_detector\_set\_binsize()}] -
        Sets the current binsize for the area detector.
	If the requested binsize is not available, the new binsize
	will be the nearest available binsize.
    %
    \item[\mxfn{mx\_area\_detector\_get\_bytes\_per\_frame()}] -
        Reports the number of bytes per frame for the current image size
	and format.
    %
    \item[\mxfn{mx\_area\_detector\_get\_bytes\_per\_pixel()}] -
        Reports the number of bytes per pixel for the current image format.
	This number is not necessarily an integer.
    %
    \item[\mxfn{mx\_area\_detector\_get\_bits\_per\_pixel()}] -
        Reports the number of bits per pixel for the current image format.
	This number is not necessarily a multiple of 8.
\end{description}

\subsection{Image correction functions}

\begin{description}
    \item[\mxfn{mx\_area\_detector\_get\_correction\_flags()}] -
        Returns a bitmap specifying which individual types of image
	corrections are currently enabled.
    %
    \item[\mxfn{mx\_area\_detector\_set\_correction\_flags()}] -
        Uses the supplied bitmap to determine which individual types
	of image corrections are currently enabled.
    %
    \item[\mxfn{mx\_area\_detector\_measure\_correction\_frame()}] -
        Measures the requested type of correction frame and leaves
	the frame in the matching image buffer, ready to be used
	for corrections.
    %
    \item[\mxfn{mx\_area\_detector\_measure\_dark\_current\_frame()}] -
        Acquires a dark current frame and places the frame in the
	dark current correction image buffer.
    %
    \item[\mxfn{mx\_area\_detector\_measure\_flood\_field\_frame()}] -
        Acquires a flood field frame and places the frame in the
	flood field correction image buffer.
    %
    \item[\mxfn{mx\_area\_detector\_get\_use\_scaled\_dark\_current\_flag()}] -
        Gets the current value of the \textit{use\_scaled\_dark\_current\_flag}
	field.  If this flag is set, a dark current image acquired for
	a different measurement time can be used to correct the image by
	rescaling the pixel values to match the current measurement time of
	the area detector.
    %
    \item[\mxfn{mx\_area\_detector\_set\_use\_scaled\_dark\_current\_flag()}] -
    	Assigns a new value to the \textit{use\_scaled\_dark\_current\_flag}
	field.
\end{description}

\subsection{Imaging sequence functions}

\begin{description}
    \item[\mxfn{mx\_area\_detector\_get\_total\_acquisition\_time()}] -
        Returns the amount of time in seconds devoted to image acquisition
	in the currently configured image sequence.
    %
    \item[\mxfn{mx\_area\_detector\_get\_total\_sequence\_time()}] -
        Returns the amount of time in seconds required to execute the
	currently configured image sequence.
    %
    \item[\mxfn{mx\_area\_detector\_get\_detector\_readout\_time()}] -
        Returns the amount of time in seconds required to read out
	a single image frame from the currently configured sequence.
    %
    \item[\mxfn{mx\_area\_detector\_get\_sequence\_start\_delay()}] -
        For some area detectors, it is possible to configure a delay
	of the start of a sequence.  This function returns the value
	of that delay in seconds.
    %
    \item[\mxfn{mx\_area\_detector\_get\_sequence\_parameters()}] -
        Returns a structure containing the currently configured
	image sequence for the area detector.
    %
    \item[\mxfn{mx\_area\_detector\_set\_sequence\_parameters()}] -
        Reconfigures the area detector for the requested
	image sequence parameters.
    %
    \item[\mxfn{mx\_area\_detector\_set\_one\_shot\_mode()}] -
        Configures the area detector to acquire a single frame using either
	an internal or an external trigger.
    %
    \item[\mxfn{mx\_area\_detector\_set\_continuous\_mode()}] -
        Configures the area detector to acquire an unending sequence of
	image frames into the same buffer until told to stop.
	The sequence can be started using either an internal
	or an external trigger.
    %
    \item[\mxfn{mx\_area\_detector\_set\_multiframe\_mode()}] -
        Configures the area detector to acquire the requested number of
	image frames into a matching number of image buffers.
	The sequence can be started using either an internal
	or an external trigger.
    %
    \item[\mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode()}] -
        Configures the area detector to acquire an unending sequence of
	image frames into the specified number of image buffers.
	When the last frame buffer is reached, the sequence wraps around
	to overwrite the first frame buffer.
	The sequence can be started using either an internal
	or an external trigger.
    %
    \item[\mxfn{mx\_area\_detector\_set\_strobe\_mode()}] -
        Configures the area detector to acquire the requested number of
	image frames into a matching number of image buffers.
	The sequence is driven by external trigger pulses.  When the
	next external trigger is received, the next image frame will
	be acquired.
    %
    \item[\mxfn{mx\_area\_detector\_set\_bulb\_mode()}] -
        Configures the area detector to acquire the requested number of
	image frames into a matching number of image buffers.
	The external trigger input is used as a gate signal.  When the
	gate is turned on, the area detector starts to acquire the next
	image in the sequence.  The image acquisition for that frame
	lasts until the gate is turned off.  Then, the next frame will
	begin once the gate is turned back on.
	\newline
	\textit{Warning: For the AVIEX PCCD-170170 detector, this
	sequence mode can only run for 1 frame.}
\end{description}

\subsection{Aviex-specific sequence types}

The Aviex PCCD-170170 area detector has three sequence types that are
specific to it.
%
\begin{description}
    \item[\mxfn{mx\_area\_detector\_set\_geometrical\_mode()}] -
        The first frame in the sequence is acquired using the specified
	exposure time and the detector waits for the specified gap time
	before starting the next frame.  On subsequent frames, the
	exposure time and gap time for a given frame are those for the
	previous frame multiplied by an exposure time multiplier and
	a gap time multiplier.  The sequence can be started using either
	an internal trigger or an external trigger.
    %
    \item[\mxfn{mx\_area\_detector\_set\_streak\_camera\_mode()}] -
        In this mode, the area detector acquires a new single line of the
	image using the requested exposure time for the requested number
	of lines.  Once all the lines have been acquired, the resulting
	data is returned as one long image.  The sequence can be started
	using either an internal trigger or an external trigger.
    %
    \item[\mxfn{mx\_area\_detector\_set\_subimage\_mode()}] -
        In this mode, the full frame of the detector is broken up into
	several strips called \textit{subimages} which are each acquired
	at a different time.  When all of the requested subimages have
	been acquired, the resulting data is returned as one long image.
	The sequence can be started
	using either an internal trigger or an external trigger.
\end{description}

\subsection{Trigger configuration functions}

\begin{description}
    \item[\mxfn{mx\_area\_detector\_get\_trigger\_mode()}] -
        Reports whether the detector is configured for internal trigger mode
	or external trigger mode.
    %
    \item[\mxfn{mx\_area\_detector\_set\_trigger\_mode()}] -
        Configures the detector for the requested choice of either
	internal trigger mode or external trigger mode.
\end{description}

\subsection{Image acquisition functions}

This set of functions is used to control image acquisition and monitor
the status of an imaging sequence.
%
\begin{description}
    \item[\mxfn{mx\_area\_detector\_arm()}] -
        Makes sure that the area detector is ready to 
	execute the previously requested sequence.  If the area detector
	is in \textit{external trigger} mode, the sequence will start
	when the next external trigger arrives.
    %
    \item[\mxfn{mx\_area\_detector\_trigger()}] -
    	If the detector is in \textit{internal trigger} mode, this function
	starts the imaging sequence.  If the detector is in 
	\textit{external trigger} mode, then this function does nothing.
    %
    \item[\mxfn{mx\_area\_detector\_start()}] -
    	This function is merely a convenience function that calls
	\mxfn{mx\_area\_detector\_arm()} followed by
	\mxfn{mx\_area\_detector\_trigger()}.
    %
    \item[\mxfn{mx\_area\_detector\_stop()}] -
        If an imaging sequence is in progress, this function tells the
	area detector to end the sequence when it has finished acquiring
	the current frame.
    %
    \item[\mxfn{mx\_area\_detector\_abort()}] -
        If an imaging sequence is in progress, this function tells the
	area detector to end the sequence as quickly as possible, even
	if this means losing the image frame currently being acquired.
    %
    \item[\mxfn{mx\_area\_detector\_is\_busy()}] -
        The function reports whether or not an imaging sequence is
	in progress.
    %
    \item[\mxfn{mx\_area\_detector\_get\_last\_frame\_number()}] -
        The function reports the number of the frame buffer containing
	the most recently acquired frame.  If the area detector is
	currently in continuous or circular multiframe mode, the
	frame buffer number will wrap back to 0 when the sequence wraps
	back to the first frame buffer.
    %
    \item[\mxfn{mx\_area\_detector\_get\_total\_num\_frames()}] -
        Reports the total number of frames acquired
	since the counter was reset.  Usually, this will either be
	the total number of frames acquired since the MX server
	was started or it will be the total number of frames
	acquired since the computer booted.
    %
    \item[\mxfn{mx\_area\_detector\_get\_status()}] -
        Reports the current detector status flags.  In general, this
	will at least include the \textit{busy} flag.
    %
    \item[\mxfn{mx\_area\_detector\_get\_extended\_status()}] -
        Reports the current detector status flags as well as the last
	frame number acquired and the total number of frames acquired.
	For some area detectors, calling this function will be more
	efficient than separately calling the individual functions
	listed above.
\end{description}

\subsection{Image setup and transfer functions}

\begin{description}
    \item[\mxfn{mx\_area\_detector\_setup\_frame()}] -
        This function makes sure that an image buffer has
	been allocated that is large enough to contain the next frame
	to be acquired.  If the image buffer is already large enough,
	then this function does nothing.
    %
    \item[\mxfn{mx\_area\_detector\_readout\_frame()}] -
        On some systems, the image data is initially saved into an
	inaccessible buffer either on the imaging board or in kernel
	memory belonging to the operating system.
        This function copies the image frame data from the inaccessible
	system buffer into an MX controlled image buffer in the address
	space of the MX process.  If the initial frame buffer is in
	memory that is already controlled by MX, then this function
	does nothing.
    %
    \item[\mxfn{mx\_area\_detector\_correct\_frame()}] -
        This function performs the set of image corrections specified
	by the correction flags bitmap.
    %
    \item[\mxfn{mx\_area\_detector\_transfer\_frame()}] -
        Transfers the requested type of remote image frame to the
	local image frame buffer.  For network-based systems, this is the
	step that sends the image data across the network.
    %
    \item[\mxfn{mx\_area\_detector\_load\_frame()}] -
        Tells the MX server to load the requested frame buffer from 
	a file which is located on the server.
    %
    \item[\mxfn{mx\_area\_detector\_save\_frame()}] -
        Tells the MX server to save the requested frame buffer to 
	a file which is located on the server.
    %
    \item[\mxfn{mx\_area\_detector\_copy\_frame()}] -
        Tells the MX server to copy image data from one internal frame
	buffer to another.  This is used for things like moving a 
	recently acquired or loaded image frame to another buffer
	such as the dark current frame or the flood field frame.
    %
    \item[\mxfn{mx\_area\_detector\_get\_frame()}] -
        Transfers the contents of the requested frame number from
	the server to the supplied MX\_IMAGE\_FRAME object.
    %
    \item[\mxfn{mx\_area\_detector\_get\_sequence()}] -
        Transfers the contents of the requested number of image frames
	on the server to the supplied MX\_IMAGE\_SEQUENCE object.
\end{description}

\subsection{ROI functions}

\begin{description}
    \item[\mxfn{mx\_area\_detector\_get\_roi()}] -
        Returns the boundaries of the specified region of interest.
    %
    \item[\mxfn{mx\_area\_detector\_set\_roi()}] -
        Sets the boundaries of the specified region of interest.
    %
    \item[\mxfn{mx\_area\_detector\_get\_roi\_frame()}] -
        Transfers the contents of the requested ROI from the current
	image frame buffer on the server to the supplied local
	MX\_IMAGE\_FRAME object.
\end{description}

%-----------------------------------------------------------------------------

\section{MX Autoscale Functions}

In MX, \textit{autoscale} devices are pseudodevices used by the 
\textit{autoscale\_scaler} device driver.  Autoscaling scalers
set upper and lower limits on their count rate so that they can
stay within the most linear part of their dynamic range.

If a string record with the specific name\textbf{mx\_scan\_fault}
is defined, MX step scans
will check after each step to see if any scan faults have occurred.
The contents of the string in the define what scan faults will be checked
for.  For example, if \textbf{mx\_scan\_fault} contains the string
``autoscale:I0'', this tells the scan that I0 is an autoscaling scaler
and that the scan should check for autoscale faults using that record.

An autoscale fault is declared if the measured intensity of the scaler is 
not within the upper and lower limits of the scaler record.  If the 
intensity is not between those limits, the
autoscaling scaler tells its associated \textit{autoscale} record to make
whatever changes to amplifier gains or inserted filters are necessary
to bring the raw autoscaled value back within the upper and lower limits.
After this is done, the scan step is retried.  If the measured intensity
is still not between the limits, then the autoscaling scaler will try 
making further changes to the gain and/or filter settings until the
fault is fixed or the maximum or minimum gain or filter settings are reached.

The autoscale record itself contains the logic required to implement
the feedback control.  You can find more information about autoscale
records and other associated records in the
``Autoscale Related Pseudoscalers'' section and the ``Autoscale Devices''
chapter of the MX Driver Reference Manual.  Those sections include examples
of how to set up the appropriate records in your MX database.

Here are the functions used by autoscale devices.  The only reason
for which you may need to know what these functions do is if you
plan to implement a new type of autoscale fault.
\begin{description}
    \item[\mxfn{mx\_autoscale\_read\_monitor()}] -
    \item[\mxfn{mx\_autoscale\_get\_change\_request()}] -
    \item[\mxfn{mx\_autoscale\_change\_control()}] -
    \item[\mxfn{mx\_autoscale\_get\_offset\_index()}] -
    \item[\mxfn{mx\_autoscale\_set\_offset\_index()}] -
    \item[\mxfn{mx\_autoscale\_get\_offset\_array()}] -
    \item[\mxfn{mx\_autoscale\_set\_offset\_array()}] -
    \item[\mxfn{mx\_autoscale\_get\_limits()}] -
    \item[\mxfn{mx\_autoscale\_set\_limits()}] -
    \item[\mxfn{mx\_autoscale\_compute\_dynamic\_limits()}] -
\end{description}
\ \newline\textbf{FIXME - I need to refresh my memory
of what all of these functions do.}

%-----------------------------------------------------------------------------

\section{MX CCD Functions}

\textbf{\textit{WARNING: The CCD class has been replaced
by the new Area Detector class.}}
\newline
The existing \textit{remote\_marccd}
CCD driver will be replaced by a new \textit{marccd} Area Detector driver
at some point in the near future.

%-----------------------------------------------------------------------------

\section{MX Digital Input Functions}

\begin{description}
    \item[\mxfn{mx\_digital\_input\_read()}] - Read a digital input register.
\end{description}

%-----------------------------------------------------------------------------

\section{MX Digital Output Functions}

\begin{description}
    \item[\mxfn{mx\_digital\_output\_read()}] -
        Read the output value for a digital output register.
    %
    \item[\mxfn{mx\_digital\_output\_write()}] -
    	Write to a digital output register.
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX Encoder Functions}

\begin{description}
    \item[\mxfn{mx\_encoder\_read()}] - Read the encoder position.
    %
    \item[\mxfn{mx\_encoder\_write()}] - Write the encoder position.
    %
    \item[\mxfn{mx\_encoder\_get\_overflow\_status()}] -
        Checks for overflow or underflow.
    %
    \item[\mxfn{mx\_encoder\_reset\_overflow\_status()}] -
        Clears any overflow or underflow flags.
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX Multichannel Analyzer Functions}

\subsection{Counting Functions}

\begin{description}
    \item[\mxfn{mx\_mca\_start()}] - Starts the MCA counting.
    %
    \item[\mxfn{mx\_mca\_stop()}] - Stops the MCA from counting.
    %
    \item[\mxfn{mx\_mca\_start\_without\_preset()}] -
        Starts the MCA counting without a preset.
	The MCA will continue counting until it is asked to stop.
    %
    \item[\mxfn{mx\_mca\_start\_with\_preset()}] -
        Starts the MCA counting with a preset.  You must specify
	the type of preset and a value for the preset when you
	invoke this function.
    %
    \item[\mxfn{mx\_mca\_start\_for\_preset\_live\_time()}] -
        Starts the MCA counting for a preset live time interval.
    %
    \item[\mxfn{mx\_mca\_start\_for\_preset\_real\_time()}] -
        Starts the MCA counting for a preset real time interval.
    %
    \item[\mxfn{mx\_mca\_start\_for\_preset\_count()}] -
        Starts the MCA counting until the preset count is reached
	in a user specified window.
    %
    \item[\mxfn{mx\_mca\_is\_busy()}] - Checks to see if the MCA is currently
    	acquiring data.
    %
    \item[\mxfn{mx\_mca\_is\_new\_data\_available()}] -
        Checks to see if the MCA spectrum has changed since the last time
	it was read.
    %
\end{description}

\subsection{Data Handling Functions}

\begin{description}
    \item[\mxfn{mx\_mca\_clear()}] - Clears the spectrum in the MCA.
    %
    \item[\mxfn{mx\_mca\_read()}] - Reads the spectrum from the MCA.
    %
    \item[\mxfn{mx\_mca\_get\_roi\_integral()}] -
        Gets the integrated counts from the MCA region of interest.
    %
    \item[\mxfn{mx\_mca\_get\_roi\_integral\_array()}] -
        Gets an array containing the integrated counts of all
	regions of interest for the MCA.
    %
    \item[\mxfn{mx\_mca\_get\_channel()}] -
        Gets the value from the specified MCA channel.
    %
    \item[\mxfn{mx\_mca\_get\_real\_time()}] - Get the MCA real time.
    %
    \item[\mxfn{mx\_mca\_get\_live\_time()}] - Get the MCA live time.
    %
    \item[\mxfn{mx\_mca\_get\_counts()}] - Gets the integrated number
    	of counts within the MCA preset count window.
    %
    \item[\mxfn{mx\_mca\_get\_input\_count\_rate()}] - Gets the 
    	input count rate in counts per second for the MCA.
    %
    \item[\mxfn{mx\_mca\_get\_output\_count\_rate()}] - Gets the 
    	output count rate in counts per second for the MCA.
    %
\end{description}

\subsection{Parameter Setting Functions}

\begin{description}
    \item[\mxfn{mx\_mca\_get\_parameter()}] -
        Reads the value of one or more MCA parameters from the controller.
    %
    \item[\mxfn{mx\_mca\_set\_parameter()}] -
        Sets the value of one or more MCA parameters in the controller.
    %
    \item[\mxfn{mx\_mca\_get\_preset\_type()}] -
        Gets the type of preset used by the MCA.
    %
    \item[\mxfn{mx\_mca\_set\_preset\_type()}] -\
        Sets the type of preset used by the MCA.
    %
    \item[\mxfn{mx\_mca\_get\_preset\_count\_region()}] -
        Gets the boundaries of the current preset count region of the MCA.
    %
    \item[\mxfn{mx\_mca\_set\_preset\_count\_region()}] -
        Sets the boundaries of the preset count region of the MCA.
    %
    \item[\mxfn{mx\_mca\_get\_roi()}] -
        Gets the boundaries of the specified MCA region of interest.
    %
    \item[\mxfn{mx\_mca\_set\_roi()}] -\
        Sets the boundaries of the specified MCA region of interest.
    %
    \item[\mxfn{mx\_mca\_get\_roi\_array()}] -
        Gets the boundaries of all regions of interest for the MCA.
    %
    \item[\mxfn{mx\_mca\_set\_roi\_array()}] -
        Sets the boundaries of all regions of interest for the MCA.
    %
    \item[\mxfn{mx\_mca\_get\_num\_channels()}] -
        Gets the number of channels to be used by the MCA.
    %
    \item[\mxfn{mx\_mca\_set\_num\_channels()}] -
        Sets the number of channels to be used by the MCA.
    %
\end{description}

\subsection{Soft ROI Functions}

The soft ROI functions are used to provide an alternate way of implementing
region of interest functionality for multichannel analyzers.  Soft ROIs
do not depend on the presence of hardware ROIs in the MCA.  Instead,
the ROI integrals are computed within the associated MX driver itself.
Typically, this will be used for MCAs that do not provide hardware ROIs.
However, there is nothing stopping you from using soft ROIs with MCAs
that also have hardware ROIs.  For example, you may want to
do this if the hardware only has one hardware ROI, but you want more than
one ROI for your measurement.  Typically, the processing of soft ROIs will be
slower than that for hardware ROIs since the entire MCA spectrum must be
read into the MX driver, so that the MX driver can compute the integral itself.

Keep in mind that the hardware ROIs and the software ROIs have no connection
to each other.  For example, in general, hardware ROI 4 will
have different limits and a different integral from software ROI 4.

\begin{description}
    \item[\mxfn{mx\_mca\_get\_soft\_roi()}] -
        Gets the boundaries of the specified software region of interest.
    %
    \item[\mxfn{mx\_mca\_set\_soft\_roi()}] -\
        Sets the boundaries of the specified software region of interest.
    %
    \item[\mxfn{mx\_mca\_get\_soft\_roi\_integral()}] -
        Gets the integrated counts from the software region of interest.
    %
    \item[\mxfn{mx\_mca\_get\_soft\_roi\_integral\_array()}] -
        Gets an array containing the integrated counts of all
	software regions of interest for the MCA.
    %
\end{description}

\subsection{Energy Scale Functions}

These functions can be used to handle the MCA X axis in units of energy
rather than channel number.

\begin{description}
    \item[\mxfn{mx\_mca\_get\_energy\_scale()}] -
        Gets the scale factor for converting from MCA channel number to energy.
    %
    \item[\mxfn{mx\_mca\_set\_energy\_scale()}] -
        Sets the scale factor for converting from MCA channel number to energy.
    %
    \item[\mxfn{mx\_mca\_get\_energy\_offset()}] -
        Gets the offset for converting from MCA channel number to energy.
    %
    \item[\mxfn{mx\_mca\_set\_energy\_offset()}] -
        Sets the offset for converting from MCA channel number to energy.
    %
    \item[\mxfn{mx\_mca\_get\_energy\_axis\_array()}] -
    	Returns an array that contains the energy corresponding to
	each MCA channel number.
\end{description}

%-----------------------------------------------------------------------------

\section{MX Multichannel Encoder Functions}

\begin{description}
    \item[\mxfn{mx\_mce\_read()}] -
        Reads the position values from a multichannel encoder.
    %
    \item[\mxfn{mx\_mce\_get\_overflow\_status()}] -
        Checks to see if the MCE has overflowed.
    %
    \item[\mxfn{mx\_mce\_reset\_overflow\_status()}] -
        Clears the overflow status of an MCE.
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX Multichannel Scaler Functions}

\subsection{Counting Functions}

\begin{description}
    \item[\mxfn{mx\_mcs\_start()}] - Starts the MCS counting.
    %
    \item[\mxfn{mx\_mcs\_stop()}] - Stops the MCS from counting.
    %
    \item[\mxfn{mx\_mcs\_is\_busy()}] - Checks to see if the MCS is counting.
    %
\end{description}

\subsection{Data Handling Functions}

\begin{description}
    \item[\mxfn{mx\_mcs\_clear()}] - Clears the data in the MCS.
    %
    \item[\mxfn{mx\_mcs\_read\_all()}] - Reads all values from the MCS.
    %
    \item[\mxfn{mx\_mcs\_read\_scaler()}] -
        Reads the values from the specified scaler channel in the MCS.
    %
    \item[\mxfn{mx\_mcs\_read\_measurement()}] -
        Reads all the scaler values from the specified measurement in the MCS.
    %
    \item[\mxfn{mx\_mcs\_read\_timer()}] - Reads the timer channel from the MCS.
    %
\end{description}

\subsection{Parameter Setting Functions}

\begin{description}
    \item[\mxfn{mx\_mcs\_get\_mode()}] - Gets the counting mode for the MCS.
    %
    \item[\mxfn{mx\_mcs\_set\_mode()}] - Sets the counting mode for the MCS.
    %
    \item[\mxfn{mx\_mcs\_get\_measurement\_time()}] -
        Gets the preset measurement time for the MCS.
    %
    \item[\mxfn{mx\_mcs\_set\_measurement\_time()}] -
        Sets the preset measurement time for the MCS.
    %
    \item[\mxfn{mx\_mcs\_get\_measurement\_counts()}] -
        Gets the preset measurement count for the MCS.
    %
    \item[\mxfn{mx\_mcs\_set\_measurement\_counts()}] -
        Sets the preset measurement count for the MCS.
    %
    \item[\mxfn{mx\_mcs\_get\_num\_measurements()}] -
        Gets the number of measurements for the MCS.
    %
    \item[\mxfn{mx\_mcs\_set\_num\_measurements()}] -
        Sets the number of measurements for the MCS.
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX Motor Functions}

\subsection{Motor status functions}

\begin{description}
    \item[\mxfn{mx\_motor\_get\_position()}] -
        Gets the motor position in user units.
    %
    \item[\mxfn{mx\_motor\_get\_status()}] -
        Gets a 32-bit set of status flags that report the current state
	of the motor axis.\newline
	These bits include:
	%
	\begin{description}
	\item[\ ]\textit{busy} - is a move in progress?
	\item[\ ]\textit{positive limit hit}
	\item[\ ]\textit{negative limit hit}
	\item[\ ]\textit{home search succeeded}
	\item[\ ]\textit{following error}
	\item[\ ]\textit{drive fault}
	\item[\ ]\textit{axis disabled}
	\item[\ ]\textit{open loop}
	\item[\ ]\textit{controller disabled}
	\item[\ ]\textit{soft positive limit hit}
	\item[\ ]\textit{soft negative limit hit}
	\item[\ ]\textit{software error}
	\end{description}
    %
    \item[\mxfn{mx\_motor\_get\_extended\_status()}] -
        This function reports both the position of the motor and the motor
	status flags in one call.  In many situations, calling this function
	is more efficient performing than two separate calls to 
	\mxfn{mx\_motor\_get\_position()} and \mxfn{mx\_motor\_get\_status()}.
    %
\end{description}

\subsection{Alternate motor status functions}

These functions report the state of only a single bit in the status flag
described above.
%
\begin{description}
    \item[\mxfn{mx\_motor\_is\_busy()}] -
    Check to see if a commanded move is still
	in progress.
    %
    \item[\mxfn{mx\_motor\_positive\_limit\_hit()}] -
    	Checks to see if the positive limit switch has been hit.
    %
    \item[\mxfn{mx\_motor\_negative\_limit\_hit()}] -
    	Checks to see if the negative limit switch has been hit.
    %
\end{description}

\subsection{Motor motion functions}

\begin{description}
    \item[\mxfn{mx\_motor\_move\_absolute()}] -
    	Moves the motor to an absolute position in user units.
    %
    \item[\mxfn{mx\_motor\_move\_relative()}] -
    	Moves the motor by a relative distance in user units.
    %
    \item[\mxfn{mx\_motor\_array\_move\_absolute()}] -
    	Moves an array of motors to absolute positions in motor units.
    %
    \item[\mxfn{mx\_wait\_for\_motor\_stop()}] -
    	Waits for a motor move to complete.  Use one of the motor status
	functions if you want to check the motion status without blocking.
    %
    \item[\mxfn{mx\_wait\_for\_motor\_array\_stop()}] -
    	Waits for an array of motors to stop moving.
    %
\end{description}

\subsection{Motor abort functions}

\begin{description}
    \item[\mxfn{mx\_motor\_soft\_abort()}] -
        Tells the motor to stop moving in a ``nice'' fashion so that it
	does not lose track of its position.
    %
    \item[\mxfn{mx\_motor\_immediate\_abort()}] - Tells the motor to
        stop moving as soon as it can.
    %
\end{description}

\subsection{Setting the motor position}

\begin{description}
    \item[\mxfn{mx\_motor\_set\_position()}] -
        Sets the motor position in the controller to the requested value,
	if this is possible.
    %
\end{description}

Many controllers have restrictions on what values the position can be set
to or do not allow the position to be set at all.  A common restriction is
to only allow the current position to be set to zero.

\subsection{Home search}

\begin{description}
    \item[\mxfn{mx\_motor\_find\_home\_position()}] -
        Performs a home search in the requested direction.
    %
    \item[\mxfn{mx\_motor\_is\_at\_home\_switch()}] -
        Finds out whether the motor is currently at the home switch.
    %
\end{description}

\subsection{Continuous moves}

\begin{description}
    \item[\mxfn{mx\_motor\_constant\_velocity\_move()}] -
        Moves the motor in the requested direction until the motor move
	is aborted or until the motor reaches a hardware or software limit.
    %
\end{description}

\subsection{Motor speeds}

\begin{description}
    \item[\mxfn{mx\_motor\_get\_speed()}] -
    	Get the programmed motor speed from the controller.
    %
    \item[\mxfn{mx\_motor\_set\_speed()}] -
        Set the programmed motor speed in the controller.
    %
    \item[\mxfn{mx\_motor\_get\_base\_speed()}] -
        Get the programmed motor base speed from the controller.
    %
    \item[\mxfn{mx\_motor\_set\_base\_speed()}] -
        Set the programmed motor base speed in the controller.
    %
    \item[\mxfn{mx\_motor\_get\_maximum\_speed()}] -
        Get the programmed maximum speed from the controller.
    %
    \item[\mxfn{mx\_motor\_set\_maximum\_speed()}] -
        Set the programmed maximum speed in the controller.
    %
    \item[\mxfn{mx\_motor\_save\_speed()}] -
        Saves the current programmed motor speed so that it can be restored
	at a later date.
    %
    \item[\mxfn{mx\_motor\_restore\_speed()}] -
        Restores the motor speed most recently set
	by \mxfn{mx\_motor\_save\_speed()}.
    %
    \item[\mxfn{mx\_motor\_set\_speed\_between\_positions()}] -
        Sets the motor controller's speed such that it will travel
	between the two requested positions in the requested amount of time.
	This function is more general than \mxfn{mx\_motor\_set\_speed()}]
	since it will also work for pseudomotors whose positions
	are non-linear functions of the underlying real motor.
	However, the function works for real motors as well.
    %
\end{description}

\subsection{Motor acceleration}

\begin{description}
    \item[\mxfn{mx\_motor\_get\_acceleration\_type()}] -
        Used to find out what type of acceleration parameters are used
	by this controller.
    %
    \item[\mxfn{mx\_motor\_get\_acceleration\_parameters()}] -
	Get acceleration parameters used by the controller.
    %
    \item[\mxfn{mx\_motor\_set\_acceleration\_parameters()}] -
	Set acceleration parameters used by the controller.
    %
    \item[\mxfn{mx\_motor\_get\_acceleration\_time()}] -
	Calculates the total time required for the motor to accelerate
	from zero to the programmed speed for the motor.
    %
    \item[\mxfn{mx\_motor\_get\_acceleration\_distance()}] -
	Calculates the total distance required for the motor to accelerate
	from zero to the programmed speed for the motor.
    %
\end{description}

Motor acceleration is specified in a variety of different ways by different
controllers such as steps/sec**2, acceleration time, acceleration slope,
and so forth.  Currently, MX uses the form of the acceleration parameters
that is native to each controller rather than trying to force them all to
conform to one particular scheme such as steps/sec**2.

\subsection{Pseudomotor position calculation functions}

\begin{description}
 \item[\mxfn{mx\_motor\_compute\_pseudomotor\_position\_from\_real\_position()}]
	- This function takes the supplied real motor position and converts
	it to the corresponding pseudomotor position.
 %
 \item[\mxfn{mx\_motor\_compute\_real\_position\_from\_pseudomotor\_position()}]
	- This function takes the supplied pseudomotor position and converts
	it to the corresponding real motor position.
 %
\end{description}

\subsection{Scan related functions}

\begin{description}
    \item[\mxfn{mx\_motor\_compute\_extended\_scan\_range()}] -
	Uses the provided motor scan range to calculate an extended
	scan range that adds enough acceleration and deceleration distance
	such that the motor will already be moving at the slew speed
	when it reaches the start of the originally specified scan range.
\end{description}

\subsection{Getting and setting other motor parameters}

\begin{description}
    \item[\mxfn{mx\_motor\_get\_parameter()}] -
        Reads the value of one or more motor parameters from the controller.
    %
    \item[\mxfn{mx\_motor\_set\_parameter()}] -
        Sets the value of one or more motor parameters in the controller.
    %
\end{description}

This pair of functions is used to get and set other parameters that a given
record type may define for itself.  The speed and acceleration support above
is built on top of these two functions.  A variety of other parameters
such as PID servo loop gains can be controlled via these functions.

%-----------------------------------------------------------------------------

\section{MX Relay Functions}

\begin{description}
    \item[\mxfn{mx\_relay\_command()}] - Opens or closes the relay.
    %
    \item[\mxfn{mx\_get\_relay\_status()}] -
        Checks to see if the relay is open or closed.
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX Scaler Functions}

\subsection{Preset time functions}

\begin{description}
    \item[\mxfn{mx\_scaler\_read()}] -
        Reads the current value of the scaler without stopping it.
    %
    \item[\mxfn{mx\_scaler\_clear()}] -
        Stops the scaler, clears its value and rearms the scaler.
    %
    \item[\mxfn{mx\_scaler\_read\_and\_clear()}] -
        Combines the two operations above.
    %
    \item[\mxfn{mx\_scaler\_overflow\_set()}] -
        Checks to see if the scaler has overflowed its maximum value.
    %
\end{description}

\subsection{Preset count functions}

\begin{description}
    \item[\mxfn{mx\_scaler\_start()}] -
        Start the scaler counting to a preset value.  The scaler is assumed
	to generate a gate signal while it is counting.
    %
    \item[\mxfn{mx\_scaler\_stop()}] -
        Stop the scaler from counting and removes the gate signal.
    %
    \item[\mxfn{mx\_scaler\_is\_busy()}] -
        Is the scaler still counting?
    %
\end{description}

\subsection{Counter mode functions}

\begin{description}
    \item[\mxfn{mx\_scaler\_get\_mode()}] -
        Finds out whether the scaler is configured
	to be in preset time or preset count compatible mode.
    %
    \item[\mxfn{mx\_scaler\_set\_mode()}] - Sets the counter mode.
    %
    \item[\mxfn{mx\_scaler\_set\_modes\_of\_associated\_counters()}] -
        Ensures that the other counter channels in a module with
	multiple counters are set to counter modes that are compatible
	with the given scaler.
    %
\end{description}

\subsection{Dark current functions}

\begin{description}
    \item[\mxfn{mx\_scaler\_get\_dark\_current()}] -
        Gets the dark current for the given scaler in counts per second.
	This does not actually perform a dark current measurement.  It merely
	returns the previous value that was set by the
	\mxfn{mx\_scaler\_set\_dark\_current()} function.
    %
    \item[\mxfn{mx\_scaler\_set\_dark\_current()}] -
        Sets the dark current for the given scaler in counts per second.
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX Table Functions}

This set of functions controls a diffractometer/goniostat table so that
the table can make pure rotations and tranlations relative to an arbitrary
point on the table.

\begin{description}
    \item[\mxfn{mx\_table\_get\_position()}] -
        Gets the current position of the specified table pseudomotor.
    %
    \item[\mxfn{mx\_table\_set\_position()}] -
        Sets the current position of the specified table pseudomotor.
    %
    \item[\mxfn{mx\_table\_move\_absolute()}] -
        Moves the specified table pseudomotor to the requested position.
    %
    \item[\mxfn{mx\_table\_is\_busy()}] -
        Checks to see if the specified table pseudomotor is currently moving.
    %
    \item[\mxfn{mx\_table\_soft\_abort()}] -
        Tells the table pseudomotor to stop moving in a ``nice'' fashion
	so that it does not lose track of its position.
    %
    \item[\mxfn{mx\_table\_immediate\_abort()}] -
        Tells the table pseudomotor to stop moving as fast as it can.
    %
    \item[\mxfn{mx\_table\_positive\_limit\_hit()}] -
        Checks whether the limit for the specified table pseudomotor
	has been hit.
    %
    \item[\mxfn{mx\_table\_negative\_limit\_hit()}] -
        Checks whether the limit for the specified table pseudomotor
	has been hit.
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX Timer Functions}

\subsection{Preset time functions}

\begin{description}
    \item[\mxfn{mx\_timer\_start()}] -
        Starts the timer counting for the specified number of seconds.
    %
    \item[\mxfn{mx\_timer\_stop()}] -
        Stops the timer from counting and removes the gate signal.
    %
    \item[\mxfn{mx\_timer\_is\_busy()}] - Is the timer still counting?
    %
\end{description}

\subsection{Preset count functions}

\begin{description}
    \item[\mxfn{mx\_timer\_read()}] -
        Reads the elapsed time in seconds without stopping the timer.
    %
    \item[\mxfn{mx\_timer\_clear()}] -
        Stops the timer, clears its value and rearms the timer.
    %
\end{description}

\subsection{Timer mode functions}

\begin{description}
    \item[\mxfn{mx\_timer\_get\_mode()}] -
        Finds out whether the timer is configured
	to be in preset time or preset count compatible mode.
    %
    \item[\mxfn{mx\_timer\_set\_mode()}] - Sets the timer mode.
    %
    \item[\mxfn{mx\_timer\_set\_modes\_of\_associated\_counters()}] -
        Ensures that the
	other counter channels in a module with multiple counters are set
	to counter modes that are compatible with the given timer.
    %
\end{description}

%****************************************************************************

\chapter{Interface API}

%-----------------------------------------------------------------------------

\section{MX CAMAC Functions}

\begin{description}
    \item[\mxfn{mx\_camac()}] -
        Sends a CAMAC FNA command to the crate controller.
    %
    \item[\mxfn{mx\_camac\_qwait()}] - Repeatedly sends a CAMAC FNA command to
	the crate controller until Q=1 is received.  Needed by E500
	motor controllers.
    %
    \item[\mxfn{mx\_camac\_send\_control\_word()}] -
        Sends a Z, C, or I command to the crate controller.
    %
    \item[\mxfn{mx\_camac\_get\_lam\_status()}] -
        Checks the Look At Me (LAM) status for the crate controller.
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX GPIB Functions}

\begin{description}
    \item[\mxfn{mx\_gpib\_open\_device()}] -
        Makes a connection to the GPIB device
	at the specified GPIB address.
    %
    \item[\mxfn{mx\_gpib\_close\_device()}] -
        Shuts down the connection to
	the GPIB device at the specified GPIB address.
    %
    \item[\mxfn{mx\_gpib\_read\_parms\_from\_device()}] -
        Reads several GPIB parameters
	from the device at the specified GPIB address, such as
	the secondary address, I/O timeout, EOI mode, and EOS characters.
    %
    \item[\mxfn{mx\_gpib\_write\_parms\_to\_device()}] -
        Writes the GPIB parameters to the device at the specified GPIB address.
    %
    \item[\mxfn{mx\_gpib\_read()}] -
    	Reads up to a specified number of characters from the GPIB interface.
    %
    \item[\mxfn{mx\_gpib\_write()}] -
        Writes up to a specified number of characters
	to the GPIB interface.
    %
    \item[\mxfn{mx\_gpib\_getline()}] -
        Gets a line of text from the GPIB interface.
    %
    \item[\mxfn{mx\_gpib\_putline()}] -
    	Sends a line of text to the GPIB interface.
    %
    \item[\mxfn{mx\_gpib\_interface\_clear()}] -
        Sends an interface clear signal to the GPIB bus.
    %
    \item[\mxfn{mx\_gpib\_device\_clear()}] -
        Send a device clear (DCL) signal to all the devices on the GPIB bus.
    %
    \item[\mxfn{mx\_gpib\_selective\_device\_clear()}] -
        Sends a selective device clear
	(SDC) signal to a particular device on the GPIB bus.
    %
    \item[\mxfn{mx\_gpib\_local\_lockout()}] -
        Perform a local lockout (LLO) on the GPIB bus.
    %
    \item[\mxfn{mx\_gpib\_remote\_enable()}] -
        Enable remote control for the specified device.
    %
    \item[\mxfn{mx\_gpib\_go\_to\_local()}] -
        Changes the specified device to local mode (GTL).
    %
    \item[\mxfn{mx\_gpib\_trigger()}] - Triggers the specified device (GET).
    %
    \item[\mxfn{mx\_gpib\_wait\_for\_service\_request()}] -
        Waits until an SRQ signal is received.
    %
    \item[\mxfn{mx\_gpib\_serial\_poll()}] -
        Performs a serial poll on the specified device (SPE and serial poll).
    %
    \item[\mxfn{mx\_gpib\_serial\_poll\_disable()}] -
        Disables serial polling (SPD).
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX Portio Functions}

These functions are used to access I/O ports on x86 platforms.

\begin{description}
    \item[\mxfn{mx\_portio\_inp8()}] - Reads an 8 bit value from an I/O port.
    %
    \item[\mxfn{mx\_portio\_inp16()}] - Reads a 16 bit value from an I/O port.
    %
    \item[\mxfn{mx\_portio\_outp8()}] - Writes an 8 bit value to an I/O port.
    %
    \item[\mxfn{mx\_portio\_outp16()}] - Writes a 16 bit value to an I/O port.
    %
    \item[\mxfn{mx\_portio\_request\_region()}] -
    	Asks the operating system for access to the specified range
	of I/O ports.
    %
    \item[\mxfn{mx\_portio\_release\_region()}] -
        Releases control of the specified range of I/O ports
	back to the operating system.
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX RS-232 Functions}

\begin{description}
    \item[\mxfn{mx\_rs232\_getchar()}] -
        Gets a single character from the specified serial interface.
    %
    \item[\mxfn{mx\_rs232\_putchar()}] -
        Sends a single character to the specified serial interface.
    %
    \item[\mxfn{mx\_rs232\_read()}] -
        Reads up to a specified number of characters from the serial interface.
    %
    \item[\mxfn{mx\_rs232\_write()}] -
        Writes up to a specified number of characters to the serial interface.
    %
    \item[\mxfn{mx\_rs232\_getline()}] -
        Gets a line of text from the serial interface.
    %
    \item[\mxfn{mx\_rs232\_putline()}] -
        Sends a line of text to the serial interface.
    %
    \item[\mxfn{mx\_rs232\_input\_is\_available()}] -
        Checks to see if there are any characters in the input buffer
	for the serial interface.
    %
    \item[\mxfn{mx\_rs232\_discard\_unread\_input()}] -
        Discards the contents of the input buffers for the serial interface.
    %
    \item[\mxfn{mx\_rs232\_discard\_unwritten\_output()}] -
        Discards any characters that are still in the output buffers
	for the serial interface.
    %
\end{description}

%-----------------------------------------------------------------------------

\section{MX Generic Interface Functions}

\textbf{\textit{Warning: The Generic Interface Functions are deprecated,
at least in their current form.}}

The \textit{generic} interface class is essentially a catchall for various
types of interfaces that do not fit somewhere else.  It is quite common
for motor drivers (which control a single motor) to have an associated
generic interface driver which manages all of the axes belonging to
the controller as a whole.  Typically, if a driver needs to have a place
to put information about all the resources controlled by a controller
as a whole, the best place to put these is in a generic interface driver.
Thus, for a Compumotor 6K motor controller, each axis has its own
separate motor record, but the controller as a whole has a generic
interface record which is used to manage sending and receiving ASCII
commands to and from the controller.

Many, but not all, generic interface drivers have ways of sending and
receiving ASCII strings.  For those that do, the following functions
are available.  Please note that \mxfn{mx\_generic\_getline()} and
\mxfn{mx\_generic\_putline()}] do not exist yet, but are scheduled to 
be added to the library.

\begin{description}
    \item[\mxfn{mx\_generic\_getchar()}] -
        Gets a single character from the specified generic interface.
    %
    \item[\mxfn{mx\_generic\_putchar()}] -
        Sends a single character to the specified generic interface.
    %
    \item[\mxfn{mx\_generic\_read()}] -
        Reads up to a specified number of characters from the generic interface.
    %
    \item[\mxfn{mx\_generic\_write()}] -
        Writes up to a specified number of characters to the generic interface.
    %
    \item[\mxfn{mx\_generic\_input\_is\_available()}] -
        Checks to see if there are any
	characters in the input buffer for the generic interface.
    %
    \item[\mxfn{mx\_generic\_discard\_unread\_input()}] -
        Discards the contents of the
	input buffers for the generic interface.
    %
    \item[\mxfn{mx\_generic\_discard\_unwritten\_output()}] -
        Discards any characters
	that are still in the output buffers for the generic interface.
    %
\end{description}

%****************************************************************************

\chapter{MX Variable Functions}

\section{Generic variable functions}

\begin{description}
    \item[\mxfn{mx\_send\_variable()}] -
        Sends the value field of a local variable record to the remote server.
    %
    \item[\mxfn{mx\_receive\_variable()}] -
        Receives the value field of a local variable
	record from the remote server.
    %
    \item[\mxfn{mx\_get\_variable\_parameters()}] -
        Gets the dimensionality and variable type of a local variable record.
    %
    \item[\mxfn{mx\_get\_variable\_pointer()}] -
        Gets a pointer to the data values
	for a local variable record.
    %
\end{description}

\section{One-dimensional variable functions}

Since one-dimensional arrays are more common than higher-dimensional arrays,
there are a number of convenience functions specifically for working
with them.

\begin{description}
    \item[\mxfn{mx\_get\_1d\_array()}] - For a given one-dimensional
	variable record pointer, this function verifies that the variable
	is the correct data type.  It then gets both the number of elements
	and a pointer to the data values.
    %
    \item[\mxfn{mx\_get\_1d\_array\_by\_name()}] -
        For a given MX record list pointer,
	this function tries to find a matching one-dimensional variable
	record with the listed name and data type.  It then returns the
	number of elements and a pointer to the data values. 
    %
    \item[\mxfn{mx\_test\_1d\_array()}] -
        Verifies that the specified record is a
	one-dimensional variable record with the requested field type
	and number of elements.
    %
\end{description}

\section{Scalar variable functions}

Several convenience functions for scalar values are available.  The set
of available convenience functions is incomplete at the moment.  I will
fill it out in the near future.

The following \textit{get} functions require a record list pointer and
a record name.

\begin{description}
    \item[\mxfn{mx\_get\_long\_variable\_by\_name()}]
    %
    \item[\mxfn{mx\_get\_unsigned\_long\_variable\_by\_name()}]
    %
    \item[\mxfn{mx\_get\_double\_variable\_by\_name()}]
    %
    \item[\mxfn{mx\_get\_string\_variable\_by\_name()}]
    %
\end{description}

The following \textit{set} function requires a pointer to the MX record.

\begin{description}
    \item[\mxfn{mx\_set\_long\_variable()}]
\end{description}

%****************************************************************************

\chapter{Server API}

%-----------------------------------------------------------------------------

\section{MX Server Functions}

\begin{description}
    \item[\mxfn{mx\_get()}] - This is a macro that gets the value of a zero
	dimensional value (a scalar) from a remote MX server.
    %
    \item[\mxfn{mx\_put()}] - This is a macro that sends the value of a zero
	dimensional value (a scalar) to a remote MX server.
    %
    \item[\mxfn{mx\_get\_array()}] - Receives the value of an MX record field
	from a remote MX server.
    %
    \item[\mxfn{mx\_put\_array()}] - Sends a local value to an MX record field
	on a remote MX server.
    %
    \item[\mxfn{mx\_network\_send\_message()}] - Sends an MX protocol message
	to an MX server.
    %
    \item[\mxfn{mx\_network\_receive\_message()}] -
        Receives an MX protocol message from an MX server.
    %
\end{description}

\begin{description}
    \item[\mxfn{mx\_socket\_send\_message()}] - This is a low level function
	that sends an MX protocol message on the specified socket.
    %
    \item[\mxfn{mx\_socket\_receive\_message()}] - This is a low level function
	that receives an MX protocol message on the specified socket.
    %
    \item[\mxfn{mx\_socket\_send\_error\_message()}] -
    	This is a low level function
	that sends an MX protocol error message on the specified socket.
    %
\end{description}

%****************************************************************************

\chapter{MX Scan Functions}

There is only one scan record specific function available, namely,

\begin{description}
    \item[\mxfn{mx\_perform\_scan()}] - Executes the specified scan from the
	MX database.
\end{description}

It is the only function that an application program using standard scan drivers
should need to invoke.

\section{Scan driver functions}

There are a variety of other scan related functions that are mostly intended
for use by \textit{scan device drivers}, rather than application programs.
These functions are normally invoked behind the scenes by 
\textit{mx\_perform\_scan()}, but a custom scan driver is \textit{not required}
to use any of them if it has special needs.  The functions are passed pointers
to MX\_SCAN structures rather than pointers to MX\_RECORD functions.

\begin{description}
    \item[\mxfn{mx\_standard\_prepare\_for\_scan\_start()}] -
        This is the default routine that handles 
	standard types of preparation before the beginning of a scan
	such as opening datafiles and starting plotting programs.
    %
    \item[\mxfn{mx\_standard\_cleanup\_after\_scan\_end()}] -
        This is the default
	routine that closes down all of the resources acquired by 
	\mxfn{mx\_standard\_prepare\_for\_scan\_start()}.
    %
    \item[\mxfn{mx\_setup\_scan\_shutter()}] - This routine checks to see if
	the scan is using an X-ray shutter and initializes the
	associated data structures.
    %
    \item[\mxfn{mx\_setup\_scan\_enable()}] - This routine checks to see if
	the scan will be using a scan enable/disable interlock
	and initializes the associated data structures.
    %
    \item[\mxfn{mx\_scan\_handle\_data\_measurement()}] -
        When it is time to perform
	a measurement, this routine invokes the function used by this
	scan's measurement type to perform measurements.
    %
    \item[\mxfn{mx\_scan\_handle\_pause\_request()}] -
        When the user requests that
	a scan be paused, this function passes control to the installed
	pause request handler.
    %
    \item[\mxfn{mx\_set\_scan\_pause\_request\_handler()}] -
        Allows an application
	program to redefine the default pause request handler.
    %
    \item[\mxfn{mx\_default\_scan\_pause\_request\_handler()}] -
        This function merely
	prints out a message that a pause has been requested.
    %
    \item[\mxfn{mx\_scan\_display\_scan\_progress()}] -
        This function displays the
	current status of the scan to the user.  Typically, it is used
	to present the results of the most recent measurement.
    %
    \item[\mxfn{mx\_clear\_scan\_input\_devices()}] - This function makes the 
	current scan's input devices ready to make the next measurement.
    %
    \item[\mxfn{mx\_handle\_abnormal\_scan\_termination()}] -
        This function is invoked
	any time a scan is abnormally terminated, both for user requested
	aborts and for failures in the beamline hardware such as
	hitting a limit switch.
    %
    \item[\mxfn{mx\_scan\_restore\_speeds()}] - Restores all the motor speeds to
	the values they had before the start of the scan.
    %
    \item[\mxfn{mx\_log\_scan\_start()}] -
        If scan logging is enabled, this function
	writes a ``start of scan'' message to the scan log.
    %
    \item[\mxfn{mx\_log\_scan\_stop()}] -
        If scan logging is enabled, this function
	writes an ``end of scan'' message to the scan log.
    %
    \item[\mxfn{mx\_setup\_topup\_interlock()}] -
        This is an APS specific scan function
	that sets up an scan interlock with the Advanced Photon Source 
	topup injection.  This function tries to ensure that measurements
	are not made during a topup injection and retakes a measurement
	if necessary.
    %
    \item[\mxfn{mx\_scan\_finish\_record\_initialization()}] -
        Performs initialization
	steps that must be performed for all scan records.  It is intended
	to be used in the \mxfn{xxx\_finish\_record\_initialization} driver
	function for a particular scan type.
    %
\end{description}

\section{Measurement driver functions}

Each type of measurement that an MX scan record can perform
such as preset time, preset count, etc. has an associated
measurement type driver.  These functions are passed pointers
to MX\_MEASUREMENT structures.

\begin{description}
    \item[\mxfn{mx\_measure\_data()}] - This function performs the detector
	measurements required for the current step in the scan.
    %
    \item[\mxfn{mx\_configure\_measurement\_type()}] - Before a scan starts,
	this function reconfigures the devices used by this scan
	to be ready for the requested measurement type.  This may
	involve things like reconfiguring which devices have presets
	and so forth.
    %
    \item[\mxfn{mx\_deconfigure\_measurement\_type()}] - After a scan ends,
	the devices involved in the scan are reprogrammed to revert
	back to the default measurement type, namely, preset time.
    %
    \item[\mxfn{mx\_prescan\_measurement\_processing()}] -
        Performs any measurement
	related functions required before the first data point is taken.
    %
    \item[\mxfn{mx\_postscan\_measurement\_processing()}] -
        Performs any measurement
	related functions required after the last data point is taken.
    %
    \item[\mxfn{mx\_preslice\_measurement\_processing()}] -
        For a multidimensional
	scan, this function performs any measurement
	related functions required before the first data point 
	of the current slice is taken.
    %
    \item[\mxfn{mx\_postslice\_measurement\_processing()}] -
        For a multidimensional
	scan, this function performs any measurement
	related functions required after the last data point 
	of the current slice is taken.
    %
\end{description}

\section{Data file driver functions}

Each type of data file format that can be generated by an MX scan record
has an associated data file driver.  These functions are passed pointers
to MX\_DATAFILE structures.

\subsection{Data file handling functions}

\begin{description}
    \item[\mxfn{mx\_datafile\_open()}] -
        Opens the file that the data will be written to.
    %
    \item[\mxfn{mx\_datafile\_close()}] -
        Closes the file that the data have been written to.
    %
    \item[\mxfn{mx\_datafile\_write\_main\_header()}] - This function writes out
	the header information required by this data file type.
    %
    \item[\mxfn{mx\_datafile\_write\_section\_header()}] - For data files that
	are broken up into sections, this function writes out the
	header for the current section.
    %
    \item[\mxfn{mx\_datafile\_write\_trailer()}] - This function writes out
	any trailer information required by this data file type.
    %
    \item[\mxfn{mx\_add\_measurement\_to\_datafile()}] - This function goes to
	each device in turn and copies the data for this datapoint
	to the data file.
    %
    \item[\mxfn{mx\_add\_array\_to\_datafile()}] -
        For some scan types, the results
	of the measurement are already located in arrays in the
	memory of the MX application program.  For this case, this
	function copies the contents of those arrays to the data file.
    %
\end{description}

\subsection{Data file version number functions}

An MX scan record will autoincrement the version number for the next
scan data file, if and only if, everything after the last period '.'
in the filename consists only of the digits '0-9'.  The following
functions handle the job of autoincrementing the number.

\begin{description}
    \item[\mxfn{mx\_parse\_datafile\_name()}] - This function checks to see
	if the current data file name has a version number and splits
	the file name into the version number and the version independent
	part.
    %
    \item[\mxfn{mx\_construct\_datafile\_version\_number()}] - Constructs a new
	data file version number from the old version number.  This
	function wraps back to zero if the next version number would
	increase the number of digits in the version number.  For example,
	if the most recently created data file had version number '.999',
	the next version number will be '.000'.
    %
    \item[\mxfn{mx\_update\_datafile\_name()}] - This function replaces the old
	version number with the new version number.
    %
\end{description}

\section{Plot driver functions}

Each type of scan progress plotting program that can be used by an MX
scan record has an associated plot driver.  These functions are passed
pointers to MX\_PLOT structures.

\begin{description}
    \item[\mxfn{mx\_plot\_open()}] -
        Initializes the connection to the plotting program.
    %
    \item[\mxfn{mx\_plot\_close()}] -
        Shuts down the connection to the plotting program.
    %
    \item[\mxfn{mx\_add\_measurement\_to\_plot\_buffer()}] -
        This function goes to
	each device in turn and copies the data for this datapoint
	to the plot buffer.
    %
    \item[\mxfn{mx\_add\_array\_to\_plot\_buffer()}] -
        For some scan types, the results
	of the measurement are already located in arrays in the
	memory of the MX application program.  For this case, this
	function copies the contents of those arrays to the plot buffer.
    %
    \item[\mxfn{mx\_display\_plot()}] - This function tells the plotting program
	to update its scan progress windows to include all the measurements
	that have been sent to it.
    %
    \item[\mxfn{mx\_plot\_set\_x\_range()}] -
        Sets the X axis limits of the scan progress window.
    %
    \item[\mxfn{mx\_plot\_set\_y\_range()}] -
        Sets the Y axis limits of the scan progress window.
    %
    \item[\mxfn{mx\_plot\_start\_plot\_section()}] -
        For multidimensional scans, MX
	at present only supports displaying the current one-dimensional
	slice of the scan in the scan progress window.
	\mxfn{mx\_plot\_start\_plot\_section()} tells the plotting program
	that a new one-dimensional slice has just started.
    %
    \item[\mxfn{mx\_plotting\_is\_enabled()}] -
        Checks to see if the user has requested
	that a scan progress graph be displayed.
    %
    \item[\mxfn{mx\_set\_plot\_enable()}] -
        This function sets the flag that is used
	by \mxfn{mx\_plotting\_is\_enabled()}].
    %
\end{description}

\end{document}

