int MPI_Type_get_envelope(
  MPI_Datatype datatype,
  int *num_integers,
  int *num_addresses,
  int *num_datatypes,
  int *combiner
);

Parameters

datatype

[in] datatype

num_integers

[out] num integers

num_addresses

[out] num addresses

num_datatypes

[out] num datatypes

combiner

[out] combiner

Remarks

For the given datatype, MPI_TYPE_GET_ENVELOPE returns information on the number and type of input arguments used in the call that created the datatype. The number-of-arguments values returned can be used to provide sufficiently large arrays in the decoding routine MPI_TYPE_GET_CONTENTS. This call and the meaning of the returned values is described below. The combiner reflects the MPI datatype constructor call that was used in creating datatype.

Rationale.

By requiring that the combiner reflect the constructor used in the creation of the datatype, the decoded information can be used to effectively recreate the calling sequence used in the original creation. One call is effectively the same as another when the information obtained from MPI_TYPE_GET_CONTENTS may be used with either to produce the same outcome. C calls MPI_Type_hindexed and MPI_Type_create_hindexed are always effectively the same while the Fortran call MPI_TYPE_HINDEXED will be different than either of these in some MPI implementations. This is the most useful information and was felt to be reasonable even though it constrains implementations to remember the original constructor sequence even if the internal representation is different.

The decoded information keeps track of datatype duplications. This is important as one needs to distinguish between a predefined datatype and a dup of a predefined datatype. The former is a constant object that cannot be freed, while the latter is a derived datatype that can be freed. ( End of rationale.)
The list below has the values that can be returned in combiner on the left and the call associated with them on the right.

MPI_COMBINER_NAMEDa named predefined datatype
MPI_COMBINER_DUP MPI_TYPE_DUP
MPI_COMBINER_CONTIGUOUS MPI_TYPE_CONTIGUOUS
MPI_COMBINER_VECTOR MPI_TYPE_VECTOR
MPI_COMBINER_HVECTOR_INTEGER MPI_TYPE_HVECTOR from Fortran
MPI_COMBINER_HVECTOR MPI_TYPE_HVECTOR from C or C++
and in some case Fortran
or MPI_TYPE_CREATE_HVECTOR
MPI_COMBINER_INDEXED MPI_TYPE_INDEXED
MPI_COMBINER_HINDEXED_INTEGER MPI_TYPE_HINDEXED from Fortran
MPI_COMBINER_HINDEXED MPI_TYPE_HINDEXED from C or C++
and in some case Fortran
or MPI_TYPE_CREATE_HINDEXED
MPI_COMBINER_INDEXED_BLOCK MPI_TYPE_CREATE_INDEXED_BLOCK
MPI_COMBINER_STRUCT_INTEGER MPI_TYPE_STRUCT from Fortran
MPI_COMBINER_STRUCT MPI_TYPE_STRUCT from C or C++
and in some case Fortran
or MPI_TYPE_CREATE_STRUCT
MPI_COMBINER_SUBARRAY MPI_TYPE_CREATE_SUBARRAY
MPI_COMBINER_DARRAY MPI_TYPE_CREATE_DARRAY
MPI_COMBINER_F90_REAL MPI_TYPE_CREATE_F90_REAL
MPI_COMBINER_F90_COMPLEX MPI_TYPE_CREATE_F90_COMPLEX
MPI_COMBINER_F90_INTEGER MPI_TYPE_CREATE_F90_INTEGER
MPI_COMBINER_RESIZED MPI_TYPE_CREATE_RESIZED
 

If combiner is MPI_COMBINER_NAMED then datatype is a named predefined datatype.

For calls with address arguments, we sometimes need to differentiate whether the call used an integer or an address size argument. For example, there are two combiners for hvector: MPI_COMBINER_HVECTOR_INTEGER and MPI_COMBINER_HVECTOR. The former is used if it was the MPI-1 call from Fortran, and the latter is used if it was the MPI-1 call from C or C++. However, on systems where MPI_ADDRESS_KIND = MPI_INTEGER_KIND (i.e., where integer arguments and address size arguments are the same), the combiner MPI_COMBINER_HVECTOR may be returned for a datatype constructed by a call to MPI_TYPE_HVECTOR from Fortran. Similarly, MPI_COMBINER_HINDEXED may be returned for a datatype constructed by a call to MPI_TYPE_HINDEXED from Fortran, and MPI_COMBINER_STRUCT may be returned for a datatype constructed by a call to MPI_TYPE_STRUCT from Fortran. On such systems, one need not differentiate constructors that take address size arguments from constructors that take integer arguments, since these are the same. The new MPI-2 calls all use address sized arguments.

Rationale.

For recreating the original call, it is important to know if address information may have been truncated. The MPI-1 calls from Fortran for a few routines could be subject to truncation in the case where the default INTEGER size is smaller than the size of an address.

Notes for Fortran

All MPI objects (e.g., MPI_Datatype, MPI_Comm) are of type INTEGER in Fortran.

Errors

All MPI routines (except MPI_Wtime and MPI_Wtick) return an error value; C routines as the value of the function and Fortran routines in the last argument. Before the value is returned, the current MPI error handler is called. By default, this error handler aborts the MPI job. The error handler may be changed with MPI_Comm_set_errhandler (for communicators), MPI_File_set_errhandler (for files), and MPI_Win_set_errhandler (for RMA windows). The MPI-1 routine MPI_Errhandler_set may be used but its use is deprecated. The predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned. Note that MPI does not guarentee that an MPI program can continue past an error; however, MPI implementations will attempt to continue whenever possible.

MPI_SUCCESS

No error; MPI routine completed successfully.

Example Code

The following sample code illustrates MPI_Type_get_envelope.

Insert code here.