HDF5 Table APIs (H5TB)

Detailed Description

Creating and manipulating HDF5 datasets intended to be interpreted as tables (H5TB)

The HDF5 Table API defines a standard storage for HDF5 datasets that are intended to be interpreted as tables. A table is defined as a collection of records whose values are stored in fixed-length fields. All records have the same structure, and all values in each field have the same data type.

Note

Programming hints:

To use any of these functions or subroutines, you must first include the relevant include file (C) or module (Fortran) in your application.

The following line includes the HDF5 Table package, H5TB, in C applications:

#include "hdf5_hl.h" 

To include the H5TB module in Fortran applications specify:

use h5tb 

Fortran applications must also include H5open before any HDF5 calls to initialize global variables and H5close after all HDF5 calls to close the Fortran interface.

Creation H5TBmake_table Storage H5TBappend_records (No Fortran) H5TBwrite_records (No Fortran) H5TBwrite_fields_name H5TBwrite_fields_index Modification H5TBdelete_record (No Fortran) H5TBinsert_record (No Fortran) H5TBadd_records_from (No Fortran) H5TBcombine_tables (No Fortran) H5TBinsert_field H5TBdelete_field

Retrieval H5TBread_table H5TBread_records (No Fortran) H5TBread_fields_name H5TBread_fields_index Query H5TBget_table_info H5TBget_field_info Query Table Attributes H5TBAget_fill H5TBAget_title

Functions
H5_HLDLL herr_t	H5TBmake_table (const char *table_title, hid_t loc_id, const char *dset_name, hsize_t nfields, hsize_t nrecords, size_t type_size, const char *field_names[], const size_t *field_offset, const hid_t *field_types, hsize_t chunk_size, void *fill_data, int compress, const void *buf)
	Creates and writes a table.
H5_HLDLL herr_t	H5TBappend_records (hid_t loc_id, const char *dset_name, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf)
	Adds records to the end of the table.
H5_HLDLL herr_t	H5TBwrite_records (hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf)
	Overwrites records.
H5_HLDLL herr_t	H5TBwrite_fields_name (hid_t loc_id, const char *dset_name, const char *field_names, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf)
	Overwrites fields.
H5_HLDLL herr_t	H5TBwrite_fields_index (hid_t loc_id, const char *dset_name, hsize_t nfields, const int *field_index, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf)
	Overwrites fields.
H5_HLDLL herr_t	H5TBread_table (hid_t loc_id, const char *dset_name, size_t dst_size, const size_t *dst_offset, const size_t *dst_sizes, void *dst_buf)
	Reads a table.
H5_HLDLL herr_t	H5TBread_fields_name (hid_t loc_id, const char *dset_name, const char *field_names, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, void *buf)
	Reads one or several fields. The fields are identified by name.
H5_HLDLL herr_t	H5TBread_fields_index (hid_t loc_id, const char *dset_name, hsize_t nfields, const int *field_index, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, void *buf)
	Reads one or several fields. The fields are identified by index.
H5_HLDLL herr_t	H5TBread_records (hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *dst_offset, const size_t *dst_sizes, void *buf)
	Reads records.
H5_HLDLL herr_t	H5TBget_table_info (hid_t loc_id, const char *dset_name, hsize_t *nfields, hsize_t *nrecords)
	Gets the table dimensions.
H5_HLDLL herr_t	H5TBget_field_info (hid_t loc_id, const char *dset_name, char *field_names[], size_t *field_sizes, size_t *field_offsets, size_t *type_size)
	Gets information about a table.
H5_HLDLL herr_t	H5TBdelete_record (hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords)
	Delete records.
H5_HLDLL herr_t	H5TBinsert_record (hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t dst_size, const size_t *dst_offset, const size_t *dst_sizes, void *buf)
	Insert records.
H5_HLDLL herr_t	H5TBadd_records_from (hid_t loc_id, const char *dset_name1, hsize_t start1, hsize_t nrecords, const char *dset_name2, hsize_t start2)
	Add records from first table to second table.
H5_HLDLL herr_t	H5TBcombine_tables (hid_t loc_id1, const char *dset_name1, hid_t loc_id2, const char *dset_name2, const char *dset_name3)
	Combines records from two tables into a third.
