CBFlib Manual

Version	Date	By	Description
0.1	Apr. 1998	PJE	This was the first CBFlib release. It supported binary CBF files using binary strings.
0.2	Aug. 1998	HJB	This release added ascii imgCIF support using MIME-encoded binary sections, added the option of MIME headers for the binary strings was well. MIME code adapted from mpack 1.5. Added hooks needed for DDL1-style names without categories.
0.3	Sep. 1998	PJE	This release cleaned up the changes made for version 0.2, allowing multi-threaded use of the code, and removing dependence on the mpack package.
0.4	Nov. 1998	HJB	This release merged much of the message digest code into the general file reading and writing to reduce the number of passes. More consistency checking between the MIME header and the binary header was introduced. The size in the MIME header was adjusted to agree with the version 0.2 documentation.
0.5	Dec. 1998	PJE	This release greatly increased the speed of processing by allowing for deferred digest evaluation.
0.6	Jan. 1999	HJB	This release removed the redundant information (binary id, size, compression id) from a binary header when there is a MIME header, removed the unused repeat argument, and made the memory allocation for buffering and tables with many rows sensitive to the current memory allocation already used.
0.6.1	Feb. 2001	HP (per HJB)	This release fixed a memory leak due to misallocation by size of cbf_handle instead of cbf_handle_struct
0.7	Mar. 2001	PJE	This release added high-level instructions based on the imgCIF dictionary version 1.1.
0.7.1	Mar. 2001	PJE	The high-level functions were revised to permit future expansion to files with multiple images.
0.7.2	Apr. 2001	HJB	This release adjusted cbf_cimple.c to conform to cif_img.dic version 1.1.3
0.7.2.1	May 2001	PJE	This release corrected an if nesting error in the prior mod to cbf_cimple.c.
0.7.3	Oct. 2002	PJE	This release modified cbf_simple.c to reorder image data on read so that the indices are always increasing in memory (this behavior was undefined previously).
0.7.4	Jan 2004	HJB	This release fixes a parse error for quoted strings, adds code to get and set character string types, and removes compiler warnings
0.7.5	Apr 2006	HJB	This release cleans up some compiler warnings, corrects a parse error on quoted strings with a leading blank as adds the new routines for support of aliases, dictionaries and real arrays, higher level routines to get and set pixel sizes, do cell computations, and to set beam centers, improves support for conversion of images, picking up more data from headers.
0.7.6	Jul 2006	HJB	This release reorganizes the kit into two pieces: CBFlib_0.7.6_Data_Files and CBFlib_0.7.6. An optional local copy of getopt is added. The 1.4 draft dictionary has been added. cif2cbf updated to support vcif2 validation. convert_image and cif2cbf updated to report text of error messages. convert_image updated to support tag and category aliases, default to adxv images. convert_image and img updated to support row-major images. Support added for binning. API Support added for validation, wide files and line folding. Logic changed for beam center reporting. Added new routines: cbf_validate, cbf_get_bin_sizes, cbf_set_bin_sizes, cbf_find_last_typed_child, cbf_compose_itemname, cbf_set_cbf_logfile, cbf_make_widefile, cbf_read_anyfile, cbf_read_widefile, cbf_write_local_file, cbf_write_widefile, cbf_column_number, cbf_blockitem_number, cbf_log, cbf_check_category_tags, cbf_set_beam_center
0.7.7	February 2007	HJB	This release reflects changes for base 32K support developed by G. Darakev, and changes for support of reals, 3d arrays, byte_offset compression and J. P. Abrahams packed compression made in consultation with (in alphabetic order) E. Eikenberry, A. Hammerley, W. Kabsch, M. Kobas, J. Wright and others at PSI and ESRF in January 2007, as well accumulated changes fixing problems in release 0.7.6.
0.7.7.1	February 2007	HJB	This release is a patch to 0.7.7 to change the treatment of the byteorder parameter from strcpy semantics to return of a pointer to a string constant. Our thanks to E. Eikenberry for pointing out the problem.
0.7.7.2	February 2007	HJB	This release is a patch to 0.7.7.1 to add testing for JPA packed compression and to respect signs declared in the MIME header.
0.7.7.3	April 2007	HJB	This release is a patch to 0.7.7.3 to add f90 support for reading of CBF byte-offset and packed compression, to fix problems with gcc 4.4.1 and to correct errors in multidimensional packed compression.
0.7.7.4	May 2007	HJB	Corrects in handling SLS detector mincbfs and reorder dimensions versus arrays for some f90 compilers as per H. Powell.
0.7.7.5	May 2007	HJB	Fix to cbf_get_image for bug reported by F. Remacle, fixes for windows builds as per J. Wright and F. Remacle.
0.7.7.6	Jun 2007	HJB	Fix to CBF byte-offset compression writes, fix to Makefiles and m4 for f90 test programs to allow adjustable record length.
0.7.8	Jul 2007	HJB	Release for full support of SLS data files with updated convert_minicbf, and support for gfortran from gcc 4.2.
0.7.8.1	Jul 2007	HJB	Update to 0.7.8 release to fix memory leaks reported by N. Sauter and to update validation checks for recent changes.
0.7.8.2	Dec 2007	CN, HJB	Update to 0.7.8.1 to add ADSC jiffie by Chris Nielsen, and to add ..._fs and ..._sf macros.
0.7.9	Dec 2007	CN, HJB	Identical to 0.7.8.2 except for a cleanup of deprecated examples, e.g. diffrn_frame_data
0.7.9.1	Jan 2008	CN, HJB	Update to 0.7.8.2 to add inverse ADSC jiffie by Chris Nielsen, to clean up problems in handling maps for RasMol.
0.8.0	Jul 2008	GT, HJB	Cleanup of 0.7.9.1 to start 0.8 series.
0.8.1	Jul 2009	EZ, CN, PC, GW, JH, HJB	Release with EZ's 2008 DDLm support using JH's PyCifRW, also cbff f95 wrapper code, PC's java bindings.
0.9.1	Aug 2010	PC, EE, JLM, NS, EZ, HJB	Release with EE's Dectris template software, also with vcif3, new arvai_test, sequence_match.
0.9.2	Feb 2011	PC, EE, JLM, NS, EZ, HJB	New default release with updated pycbf, tiff support, removal of default use of PyCifRW to avoid Fedora license issue.
0.9.3	Oct 2013	JS, HJB	Added low-level 'cbf_H5' functions for interacting with HDF5, higher level functions for converting CBF or miniCBF files to NeXus format, two utility programs to convert CBF or miniCBF files to NeXus format and some unit tests for the low-level 'cbf_H5' functions. Add initial FEL detector support.
0.9.4	March 2014	JS, HJB	Refactored implementation of the NXMX application defintion functional mapping with improvements to cmake support and a preliminary effort at handling Stokes polarization mapping. This release had serious issues in the functional mapping axis mapping and should not be used for production involving NeXus files.
0.9.5	April 2014	HJB	This is a production release for single detector module single crystal MX NeXus support.

2.6 HDF5 abstraction layer and convenience functions

The HDF5 abstraction layer mostly follows the HDF5 naming convention of H5Xfunction_name, where X is usually a single letter identifying the section of the API that the function resides in. A cbf_ prefix is used on all functions to avoid naming conflicts and make it clear that all these functions use the CBFlib error handling method whenever an error may occur.

The main purpose of this API is to not to reimplement the HDF5 API, but to make common HDF5-related tasks easier when working with HDF5 files within CBFlib. The API therefore doesn't attempt to cover every possible use of HDF5, but to simplify common tasks. Use of the HDF5 API is not unexpected in library or user code, but functions in this section should be preferred in order to reduce development time and the amount of debugging required. A relatively comprehensive test program is provided, this should be used to verify that the functions in this section of the API are performing as expected and can be used as a source of example code.

