Naming Conventions

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.