# HDF5: API Mapping to legacy APIs

Functionality | netCDF | SD | AIO | HDF5 | Comments
--- | --- | --- | --- | --- | ---
Open existing file for read/write | ncopen | SDstart | AIO_open | H5Fopen

Creates new file for read/write.

nccreate

H5Fcreate

SD API handles this with SDopen

Close file | ncclose | SDend | AIO_close | H5Fclose

Redefine parameters

ncredef

Unneccessary under SD & HDF5 data-models

End "define" mode

ncendef

Unneccessary under SD & HDF5 data-models

Query the number of datasets, dimensions and attributes in a file

ncinquire

SDfileinfo

H5Dget_info
H5Rget_num_relations
H5Gget_num_contents

HDF5 interface is more granular and flexible

Update a writeable file with current changes

ncsync

AIO_flush

H5Mflush

HDF5 interface is more flexible because it can be applied to parts of the file hierarchy instead of the whole file at once. The SD interface does not have this feature, although most of the lower HDF library supports it.

Close file access without applying recent changes

ncabort

How useful is this feature?

Create new dimension

ncdimdef

SDsetdimname

H5Mcreate

SD interface actually creates dimensions with datasets, this just allows naming them

Get ID of existing dimension

ncdimid

SDgetdimid

H5Maccess

SD interface looks up dimensions by index and the netCDF interface uses names, but they are close enough. The HDF5 interface does not current allow access to particular dimensions, only the dataspace as a whole.

Get size & name of dimension

ncdiminq

SDdiminfo

H5Mget_name
H5Sget_lrank

Only a rough match

Rename dimension

ncdimrename

SDsetdimname

H5Mset_name

Create a new dataset | ncvardef | SDcreate | AIO_mkarray | H5Mcreate |
Attach to an existing dataset | ncvarid | SDselect | AIO_arr_load | H5Maccess |
Get basic information about a dataset | ncvarinq | SDgetinfo | AIO_arr_get_btype AIO_arr_get_nelmts AIO_arr_get_nbdims AIO_arr_get_bdims AIO_arr_get_slab | H5Dget_info | All interfaces have different levels of information that they return, some use of auxilliary functions is required to get equivalent amount of information
Write a single value to a dataset | ncvarput1 | SDwritedata | AIO_write | H5Dwrite | What is this useful for?
Read a single value from a dataset | ncvarget1 | SDreaddata | AIO_read | H5Dread | What is this useful for?
Write a solid hyperslab of data (i.e. subset) to a dataset | ncvarput | SDwritedata | AIO_write | H5Dwrite |
Read a solid hyperslab of data (i.e. subset) from a dataset | ncvarget | SDreaddata | AIO_read | H5Dread |
Write a general hyperslab of data (i.e. possibly subsampled) to a dataset | ncvarputg | SDwritedata | AIO_write | H5Dwrite |
Read a general hyperslab of data (i.e. possibly subsampled) from a dataset | ncvargetg | SDreaddata | AIO_read | H5Dread |

Rename a dataset variable

ncvarrename

H5Mset_name

Add an attribute to a dataset

ncattput

SDsetattr

H5Rattach_oid

HDF5 requires creating a seperate object to attach to a dataset, but it also allows objects to be attributes of any other object, even nested.

Get attribute information

ncattinq

SDattrinfo

H5Dget_info

HDF5 has no specific function for attributes, they are treated as all other objects in the file.

Retrieve attribute for a dataset

ncattget

SDreadattr

H5Dread

HDF5 uses general dataset I/O for attributes.

Copy attribute from one dataset to another

ncattcopy

What is this used for?

Get name of attribute

ncattname

SDattrinfo

H5Mget_name

Rename attribute

ncattrename

H5Mset_name

Delete attribute

ncattdel

H5Mdelete

This can be faked in current HDF interface with lower-level calls

Compute # of bytes to store a number-type

nctypelen

DFKNTsize

Hmm, the HDF5 Datatype interface needs this functionality.

Indicate that fill-values are to be written to dataset

ncsetfill

SDsetfillmode

HDF5 Datatype interface should work on this functionality