This section describes functions available for working with:

Attributes:
Datasets:
Files:
- 2.6.21 cbf_H5Fopen
- 2.6.22 cbf_H5Fclose
Groups:
Identifiers:
- 2.6.27 cbf_H5Ivalid
Objects:
- 2.6.28 cbf_H5Ocmp
- 2.6.29 cbf_H5Ofree
Dataspaces:
- 2.6.30 cbf_H5Screate
- 2.6.31 cbf_H5Sfree
Datatypes:
- 2.6.32 cbf_H5Tcreate_string
- 2.6.33 cbf_H5Tfree

Rank of a dataset

Where a rank is required it must be equal to the length of the dim, max & chunk parameters, if they are given, and should be:

0, for scalar data
1, for vector data
2, for matrix data
3, for volume data
etc...

The maximum rank is defined by the HDF5 library, a negative rank makes no sense and will often be treated as an error.

HDF5-specific datatypes

Any type parameters defining types for data stored in a file should usually be a value returned by cbf_H5Tcreate_string or one of the standard or IEEE types:

`H5T_STD_I8LE`	`H5T_STD_I16LE`	`H5T_STD_I32LE`	`H5T_STD_I64LE`
`H5T_STD_U8LE`	`H5T_STD_U16LE`	`H5T_STD_U32LE`	`H5T_STD_U64LE`
`H5T_STD_I8BE`	`H5T_STD_I16BE`	`H5T_STD_I32BE`	`H5T_STD_I64BE`
`H5T_STD_U8BE`	`H5T_STD_U16BE`	`H5T_STD_U32BE`	`H5T_STD_U64BE`
`H5T_IEEE_F32LE`	`H5T_IEEE_F64LE`	`H5T_IEEE_F32BE`	`H5T_IEEE_F64BE`

Any type parameters defining types for data stored in memory should usually be a value returned by cbf_H5Tcreate_string or one of the native types:

`H5T_NATIVE_SCHAR`	`H5T_NATIVE_SHORT`	`H5T_NATIVE_INT`	`H5T_NATIVE_LONG`	`H5T_NATIVE_LLONG`
`H5T_NATIVE_UCHAR`	`H5T_NATIVE_USHORT`	`H5T_NATIVE_UINT`	`H5T_NATIVE_ULONG`	`H5T_NATIVE_ULLONG`
`H5T_NATIVE_FLOAT`	`H5T_NATIVE_DOUBLE`	`H5T_NATIVE_LDOUBLE`

Functions are rarely (if ever) limited to the above values, and can take any valid HDF5 datatype. The above is not a complete list of all available types, check the HDF5 documentation for such a list if you need one.

Comparing data

Some of the functions in this section will require a comparison function and some comparison parameters to be provided. The function should return zero if the data in the two arrays are considered equal and non-zero otherwise, note that this is the same as C's strcmp(). The signature of the comparison functions used here is:

int compare (const void * expected, const void * existing, size_t length, const void * params)

This will be called with:

Type	Name	Description
const void *	expected	A pointer to the array of requested values that was passed to the function.
const void *	existing	An array of existing values read from the object.
size_t	length	The length of the `expected` and `existing` arrays.
const void *	params	A pointer to the comparison parameters which were passed to the calling function.

The comparison parameters allow more complex comparisons to be performed, such as a check that the numbers are 'close enough' as determined by some variable measure of closeness. It is the caller's responsibility to ensure that the comparison function is appropriate for the type of data expected and that params is of the appropriate type for the comparison function. The parameters expected and existing should normally be cast to the appropriate type before being used.

An example function for comparing ints, taken from the implementation of CBFlib:


          /*
Compare two arrays of ints.
Most parameters are defined as being 'const' even though
the expected signature allows them to be mutable.
*/
int cmp_int
    (const void * const expected,
     const void * const existing,
     size_t length,
     const void * const params)
{
	/*
    Cast the array pointers to the appropriate type, preserving the const-ness of the data.
    I won't be using any parameters for this comparison, so just ignore that argument.
	*/
    const int * A = expected;
    const int * B = existing;

	/*
    Iterate through the arrays comparing each element and decrementing a counter.
    If any are not equal the loop will exit early with length being non-zero.
	*/
    while (length && *A++ == *B++) --length;

	/*
    Return a value indicating whether the arrays are equal.
	*/
    return length;
}

Some older functions use a simpler 3-argument comparison function, which doesn't have a parameter that can be used to pass some extra information to or retrieve information from the function.

2.6.1 cbf_H5Acreate

Create a new attribute.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Acreate (const hid_t location, hid_t *const attr, const char *const name, const hid_t type, const hid_t space)

DESCRIPTION

Creates a new attribute of the object location with name given by name, optionally returning it in the attr variable. An error will occur if a similarly named attribute already exists.

ARGUMENTS

location	The hdf5 group/file in which to put the attribute.
attr	A pointer to a HDF5 object identifier that is set to the location of a valid object if the function succeeds, otherwise is left untouched.
name	The name of the existing/new dataset.
type	The type of data to be stored in the attribute.
space	The dataspace of the attribute.

RETURN VALUE

An error code.

SEE ALSO

2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.2 cbf_H5Afind

Try to locate an existing attribute.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Afind (const hid_t location, hid_t *const attr, const char *const name, const hid_t type, const hid_t space)

DESCRIPTION

Checks for the existance of an attribute with the given name at location with a datatype of type and dataspace of space. Will return CBF_NOTFOUND if it cannot be found, or open it if it already exists.

If type is not a datatype then no check of the attribute datatype will be done. If space is not a dataspace then no checks of the attribute dataspace wil be done.

ARGUMENTS

location	The hdf5 group/file in which to put the attribute.
attr	A pointer to a HDF5 object identifier that is set to the location of a valid object if the function succeeds, otherwise is left untouched.
name	The name of the existing/new attribute.
type	The type of data stored in the attribute, or an invalid identifier if it should not be checked.
space	The dataspace of the attribute, or an invalid identifier if it should not be checked.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.3 cbf_H5Aread

Read an entire attribute from a file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Aread (const hid_t attr, const hid_t type, void *const buf)

DESCRIPTION

Reads all of the data from attr into buf, which should have been allocated as the native type indicated by mem_type.

ARGUMENTS

attr	A valid hdf5 handle for an attribute.
type	The type of data in memory.
buf	The location where the data is to be stored.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.4 cbf_H5Aread_string

Read an entire string attribute from a file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Aread_string (const hid_t attr, const char **const val)

DESCRIPTION

Read a string attribute into memory, returning a pointer that must be free'd by the caller in val.

ARGUMENTS

attr	The attribute to read from.
val	A pointer to a place the string may be stored.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.5 cbf_H5Awrite

Write an entire attribute to a file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Awrite (const hid_t attr, const hid_t type, void *const buf)

DESCRIPTION

Writes all of the data from buf, which should contain data if the type indicated by mem_type, into attr.

ARGUMENTS

attr	A valid hdf5 handle for an attribute.
type	The type of data in memory.
buf	The address of the data to be written.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.6 cbf_H5Arequire_cmp2

Check for an attribute with the given space/type/value, or set one if it doesn't exist.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Arequire_cmp2 (const hid_t ID, const char *const name, const int rank, const hsize_t *const dim, const hid_t fileType, const hid_t memType, const void *const value, void *const buf, int(*cmp)(const void *, const void *, size_t))

DESCRIPTION

Checks the existance of an attribute of the given name, size, type and value. Equal value is determined by a custom comparison function which may use some extra data for more sophisticated tests. A new attribute with the given properties will be created if none currently exist, the function will fail if an incompatible attribute exists.

ARGUMENTS

