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

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).

Known Problems

This version does not have support for byte-offset or predictor compression. Code is needed to support array sub-sections.

Foreword

In order to work with CBFlib, you need the source code, in the form of a "gzipped" tar, CBFlib.tar.gz. Uncompress this file. Place it in an otherwise empty directory, and unpack it with tar. You will also need Paul Ellis's sample MAR345 image, example.mar2300, as sample data. This file can also be found at http://biosg1.slac.stanford.edu/biosg1-users/ellis/Public/. Place that file in the top level directory (one level up from the source code). Adjust the definition of CC in Makefile to point to your C compiler, and then

make all
make tests

This release has been tested on an SGI under IRIX 6.4 and on a PowerPC under Linux-ppc 2.1.24.

We have included examples of CBF/imgCIF files produced by CBFlib, an updated version of John Westbrook's DDL2-compliant CBF Extensions Dictionary, and of Andy Hammersley's CBF definition, updated to become a DRAFT CBF/ImgCIF DEFINITION.

This is just a proposal. Please be careful about basing any code on this until and unless there has been a general agreement.

Contents

• 1. Introduction
• 2. Function descriptions
  • 2.1 General description
    • 2.1.1 CBF handles
    • 2.1.2 CBF goniometer handles
    • 2.1.3 CBF detector handles
    • 2.1.4 Return values
  • 2.2 Reading and writing files containing binary sections
    • 2.2.1 Reading binary sections
    • 2.2.2 Writing binary sections
    • 2.2.3 Summary of reading and writing files containing binary sections
  • 2.3 Low-level function prototypes
    • 2.3.1 cbf_make_handle
    • 2.3.2 cbf_free_handle
    • 2.3.3 cbf_read_file
    • 2.3.4 cbf_write_file
    • 2.3.5 cbf_new_datablock
    • 2.3.6 cbf_force_new_datablock
    • 2.3.7 cbf_new_category
    • 2.3.8 cbf_force_new_category
    • 2.3.9 cbf_new_column
    • 2.3.10 cbf_new_row
    • 2.3.11 cbf_insert_row
    • 2.3.12 cbf_delete_row
    • 2.3.13 cbf_set_datablockname
    • 2.3.14 cbf_reset_datablocks
    • 2.3.15 cbf_reset_datablock
    • 2.3.16 cbf_reset_category
    • 2.3.17 cbf_remove_datablock
    • 2.3.18 cbf_remove_category
    • 2.3.19 cbf_remove_column
    • 2.3.20 cbf_remove_row
    • 2.3.21 cbf_rewind_datablock
    • 2.3.22 cbf_rewind_category
    • 2.3.23 cbf_rewind_column
    • 2.3.24 cbf_rewind_row
    • 2.3.25 cbf_next_datablock
    • 2.3.26 cbf_next_category
    • 2.3.27 cbf_next_column
    • 2.3.28 cbf_next_row
    • 2.3.29 cbf_find_datablock
    • 2.3.30 cbf_find_category
    • 2.3.31 cbf_find_column
    • 2.3.32 cbf_find_row
    • 2.3.33 cbf_find_nextrow
    • 2.3.34 cbf_count_datablocks
    • 2.3.35 cbf_count_categories
    • 2.3.36 cbf_count_columns
    • 2.3.37 cbf_count_rows
    • 2.3.38 cbf_select_datablock
    • 2.3.39 cbf_select_category
    • 2.3.40 cbf_select_column
    • 2.3.41 cbf_select_row
    • 2.3.42 cbf_datablock_name
    • 2.3.43 cbf_category_name
    • 2.3.44 cbf_column_name
    • 2.3.45 cbf_row_number
    • 2.3.46 cbf_get_value
    • 2.3.47 cbf_set_value
    • 2.3.48 cbf_get_integervalue
    • 2.3.49 cbf_set_integervalue
    • 2.3.50 cbf_get_doublevalue
    • 2.3.51 cbf_set_doublevalue
    • 2.3.52 cbf_get_integerarrayparameters
    • 2.3.53 cbf_get_integerarray
    • 2.3.54 cbf_set_integerarray
    • 2.3.55 cbf_failnez
    • 2.3.56 cbf_onfailnez
  • 2.4 High-level function prototypes (new for version 0.7)
    • 2.4.1 cbf_read_template
    • 2.4.2 cbf_get_diffrn_id
    • 2.4.3 cbf_set_diffrn_id
    • 2.4.4 cbf_get_crystal_id
    • 2.4.5 cbf_set_crystal_id
    • 2.4.6 cbf_get_wavelength
    • 2.4.7 cbf_set_wavelength
    • 2.4.8 cbf_get_polarization
    • 2.4.9 cbf_set_polarization
    • 2.4.10 cbf_get_divergence
    • 2.4.11 cbf_set_divergence
    • 2.4.12 cbf_count_elements
    • 2.4.13 cbf_get_element_id
    • 2.4.14 cbf_get_gain
    • 2.4.15 cbf_set_gain
    • 2.4.16 cbf_get_overload
    • 2.4.17 cbf_set_overload
    • 2.4.18 cbf_get_integration_time
    • 2.4.19 cbf_set_integration_time
    • 2.4.20 cbf_get_time
    • 2.4.21 cbf_set_time
    • 2.4.22 cbf_get_date
    • 2.4.23 cbf_set_date
    • 2.4.24 cbf_set_current_time
    • 2.4.25 cbf_get_image_size
    • 2.4.26 cbf_get_image
    • 2.4.27 cbf_set_image
    • 2.4.28 cbf_get_axis_setting
    • 2.4.29 cbf_set_axis_setting
    • 2.4.30 cbf_construct_goniometer
    • 2.4.31 cbf_free_goniometer
    • 2.4.32 cbf_get_rotation_axis
    • 2.4.33 cbf_get_rotation_range
    • 2.4.34 cbf_rotate_vector
    • 2.4.35 cbf_get_reciprocal
    • 2.4.36 cbf_construct_detector
    • 2.4.37 cbf_free_detector
    • 2.4.38 cbf_get_beam_center
    • 2.4.39 cbf_get_detector_distance
    • 2.4.40 cbf_get_detector_normal
    • 2.4.41 cbf_get_pixel_coordinates
    • 2.4.42 cbf_get_pixel_normal
    • 2.4.43 cbf_get_pixel_area
• 3. File format
  • 3.1 General description
  • 3.2 Format of the binary sections
    • 3.2.1 Format of imgCIF binary sections
    • 3.2.2 Format of CBF binary sections
  • 3.3 Compression schemes
    • 3.3.1 Canonical-code compression
    • 3.3.2 CCP4-style compression
• 4. Installation
• 5. Example programs

1. Introduction

CBFlib is a library of ANSI-C functions providing a simple mechanism for accessing Crystallographic Binary Files (CBF files) and Image-supporting CIF (imgCIF) files. The CBFlib API is loosely based on the CIFPARSE API for mmCIF files. Like CIFPARSE, CBFlib does not perform any semantic integrity checks; rather it simply provides functions to create, read, modify and write CBF binary data files and imgCIF ASCII data files.

2. Function descriptions

2.1 General description

Almost all of the CBFlib functions receive a value of type cbf_handle (a CBF handle) as the first argument. Several of the high-level CBFlib functions dealing with geometry receive a value of type cbf_goniometer (a handle for a CBF goniometer object) or cbf_detector (a handle for a CBF detector object).

All functions return an integer equal to 0 for success or an error code for failure.

2.1.1 CBF handles

CBFlib permits a program to use multiple CBF objects simultaneously. To identify the CBF object on which a function will operate, CBFlib uses a value of type cbf_handle.

All functions in the library except cbf_make_handle expect a value of type cbf_handle as the first argument.

The function cbf_make_handle creates and initializes a new CBF handle.

The function cbf_free_handle destroys a handle and frees all memory associated with the corresponding CBF object.

2.1.2 CBF goniometer handles

To represent the goniometer used to orient a sample, CBFlib uses a value of type cbf_goniometer.

A goniometer object is created and initialized from a CBF object using the function cbf_construct_goniometer.

The function cbf_free_goniometer destroys a goniometer handle and frees all memory associated with the corresponding object.

2.1.3 CBF detector handles

To represent a detector surface mounted on a positioning system, CBFlib uses a value of type cbf_detector.

