A simple C example for the ParallelIO Library. More...

#include "config.h"
#include <getopt.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <mpi.h>
#include <pio.h>

Include dependency graph for example1.c:

Macros
#define	TEST_NAME "example1"
	The name of this program.

#define	NUM_NETCDF_FLAVORS 4
	The number of possible output netCDF output flavors available to the ParallelIO library.

#define	NDIM 1
	The number of dimensions in the example data. More...

#define	DIM_LEN 16
	The length of our sample data. More...

#define	DIM_NAME "x"
	The name of the dimension in the netCDF output file.

#define	VAR_NAME "foo"
	The name of the variable in the netCDF output file.

#define	ERR_BAD 1001
	Return code when netCDF output file does not match expectations.

#define	START_DATA_VAL 42
	The meaning of life, the universe, and everything.

#define	MPIERR(e)
	Handle MPI errors. More...

#define	ERR(e)
	Handle non-MPI errors by finalizing the MPI library and exiting with an exit code. More...

Functions
int	check_file (int ntasks, char *filename)
	Check the output file. More...

int	main (int argc, char *argv[])
	Main execution of code. More...

Variables
char	exerr_buffer [MPI_MAX_ERROR_STRING]
	Global err buffer for MPI. More...

int	exresultlen
	This is the length of the most recent MPI error message, stored int the global error string.

Detailed Description

A simple C example for the ParallelIO Library.

This example creates a netCDF output file with one dimension and one variable. It first writes, then reads the sample file using the ParallelIO library.

This example can be run in parallel for 1, 2, 4, 8, or 16 processors.

Macro Definition Documentation

◆ DIM_LEN

#define DIM_LEN 16

The length of our sample data.

There will be a total of 16 integers in our data, and responsibilty for writing and reading them will be spread between all the processors used to run this example.

◆ ERR

#define ERR ( e )

Value:

        do {                \
        MPI_Finalize();             \
        return e;               \
    } while (0)

Handle non-MPI errors by finalizing the MPI library and exiting with an exit code.

◆ MPIERR

#define MPIERR ( e )

Value:

        do {                                                  \
        MPI_Error_string(e, exerr_buffer, &exresultlen);            \
        printf("MPI error, line %d, file %s: %s\n", __LINE__, __FILE__, exerr_buffer); \
        MPI_Finalize();                         \
        return 2;                           \
    } while (0)

Handle MPI errors.

This should only be used with MPI library function calls.

◆ NDIM

#define NDIM 1

The number of dimensions in the example data.

In this simple example, we are using one-dimensional data.

Function Documentation

◆ check_file()

int check_file	(	int	ntasks,
		char *	filename
	)

Check the output file.

Use netCDF to check that the output is as expected.

Parameters

ntasks	The number of processors running the example.
filename	The name of the example file to check.

Returns: 0 if example file is correct, non-zero otherwise.

< File ID from netCDF.

< Number of dimensions.

< Number of variables.

< Number of global attributes.

< ID of unlimited dimension.

< Length of the dimension.

< Number of variable attributes.

< NetCDF data type of this variable.

< Return code for function calls.

< Dimension ids for this variable.

< Name of the dimension.

< Name of the variable.

< Zero-based index to start read.

< Number of elements to read.

< Buffer to read in data.

< Data values we expect to find.

◆ main()

int main	(	int	argc,
		char *	argv[]
	)

Main execution of code.

Executes the functions to:

create a new examplePioClass instance
initialize MPI and the ParallelIO libraries
create the decomposition for this example
create the netCDF output file
define the variable in the file
write data to the variable in the file using decomposition
read the data back from the file using decomposition
close the file
clean up resources

The example can be run from the command line (on system that support it) like this:

mpiexec -n 4 ./examplePio

The sample file created by this program is a small netCDF file. It has the following contents (as shown by ncdump) for a 4-processor run:

netcdf examplePio_c {
dimensions:
x = 16 ;
variables:
int foo(x) ;
data:

foo = 42, 42, 42, 42, 43, 43, 43, 43, 44, 44, 44, 44, 45, 45, 45, 45 ;
}

Parameters

[in]	argc	argument count (should be zero)
[in]	argv	argument array (should be NULL)

Return values

examplePioClass* Pointer to self.

Set to non-zero to get output to stdout.

Zero-based rank of processor.

Number of processors involved in current execution.

Different output flavors. The example file is written (and then read) four times. The first two flavors, parallel-netcdf, and netCDF serial, both produce a netCDF classic format file (but with different libraries). The last two produce netCDF4/HDF5 format files, written with and without using netCDF-4 parallel I/O.

Number of processors that will do IO. In this example we will do IO from all processors.

Stride in the mpi rank between io tasks. Always 1 in this example.

Zero based rank of first processor to be used for I/O.

The dimension ID.

Array index per processing unit. This is the number of elements of the data array that will be handled by each processor. In this example there are 16 data elements. If the example is run on 4 processors, then arrIdxPerPe will be 4.

The ID for the parallel I/O system. It is set by PIOc_Init_Intracomm(). It references an internal structure containing the general IO subsystem data and MPI structure. It is passed to PIOc_finalize() to free associated resources, after all I/O, but before MPI_Finalize is called.

The ncid of the netCDF file created in this example.

The ID of the netCDF varable in the example file.

The I/O description ID as passed back by PIOc_InitDecomp() and freed in PIOc_freedecomp().

A buffer for sample data. The size of this array will vary depending on how many processors are involved in the execution of the example code. It's length will be the same as elements_per_pe.

A 1-D array which holds the decomposition mapping for this example. The size of this array will vary depending on how many processors are involved in the execution of the example code. It's length will be the same as elements_per_pe.

Test filename.

The number of netCDF flavors available in this build.

Used for command line processing.

Return value.

Variable Documentation

◆ exerr_buffer

char exerr_buffer[MPI_MAX_ERROR_STRING]

Global err buffer for MPI.

When there is an MPI error, this buffer is used to store the error message that is associated with the MPI error.

Macros

Functions

Variables