ID	The HDF5 object that the attribute will be applied to.
name	The name of the attribute.
rank	The number of dimensions of the attribute data, 0 for scalar data.
dim	The length of each dimension, not used for scalar data.
fileType	The HDF5 type of the attribute data in the file.
memType	The HDF5 type of the attribute data in memory.
value	The data to be written to the attribute.
buf	A buffer to be used when reading an existing attribute of the same size.
cmp	A comparison function to test if a previously set value is equal to the value I asked for.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.7 cbf_H5Arequire_cmp2_ULP

Check for an attribute with the given space/type/value, or set one if it doesn't exist.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Arequire_cmp2_ULP (const hid_t ID, const char *const name, const int rank, const hsize_t *const dim, const hid_t fileType, const hid_t memType, const void *const value, void *const buf, int(*cmp)(const void *, const void *, size_t, const void *), const void *const cmp_params)

DESCRIPTION

ARGUMENTS

ID	The HDF5 object that the attribute will be applied to.
name	The name of the attribute.
rank	The number of dimensions of the attribute data, 0 for scalar data.
dim	The length of each dimension, not used for scalar data.
fileType	The HDF5 type of the attribute data in the file.
memType	The HDF5 type of the attribute data in memory.
value	The data to be written to the attribute.
buf	A buffer to be used when reading an existing attribute of the same size.
cmp	A comparison function to test if a previously set value is equal to the value I asked for.
cmp_params	A pointer to a data structure which may be used by the comparison function.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.8 cbf_H5Arequire_string

Check for a scalar string attribute with a given value, or set one if it doesn't exist.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Arequire_string (const hid_t location, const char *const name, const char *const value)

DESCRIPTION

Forwarding function that calls cbf_H5Arequire_cmp2_ULP with the appropriate arguments to compare two strings. The strcmp function is used for string comparison, with a small wrapper to verify array length:


          /** a possible implementation of a function to compare two strings for equality */
static int cmp_string
    (const void * const a,
     const void * const b,
     const size_t N,
     const void * const params)
{
	/* first ensure the arrays have one element each */
    if (1 != N) return 1;
	/* then forward to 'strcmp' for the actual comparison */
    else return strcmp(a,b);
}

ARGUMENTS

location	HDF5 object to which the string attribute should/will belong.
name	The name of the attribute.
value	The value which the attribute should/will have.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.9 cbf_H5Afree

2.6.9 cbf_H5Afree

Close a HDF5 attribute.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Afree (const hid_t ID)

DESCRIPTION

Attempt to close an attribute, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 attribute to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string

2.6.10 cbf_H5Dcreate

Creates a new dataset in the given location.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dcreate (const hid_t location, hid_t *const dataset, const char *const name, const int rank, const hsize_t *const dim, const hsize_t *const max, const hsize_t *const chunk, const hid_t type)

DESCRIPTION

The dataset parameter gives a location to store the dataset for use by the caller, for example to add an attribute to it. If non-zero the returned handle MUST be free'd by the caller with cbf_H5Dfree.

The dimensions of the dataset to create are given in dim. The maximum extents of the dataset are given in max, which uses the values in dim as defaults if set to a null pointer. Each element of max must be at least as large as the corresponding element of dim. The dataset created will be a fixed-size dataset unless one of the elements of max is set to H5S_UNLIMITED.

A chunk size must be given in the chunk argument if any element of max is set to H5S_UNLIMITED or is greater than the corresponding element of dim. If the dataset should not be chunked then a null pointer should be given.

The dim, max and chunk arrays - if given - must each contain rank elements.

This function will fail if a link with the same name already exists in location.

ARGUMENTS

location	The hdf5 group/file in which to put the dataset.
dataset	An optional pointer to a location where the dataset handle should be stored.
name	The name of the new dataset.
rank	The rank of the data.
dim	The dimensions of the dataset to create. Unused if `rank == 0`.
max	The maximum size of each dimension. Unused if `rank == 0`.
chunk	The chunk size for the dataset.
type	The type of each data element in the file.

RETURN VALUE

An error code.

SEE ALSO

2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.11 cbf_H5Dfind2

Look for a dataset with the given properties.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dfind2 (const hid_t location, hid_t *const dataset, const char *const name, const int rank, const hsize_t *const max, hsize_t *const buf, const hid_t type)

DESCRIPTION

Returns CBF_NOTFOUND without modifying dataset if no dataset exists and fails without modifying dataset if one with different properties exists. A dataset will be 'found' if it has the same name and a maximum size which is at least as big as the size requested in max.

A buffer of rank elements pointed to by buf may be used to store the array of maximum extents for a potentially matching dataset, in order to avoid the use of malloc & free for very small amounts of memory.

Use as:


          /* Get the return code from the function call, */
const int found = cbf_H5Dfind(location, &dataset, ...);
/* and check what it was: */
if (CBF_SUCCESS==found) {
	/* A dataset already existed and I have a handle for it: */
    use_existing_dataset(dataset);
} else if (CBF_NOTFOUND==found) {
	/* No matching dataset existed, so I can create one: */
	cbf_H5Dcreate(location, &dataset, ...);
    use_new_datset(dataset);
} else {
	/*
    The function call failed, do something with the error.
    In this case, store it for later use and print a message.
	*/
    error |= found;
     cbf_debug_print(cbf_strerror(error));
}
/* clean up: */
cbf_H5Dfree(dataset);

ARGUMENTS

location	The hdf5 group/file in which to put the dataset.
dataset	A pointer to a HDF5 object identifier that is set to the location of a valid object if the function succeeds, otherwise is left in an undefined state.
name	The name of the existing/new dataset.
rank	The rank of the data, must be equal to the length of the `max` and `buf` arrays, if they are given.
max	The (optional) maximum size of each dimension, pointer or an array of length `rank` where `0 <= max[i] <= H5S_UNLIMITED` for `i = [0, rank)`, unused if `rank == 0`.
buf	An optional buffer with `rank` elements which may be used to store the current maximum dimensions of a potential match to avoid a malloc/free call.
type	The type of each data element in the file. If an invalid type is given a dataset of any type may be returned.

RETURN VALUE

CBF_SUCCESS if a matching dataset was found, CBF_NOTFOUND if nothing with the same name was found, some other error code otherwise.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.12 cbf_H5Drequire

Ensure that a dataset exists, returning a handle to an existing dataset or creating a new dataset if needed.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Drequire (const hid_t location, hid_t *const dataset, const char *const name, const int rank, const hsize_t *const max, const hsize_t *const chunk, hsize_t *const buf, const hid_t type)

DESCRIPTION

Ensure a dataset of the given rank exists and can hold at least as many elements as specified in max. If no dataset exists then one will be created with dimensions of [0, 0, ... 0]. cbf_H5Dfind and cbf_H5Dcreate are used in the implementation of this function.

An existing dataset may be found using cbf_H5Dfind2(location, dataset, name, rank, max, buf, type). If no dataset can be found then a dataset will be created by setting each element of a buffer of length rank to zero and using cbf_H5Dcreate(location, dataset, name, rank, buffer, max, chunk, type). A buffer of rank elements may be provided to avoid using malloc to allocate memory for a small array whose size may already be known.

The value pointed to by dataset should be a valid object identifier if the function exits successfully, and will be left in an undefined state otherwise.

This is roughly equivalent to:


          const int error = cbf_H5Dfind2(location, dataset, name, rank, max, buf, type);
if (CBF_NOTFOUND==error) {
	int i;
	for (i = 0; i != rank; ++i) buf[i] = 0;
	return cbf_H5Dcreate(location, dataset, name, rank, buf, max, chunk, type);
} else {
	/* 'error' may be 'CBF_SUCCESS' or could indicate an error: */
	return error;
}

but contains more sophisticated error handling code and allows for some parameters to be omitted.

ARGUMENTS