A goniometer object is created and initialized from a CBF object using the function cbf_construct_detector.

The function cbf_free_detector destroys a detector handle and frees all memory associated with the corresponding object.

2.1.4 Return values

If more than one error has occurred, the error code is the logical OR of the individual error codes.

2.2 Reading and writing files containing binary sections

2.2.1 Reading binary sections

The current version of CBFlib only decompresses a binary section from disk when requested by the program.

When a file containing one or more binary sections is read, CBFlib saves the file pointer and the position of the binary section within the file and then jumps past the binary section. When the program attempts to access the binary data, CBFlib sets the file position back to the start of the binary section and then reads the data.

For this scheme to work:

1. The file must be a random-access file opened in binary mode (fopen ( ," rb")).
2. The program must not close the file. CBFlib will close the file using fclose ( ) when it is no longer needed.

At present, this also means that a program cant read a file and then write back to the same file. This restriction will be eliminated in a future version.

When reading an imgCIF vs a CBF, the difference is detected automatically.

2.2.2 Writing binary sections

When a program passes CBFlib a binary value, the data is compressed to a temporary file. If the CBF object is subsequently written to a file, the data is simply copied from the temporary file to the output file.

The output file can be of any type. If the program indicates to CBFlib that the file is a random-access and readable, CBFlib will conserve disk space by closing the temporary file and using the output file as the location at which the binary value is stored.

For this option to work:

1. The file must be a random-access file opened in binary update mode (fopen ( , "w+b")).
2. The program must not close the file. CBFlib will close the file using fclose ( ) when it is no longer needed.

If this option is not used:

1. CBFlib will continue using the temporary file.
2. CBFlib will not close the file. This is the responsibility of the main program.

2.2.3 Summary of reading and writing files containing binary sections

1. Open disk files to read using the mode "rb".
2. If possible, open disk files to write using the mode "w+b" and tell CBFlib that it can use the file as a buffer.
3. Do not close any files read by CBFlib or written by CBFlib with buffering turned on.
4. Do not attempt to read from a file, then write to the same file.

2.3 Low-level function prototypes

2.3.1 cbf_make_handle

PROTOTYPE

#include "cbf.h"

int cbf_make_handle (cbf_handle *handle);

DESCRIPTION

cbf_make_handle creates and initializes a new internal CBF object. All other CBFlib functions operating on this object receive the CBF handle as the first argument.

ARGUMENTS

handle

Pointer to a CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.2 cbf_free_handle

2.3.2 cbf_free_handle

PROTOTYPE

#include "cbf.h"

int cbf_free_handle (cbf_handle handle);

DESCRIPTION

cbf_free_handle destroys the CBF object specified by the handle and frees all associated memory.

ARGUMENTS

handle

CBF handle to free.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.1 cbf_make_handle

2.3.3 cbf_read_file

PROTOTYPE

#include "cbf.h"

int cbf_read_file (cbf_handle handle, FILE *file, int headers);

DESCRIPTION

cbf_read_file reads the CBF or CIF file file into the CBF object specified by handle.

headers controls the interprestation of binary section headers of imgCIF files.

MSG_DIGEST:	Instructs CBFlib to check that the digest of the binary section matches any header 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 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_DIGESTNOW, below.
MSG_NODIGEST:	Do not check the digest (default).

CBFlib defers reading binary sections as long as possible. In the current version of CBFlib, this means that:

1. The file must be a random-access file opened in binary mode (fopen ( , "rb")).
2. The program must not close the file. CBFlib will close the file using fclose ( ) when it is no longer needed.

These restrictions may change in a future release.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.4 cbf_write_file

2.3.4 cbf_write_file

PROTOTYPE

#include "cbf.h"

int cbf_write_file (cbf_handle handle, FILE *file, int readable, int ciforcbf, int headers, int encoding);

DESCRIPTION

cbf_write_file writes the CBF object specified by handle into the file file.

Unlike cbf_read_file, the file does not have to be random-access.

If the file is random-access and readable, readable can be set to non-0 to indicate to CBFlib that the file can be used as a buffer to conserve disk space. If the file is not random-access or not readable, readable must be 0.

If readable is non-0, CBFlib will close the file when it is no longer required, otherwise this is the responsibility of the program.

ciforcbf selects the format in which the binary sections are written:

CIF	Write an imgCIF file.
CBF	Write a CBF file (default).

headers selects the type of header used in CBF binary sections and selects whether message digests are generated. The value of headers can be a logical OR of any of:

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).

encoding selects the type of encoding used for binary sections and the type of line-termination in imgCIF files. The value can be a logical OR of any of:

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).

ARGUMENTS

handle	CBF handle.
file	Pointer to a file descriptor.
readable	If non-0: this file is random-access and readable and can be used as a buffer.
ciforcbf	Selects the format in which the binary sections are written (CIF/CBF).
headers	Selects the type of header in CBF binary sections and message digest generation.
encoding	Selects the type of encoding used for binary sections and the type of line-termination in imgCIF files.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.3 cbf_read_file

2.3.5 cbf_new_datablock

PROTOTYPE

#include "cbf.h"

int cbf_new_datablock (cbf_handle handle, const char *datablockname);

DESCRIPTION

cbf_new_datablock creates a new data block with name datablockname and makes it the current data block.

If a data block with this name already exists, the existing data block becomes the current data block.

ARGUMENTS

handle	CBF handle.
datablockname	The name of the new data block.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.6 cbf_force_new_datablock
2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.9 cbf_new_column
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.12 cbf_set_datablockname
2.3.17 cbf_remove_datablock

2.3.6 cbf_force_new_data_block

PROTOTYPE

#include "cbf.h"

int cbf_force_new_datablock (cbf_handle handle, const char *datablockname);

DESCRIPTION

cbf_force_new_datablock creates a new data block with name datablockname and makes it the current data block. Duplicate data block names are allowed.

Even if a data block with this name already exists, a new data block is created and becomes the current data block.

ARGUMENTS

handle	CBF handle.
datablockname	The name of the new data block.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.5 cbf_new_datablock
2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.9 cbf_new_column
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.12 cbf_set_datablockname
2.3.17 cbf_remove_datablock

2.3.7 cbf_new_category

PROTOTYPE

#include "cbf.h"

int cbf_new_category (cbf_handle handle, const char *categoryname);

DESCRIPTION

cbf_new_category creates a new category in the current data block with name categoryname and makes it the current category.

If a category with this name already exists, the existing category becomes the current category.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.5 cbf_new_datablock
2.3.6 cbf_force_new_datablock
2.3.8 cbf_force_new_category
2.3.9 cbf_new_column
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.18 cbf_remove_category

2.3.8 cbf_force_new_category

PROTOTYPE

#include "cbf.h"

int cbf_force_new_category (cbf_handle handle, const char *categoryname);

DESCRIPTION

cbf_force_new_category creates a new category in the current data block with name categoryname and makes it the current category. Duplicate category names are allowed.

Even if a category with this name already exists, a new category of the same name is created and becomes the current category. The allows for the creation of unlooped tag/value lists drawn from the same category.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.5 cbf_new_datablock
2.3.6 cbf_force_new_datablock
2.3.7 cbf_new_category
2.3.9 cbf_new_column
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.18 cbf_remove_category

2.3.9 cbf_new_column

PROTOTYPE

#include "cbf.h"

int cbf_new_column (cbf_handle handle, const char *columnname);

DESCRIPTION

cbf_new_column creates a new column in the current category with name columnname and makes it the current column.

If a column with this name already exists, the existing column becomes the current category.

ARGUMENTS

handle	CBF handle.
columnname	The name of the new column.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.5 cbf_new_datablock
2.3.6 cbf_force_new_datablock
2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.19 cbf_remove_column

2.3.10 cbf_new_row

PROTOTYPE

#include "cbf.h"

int cbf_new_row (cbf_handle handle);

DESCRIPTION

cbf_new_row adds a new row to the current category and makes it the current row.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.5 cbf_new_datablock
2.3.6 cbf_force_new_datablock
2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.9 cbf_new_column
2.3.11 cbf_insert_row
2.3.12 cbf_delete_row
2.3.20 cbf_remove_row

2.3.11 cbf_insert_row

PROTOTYPE

#include "cbf.h"

int cbf_insert_row (cbf_handle handle, unsigned int rownumber);

DESCRIPTION

