mpiRecorderCreate

Declaration

	MPIRecorder mpiRecorderCreate(MPIControl control, long number);
	Required Header: stdmpi.h

Description

mpiRecorderCreate creates a Recorder object identified by number, which is associated with a control object. RecorderCreate is the equivalent of a C++ constructor.

The recorder number specifies which recorder to create. The valid range for the number parameter is -1 to the controller's recordCount (MPIControlConfig.recorderCount). Use a recorder number of -1 to specify the recorder number as the next available recorder.

See MPIControlConfig{.} for details. If the recorder is not enabled or is already in use (another process has called mpiRecorderCreate(...) with the same number parameter), mpiRecorderCreate(...) will return an invalid handle causing subsequent mpiRecorderValidate(...) calls to fail.

It is possible to create a recorder object and not delete it, leaving the resources for the recorder occupied, but forgotten about (abandoned). It is most common to run into this situation when using an index of -1 for the recorder. When developing a program and running it in the debugger, it is common for the developer to exit the program without letting the program clean up its recorder resources. To see how to handle this situation programmatically, please see recorderinuse.c.

control

a handle to a Control object.

number

An index to the controller's data recorder. If (-1) is specified, the next available recorder object handle will be returned. The valid range is from -1 (next available recorder) to the controller's recordCount - 1.

When using (-1), make sure to delete the recorder object to free it for other applications. If the recorder object is not freed, it will not be accessible to another application until the controller is reset.

Return Values
handle	to a Recorder object
MPIHandleVOID	if the Recorder object could not be created

Sample Code


/*
  This Function Creates a Recorder. Pass in the Recorder handle,
  and the recorder number. To create the next available recorder,
  pass in -1 for recorderNumber
*/

long recorderInit(MPIControl    *control, 
                  MPIRecorder   *recorder, 
                  long          recorderNumber)
{
   long returnValue; 

   // Create recorder object
   *recorder = mpiRecorderCreate(*control, recorderNumber);

   returnValue = mpiRecorderValidate(*recorder);
   return returnValue;
}