MPI_Type_get_contents - Constructs new data types


SYNOPSIS

       C:

            #include "mpi.h"

            int MPI_Type_get_contents(MPI_Datatype datatype, int max_integers,
            int max_addresses, int max_datatypes, int array_of_integers[],
            MPI_Aint array_of_addresses[], MPI_Datatype array_of_datatypes[])

       Fortran:

            INCLUDE "mpif.h" (or USE MPI)

            INTEGER datatype, max_integers, max_addresses,
            max_datatypes, array_of_integers(*), array_of_datatypes(*),
            ierror
            INTEGER(KIND=MPI_ADDRESS_KIND) array_of_addresses(*)

            CALL MPI_TYPE_GET_CONTENTS(datatype, max_integers,
            max_addresses,
            max_datatypes, array_of_integers, array_of_addresses,
            array_of_datatypes, ierror)


DESCRIPTION

       MPI_Type_get_contents constructs new data types. Arguments
       are as follows:

       datatype            Specifies the data type to be accessed
                           (handle). datatype must be a
                           predefined unnamed data type or a
                           derived data type.  The call is
                           erroneous if datatype is a predefined
                           named data type.

                           MPI_Type_get_contents can be invoked
                           with a data type argument that was
                           constructed by using
                           MPI_TYPE_CREATE_F90_REAL,
                           MPI_TYPE_CREATE_F90_INTEGER, or
                           MPI_TYPE_CREATE_F90_COMPLEX (an
                           unnamed predefined data type). In such
                           a case, an empty array_of_datatypes is
                           returned.

                           The definition of data type
                           equivalence implies that equivalent
                           predefined data types are equal. By
                           requiring the same handle for named
                           predefined data types, it is possible
                           to use the == or .EQ. comparison

                           involved.

       max_integers        Specifies the number of elements in
                           array_of_integers (non-negative
                           integer).

       max_addresses       Specifies the number of elements in
                           array_of_addresses (non-negative
                           integer).

       max_datatypes       Specifies the number of elements in
                           array_of_datatypes (non-negative
                           integer).

       array_of_integers   Returns integer arguments used in
                           constructing the data type (array of
                           integers).

       array_of_addresses  Returns address arguments used in
                           constructing the data type (array of
                           integers).

       array_of_datatypes  Returns data type arguments used in
                           constructing the data type (array of
                           handles).

       ierror              Specifies the return code value for
                           successful completion, which is in
                           MPI_SUCCESS.  MPI_SUCCESS is defined
                           in the mpif.h file.

       The values given for max_integers, max_addresses, and
       max_datatypes must be at least as large as the
       corresponding values returned in num_integers,
       num_addresses, and num_datatypes in the
       MPI_TYPE_GET_ENVELOPE call for the same data type
       argument.

       The data types returned in array_of_datatypes are handles
       to data type objects that are equivalent to the data types
       used in the original construction call. If these were
       derived data types, the returned data types are new data
       type objects, and the user is responsible for freeing
       these data types by using MPI_TYPE_FREE. If these were
       predefined data types, the returned data type is a
       constant equal to that predefined data type and cannot be
       freed.

       The committed state of returned derived data types is
       undefined (that is, the data types might or might not be
       committed). Furthermore, the content of attributes of
       returned data types is undefined.

       arguments in Fortran are of type INTEGER. In the new MPI-2
       calls, the address arguments are of type
       INTEGER(KIND=MPI_ADDRESS_KIND).  The MPI_Type_get_contents
       call returns all addresses in an argument of type
       INTEGER(KIND=MPI_ADDRESS_KIND). This is true even if the
       old MPI-1 calls were used. Thus, the location of returned
       values can be thought of as being returned by the C
       bindings. It can also be determined by examining the new
       MPI-2 calls for data type constructors for the deprecated
       MPI-1 calls that involve addresses.  Since the Fortran
       verison of this function uses MPI_ADDRESS_KIND, which is
       supported only for ABI 64, the Fortran version of this
       function is also available only for ABI 64.

       By having all address arguments returned in the
       array_of_addresses argument, the result from a C and
       Fortran decoding of a data type gives the result in the
       same argument. It is assumed that an integer of type
       INTEGER(KIND=MPI_ADDRESS_KIND) will be at least as large
       as the integer argument used in data type construction
       with the old MPI-1 calls, so no loss of information will
       occur.


EXAMPLES

       The following code defines what values are placed in each
       entry of the returned arrays depending on the data type
       constructor used for data type. It also specifies the size
       of the arrays needed, which are the values returned by
       MPI_TYPE_GET_ENVELOPE.

       Fortran calls:

       PARAMETER (LARGE = 1000)
             INTEGER TYPE, NI, NA, ND, COMBINER, I(LARGE), D(LARGE), IERROR
             INTEGER(KIND=MPI_ADDRESS_KIND) A(LARGE)
       !     CONSTRUCT DATATYPE TYPE (NOT SHOWN)
             CALL MPI_TYPE_GET_ENVELOPE(TYPE, NI, NA, ND, COMBINER, IERROR)
             IF ((NI .GT. LARGE) .OR. (NA .GT. LARGE) .OR. (ND .GT. LARGE)) THEN
               WRITE (*, *) "NI, NA, OR ND = ", NI, NA, ND, &
               " RETURNED BY MPI_TYPE_GET_ENVELOPE IS LARGER THAN LARGE = ", LARGE
               CALL MPI_ABORT(MPI_COMM_WORLD, 99)
             ENDIF
             CALL MPI_TYPE_GET_CONTENTS(TYPE, NI, NA, ND, I, A, D, IERROR)

       C calls:

       #define LARGE 1000
       int ni, na, nd, combiner, i[LARGE];
       MPI_Aint a[LARGE];
       MPI_Datatype type, d[LARGE];
       /* construct datatype type (not shown) */

       if ((ni > LARGE) || (na > LARGE) || (nd > LARGE)) {
         fprintf(stderr, "ni, na, or nd = %d %d %d returned by ", ni, na, nd);
         fprintf(stderr, "MPI_Type_get_envelope is larger than LARGE = %d0,
                 LARGE);
         MPI_Abort(MPI_COMM_WORLD, 99);
       };
       MPI_Type_get_contents(type, ni, na, nd, i, a, d);


SEE ALSO

       MPI_File_open(3), MPI_Type_get_envelope(3)


Man(1) output converted with man2html