cbf_insert_row adds a new row to the current category. The new row is inserted as row rownumber and existing rows starting from rownumber are moved up by 1. The new row becomes the current row.

If the category has fewer than rownumber rows, the function returns CBF_NOTFOUND.

The row numbers start from 0.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.5 cbf_new_datablock
2.3.6 cbf_force_new_datablock
2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.9 cbf_new_column
2.3.10 cbf_new_row
2.3.12 cbf_delete_row
2.3.20 cbf_remove_row

2.3.12 cbf_delete_row

PROTOTYPE

#include "cbf.h"

int cbf_delete_row (cbf_handle handle, unsigned int rownumber);

DESCRIPTION

cbf_delete_row deletes a row from the current category. Rows starting from rownumber +1 are moved down by 1. If the current row was higher than rownumber, or if the current row is the last row, it will also move down by 1.

The row numbers start from 0.

ARGUMENTS

handle	CBF handle.
rownumber	The number of the row to delete.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.17 cbf_remove_datablock
2.3.18 cbf_remove_category
2.3.19 cbf_remove_column
2.3.20 cbf_remove_row

2.3.13 cbf_set_datablockname

PROTOTYPE

#include "cbf.h"

int cbf_set_datablockname (cbf_handle handle, const char *datablockname);

DESCRIPTION

cbf_set_datablockname changes the name of the current data block to datablockname.

If a data block with this name already exists (comparison is case-insensitive), the function returns CBF_IDENTICAL.

ARGUMENTS

handle	CBF handle.
datablockname	The new data block name.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.5 cbf_new_datablock
2.3.14 cbf_reset_datablocks
2.3.15 cbf_reset_datablock
2.3.17 cbf_remove_datablock
2.3.42 cbf_datablock_name

2.3.14 cbf_reset_datablocks

PROTOTYPE

#include "cbf.h"

int cbf_reset_datablocks (cbf_handle handle);

DESCRIPTION

cbf_reset_datablocks deletes all categories from all data blocks.

The current data block does not change.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.15 cbf_reset_datablock
2.3.18 cbf_remove_category

2.3.15 cbf_reset_datablock

PROTOTYPE

#include "cbf.h"

int cbf_reset_datablock (cbf_handle handle);

DESCRIPTION

cbf_reset_datablock deletes all categories from the current data block.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.14 cbf_reset_datablocks
2.3.18 cbf_remove_category

2.3.16 cbf_reset_category

PROTOTYPE

#include "cbf.h"

int cbf_reset_category (cbf_handle handle);

DESCRIPTION

cbf_reset_category deletes all columns and rows from current category.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.16 cbf_reset_category
2.3.19 cbf_remove_column
2.3.20 cbf_remove_row

2.3.17 cbf_remove_datablock

PROTOTYPE

#include "cbf.h"

int cbf_remove_datablock (cbf_handle handle);

DESCRIPTION

cbf_remove_datablock deletes the current data block.

The current data block becomes undefined.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.5 cbf_new_datablock
2.3.6 cbf_force_new_datablock
2.3.18 cbf_remove_category
2.3.19 cbf_remove_column
2.3.20 cbf_remove_row

2.3.18 cbf_remove_category

PROTOTYPE

#include "cbf.h"

int cbf_remove_category (cbf_handle handle);

DESCRIPTION

cbf_remove_category deletes the current category.

The current category becomes undefined.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.7 cbf_new_category
2.3.8 cbf_force_new_category
2.3.17 cbf_remove_datablock
2.3.19 cbf_remove_column
2.3.20 cbf_remove_row

2.3.19 cbf_remove_column

PROTOTYPE

#include "cbf.h"

int cbf_remove_column (cbf_handle handle);

DESCRIPTION

cbf_remove_column deletes the current column.

The current column becomes undefined.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.9 cbf_new_column
2.3.17 cbf_remove_datablock
2.3.18 cbf_remove_category
2.3.20 cbf_remove_row

2.3.20 cbf_remove_row

PROTOTYPE

#include "cbf.h"

int cbf_remove_row (cbf_handle handle);

DESCRIPTION

cbf_remove_row deletes the current row in the current category.

If the current row was the last row, it will move down by 1, otherwise, it will remain the same.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.10 cbf_new_row
2.3.11 cbf_insert_row
2.3.17 cbf_remove_datablock
2.3.18 cbf_remove_category
2.3.19 cbf_remove_column
2.3.12 cbf_delete_row

2.3.21 cbf_rewind_datablock

PROTOTYPE

#include "cbf.h"

int cbf_rewind_datablock (cbf_handle handle);

DESCRIPTION

cbf_rewind_datablock makes the first data block the current data block.

If there are no data blocks, the function returns CBF_NOTFOUND.

The current category becomes undefined.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.22 cbf_rewind_category
2.3.19 cbf_rewind_column
2.3.24 cbf_rewind_row
2.3.25 cbf_next_datablock

2.3.22 cbf_rewind_category

PROTOTYPE

#include "cbf.h"

int cbf_rewind_category (cbf_handle handle);

DESCRIPTION

cbf_rewind_category makes the first category in the current data block the current category.

If there are no categories, the function returns CBF_NOTFOUND.

The current column and row become undefined.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.21 cbf_rewind_datablock
2.3.19 cbf_rewind_column
2.3.24 cbf_rewind_row
2.3.26 cbf_next_category

2.3.23 cbf_rewind_column

PROTOTYPE

#include "cbf.h"

int cbf_rewind_column (cbf_handle handle);

DESCRIPTION

cbf_rewind_column makes the first column in the current category the current column.

If there are no columns, the function returns CBF_NOTFOUND.

The current row is not affected.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.21 cbf_rewind_datablock
2.3.22 cbf_rewind_category
2.3.24 cbf_rewind_row
2.3.27 cbf_next_column

2.3.24 cbf_rewind_row

PROTOTYPE

#include "cbf.h"

int cbf_rewind_row (cbf_handle handle);

DESCRIPTION

cbf_rewind_row makes the first row in the current category the current row.

If there are no rows, the function returns CBF_NOTFOUND.

The current column is not affected.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.21 cbf_rewind_datablock
2.3.22 cbf_rewind_category
2.3.19 cbf_rewind_column
2.3.28 cbf_next_row

2.3.25 cbf_next_datablock

PROTOTYPE

#include "cbf.h"

int cbf_next_datablock (cbf_handle handle);

DESCRIPTION

cbf_next_datablock makes the data block following the current data block the current data block.

If there are no more data blocks, the function returns CBF_NOTFOUND.

The current category becomes undefined.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.21 cbf_rewind_datablock
2.3.26 cbf_next_category
2.3.27 cbf_next_column
2.3.28 cbf_next_row

2.3.26 cbf_next_category

PROTOTYPE

#include "cbf.h"

int cbf_next_category (cbf_handle handle);

DESCRIPTION

cbf_next_category makes the category following the current category in the current data block the current category.

If there are no more categories, the function returns CBF_NOTFOUND.

The current column and row become undefined.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.22 cbf_rewind_category
2.3.25 cbf_next_datablock
2.3.27 cbf_next_column
2.3.27 cbf_next_row

2.3.27 cbf_next_column

PROTOTYPE

#include "cbf.h"

int cbf_next_column (cbf_handle handle);

DESCRIPTION

cbf_next_column makes the column following the current column in the current category the current column.

If there are no more columns, the function returns CBF_NOTFOUND.

The current row is not affected.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.19 cbf_rewind_column
2.3.25 cbf_next_datablock
2.3.26 cbf_next_category
2.3.28 cbf_next_row

2.3.28 cbf_next_row

PROTOTYPE

#include "cbf.h"

int cbf_next_row (cbf_handle handle);

DESCRIPTION

cbf_next_row makes the row following the current row in the current category the current row.

If there are no more rows, the function returns CBF_NOTFOUND.

The current column is not affected.

ARGUMENTS

handle

CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.24 cbf_rewind_row
2.3.25 cbf_next_datablock
2.3.26 cbf_next_category
2.3.27 cbf_next_column

2.3.29 cbf_find_datablock

PROTOTYPE

#include "cbf.h"

int cbf_find_datablock (cbf_handle handle, const char *datablockname);

DESCRIPTION

cbf_find_datablock makes the data block with name datablockname the current data block.

The comparison is case-insensitive.