H5_HLDLL herr_t	H5TBinsert_field (hid_t loc_id, const char *dset_name, const char *field_name, hid_t field_type, hsize_t position, const void *fill_data, const void *buf)
	Insert a new field into a table.
H5_HLDLL herr_t	H5TBdelete_field (hid_t loc_id, const char *dset_name, const char *field_name)
	Deletes a field from a table.
H5_HLDLL herr_t	H5TBAget_title (hid_t loc_id, char *table_title)
	Reads a table's title.
H5_HLDLL htri_t	H5TBAget_fill (hid_t loc_id, const char *dset_name, hid_t dset_id, unsigned char *dst_buf)
	Reads the table attribute fill values.

Function Documentation

H5TBadd_records_from()

H5_HLDLL herr_t H5TBadd_records_from	(	hid_t	loc_id,
		const char *	dset_name1,
		hsize_t	start1,
		hsize_t	nrecords,
		const char *	dset_name2,
		hsize_t	start2
	)

Add records from first table to second table.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name1	The name of the dataset to read the records
[in]	start1	The position to read the records from the first table
[in]	nrecords	The number of records to read from the first table
[in]	dset_name2	The name of the dataset to write the records
[in]	start2	The position to write the records on the second table

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBadd_records_from() adds records from a dataset named dset_name1 to a dataset named dset_name2. Both tables are attached to the object specified by the identifier loc_id.

H5TBAget_fill()

H5_HLDLL htri_t H5TBAget_fill	(	hid_t	loc_id,
		const char *	dset_name,
		hid_t	dset_id,
		unsigned char *	dst_buf
	)

Reads the table attribute fill values.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	Name of table
[in]	dset_id	Table identifier
[out]	dst_buf	Buffer of fill values for table fields

Returns

A return value of 1 indicates that a fill value is present.

A return value of 0 indicates a fill value is not present.

A return value <0 indicates an error.

H5TBget_fill() reads the table attribute fill values into the buffer dst_buf for the table specified by dset_id and dset_name located in loc_id.

Example

unsigned char tmp_fill_buf[40];
...
 
    file_id = H5Fopen(FILENAME, H5F_ACC_RDWR, H5P_DEFAULT);
dataset_id  = H5Dopen(file_id, TABLE_NAME, H5P_DEFAULT);
datatype_id = H5Dget_type(dataset_id);
 
status = H5TBget_table_info(file_id, TABLE_NAME, &nfields, &nrecords);
 
hasfill = H5TBAget_fill(file_id, TABLE_NAME, dataset_id, tmp_fill_buf);
 
