CBFlib Manual

CBFlib

An API for CBF/imgCIF
Crystallographic Binary Files with ASCII Support
Version 0.7.9.1
24 January 2008

by
Paul J. Ellis
Stanford Synchrotron Radiation Laboratory

and
Herbert J. Bernstein
Bernstein + Sons

YOU MAY REDISTRIBUTE THE CBFLIB PACKAGE UNDER THE TERMS OF THE GPL.

ALTERNATIVELY YOU MAY REDISTRIBUTE THE CBFLIB API UNDER THE TERMS OF THE LGPL .

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.

Work on imgCIF and CBFlib supported in part by the U. S. Department of Energy (DOE) under grants ER63601-1021466-0009501 and ER64212-1027708-0011962, by the U. S. National Science Foundation (NSF) under grants DBI-0610407, DBI-0315281 and EF-0312612, the U. S. National Institutes of Health (NIH) under grants 1R15GM078077 from NIGMS and 1R13RR023192 from NCRR and funding from the International Union for Crystallographyn (IUCr). The content is solely the responsibility of the authors and does not necessarily represent the official views of DOE, NSF, NIH, NIGMS, NCRR or IUCr.

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).
  0.7.4   Jan 2004   HJB   This release fixes a parse error for quoted strings, adds code to get and set character string types, and removes compiler warnings
  0.7.5   Apr 2006   HJB   This release cleans up some compiler warnings, corrects a parse error on quoted strings with a leading blank as adds the new routines for support of aliases, dictionaries and real arrays, higher level routines to get and set pixel sizes, do cell computations, and to set beam centers, improves support for conversion of images, picking up more data from headers.
  0.7.6   Jul 2006   HJB   This release reorganizes the kit into two pieces: CBFlib_0.7.6_Data_Files and CBFlib_0.7.6. An optional local copy of getopt is added. The 1.4 draft dictionary has been added. cif2cbf updated to support vcif2 validation. convert_image and cif2cbf updated to report text of error messages. convert_image updated to support tag and category aliases, default to adxv images. convert_image and img updated to support row-major images. Support added for binning. API Support added for validation, wide files and line folding. Logic changed for beam center reporting. Added new routines: cbf_validate, cbf_get_bin_sizes, cbf_set_bin_sizes, cbf_find_last_typed_child, cbf_compose_itemname, cbf_set_cbf_logfile, cbf_make_widefile, cbf_read_anyfile, cbf_read_widefile, cbf_write_local_file, cbf_write_widefile, cbf_column_number, cbf_blockitem_number, cbf_log, cbf_check_category_tags, cbf_set_beam_center
  0.7.7   February 2007   HJB   This release reflects changes for base 32K support developed by G. Darakev, and changes for support of reals, 3d arrays, byte_offset compression and J. P. Abrahams packed compression made in consultation with (in alphabetic order) E. Eikenberry, A. Hammerley, W. Kabsch, M. Kobas, J. Wright and others at PSI and ESRF in January 2007, as well accumulated changes fixing problems in release 0.7.6.
  0.7.7.1   February 2007   HJB   This release is a patch to 0.7.7 to change the treatment of the byteorder parameter from strcpy semantics to return of a pointer to a string constant. Our thanks to E. Eikenberry for pointing out the problem.
  0.7.7.2   February 2007   HJB   This release is a patch to 0.7.7.1 to add testing for JPA packed compression and to respect signs declared in the MIME header.
  0.7.7.3   April 2007   HJB   This release is a patch to 0.7.7.3 to add f90 support for reading of CBF byte-offset and packed compression, to fix problems with gcc 4.4.1 and to correct errors in multidimensional packed compression.
  0.7.7.4   May 2007   HJB   Corrects in handling SLS detector mincbfs and reorder dimensions versus arrays for some f90 compilers as per H. Powell.
  0.7.7.5   May 2007   HJB   Fix to cbf_get_image for bug reported by F. Remacle, fixes for windows builds as per J. Wright and F. Remacle.
  0.7.7.6   Jun 2007   HJB   Fix to CBF byte-offset compression writes, fix to Makefiles and m4 for f90 test programs to allow adjustable record length.
  0.7.8   Jul 2007   HJB   Release for full support of SLS data files with updated convert_minicbf, and support for gfortran from gcc 4.2.
  0.7.8.1   Jul 2007   HJB   Update to 0.7.8 release to fix memory leaks reported by N. Sauter and to update validation checks for recent changes.
  0.7.8.2   Dec 2007   CN, HJB   Update to 0.7.8.1 to add ADSC jiffie by Chris Nielsen, and to add ..._fs and ..._sf macros.
  0.7.9   Dec 2007   CN, HJB Identical to 0.7.8.2 except for a cleanup of deprecated examples, e.g. diffrn_frame_data
  0.7.9.1   Jan 2008   CN, HJB   Update to 0.7.8.2 to add inverse ADSC jiffie by Chris Nielsen, to clean up problems in handling maps for RasMol.

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