If the data block does not exist, the function returns CBF_NOTFOUND.

The current category becomes undefined.

ARGUMENTS

handle	CBF handle.
datablockname	The name of the data block to find.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.21 cbf_rewind_datablock
2.3.25 cbf_next_datablock
2.3.30 cbf_find_category
2.3.31 cbf_find_column
2.3.32 cbf_find_row
2.3.42 cbf_datablock_name

2.3.30 cbf_find_category

PROTOTYPE

#include "cbf.h"

int cbf_find_category (cbf_handle handle, const char *categoryname);

DESCRIPTION

cbf_find_category makes the category in the current data block with name categoryname the current category.

The comparison is case-insensitive.

If the category does not exist, the function returns CBF_NOTFOUND.

The current column and row become undefined.

ARGUMENTS

handle	CBF handle.
categoryname	The name of the category to find.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.22 cbf_rewind_category
2.3.26 cbf_next_category
2.3.29 cbf_find_datablock
2.3.31 cbf_find_column
2.3.32 cbf_find_row
2.3.43 cbf_category_name

2.3.31 cbf_find_column

PROTOTYPE

#include "cbf.h"

int cbf_find_column (cbf_handle handle, const char *columnname);

DESCRIPTION

cbf_find_column makes the columns in the current category with name columnname the current column.

The comparison is case-insensitive.

If the column does not exist, the function returns CBF_NOTFOUND.

The current row is not affected.

ARGUMENTS

handle	CBF handle.
columnname	The name of column to find.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.19 cbf_rewind_column
2.3.27 cbf_next_column
2.3.29 cbf_find_datablock
2.3.30 cbf_find_category
2.3.32 cbf_find_row
2.3.44 cbf_column_name

2.3.32 cbf_find_row

PROTOTYPE

#include "cbf.h"

int cbf_find_row (cbf_handle handle, const char *value);

DESCRIPTION

cbf_find_row makes the first row in the current column with value value the current row.

The comparison is case-sensitive.

If a matching row does not exist, the function returns CBF_NOTFOUND.

The current column is not affected.

ARGUMENTS

handle	CBF handle.
value	The value of the row to find.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.24 cbf_rewind_row
2.3.28 cbf_next_row
2.3.29 cbf_find_datablock
2.3.30 cbf_find_category
2.3.31 cbf_find_column
2.3.33 cbf_find_nextrow
2.3.46 cbf_get_value

2.3.33 cbf_find_nextrow

PROTOTYPE

#include "cbf.h"

int cbf_find_nextrow (cbf_handle handle, const char *value);

DESCRIPTION

cbf_find_nextrow makes the makes the next row in the current column with value value the current row. The search starts from the row following the last row found with cbf_find_row or cbf_find_nextrow, or from the current row if the current row was defined using any other function.

The comparison is case-sensitive.

If no more matching rows exist, the function returns CBF_NOTFOUND.

The current column is not affected.

ARGUMENTS

handle	CBF handle.
value	the value to search for.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.24 cbf_rewind_row
2.3.28 cbf_next_row
2.3.29 cbf_find_datablock
2.3.30 cbf_find_category
2.3.31 cbf_find_column
2.3.32 cbf_find_row
2.3.46 cbf_get_value

2.3.34 cbf_count_datablocks

PROTOTYPE

#include "cbf.h"

int cbf_count_datablocks (cbf_handle handle, unsigned int *datablocks);

DESCRIPTION

cbf_count_datablocks puts the number of data blocks in *datablocks .

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.35 cbf_count_categories
2.3.36 cbf_count_columns
2.3.37 cbf_count_rows
2.3.38 cbf_select_datablock

2.3.35 cbf_count_categories

PROTOTYPE

#include "cbf.h"

int cbf_count_categories (cbf_handle handle, unsigned int *categories);

DESCRIPTION

cbf_count_categories puts the number of categories in the current data block in *categories.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.34 cbf_count_datablocks
2.3.36 cbf_count_columns
2.3.37 cbf_count_rows
2.3.39 cbf_select_category

2.3.36 cbf_count_columns

PROTOTYPE

#include "cbf.h"

int cbf_count_columns (cbf_handle handle, unsigned int *columns);

DESCRIPTION

cbf_count_columns puts the number of columns in the current category in *columns.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.34 cbf_count_datablocks
2.3.35 cbf_count_categories
2.3.37 cbf_count_rows
2.3.40 cbf_select_column

2.3.37 cbf_count_rows

PROTOTYPE

#include "cbf.h"

int cbf_count_rows (cbf_handle handle, unsigned int *rows);

DESCRIPTION

cbf_count_rows puts the number of rows in the current category in *rows .

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.34 cbf_count_datablocks
2.3.35 cbf_count_categories
2.3.36 cbf_count_columns
2.3.41 cbf_select_row

2.3.38 cbf_select_datablock

PROTOTYPE

#include "cbf.h"

int cbf_select_datablock (cbf_handle handle, unsigned int datablock);

DESCRIPTION

cbf_select_datablock selects data block number datablock as the current data block.

The first data block is number 0.

If the data block does not exist, the function returns CBF_NOTFOUND.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.34 cbf_count_datablocks
2.3.39 cbf_select_category
2.3.40 cbf_select_column
2.3.41 cbf_select_row

2.3.39 cbf_select_category

PROTOTYPE

#include "cbf.h"

int cbf_select_category (cbf_handle handle, unsigned int category);

DESCRIPTION

cbf_select_category selects category number category in the current data block as the current category.

The first category is number 0.

The current column and row become undefined.

If the category does not exist, the function returns CBF_NOTFOUND.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.35 cbf_count_categories
2.3.38 cbf_select_datablock
2.3.40 cbf_select_column
2.3.41 cbf_select_row

2.3.40 cbf_select_column

PROTOTYPE

#include "cbf.h"

int cbf_select_column (cbf_handle handle, unsigned int column);

DESCRIPTION

cbf_select_column selects column number column in the current category as the current column.

The first column is number 0.

The current row is not affected

If the column does not exist, the function returns CBF_NOTFOUND.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.36 cbf_count_columns
2.3.38 cbf_select_datablock
2.3.39 cbf_select_category
2.3.41 cbf_select_row

2.3.41 cbf_select_row

PROTOTYPE

#include "cbf.h"

int cbf_select_row (cbf_handle handle, unsigned int row);

DESCRIPTION

cbf_select_row selects row number row in the current category as the current row.

The first row is number 0.

The current column is not affected

If the row does not exist, the function returns CBF_NOTFOUND.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.37 cbf_count_rows
2.3.38 cbf_select_datablock
2.3.39 cbf_select_category
2.3.40 cbf_select_column

2.3.42 cbf_datablock_name

PROTOTYPE

#include "cbf.h"

int cbf_datablock_name (cbf_handle handle, const char **datablockname);

DESCRIPTION

cbf_datablock_name sets *datablockname to point to the name of the current data block.

The data block name will be valid as long as the data block exists and has not been renamed.

The name must not be modified by the program in any way.

ARGUMENTS

handle	CBF handle.
datablockname	Pointer to the destination data block name pointer.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.29 cbf_find_datablock

2.3.43 cbf_category_name

PROTOTYPE

#include "cbf.h"

int cbf_category_name (cbf_handle handle, const char **categoryname);

DESCRIPTION

cbf_category_name sets *categoryname to point to the name of the current category of the current data block.

The category name will be valid as long as the category exists.

The name must not be modified by the program in any way.

ARGUMENTS

handle	CBF handle.
categoryname	Pointer to the destination category name pointer.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.30 cbf_find_category

2.3.44 cbf_column_name

PROTOTYPE

#include "cbf.h"

int cbf_column_name (cbf_handle handle, const char **columnname);

DESCRIPTION

cbf_column_name sets *columnname to point to the name of the current column of the current category.

The column name will be valid as long as the column exists.

The name must not be modified by the program in any way.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.31 cbf_find_column

2.3.45 cbf_row_number

PROTOTYPE

#include "cbf.h"

int cbf_row_number (cbf_handle handle, unsigned int *row);

DESCRIPTION

cbf_row_number sets *row to the number of the current row of the current category.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.41 cbf_select_row

2.3.46 cbf_get_value

PROTOTYPE

#include "cbf.h"

int cbf_get_value (cbf_handle handle, const char **value);

DESCRIPTION

