NeXusDataFormat  1
NeXusCAPI
 All Functions Groups
Functions
Reading and Writing Data
C API

Functions

NXstatus NXflush (NXhandle *pHandle)
 flush data to disk
NXstatus NXmakedata (NXhandle handle, CONSTCHAR *label, int datatype, int rank, int dim[])
 Create a multi dimensional data array or dataset.
NXstatus NXcompmakedata (NXhandle handle, CONSTCHAR *label, int datatype, int rank, int dim[], int comp_typ, int bufsize[])
 Create a compressed dataset.
NXstatus NXcompress (NXhandle handle, int compr_type)
 Switch compression on.
NXstatus NXopendata (NXhandle handle, CONSTCHAR *label)
 Open access to a dataset.
NXstatus NXclosedata (NXhandle handle)
 Close access to a dataset.
NXstatus NXputdata (NXhandle handle, const void *data)
 Write data to a datset which has previouly been opened with NXopendata.
NXstatus NXputattr (NXhandle handle, CONSTCHAR *name, const void *data, int iDataLen, int iType)
 Write an attribute.
NXstatus NXputslab (NXhandle handle, const void *data, const int start[], const int size[])
 Write a subset of a multi dimensional dataset.
NXstatus NXgetdata (NXhandle handle, void *data)
 Read a complete dataset from the currently open dataset into memory.
NXstatus NXgetslab (NXhandle handle, void *data, const int start[], const int size[])
 Read a subset of data from file into memory.
NXstatus NXgetnextattr (NXhandle handle, NXname pName, int *iLength, int *iType)
 Iterate over global, group or dataset attributes depending on the currently open group or dataset.
NXstatus NXgetattr (NXhandle handle, char *name, void *data, int *iDataLen, int *iType)
 Read an attribute.
NXstatus NXsetnumberformat (NXhandle handle, int type, char *format)
 Sets the format for number printing.

Detailed Description


Function Documentation

NXstatus NXclosedata ( NXhandle  handle)

Close access to a dataset.

Parameters:
handleA NeXus file handle as initialized by NXopen.
Returns:
NX_OK on success, NX_ERROR in the case of an error.
NXstatus NXcompmakedata ( NXhandle  handle,
CONSTCHAR *  label,
int  datatype,
int  rank,
int  dim[],
int  comp_typ,
int  bufsize[] 
)

Create a compressed dataset.

The dataset is NOT opened. Data from this set will automatically be compressed when writing and decompressed on reading.

Parameters:
handleA NeXus file handle as initialized by NXopen.
labelThe name of the dataset
datatypeThe data type of this data set.
rankThe number of dimensions this dataset is going to have
comp_typThe compression scheme to use. Possible values:
  • NX_COMP_NONE no compression
  • NX_COMP_LZW lossless Lempel Ziv Welch compression (recommended)
  • NX_COMP_RLE run length encoding (only HDF-4)
  • NX_COMP_HUF Huffmann encoding (only HDF-4)
dimAn array of size rank holding the size of the dataset in each dimension. The first dimension can be NX_UNLIMITED. Data can be appended to such a dimension using NXputslab.
bufsizeThe dimensions of the subset of the data which usually be writen in one go. This is a parameter used by HDF for performance optimisations. If you write your data in one go, this should be the same as the data dimension. If you write it in slabs, this is your preferred slab size.
Returns:
NX_OK on success, NX_ERROR in the case of an error.
NXstatus NXcompress ( NXhandle  handle,
int  compr_type 
)

Switch compression on.

This routine is superseeded by NXcompmakedata and thus is deprecated.

Parameters:
handleA NeXus file handle as initialized by NXopen.
compr_typeThe compression scheme to use. Possible values:
  • NX_COMP_NONE no compression
  • NX_COMP_LZW lossless Lempel Ziv Welch compression (recommended)
  • NX_COMP_RLE run length encoding (only HDF-4)
  • NX_COMP_HUF Huffmann encoding (only HDF-4)
NXstatus NXflush ( NXhandle *  pHandle)

flush data to disk

Parameters:
pHandleA NeXus file handle as initialized by NXopen.
Returns:
NX_OK on success, NX_ERROR in the case of an error.
NXstatus NXgetattr ( NXhandle  handle,
char *  name,
void *  data,
int *  iDataLen,
int *  iType 
)

Read an attribute.

Parameters:
handleA NeXus file handle as initialized by NXopen.
nameThe name of the atrribute to read.
dataA pointer to a memory area large enough to hold the attributes value.
iDataLenThe length of data in bytes.
iTypeA pointer to an integer which will had been set to the NeXus data type of the attribute.
Returns:
NX_OK on success, NX_ERROR in the case of an error.
NXstatus NXgetdata ( NXhandle  handle,
void *  data 
)