Get information about "record" variables (Those datasets which share the same unlimited dimension

ncrecinq

This should probably be wrapped in a higher layer interface, if it's needed for HDF5.

Get a record from each dataset sharing the unlimited dimension

ncrecget

This is somewhat equivalent to reading a vdata with non-interlaced fields, only in a dataset oriented way. This should also be wrapped in a higher layer interface if it's necessary for HDF5.

Put a record from each dataset sharing the unlimited dimension

ncrecput

This is somewhat equivalent to writing a vdata with non-interlaced fields, only in a dataset oriented way. This should also be wrapped in a higher layer interface if it's necessary for HDF5.

Map a dataset's name to an index to reference it with

SDnametoindex

H5Mfind_name

Equivalent functionality except HDF5 call returns an OID instead of an index.

Get the valid range of values for data in a dataset

SDgetrange

Easily implemented with attributes at a higher level for HDF5.

Release access to a dataset

SDendaccess

AIO_arr_destroy

H5Mrelease

Odd that the netCDF API doesn't have this...

Set the valid range of data in a dataset

SDsetrange

Easily implemented with attributes at a higher level for HDF5.

Set the label, units, format, etc. of the data values in a dataset

SDsetdatastrs

Easily implemented with attributes at a higher level for HDF5.

Get the label, units, format, etc. of the data values in a dataset

SDgetdatastrs

Easily implemented with attributes at a higher level for HDF5.

Set the label, units, format, etc. of the dimensions in a dataset

SDsetdimstrs

Easily implemented with attributes at a higher level for HDF5.

Get the label, units, format, etc. of the dimensions in a dataset

SDgetdimstrs

Easily implemented with attributes at a higher level for HDF5.

Set the scale of the dimensions in a dataset

SDsetdimscale

Easily implemented with attributes at a higher level for HDF5.

Get the scale of the dimensions in a dataset

SDgetdimscale

Easily implemented with attributes at a higher level for HDF5.

Set the calibration parameters of the data values in a dataset

SDsetcal

Easily implemented with attributes at a higher level for HDF5.

Get the calibration parameters of the data values in a dataset

SDgetcal

Easily implemented with attributes at a higher level for HDF5.

Set the fill value for the data values in a dataset

SDsetfillvalue

HDF5 needs something like this, I'm not certain where to put it.

Get the fill value for the data values in a dataset

SDgetfillvalue

HDF5 needs something like this, I'm not certain where to put it.

Move/Set the dataset to be in an 'external' file

SDsetexternalfile

H5Dset_storage

HDF5 has simple functions for this, but needs an API for setting up the storage flow.

Move/Set the dataset to be stored using only certain bits from the dataset

SDsetnbitdataset

H5Dset_storage

HDF5 has simple functions for this, but needs an API for setting up the storage flow.

Move/Set the dataset to be stored in compressed form

SDsetcompress

H5Dset_storage

HDF5 has simple functions for this, but needs an API for setting up the storage flow.

Search for an dataset attribute with particular name

SDfindattr

H5Mfind_name
H5Mwild_search

HDF5 can handle wildcard searchs for this feature.

Map a run-time dataset handle to a persistant disk reference

SDidtoref

I'm not certain this is needed for HDF5.

Map a persistant disk reference for a dataset to an index in a group

SDreftoindex

I'm not certain this is needed for HDF5.

Determine if a dataset is a 'record' variable (i.e. it has an unlimited dimension)

SDisrecord

Easily implemented by querying the dimensionality at a higher level for HDF5.

Determine if a dataset is a 'coordinate' variable (i.e. it is used as a dimension)

SDiscoord

I'm not certain this is needed for HDF5.

Set the access type (i.e. parallel or serial) for dataset I/O

SDsetaccesstype

HDF5 has functions for reading the information about this, but needs a better API for setting up the storage flow.

Set the size of blocks used to store a dataset with unlimited dimensions

SDsetblocksize

HDF5 has functions for reading the information about this, but needs a better API for setting up the storage flow.

Sets backward compatibility of dimensions created.

SDsetdimval_comp

Unneccessary in HDF5.

Checks backward compatibility of dimensions created.

SDisdimval_comp

Unneccessary in HDF5.

Move/Set the dataset to be stored in chunked form

SDsetchunk

H5Dset_storage

HDF5 has simple functions for this, but needs an API for setting up the storage flow.

Get the chunking information for a dataset stored in chunked form

SDgetchunkinfo

H5Dstorage_detail

Read/Write chunks of a dataset using a chunk index

SDreadchunk
SDwritechunk

I'm not certain that HDF5 needs something like this.

Tune chunk caching parameters for chunked datasets

SDsetchunkcache

HDF5 needs something like this.

Change some default behavior of the library

AIO_defaults

Something like this would be useful in HDF5, to tune I/O pipelines, etc.

Flush and close all open files

AIO_exit

Something like this might be useful in HDF5, although it could be encapsulated with a higher-level function.

Target an architecture for data-type storage

AIO_target

There are some rough parallels with using the data-type in HDF5 to create data-type objects which can be used to write out future datasets.

Map a filename to a file ID

AIO_filename

H5Mget_name

Get the active directory (where new datasets are created)

AIO_getcwd

HDF5 allows multiple directories (groups) to be attached to, any of which can have new datasets created within it.

Change active directory

AIO_chdir

Since HDF5 has a slightly different access method for directories (groups), this functionality can be wrapped around calls to H5Gget_oid_by_name.

Create directory

AIO_mkdir

H5Mcreate

Return detailed information about an object

AIO_stat

H5Dget_info
H5Dstorage_detail

Perhaps more information should be provided through another function in HDF5?

Get "flag" information

AIO_getflags

Not required in HDF5.

Set "flag" information

AIO_setflags

Not required in HDF5.

Get detailed information about all objects in a directory

AIO_ls

H5Gget_content_info_mult
H5Dget_info
H5Dstorage_detail

Only roughly equivalent functionality in HDF5, perhaps more should be added?

Get base type of object

AIO_BASIC

H5Gget_content_info

Set base type of dataset

AIO_arr_set_btype

H5Mcreate(DATATYPE)

Set dimensionality of dataset

AIO_arr_set_bdims

H5Mcreate(DATASPACE)

Set slab of dataset to write

AIO_arr_set_slab

This is similar to the process of creating a dataspace for use when performing I/O on an HDF5 dataset

Describe chunking of dataset to write

AIO_arr_set_chunk

H5Dset_storage

Describe array index permutation of dataset to write

AIO_arr_set_perm

H5Dset_storage

Create a new dataset with dataspace and datatype information from an existing dataset.

AIO_arr_copy

This can be mimicked in HDF5 by attaching to the datatype and dataspace of an existing dataset and using the IDs to create new datasets.

Create a new directory to group objects within

AIO_mkgroup

H5Mcreate(GROUP)

Read name of objects in directory

AIO_read_group

H5Gget_content_info_mult

Add objects to directory

AIO_write_group

H5Ginsert_item_mult

Combine an architecture and numeric type to derive the format's datatype

AIO_COMBINE

This is a nice feature to add to HDF5.

Derive an architecture from the format's datatype

AIO_ARCH

This is a nice feature to add to HDF5.

Derive a numeric type from the format's datatype

AIO_PNT

This is a nice feature to add to HDF5.

Register error handling function for library to call when errors occur

AIO_error_handler

This should be added to HDF5.