location	The hdf5 group/file in which to put the dataset.
dataset	A pointer to a location to store the dataset.
name	The name of the existing/new dataset.
rank	The rank of the data.
max	The (optional) maximum size of each dimension.
chunk	The chunk size used if creating a new dataset.
buf	An optional buffer with `rank` elements.
type	The type of each data element in the file.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.13 cbf_H5Dinsert

Add some data to a datset, expanding the dataset to the appropriate size if needed.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dinsert (const hid_t dataset, const hsize_t *const offset, const hsize_t *const stride, const hsize_t *const count, hsize_t *const buf, const void *const value, const hid_t type)

DESCRIPTION

Insert a slice of data into dataset with the appropriate offset & stride, ensuring that no existing data is lost due to resizing the dataset but not checking that previous data isn't being overwritten.

The offset, stride, count and buf arrays must each have rank elements. If stride is set to the null pointer then a default of [1, 1, 1, ..., 1] will be used. An optional buffer may be provided in buf to avoid using malloc to allocate a small amount of memory whose size may actually be known at compile time.

The value array should contain count[0] * count[1] * ... * count[rank-1] === product(count) elements of data.

ARGUMENTS

dataset	The dataset to write the data to.
offset	Where to start writing the data.
stride	The number of elements in the dataset to step for each element to be written.
count	The number of elements in each dimension to be written.
buf	An optional buffer to avoid using the heap for small amounts of memory.
value	The address of the data to be written.
type	The type of data in memory.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.14 cbf_H5Dset_extent

Change the extent of a chunked dataset to the values in dim.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dset_extent (const hid_t dataset, const hsize_t *const dim)

DESCRIPTION

Forwards to a HDF5 function to change the extent of dataset. The dim array must have the same number of elements as the rank of the dataset, but this can't be checked within this function.

ARGUMENTS

dataset	A handle for the dataset whose extent is to be changed.
dim	The new extent of the dataset, if the function succeeds.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.15 cbf_H5Dwrite2

Add some data to the specified position in the dataset, without checking what (if anything) was there before.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dwrite2 (const hid_t dataset, const hsize_t *const offset, const hsize_t *const stride, const hsize_t *const count, const void *const value, const hid_t type)

DESCRIPTION

Assumes the dataset has the appropriate size to contain all the data and overwrites any existing data that may be there. The rank of the dataset is assumed to be known, and the size of the array parameters is not tested. When rank is zero - in the case of scalar datasets - the offset, stride and count parameters are meaningless and should be omitted by setting them to zero.

ARGUMENTS

dataset	The dataset to write the data to.
offset	Where to start writing the data, as an array of `rank` numbers.
stride	The number of elements in the dataset to step for each element to be written, where null is equivalent to a stride of [1, 1, 1, ..., 1], as an array of `rank` numbers.
count	The number of elements in each dimension to be written, as an array of `rank` numbers.
value	The address of the data to be written.
type	The type of data in memory.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.16 cbf_H5Dread2

Extract some existing data from a dataset at a known position with memtype.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dread2 (const hid_t dataset, const hsize_t *const offset, const hsize_t *const stride, const hsize_t *const count, void *const value, const hid_t type)

DESCRIPTION

Read some data from a given location in the dataset to an existing location in memory. Does not check the length of the array parameters, which should all have rank elements or (in some cases) be null. When rank is zero - in the case of scalar datasets - the offset, stride and count parameters are meaningless and should be omitted by setting them to zero.

ARGUMENTS

dataset	The dataset to read the data from.
offset	Where to start writing the data, as an array of `rank` numbers.
stride	The number of elements in the dataset to step for each element to be written, where null is equivalent to a stride of [1, 1, 1, ..., 1], as an array of `rank` numbers.
count	The number of elements in each dimension to be written, as an array of `rank` numbers.
value	The location where the data is to be stored.
type	The type of data in memory.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.17 cbf_H5Drequire_scalar_F64LE2

Write a scalar 64-bit floating point number as a dataset with comparison.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Drequire_scalar_F64LE2 (const hid_t location, hid_t *const dataset, const char *const name, const double value, int(*cmp)(const void *, const void *, size_t))

DESCRIPTION

Convenience function using the HDF5 abstraction layer to avoid the need to consider array-related parameters for a scalar dataset.It ensures that a scalar 64-bit IEEE floating point dataset exists with the appropriate name and (for an existing dataset) the correct value as determined by the comparison function cmp.

ARGUMENTS

location	The group containing the new dataset.
dataset	An optional pointer to a place to store the new dataset.
name	The name of the new dataset.
value	The value of the new dataset.
cmp	A comparison function to test if a previously set value is equal to the value I asked for.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP

Write a scalar 64-bit floating point number as a dataset with a user-defined comparison.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Drequire_scalar_F64LE2_ULP (const hid_t location, hid_t *const dataset, const char *const name, const double value, int(*cmp)(const void *, const void *, size_t, const void *), const void *const cmp_params)

DESCRIPTION

Convenience function using the HDF5 abstraction layer to avoid the need to consider array-related parameters for a scalar dataset. It ensures that a scalar 64-bit IEEE floating point dataset exists with the appropriate name and (for an existing dataset) the correct value as determined by the user-supplied comparison function cmp.

It is implemented using some of the other dataset functions:

cbf_H5Dfind2
cbf_H5Dcreate
cbf_H5Dread2
cbf_H5Dwrite2

ARGUMENTS

location	The group containing the new dataset.
dataset	An optional pointer to a place to store the new dataset.
name	The name of the new dataset.
value	The value of the new dataset.
cmp	A comparison function to test if a previously set value is equal to the value I asked for.
cmp_params	Some extra data which may be required by the comparison function.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.19 cbf_H5Drequire_flstring

Write a single fixed-length string as a dataset.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Drequire_flstring (const hid_t location, hid_t *const dataset, const char *const name, const char *const value)

DESCRIPTION

Convenience function using the HDF5 abstraction layer to avoid the need to consider array-related parameters for a scalar dataset and to automatically set the string type to the correct size.

ARGUMENTS

location	The group containing the new dataset.
dataset	An optional pointer to a place to store the new dataset.
name	The name of the new dataset.
value	The value of the new dataset.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.20 cbf_H5Dfree

2.6.20 cbf_H5Dfree

Close a HDF5 dataset.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dfree (const hid_t ID)

DESCRIPTION

Attempt to close a dataset, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 dataset to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring

2.6.21 cbf_H5Fopen

Attempt to open an HDF5 file by file name.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Fopen (hid_t *const file, const char *const name)

DESCRIPTION

Will try to open a file of the given name with suitable values for some of it's properties to make memory leaks less likely.

Warning: this function will destroy any existing data in the file, do not pass the name of any file containing data you want to keep.

ARGUMENTS

file	A pointer to an HDF5 ID where the newly opened file should be stored.
name	The name of the file to attempt to open.

RETURN VALUE

An error code.

SEE ALSO

2.6.22 cbf_H5Fclose

2.6.22 cbf_H5Fclose

Close a HDF5 file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Fclose (const hid_t ID)

DESCRIPTION

Attempt to close a file, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 file to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.21 cbf_H5Fopen

2.6.23 cbf_H5Gcreate

Attempt to create a group.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Gcreate (const hid_t location, hid_t *const group, const char *const name)

DESCRIPTION

Helper function to attempt to create a HDF5 group identified by name and return an error code, to make error handling more consistant. This will fail if a link with the same name already exists in parent.

ARGUMENTS

location	The group that will contain the newly created group.
group	A pointer to a HDF5 ID type where the group will be stored.
name	The name that the group will be given.

RETURN VALUE

An error code.

SEE ALSO

2.6.24 cbf_H5Gfind
2.6.25 cbf_H5Grequire
2.6.26 cbf_H5Gfree

2.6.24 cbf_H5Gfind

Check if a group exists.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Gfind (const hid_t location, hid_t *const group, const char *const name)

DESCRIPTION