cbf_get_value sets *value to point to the ASCII value of the item at the current column and row.

If the value is not ASCII, the function returns CBF_BINARY.

The value will be valid as long as the item exists and has not been set to a new value.

The value must not be modified by the program in any way.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.47 cbf_set_value
2.3.48 cbf_get_integervalue
2.3.50 cbf_get_doublevalue
2.3.52 cbf_get_integerarrayparameters
2.3.53 cbf_get_integerarray

2.3.47 cbf_set_value

PROTOTYPE

#include "cbf.h"

int cbf_set_value (cbf_handle handle, const char *value);

DESCRIPTION

cbf_set_value sets the item at the current column and row to the ASCII value value.

ARGUMENTS

handle	CBF handle.
value	ASCII value.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.46 cbf_get_value
2.3.49 cbf_set_integervalue
2.3.51 cbf_set_doublevalue
2.3.54 cbf_set_integerarray

2.3.48 cbf_get_integervalue

PROTOTYPE

#include "cbf.h"

int cbf_get_integervalue (cbf_handle handle, int *number);

DESCRIPTION

cbf_get_integervalue sets *number to the value of the ASCII item at the current column and row interpreted as a decimal integer.

If the value is not ASCII, the function returns CBF_BINARY.

ARGUMENTS

handle	CBF handle.
number	pointer to the number.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.46 cbf_get_value
2.3.49 cbf_set_integervalue
2.3.50 cbf_get_doublevalue
2.3.52 cbf_get_integerarrayparameters
2.3.53 cbf_get_integerarray

2.3.49 cbf_set_integervalue

PROTOTYPE

#include "cbf.h"

int cbf_set_integervalue (cbf_handle handle, int number);

DESCRIPTION

cbf_set_integervalue sets the item at the current column and row to the integer value number written as a decimal ASCII string.

ARGUMENTS

handle	CBF handle.
number	Integer value.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.46 cbf_get_value
2.3.47 cbf_set_value
2.3.48 cbf_get_integervalue
2.3.49 cbf_set_integervalue
2.3.51 cbf_set_doublevalue
2.3.54 cbf_set_integerarray

2.3.50 cbf_get_doublevalue

PROTOTYPE

#include "cbf.h"

int cbf_get_doublevalue (cbf_handle handle, double *number);

DESCRIPTION

cbf_get_doublevalue sets *number to the value of the ASCII item at the current column and row interpreted as a decimal floating-point number.

If the value is not ASCII, the function returns CBF_BINARY.

ARGUMENTS

handle	CBF handle.
number	Pointer to the destination number.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.46 cbf_get_value
2.3.48 cbf_get_integervalue
2.3.51 cbf_set_doublevalue
2.3.52 cbf_get_integerarrayparameters
2.3.53 cbf_get_integerarray

2.3.51 cbf_set_doublevalue

PROTOTYPE

#include "cbf.h"

int cbf_set_doublevalue (cbf_handle handle, const char *format, double number);

DESCRIPTION

cbf_set_doublevalue sets the item at the current column and row to the floating-point value number written as an ASCII string with the format specified by format as appropriate for the printf function.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.46 cbf_get_value
2.3.47 cbf_set_value
2.3.49 cbf_set_integervalue
2.3.50 cbf_get_doublevalue
2.3.54 cbf_set_integerarray

2.3.52 cbf_get_integerarrayparameters

PROTOTYPE

#include "cbf.h"

int cbf_get_integerarrayparameters (cbf_handle handle, unsigned int *compression, int *binary_id, size_t *elsize, int *elsigned, int *elunsigned, size_t *elements, int *minelement, int *maxelement);

DESCRIPTION

cbf_get_integerarrayparameters sets *compression, *binary_id, *elsize, *elsigned, *elunsigned, *elements, *minelement and *maxelement to values read from the binary value of the item at the current column and row. This provides all the arguments needed for a subsequent call to cbf_set_integerarray, if a copy of the arry is to be made into another CIF or CBF.

If the value is not binary, the function returns CBF_ASCII.

ARGUMENTS

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.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.46 cbf_get_value
2.3.48 cbf_get_integervalue
2.3.50 cbf_get_doublevalue
2.3.53 cbf_get_integerarray
2.3.54 cbf_set_integerarray

2.3.53 cbf_get_integerarray

PROTOTYPE

#include "cbf.h"

int cbf_get_integerarray (cbf_handle handle, int *binary_id, void *array, size_t elsize, int elsigned, size_t elements, size_t *elements_read);

DESCRIPTION

cbf_get_integerarray reads the binary value of the item at the current column and row into an integer array. The array consists of elements elements of elsize bytes each, starting at array. The elements are signed if elsigned is non-0 and unsigned otherwise. *binary_id is set to the binary section identifier and *elements_read to the number of elements actually read.

If any element in the binary data cant fit into the destination element, the destination is set the nearest possible value.

If the value is not binary, the function returns CBF_ASCII.

If the requested number of elements cant be read, the function will read as many as it can and then return CBF_ENDOFDATA.

Currently, the destination array must consist of chars, shorts or ints (signed or unsigned). If elsize is not equal to sizeof (char), sizeof (short) or sizeof (int), the function returns CBF_ARGUMENT.

An additional restriction in the current version of CBFlib is that values too large to fit in an int are not correctly decompressed. As an example, if the machine with 32-bit ints is reading an array containing a value outside the range 0 .. 2^³²-1 (unsigned) or -2^³¹ .. 2^³¹-1 (signed), the array will not be correctly decompressed. This restriction will be removed in a future release.

ARGUMENTS

handle	CBF handle.
binary_id	Pointer to the destination integer binary identifier.
array	Pointer to the destination array.
elsize	Size in bytes of each destination array element.
elsigned	Set to non-0 if the destination array elements are signed.
elements	The number of elements to read.
elements_read	Pointer to the destination number of elements actually read.

RETURN VALUE

Returns an error code on failure or 0 for success.
SEE ALSO

2.3.46 cbf_get_value
2.3.48 cbf_get_integervalue
2.3.50 cbf_get_doublevalue
2.3.52 cbf_get_integerarrayparameters
2.3.54 cbf_set_integerarray

2.3.54 cbf_set_integerarray

PROTOTYPE

#include "cbf.h"

int cbf_set_integerarray (cbf_handle handle, unsigned int compression, int binary_id, void *array, size_t elsize, int elsigned, size_t elements);

DESCRIPTION

cbf_set_integerarray sets the binary value of the item at the current column and row to an integer array. The array consists of elements elements of elsize bytes each, starting at array. The elements are signed if elsigned is non-0 and unsigned otherwise. binary_id is the binary section identifier.

The array will be compressed using the compression scheme specifed by compression. Currently, the available schemes are:

CBF_CANONICAL	Canonical-code compression (section 3.3.1)
CBF_PACKED	CCP4-style packing (section 3.3.2)
CBF_NONE	No compression. NOTE: This scheme is by far the slowest of the three 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.

The values compressed are limited to 64 bits. If any element in the array is larger than 64 bits, the value compressed is the nearest 64-bit value.

Currently, the source array must consist of chars, shorts or ints (signed or unsigned). If elsize is not equal to sizeof (char), sizeof (short) or sizeof (int), the function returns CBF_ARGUMENT.

ARGUMENTS

handle	CBF handle.
compression	Compression method to use.
binary_id	Integer binary identifier.
array	Pointer to the source array.
elsize	Size in bytes of each source array element.
elsigned	Set to non-0 if the source array elements are signed. elements: The number of elements in the array.

RETURN VALUE

Returns an error code on failure or 0 for success.

SEE ALSO

2.3.47 cbf_set_value
2.3.49 cbf_set_integervalue
2.3.51 cbf_set_doublevalue
2.3.52 cbf_get_integerarrayparameters
2.3.53 cbf_get_integerarray

2.3.55 cbf_failnez

DEFINITION

#include "cbf.h"

#define cbf_failnez(f) {int err; err = (f); if (err) return err; }

DESCRIPTION

cbf_failnez is a macro used for error propagation throughout CBFlib. cbf_failnez executes the function f and saves the returned error value. If the error value is non-0, cbf_failnez executes a return with the error value as argument. If CBFDEBUG is defined, then a report of the error is also printed to the standard error stream, stderr, in the form

CBFlib error f in "symbol"

where f is the decimal value of the error and symbol is the symbolic form.