Read a complete dataset from the currently open dataset into memory.

Parameters:
handleA NeXus file handle as initialized by NXopen.
dataA pointer to the memory area where to read the data, too. Data must point to a memory area large enough to accomodate the data read. Otherwise your program may behave in unexpected and unwelcome ways.
Returns:
NX_OK on success, NX_ERROR in the case of an error.
NXstatus NXgetnextattr ( NXhandle  handle,
NXname  pName,
int *  iLength,
int *  iType 
)

Iterate over global, group or dataset attributes depending on the currently open group or dataset.

In order to search attributes multiple calls to NXgetnextattr are performed in a loop until NXgetnextattr returns NX_EOD which indicates that there are no further attributes. reset search using NXinitattrdir

Parameters:
handleA NeXus file handle as initialized by NXopen.
pNameThe name of the attribute
iLengthA pointer to an integer which be set to the length of the attribute data.
iTypeA pointer to an integer which be set to the NeXus data type of the attribute.
Returns:
NX_OK on success, NX_ERROR in the case of an error, NX_EOD when there are no more items.
NXstatus NXgetslab ( NXhandle  handle,
void *  data,
const int  start[],
const int  size[] 
)

Read a subset of data from file into memory.

Parameters:
handleA NeXus file handle as initialized by NXopen.
dataA pointer to the memory data where to copy the data too. The pointer must point to a memory area large enough to accomodate the size of the data read.
startAn array holding the start indices where to start reading the data subset.
sizeAn array holding the size of the data subset to read for each dimension.
Returns:
NX_OK on success, NX_ERROR in the case of an error.
NXstatus NXmakedata ( NXhandle  handle,
CONSTCHAR *  label,
int  datatype,
int  rank,
int  dim[] 
)

Create a multi dimensional data array or dataset.

The dataset is NOT opened.

Parameters:
handleA NeXus file handle as initialized by NXopen.
labelThe name of the dataset
datatypeThe data type of this data set.
rankThe number of dimensions this dataset is going to have
dimAn array of size rank holding the size of the dataset in each dimension. The first dimension can be NX_UNLIMITED. Data can be appended to such a dimension using NXputslab.
Returns:
NX_OK on success, NX_ERROR in the case of an error.
NXstatus NXopendata ( NXhandle  handle,
CONSTCHAR *  label 
)

Open access to a dataset.

After this call it is possible to write and read data or attributes to and from the dataset.

Parameters:
handleA NeXus file handle as initialized by NXopen.
labelThe name of the dataset
Returns:
NX_OK on success, NX_ERROR in the case of an error.
NXstatus NXputattr ( NXhandle  handle,
CONSTCHAR *  name,
const void *  data,
int  iDataLen,
int  iType 
)

Write an attribute.

The kind of attribute written depends on the poistion in the file: at root level, a global attribute is written, if agroup is open but no dataset, a group attribute is written, if a dataset is open, a dataset attribute is written.

Parameters:
handleA NeXus file handle as initialized by NXopen.
nameThe name of the attribute.
dataA pointer to the data to write for the attribute.
iDataLenThe length of the data in data in bytes.
iTypeThe NeXus data type of the attribute.
Returns:
NX_OK on success, NX_ERROR in the case of an error.
NXstatus NXputdata ( NXhandle  handle,
const void *  data 
)

Write data to a datset which has previouly been opened with NXopendata.

This writes all the data in one go. Data should be a pointer to a memory area matching the datatype and dimensions of the dataset.

Parameters:
handleA NeXus file handle as initialized by NXopen.
dataPointer to data to write.
Returns:
NX_OK on success, NX_ERROR in the case of an error.
NXstatus NXputslab ( NXhandle  handle,
const void *  data,
const int  start[],
const int  size[] 
)

Write a subset of a multi dimensional dataset.

Parameters:
handleA NeXus file handle as initialized by NXopen.
dataA pointer to a memory area holding the data to write.
startAn array holding the start indices where to start the data subset.
sizeAn array holding the size of the data subset to write in each dimension.
Returns:
NX_OK on success, NX_ERROR in the case of an error.
NXstatus NXsetnumberformat ( NXhandle  handle,
int  type,
char *  format 
)

Sets the format for number printing.

This call has only an effect when using the XML physical file format.

Parameters:
handleA NeXus file handle as initialized by NXopen.
typeThe NeXus data type to set the format for.
formatThe C-language format string to use for this data type.
Returns:
NX_OK on success, NX_ERROR in the case of an error.