|
Uniqueness
|
|
We have tried to make the names of all MPI code and data
symbols unique, so that the names don't conflict with symbols
already defined in the supported operating systems, and in
C language and third-party libraries. The MPI naming convention
enables you to look at a symbol and know whether the symbol
refers to code or data. The MPI uses "MPI" as the initial
token of data symbols, while code symbols use an initial token
of "mpi".
|
|
Example |
The axis handle
data type is called MPIAxis. The method that creates an
axis object is called mpiAxisCreate(...). |
MPI/XMP: MEI-specific additions and extensions to the
MPI are named similarly with an initial token of "MEI" indicating
a data symbol and "mei" indicating a code symbol.
Example |
The MEIAxisConfig{}
data structure contains XMP-specific axis configuration
parameters that extend the MPI-defined axis configuration
parameters. The meiFilterCreate(...) function creates
a Filter object, returning a handle of type MEIFilter.
The Filter object is an addition to the MPI. |
|
|
Symbol Declaration & Definition
|

|
MPI symbols are declared in header files and defined in source
files. To determine the file in which an MPI symbol is declared
and defined, look at the second token of the symbol name:
the second token indicates the module where the symbol is
declared and defined. Also, to maximize the portability of
the code, the MPI uses a DOS-like 8.3 file naming convention.
Therefore, the second token of any symbol name will not exceed
8 characters, nor will the names of modules and objects.
For example, consider a symbol named MPIObjectXyz. The symbol
is a data symbol (MPI) declared in object.h and defined in
object.c. Similarly, a symbol named mpiObjectAbc is a code
symbol (mpi) declared in object.h and defined in object.c.
|
Example |
The MPIAxis
data type and the mpiAxisCreate(...) method are declared
in the header file axis.h. The MEIServer data type and
meiServerDelete(...) method are declared in header file
server.h. The code and data symbols for the Axis object
are defined in axis.c; for the Server object, they are
defined in server.c. |
|

|
|
Symbol Naming
|

|
The previous sections use the concept of a token when discussing
symbol names, where a token is a word or abbreviation contained
in a symbol name. The name of an MPI symbol consists of a
left-to-right sequence of tokens (with no spaces in between).
An uppercase letter indicates the beginning of a token, except
the first token of a symbol, which may be either upper (MPI)
or lower case (mpi). The MPI uses underscores in symbol names
only when it is necessary to separate tokens that are all
uppercase letters.
The first token of a symbol (MPI or mpi) guarantees uniqueness
and indicates whether the symbol is a data symbol (MPI) or
a code symbol (mpi) . The second token indicates the module
that declares and defines the symbol. The remaining tokens
of the symbol name vary, depending on whether the symbol is
code or data.
|
|
|
Data Symbols
|

|
Tokens in data symbols are arranged from left-to-right in
a hierarchical fashion, with the leftmost token being general
and the rightmost token being specific. If the data symbol
names are listed alphabetically, this scheme results in an
listing that groups related data symbols together.
If the rightmost token of a data symbol is all uppercase,
then that data symbol is a constant. If the rightmost token
of a data symbol is not all uppercase, then that data symbol
is either data or a data type. Because the MPI contains virtually
no global data, there is little need to distinguish between
data and data type.
|
|
Consider the MPIMotorHomeIndex enumeration:
|
typedef enum {
MPIMotorHomeIndexINVALID = -1,
MPIMotorHomeIndexHOME_HI_INDEX,
MPIMotorHomeIndexINDEX_ONLY,
MPIMotorHomeIndexHOME_LO_INDEX,
MPIMotorHomeIndexHOME_ONLY,
MPIMotorHomeIndexLAST,
MPIMotorHomeIndexFIRST = MPIMotorHomeIndexINVALID + 1
} MPIMotorHomeIndex;
|
The third and fourth tokens (Home,
Index) are the same for all symbols. The enum name (MPIMotorHomeIndex)
is incorporated in the name of all of the enum members, whose
last token is all uppercase (FIRST, HOME_HI_INDEX, etc.) to
indicate that they are constants (instead of a data type). It
is standard coding practice to use enums rather than #defines
to declare constants, which allows for greater control of the
name space and better type-checking. The use of FIRST and LAST
members in an enum is also standard coding practice, so that
functions can bounds-check enum values. |
|
|
Code Symbols
|

|
Tokens in code symbols indicate the data type and order of
the arguments to the function. The last token in a code symbol
is often the action that the function performs, or the data
type that the function returns. If the code symbol names are
listed alphabetically, this scheme results in a listing that
groups related code symbols together.
If the rightmost token of a code symbol is all uppercase,
then that code symbol is a macro.
If the rightmost token of a code symbol is not all uppercase,
then that code symbol is either a function or a method.
Consider mpiAxisConfigGet(...) and mpiAxisConfigSet(...),
which are 2 methods used to configure an Axis. Because these
functions are methods, the first argument to them is an Axis
handle. The second argument is a pointer to a structure of
type MPIAxisConfig{}. The last token of the method name indicates
the action to take; Get fills the supplied structure with
Axis configuration and Set configures the Axis from the supplied
structure.
The mpiAxisControl(...) method returns the MPIControl handle
with which the Axis was created, while meiElementNEXT(...)
is a macro that returns the MEIElement following the specified
Element.
|
|
|
|