\section{Records and Record Fields}

So what is a record, actually?
On a technical level, it is a C data structure of type \textit{MX\_RECORD}
that is declared in the MX source code in the header file
\textit{mx/libMx/mx\_record.h}.  But most of you probably did not
want to know that.

On a more practical level, it is a repository for most of the information
that MX program needs to know about a given object.  The reason I say
``most'' is that MX records often have pointers to other MX records in
the database.  Thus, the \textit{6k} record from the example in the
previous section does not itself contain the information about the RS-232
settings of the port used to communicate with the Compumotor controller.
Instead it uses the pointer \textit{6k\_rs232} in its own record description
so that it can find that information in the record \textit{6k\_rs232}.

MX records are the primary ``objects'' of MX.  They encapsulate both
data values such as motor position, scaler counts, etc.\ and tables of 
functions (``methods'') that operate on that data.  Many of the data
fields will be the same for all records of a given class.  For example,
all motor drivers need to have a place to store the current position
of the motor.  However, each record type will have type specific information
in it.  For example, a Pontech \textit{stp100} record contains a field
for the digital I/O pin number used to implement a home switch, a concept
which many motor drivers would have no need for.

Internally, the data belonging to a record is contained in a variety of
C data structures with names like \textit{MX\_MOTOR}, \textit{MX\_COMPUMOTOR},
\textit{MX\_PMAC\_MOTOR}, and so forth.  However, when it comes time to
read data from a disk file or send it across the network, we can't really
use the binary C structures or pointers to them for this.  Theoretically
you could, but it would be a really bad idea to do so.  Instead, we use
the concept of a \textit{record field}.

An MX record field contains a pointer to a piece of data and also a
description of its datatype and size.  The record field also has a name
that we can use to refer to it by.  For example, if we look at an 
MX motor record called \textit{theta}, its position will be found in
the record field \textit{theta.position}.  Thus, the record field name
has two parts, namely, the record name \textit{theta} and the field name
\textit{position}.  Information read from MX database files and sent
across MX network connections is identified by it record field name.

We said earlier in this chapter that each horizontal line in an MX database
corresponds to one MX record.  Within a given database line, the data is
organized by field name.  As we saw earlier, the first four fields are
called \textit{name}, \textit{mx\_superclass}, \textit{mx\_class}, and
\textit{mx\_type}.  These four fields are always found at the start of
an MX database line.  They are followed by two more fields called 
\textit{label} and \textit{acl\_description} which are also common to
all record types.  These record fields can be summarized by the
following table:
%
\begin{center}
\begin{tabular}{|c|c|c|c|p{52mm}|}
\hline
\MxTextFieldName & \MxTextFieldType & \MxTextNumDimensions &
  \MxTextSizes & \MxTextDescription \\
\hline
\textit{name} & string & 1 & 16 & The name of the record \\
\hline
\textit{mx\_superclass} & recordtype & 0 & 0 & The string ``device'' \\
\hline
\textit{mx\_class} & recordtype & 0 & 0 & The string ``motor'' \\
\hline
\textit{mx\_type} & recordtype & 0 & 0 & 
	The name of the motor driver for this motor. \\
\hline
\textit{label} & string & 1 & 40 & A verbose description of the record. \\
\hline
\textit{acl\_description} & string & 1 & 40 &
	Placeholder for an access control list \textit{(not yet implemented)}.\\
\hline
\end{tabular}
\end{center}
%
You will see tables like the above throughout the rest of this manual,
so we will try to explain it further here.

First of all, the \textbf{Field Name} column is just what it says, the name
of the field.  The \textbf{Field Type} column tells you what datatype the
field contains.  At present, MX supports the following datatypes, which
are mostly modeled on the C datatypes:

\begin{center}
\begin{tabular}{|c|c|p{90mm}|}
\hline
\textbf{Internal Name} & \textbf{Common Name} & \textbf{Description}\\
\hline
MXFT\_STRING & string & Null terminated C string \\
\hline
MXFT\_CHAR   & char   & C char \\
\hline
MXFT\_UCHAR  & uchar  & C unsigned char \\
\hline
MXFT\_SHORT  & short  & C short \\
\hline
MXFT\_USHORT & ushort & C unsigned short \\
\hline
MXFT\_INT    & int    & C int \\
\hline
MXFT\_UINT   & uint   & C unsigned int \\
\hline
MXFT\_LONG   & long   & C long \\
\hline
MXFT\_ULONG  & ulong  & C unsigned long \\
\hline
MXFT\_FLOAT  & float  & C float \\
\hline
MXFT\_DOUBLE & double & C double \\
\hline
MXFT\_HEX    & hex    & A C unsigned long, usually represented in
			   hexadecimal notation, such as 0x27a5. \\
\hline
MXFT\_RECORD & record & A pointer to another MX record, represented by
			   the name of the record in the database file. \\
\hline
MXFT\_RECORDTYPE & recordtype & Used to point to device driver structures.
				Represented by the name of the driver type. \\
\hline
MXFT\_INTERFACE  & interface  & A generalization of the MX\_RECORD type
				which includes an optional address field. 
				Typically used for devices that can be 
				controlled by both RS-232 and GPIB.
				An example would be \textit{gpib0:4}
				which refers to GPIB address 4
				for GPIB interface record \textit{gpib0}.\\
\hline
\end{tabular}
\end{center}

The \textbf{Number of Dimensions} column refers, of course, to the 
dimensions of the array containing the data.  The case ``0'' stands
for a single scalar value.
The \textbf{Sizes} column contains a list of the sizes of each dimension.