ARGUMENTS

f	Integer error value.

SEE ALSO

2.3.56 cbf_onfailnez

2.3.56 cbf_onfailnez

DEFINITION

#include "cbf.h"

#define cbf_onfailnez(f,c) {int err; err = (f); if (err) {{c; }return err; }}

DESCRIPTION

cbf_onfailnez is a macro used for error propagation throughout CBFlib. cbf_onfailnez executes the function f and saves the returned error value. If the error value is non-0, cbf_failnez executes first the statement c and then a return with the error value as argument. If CBFDEBUG is defined, then a report of the error is also printed to the standard error stream, stderr, in the form

CBFlib error f in "symbol"

where f is the decimal value of the error and symbol is the symbolic form.

ARGUMENTS

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

SEE ALSO

2.3.55 cbf_failnez

2.4 High-level function prototypes

2.4.1 cbf_read_template

PROTOTYPE

#include "cbf_simple.h"

int cbf_read_template (cbf_handle handle, FILE *file);

DESCRIPTION

cbf_read_template reads the CBF or CIF file file into the CBF object specified by handle and selects the first datablock as the current datablock.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.2 cbf_get_diffrn_id

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_diffrn_id (cbf_handle handle, const char **diffrn_id);

DESCRIPTION

cbf_get_diffrn_id sets *diffrn_id to point to the ASCII value of the "diffrn.id" entry.

The diffrn_id will be valid as long as the item exists and has not been set to a new value.

The diffrn_id must not be modified by the program in any way.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.3 cbf_set_diffrn_id

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_diffrn_id (cbf_handle handle, const char *diffrn_id);

DESCRIPTION

cbf_set_diffrn_id sets the "diffrn.id" entry of the current datablock to the ASCII value diffrn_id.

This function also changes corresponding "diffrn_id" entries in the "diffrn_source", "diffrn_radiation", "diffrn_detector" and "diffrn_measurement" categories.

ARGUMENTS

handle	CBF handle.
diffrn_id	ASCII value.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.4 cbf_get_crystal_id

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_crystal_id (cbf_handle handle, const char **crystal_id);

DESCRIPTION

cbf_get_crystal_id sets *crystal_id to point to the ASCII value of the "diffrn.crystal_id" entry.

If the value is not ASCII, the function returns CBF_BINARY.

The value will be valid as long as the item exists and has not been set to a new value.

The value must not be modified by the program in any way.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.5 cbf_set_crystal_id

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_crystal_id (cbf_handle handle, const char *crystal_id);

DESCRIPTION

cbf_set_crystal_id sets the "diffrn.crystal_id" entry to the ASCII value crystal_id.

ARGUMENTS

handle	CBF handle.
crystal_id	ASCII value.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.6 cbf_get_wavelength

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_wavelength (cbf_handle handle, double *wavelength);

DESCRIPTION

cbf_get_wavelength sets *wavelength to the current wavelength in Å.

ARGUMENTS

handle	CBF handle.
wavelength	Pointer to the destination.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.7 cbf_set_wavelength

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_wavelength (cbf_handle handle, double wavelength);

DESCRIPTION

cbf_set_wavelength sets the current wavelength in Å to wavelength.

ARGUMENTS

handle	CBF handle.
wavelength	Wavelength in Å.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.8 cbf_get_polarization

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_polarization (cbf_handle handle, double *polarizn_source_ratio, double *polarizn_source_norm);

DESCRIPTION

cbf_get_polarization sets *polarizn_source_ratio and *polarizn_source_norm to the corresponding source polarization parameters.

Either destination pointer may be NULL.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.9 cbf_set_polarization

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_polarization (cbf_handle handle, double polarizn_source_ratio, double polarizn_source_norm);

DESCRIPTION

cbf_set_polarization sets the source polarization to the values specified by polarizn_source_ratio and polarizn_source_norm.

ARGUMENTS

handle	CBF handle.
polarizn_source_ratio	New value of polarizn_source_ratio.
polarizn_source_norm	New value of polarizn_source_norm.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.10 cbf_get_divergence

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_divergence (cbf_handle handle, double *div_x_source, double *div_y_source, double *div_x_y_source);

DESCRIPTION

cbf_get_divergence sets *div_x_source, *div_y_source and *div_x_y_source to the corresponding source divergence parameters.

Any of the destination pointers may be NULL.

ARGUMENTS

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.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.11 cbf_ set_divergence

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_divergence (cbf_handle handle, double div_x_source, double div_y_source, double div_x_y_source);

DESCRIPTION

cbf_set_divergence sets the source divergence parameters to the values specified by div_x_source, div_y_source and div_x_y_source.

ARGUMENTS

handle	CBF handle.
div_x_source	New value of div_x_source.
div_y_source	New value of div_y_source.
div_x_y_source	New value of div_x_y_source.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.12 cbf_count_elements

PROTOTYPE

#include "cbf_simple.h"

int cbf_count_elements (cbf_handle handle, unsigned int *elements);

DESCRIPTION

cbf_count_elements sets *elements to the number of detector elements.

ARGUMENTS

handle	CBF handle.
elements	Pointer to the destination count.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.13 cbf_get_element_id

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_element_id (cbf_handle handle, unsigned int element_number, const char **element_id);

DESCRIPTION

cbf_get_element_id sets *element_id to point to the ASCII value of the element_numberŐth "diffrn_data_frame.detector_element_id" entry, counting from 0.

If the detector element does not exist, the function returns CBF_NOTFOUND.

The element_id will be valid as long as the item exists and has not been set to a new value.

The element_id must not be modified by the program in any way.

ARGUMENTS

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.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.14 cbf_get_gain

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_gain (cbf_handle handle, unsigned int element_number, double *gain, double *gain_esd);

DESCRIPTION

cbf_get_gain sets *gain and *gain_esd to the corresponding gain parameters for element number element_number.

Either of the destination pointers may be NULL.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.15 cbf_ set_gain

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_gain (cbf_handle handle, unsigned int element_number, double gain, double gain_esd);

DESCRIPTION

cbf_set_gain sets the gain of element number element_number to the values specified by gain and gain_esd.

ARGUMENTS

handle	CBF handle.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
gain	New gain value.
gain_esd	New gain_esd value.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.16 cbf_get_overload

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_overload (cbf_handle handle, unsigned int element_number, double *overload);

DESCRIPTION

cbf_get_overload sets *overload to the overload value for element number element_number.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.17 cbf_ set_overload

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_overload (cbf_handle handle, unsigned int element_number, double overload);

DESCRIPTION

cbf_set_overload sets the overload value of element number element_number to overload.

ARGUMENTS

handle	CBF handle.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
overload	New overload value.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.18 cbf_get_integration_time

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_integration_time (cbf_handle handle, unsigned int reserved, double *time);

DESCRIPTION

cbf_get_integration_time sets *time to the integration time in seconds. The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.19 cbf_set_integration_time

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_integration_time (cbf_handle handle, unsigned int reserved, double time);

DESCRIPTION

cbf_set_integration_time sets the integration time in seconds to the value specified by time. The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
time Integration	time in seconds.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.20 cbf_get_timestamp

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_timestamp (cbf_handle handle, unsigned int reserved, double *time, int *timezone);

DESCRIPTION

cbf_get_timestamp sets *time to the collection timestamp in seconds since January 1 1970. *timezone is set to timezone difference from UTC in minutes. The parameter reserved is presently unused and should be set to 0.

Either of the destination pointers may be NULL.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.21 cbf_set_timestamp

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_timestamp (cbf_handle handle, unsigned int reserved, double time, int timezone, double precision);

DESCRIPTION

cbf_set_timestamp sets the collection timestamp in seconds since January 1 1970 to the value specified by time. The timezone difference from UTC in minutes is set to timezone. If no timezone is desired, timezone should be CBF_NOTIMEZONE. The parameter reserved is presently unused and should be set to 0.

The precision of the new timestamp is specified by the value precision in seconds. If precision is 0, the saved timestamp is assumed accurate to 1 second.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
time	Timestamp in seconds since January 1 1970.
timezone	Timezone difference from UTC in minutes or CBF_NOTIMEZONE.
precision	Timestamp precision in seconds.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.22 cbf_get_datestamp

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_datestamp (cbf_handle handle, unsigned int reserved, int *year, int *month, int *day, int *hour, int *minute, double *second, int *timezone);

