An Example of an Uninstrumented HDF5 C Code (Corresponding C Code Instrumented for Runtime tracing)

/*  
 *  This example writes data to an HDF5 file on each processor.
 *  Data conversion is performed during write operation.  
 *  It is a modified version of the example h5_write provided with the
 *  HDF 5 software distribution.
 */
 
#include <hdf5.h>
#include <mpi.h>
#define FILE        "SDS.h5"
#define DATASETNAME "IntArray" 
#define NX     5                      /* dataset dimensions */
#define NY     6
#define RANK   2
int
main(int argc, char **argv)
{
    hid_t       file, dataset;         /* file and dataset handles */
    hid_t       datatype, dataspace;   /* handles */
    hsize_t     dimsf[2];              /* dataset dimensions */
    herr_t      status;                             
    int         data[NX][NY];          /* data to write */
    int         i, j;
    int mpi_size, mpi_rank;                             /* mpi variables */
    char *fileName;
    MPI_Init(&argc, &argv);
    MPI_Comm_size(MPI_COMM_WORLD, &mpi_size);
    MPI_Comm_rank(MPI_COMM_WORLD, &mpi_rank);
    /*
     * Create a separate file name for each processor.
    */
    fileName = (char *)malloc( strlen(FILE) + 5 );
    sprintf(fileName,"%s.nd%d\0",FILE,mpi_rank);
    /* 
     * Data  and output buffer initialization. 
     */
    for (j = 0; j < NX; j++) {
	for (i = 0; i < NY; i++)
	    data[j][i] = i + j;
    }     
    /*
     * 0 1 2 3 4 5 
     * 1 2 3 4 5 6
     * 2 3 4 5 6 7
     * 3 4 5 6 7 8
     * 4 5 6 7 8 9
     */
    /*
     * Create a new file using H5F_ACC_TRUNC access,
     * default file creation properties, and default file
     * access properties.
     */
    file = H5Fcreate(fileName, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
    /*
     * Describe the size of the array and create the data space for fixed
     * size dataset. 
     */
    dimsf[0] = NX;
    dimsf[1] = NY;
    dataspace = H5Screate_simple(RANK, dimsf, NULL); 
    /* 
     * Define datatype for the data in the file.
     * We will store little endian INT numbers.
     */
    datatype = H5Tcopy(H5T_NATIVE_INT);
    status = H5Tset_order(datatype, H5T_ORDER_LE);
    /*
     * Create a new dataset within the file using defined dataspace and
     * datatype and default dataset creation properties.
     */
    dataset = H5Dcreate(file, DATASETNAME, datatype, dataspace,
			H5P_DEFAULT);
    /*
     * Write the data to the dataset using default transfer properties.
     */
    status = H5Dwrite(dataset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL,
		      H5P_DEFAULT, data);
    /*
     * Close/release resources.
     */
    H5Sclose(dataspace);
    H5Tclose(datatype);
    H5Dclose(dataset);
    H5Fclose(file);
    
    MPI_Finalize();
 
    return 0;
}     

Instrumented for Runtime Tracing

/*  
 *  This example writes data to an HDF5 file on each processor.
 *  Data conversion is performed during write operation.  
 *  It is a modified version of the example h5_write provided with the
 *  HDF 5 software distribution.
 *  This file has been modified for Pablo tracing.
 */
 
#include <hdf5.h>
#include <mpi.h>
#include "ProcTrace.h"		/* pablo header file */
#define FILE        "SDS.h5"
#define DATASETNAME "IntArray" 
#define NX     5                      /* dataset dimensions */
#define NY     6
#define RANK   2
int
main(int argc, char **argv)
{
    hid_t       file, dataset;         /* file and dataset handles */
    hid_t       datatype, dataspace;   /* handles */
    hsize_t     dimsf[2];              /* dataset dimensions */
    herr_t      status;                             
    int         data[NX][NY];          /* data to write */
    int         i, j;
    int mpi_size, mpi_rank;                             /* mpi variables */
    char *fileName;
    MPI_Init(&argc, &argv);
    MPI_Comm_size(MPI_COMM_WORLD, &mpi_size);
    MPI_Comm_rank(MPI_COMM_WORLD, &mpi_rank);
    /*
     * Initialize Pablo Tracing.  All HDF calls are traced.
     * Runtime tracing is performed.			
     */
    HDFinitTrace( "myTrace",ID_ALLHDF, MPI_RUNTIME_TRACE ); 
    /*
     * Create a separate file name for each processor.
    */
    fileName = (char *)malloc( strlen(FILE) + 5 );
    sprintf(fileName,"%s.nd%d\0",FILE,mpi_rank);
    /* 
     * Data  and output buffer initialization. 
     */
    for (j = 0; j < NX; j++) {
	for (i = 0; i < NY; i++)
	    data[j][i] = i + j;
    }     
    /*
     * 0 1 2 3 4 5 
     * 1 2 3 4 5 6
     * 2 3 4 5 6 7
     * 3 4 5 6 7 8
     * 4 5 6 7 8 9
     */
    /*
     * Create a new file using H5F_ACC_TRUNC access,
     * default file creation properties, and default file
     * access properties.
     */
    file = H5Fcreate(fileName, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
    /*
     * Describe the size of the array and create the data space for fixed
     * size dataset. 
     */
    dimsf[0] = NX;
    dimsf[1] = NY;
    dataspace = H5Screate_simple(RANK, dimsf, NULL); 
    /* 
     * Define datatype for the data in the file.
     * We will store little endian INT numbers.
     */
    datatype = H5Tcopy(H5T_NATIVE_INT);
    status = H5Tset_order(datatype, H5T_ORDER_LE);
    /*
     * Create a new dataset within the file using defined dataspace and
     * datatype and default dataset creation properties.
     */
    dataset = H5Dcreate(file, DATASETNAME, datatype, dataspace,
			H5P_DEFAULT);
    /*
     * Write the data to the dataset using default transfer properties.
     */
    status = H5Dwrite(dataset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL,
		      H5P_DEFAULT, data);
    /*
     * Close/release resources.
     */
    H5Sclose(dataspace);
    H5Tclose(datatype);
    H5Dclose(dataset);
    H5Fclose(file);
    
    /*
     * Terminate Pablo Tracing.
     */
    HDFendTrace();
    MPI_Finalize();
 
    return 0;
}     

Compiling, Linking, and Executing

Suppose the Pablo software is installed in the directory <PabloDir> and the instrumented HDF software is installed in the directory <HDF5Dir>.

To compile the code, use the following command:

mpicc -c h5_write.c -I<PabloDir>/include -I<HDF5Dir>/include -I<MPIdir>/include

To link the code, use the following command:

mpicc -o myEXE h5_write.o -L<PabloDir>/lib -L<HDF5Dir>/lib -ldf-inst -lmfhdf-inst -lPabloTrace -lPabloTraceExt -lmpi  [other libraries as necessary]

To execute the code, use the following command:

mpirun -mp <nprocs> myEXE

This will produce a trace output files named myTrace.nd<p.> where p is the node number.

Click on the name below to download the binary files produced for the case <nprocs>=2 described above. See the Trace Output Files section below for the steps necessary to convert these files to ascii.

Create HDF Records

Before doing any further processing, each trace file should be processed using the createHDFRecords command, which summarizes the Unix I/O and HDF activity within each HDF procedure call. This can be done by issuing the following commands:

CreateHDFRecords myTrace.nd<p>

This will produce tracefiles myTrace.nd<p>.rec.   Click the name below to download the binary files produced for the case <nprocs>=2.

Merging the Trace Output Files

Before doing any further processing, the trace files should be merged and the file ids synchronized. This can be done by issuing the following commands:

MergePabloTraces -o myTrace.mrg myTrace.nd*.rec

SyncHDFids myTrace.mrg

This will produce a tracefile myTrace.mrg.syncFiles and a map file myTrace.mrg.syncFiles.map. This last file is a mapping of file IDs to file names in the application.

Click to download the trace output file myTrace.mrg or the file myTrace.mrg.syncFiles  produced by following the steps above with nprocs equal to two (2). The file is in binary. To convert it to ASCII follow the steps in the Trace Output Files section below.

Click to dowload the map file myTrace.mrg.syncFiles.map.   It is already in ASCII format.

Trace Output Files

The trace output files are in binary format and are generally best processed in that format. Sometimes it is convenient, however, to convert the file to ASCII to read its contents. To convert a binary trace file to ASCII, use the command SDDFconverter. The following is the session used to convert myTrace.mrg from a binary format to the ASCII file myTrace.mrg.ascii. User responses are in bold. Click to download the converted trace output file User responses are in bold. Click to download the converted trace output file myTrace.mrg.ascii.

% SDDFconverter

Please enter name of the input SDDF file: myTrace.mrg

File is in SDDF Non-Native Binary format

Output in Ascii, Binary or Converted (reverse byte order) format [A, B, C]: A

Please entery name of the output SDDF file: myTrace.mrg.ascii

Do you want diagnostic messages printed [Y or N}: N

Processing Data: Sample Reports

Runtime

Issue the command HDFStatsTables myTrace.mrg.syncFiles to produce the report on the screen. Note that the output is 132 columns wide.

Summary

Follow the steps outlined for HDF4 Summary tracing of C codes to generate reports on HDF5 codes.