Object Methods

Introduction | Common Methods for MPI Objects
mpiObjectCreate(...) | mpiObjectDelete(...) | mpiObjectValidate(...)

Introduction

Object-oriented languages such as C++ and Java provide capabilities such as inheritance and polymorphism. The MPI is written in the C language, and so these more exotic object-oriented features are not available. However, the basic concepts of object-oriented design are in the MPI: modularity, data hiding and no global or static data.

It's similar to C++
If you are already familiar with C++, you will quickly realize that the MPI methods that create and delete objects are patterned after C++ constructors and destructors. An MPI method takes an object as its first argument, much as a C++ method has a "this" pointer. Object data is private and available only by calling object methods. MPI source code is organized into modules, with one object per module. Library state is distributed across application-created objects; there is virtually no state information maintained by the library.

All object methods and all functions return a value indicating whether the call to them succeeded or not. In general, the return value is of type long, with a value of 0 indicating success. The return value can be treated as an MPIMessage, so that you can call the mpiMessage(...) function to obtain a text string that describes the return value. The text string that indicates a successful return value of MPIMessageOK (0) is empty ("").

All MPI objects must implement certain required methods. Note that most MPI objects implement standard configuration and memory methods; many MPI objects implement standard status and list manipulation methods and a few objects implement standard event notification methods. For multi-threaded environments, all objects must implement standard resource allocation timeout methods.

In general, there are few methods that are unique to an object, and those unique methods tend to be those that perform object-specific actions. The following sections describe the standard methods that are implemented by many objects. For specific details about objects and their methods/functions, refer to the breakdown of Objects.

Where used in the rest of this section, the word Object may be replaced with the name of an MPI object in order to obtain the name of the methods for that object.

Example

For the term mpiObjectCreate(...), replace Object with Axis to obtain the name of the method that you would use to create Axis objects, mpiAxisCreate(...).

For the term MPIObject, replace Object with Axis to obtain the data type of the Axis handle (MPIAxis) returned by the Axis method mpiAxisCreate(...), and also used by other Axis methods, such as mpiAxisValidate(...).

Common Methods for MPI Objects

All MPI objects have four types of common methods:

methods which create an object
methods which delete an object
methods which validate an object
methods which identify an object

mpiObjectCreate(...)

Use the Create method to create an object and return a handle that uniquely identifies that object. The MPI does not support declaring an object directly, so you must always use the Create method. The Create method is the only method that does not take an object handle as its first argument. The Create method arguments depend on the type of object being created.

If an object cannot be created, the value of the handle returned is MPIHandleVOID, which typically indicates only that no memory is available to hold the object. If memory is available to create the object, but the Create method encounters an error, then the Create method returns a handle, but the object referenced by the handle is not valid. A call to the mpiObjectValidate(...) method returns a value that indicates whether an object is valid, and if it is not valid, why. In general, if you call a method using an object handle that is invalid, the method will fail and return a value indicating the cause of failure.

The MPI supports multiple motion controllers. Typically, an MPI application first creates a Control object that corresponds to the desired motion controller. If the application will use more than one motion controller, it must create a Control object for each motion controller. The arguments to mpiControlCreate(...) associate a Control object with a specific motion controller.

A motion controller provides various types of resources, such as axis, digital-to-analog converter, data recorder, etc. Many of a motion controller's resource types have multiple instances. For example, motion controllers provide multiple axes and DACs.

Most MPI objects are associated with a specific instance of a resource on a specific motion controller. An Axis object, for example, is associated with a single axis on a motion controller. When creating an MPI object that corresponds to a specific motion controller resource, the Create method takes an MPIControl handle as its first argument and a number as the second argument. The number argument identifies the specific motion controller resource to be used.

Example

The number argument of mpiAxisCreate(...) identifies an axis on the motion controller specified by the MPIControl handle argument.

For XMP only

Number arguments, for those MPI objects that take them, start with 0 (not 1). For example, on an 8-axis XMP motion controller, valid axis numbers are 0 - 7.

Some MPI objects maintain a list whose elements are other MPI objects. The Create method for a list object generally takes a third argument that is a handle to an element object. The element object then becomes the first element of the list maintained by the list object. Specifying an element object is optional; if the handle (third argument) has value MPIHandleVOID, the list object will be created with an empty list.

Example

The Motion object maintains an ordered list of Axis objects. This ordered list of Axis objects defines a motion coordinate system. The third argument to mpiMotionCreate(...) is an Axis handle (MPIAxis). If the Axis handle is valid, then the Axis object (that the handle points to) will be made the first axis in the motion coordinate system.

All MPI objects provide a method to return the value of each of its Create method arguments. These methods serve to identify the object. For more detail, see Identity Methods on page 1-47.

mpiObjectDelete(...)
	Use the Delete method to delete an object created by the Create method. After an object has been deleted, the handle to that object can no longer be used. If a method attempts to use a handle to a deleted object, it returns MPIMessageObject_FREED, but not always. If the memory originally allocated for the deleted object is subsequently allocated for a different purpose, then the method will not return MPIMessageObject_FREED. Your application must ensure that handles to deleted objects are no longer used. After an object is deleted, your application should ensure that the handle to that object is set to MPIHandleVOID. After that, any calls to methods using this handle will return MPIMessageHANDLE_INVALID. When your application exits, it should call Delete methods for all objects that have been created by your application. We recommend that your application delete objects in the reverse order in which they were created. Regardless, the Control object should be the last object deleted. The MPI does not provide the ability to automatically delete all of the objects that have been created. Alternatively, to delete objects, your application may use the C library function atexit(...), which guarantees that the objects will be deleted even if the application terminates abnormally.

mpiObjectValidate(...)
	Use the Validate method to "validate" an object created by the Create method. Your application should always call the Validate method immediately after calling the Create method. Afterwards, the Validate method can additionally be called at any time in an application. If the object is valid, the Validate method will return MPIMessageOK. If the handle passed to the Validate method has value MPIHandleVOID, the Validate method returns MPIMessageHANDLE_INVALID. If a method attempts to use a handle to a deleted object, the method returns MPIMessageObject_FREED. (Also see the previous discussion in mpiObjectDelete(...)). Other possible return values are declared in the message header file(MPI\include\message.h) and in the object's header file (MPI\include\object.h).