DESCRIPTION

cbf_get_datestamp sets *year, *month, *day, *hour, *minute and *second to the corresponding values of the collection timestamp. *timezone is set to timezone difference from UTC in minutes. The parameter reserved is presently unused and should be set to 0.

Any of the destination pointers may be NULL.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
year	Pointer to the destination timestamp year.
month	Pointer to the destination timestamp month (1-12).
day	Pointer to the destination timestamp day (1-31).
hour	Pointer to the destination timestamp hour (0-23).
minute	Pointer to the destination timestamp minute (0-59).
second	Pointer to the destination timestamp second (0-60.0).
timezone	Pointer to the destination timezone difference from UTC in minutes.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.23 cbf_set_datestamp

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_datestamp (cbf_handle handle, unsigned int reserved, int year, int month, int day, int hour, int minute, double second, int timezone, double precision);

DESCRIPTION

cbf_set_datestamp sets the collection timestamp in seconds since January 1 1970 to the value specified by time. The timezone difference from UTC in minutes is set to timezone. If no timezone is desired, timezone should be CBF_NOTIMEZONE. The parameter reserved is presently unused and should be set to 0.

The precision of the new timestamp is specified by the value precision in seconds. If precision is 0, the saved timestamp is assumed accurate to 1 second.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
time	Timestamp in seconds since January 1 1970.
timezone	Timezone difference from UTC in minutes or CBF_NOTIMEZONE.
precision	Timestamp precision in seconds.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.24 cbf_set_current_timestamp

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_current_timestamp (cbf_handle handle, unsigned int reserved, int timezone)

DESCRIPTION

cbf_set_current_timestamp sets the collection timestamp to the current time. The timezone difference from UTC in minutes is set to timezone. If no timezone is desired, timezone should be CBF_NOTIMEZONE. If no timezone is used, the timestamp will be UTC. The parameter reserved is presently unused and should be set to 0.

The new timestamp will have a precision of 1 second.

ARGUMENTS

handle	CBF handle.
reserved	Unused.   Any value other than 0 is invalid.
timezone	Timezone difference from UTC in minutes or CBF_NOTIMEZONE.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.25 cbf_get_image_size

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_image_size (cbf_handle handle, unsigned int reserved, unsigned int element_number, size_t *ndim1, size_t *ndim2);

DESCRIPTION

cbf_get_image_size sets *ndim1 and *ndim2 to the slow and fast dimensions of the image array for element number element_number. If the array is 1-dimensional, *ndim1 will be set to the array size and *ndim2 will be set to 1.

Either of the destination pointers may be NULL.

The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
ndim1	Pointer to the destination slow dimension.
ndim2	Pointer to the destination fast dimension.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.26 cbf_get_image

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_image (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, int elsign, size_t ndim1, size_t ndim2);

DESCRIPTION

cbf_get_image reads the image array for element number element_number into an array. The array consists of ndim1×ndim2 elements of elsize bytes each, starting at array. The elements are signed if elsign is non-0 and unsigned otherwise.

If the array is 1-dimensional, ndim1 should be the array size and ndim2 should be set to 1.

If any element in the binary data canŐt fit into the destination element, the destination is set the nearest possible value.

If the value is not binary, the function returns CBF_ASCII.

If the requested number of elements canŐt be read, the function will read as many as it can and then return CBF_ENDOFDATA.

Currently, the destination array must consist of chars, shorts or ints (signed or unsigned). If elsize is not equal to sizeof (char), sizeof (short) or sizeof (int), the function returns CBF_ARGUMENT.

An additional restriction in the current version of CBFlib is that values too large to fit in an int are not correctly decompressed. As an example, if the machine with 32-bit ints is reading an array containing a value outside the range 0 .. 232-1 (unsigned) or -231 .. 231-1 (signed), the array will not be correctly decompressed. This restriction will be removed in a future release.

The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
array	Pointer to the destination array.
elsize	Size in bytes of each destination array element.
elsigned	Set to non-0 if the destination array elements are signed.
ndim1	Slow array dimension.
ndim2	Fast array dimension.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.27 cbf_set_image

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_image (cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array, size_t elsize, int elsign, size_t ndim1, size_t ndim2);

DESCRIPTION

cbf_set_image writes the image array for element number element_number. The array consists of ndim1×ndim2 elements of elsize bytes each, starting at array. The elements are signed if elsign is non-0 and unsigned otherwise.

If the array is 1-dimensional, ndim1 should be the array size and ndim2 should be set to 1.

The array will be compressed using the compression scheme specifed by compression. Currently, the available schemes are:

CBF_CANONICAL	Canonical-code compression (section 3.3.1)
CBF_PACKED	CCP4-style packing (section 3.3.2)
CBF_NONE	No compression.

The values compressed are limited to 64 bits. If any element in the array is larger than 64 bits, the value compressed is the nearest 64-bit value.

Currently, the source array must consist of chars, shorts or ints (signed or unsigned). If elsize is not equal to sizeof (char), sizeof (short) or sizeof (int), the function returns CBF_ARGUMENT.

The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
compression	Compression type.
array	Pointer to the destination array.
elsize	Size in bytes of each destination array element.
elsigned	Set to non-0 if the destination array elements are signed.
ndim1	Slow array dimension.
ndim2	Fast array dimension.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.28 cbf_get_axis_setting

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_axis_setting (cbf_handle handle, unsigned int reserved, const char *axis_id, double *start, double *increment);

DESCRIPTION

cbf_get_axis_setting sets *start and *increment to the corresponding values of the axis axis_id.

Either of the destination pointers may be NULL.

The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
axis_id	Axis id.
start	Pointer to the destination start value.
increment	Pointer to the destination increment value.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.29 cbf_set_axis_setting

PROTOTYPE

#include "cbf_simple.h"

int cbf_set_axis_setting (cbf_handle handle, unsigned int reserved, const char *axis_id, double start, double increment);

DESCRIPTION

cbf_set_axis_setting sets the starting and increment values of the axis axis_id to start and increment.

The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
axis_id	Axis id.
start	Start value.
increment	Increment value.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.30 cbf_construct_goniometer

PROTOTYPE

#include "cbf_simple.h"

int cbf_construct_goniometer (cbf_handle handle, cbf_goniometer *goniometer);

DESCRIPTION

cbf_construct_goniometer constructs a goniometer object using the description in the CBF object handle and initialises the goniometer handle *goniometer.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.31 cbf_free_goniometer

PROTOTYPE

#include "cbf_simple.h"

int cbf_free_goniometer (cbf_goniometer goniometer);

DESCRIPTION

cbf_free_goniometer destroys the goniometer object specified by goniometer and frees all associated memory.

ARGUMENTS

goniometer

Goniometer handle to free.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.32 cbf_get_rotation_axis

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_rotation_axis (cbf_goniometer goniometer, unsigned int reserved, double *vector1, double *vector2, double vector3);

DESCRIPTION

cbf_get_rotation_axis sets *vector1, *vector2, and *vector3 to the 3 components of the goniometer rotation axis used for the exposure.

Any of the destination pointers may be NULL.

The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

goniometer	Goniometer handle.
reserved	Unused. Any value other than 0 is invalid.
vector1	Pointer to the destination x component of the rotation axis.
vector2	Pointer to the destination y component of the rotation axis.
vector3	Pointer to the destination z component of the rotation axis.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.33 cbf_get_rotation_range

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_rotation_range (cbf_goniometer goniometer, unsigned int reserved, double *start, double *increment);

DESCRIPTION

cbf_get_rotation_range sets *start and *increment to the corresponding values of the goniometer rotation axis used for the exposure.

Either of the destination pointers may be NULL.

The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

goniometer	Goniometer handle.
reserved	Unused. Any value other than 0 is invalid.
start	Pointer to the destination start value.
increment	Pointer to the destination increment value.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.34 cbf_rotate_vector

PROTOTYPE

#include "cbf_simple.h"

int cbf_rotate_vector (cbf_goniometer goniometer, unsigned int reserved, double ratio, double initial1, double initial2, double initial3, double *final1, double *final2, double *final3);

DESCRIPTION

cbf_rotate_vector sets *final1, *final2, and *final3 to the 3 components of the of the vector (initial1, initial2, initial3) after reorientation by applying the goniometer rotations. The value ratio specifies the goniometer setting and varies from 0.0 at the beginning of the exposure to 1.0 at the end, irrespective of the actual rotation range.