for (i = 0; i < nfields; i++) {
    member_type_id     = H5Tget_member_type(datatype_id, (unsigned)i);
    native_mem_type_id = H5Tget_native_type(member_type_id, H5T_DIR_ASCEND);
    member_offset      = H5Tget_member_offset(datatype_id, (unsigned)i);
    printf("member_offset: %i\n", member_offset);
    memb_class = H5Tget_class(member_type_id);
    switch (memb_class) {
        case H5T_INTEGER:
            /* convert unsigned char array to integer */
            break;
        case H5T_FLOAT:
            /* convert unsigned char array to double or float */
 
            if (H5Tequal(native_mem_type_id, H5T_NATIVE_DOUBLE)) {
            }
            else if (H5Tequal(native_mem_type_id, H5T_NATIVE_FLOAT)) {
                f.i = tmp_fill_buf[member_offset] | (tmp_fill_buf[member_offset + 1] << 8) |
                      (tmp_fill_buf[member_offset + 2] << 16) | (tmp_fill_buf[member_offset + 3] << 24);
                printf("Field %i  Fill Value:  %lf\n", i, f.f);
            }
            break;
 
        case H5T_STRING:
            /* convert unsigned char array to string */
            strsize = H5Tget_size(member_type_id);
 
            printf("Field %i  Fill Value: ", i);
            for (j = 0; j < strsize; j++)
                printf("%c", tmp_fill_buf[member_offset + j]);
            printf("\n");
            break;
    }

H5TBAget_title()

H5_HLDLL herr_t H5TBAget_title	(	hid_t	loc_id,
		char *	table_title
	)

Reads a table's title.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[out]	table_title	Buffer for title name

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBget_title() returns the title of the table identified by loc_id in a buffer table_title.

H5TBappend_records()

H5_HLDLL herr_t H5TBappend_records	(	hid_t	loc_id,
		const char *	dset_name,
		hsize_t	nrecords,
		size_t	type_size,
		const size_t *	field_offset,
		const size_t *	dst_sizes,
		const void *	buf
	)

Adds records to the end of the table.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset to overwrite
[in]	nrecords	The number of records to append
[in]	type_size	The size of the structure type, as calculated by sizeof().
[in]	field_offset	An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro
[in]	dst_sizes	An array containing the sizes of the fields
[in]	buf	Buffer with data

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBappend_records() adds records to the end of the table named dset_name attached to the object specified by the identifier loc_id. The dataset is extended to hold the new records.

H5TBcombine_tables()

H5_HLDLL herr_t H5TBcombine_tables	(	hid_t	loc_id1,
		const char *	dset_name1,
		hid_t	loc_id2,
		const char *	dset_name2,
		const char *	dset_name3
	)

Combines records from two tables into a third.

---

Parameters

[in]	loc_id1	Identifier of the file or group in which the first table is located
[in]	dset_name1	The name of the first table to combine
[in]	loc_id2	Identifier of the file or group in which the second table is located
[in]	dset_name2	The name of the second table to combine
[in]	dset_name3	The name of the new table

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBcombine_tables() combines records from two datasets named dset_name1 and dset_name2, to a new table named dset_name3. These tables can be located on different files, identified by loc_id1 and loc_id2 (identifiers obtained with H5Fcreate()). They can also be located on the same file. In this case one uses the same identifier for both parameters loc_id1 and loc_id2. If two files are used, the third table is written in the first file.

H5TBdelete_field()

H5_HLDLL herr_t H5TBdelete_field	(	hid_t	loc_id,
		const char *	dset_name,
		const char *	field_name
	)

Deletes a field from a table.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the table
[in]	field_name	The name of the field to delete

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBdelete_field() deletes a field named field_name from the table dset_name. Note: this function requires the table to be re-created and rewritten in its entirety, and this can result in some unused space in the file, and can also take a great deal of time if the table is large.

H5TBdelete_record()

H5_HLDLL herr_t H5TBdelete_record	(	hid_t	loc_id,
		const char *	dset_name,
		hsize_t	start,
		hsize_t	nrecords
	)

Delete records.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset
[in]	start	The start record to delete from
[in]	nrecords	The number of records to delete

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBdelete_record() deletes nrecords number of records starting from start from the middle of the table dset_name ("pulling up" all the records after it).

H5TBget_field_info()

H5_HLDLL herr_t H5TBget_field_info	(	hid_t	loc_id,
		const char *	dset_name,
		char *	field_names[],
		size_t *	field_sizes,
		size_t *	field_offsets,
		size_t *	type_size
	)

Gets information about a table.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset to read
[out]	field_names	An array containing the names of the fields
[out]	field_sizes	An array containing the size of the fields
[out]	field_offsets	An array containing the offsets of the fields
[out]	type_size	The size of the HDF5 datatype associated with the table. (More specifically, the size in bytes of the HDF5 compound datatype used to define a row, or record, in the table)

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBget_field_info() gets information about a dataset named dset_name attached to the object specified by the identifier loc_id.

H5TBget_table_info()

H5_HLDLL herr_t H5TBget_table_info	(	hid_t	loc_id,
		const char *	dset_name,
		hsize_t *	nfields,
		hsize_t *	nrecords
	)

Gets the table dimensions.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset to read
[out]	nfields	The number of fields
[out]	nrecords	The number of records

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBget_table_info() retrieves the table dimensions from a dataset named dset_name attached to the object specified by the identifier loc_id.

H5TBinsert_field()

H5_HLDLL herr_t H5TBinsert_field	(	hid_t	loc_id,
		const char *	dset_name,
		const char *	field_name,
		hid_t	field_type,
		hsize_t	position,
		const void *	fill_data,
		const void *	buf
	)

Insert a new field into a table.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the table
[in]	field_name	The name of the field to insert
[in]	field_type	The data type of the field
[in]	position	The zero based index position where to insert the field
[in]	fill_data	Fill value data for the field. This parameter can be NULL
[in]	buf	Buffer with data

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBinsert_field() inserts a new field named field_name into the table dset_name. Note: this function requires the table to be re-created and rewritten in its entirety, and this can result in some unused space in the file, and can also take a great deal of time if the table is large.

H5TBinsert_record()

H5_HLDLL herr_t H5TBinsert_record	(	hid_t	loc_id,
		const char *	dset_name,
		hsize_t	start,
		hsize_t	nrecords,
		size_t	dst_size,
		const size_t *	dst_offset,
		const size_t *	dst_sizes,
		void *	buf
	)

Insert records.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset
[in]	start	The position to insert
[in]	nrecords	The number of records to insert
[in]	dst_size	The size in bytes of the structure associated with the table
[in]	dst_offset	An array containing the offsets of the fields
[in]	dst_sizes	An array containing the size in bytes of the fields
[in]	buf	Buffer with data

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBinsert_record() inserts records into the middle of the table ("pushing down" all the records after it)

H5TBmake_table()

H5_HLDLL herr_t H5TBmake_table	(	const char *	table_title,
		hid_t	loc_id,
		const char *	dset_name,
		hsize_t	nfields,
		hsize_t	nrecords,
		size_t	type_size,
		const char *	field_names[],
		const size_t *	field_offset,
		const hid_t *	field_types,
		hsize_t	chunk_size,
		void *	fill_data,
		int	compress,
		const void *	buf
	)

Creates and writes a table.

---

Parameters

[in]	table_title	The title of the table
[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset to create
[in]	nfields	The number of fields
[in]	nrecords	The number of records
[in]	type_size	The size in bytes of the structure associated with the table; This value is obtained with sizeof().
[in]	field_names	An array containing the names of the fields
[in]	field_offset	An array containing the offsets of the fields
[in]	field_types	An array containing the type of the fields
[in]	chunk_size	The chunk size
[in]	fill_data	Fill values data
[in]	compress	Flag that turns compression on or off
[in]	buf	Buffer with data to be written to the table

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBmake_table() creates and writes a dataset named dset_name attached to the object specified by the identifier loc_id.

H5TBread_fields_index()

H5_HLDLL herr_t H5TBread_fields_index	(	hid_t	loc_id,
		const char *	dset_name,
		hsize_t	nfields,
		const int *	field_index,
		hsize_t	start,
		hsize_t	nrecords,
		size_t	type_size,
		const size_t *	field_offset,
		const size_t *	dst_sizes,
		void *	buf
	)

Reads one or several fields. The fields are identified by index.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset to read
[in]	nfields	The number of fields to read (This parameter is also the size of the field_index array.) fields to read
[in]	field_index	The indexes of the fields to read
[in]	start	The start record to read from
[in]	nrecords	The number of records to read
[in]	type_size	The size in bytes of the structure associated with the table (This value is obtained with sizeof())
[in]	field_offset	An array containing the offsets of the fields
[in]	dst_sizes	An array containing the size in bytes of the fields
[out]	buf	Buffer with data

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBread_fields_index() reads the fields identified by field_index from a dataset named dset_name attached to the object specified by the identifier loc_id.

H5TBread_fields_name()

H5_HLDLL herr_t H5TBread_fields_name	(	hid_t	loc_id,
		const char *	dset_name,
		const char *	field_names,
		hsize_t	start,
		hsize_t	nrecords,
		size_t	type_size,
		const size_t *	field_offset,
		const size_t *	dst_sizes,
		void *	buf
	)

Reads one or several fields. The fields are identified by name.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset to read
[in]	field_names	An array containing the names of the fields to read
[in]	start	The start record to read from
[in]	nrecords	The number of records to read
[in]	type_size	The size in bytes of the structure associated with the table (This value is obtained with sizeof().)
[in]	field_offset	An array containing the offsets of the fields
[in]	dst_sizes	An array containing the size in bytes of the fields
[out]	buf	Buffer with data

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBread_fields_name() reads the fields identified by field_names from a dataset named dset_name attached to the object specified by the identifier loc_id.

H5TBread_records()

H5_HLDLL herr_t H5TBread_records	(	hid_t	loc_id,
		const char *	dset_name,
		hsize_t	start,
		hsize_t	nrecords,
		size_t	type_size,
		const size_t *	dst_offset,
		const size_t *	dst_sizes,
		void *	buf
	)

Reads records.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset to read
[in]	start	The start record to read from
[in]	nrecords	The number of records to read
[in]	type_size	The size of the structure type, as calculated by sizeof()
[in]	dst_offset	An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro
[in]	dst_sizes	An array containing the size in bytes of the fields
[out]	buf	Buffer with data

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBread_records() reads some records identified from a dataset named dset_name attached to the object specified by the identifier loc_id.

H5TBread_table()

H5_HLDLL herr_t H5TBread_table	(	hid_t	loc_id,
		const char *	dset_name,
		size_t	dst_size,
		const size_t *	dst_offset,
		const size_t *	dst_sizes,
		void *	dst_buf
	)

Reads a table.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset to read
[in]	dst_size	The size of the structure type, as calculated by sizeof()
[in]	dst_offset	An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro
[in]	dst_sizes	An array containing the sizes of the fields. These sizes can be calculated with the sizeof() macro.
[in]	dst_buf	Buffer with data

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBread_table() reads a table named dset_name attached to the object specified by the identifier loc_id.

H5TBwrite_fields_index()

H5_HLDLL herr_t H5TBwrite_fields_index	(	hid_t	loc_id,
		const char *	dset_name,
		hsize_t	nfields,
		const int *	field_index,
		hsize_t	start,
		hsize_t	nrecords,
		size_t	type_size,
		const size_t *	field_offset,
		const size_t *	dst_sizes,
		const void *	buf
	)

Overwrites fields.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset to overwrite
[in]	nfields	The number of fields to overwrite. This parameter is also the size of the field_index array.
[in]	field_index	The indexes of the fields to write
[in]	start	The zero based index record to start writing
[in]	nrecords	The number of records to write
[in]	type_size	The size of the structure type, as calculated by sizeof().
[in]	field_offset	An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro
[in]	dst_sizes	An array containing the sizes of the fields
[in]	buf	Buffer with data

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBwrite_fields_index() overwrites one or several fields specified by field_index with a buffer buf from a dataset named dset_name attached to the object specified by the identifier loc_id.

H5TBwrite_fields_name()

H5_HLDLL herr_t H5TBwrite_fields_name	(	hid_t	loc_id,
		const char *	dset_name,
		const char *	field_names,
		hsize_t	start,
		hsize_t	nrecords,
		size_t	type_size,
		const size_t *	field_offset,
		const size_t *	dst_sizes,
		const void *	buf
	)

Overwrites fields.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset to overwrite
[in]	field_names	The names of the fields to write
[in]	start	The zero index record to start writing
[in]	nrecords	The number of records to write
[in]	type_size	The size of the structure type, as calculated by sizeof().
[in]	field_offset	An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro
[in]	dst_sizes	An array containing the sizes of the fields
[in]	buf	Buffer with data

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBwrite_fields_name() overwrites one or several fields specified by field_names with data in buf from a dataset named dset_name attached to the object specified by the identifier loc_id.

H5TBwrite_records()

H5_HLDLL herr_t H5TBwrite_records	(	hid_t	loc_id,
		const char *	dset_name,
		hsize_t	start,
		hsize_t	nrecords,
		size_t	type_size,
		const size_t *	field_offset,
		const size_t *	dst_sizes,
		const void *	buf
	)

Overwrites records.

---

Parameters

[in]	loc_id	Location identifier. The identifier may be that of a file or group.
[in]	dset_name	The name of the dataset to overwrite
[in]	start	The zero index record to start writing
[in]	nrecords	The number of records to write
[in]	type_size	The size of the structure type, as calculated by sizeof().
[in]	field_offset	An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro
[in]	dst_sizes	An array containing the sizes of the fields
[in]	buf	Buffer with data

Returns

Returns a non-negative value if successful; otherwise, returns a negative value.

H5TBwrite_records() overwrites records starting at the zero index position start of the table named dset_name attached to the object specified by the identifier loc_id.