Known Problems

This version does not have support for 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_0.7.9.tar.gz; and
the test data:
- CBFlib_0.7.9_Data_Files_Input.tar.gz (13 MB) a "gzipped" tar of the input data files needed to test the API;
- CBFlib_0.7.9_Data_Files_Output.tar.gz (34 MB) a "gzipped" tar of the output data files needed to test the API, or, if space is at a premium;
- CBFlib_0.7.9_Data_Files_Output_Sigs_Only.tar.gz (1KB) is a "gzipped" tar of only the MD5 signatures of the output data files needed to test the API.

If your system has the program wget, you only need the source code. The download of the other tar balls will be handled automatically.

Be careful about space. A full build and test can use 350 MB or more. If space is tight, be sure to read the instructions below on using only the signatures of the test files.

Uncompress and unpack :

gunzip < CBFlib_0.7.9.tar.gz | tar xvf -

To run the test programs, you will also need Paul Ellis's sample MAR345 image, example.mar2300, Chris Nielsen's sample ADSC Quantum 315 image, mb_LP_1_001.img, and Eric Eikenberry's SLS sample Pilatus 6m image, insulin_pilatus6m, as sample data. In addition there are is a PDB mmCIF file, 9ins.cif, and 3 special test files testflatin.cbf, testflatpackedin.cbf and testrealin.cbf. All these files will be dowloaded and extracted by the Makefile from CBFlib_0.7.9_Data_Files_Input. Do not download copies into the top level directory.

Thare are various sample Makefiles for common configurations. The Makefile_LINUX and Makefile_OSX samples are for systems with gfortran from prior to the release of gcc 4.2. For the most recent gfortran, use Makefile_LINUX_gcc42 ot Makfile_OSX_gcc42. All the Makefiles come from m4/Makefile.m4.

The Makefiles use GNU make constructs, such as ifeq and ifneq. If you need to use a diferent version of make, you will need to edit out the conditionals

If necessary, adjust the definition of CC and C++ and other defintions in Makefile to point to your compilers. Set the definition of CFLAGS to an appropriate value for your C and C++ compilers, the definition of F90C to point to your Fortan-90/95 compiler, and the definitions of F90FLAGS and F90LDFLAGS to approriate values for your Fortan-90/95 compilers, and then

make all
make tests

or, if space is at a premium:

make all
make tests_sigs_only

If you do not have a fortran compiler, you will need edit the Makefile or to define the variable NOFORTRAN, either in the Makefile or in the environment

We have included examples of CBF/imgCIF files produced by CBFlib in the test data CBFlib_0.7.9_Data_Files_Output.tar.gz, the current best draft of the CBF Extensions Dictionary, and of Andy Hammersley's CBF definition, updated to become a DRAFT CBF/ImgCIF DEFINITION.

1. Introduction
2. Function descriptions
3. File format
4. Installation
5. Example programs

1. Introduction

CBFlib (Crystallographic Binary File library) 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.