Any of the destination pointers may be NULL.

The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

goniometer	Goniometer handle.
reserved	Unused. Any value other than 0 is invalid.
ratio	Goniometer setting. 0 = beginning of exposure, 1 = end.
initial1	x component of the initial vector.
initial2	y component of the initial vector.
initial3	z component of the initial vector.
vector1	Pointer to the destination x component of the final vector.
vector2	Pointer to the destination y component of the final vector.
vector3	Pointer to the destination z component of the final vector.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.35 cbf_get_reciprocal

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_reciprocal (cbf_goniometer goniometer, unsigned int reserved, double ratio, double wavelength, double real1, double real2, double real3, double *reciprocal1, double *reciprocal2, double *reciprocal3);

DESCRIPTION

cbf_get_reciprocal sets *reciprocal1, * reciprocal2, and * reciprocal3 to the 3 components of the of the reciprocal-space vector corresponding to the real-space vector (real1, real2, real3). The reciprocal-space vector is oriented to correspond to the goniometer setting with all axes at 0. The value wavelength is the wavlength in Å and the value ratio specifies the current goniometer setting and varies from 0.0 at the beginning of the exposure to 1.0 at the end, irrespective of the actual rotation range.

Any of the destination pointers may be NULL.

The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

goniometer	Goniometer handle.
reserved	Unused. Any value other than 0 is invalid.
ratio	Goniometer setting. 0 = beginning of exposure, 1 = end.
wavelength	Wavelength in Å.
real1	x component of the real-space vector.
real2	y component of the real-space vector.
real3	z component of the real-space vector.
reciprocal1	Pointer to the destination x component of the reciprocal-space vector.
reciprocal2	Pointer to the destination y component of the reciprocal-space vector.
reciprocal3	Pointer to the destination z component of the reciprocal-space vector.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.36 cbf_construct_detector

PROTOTYPE

#include "cbf_simple.h"

int cbf_construct_detector (cbf_handle handle, cbf_detector *detector, unsigned int element_number);

DESCRIPTION

cbf_construct_detector constructs a detector object for detector element number element_number using the description in the CBF object handle and initialises the detector handle *detector.

ARGUMENTS

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.37 cbf_free_detector

PROTOTYPE

#include "cbf_simple.h"

int cbf_free_detector (cbf_detector detector);

DESCRIPTION

cbf_free_detector destroys the detector object specified by detector and frees all associated memory.

ARGUMENTS

detector

Detector handle to free.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.38 cbf_get_beam_center

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_beam_center (cbf_detector detector, double *index1, double *index2, double *center1, double *center2);

DESCRIPTION

cbf_get_beam_center sets *center1 and *center2 to the displacements in mm along the detector axes from pixel (0, 0) to the point at which the beam intersects the detector and *index1 and *index2 to the corresponding indices.

Any of the destination pointers may be NULL.

ARGUMENTS

detector	Detector handle.
index1	Pointer to the destination slow index.
index2	Pointer to the destination fast index.
center1	Pointer to the destination displacement along the slow axis.
center2	Pointer to the destination displacement along the fast axis.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.39 cbf_get_detector_distance

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_detector_distance (cbf_detector detector, double *distance);

DESCRIPTION

cbf_get_detector_distance sets *distance to the nearest distance from the sample position to the detector plane.

ARGUMENTS

detector	Detector handle.
distance	Pointer to the destination distance.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.40 cbf_get_detector_normal

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_detector_normal (cbf_detector detector, double *normal1, double *normal2, double *normal3);

DESCRIPTION

cbf_get_detector_normal sets *normal1, *normal2, and *normal3 to the 3 components of the of the normal vector to the detector plane. The vector is normalized.

Any of the destination pointers may be NULL.

ARGUMENTS

detector	Detector handle.
normal1	Pointer to the destination x component of the normal vector.
normal2	Pointer to the destination y component of the normal vector.
normal3	Pointer to the destination z component of the normal vector.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.41 cbf_get_pixel_coordinates

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_pixel_coordinates (cbf_detector detector, double index1, double index2, double *coordinate1, double *coordinate2, double *coordinate3);

DESCRIPTION

cbf_get_pixel_coordinates sets *coordinate1, *coordinate2, and *coordinate3 to the vector position of pixel (index1, index2) on the detector surface. If index1 and index2 are integers then the coordinates correspond to the center of a pixel.

Any of the destination pointers may be NULL.

ARGUMENTS

detector	Detector handle.
index1	Slow index.
index2	Fast index.
coordinate1	Pointer to the destination x component.
oordinate2	Pointer to the destination y component.
coordinate3	Pointer to the destination z component.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.42 cbf_get_pixel_normal

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_pixel_normal (cbf_detector detector, double index1, double index2, double *normal1, double *normal2, double *normal3);

DESCRIPTION

cbf_get_detector_normal sets *normal1, *normal2, and *normal3 to the 3 components of the of the normal vector to the pixel at (index1, index2). The vector is normalized.

Any of the destination pointers may be NULL.

ARGUMENTS

detector	Detector handle.
index1	Slow index.
index2	Fast index.
normal1	Pointer to the destination x component of the normal vector.
normal2	Pointer to the destination y component of the normal vector.
normal3	Pointer to the destination z component of the normal vector.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.4.43 cbf_get_pixel_area

PROTOTYPE

#include "cbf_simple.h"

int cbf_get_pixel_area (cbf_detector detector, double index1, double index2, double *area, double *projected_area);

DESCRIPTION

cbf_get_pixel_area sets *area to the area of the pixel at (index1, index2) on the detector surface and *projected_area to the apparent area of the pixel as viewed from the sample position.

Either of the destination pointers may be NULL.

ARGUMENTS

detector	Detector handle.
index1	Slow index.
index2	Fast index.
area	Pointer to the destination area in mm2.
projected_area	Pointer to the destination apparent area in mm2.

RETURN VALUE

Returns an error code on failure or 0 for success.

3. File format

3.1 General description

With the exception of the binary sections, a CBF file is an mmCIF-format ASCII file, so a CBF file with no binary sections is a CIF file. An imgCIF file has any binary sections encoded as CIF-format ASCII strings and is a CIF file whether or not it contains binary sections. In most cases, CBFlib can also be used to access normal CIF files as well as CBF and imgCIF files.

3.2 Format of the binary sections

Before getting to the binary data itself, there are some preliminaries to allow a smooth transition from the conventions of CIF to those of raw or encoded streams of "octets" (8-bit bytes). The binary data is given as the essential part of a specially formatted semicolon-delimited CIF multi-line text string. This text string is the value associated with the tag "_array_data.data".

The specific format of the binary sections differs between an imgCIF and a CBF file.

3.2.1 Format of imgCIF binary sections

Each binary section is encoded as a ;-delimited string. Within the text string, the conventions developed for transmitting email messages including binary attachments are followed. There is secondary ASCII header information, formatted as Multipurpose Internet Mail Extensions (MIME) headers (see RFCs 2045-49 by Freed, et al.). The boundary marker for the beginning of all this is the special string

--CIF-BINARY-FORMAT-SECTION--

at the beginning of a line. The initial "--" says that this is a MIME boundary. We cannot put "###" in front of it and conform to MIME conventions. Immediately after the boundary marker are MIME headers, describing some useful information we will need to process the binary section. MIME headers can appear in different orders, and can be very confusing (look at the raw contents of a email message with attachments), but there is only one header which is has to be understood to process an imgCIF: "Content-Transfer-Encoding". If the value given on this header is "BINARY", this is a CBF and the data will be presented as raw binary, containing a count (in the header described in 3.2.2 Format of CBF binary sections) so that we'll know when to start looking for more information.

If the value given for "Content-Transfer-Encoding" is one of the real encodings: "BASE64", "QUOTED-PRINTABLE", "X-BASE8", "X-BASE10" or "X-BASE16", the file is an imgCIF, and we'll need some other headers to process the encoded binary data properly. It is a good practice to give headers in all cases. The meanings of various encodings is given in the CBF extensions dictionary, cif_img_1.1.3.dic.

The "Content-Type" header tells us what sort of data we have (currently always "application/octet-stream" for a miscellaneous stream of binary data) and, optionally, the conversions that we