Checks for the existance of a group with the given name and parent. Will return CBF_NOTFOUND if it cannot be found, or open it if it already exists. An error code will be returned if something other than a group exists at the specified location.

ARGUMENTS

location	The group to be searched.
group	A pointer to a HDF5 ID type where the group will be stored.
name	The path (ie, name) of the group to be found.

RETURN VALUE

An error code.

SEE ALSO

2.6.23 cbf_H5Gcreate
2.6.25 cbf_H5Grequire
2.6.26 cbf_H5Gfree

2.6.25 cbf_H5Grequire

Ensure a group exists.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Grequire (const hid_t location, hid_t *const group, const char *const name)

DESCRIPTION

Checks for the existance of a group with the given name and parent. Will create the group if it cannot be found, or open it if it already exists. It is an error if a matching group cannot be found or created. This uses cbf_H5Gcreate to create any new groups.

ARGUMENTS

location	The group that will contain the newly created group.
group	A pointer to a HDF5 ID type where the group will be stored.
name	The name that the group will be given.

RETURN VALUE

An error code.

SEE ALSO

2.6.23 cbf_H5Gcreate
2.6.24 cbf_H5Gfind
2.6.26 cbf_H5Gfree

2.6.26 cbf_H5Gfree

Close a HDF5 group.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Gfree (const hid_t ID)

DESCRIPTION

Attempt to close a group, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 group to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.23 cbf_H5Gcreate
2.6.24 cbf_H5Gfind
2.6.25 cbf_H5Grequire

2.6.27 cbf_H5Ivalid

Check the validity of an object identifier.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Ivalid (const hid_t ID)

DESCRIPTION

Function to check validity of a HDF5 identifier. HDF5's predefined types are never counted as valid by this function, so it can't be used to test the validity of a type constant. Types obtained by using H5Tcopy are safe to test.

ARGUMENTS

ID	An HDF5 object identifier.

RETURN VALUE

Non-zero if the type is valid, zero otherwise.

SEE ALSO

2.6.28 cbf_H5Ocmp

2.6.28 cbf_H5Ocmp

A missing HDF5 function.

PROTOTYPE

#include "cbf_hdf5.h"
htri_t cbf_H5Ocmp (const hid_t id0, const hid_t id1)

DESCRIPTION

Compare two HDF5 object ID's for equality. This follows the standard practice of returning zero if objects should be considered equal, and the HDF5 practice of returning a negative number if there is an error.

ARGUMENTS

id0	An HDF5 identifier.
id1	An HDF5 identifier.

RETURN VALUE

0 if equal, a positive value if not equal, or a negative value if there is an error.

SEE ALSO

2.6.27 cbf_H5Ivalid

2.6.29 cbf_H5Ofree

Close a HDF5 object identifier.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Ofree (const hid_t ID)

DESCRIPTION

Attempt to close an object identifier of unknown type, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 object to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.28 cbf_H5Ocmp
2.6.27 cbf_H5Ivalid

2.6.30 cbf_H5Screate

Create a dataspace with some given values.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Screate (hid_t *const ID, const int rank, const hsize_t *const dim, const hsize_t *const max)

DESCRIPTION

Helper function which creates a HDF5 dataspace.

Maximum dimensions can be set to infinity by passing H5S_UNLIMITED in the appropriate slot of the max parameter. If rank is zero then neither dim nor max are used and a scalar dataspace is created. If rank is non-zero and dim is a null pointer then ID will not be modified and the function will fail. If rank is non-zero and max is a null pointer the maximum length is set to the current length as given by dim.

ARGUMENTS

ID	A pointer to a HDF5 identifier that will contain the new dataspace.
rank	The number of dimensions of the new dataspace.
dim	The current size of each dimension of the dataspace, should be an array of length `rank` .
max	The maximum size of each dimension, should be an array of length `rank` .

RETURN VALUE

An error code.

SEE ALSO

2.6.31 cbf_H5Sfree

2.6.31 cbf_H5Sfree

Close a HDF5 dataspace identifier.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Sfree (const hid_t ID)

DESCRIPTION

Attempt to close a dataspace identifier, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 dataspace to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.30 cbf_H5Screate

2.6.32 cbf_H5Tcreate_string

Get a HDF5 string datatype to describe a sting of the specified length.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Tcreate_string (hid_t *const type, const size_t len)

DESCRIPTION

Convenience function to create a string datatype suitable for use when storing a string of length len, returning it in the identifier pointed to by type.

ARGUMENTS

type	A pointer to a the HDF5 handle of the new datatype, which should be free'd with `cbf_H5Tfree`
len	The length of the string datatype - should be `strlen()` or `H5T_VARIABLE`

RETURN VALUE

An error code.

SEE ALSO

2.6.33 cbf_H5Tfree

2.6.33 cbf_H5Tfree

Close a HDF5 datatype identifier.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Tfree (const hid_t ID)

DESCRIPTION

Attempt to close a datatype identifier, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 datatype to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.32 cbf_H5Tcreate_string

2.7 High-level NeXus-related functions

These functions primarily allow interaction with a cbf_h5handle without being exposed to its structure or the complexities of using it correctly. Wherever possible these functions should be used instead of directly accessing a cbf_h5handle or cbf_config_t in order make code easier to read, to maintain the integrity of the data structures and to ensure all resources allocated to these object are correctly cleaned up.

This section describes functions available for working with:

CBF's HDF5 handles:
miniCBF configuration settings:

Reading miniCBF configuration settings

This example demonstrates how a miniCBF configuration file should be parsed, what should be checked before the extracted settings are used and what should be cleaned up by the caller afterwards:


          /* Declare some important variables */
int configError = cbf_configError_success;
FILE * configFile = fopen("config.txt","r");
cbf_config_t * const configSettings = cbf_config_create();

/*
Read and check the configuration settings,
writing any error messages to stderr.
*/
configError = cbf_config_parse(configFile,stderr,configSettings);
/* I no longer need to keep the file open */
fclose(configFile);

/* Check if I could read the file successfully */
if (cbf_configError_success != configError) {
    fprintf(stderr,"Error parsing configuration file 'config.txt': %s\n",
            cbf_config_strerror(configError));
} else {
	/* Use the configuration settings here... */
}

/* Clean up the settings to avoid memory leaks */
cbf_config_free(configSettings);

2.7.1 cbf_h5handle_get_file

Get the current id of the file within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_file (const cbf_h5handle nx, hid_t *const file)

DESCRIPTION

Check the handle for the presence of a file, optionally returning it.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
file	A place to store the file (if found), or null if the file isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.2 cbf_h5handle_set_file

2.7.2 cbf_h5handle_set_file

Set the id of the file within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_file (const cbf_h5handle nx, const hid_t file)

DESCRIPTION

Sets the file id within the handle to the given value. Doesn't check or modify any attributes in any way.

ARGUMENTS

nx	The handle to add information to.
file	The file to be set as the current file id.

RETURN VALUE

An error code.

SEE ALSO

2.7.1 cbf_h5handle_get_file

2.7.3 cbf_h5handle_get_entry