Starting with version 0.7.7, an envolving FCBlib (Fortran Crystallographic Binary library) has been added. As of this release it includes code for reading byte-offset and packed compression image files created by CBFlib.

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 one of the functions cbf_construct_detector, cbf_construct_reference_detector or cbf_require_reference_detector.

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

2.1.4 Return values

All of the CBFlib functions return 0 on success and an error code on failure. The error codes are:

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

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.2.4 Ordering of array indices

There are two major conventions in the ordering of array indices:

fs: Fast to slow. The first array index (the one numbered "1") is the one for which the values of that index change "fastest". That is as we move forward in memory, the value of this index changes more rapidly than any other.
sf: Slow to fast. The first array index (the one numbered "1") is the one for which the values of that index change "slowest". That is as we move forward in memory, the value of this index changes more slowly than any other.

During the development of CBFlib, both conventions have been used. In order to avoid confusion, the functions for which array indices are used are available in three forms: a default version which may used either one convention or the other, a form in which the name of the function has an "_fs" suffix for the fast to slow convention and a form in which the name of the function has a "_sf" suffix for the slow to fast convention. Designers of applications are advised to use one of the two conventions. There is no burden on performance for using one convention or the other. The differences are resolved at compile time by use of preprocessor macros.

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

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);
int cbf_read_widefile (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, using the CIF 1.0 convention of 80 character lines. cbf_read_widefile reads the CBF or CIF file file into the CBF object specified by handle, using the CIF 1.1 convention of 2048 character lines. A warning is issued to stderr for ascii lines over the limit. No test is performed on binary sections.

Validation is performed in three ways levels: during the lexical scan, during the parse, and, if a dictionary was converted, against the value types, value enumerations, categories and parent-child relationships specified in the dictionary.

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

PROTOTYPE

#include "cbf.h"

int cbf_write_file (cbf_handle handle, FILE *file, int readable, int ciforcbf, int headers, int encoding);
int cbf_write_widefile (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, following CIF 1.0 conventions of 80 character lines. cbf_write_widefile writes the CBF object specified by handle into the file file, following CIF 1.1 conventions of 2048 character lines. A warning is issued to stderr for ascii lines over the limit, and an attempt is made to fold lines to fit. No test is performed on binary sections.

If a dictionary has been provided, aliases will be applied on output.

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, cbf_new_saveframe

PROTOTYPE

#include "cbf.h"

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

DESCRIPTION

cbf_new_datablock creates a new data block with name datablockname and makes it the current data block. cbf_new_saveframe creates a new save frame with name saveframename within the current data block and makes the new save frame the current save frame.

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

ARGUMENTS

  handle   CBF handle.

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe

PROTOTYPE

#include "cbf.h"

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

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. cbf_force_new_saveframe creates a new savew frame with name saveframename and makes it the current save frame. Duplicate save frame names are allowed.

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

ARGUMENTS

  handle   CBF handle.

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

RETURN VALUE

Returns an error code on failure or 0 for success.

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.

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.

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.

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.

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.

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.

2.3.13 cbf_set_datablockname, cbf_set_saveframename

PROTOTYPE

#include "cbf.h"

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

DESCRIPTION

cbf_set_datablockname changes the name of the current data block to datablockname. cbf_set_saveframename changes the name of the current save frame to saveframename.

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

ARGUMENTS

  handle   CBF handle.

  datablockname   The new data block name.

  datablockname   The new save frame name.

RETURN VALUE

Returns an error code on failure or 0 for success.

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.

2.3.15 cbf_reset_datablock, cbf_reset_datablock

PROTOTYPE

#include "cbf.h"

int cbf_reset_datablock (cbf_handle handle);
int cbf_reset_saveframe (cbf_handle handle);

DESCRIPTION

cbf_reset_datablock deletes all categories from the current data block. cbf_reset_saveframe deletes all categories from the current save frame.

ARGUMENTS

handle CBF handle.

RETURN VALUE

Returns an error code on failure or 0 for success.

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.

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.

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.

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.

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.

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, cbf_require_value

PROTOTYPE

#include "cbf.h"

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

DESCRIPTION

cbf_get_value sets *value to point to the ASCII value of the item at the current column and row. cbf_require_value sets *value to point to the ASCII value of the item at the current column and row, creating the data item if necessary and initializing it to a copy of defaultvalue.

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.

  defaultvalue   Default value character string.

RETURN VALUE

Returns an error code on failure or 0 for success.

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.

2.3.48 cbf_get_typeofvalue

PROTOTYPE

#include "cbf.h"

int cbf_get_typeofvalue (cbf_handle handle, const char **typeofvalue);

DESCRIPTION

cbf_get_value sets *typeofvalue to point an ASCII descriptor of the value of the item at the current column and row. The strings that may be returned are "null" for a null value indicated by a "." or a "?", "bnry" for a binary value, "word" for an unquoted string, "dblq" for a double-quoted string, "sglq" for a single-quoted string, and "text" for a semicolon-quoted text field. A field for which no value has been set sets *typeofvalue to NULL rather than to the string "null".

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

ARGUMENTS

handle CBF handle.

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

RETURN VALUE

Returns an error code on failure or 0 for success.

2.3.49 cbf_set_typeofvalue

PROTOTYPE

#include "cbf.h"

int cbf_set_typeofvalue (cbf_handle handle, const char *typeofvalue);

DESCRIPTION

cbf_set_typeofvalue sets the type of the item at the current column and row to the type specified by the ASCII character string given by typeofvalue. The strings that may be used are "null" for a null value indicated by a "." or a "?", "word" for an unquoted string, "dblq" for a double-quoted string, "sglq" for a single-quoted string, and "text" for a semicolon-quoted text field. Not all types may be used for all values. No changes may be made to the type of binary values. You may not set the type of a string that contains a single quote followed by a blank or a tab or which contains multiple lines to "sglq". You may not set the type of a string that contains a double quote followed by a blank or a tab or which contains multiple lines to "dblq".

ARGUMENTS

handle CBF handle.

typeofvalue ASCII string for desired type of value.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.3.50 cbf_get_integervalue, cbf_require_integervalue

PROTOTYPE

#include "cbf.h"

int cbf_get_integervalue (cbf_handle handle, int *number);
int cbf_require_integervalue (cbf_handle handle, int *number, int defaultvalue);

DESCRIPTION

cbf_get_integervalue sets *number to the value of the ASCII item at the current column and row interpreted as a decimal integer. cbf_require_integervalue sets *number to the value of the ASCII item at the current column and row interpreted as a decimal integer, setting it to defaultvalue if necessary.

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

ARGUMENTS

  handle   CBF handle.

  number   pointer to the number.

  defaultvalue   default number value.

RETURN VALUE

Returns an error code on failure or 0 for success.

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

2.3.52 cbf_get_doublevalue, cbf_require_doublevalue

PROTOTYPE

#include "cbf.h"

int cbf_get_doublevalue (cbf_handle handle, double *number);
int cbf_require_doublevalue (cbf_handle handle, double *number, double defaultvalue);

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. cbf_require_doublevalue sets *number to the value of the ASCII item at the current column and row interpreted as a decimal floating-point number, setting it to defaultvalue if necessary.

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

ARGUMENTS

  handle   CBF handle.

  number   Pointer to the destination number.

  defaultvalue   default number value.

RETURN VALUE

Returns an error code on failure or 0 for success.

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

2.3.54 cbf_get_integerarrayparameters,
cbf_get_integerarrayparameters_wdims, cbf_get_integerarrayparameters_wdims_fs, cbf_get_integerarrayparameters_wdims_sf, cbf_get_realarrayparameters,
cbf_get_realarrayparameters_wdims, cbf_get_realarrayparameters_wdims_fs, cbf_get_realarrayparameters_wdims_sf

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

int cbf_get_integerarrayparameters_wdims (cbf_handle handle, unsigned int *compression, int *binary_id, size_t *elsize, int *elsigned, int *elunsigned, size_t *elements, int *minelement, int *maxelement, const char **byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t *padding);
int cbf_get_integerarrayparameters_wdims_fs (cbf_handle handle, unsigned int *compression, int *binary_id, size_t *elsize, int *elsigned, int *elunsigned, size_t *elements, int *minelement, int *maxelement, const char **byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t *padding);
int cbf_get_integerarrayparameters_wdims_sf (cbf_handle handle, unsigned int *compression, int *binary_id, size_t *elsize, int *elsigned, int *elunsigned, size_t *elements, int *minelement, int *maxelement, const char **byteorder, size_t *dimslow, size_t *dimmid, size_t *dimfast, size_t *padding);

int cbf_get_realarrayparameters (cbf_handle handle, unsigned int *compression, int *binary_id, size_t *elsize, size_t *elements);

int cbf_get_realarrayparameters_wdims (cbf_handle handle, unsigned int *compression, int *binary_id, size_t *elsize, size_t *elements, const char **byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t *padding);
int cbf_get_realarrayparameters_wdims_fs (cbf_handle handle, unsigned int *compression, int *binary_id, size_t *elsize, size_t *elements, const char **byteorder, size_t *dimfast, size_t *dimmid, size_t *dimslow, size_t *padding);
int cbf_get_realarrayparameters_wdims_sf (cbf_handle handle, unsigned int *compression, int *binary_id, size_t *elsize, size_t *elements, const char **byteorder, size_t *dimslow, size_t *dimmid, size_t *dimfast, size_t *padding);

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 array is to be made into another CIF or CBF. cbf_get_realarrayparameters sets *compression, *binary_id, *elsize, *elements 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_realarray, if a copy of the arry is to be made into another CIF or CBF.

The variants cbf_get_integerarrayparameters_wdims, cbf_get_integerarrayparameters_wdims_fs, cbf_get_integerarrayparameters_wdims_sf, cbf_get_realarrayparameters_wdims, cbf_get_realarrayparameters_wdims_fs, cbf_get_realarrayparameters_wdims_sf set **byteorder, *dimfast, *dimmid, *dimslow, and *padding as well, providing the additional parameters needed for a subsequent call to cbf_set_integerarray_wdims or cbf_set_realarray_wdims.

The value returned in *byteorder is a pointer either to the string "little_endian" or to the string "big_endian". This should be the byte order of the data, not necessarily of the host machine. No attempt should be made to modify this string. At this time only "little_endian" will be returned.

The values returned in *dimfast, *dimmid and *dimslow are the sizes of the fastest changing, second fastest changing and third fastest changing dimensions of the array, if specified, or zero, if not specified.

The value returned in *padding is the size of the post-data padding, if any and if specified in the data header. The value is given as a count of octets.

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.

  byteorder   Pointer to the destination byte order.

  dimfast   Pointer to the destination fastest dimension.

  dimmid   Pointer to the destination second fastest dimension.

  dimslow   Pointer to the destination third fastest dimension.

  padding   Pointer to the destination padding size.

RETURN VALUE

Returns an error code on failure or 0 for success.

2.3.55 cbf_get_integerarray, cbf_get_realarray

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);
int cbf_get_realarray (cbf_handle handle, int *binary_id, void *array, size_t elsize, 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. cbf_get_realarray reads the binary value of the item at the current column and row into a real array. The array consists of elements elements of elsize bytes each, starting at array. *binary_id is set to the binary section identifier and *elements_read to the number of elements actually read.

If any element in the integer 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), for cbf_get_integerarray, or sizeof(double) or sizeof(float), for cbf_get_realarray 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. For cbf_get_realarray, only IEEE format is supported. No conversion to other floating point formats is done at this time.

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, cbf_require_value
2.3.48 cbf_get_typeofvalue
2.3.49 cbf_set_typeofvalue
2.3.50 cbf_get_integervalue, cbf_require_integervalue
2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
2.3.54 cbf_get_integerarrayparameters, cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters, cbf_get_realarrayparameters_wdims
2.3.56 cbf_set_integerarray, cbf_set_integerarray_wdims, cbf_set_realarray, cbf_set_realarray_wdims
2.3.62 cbf_require_column_value
2.3.63 cbf_require_column_integervalue
2.3.64 cbf_require_column_doublevalue

2.3.56 cbf_set_integerarray,
      cbf_set_integerarray_wdims, cbf_set_integerarray_wdims_fs, cbf_set_integerarray_wdims_sf,
      cbf_set_realarray,
      cbf_set_realarray_wdims, cbf_set_realarray_wdims_fs, cbf_set_realarray_wdims_sf

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

int cbf_set_integerarray_wdims (cbf_handle handle, unsigned int compression, int binary_id, void *array, size_t elsize, int elsigned, size_t elements, const char *byteorder, size_t dimfast, size_t dimmid, size_t dimslow, size_t padding);
int cbf_set_integerarray_wdims_fs (cbf_handle handle, unsigned int compression, int binary_id, void *array, size_t elsize, int elsigned, size_t elements, const char *byteorder, size_t dimfast, size_t dimmid, size_t dimslow, size_t padding);
int cbf_set_integerarray_wdims_sf (cbf_handle handle, unsigned int compression, int binary_id, void *array, size_t elsize, int elsigned, size_t elements, const char *byteorder, size_t dimslow, size_t dimmid, size_t dimfast, size_t padding);

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

int cbf_set_realarray_wdims (cbf_handle handle, unsigned int compression, int binary_id, void *array, size_t elsize, size_t elements, const char *byteorder, size_t dimfast, size_t dimmid, size_t dimslow, size_t padding);
int cbf_set_realarray_wdims_fs (cbf_handle handle, unsigned int compression, int binary_id, void *array, size_t elsize, size_t elements, const char *byteorder, size_t dimfast, size_t dimmid, size_t dimslow, size_t padding);
int cbf_set_realarray_wdims_sf (cbf_handle handle, unsigned int compression, int binary_id, void *array, size_t elsize, size_t elements, const char *byteorder, size_t dimslow, size_t dimmid, size_t dimfast, size_t padding);

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. cbf_set_realarray 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. binary_id is the binary section identifier.

The cbf_set_integerarray_wdims, cbf_set_integerarray_wdims_fs, cbf_set_integerarray_wdims_sf, cbf_set_realarray_wdims, cbf_set_realarray_wdims_fs and cbf_set_realarray_wdims_sf variants allow the data header values of byteorder, dimfast, dimmid, dimslow and padding to be set to the data byte order, the fastest, second fastest and third fastest array dimensions and the size in byte of the post data padding to be used.

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_PACKED_V2   CCP4-style packing, version 2 (section 3.3.2)
  CBF_BYTE_OFFSET   Simple "byte_offset" compression.
  CBF_NONE   No compression. NOTE: This scheme is by far the slowest of the four and uses much more disk space. It is intended for routine use with small arrays only. With large arrays (like images) it should be used only for debugging.

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), for cbf_set_integerarray, or IEEE doubles or floats for cbf_set_realarray. 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.

2.3.57 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.58 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.57 cbf_failnez

2.3.59 cbf_require_datablock

PROTOTYPE

#include "cbf.h"

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

DESCRIPTION

cbf_require_datablock makes the data block with name datablockname the current data block, if it exists, or creates it if it does not.

The comparison is case-insensitive.

The current category becomes undefined.

ARGUMENTS

handle CBF

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

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

MIME_HEADERS	Use MIME-type headers (default).
MIME_NOHEADERS	Use a simple ASCII headers.
MSG_DIGEST	Generate message digests for binary data validation.
MSG_NODIGEST	Do not generate message digests (default).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

CBFlib

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

Version History

Known Problems

Foreword

Contents

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.

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

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