# 5.2.60 hdfql_mpi_use_communicator

Part of: [5 Application Programming Interface](5-application-programming-interface.md) › [5.2 Functions](5-2-functions.md)

### Syntax

int hdfql_mpi_use_communicator(const void \*communicator)

### Description

Set the MPI communicator named _communicator_ as the one to be used when performing operations (e.g. [SELECT](6-6-1-select.md)) in parallel. An MPI communicator represents a group of processes that participate in the communication, which may involve some or all the processes specified when launching a program using “mpiexec” (or a similar launcher). Of note, if the function is called before the first call to an operation ([CREATE FILE](6-4-2-create-file.md), [INSERT](6-5-1-insert.md), [SELECT](6-6-1-select.md), or [USE FILE](6-8-2-use-file.md)) or a function ([hdfql_mpi_get_size](5-2-62-hdfql-mpi-get-size.md) or [hdfql_mpi_get_rank](5-2-63-hdfql-mpi-get-rank.md)) that employs parallelism, HDFql will not initialize the MPI library, as it assumes that the initialization was previously done by the programmer through MPI function “MPI_Init” (please refer to <https://www.mpich.org/static/docs/v3.4/www3/MPI_Init.html> or <https://www.open-mpi.org/doc/v3.1/man3/MPI_Init.3.php> for additional information in case the MPI library used is MPICH or Open MPI, respectively).

### Parameter(s)

_communicator_ – pointer to an MPI communicator to use when performing operations in parallel. If the pointer is NULL (in C), the default MPI communicator (MPI_COMM_WORLD) is used instead (i.e. equivalent to calling the function [hdfql_mpi_use_default_communicator](5-2-61-hdfql-mpi-use-default-communicator.md)). The equivalent of a NULL pointer in C++, Java, Python, C#, Fortran, R, and MATLAB HDFql wrappers is NULL, null, None, null, NULL(), NULL, and NaN, respectively.

### Return

int – depending on the success in using _communicator_, it can be [HDFQL_SUCCESS](5-1-constants.md#hdfql_success), [HDFQL_ERROR_NOT_SUPPORTED](5-1-constants.md#hdfql_error_not_supported) (in case MPI itself was not initialized properly or when using an HDFql non MPI-based distribution), or [HDFQL_ERROR_UNKNOWN](5-1-constants.md#hdfql_error_unknown).

### Example(s)

```c
// declare variables 
MPI_Comm my_communicator;
MPI_Group group;
int ranks[2];

// create an MPI group named "group" containing processes (i.e. ranks) #0 and #1 
ranks[0] = 0; 
ranks[1] = 1;
MPI_Group_incl(MPI_COMM_WORLD, 2, ranks, &group);

// create an MPI communicator named "my_communicator" based on MPI group "group" 
MPI_Comm_create(MPI_COMM_WORLD, group, &my_communicator);

// use MPI communicator "my_communicator" in subsequent operations performed in parallel 
hdfql_mpi_use_communicator(&my_communicator);

// select (i.e. read) dataset named "my_dataset" in parallel using MPI communicator "my_communicator"
hdfql_execute("SELECT FROM my_dataset IN PARALLEL");

// use default MPI communicator (MPI_COMM_WORLD) in subsequent operations performed in parallel
hdfql_mpi_use_communicator(NULL); 

// select (i.e. read) dataset "my_dataset" in parallel using default MPI communicator (MPI_COMM_WORLD)
hdfql_execute("SELECT FROM my_dataset IN PARALLEL");
```