Get the current id and name of the entry group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_entry (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an entry group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.4 cbf_h5handle_set_entry
2.7.5 cbf_h5handle_require_entry

2.7.4 cbf_h5handle_set_entry

Set the id and name of the entry group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_entry (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the entry group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current entry group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.3 cbf_h5handle_get_entry
2.7.5 cbf_h5handle_require_entry

2.7.5 cbf_h5handle_require_entry

Ensure I have an entry in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_entry (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the entry group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"entry"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.3 cbf_h5handle_get_entry
2.7.4 cbf_h5handle_set_entry

2.7.6 cbf_h5handle_require_entry_definition

Ensure I have an entry in the hdf5 handle with definition.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_entry_definition (const cbf_h5handle nx, hid_t *const group, const char *name, const char *definition, const char *version, const char *URL)

DESCRIPTION

This will check if the entry group and definition within the handle matches any existing group of the same name within the current file and has a definition designation that agrees. If the group name doesn't match a new group is opened or created and added to the handle. If the definition does not match, it is replaced with the new one. If the version attribute does not match it is replaced with the new one. If the URL> attribute does not match it is replace with the new one. The NX_class attributes are not checked, but if a new entry is created it will be created with NX_class NXentry.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group ID should be stored.
name	The group name, or null to use the default name of `"entry"`.
definition	The definition name, or null to not specify a definition name.
version	The version string, or null to not specify a version string.
URL	The URL at which the definition is stored, or null to not specify a URL

RETURN VALUE

An error code.

SEE ALSO

2.7.3 cbf_h5handle_get_entry
2.7.4 cbf_h5handle_set_entry
2.7.5 cbf_h5handle_require_entry

2.7.7 cbf_h5handle_get_sample

Get the current id and name of the sample group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_sample (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an sample group and its name, optionally returning any combination of them.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.8 cbf_h5handle_set_sample
2.7.9 cbf_h5handle_require_sample

2.7.8 cbf_h5handle_set_sample

Set the id and name of the sample group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_sample (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the sample group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current sample group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.7 cbf_h5handle_get_sample
2.7.9 cbf_h5handle_require_sample

2.7.9 cbf_h5handle_require_sample

Ensure I have a sample in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_sample (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the sample group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"sample"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.7 cbf_h5handle_get_sample
2.7.8 cbf_h5handle_set_sample

2.7.10 cbf_h5handle_get_beam

Get the current id and name of the beam group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_beam (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of a beam group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.11 cbf_h5handle_set_beam
2.7.12 cbf_h5handle_require_beam

2.7.11 cbf_h5handle_set_beam

Set the id and name of the beam group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_beam (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the beam group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current beam group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.10 cbf_h5handle_get_beam
2.7.12 cbf_h5handle_require_beam

2.7.12 cbf_h5handle_require_beam

Ensure I have a beam in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_beam (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the beam group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"beam"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.10 cbf_h5handle_get_beam
2.7.11 cbf_h5handle_set_beam

2.7.13 cbf_h5handle_get_instrument

Get the current id and name of the instrument group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_instrument (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an instrument group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.14 cbf_h5handle_set_instrument
2.7.15 cbf_h5handle_find_instrument
2.7.16 cbf_h5handle_require_instrument

2.7.14 cbf_h5handle_set_instrument

Set the id and name of the instrument group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_instrument (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the instrument group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current instrument group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.13 cbf_h5handle_get_instrument
2.7.15 cbf_h5handle_find_instrument
2.7.16 cbf_h5handle_require_instrument

2.7.15 cbf_h5handle_find_instrument

Find an existing instrument group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_find_instrument (const cbf_h5handle nx, hid_t *const group, const char **const name)

ARGUMENTS

nx
group
name

2.7.16 cbf_h5handle_require_instrument

Ensure I have an instrument in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_instrument (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the instrument group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"instrument"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.13 cbf_h5handle_get_instrument
2.7.14 cbf_h5handle_set_instrument
2.7.15 cbf_h5handle_find_instrument

2.7.17 cbf_h5handle_get_detector

Get the current id and name of the detector group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_detector (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an detector group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.18 cbf_h5handle_set_detector
2.7.19 cbf_h5handle_find_detector
2.7.20 cbf_h5handle_require_detector

2.7.18 cbf_h5handle_set_detector

Set the id and name of the detector group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_detector (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the detector group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current detector group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.17 cbf_h5handle_get_detector
2.7.19 cbf_h5handle_find_detector
2.7.20 cbf_h5handle_require_detector

2.7.19 cbf_h5handle_find_detector

Find an existing detector group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_find_detector (const cbf_h5handle nx, hid_t *const group, const char **const name)

ARGUMENTS

nx
group
name

2.7.20 cbf_h5handle_require_detector

Ensure I have a detector in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_detector (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the detector group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"detector"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.17 cbf_h5handle_get_detector
2.7.18 cbf_h5handle_set_detector
2.7.19 cbf_h5handle_find_detector

2.7.21 cbf_h5handle_get_goniometer

Get the current id and name of the goniometer group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_goniometer (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an goniometer group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.22 cbf_h5handle_set_goniometer
2.7.23 cbf_h5handle_require_goniometer

2.7.22 cbf_h5handle_set_goniometer

Set the id and name of the goniometer group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_goniometer (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the goniometer group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current goniometer group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.21 cbf_h5handle_get_goniometer
2.7.23 cbf_h5handle_require_goniometer

2.7.23 cbf_h5handle_require_goniometer

Ensure I have a goniometer in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_goniometer (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the goniometer group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"goniometer"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.21 cbf_h5handle_get_goniometer
2.7.22 cbf_h5handle_set_goniometer

2.7.24 cbf_h5handle_get_monochromator

Get the current id and name of the monochromator group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_monochromator (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an monochromator group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.25 cbf_h5handle_set_monochromator
2.7.26 cbf_h5handle_require_monochromator

2.7.25 cbf_h5handle_set_monochromator

Set the id and name of the monochromator group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_monochromator (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the monochromator group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current monochromator group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.24 cbf_h5handle_get_monochromator
2.7.26 cbf_h5handle_require_monochromator

2.7.26 cbf_h5handle_require_monochromator

Ensure I have a monochromator in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_monochromator (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the monochromator group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"monochromator"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.24 cbf_h5handle_get_monochromator
2.7.25 cbf_h5handle_set_monochromator

2.7.27 cbf_h5handle_get_source

Get the current id and name of the source group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_source (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an source group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.28 cbf_h5handle_set_source
2.7.29 cbf_h5handle_require_source

2.7.28 cbf_h5handle_set_source

Set the id and name of the source group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_source (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the source group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current source group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.27 cbf_h5handle_get_source
2.7.29 cbf_h5handle_require_source

2.7.29 cbf_h5handle_require_source

Ensure I have a source in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_source (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the source group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"source"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.27 cbf_h5handle_get_source
2.7.28 cbf_h5handle_set_source

2.7.30 cbf_free_h5handle

Free a handle for an HDF5 file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_free_h5handle (cbf_h5handle h5handle)

DESCRIPTION

Checks if the handle appears to be valid, the free's the handle and any data that the handle owns.

ARGUMENTS

h5handle

The handle to be free'd.

RETURN VALUE

An error code

SEE ALSO

2.7.31 cbf_create_h5handle3

2.7.31 cbf_create_h5handle3

Allocates space for a HDF5 file handle and associates it with the given file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_create_h5handle3 (cbf_h5handle *handle, hid_t file)

DESCRIPTION

This function expects the user to create or open a hdf5 file with the appropriate parameters for what they are trying to do, replacing older functions which would create a file with the H5F_ACC_TRUNC flag and H5F_CLOSE_STRONG property.

ARGUMENTS

handle	A pointer to a handle which is to be allocated.
file	A HDF5 file to store within the newly created handle.

RETURN VALUE

An error code

SEE ALSO

2.7.30 cbf_free_h5handle

2.7.32 cbf_write_cbf_h5file

Extract the data from a CBF file & put it into a NeXus file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_write_cbf_h5file (cbf_handle handle, cbf_h5handle h5handle)

DESCRIPTION

Equivalent to cbf_write_cbf2nx(handle,h5handle,0,0,0).

ARGUMENTS

handle	The CBF file to extract data from.
h5handle	The NeXuS file to write data to.

RETURN VALUE

An error code.

SEE ALSO

2.7.34 cbf_write_minicbf_h5file
2.7.33 cbf_write_cbf2nx
2.7.35 cbf_write_nx2cbf

2.7.33 cbf_write_cbf2nx

Extract the data from a CBF file & put it into a NeXus file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_write_cbf2nx (cbf_handle handle, cbf_h5handle h5handle, const char *const datablock, const char *const scan, const int list)

DESCRIPTION

Extracts data from handle and generates a NeXus file in h5handle. This will attempt to extract metadata and image data from each scan (or the named scan) within each datablock (or the the named datablock) and insert it into a given index into the NXentry group specified in h5handle.

Each scan in the CBF file corresponds to one NXentry in NeXus, so a CBF datablock with multiple scans must be converted by calling this function with the appropriate value of scan once for each scan in the datablock.

The flags (within h5handle) determine:

Compression algorithm: zlib/CBF/none
Plugin registration method: automatic/manual

The strings given by h5handle->scan_id and h5handle->sample_id define:

The presence and value of an identifier for the scan, stored in /*:NXentry/entry_identifier.
The presence and value of an identifier for the sample, stored in /*:NXentry/*:NXsample/sample_identifier.

ARGUMENTS

handle	The CBF file to extract data from.
h5handle	The NeXuS file to write data to.
datablock	The name of the datablock to convert, or NULL to convert all datablocks.
scan	The name of the scan to convert, or NULL if there is only one scan in the datablock.
list	Boolean flag to determine if a list of processed items is printed.

RETURN VALUE

An error code.

SEE ALSO

2.7.32 cbf_write_cbf_h5file
2.7.34 cbf_write_minicbf_h5file
2.7.35 cbf_write_nx2cbf

2.7.34 cbf_write_minicbf_h5file

Extract the data from a miniCBF file & put it into a NeXus file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_write_minicbf_h5file (cbf_handle handle, cbf_h5handle h5handle, const cbf_config_t *const axisConfig)

DESCRIPTION

Extracts the miniCBF data directly - by parsing the header - and uses that plus the configuration options from axisConfig to generate a NeXus file in h5handle. This can extract metadata and image data from miniCBF files containing multiple datablocks which each contain a single image and insert it into a given index into the NXentry group specified in h5handle.

Currently, only Pilatus 1.2 format headers are supported.

The flags determine:

Compression algorithm: zlib/CBF/none
Plugin registration method: automatic/manual

ARGUMENTS

handle	The miniCBF file to extract data from.
h5handle	The NeXus file to write data to.
axisConfig	The configuration settings desribing the axes and their relation to the sample and to each other.

RETURN VALUE

An error code.

SEE ALSO

2.7.32 cbf_write_cbf_h5file
2.7.35 cbf_write_nx2cbf

2.7.35 cbf_write_nx2cbf

Extract data from a nexus file and store it in a CBF file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_write_nx2cbf (cbf_h5handle nx, cbf_handle cbf)

DESCRIPTION

Reads NeXus-format data from the entry group defined in the nx handle, extracting data related to the frame with index nx->slice and in CBF-format within the the cbf handle.

ARGUMENTS

nx	The handle defining the NeXus data to be converted.
cbf	The handle in which to store the resulting CBF data.

RETURN VALUE

An error code.

SEE ALSO

2.7.32 cbf_write_cbf_h5file
2.7.34 cbf_write_minicbf_h5file

2.7.36 cbf_config_create

Obtain a new handle for some configuration settings.

PROTOTYPE

#include "cbf_hdf5.h"
cbf_config_t* cbf_config_create ()

DESCRIPTION

Allocates a new collection of configuration settings on the heap, and initialises it. The returned pointer should be destroyed by the caller.

ARGUMENTS

This function takes no arguments.

RETURN VALUE

A newly allocated object for miniCBF configuration settings, or NULL.

2.7.37 cbf_config_parse

Read a minicbf configuration file into the given handle, writing errors to logfile.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_config_parse (FILE *const configFile, FILE *const logFile, cbf_config_t *const vec)

DESCRIPTION

Parses a configuration file to extract a collection of configuration settings for a miniCBF file, storing them in the given configuration settings object. The pointer should have been obtained by a call to cbf_config_create. The configuration file format is described in the minicbf2nexus documentation.

ARGUMENTS

configFile	The file from which the config settings should be read.
logFile	A stream to be used for logging error messages.
vec	An object describing the configuration settings.

RETURN VALUE

A parser error code.

2.7.38 cbf_config_free

Free any heap memory associated with the given cbf_hdf5_configItemVectorhandle object.

PROTOTYPE

#include "cbf_hdf5.h"
void cbf_config_free (const cbf_config_t *const vector)

DESCRIPTION

Destroys an existing collection of configuration settings. The settings should have been obtained by a call to cbf_config_create.

ARGUMENTS

vector

The configuration data to be free'd.

RETURN VALUE

Nothing.

2.7.39 cbf_config_strerror

Convert a parse error to a descriptive string.

PROTOTYPE

#include "cbf_hdf5.h"
const char* cbf_config_strerror (const int error)

DESCRIPTION

The returned string is "none" for success, "unknown error" if the given error code is not recognised and a non-empty string briefly describing the error otherwise.

The returned string must not be free'd.

ARGUMENTS

error

An error returned by a cbf_config_* function.

RETURN VALUE

A string describing the error.

CBF_FORMAT	The file format is invalid
CBF_ALLOC	Memory allocation failed
CBF_ARGUMENT	Invalid function argument
CBF_ASCII	The value is ASCII (not binary)
CBF_BINARY	The value is binary (not ASCII)
CBF_BITCOUNT	The expected number of bits does not match the actual number written
CBF_ENDOFDATA	The end of the data was reached before the end of the array
CBF_FILECLOSE	File close error
CBF_FILEOPEN	File open error
CBF_FILEREAD	File read error
CBF_FILESEEK	File seek error
CBF_FILETELL	File tell error
CBF_FILEWRITE	File write error
CBF_IDENTICAL	A data block with the new name already exists
CBF_NOTFOUND	The data block, category, column or row does not exist
CBF_OVERFLOW	The number read cannot fit into the destination argument. The destination has been set to the nearest value.
CBF_UNDEFINED	The requested number is not defined (e.g. 0/0; new for version 0.7).
CBF_NOTIMPLEMENTED	The requested functionality is not yet implemented (New for version 0.7).

MSG_DIGEST:	Instructs CBFlib to check that the digest of the binary section matches any header digest value. If the digests do not match, the call will return CBF_FORMAT. This evaluation and comparison is delayed (a "lazy" evaluation) to ensure maximal processing efficiency. If an immediately evaluation is required, see MSG_DIGESTNOW, below.
MSG_DIGESTNOW:	Instructs CBFlib to check that the digest of the binary section matches any header digeste value. If the digests do not match, the call will return CBF_FORMAT. This evaluation and comparison is performed during initial parsing of the section to ensure timely error reporting at the expense of processing efficiency. If a more efficient delayed ("lazy") evaluation is required, see MSG_DIGEST, above.
MSG_DIGESTWARN:	Instructs CBFlib to check that the digest of the binary section matches any header digeste value. If the digests do not match, a warning message will be sent to stderr, but processing will attempt to continue. This evaluation and comparison is first performed during initial parsing of the section to ensure timely error reporting at the expense of processing efficiency. An mismatch of the message digest usually indicates a serious error, but it is sometimes worth continuing processing to try to isolate the cause of the error. Use this option with caution.
MSG_NODIGEST:	Do not check the digest (default).
PARSE_BRACKETS:	Accept DDLm bracket-delimited [item,item,...item] or {item,item,...item} or (item,item,...item) constructs as valid, stripping non-quoted embedded whitespace and comments. These constructs may span multiple lines.
PARSE_LIBERAL_BRACKETS:	Accept DDLm bracket-delimited [item,item,...item] or {item,item,...item} or (item,item,...item) constructs as valid, stripping embedded non-quoted, non-separating whitespace and comments. These constructs may span multiple lines. In this case, whitespace may be used as an alternative to the comma.
PARSE_TRIPLE_QUOTES:	Accept DDLm triple-quoted """item,item,...item""" or '''item,item,...item''' constructs as valid, stripping embedded whitespace and comments. These constructs may span multiple lines. If this flag is set, then ''' will not be interpreted as a quoted apoptrophe and """ will not be interpreted as a quoted double quote mark and
PARSE_NOBRACKETS:	Do not accept DDLm bracket-delimited [item,item,...item] or {item,item,...item} or (item,item,...item) constructs as valid, stripping non-quoted embedded whitespace and comments. These constructs may span multiple lines.
PARSE_NOTRIPLE_QUOTES:	No not accept DDLm triple-quoted """item,item,...item""" or '''item,item,...item''' constructs as valid, stripping embedded whitespace and comments. These constructs may span multiple lines. If this flag is set, then ''' will be interpreted as a quoted apostrophe and """ will be interpreted as a quoted double quote mark.

handle	CBF handle.
file	Pointer to a file descriptor.
headers	Controls interprestation of binary section headers.

MIME_HEADERS	Use MIME-type headers (default).
MIME_NOHEADERS	Use a simple ASCII headers.
MSG_DIGEST	Generate message digests for binary data validation.
MSG_NODIGEST	Do not generate message digests (default).
PARSE_BRACKETS	Do not convert bracketed strings to text fields (default).
PARSE_LIBERAL_BRACKETS	Do not convert bracketed strings to text fields (default).
PARSE_NOBRACKETS	Convert bracketed strings to text fields (default).
PARSE_TRIPLE_QUOTES	Do not convert triple-quoted strings to text fields (default).
PARSE_NOTRIPLE_QUOTES	Convert triple-quoted strings to text fields (default).
PAD_1K	Pad binary sections with 1023 nulls.
PAD_2K	Pad binary sections with 2047 nulls.
PAD_4K	Pad binary sections with 4095 nulls.

ENC_BASE64	Use BASE64 encoding (default).
ENC_QP	Use QUOTED-PRINTABLE encoding.
ENC_BASE8	Use BASE8 (octal) encoding.
ENC_BASE10	Use BASE10 (decimal) encoding.
ENC_BASE16	Use BASE16 (hexadecimal) encoding.
ENC_FORWARD	For BASE8, BASE10 or BASE16 encoding, map bytes to words forward (1234) (default on little-endian machines).
ENC_BACKWARD	Map bytes to words backward (4321) (default on big-endian machines).
ENC_CRTERM	Terminate lines with CR.
ENC_LFTERM	Terminate lines with LF (default).

handle	CBF handle.
datablockname	The name of the new data block.
saveframename	The name of the new save frame.

handle	CBF handle.
categoryname	The name of the new category.

handle	CBF handle.
rownumber	The row number of the new row.

handle	CBF handle.
datablocks	Pointer to the destination data block count.

handle	CBF handle.
categories	Pointer to the destination category count.

handle	CBF handle.
columns	Pointer to the destination column count.

handle	CBF handle.
rows	Pointer to the destination row count.

handle	CBF handle.
datablock	Number of the data block to select.

handle	CBF handle.
category	Number of the category to select.

handle	CBF handle.
columnname	Pointer to the destination column name pointer.
newcolumnname	New column name pointer.

handle	CBF handle.
row	Pointer to the destination row number.

handle	CBF handle.
value	Pointer to the destination value pointer.
defaultvalue	Default value character string.

"null"	for a null value indicated by a "." or a "?"
"bnry"	for a binary value
"word"	for an unquoted string
"dblq"	for a double-quoted string
"sglq"	for a single-quoted string
"text"	for a semicolon-quoted string (multiline text field)
"prns"	for a parenthesis-bracketed string (multiline text field)
"brcs"	for a brace-bracketed string (multiline text field)
"bkts"	for a square-bracket-bracketed string (multiline text field)
"tsqs"	for a treble-single-quote quoted string (multiline text field)
"tdqs"	for a treble-double-quote quoted string (multiline text field)

handle	CBF handle.
typeofvalue	Pointer to the destination type-of-value string pointer.

handle	CBF handle.
number	pointer to the number.
defaultvalue	default number value.

handle	CBF handle.
format	Format for the number.
number	Floating-point value.

handle	CBF handle.
compression	Compression method used.
elsize	Size in bytes of each array element.
binary_id	Pointer to the destination integer binary identifier.
elsigned	Pointer to an integer. Set to 1 if the elements can be read as signed integers.
elunsigned	Pointer to an integer. Set to 1 if the elements can be read as unsigned integers.
elements	Pointer to the destination number of elements.
minelement	Pointer to the destination smallest element.
maxelement	Pointer to the destination largest element.
byteorder	Pointer to the destination byte order.
dimfast	Pointer to the destination fastest dimension.
dimmid	Pointer to the destination second fastest dimension.
dimslow	Pointer to the destination third fastest dimension.
padding	Pointer to the destination padding size.

CBF_CANONICAL	Canonical-code compression (section 3.3.1)
CBF_PACKED	CCP4-style packing (section 3.3.2)
CBF_PACKED_V2	CCP4-style packing, version 2 (section 3.3.2)
CBF_BYTE_OFFSET	Simple "byte_offset" compression.
CBF_NIBBLE_OFFSET	Simple "nibble_offset" compression.
CBF_NONE	No compression. NOTE: This scheme is by far the slowest of the four and uses much more disk space. It is intended for routine use with small arrays only. With large arrays (like images) it should be used only for debugging.

f	integer function to execute.
c	statement to execute on failure.

byte_order	pointer to the returned string
real_format	pointer to the returned string

CBFlib

Before using this software, please read the for important disclaimers and the IUCr Policy on the Use of the Crystallographic Information File (CIF) and for other important information.

Version History

Known Problems

Foreword

Contents

2.4.27 cbf_set_image, cbf_set_image_fs, cbf_set_image_sf, cbf_set_real_image, cbf_set_real_image_fs, cbf_set_real_image_sf, cbf_set_3d_image, cbf_set_3d_image, cbf_set_3d_image, cbf_set_real_3d_image, cbf_set_real_3d_image_fs, cbf_set_real_3d_image_sf

Before using this software, please read the

for important disclaimers and the IUCr Policy on the Use of the Crystallographic Information File (CIF) and for other important information.

2.4.27 cbf_set_image, cbf_set_image_fs, cbf_set_image_sf,
cbf_set_real_image, cbf_set_real_image_fs, cbf_set_real_image_sf,
cbf_set_3d_image, cbf_set_3d_image, cbf_set_3d_image,
cbf_set_real_3d_image, cbf_set_real_3d_image_fs, cbf_set_real_3d_image_sf

handle	CBF handle.
dictionary	Pointer to CBF handle of dictionary.
dictionary_in	CBF handle of dcitionary.

handle	CBF handle.
tagname	tag name which may be an alias.
tagroot	pointer to a returned tag root name.
tagroot_in	input tag root name.

handle	Pointer to a CBF handle.
file	Pointer to a file descriptor.

handle	CBF handle.
diffrn_id	Pointer to the destination value pointer.
default_id	Character string default value.

handle	CBF handle.
crystal_id	Pointer to the destination value pointer.

handle	CBF handle.
polarizn_source_ratio	Pointer to the destination polarizn_source_ratio.
polarizn_source_norm	Pointer to the destination polarizn_source_norm.

handle	CBF handle.
div_x_source	Pointer to the destination div_x_source.
div_y_source	Pointer to the destination div_y_source.
div_x_y_source	Pointer to the destination div_x_y_source.

handle	CBF handle.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
element_id	Pointer to the destination.

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
time	Pointer to the destination time.

handle	CBF handle.
goniometer	Pointer to the destination goniometer handle.