File: CBFlib.html

package info (click to toggle)
cbflib 0.9.7%2Bdfsg1-5
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 65,272 kB
sloc: ansic: 131,361; python: 22,780; sh: 3,108; makefile: 2,088; yacc: 659; java: 223; f90: 214; xml: 210; cpp: 58
file content (14744 lines) | stat: -rw-r--r-- 607,832 bytes
parent folder | download | duplicates (2)
<HTML>
<HEAD>
<TITLE>CBFlib Manual</TITLE>
<style>
h1,
h2
{
	text-align: center;
}

h1,
h2,
h3,
h4
{
	color: #0808A0;
	font-weight: bold;
}

pre
{
	border: 1px solid grey;
	font-family: "", "monospace";
	padding: 0.5em;
	white-space: pre;
}

code
{
	font-family: "", "monospace";
	white-space: normal;
}

ul.mini-ToC
{
	list-style-type: none;
}

ul.see-also
{
	list-style-type: none;
	padding-left: 0;
}

table.hdf5-types
{
	border-collapse: collapse;
	margin: auto;
}

table.hdf5-types td
{
	border: 1px solid black;
	padding: 0.5em;
}

table.params
{
	border-collapse: separate;
	margin: 0;
	width: 100%;
}

table.params td
{
	border: none;
	padding: 0 0.5em;
}

table.params th
{
	font-weight: bold;
	padding: 0 0 0 0.5em;
}

table.params td.type,
table.params td.name
{
	font-family: "", "monospace";
}
</style>
</HEAD>
<body bgcolor="#FAFAFF" text="#000000"
BACKGROUND="../html_graphics/cbflibbackground.jpg">
<a href="http://www.iucr.org/iucr-top/welcome.html">
<img alt="[IUCr Home Page]" src="../html_graphics/iucrhome.jpg"></a>
<a href="http://www.iucr.org/iucr-top/cif/home.html">
<img alt="[CIF Home Page]" src="../html_graphics/cifhome.jpg"></a>
<A HREF="cbf_definition_rev.html"><IMG SRC="../html_graphics/CBFbutton.jpg"
ALT="[CBF/imgCIF]"></A>
<IMG SRC="../html_graphics/cbflibbutton.jpg">
<hr />
<CENTER>
| <a href="http://www.iucr.org/iucr-top/welcome.html">IUCr Home Page</a>
| <a href="http://www.iucr.org/iucr-top/cif/home.html">CIF Home Page</a>
| <A HREF="cbf_definition_rev.html">CBF/imgCIF</a>
| CBFlib
|<br />
| <A HREF = "CBFlib_NOTICES.html">NOTICE</A>
| <a href=gpl.txt>GPL</a>
| <a href=lgpl.txt>LGPL</a>
| <a href="cif_img_1.7.10.html">imgCIF dictionary</a>
|<br />
| <a href="http://arcib.dowling.edu/donation.shtml">Click Here to Make a Donation</a>
|<P>
<IMG  SRC="../html_graphics/cbflibbig.jpg" ALT="">
</CENTER>
<font color="#0808A0">
<H2 ALIGN=CENTER>CBFlib</H2>
<CENTER>
<b>An API for CBF/imgCIF<br />
Crystallographic Binary Files with ASCII Support</b><br />
Version 0.9.5<BR>
27 April 2014<BR>
rev 22 February 2015<br />
<p>
</CENTER>
</font><font color="#000000">
<p>
<CENTER>
by<br />
Paul J. Ellis<br />
Stanford Synchrotron Radiation Laboratory<br />
<p>
and<br />
Herbert J. Bernstein<br />
Bernstein + Sons<br />
<script language="javascript" type="text/javascript">
<!--
      var name = "yaya@";
      var domain = "bernstein-plus-sons";
      var domext = ".com";
      document.write ("<a href=\"mailto:" + name + domain + domext + "\">" + name + " <b>at</b> " + domain + " <b>dot</b> "+  domext+"</a>"); 
// -->
</script>
<noscript>
yaya <b>at</b> bernstein-plus-sons <b>dot</b> com
</noscript>
<p>
&#169; Copyright 2006, 2007, 2008, 2011, 2013, 2014 Herbert J. Bernstein
<P>
<hr />
<b>YOU MAY REDISTRIBUTE THE CBFLIB PACKAGE UNDER THE TERMS OF THE <a href=gpl.txt>GPL</a>.
<P>
 ALTERNATIVELY YOU MAY REDISTRIBUTE THE CBFLIB API UNDER THE TERMS
 OF THE <a href=lgpl.txt>LGPL<a/>.</b>

</CENTER>
<p>
<hr />
<H3 ALIGN=CENTER>
Before using this software, please read the <br />
<A HREF = "CBFlib_NOTICES.html"> <IMG SRC="../html_graphics/noticeButton.jpg" ALT="NOTICE"></A><br />
for important disclaimers and the IUCr Policy
 on the Use of the Crystallographic Information File (CIF) and for other important
information.
</h3>
<P>
   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.
    Recent work on integration among CBF, HDF5 and NeXus supported in part
    by Pandata ODI (EU 7th Framework Programme)
<p>
<hr />
</font><font color="#0808A0">
<h2 ALIGN=CENTER>Version History</H2>
</font><font color="#000000">
<p>
<TABLE>
<tr><th align="left">Version
<th align="left">Date<th align="left">By<th align="left">Description
<tr>
<td valign="top">&nbsp;&nbsp;0.1<td valign="top">&nbsp;&nbsp;Apr. 1998
<td valign="top">&nbsp;&nbsp;PJE
<td>&nbsp;&nbsp;This was the 
first CBFlib release.  It
supported binary CBF files using binary strings.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.2">0.2</a>
<td valign="top">&nbsp;&nbsp;Aug. 1998
<td valign="top">&nbsp;&nbsp;HJB<td>&nbsp;&nbsp;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.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.3">0.3</a>
<td valign="top">&nbsp;&nbsp;Sep. 1998
<td valign="top">&nbsp;&nbsp;PJE<td>&nbsp;&nbsp;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.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.4">0.4</a>
<td valign="top">&nbsp;&nbsp;Nov. 1998
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;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.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.5">0.5</a>
<td valign="top">&nbsp;&nbsp;Dec. 1998
<td valign="top">&nbsp;&nbsp;PJE<td>&nbsp;&nbsp;This release
greatly increased the speed of processing by allowing for deferred digest
evaluation.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.6">0.6</a>
<td valign="top">&nbsp;&nbsp;Jan. 1999
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;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.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.6.1">0.6.1</a>
<td valign="top">&nbsp;&nbsp;Feb. 2001
<td valign="top">&nbsp;&nbsp;HP (per HJB)
<td>&nbsp;&nbsp;This release
fixed a memory leak due to misallocation by size of cbf_handle instead of cbf_handle_struct
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7">0.7</a>
<td valign="top">&nbsp;&nbsp;Mar. 2001
<td valign="top">&nbsp;&nbsp;PJE
<td>&nbsp;&nbsp;This release
added high-level instructions based on the imgCIF dictionary
version 1.1.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.1">0.7.1</a>
<td valign="top">&nbsp;&nbsp;Mar. 2001
<td valign="top">&nbsp;&nbsp;PJE
<td>&nbsp;&nbsp;The high-level functions were revised to permit future expansion to
files with multiple images.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.2">0.7.2</a>
<td valign="top">&nbsp;&nbsp;Apr. 2001
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;This release
adjusted cbf_cimple.c to conform to cif_img.dic version 1.1.3
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.2.1">0.7.2.1</a>
<td valign="top">&nbsp;&nbsp;May 2001
<td valign="top">&nbsp;&nbsp;PJE
<td>&nbsp;&nbsp;This release
corrected an if nesting error in the prior mod to cbf_cimple.c.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.3">0.7.3</a>
<td valign="top">&nbsp;&nbsp;Oct. 2002
<td valign="top">&nbsp;&nbsp;PJE
<td>&nbsp;&nbsp;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).
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.4">0.7.4</a>
<td valign="top">&nbsp;&nbsp;Jan 2004
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;This release fixes a parse error for 
quoted strings, adds code to get and set character string types, and removes compiler warnings
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.5">0.7.5</a>
<td valign="top">&nbsp;&nbsp;Apr 2006
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;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.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.6">0.7.6</a>
<td valign="top">&nbsp;&nbsp;Jul 2006
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;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

<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.7">0.7.7</a>
<td valign="top">&nbsp;&nbsp;February 2007
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;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.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.7.1">0.7.7.1</a>
<td valign="top">&nbsp;&nbsp;February 2007
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;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.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.7.2">0.7.7.2</a>
<td valign="top">&nbsp;&nbsp;February 2007
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;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.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.7.3">0.7.7.3</a>
<td valign="top">&nbsp;&nbsp;April 2007
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;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.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.7.4">0.7.7.4</a>
<td valign="top">&nbsp;&nbsp;May 2007
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;Corrects in handling SLS
detector mincbfs and reorder dimensions versus arrays for some
f90 compilers as per H. Powell.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.7.5">0.7.7.5</a>
<td valign="top">&nbsp;&nbsp;May 2007
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;Fix to cbf_get_image for bug
reported by F. Remacle, fixes for windows builds as per J. Wright
and F. Remacle.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.7.6">0.7.7.6</a>
<td valign="top">&nbsp;&nbsp;Jun 2007
<td valign="top">&nbsp;&nbsp;HJB
<td>&nbsp;&nbsp;Fix to CBF byte-offset compression
writes, fix to Makefiles and m4 for f90 test programs to allow adjustable
record length.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.8">0.7.8</a>
<td valign="top">&nbsp;&nbsp;Jul 2007
<td valign="top">&nbsp;&nbsp;HJB<td>&nbsp;&nbsp;Release for full support of
SLS data files with updated convert_minicbf, and support for gfortran
from gcc 4.2.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.8.1">0.7.8.1</a><td
valign="top">&nbsp;&nbsp;Jul 2007<td
valign="top">&nbsp;&nbsp;HJB<td>&nbsp;&nbsp;Update to 0.7.8 release to fix
memory leaks reported by N. Sauter and to update validation checks
for recent changes.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.8.2">0.7.8.2</a><td
valign="top">&nbsp;&nbsp;Dec 2007<td
valign="top">&nbsp;&nbsp;CN, HJB<td>&nbsp;&nbsp;Update to 0.7.8.1 to add
ADSC jiffie by Chris Nielsen, and to add ..._fs and ..._sf macros.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.9">0.7.9</a><td
valign="top">&nbsp;&nbsp;Dec 2007<td
valign="top">&nbsp;&nbsp;CN, HJB<td>Identical to 0.7.8.2 except for
a cleanup of deprecated examples, e.g. diffrn_frame_data
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.7.9.1">0.7.9.1</a><td
valign="top">&nbsp;&nbsp;Jan 2008<td
valign="top">&nbsp;&nbsp;CN, HJB<td>&nbsp;&nbsp;Update to 0.7.8.2 to add
inverse ADSC jiffie by Chris Nielsen, to clean up problems in
handling maps for RasMol.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.8.0">0.8.0</a><td
valign="top">&nbsp;&nbsp;Jul 2008<td
valign="top">&nbsp;&nbsp;GT, HJB<td>&nbsp;&nbsp;Cleanup of 0.7.9.1 to start
0.8 series.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.8.1">0.8.1</a>
<td valign="top">&nbsp;&nbsp;Jul 2009
<td valign="top">&nbsp;&nbsp;EZ, CN, PC, GW, JH, HJB
<td>&nbsp;&nbsp;
Release with EZ's 2008 DDLm support using JH's PyCifRW, also
cbff f95 wrapper code, PC's java bindings.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.9.1">0.9.1</a><td
valign="top">&nbsp;&nbsp;Aug 2010<td
valign="top">&nbsp;&nbsp;PC, EE, JLM, NS, EZ, HJB<td>&nbsp;&nbsp;
Release with EE's Dectris template software,
also with vcif3, new arvai_test, sequence_match.
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.9.2">0.9.2</a></td>
<td valign="top">&nbsp;&nbsp;Feb 2011</td>
<td valign="top">&nbsp;&nbsp;PC, EE, JLM, NS, EZ, HJB<td>&nbsp;&nbsp;
New default release with updated pycbf, tiff support, removal of
default use of PyCifRW to avoid Fedora license issue.</td>
</tr>
<tr>
<td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.9.3">0.9.3</a></td>
<td valign="top">&nbsp;&nbsp;Oct 2013</td>
<td valign="top">&nbsp;&nbsp;JS, HJB</td>
<td>&nbsp;&nbsp;Added low-level 'cbf_H5*' functions for interacting with HDF5, higher level functions for converting CBF or miniCBF files to NeXus format, two utility programs to convert CBF or miniCBF files to NeXus format and some unit tests for the low-level 'cbf_H5*' functions.  Add initial FEL detector support.</td>
</tr>
    <tr>
        <td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.9.4">0.9.4</a></td>
        <td valign="top">&nbsp;&nbsp;March 2014</td>
        <td valign="top">&nbsp;&nbsp;JS, HJB</td>
        <td>&nbsp;&nbsp;Refactored implementation of the NXMX application defintion
            functional mapping with improvements to cmake support and a preliminary
            effort at handling Stokes polarization mapping.  This release had serious
            issues in the functional mapping axis mapping and should not be used for
            production involving NeXus files.
   </td>
    </tr>
    <tr>
        <td valign="top">&nbsp;&nbsp;<a href="ChangeLog.html#0.9.5">0.9.5</a></td>
        <td valign="top">&nbsp;&nbsp;April 2014</td>
        <td valign="top">&nbsp;&nbsp;HJB</td>
        <td>&nbsp;&nbsp;This is a production release for single detector module
        single crystal MX NeXus support.</td>
    </tr>
</TABLE>

<hr />
</font><font color="#0808A0">
<h2 ALIGN=CENTER>Known Problems</H2>
</font><font color="#000000">
<P>
The example program tiff2cbf needs the enviroment variable LD_LIBRARY_PATH
set to the location of the lib directory in CBFlib_0.9.2.11, unless
a system install of tiff-3.9.4-rev-6Feb11 has been done.
<p>
Due to license issues, PyCifRW is not included with default releases
of CBFlib.  Users can download PyCifRW separately.
<p>
There are some issues with Peter Chang's lastest java wrapper under
the CBFlib 0.9.2.11 release.  Until
they are resolved, the CBFlib 0.8.1 release should be used
for Java applications.
<p>
This version does not have support for predictor compression.
<p>
Code is needed to support array sub-sections.
</font><font color="#0808A0">
<h2 ALIGN=CENTER>Foreword</H2>
</font><font color="#000000">
<p>
In order to work with CBFlib, you need:
<P>
<ul>
<li>the source code, in the form
of a &quot;gzipped&quot; tar,
<A HREF="http://downloads.sf.net/cbflib/CBFlib_0.9.5.tar.gz">CBFlib_0.9.5.tar.gz</A>; and
<li>the test data:
<ul>
<li><A HREF="http://downloads.sf.net/cbflib/CBFlib_0.9.5_Data_Files_Input.tar.gz">CBFlib_0.9.5_Data_Files_Input.tar.gz</a>
(17 MB) a "gzipped" tar of the input data files needed to test the API;
<li><A HREF="http://downloads.sf.net/cbflib/CBFlib_0.9.5_Data_Files_Output.tar.gz">CBFlib_0.9.5_Data_Files_Output.tar.gz</a>
(36 MB) a "gzipped" tar of the output data files needed to test the API, or, if space is at a premium;
<li><A HREF="http://downloads.sf.net/cbflib/CBFlib_0.9.5_Data_Files_Output_Sigs_Only.tar.gz">CBFlib_0.9.5_Data_Files_Output_Sigs_Only.tar.gz</a>
(1 KB) is a "gzipped" tar of only the MD5 signatures of the output data files needed to test the API.
</ul>
</ul>
<P>
If your system has the program wget, you only need the source code.  The download of the other tar balls will be
handled automatically.
<P>
<b>Be careful about space.  A full build and test can use 450 MB or more.  If space is tight, be sure to read the
instructions below on using only the signatures of the test files.</b>
<P>
Uncompress and unpack :
<P>
<ul>
<li>gunzip &lt; CBFlib_0.9.5.tar.gz | tar xvf -
</ul>
<P>   
<p>
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.9.2.11_Data_Files_Input.  Do
not download copies into the top level directory.
<P>
In addition, the kit will need tiff and hdf5 libraries.
<p>

Thare are various sample Makefiles for common
configurations.  The Makefile_OSX
samples is for systems with gfortran from prior to
the release of gcc 4.2.  For the most recent gfortran,
use Makefile_OSX_gcc42.  All
the Makefiles are generated from m4/Makefile.m4.
For newer OS X systems, the default Makefile should work.
<p>
<B>The Makefiles use GNU make constructs, such as ifeq
and ifneq.  If you need to use a different version of
make, you will need to edit out the conditionals</b>
<p>
The operation of the Makefiles is sensitive to the
following environment variables:
<p>
<ul>
<li><b>CBFLIB_USE_PYCIFRW</b> If you define this environment variable,
you may rebuild the Makefiles to include James Hester's PyCifRW.  The
process under bash is:<p>
<pre>
export CBFLIB_USE_PYCIFRW=yes
cd CBFlib_0.9.5
touch m4/Makefile.m4
make Makefiles
</pre>
</li>
<li><b>CBF_DONT_USE_LONG_LONG</b> If you define this environment variable,
use of the <tt>long long</tt> data type in CBFlib is replaced by
use of a struct.  The Makefiles do not need to be rebuilt.  Makefile_MINGW
does not use the <tt>long long</tt> data type even without defining
this variable.
</li>

<li><b>NOFORTRAN</b> If you define this environment variable,
use of the fortran compiler is suppressed.
</li>


</ul>

<p>


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
<p>
<b>make all</b><br />
<b>make tests</b>
<P>
or, if space is at a premium:
<p>
<p>
<b>make all</b><br />
<b>make tests_sigs_only</b>
<P>
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
<P>

<p>
We have included examples of
CBF/imgCIF files produced by CBFlib in the test data 
<A HREF="http://downloads.sf.net/cbflib/CBFlib_0.9.5_Data_Files_Output.tar.gz">CBFlib_0.9.5_Data_Files_Output.tar.gz</a>,
the current best draft of
the 
<A HREF="cif_img_1.7.10.html">CBF Extensions Dictionary</A>,
and of Andy Hammersley's CBF definition, updated to become a 
<A HREF="cbf_definition_rev.html">
DRAFT CBF/ImgCIF DEFINITION</A>.
<p>
CBFlib 0.9.5 includes a program, tiff2cbf, to convert from tiff files
to CBF files, that requires an augmented version of tiff-3.9.4 called 
tiff-3.9.4-rev-6Feb11, that installs into the CBFlib_0.9.2.11 directory.
If a system copy is desired, download and install
<a href="http://downloads.sf.net/cbflib/tiff-3.9.4-rev-6Feb11.tar.gz">
http://downloads.sf.net/cbflib/tiff-3.9.4-rev-6Feb11.tar.gz</a>
<hr />


</font><font color="#0808A0">
<H2 ALIGN=CENTER>Contents</H2>
</font><font color="#000000">
<p>
<UL>
<LI><A HREF="#1. Introduction">1.   Introduction</A>
<LI><A HREF="#2.">2.  Function descriptions</A>
  <UL>
    <LI><A HREF="#2.1">2.1  General description</A>
    <UL>
      <LI><A HREF="#2.1.1">2.1.1   CBF handles</A>
      <LI><A HREF="#2.1.2">2.1.2   CBF goniometer handles</A>
      <LI><A HREF="#2.1.3">2.1.3   CBF detector handles</A>
      <LI><A HREF="#2.1.4">2.1.4   CBF positioner handles</A>
      <LI><A HREF="#2.1.5">2.1.5   Return values</A>
    </UL>
    <LI><A HREF="#2.2">2.2   Reading and writing files containing binary sections</A>
    <UL>
      <LI><A HREF="#2.2.1">2.2.1   Reading binary sections</A>
      <LI><A HREF="#2.2.2">2.2.2   Writing binary sections</A>
      <LI><A HREF="#2.2.3">2.2.3   Summary of reading and writing files containing binary sections</A>
      <LI><A HREF="#2.2.4">2.2.4   Ordering of array indices</A>
    </UL>
    <LI><A HREF="#2.3">2.3   Low-level function prototypes</A>
    <UL>
      <LI><A HREF="#2.3.1">2.3.1   cbf_make_handle</A>
      <LI><A HREF="#2.3.2">2.3.2   cbf_free_handle</A>
      <LI><A HREF="#2.3.3">2.3.3   cbf_read_file, cbf_read_widefile</A>
      <LI><a href="#2.3.4">2.3.4   cbf_write_file, cbf_write_widefile</a>
      <LI><A HREF="#2.3.5">2.3.5   cbf_new_datablock, cbf_new_saveframe</A>
      <LI><A HREF="#2.3.6">2.3.6   cbf_force_new_datablock, cbf_force_new_saveframe</A>
      <LI><A HREF="#2.3.7">2.3.7   cbf_new_category</A>
      <LI><A HREF="#2.3.8">2.3.8   cbf_force_new_category</A>
      <LI><A HREF="#2.3.9">2.3.9   cbf_new_column</A>
      <LI><A HREF="#2.3.10">2.3.10   cbf_new_row</A>
      <LI><A HREF="#2.3.11">2.3.11   cbf_insert_row</A>
      <LI><A HREF="#2.3.12">2.3.12   cbf_delete_row</A>
      <LI><A HREF="#2.3.13">2.3.13   cbf_set_datablockname, cbf_set_saveframename</A>
      <LI><A HREF="#2.3.14">2.3.14   cbf_reset_datablocks</A>
      <LI><A HREF="#2.3.15">2.3.15   cbf_reset_datablock, cbf_reset_saveframe</A>
      <LI><A HREF="#2.3.16">2.3.16   cbf_reset_category</A>
      <LI><A HREF="#2.3.17">2.3.17   cbf_remove_datablock, cbf_remove_saveframe</A>
      <LI><A HREF="#2.3.18">2.3.18   cbf_remove_category</A>
      <LI><A HREF="#2.3.19">2.3.19   cbf_remove_column</A>
      <LI><A HREF="#2.3.20">2.3.20   cbf_remove_row</A>
      <LI><A HREF="#2.3.21">2.3.21   cbf_rewind_datablock</A>
      <LI><A HREF="#2.3.22">2.3.22   cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem</A>
      <LI><A HREF="#2.3.23">2.3.23   cbf_rewind_column</A>
      <LI><A HREF="#2.3.24">2.3.24   cbf_rewind_row</A>
      <LI><A HREF="#2.3.25">2.3.25   cbf_next_datablock</A>
      <LI><A HREF="#2.3.26">2.3.26   cbf_next_category, cbf_next_saveframe, cbf_next_blockitem</A>
      <LI><A HREF="#2.3.27">2.3.27   cbf_next_column</A>
      <LI><A HREF="#2.3.28">2.3.28   cbf_next_row</A>
      <LI><A HREF="#2.3.29">2.3.29   cbf_find_datablock</A>
      <LI><A HREF="#2.3.30">2.3.30   cbf_find_category, cbf_find_saveframe, cbf_find_blockitem</A>
      <LI><A HREF="#2.3.31">2.3.31   cbf_find_column</A>
      <LI><A HREF="#2.3.32">2.3.32   cbf_find_row</A>
      <LI><A HREF="#2.3.33">2.3.33   cbf_find_nextrow</A>
      <LI><A HREF="#2.3.34">2.3.34   cbf_count_datablocks</A>
      <LI><A HREF="#2.3.35">2.3.35   cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems</A>
      <LI><A HREF="#2.3.36">2.3.36   cbf_count_columns</A>
      <LI><A HREF="#2.3.37">2.3.37   cbf_count_rows</A>
      <LI><A HREF="#2.3.38">2.3.38   cbf_select_datablock</A>
      <LI><A HREF="#2.3.39">2.3.39   cbf_select_category, cbf_select_saveframe, cbf_select_blockitem</A>
      <LI><A HREF="#2.3.40">2.3.40   cbf_select_column</A>
      <LI><A HREF="#2.3.41">2.3.41   cbf_select_row</A>
      <LI><A HREF="#2.3.42">2.3.42   cbf_datablock_name</A>
      <LI><A HREF="#2.3.43">2.3.43   cbf_category_name</A>
      <LI><A HREF="#2.3.44">2.3.44   cbf_column_name, cbf_set_column_name</A>
      <LI><A HREF="#2.3.45">2.3.45   cbf_row_number</A>
      <LI><A HREF="#2.3.46">2.3.46   cbf_get_value, cbf_require_value</A>
      <LI><A HREF="#2.3.47">2.3.47   cbf_set_value</A>
      <LI><A HREF="#2.3.48">2.3.48   cbf_get_typeofvalue</A>
      <LI><A HREF="#2.3.49">2.3.49   cbf_set_typeofvalue</A>
      <LI><A HREF="#2.3.50">2.3.50   cbf_get_integervalue, cbf_require_integervalue</A>
      <LI><A HREF="#2.3.51">2.3.51   cbf_set_integervalue</A>
      <LI><A HREF="#2.3.52">2.3.52   cbf_get_doublevalue, cbf_require_doublevalue</A>
      <LI><A HREF="#2.3.53">2.3.53   cbf_set_doublevalue</A>
      <LI><A HREF="#2.3.54">2.3.54   cbf_get_integerarrayparameters,</a><br />
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.3.54">cbf_get_integerarrayparameters_wdims, cbf_get_integerarrayparameters_wdims_fs, cbf_get_integerarrayparameters_wdims_sf</a><br />
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.3.54">cbf_get_realarrayparameters,</a><br />
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.3.54">cbf_get_realarrayparameters_wdims, cbf_get_realarrayparameters_wdims_fs, cbf_get_realarrayparameters_wdims_sf</A>
      <LI><A HREF="#2.3.55">2.3.55   cbf_get_integerarray, cbf_get_realarray</A>
      <LI><A HREF="#2.3.56">2.3.56   cbf_set_integerarray,</a><br />
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.3.56">cbf_set_integerarray_wdims, cbf_set_integerarray_wdims_fs, cbf_set_integerarray_wdims_sf,</a><br />
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.3.56">cbf_set_realarray,</a><br />
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.3.56">cbf_set_realarray_wdims, cbf_set_realarray_wdims_fs, cbf_set_realarray_wdims_sf</A>
      <LI><A HREF="#2.3.57">2.3.57   cbf_failnez</A>
      <LI><A HREF="#2.3.58">2.3.58   cbf_onfailnez</A>
      <LI><A HREF="#2.3.59">2.3.59   cbf_require_datablock</A>
      <LI><A HREF="#2.3.60">2.3.60   cbf_require_category</A>
      <LI><A HREF="#2.3.61">2.3.61   cbf_require_column</A>
      <LI><A HREF="#2.3.62">2.3.62   cbf_require_column_value</A>
      <LI><A HREF="#2.3.63">2.3.63   cbf_require_column_integervalue</A>
      <LI><A HREF="#2.3.64">2.3.64   cbf_require_column_doublevalue</A>
      <LI><A HREF="#2.3.65">2.3.65   cbf_get_local_integer_byte_order,
       cbf_get_local_real_byte_order, cbf_get_local_real_format</A>
      <LI><A HREF="#2.3.66">2.3.66   cbf_get_dictionary, cbf_set_dictionary, cbf_require_dictionary</A>
      <LI><A HREF="#2.3.67">2.3.67   cbf_convert_dictionary</A>
      <LI><A HREF="#2.3.68">2.3.68   cbf_find_tag, cbf_find_local_tag</A>
      <LI><A HREF="#2.3.69">2.3.69   cbf_find_category_root, cbf_set_category_root, cbf_require_category_root</A>
      <LI><A HREF="#2.3.70">2.3.70   cbf_find_tag_root, cbf_set_tag_root, cbf_require_tag_root</A>
      <LI><A HREF="#2.3.71">2.3.71   cbf_find_tag_category, cbf_set_tag_category</A>


    </UL>
	<LI><A HREF="#2.4">2.4 High-level function prototypes (new for version 0.7)</a>
	<UL>
	  <LI><A HREF="#2.4.1">2.4.1 cbf_read_template</a>
	  <LI><A HREF="#2.4.2">2.4.2 cbf_get_diffrn_id, cbf_require_diffrn_id</a>
	  <LI><A HREF="#2.4.3">2.4.3 cbf_set_diffrn_id</a>
	  <LI><A HREF="#2.4.4">2.4.4 cbf_get_crystal_id</a>
	  <LI><A HREF="#2.4.5">2.4.5 cbf_set_crystal_id</a>
	  <LI><A HREF="#2.4.6">2.4.6 cbf_get_wavelength</a>
	  <LI><A HREF="#2.4.7">2.4.7 cbf_set_wavelength</a>
	  <LI><A HREF="#2.4.8">2.4.8 cbf_get_polarization</a>
	  <LI><A HREF="#2.4.9">2.4.9 cbf_set_polarization</a>
	  <LI><A HREF="#2.4.10">2.4.10 cbf_get_divergence</a>
	  <LI><A HREF="#2.4.11">2.4.11 cbf_set_divergence</a>
	  <LI><A HREF="#2.4.12">2.4.12 cbf_count_elements</a>
	  <LI><A HREF="#2.4.13">2.4.13 cbf_get_element_number, cbf_get_element_id</a>
	  <LI><A HREF="#2.4.14">2.4.14 cbf_get_gain</a>
	  <LI><A HREF="#2.4.15">2.4.15 cbf_set_gain</a>
	  <LI><A HREF="#2.4.16">2.4.16 cbf_get_overload</a>
	  <LI><A HREF="#2.4.17">2.4.17 cbf_set_overload</a>
	  <LI><A HREF="#2.4.18">2.4.18 cbf_get_integration_time</a>
	  <LI><A HREF="#2.4.19">2.4.19 cbf_set_integration_time</a>
	  <LI><A HREF="#2.4.20">2.4.20 cbf_get_time</a>
	  <LI><A HREF="#2.4.21">2.4.21 cbf_set_time</a>
	  <LI><A HREF="#2.4.22">2.4.22 cbf_get_date</a>
	  <LI><A HREF="#2.4.23">2.4.23 cbf_set_date</a>
	  <LI><A HREF="#2.4.24">2.4.24 cbf_set_current_time</a>
	  <LI><a HREF="#2.4.25">2.4.25 cbf_get_image_size, cbf_get_image_size_fs, cbf_get_image_size_fs,</a><br />
	    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.4.25">cbf_get_3d_image_size, cbf_get_3d_image_size_fs, cbf_get_3d_image_size_sf</a>
	  <LI><A HREF="#2.4.26">2.4.26 cbf_get_image, cbf_get_image_fs, cbf_get_image_sf,</a><br />
	    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.4.26">cbf_get_real_image, cbf_get_real_image_fs, cbf_get_real_image_sf,</a><br />
	    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.4.26">cbf_get_3d_image, cbf_get_3d_image_fs, cbf_get_3d_image_sf,</a><br />
	    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.4.26">cbf_get_real_3d_image, cbf_get_real_3d_image_fs, cbf_get_real_3d_image_sf</a>
	  <LI><A HREF="#2.4.27">2.4.27 cbf_set_image, cbf_set_image_fs, cbf_set_image_sf,</a><br />
	    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.4.27">cbf_set_real_image, cbf_set_real_image_fs, cbf_set_real_image_sf,</a><br />
	    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.4.27">cbf_set_3d_image, cbf_set_3d_image, cbf_set_3d_image,</a><br>
	    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.4.27">cbf_set_real_3d_image, cbf_set_real_3d_image_fs, cbf_set_real_3d_image_sf</a>
          <LI><A HREF="#2.4.28">2.4.28 cbf_get_axis_ancestor,
              cbf_get_axis_depends_on,
              cbf_get_axis_equipment,
              cbf_get_axis_equipment_component,
              cbf_get_axis_offset,
              cbf_get_axis_rotation,
              cbf_get_axis_rotation_axis,
              cbf_get_axis_setting,
              cbf_get_axis_type,
              cbf_get_axis_vector</a>
	  <LI><A HREF="#2.4.29">2.4.29 cbf_set_axis_setting</a>
	  <LI><A HREF="#2.4.30">2.4.30 cbf_construct_goniometer</a>
	  <LI><A HREF="#2.4.31">2.4.31 cbf_free_goniometer</a>
	  <LI><A HREF="#2.4.32">2.4.32 cbf_get_rotation_axis</a>
	  <LI><A HREF="#2.4.33">2.4.33 cbf_get_rotation_range</a>
	  <LI><A HREF="#2.4.34">2.4.34 cbf_rotate_vector</a>
	  <LI><A HREF="#2.4.35">2.4.35 cbf_get_reciprocal</a>
	  <LI><A HREF="#2.4.36">2.4.36 cbf_construct_detector, cbf_construct_reference_detector, cbf_require_reference_detector</a>
	  <LI><A HREF="#2.4.37">2.4.37 cbf_free_detector</a>
      <LI><A HREF="#2.4.38">2.4.38 cbf_construct_positioner, cbf_construct_reference_positioner</a>
	  <LI><A HREF="#2.4.39">2.4.39 cbf_free_positioner</a>
	  <LI><A HREF="#2.4.40">2.4.40 cbf_get_beam_center, cbf_get_beam_center_fs, cbf_get_beam_center_sf,</a><br />
	    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.4.40">cbf_set_beam_center, cbf_set_beam_center_fs, cbf_set_beam_center_sf,</a><br />
	    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#2.4.40">cbf_set_reference_beam_center, cbf_set_reference_beam_center_fs, cbf_set_reference_beam_center_sf</a>
	  <LI><A HREF="#2.4.41">2.4.41 cbf_get_detector_distance</a>
	  <LI><A HREF="#2.4.42">2.4.42 cbf_get_detector_normal</a>
      <LI><A HREF="#2.4.43">2.4.43 cbf_get_detector_axis_slow, cbf_get_detector_axis_fast, cbf_get_detector_axes, cbf_get_detector_axes_fs, cbf_get_detector_axes_sf,
          cbf_get_detector_surface_axes
	  <LI><A HREF="#2.4.44">2.4.44 cbf_get_pixel_coordinates, cbf_get_pixel_coordinates_fs, cbf_get_pixel_coordinates_sf</a>
	  <LI><A HREF="#2.4.45">2.4.45 cbf_get_pixel_normal, cbf_get_pixel_normal_fs, cbf_get_pixel_normal_sf</a>
	  <LI><A HREF="#2.4.46">2.4.46 cbf_get_pixel_area, cbf_get_pixel_area_fs, cbf_get_pixel_area_sf</a>
	  <LI><A HREF="#2.4.47">2.4.47 cbf_get_pixel_size, cbf_get_pixel_size_fs, cbf_get_pixel_size_sf</a>
	  <LI><A HREF="#2.4.48">2.4.48 cbf_set_pixel_size, cbf_set_pixel_size_fs, cbf_set_pixel_size_sf</a>
	  <LI><A HREF="#2.4.49">2.4.49 cbf_get_inferred_pixel_size, cbf_get_inferred_pixel_size_fs, cbf_get_inferred_pixel_size_sf</a>
	  <LI><A HREF="#2.4.50">2.4.50 cbf_get_unit_cell</a>
	  <LI><A HREF="#2.4.51">2.4.51 cbf_set_unit_cell</a>
	  <LI><A HREF="#2.4.52">2.4.52 cbf_get_reciprocal_cell</a>
	  <LI><A HREF="#2.4.53">2.4.53 cbf_set_reciprocal_cell</a>
	  <LI><A HREF="#2.4.54">2.4.54 cbf_compute_cell_volume</a>
	  <LI><A HREF="#2.4.55">2.4.55 cbf_compute_reciprocal_cell</a>
      <LI><A HREF="#2.4.56">2.4.56 cbf_get_orientation_matrix, cbf_set_orientation_matrix</a>
      <LI><A HREF="#2.4.57">2.4.57 cbf_get_bin_sizes, cbf_set_bin_sizes</a>
      <LI><A HREF="#2.4.58">2.4.58 cbf_get_axis_poise, cbf_get_goniometer_poise, cbf_get_axis_reference_poise</a>
      <LI><A HREF="#2.4.59">2.4.59 cbf_airy_disk, cbf_airy_disk_volume</a>
    </UL>
    <LI><A HREF="#2.5">2.5   F90 function interfaces</A>
    <UL>
      <LI><A HREF="#2.5.1">2.5.1 FCB_ATOL_WCNT</a>
      <LI><A HREF="#2.5.2">2.5.2 FCB_CI_STRNCMPARR</a>
      <LI><A HREF="#2.5.3">2.5.3 FCB_EXIT_BINARY</a>
      <LI><A HREF="#2.5.4">2.5.4 FCB_NBLEN_ARRAY</a>
      <LI><A HREF="#2.5.5">2.5.5 FCB_NEXT_BINARY</a>
      <LI><A HREF="#2.5.6">2.5.6 FCB_OPEN_CIFIN</a>
      <LI><A HREF="#2.5.7">2.5.7 FCB_PACKED: FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2, FCB_DECOMPRESS_PACKED_3D_I4</a>
      <LI><A HREF="#2.5.8">2.5.8 FCB_READ_BITS</a>
      <LI><A HREF="#2.5.9">2.5.9 FCB_READ_BYTE</a>
      <LI><A HREF="#2.5.10">2.5.10 FCB_READ_IMAGE_I2, FCB_READ_IMAGE_I4, FCB_READ_IMAGE_3D_I2, FCB_READ_IMAGE_3D_I4</a>
      <LI><A HREF="#2.5.11">2.5.11 FCB_READ_LINE</a>
      <LI><A HREF="#2.5.12">2.5.12 FCB_READ_XDS_I2</a>
      <LI><A HREF="#2.5.13">2.5.13 FCB_SKIP_WHITESPACE</a>
    </UL>
        <li>
          <a href="#2.6">2.6 HDF5 abstraction layer and convenience functions</a>
			<ul>
            <li>
              <a href="#2.6.1">2.6.1 cbf_H5Acreate</a>
            </li>
            <li>
              <a href="#2.6.2">2.6.2 cbf_H5Afind</a>
            </li>
            <li>
              <a href="#2.6.3">2.6.3 cbf_H5Aread</a>
            </li>
            <li>
              <a href="#2.6.4">2.6.4 cbf_H5Aread_string</a>
            </li>
            <li>
              <a href="#2.6.5">2.6.5 cbf_H5Awrite</a>
            </li>
            <li>
              <a href="#2.6.6">2.6.6 cbf_H5Arequire_cmp2</a>
            </li>
            <li>
              <a href="#2.6.7">2.6.7 cbf_H5Arequire_cmp2_ULP</a>
            </li>
            <li>
              <a href="#2.6.8">2.6.8 cbf_H5Arequire_string</a>
            </li>
            <li>
              <a href="#2.6.9">2.6.9 cbf_H5Afree</a>
            </li>
            <li>
              <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
            </li>
            <li>
              <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
            </li>
            <li>
              <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
            </li>
            <li>
              <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
            </li>
            <li>
              <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
            </li>
            <li>
              <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
            </li>
            <li>
              <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
            </li>
            <li>
              <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
            </li>
            <li>
              <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
            </li>
            <li>
              <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
            </li>
            <li>
              <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
            </li>
            <li>
              <a href="#2.6.21">2.6.21 cbf_H5Fopen</a>
            </li>
            <li>
              <a href="#2.6.22">2.6.22 cbf_H5Fclose</a>
            </li>
            <li>
              <a href="#2.6.23">2.6.23 cbf_H5Gcreate</a>
            </li>
            <li>
              <a href="#2.6.24">2.6.24 cbf_H5Gfind</a>
            </li>
            <li>
              <a href="#2.6.25">2.6.25 cbf_H5Grequire</a>
            </li>
            <li>
              <a href="#2.6.26">2.6.26 cbf_H5Gfree</a>
            </li>
            <li>
              <a href="#2.6.27">2.6.27 cbf_H5Ivalid</a>
            </li>
            <li>
              <a href="#2.6.28">2.6.28 cbf_H5Ocmp</a>
            </li>
            <li>
              <a href="#2.6.29">2.6.29 cbf_H5Ofree</a>
            </li>
            <li>
              <a href="#2.6.30">2.6.30 cbf_H5Screate</a>
            </li>
            <li>
              <a href="#2.6.31">2.6.31 cbf_H5Sfree</a>
            </li>
            <li>
              <a href="#2.6.32">2.6.32 cbf_H5Tcreate_string</a>
            </li>
            <li>
              <a href="#2.6.33">2.6.33 cbf_H5Tfree</a>
            </li>
			</ul>
  		</li>
        <li>
          <a href="#2.7">2.7 High-level NeXus-related functions</a>
			<ul>
            <li>
              <a href="#2.7.1">2.7.1 cbf_h5handle_get_file</a>
            </li>
            <li>
              <a href="#2.7.2">2.7.2 cbf_h5handle_set_file</a>
            </li>
            <li>
              <a href="#2.7.3">2.7.3 cbf_h5handle_get_entry</a>
            </li>
            <li>
              <a href="#2.7.4">2.7.4 cbf_h5handle_set_entry</a>
            </li>
            <li>
              <a href="#2.7.5">2.7.5 cbf_h5handle_require_entry</a>
            </li>
            <li>
              <a href="#2.7.6">2.7.6 cbf_h5handle_require_entry_definition</a>
            </li>
            <li>
              <a href="#2.7.7">2.7.7 cbf_h5handle_get_sample</a>
            </li>
            <li>
              <a href="#2.7.8">2.7.8 cbf_h5handle_set_sample</a>
            </li>
            <li>
              <a href="#2.7.9">2.7.9 cbf_h5handle_require_sample</a>
            </li>
            <li>
              <a href="#2.7.10">2.7.10 cbf_h5handle_get_beam</a>
            </li>
            <li>
              <a href="#2.7.11">2.7.11 cbf_h5handle_set_beam</a>
            </li>
            <li>
              <a href="#2.7.12">2.7.12 cbf_h5handle_require_beam</a>
            </li>
            <li>
              <a href="#2.7.13">2.7.13 cbf_h5handle_get_instrument</a>
            </li>
            <li>
              <a href="#2.7.14">2.7.14 cbf_h5handle_set_instrument</a>
            </li>
            <li>
              <a href="#2.7.15">2.7.15 cbf_h5handle_find_instrument</a>
            </li>
            <li>
              <a href="#2.7.16">2.7.16 cbf_h5handle_require_instrument</a>
            </li>
            <li>
              <a href="#2.7.17">2.7.17 cbf_h5handle_get_detector</a>
            </li>
            <li>
              <a href="#2.7.18">2.7.18 cbf_h5handle_set_detector</a>
            </li>
            <li>
              <a href="#2.7.19">2.7.19 cbf_h5handle_find_detector</a>
            </li>
            <li>
              <a href="#2.7.20">2.7.20 cbf_h5handle_require_detector</a>
            </li>
            <li>
              <a href="#2.7.21">2.7.21 cbf_h5handle_get_goniometer</a>
            </li>
            <li>
              <a href="#2.7.22">2.7.22 cbf_h5handle_set_goniometer</a>
            </li>
            <li>
              <a href="#2.7.23">2.7.23 cbf_h5handle_require_goniometer</a>
            </li>
            <li>
              <a href="#2.7.24">2.7.24 cbf_h5handle_get_monochromator</a>
            </li>
            <li>
              <a href="#2.7.25">2.7.25 cbf_h5handle_set_monochromator</a>
            </li>
            <li>
              <a href="#2.7.26">2.7.26 cbf_h5handle_require_monochromator</a>
            </li>
            <li>
              <a href="#2.7.27">2.7.27 cbf_h5handle_get_source</a>
            </li>
            <li>
              <a href="#2.7.28">2.7.28 cbf_h5handle_set_source</a>
            </li>
            <li>
              <a href="#2.7.29">2.7.29 cbf_h5handle_require_source</a>
            </li>
            <li>
              <a href="#2.7.30">2.7.30 cbf_free_h5handle</a>
            </li>
            <li>
              <a href="#2.7.31">2.7.31 cbf_create_h5handle3</a>
            </li>
            <li>
              <a href="#2.7.32">2.7.32 cbf_write_cbf_h5file</a>
            </li>
            <li>
              <a href="#2.7.33">2.7.33 cbf_write_cbf2nx</a>
            </li>
            <li>
              <a href="#2.7.34">2.7.34 cbf_write_minicbf_h5file</a>
            </li>
            <li>
              <a href="#2.7.35">2.7.35 cbf_write_nx2cbf</a>
            </li>
            <li>
              <a href="#2.7.36">2.7.36 cbf_config_create</a>
            </li>
            <li>
              <a href="#2.7.37">2.7.37 cbf_config_parse</a>
            </li>
            <li>
              <a href="#2.7.38">2.7.38 cbf_config_free</a>
            </li>
            <li>
              <a href="#2.7.39">2.7.39 cbf_config_strerror</a>
            </li>
			</ul>
  		</li>
</UL>
<LI><A HREF="#3.">3.   File format</A>
<UL>
  <LI><A HREF="#3.1">3.1   General description</A>
  <LI><A HREF="#3.2">3.2   Format of the binary sections</A>
  <UL>
    <LI><A HREF="#3.2.1">3.2.1   Format of imgCIF binary sections
    <LI><A HREF="#3.2.2">3.2.2   Format of CBF binary sections
  </UL>
  <LI><A HREF="#3.3">3.3   Compression schemes</A>
  <UL>
    <LI><A HREF="#3.3.1">3.3.1   Canonical-code compression</A>
    <LI><A HREF="#3.3.2">3.3.2   CCP4-style compression</A>
    <LI><A HREF="#3.3.3">3.3.3   Byte_offset compression</A>
    <LI><A HREF="#3.3.4">3.3.4   Nibble_offset compression</A>
  </UL>
  <LI><A HREF="#3.4">3.4   Access to CBFlib compressions from HDF5</A>

</UL>
<LI><A HREF="#4.">4.   Installation</A>
<LI><A HREF="#5.">5.   Example programs</A>
</UL>
<p>


<h3><A NAME="1.">1.  Introduction</A></h3>
<p>
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.
<p>
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.
<p>

<h3><A NAME="2.">2.  Function descriptions</A></h3>

<h4><a NAME="2.1">2.1  General description</a></h4>
<p>
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).

<p>
All functions return an integer
equal to 0 for success or an error code for failure.<br />
<p>
<h4><a NAME="2.1.1">2.1.1  CBF handles</a></h4>
<p>
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.
<p>
All functions in the library except cbf_make_handle expect a value of type cbf_handle
as the first argument.
<p>
The function <b>cbf_make_handle</b> creates and initializes a new CBF handle.
<p>
The function <b>cbf_free_handle</b> destroys a handle and frees all memory associated with
the corresponding CBF object.<br />
<p>



<h4><a NAME="2.1.2">2.1.2 CBF goniometer handles</a></h4>
<p>
To represent the goniometer used to orient a sample, CBFlib uses a value of
type cbf_goniometer.
<p>
A goniometer object is created and initialized from a CBF object using the
function <b>cbf_construct_goniometer</b>.
<p>
The function <b>cbf_free_goniometer</b> destroys a goniometer handle and frees
all memory associated with the corresponding object.
<p>



<h4><a NAME="2.1.3">2.1.3 CBF detector handles</a></h4>
<p>
To represent a detector surface mounted on a positioning system, CBFlib
uses a value of type cbf_detector.
<p>
A goniometer object is created and initialized from a CBF object using
one of the functions <b>cbf_construct_detector</b>, 
<b>cbf_construct_reference_detector</b> or <b>cbf_require_reference_detector</b>.
<p>
The function <b>cbf_free_detector</b> destroys a detector handle and frees
all memory associated with the corresponding object.

<p>

<h4><a NAME="2.1.4">2.1.4 CBF positioner handles</a></h4>
<p>
To represent an arbitrary positioning system designated by the terminal axis, 
CBFlib uses a value of type cbf_positioner.
<p>
A positioner object is created and initialized from a CBF object using
one of the functions <b>cbf_construct_positioner</b>, 
<b>cbf_construct_reference_positioner</b> or <b>cbf_require_reference_positioner</b>.
<p>
The function <b>cbf_free_positioner</b> destroys a positioner handle and frees
all memory associated with the corresponding object.

<p>


<h4><a NAME="2.1.5">2.1.5  Return values</a></h4>
All of the CBFlib functions return 0 on success and an error code on failure.
The error codes are:
<p>
<CENTER>
<table>
<TR><td valign="top">&nbsp;&nbsp;CBF_FORMAT<td valign="top">&nbsp;&nbsp;The file format is invalid
<TR><td valign="top">&nbsp;&nbsp;CBF_ALLOC<td valign="top">&nbsp;&nbsp;Memory allocation failed
<TR><td valign="top">&nbsp;&nbsp;CBF_ARGUMENT<td valign="top">&nbsp;&nbsp;Invalid function argument
<TR><td valign="top">&nbsp;&nbsp;CBF_ASCII<td valign="top">&nbsp;&nbsp;The value is ASCII (not binary)
<TR><td valign="top">&nbsp;&nbsp;CBF_BINARY<td valign="top">&nbsp;&nbsp;The value is binary (not ASCII)
<TR><TD VALIGN=TOP>&nbsp;&nbsp;CBF_BITCOUNT<td valign="top">&nbsp;&nbsp;The expected number of bits does <br />not match the actual number written
<TR><TD VALIGN=TOP>&nbsp;&nbsp;CBF_ENDOFDATA<td valign="top">&nbsp;&nbsp;The end of the data was reached <br />before the end of the array
<TR><td valign="top">&nbsp;&nbsp;CBF_FILECLOSE<td valign="top">&nbsp;&nbsp;File close error
<TR><td valign="top">&nbsp;&nbsp;CBF_FILEOPEN<td valign="top">&nbsp;&nbsp;File open error
<TR><td valign="top">&nbsp;&nbsp;CBF_FILEREAD<td valign="top">&nbsp;&nbsp;File read error
<TR><td valign="top">&nbsp;&nbsp;CBF_FILESEEK<td valign="top">&nbsp;&nbsp;File seek error
<TR><td valign="top">&nbsp;&nbsp;CBF_FILETELL<td valign="top">&nbsp;&nbsp;File tell error
<TR><td valign="top">&nbsp;&nbsp;CBF_FILEWRITE<td valign="top">&nbsp;&nbsp;File write error
<TR><TD VALIGN=TOP>&nbsp;&nbsp;CBF_IDENTICAL<td valign="top">&nbsp;&nbsp;A data block with the new name <br />already exists
<TR><TD VALIGN=TOP>&nbsp;&nbsp;CBF_NOTFOUND<td valign="top">&nbsp;&nbsp;The data block, category, column or<br /> row does not exist
<TR><TD VALIGN=TOP>&nbsp;&nbsp;CBF_OVERFLOW<td valign="top">&nbsp;&nbsp;The number read cannot fit into the<br /> destination argument.  The destination
has<br />been set to the nearest value.
<TR><TD VALIGN=TOP>&nbsp;&nbsp;CBF_UNDEFINED<td valign="top">&nbsp;&nbsp;The requested number is not defined (e.g. 0/0; new for version 0.7).
<TR><TD VALIGN=TOP>&nbsp;&nbsp;CBF_NOTIMPLEMENTED<td valign="top">&nbsp;&nbsp;The requested functionality is not yet implemented (New for version 0.7).

</TABLE>
</CENTER>
<p>

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

<h4><A NAME="2.2">2.2  Reading and writing files containing binary sections</A></h4>

<h4><A NAME="2.2.1">2.2.1  Reading binary sections</A></h4>
<p>
The current version of CBFlib only decompresses a binary section from disk when requested
by the program.
<p>
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.
<p>
For this scheme to work:
<p>
1. The file must be a random-access file opened in binary
mode (fopen ( ,&quot; rb&quot;)).<br />
2. The program <i>must not</i>
 close the file.  CBFlib will close the file using fclose ( ) when it is no longer
needed.
<p>
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.
<p>
When reading an imgCIF vs a CBF, the difference is detected automatically.
<p>
<h4><A NAME="2.2.2">2.2.2  Writing binary sections</A></h4>
<p>
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.
<p>
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.
<p>
For this option to work:
<p>
1. The file must be a random-access file opened in binary
update mode (fopen ( , &quot;w+b&quot;)).<br />
2. The program <i>must not</i>
 close the file.  CBFlib will close the file using fclose ( )
when it is no longer
needed.
<p>
If this option is not used:
<p>
1. CBFlib will continue using the temporary file.<br />
2. CBFlib <i>will not</i>
 close the file.  This is the responsibility of the main program.
<p>
<h4><A NAME="2.2.3">2.2.3  Summary of reading and writing files containing binary sections</A></h4>
<p>
1. Open disk files to read using the mode &quot;rb&quot;. <br />
2. If possible, open disk files to write using the mode &quot;w+b&quot;
and tell CBFlib that it can use the file as a buffer.<br />
3. Do <i>not</i>
close any files read by CBFlib or written by CBFlib with
buffering turned on.<br />
4. Do <i>not</i> attempt to read from a file, then
write to the same file.<br />

<P>
<h4><A NAME="2.2.4">2.2.4   Ordering of array indices</A></h4>
<P>
There are two major conventions in the ordering of array indices:
<ul>
<li><b>fs</b>: Fast to slow.  The first array index (the one numbered &quot;1&quot;) is the one
for which the values of that index change &quot;fastest&quot;.  That is, as we move
forward in memory, the value of this index changes more rapidly than any other.
<li><b>sf</b>: Slow to fast.  The first array index (the one numbered &quot;1&quot;) is the one
for which the values of that index change &quot;slowest&quot;.  That is as we move
forward in memory, the value of this index changes more slowly than any other.
</ul>
<P>
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 &quot;_fs&quot; suffix for the fast to slow convention and a form in which the name of the
function has a &quot;_sf&quot; suffix for the slow to fast convention.  Designers of applications
are advised to use one of the two suffix 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.
<hr /><hr />
<p>
<h4><A NAME="2.3">2.3  Low-level function prototypes</A></h4>

<h4><A NAME="2.3.1">2.3.1  cbf_make_handle</A> </h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_make_handle (cbf_handle *<i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
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.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;Pointer to a CBF handle.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.2">2.3.2  cbf_free_handle</A><br />
<p><hr /><P>
<h4><A NAME="2.3.2">2.3.2  cbf_free_handle</A> </h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_free_handle (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_free_handle destroys the CBF object specified by
the <i>handle</i> and frees all associated
memory.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle to free.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.1">2.3.1  cbf_make_handle</A><br />
<p><hr /><P>
<h4><A NAME="2.3.3">2.3.3  cbf_read_file, cbf_read_widefile</A></H4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_read_file (cbf_handle <i>handle</i>, FILE *<i>file</i>, int <i>flags</i>);<br />
int cbf_read_widefile (cbf_handle <i>handle</i>, FILE *<i>file</i>, int <i>flags</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_read_file reads the CBF or CIF file <i>file</i>
 into the CBF object specified by <i>handle</i>, using the CIF 1.0 convention of 80 character lines.
cbf_read_widefile reads the CBF or CIF file <i>file</i>
 into the CBF object specified by <i>handle</i>, 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.
<p>
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.  
<p>
<i>flags</i> controls the interpretation of binary section headers, the parsing of
brackets constructs and the parsing of treble-quoted strings.
<TABLE>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;MSG_DIGEST:
<td valign="top">&nbsp;&nbsp;Instructs CBFlib to check that the digest of the
binary section matches any
header digest value.  If the digests do
not match, the call will return CBF_FORMAT.  This evaluation and comparison
is delayed (a &quot;lazy&quot; evaluation) to ensure maximal processing efficiency.
If an immediately evaluation is required, see MSG_DIGESTNOW, below.
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;MSG_DIGESTNOW:
<td valign="top">&nbsp;&nbsp;Instructs CBFlib to check that the digest of the
binary section matches any
header digeste value.  If the digests do
not match, the call will return CBF_FORMAT.  This evaluation and comparison
is performed during initial parsing of the section to ensure timely
error reporting at the expense of processing efficiency.
If a more efficient delayed (&quot;lazy&quot;)  evaluation is required, see MSG_DIGEST, above.
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;MSG_DIGESTWARN:
<td valign="top">&nbsp;&nbsp;Instructs CBFlib to check that the digest of the
binary section matches any
header digeste value.  If the digests do
not match, a warning message will be sent to stderr, but processing will
attempt to continue.  This evaluation and comparison
is first performed during initial parsing of the section to ensure timely
error reporting at the expense of processing efficiency.
An mismatch of the message digest usually indicates a serious error, but it
is sometimes worth continuing processing to try to isolate the cause of
the error.  <b>Use this option with caution.</b>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;MSG_NODIGEST:
<td valign="top">&nbsp;&nbsp;Do not check the digest (default).
<tr>
<td valign="top">&nbsp;&nbsp;PARSE_BRACKETS:
<td valign="top">&nbsp;&nbsp;Accept DDLm bracket-delimited <b>[item,item,...item]</b> or
<b>{item,item,...item}</b> or <b>(item,item,...item)</b> constructs as
valid, stripping non-quoted embedded whitespace and comments.  These constructs may span multiple lines.
<tr>
<td valign="top">&nbsp;&nbsp;PARSE_LIBERAL_BRACKETS:
<td valign="top">&nbsp;&nbsp;Accept DDLm bracket-delimited <b>[item,item,...item]</b> or
<b>{item,item,...item}</b> or <b>(item,item,...item)</b> constructs as
valid, stripping embedded non-quoted, non-separating whitespace and comments.  These constructs may span multiple lines.  In
this case, whitespace may be used as an alternative to the comma.
<tr>
<td valign="top">&nbsp;&nbsp;PARSE_TRIPLE_QUOTES:
<td valign="top">&nbsp;&nbsp;Accept DDLm triple-quoted <b>&quot;&quot;&quot;item,item,...item&quot;&quot;&quot;</b> or 
<b>'''item,item,...item'''</b> constructs as
valid, stripping embedded whitespace and comments.  These constructs may span multiple lines.  If this flag
is set, then ''' will <b>not</b> be interpreted as a quoted apoptrophe and
""" will <b>not</b> be interpreted as a quoted double quote mark and
<tr>
<td valign="top">&nbsp;&nbsp;PARSE_NOBRACKETS:
<td valign="top">&nbsp;&nbsp;Do not accept DDLm bracket-delimited <b>[item,item,...item]</b> or
<b>{item,item,...item}</b> or <b>(item,item,...item)</b> constructs as
valid, stripping non-quoted embedded whitespace and comments.  These constructs may span multiple lines.
<tr>
<td valign="top">&nbsp;&nbsp;PARSE_NOTRIPLE_QUOTES:
<td valign="top">&nbsp;&nbsp;No not accept DDLm triple-quoted <b>&quot;&quot;&quot;item,item,...item&quot;&quot;&quot;</b> or 
<b>'''item,item,...item'''</b> constructs as
valid, stripping embedded whitespace and comments.  These constructs may span multiple lines.  If this flag
is set, then ''' will be interpreted as a quoted apostrophe and
""" will be interpreted as a quoted double quote mark.





</TABLE>
<p>
CBFlib defers reading binary sections as long as possible.  In the current version
of CBFlib, this means that:
<p>
1. The file must be a random-access file opened in binary mode
(fopen ( , &quot;rb&quot;)).<br />
2. The program <i>must not</i>
 close the file.  CBFlib will close the file using fclose ( ) when it is no longer
needed.
<p>
These restrictions may change in a future release.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>file</i><td valign="top">&nbsp;&nbsp;Pointer to a file descriptor.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>flags</i><td valign="top">&nbsp;&nbsp;Controls interpretation of binary section headers.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>


<A HREF="#2.3.4">2.3.4  cbf_write_file</A><br />
<p><hr /><P>
<h4><A NAME="2.3.4">2.3.4  cbf_write_file, cbf_write_widefile</A> </h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_write_file (cbf_handle <i>handle</i>, FILE *<i>file</i>, int <i>readable</i>, int <i>ciforcbf</i>, int <i>flags</i>, int <i>encoding</i>);<br />
int cbf_write_widefile (cbf_handle <i>handle</i>, FILE *<i>file</i>, int <i>readable</i>, int <i>ciforcbf</i>, int <i>flags</i>, int <i>encoding</i>);
<p>

<b>DESCRIPTION</b>
<p>
cbf_write_file writes the CBF object specified by <i>handle</i>
 into the file <i>file</i>, following CIF 1.0 conventions of 80 character lines.
cbf_write_widefile writes the CBF object specified by <i>handle</i>
 into the file <i>file</i>, 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.
<p>
If a dictionary has been provided, aliases will be applied on output.
<p>
Unlike cbf_read_file, the <i>file</i> does not have to be random-access.
<p>
If the file is random-access and readable, <i>readable</i> 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, <i>readable</i> must be 0.
<p>
If <i>readable</i> is non-0, CBFlib will close the file when it is
no longer required, otherwise this is
the responsibility of the program.
<p>
<i>ciforcbf</i> selects the format in which the binary sections are written:
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;CIF<td valign="top">&nbsp;&nbsp;Write an imgCIF file.
<TR><td valign="top">&nbsp;&nbsp;CBF<td valign="top">&nbsp;&nbsp;Write a CBF file (default).
</TABLE>
<i>flags</i> selects the type of header used in CBF binary sections, selects whether message
digests are generated, and controls the style of output.  The value of <i>flags</i> can be a logical OR of any of:
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;MIME_HEADERS<td valign="top">&nbsp;&nbsp;Use MIME-type headers (default).
<TR><td valign="top">&nbsp;&nbsp;MIME_NOHEADERS<td valign="top">&nbsp;&nbsp;Use a simple ASCII headers.
<TR><td valign="top">&nbsp;&nbsp;MSG_DIGEST<td valign="top">&nbsp;&nbsp;Generate message digests for binary data validation.
<TR><td valign="top">&nbsp;&nbsp;MSG_NODIGEST<td valign="top">&nbsp;&nbsp;Do not generate message digests (default).
<TR><td valign="top">&nbsp;&nbsp;PARSE_BRACKETS<td valign="top">&nbsp;&nbsp;Do not convert bracketed strings to text fields (default).
<TR><td valign="top">&nbsp;&nbsp;PARSE_LIBERAL_BRACKETS<td valign="top">&nbsp;&nbsp;Do not convert bracketed strings to text fields (default).
<TR><td valign="top">&nbsp;&nbsp;PARSE_NOBRACKETS<td valign="top">&nbsp;&nbsp;Convert bracketed strings to text fields (default).
<TR><td valign="top">&nbsp;&nbsp;PARSE_TRIPLE_QUOTES<td valign="top">&nbsp;&nbsp;Do not convert triple-quoted strings to text fields (default).
<TR><td valign="top">&nbsp;&nbsp;PARSE_NOTRIPLE_QUOTES<td valign="top">&nbsp;&nbsp;Convert triple-quoted strings to text fields (default).
<TR><td valign="top">&nbsp;&nbsp;PAD_1K<td valign="top">&nbsp;&nbsp;Pad binary sections with 1023 nulls.
<TR><td valign="top">&nbsp;&nbsp;PAD_2K<td valign="top">&nbsp;&nbsp;Pad binary sections with 2047 nulls.
<TR><td valign="top">&nbsp;&nbsp;PAD_4K<td valign="top">&nbsp;&nbsp;Pad binary sections with 4095 nulls.
</TABLE>

<p>

<p>
Note that on output, the types &quot;prns&, &quot;brcs&quot; and &quot;bkts&quot; will be
converted to &quot;text&quot; fields if PARSE_NOBRACKETS has been set <i>flags</i>, 
and that the types &quot;tsqs&quot; and &quot;tdqs&quot; will
be converted to &quot;text&quot; fields if the flag PARSE_NOTRIPLE_QUOTES has been set in the
<i>flags</i>.  It is an error to set PARSE_NOBRACKETS and to set either PARSE_BRACKETS or
PARSE_LIBERAL_BRACKETS.  It is an error to set both PARSE_NOTRIPLE_QUOTES and PARSE_TRIPLE_QUOTES.
<P>
<i>encoding</i> 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:
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;ENC_BASE64<td valign="top">&nbsp;&nbsp;Use BASE64 encoding (default).
<TR><td valign="top">&nbsp;&nbsp;ENC_QP<td valign="top">&nbsp;&nbsp;Use QUOTED-PRINTABLE encoding.
<TR><td valign="top">&nbsp;&nbsp;ENC_BASE8<td valign="top">&nbsp;&nbsp;Use BASE8 (octal) encoding.
<TR><td valign="top">&nbsp;&nbsp;ENC_BASE10<td valign="top">&nbsp;&nbsp;Use BASE10 (decimal) encoding.
<TR><td valign="top">&nbsp;&nbsp;ENC_BASE16<td valign="top">&nbsp;&nbsp;Use BASE16 (hexadecimal) encoding.
<TR><TD VALIGN=TOP>&nbsp;&nbsp;ENC_FORWARD<td valign="top">&nbsp;&nbsp;For BASE8, BASE10 or BASE16 encoding, map bytes to words
forward (1234) (default on little-endian machines).
<TR><TD VALIGN=TOP>&nbsp;&nbsp;ENC_BACKWARD<td valign="top">&nbsp;&nbsp;Map bytes to words backward (4321) (default on big-endian
machines).
<TR><TD VALIGN=TOP>&nbsp;&nbsp;ENC_CRTERM<td valign="top">&nbsp;&nbsp;Terminate lines with CR.
<TR><TD VALIGN=TOP>&nbsp;&nbsp;ENC_LFTERM<td valign="top">&nbsp;&nbsp;Terminate lines with LF (default).
</TABLE>
<p><b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>file</i><td valign="top">&nbsp;&nbsp;Pointer to a file descriptor.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>readable</i><td valign="top">&nbsp;&nbsp;If non-0: this file is random-access
and readable and can be used as a buffer.
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>ciforcbf</i><td valign="top">&nbsp;&nbsp;Selects the format in which the
binary sections are written (CIF/CBF).
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>flags</i><td valign="top">&nbsp;&nbsp;Selects the type of header in CBF
binary sections and message digest generation.
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>encoding</i><td valign="top">&nbsp;&nbsp;Selects the type of encoding used
for binary sections and the type of line-termination
in imgCIF files.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.3">2.3.3  cbf_read_file</A><br />
<p><hr /><P>


<h4><A NAME="2.3.5">2.3.5  cbf_new_datablock, cbf_new_saveframe</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_new_datablock (cbf_handle <i>handle</i>, const char *<i>datablockname</i>);<br />
int cbf_new_saveframe (cbf_handle <i>handle</i>, const char *<i>saveframename</i>);

<p><b>DESCRIPTION</b>
<p>
cbf_new_datablock creates a new data block with name <i>datablockname</i>
 and makes it the current data block.
cbf_new_saveframe creates a new save frame with name <i>saveframename</i>
within the current data block
 and makes the new save frame the current save frame.
<p>
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.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>datablockname</i><td valign="top">&nbsp;&nbsp;The name of the new data block.
<TR><td valign="top">&nbsp;&nbsp;<i>saveframename</i><td valign="top">&nbsp;&nbsp;The name of the new save frame.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.6">2.3.6  cbf_force_new_datablock, cbf_force_new_saveframe</A><br />
<A HREF="#2.3.7">2.3.7  cbf_new_category</A><br />
<A HREF="#2.3.8">2.3.8  cbf_force_new_category</A><br />
<A HREF="#2.3.9">2.3.9  cbf_new_column</A><br />
<A HREF="#2.3.10">2.3.10  cbf_new_row</A><br />
<A HREF="#2.3.11">2.3.11  cbf_insert_row</A><br />
<A HREF="#2.3.12">2.3.12  cbf_set_datablockname, cbf_set_saveframename</A><br />
<A HREF="#2.3.17">2.3.17  cbf_remove_datablock, cbf_remove_saveframe</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />

<p><hr /><P>
<h4><A NAME="2.3.6">2.3.6  cbf_force_new_datablock, cbf_force_new_saveframe</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_force_new_datablock (cbf_handle <i>handle</i>,
const char *<i>datablockname</i>);<br />
int cbf_force_new_saveframe (cbf_handle <i>handle</i>,
const char *<i>saveframename</i>);

<p><b>DESCRIPTION</b>
<p>
cbf_force_new_datablock creates a new data block with name <i>datablockname</i>
 and makes it the current data block.   Duplicate data block names are allowed.
cbf_force_new_saveframe creates a new savew frame with name <i>saveframename</i>
 and makes it the current save frame.   Duplicate save frame names are allowed.
<p>
Even if a save frame with this name already exists, a new save frame
 is created and becomes the current save frame.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>datablockname</i><td valign="top">&nbsp;&nbsp;The name of the new data block.
<TR><td valign="top">&nbsp;&nbsp;<i>saveframename</i><td valign="top">&nbsp;&nbsp;The name of the new save frame.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<a href="#2.3.5">2.3.5  cbf_new_datablock, cbf_new_saveframe</A><br />
<A HREF="#2.3.7">2.3.7  cbf_new_category</A><br />
<A HREF="#2.3.8">2.3.8  cbf_force_new_category</A><br />
<A HREF="#2.3.9">2.3.9  cbf_new_column</A><br />
<A HREF="#2.3.10">2.3.10  cbf_new_row</A><br />
<A HREF="#2.3.11">2.3.11  cbf_insert_row</A><br />
<a href="#2.3.12">2.3.12  cbf_set_datablockname, cbf_set_saveframename</A><br />
<A HREF="#2.3.17">2.3.17  cbf_remove_datablock, cbf_remove_saveframe</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>


<h4><A NAME="2.3.7">2.3.7  cbf_new_category</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_new_category (cbf_handle <i>handle</i>,
const char *<i>categoryname</i>);
<p><b>DESCRIPTION</b>
<p>
cbf_new_category creates a new category in the
current data block with name <i>categoryname</i>
 and makes it the current category.
<p>
If a category with this name already exists, the
existing category becomes the current
category.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>categoryname</i><td valign="top">&nbsp;&nbsp;The name of the new category.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<a href="#2.3.5">2.3.5  cbf_new_datablock, cbf_new_saveframe</A><br />
<a href="#2.3.6">2.3.6  cbf_force_new_datablock, cbf_force_new_saveframe</A><br />
<A HREF="#2.3.8">2.3.8  cbf_force_new_category</A><br />
<A HREF="#2.3.9">2.3.9  cbf_new_column</A><br />
<A HREF="#2.3.10">2.3.10  cbf_new_row</A><br />
<A HREF="#2.3.11">2.3.11  cbf_insert_row</A><br />
<A HREF="#2.3.18">2.3.18  cbf_remove_category</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>
<h4><A NAME="2.3.8">2.3.8  cbf_force_new_category</A> </h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_force_new_category (cbf_handle <i>handle</i>, const char *<i>categoryname</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_force_new_category creates a new category in the current data block with name <i>categoryname</i>
 and makes it the current category.   Duplicate category names are allowed.
<p>
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.
<p><b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>categoryname</i><td valign="top">&nbsp;&nbsp;The name of the new category.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<a href="#2.3.5">2.3.5  cbf_new_datablock, cbf_new_saveframe</A><br />
<a href="#2.3.6">2.3.6  cbf_force_new_datablock, cbf_force_new_saveframe</A><br />
<A HREF="#2.3.7">2.3.7  cbf_new_category</A><br />
<A HREF="#2.3.9">2.3.9  cbf_new_column</A><br />
<A HREF="#2.3.10">2.3.10  cbf_new_row</A><br />
<A HREF="#2.3.11">2.3.11  cbf_insert_row</A><br />
<A HREF="#2.3.18">2.3.18  cbf_remove_category</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>
<h4><A NAME="2.3.9">2.3.9  cbf_new_column</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_new_column (cbf_handle <i>handle</i>, const char *<i>columnname</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_new_column creates a new column in the current category with name <i>columnname</i>
 and makes it the current column.
<p>
If a column with this name already exists, the existing column becomes the current
category.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>columnname</i><td valign="top">&nbsp;&nbsp;The name of the new column.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<a href="#2.3.5">2.3.5  cbf_new_datablock, cbf_new_saveframe</A><br />
<a href="#2.3.6">2.3.6  cbf_force_new_datablock, cbf_force_new_saveframe</A><br />
<A HREF="#2.3.7">2.3.7  cbf_new_category</A><br />
<A HREF="#2.3.8">2.3.8  cbf_force_new_category</A><br />
<A HREF="#2.3.10">2.3.10  cbf_new_row</A><br />
<A HREF="#2.3.11">2.3.11  cbf_insert_row</A><br />
<A HREF="#2.3.19">2.3.19  cbf_remove_column</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>


<h4><A NAME="2.3.10">2.3.10  cbf_new_row</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_new_row (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_new_row adds a new row to the current category and makes it the current row.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<a href="#2.3.5">2.3.5  cbf_new_datablock, cbf_new_saveframe</A><br />
<a href="#2.3.6">2.3.6  cbf_force_new_datablock, cbf_force_new_saveframe</A><br />
<A HREF="#2.3.7">2.3.7  cbf_new_category</A><br />
<A HREF="#2.3.8">2.3.8  cbf_force_new_category</A><br />
<A HREF="#2.3.9">2.3.9  cbf_new_column</A><br />
<A HREF="#2.3.11">2.3.11  cbf_insert_row</A><br />
<A HREF="#2.3.12">2.3.12  cbf_delete_row</A><br />
<A HREF="#2.3.20">2.3.20  cbf_remove_row</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>
<h4><A NAME="2.3.11">2.3.11  cbf_insert_row</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_insert_row (cbf_handle <i>handle</i>, unsigned int <i>rownumber</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_insert_row adds a new row to the current category.  The new row is inserted as
row <i>rownumber</i>
 and existing rows starting from <i>rownumber</i>
 are moved up by 1.  The new row becomes the current row.
<p>
If the category has fewer than <i>rownumber</i>
 rows, the function returns CBF_NOTFOUND.
<p>
The row numbers start from 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>rownumber</i><td valign="top">&nbsp;&nbsp;The row number of the new row.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<a href="#2.3.5">2.3.5  cbf_new_datablock, cbf_new_saveframe</A><br />
<a href="#2.3.6">2.3.6  cbf_force_new_datablock, cbf_force_new_saveframe</A><br />
<A HREF="#2.3.7">2.3.7  cbf_new_category</A><br />
<A HREF="#2.3.8">2.3.8  cbf_force_new_category</A><br />
<A HREF="#2.3.9">2.3.9  cbf_new_column</A><br />
<A HREF="#2.3.10">2.3.10  cbf_new_row</A><br />
<A HREF="#2.3.12">2.3.12  cbf_delete_row</A><br />
<A HREF="#2.3.20">2.3.20  cbf_remove_row</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>


<h4><A NAME="2.3.12">2.3.12  cbf_delete_row</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_delete_row (cbf_handle <i>handle</i>, unsigned int <i>rownumber</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_delete_row deletes a row from the current category.  Rows starting from <i>rownumber</i>
+1 are moved down by 1.  If the current row
was higher than <i>rownumber</i>, or if the current row is the last row, it will also move down by 1.
<p>
The row numbers start from 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>rownumber</i><td valign="top">&nbsp;&nbsp;The number of the row to delete.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.10">2.3.10  cbf_new_row</A><br />
<A HREF="#2.3.11">2.3.11  cbf_insert_row</A><br />
<A HREF="#2.3.17">2.3.17  cbf_remove_datablock, cbf_remove_saveframe</A><br />
<A HREF="#2.3.18">2.3.18  cbf_remove_category</A><br />
<A HREF="#2.3.19">2.3.19  cbf_remove_column</A><br />
<A HREF="#2.3.20">2.3.20  cbf_remove_row</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>


<h4><A NAME="2.3.13">2.3.13  cbf_set_datablockname, cbf_set_saveframename</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_set_datablockname (cbf_handle <i>handle</i>, const char *<i>datablockname</i>);<br />
int cbf_set_saveframename (cbf_handle <i>handle</i>, const char *<i>saveframename</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_datablockname changes the name of the current data block to <i>datablockname</i>.
cbf_set_saveframename changes the name of the current save frame to <i>saveframename</i>.
<p>
If a data block or save frame with this name already exists (comparison is case-insensitive), the
function returns CBF_IDENTICAL.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>datablockname</i><td valign="top">&nbsp;&nbsp;The new data block name.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>saveframename</i><td valign="top">&nbsp;&nbsp;The new save frame name.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<a href="#2.3.5">2.3.5  cbf_new_datablock, cbf_new_saveframe</A><br />
<A HREF="#2.3.14">2.3.14  cbf_reset_datablocks</A><br />
<A HREF="#2.3.15">2.3.15  cbf_reset_datablock, cbf_reset_saveframe</A><br />
<A HREF="#2.3.17">2.3.17  cbf_remove_datablock, cbf_remove_saveframe</A><br />
<A HREF="#2.3.42">2.3.42  cbf_datablock_name</A><br />
<p><hr /><P>
<h4><A NAME="2.3.14">2.3.14  cbf_reset_datablocks</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_reset_datablocks (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_reset_datablocks deletes all categories from all data blocks.
<p>
The current data block does not change.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.15">2.3.15  cbf_reset_datablock, cbf_reset_saveframe</A><br />
<A HREF="#2.3.18">2.3.18  cbf_remove_category</A><br />
<p><hr /><P>
<h4><A NAME="2.3.15">2.3.15  cbf_reset_datablock, cbf_reset_saveframe</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_reset_datablock (cbf_handle <i>handle</i>);<br />
int cbf_reset_saveframe (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_reset_datablock deletes all categories from the current data block.
cbf_reset_saveframe deletes all categories from the current save frame.

<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.14">2.3.14  cbf_reset_datablocks</A><br />
<A HREF="#2.3.18">2.3.18  cbf_remove_category</A><br />

<p><hr /><P>
<h4><A NAME="2.3.16">2.3.16  cbf_reset_category</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_reset_category (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_reset_category deletes all columns and rows from current category.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.16">2.3.16  cbf_reset_category</A><br />
<A HREF="#2.3.19">2.3.19  cbf_remove_column</A><br />
<A HREF="#2.3.20">2.3.20  cbf_remove_row</A><br />
<p><hr /><P>
<h4><A NAME="2.3.17">2.3.17  cbf_remove_datablock, cbf_remove_saveframe </A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_remove_datablock (cbf_handle <i>handle</i>);<br />
int cbf_remove_saveframe (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_remove_datablock deletes the current data block.
cbf_remove_saveframe deletes the current save frame.
<p>
The current data block becomes undefined.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<a href="#2.3.5">2.3.5  cbf_new_datablock, cbf_new_saveframe</A><br />
<a href="#2.3.6">2.3.6  cbf_force_new_datablock, cbf_force_new_saveframe</A><br />
<A HREF="#2.3.18">2.3.18  cbf_remove_category</A><br />
<A HREF="#2.3.19">2.3.19  cbf_remove_column</A><br />
<A HREF="#2.3.20">2.3.20  cbf_remove_row</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>
<h4><A NAME="2.3.18">2.3.18  cbf_remove_category</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_remove_category (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_remove_category deletes the current category.
<p>
The current category becomes undefined.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.7">2.3.7  cbf_new_category</A><br />
<A HREF="#2.3.8">2.3.8  cbf_force_new_category</A><br />
<A HREF="#2.3.17">2.3.17  cbf_remove_datablock, cbf_remove_saveframe</A><br />
<A HREF="#2.3.19">2.3.19  cbf_remove_column</A><br />
<A HREF="#2.3.20">2.3.20  cbf_remove_row</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>
<h4><A NAME="2.3.19">2.3.19  cbf_remove_column</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_remove_column (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_remove_column deletes the current column.
<p>
The current column becomes undefined.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.9">2.3.9  cbf_new_column</A><br />
<A HREF="#2.3.17">2.3.17  cbf_remove_datablock, cbf_remove_saveframe</A><br />
<A HREF="#2.3.18">2.3.18  cbf_remove_category</A><br />
<A HREF="#2.3.20">2.3.20  cbf_remove_row</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>
<h4><A NAME="2.3.20">2.3.20  cbf_remove_row</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_remove_row (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_remove_row deletes the current row in the current category.
<p>
If the current row was the last row, it will move down by 1,
otherwise, it will remain the same.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.10">2.3.10  cbf_new_row</A><br />
<A HREF="#2.3.11">2.3.11  cbf_insert_row</A><br />
<A HREF="#2.3.17">2.3.17  cbf_remove_datablock, cbf_remove_saveframe</A><br />
<A HREF="#2.3.18">2.3.18  cbf_remove_category</A><br />
<A HREF="#2.3.19">2.3.19  cbf_remove_column</A><br />
<A HREF="#2.3.12">2.3.12  cbf_delete_row</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>


<h4><A NAME="2.3.21">2.3.21  cbf_rewind_datablock</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_rewind_datablock (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_rewind_datablock makes the first data block the current data block.
<p>
If there are no data blocks, the function returns CBF_NOTFOUND.
<p>
The current category becomes undefined.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.22">2.3.22  cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem</A><br />
<A HREF="#2.3.19">2.3.19  cbf_rewind_column</A><br />
<A HREF="#2.3.24">2.3.24  cbf_rewind_row</A><br />
<A HREF="#2.3.25">2.3.25  cbf_next_datablock</A><br />

<p><hr /><P>
<h4><A NAME="2.3.22">2.3.22  cbf_rewind_category,  cbf_rewind_saveframe,  cbf_rewind_blockitem</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_rewind_category (cbf_handle <i>handle</i>);<br />
int cbf_rewind_saveframe (cbf_handle <i>handle</i>);<br />
int cbf_rewind_blockitem (cbf_handle <i>handle</i>, <i>CBF_NODETYPE * type</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_rewind_category makes the first category in the current data block the current
category.
cbf_rewind_saveframe makes the first saveframe in the current data block the current
saveframe.
cbf_rewind_blockitem makes the first blockitem (category or saveframe) in the current data block the current
blockitem.  The type of the blockitem (CBF_CATEGORY or CBF_SAVEFRAME) is returned in <i>type</i>.
<p>
If there are no categories, saveframes or blockitems the function returns CBF_NOTFOUND.
<p>
The current column and row become undefined.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>type</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.21">2.3.21  cbf_rewind_datablock</A><br />
<A HREF="#2.3.19">2.3.19  cbf_rewind_column</A><br />
<A HREF="#2.3.24">2.3.24  cbf_rewind_row</A><br />
<A HREF="#2.3.26">2.3.26  cbf_next_category, cbf_next_saveframe, cbf_next_blockitem</A><br />

<p><hr /><P>
<h4><A NAME="2.3.23">2.3.23  cbf_rewind_column</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_rewind_column (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_rewind_column makes the first column in the current category
the current column.

<p>
If there are no columns, the function returns CBF_NOTFOUND.
<p>
The current row is not affected.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.21">2.3.21  cbf_rewind_datablock</A><br />
<A HREF="#2.3.22">2.3.22  cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem</A><br />
<A HREF="#2.3.24">2.3.24  cbf_rewind_row</A><br />
<A HREF="#2.3.27">2.3.27  cbf_next_column</A><br />

<p><hr /><P>
<h4><A NAME="2.3.24">2.3.24  cbf_rewind_row</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_rewind_row (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_rewind_row makes the first row in the current category the current row.
<p>
If there are no rows, the function returns CBF_NOTFOUND.
<p>
The current column is not affected.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.21">2.3.21  cbf_rewind_datablock</A><br />
<A HREF="#2.3.22">2.3.22  cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem</A><br />
<A HREF="#2.3.19">2.3.19  cbf_rewind_column</A><br />
<A HREF="#2.3.28">2.3.28  cbf_next_row</A><br />

<p><hr /><P>
<h4><A NAME="2.3.25">2.3.25  cbf_next_datablock</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_next_datablock (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_next_datablock makes the data block following the current
data block the current data block.
<p>
If there are no more data blocks, the function returns CBF_NOTFOUND.
<p>
The current category becomes undefined.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.21">2.3.21  cbf_rewind_datablock</A><br />
<A HREF="#2.3.26">2.3.26  cbf_next_category, cbf_next_saveframe, cbf_next_blockitem</A><br />
<A HREF="#2.3.27">2.3.27  cbf_next_column</A><br />
<A HREF="#2.3.28">2.3.28  cbf_next_row</A><br />
<p><hr /><P>
<h4><A NAME="2.3.26">2.3.26  cbf_next_category</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_next_category (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_next_category makes the category following the current category
in the current data block the current category.
<p>
If there are no more categories, the function returns CBF_NOTFOUND.
<p>
The current column and row become undefined.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.22">2.3.22  cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem</A><br />
<A HREF="#2.3.25">2.3.25  cbf_next_datablock</A><br />
<A HREF="#2.3.27">2.3.27  cbf_next_column</A><br />
<A HREF="#2.3.28">2.3.27  cbf_next_row</A><br />
<p><hr /><P>
<h4><A NAME="2.3.27">2.3.27  cbf_next_column</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_next_column (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_next_column makes the column following the current column in the current category
the current column.
<p>
If there are no more columns, the function returns CBF_NOTFOUND.
<p>
The current row is not affected.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.19">2.3.19  cbf_rewind_column</A><br />
<A HREF="#2.3.25">2.3.25  cbf_next_datablock</A><br />
<A HREF="#2.3.26">2.3.26  cbf_next_category, cbf_next_saveframe, cbf_next_blockitem</A><br />
<A HREF="#2.3.28">2.3.28  cbf_next_row</A><br />
<p><hr /><P>
<h4><A NAME="2.3.28">2.3.28  cbf_next_row</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_next_row (cbf_handle <i>handle</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_next_row makes the row following the current row in the current
category the current row.
<p>
If there are no more rows, the function returns CBF_NOTFOUND.
<p>
The current column is not affected.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.24">2.3.24  cbf_rewind_row</A><br />
<A HREF="#2.3.25">2.3.25  cbf_next_datablock</A><br />
<A HREF="#2.3.26">2.3.26  cbf_next_category, cbf_next_saveframe, cbf_next_blockitem</A><br />
<A HREF="#2.3.27">2.3.27  cbf_next_column</A><br />

<p><hr /><P>
<h4><A NAME="2.3.29">2.3.29  cbf_find_datablock</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_find_datablock (cbf_handle <i>handle</i>, const char *<i>datablockname</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_find_datablock makes the data block with name <i>datablockname</i>
 the current data block.
<p>
The comparison is case-insensitive.
<p>
If the data block does not exist, the function returns CBF_NOTFOUND.
<p>
The current category becomes undefined.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>datablockname</i><td valign="top">&nbsp;&nbsp;The name of the data block to find.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.21">2.3.21  cbf_rewind_datablock</A><br />
<A HREF="#2.3.25">2.3.25  cbf_next_datablock</A><br />
<A HREF="#2.3.30">2.3.30  cbf_find_category, cbf_find_saveframe, cbf_find_blockitem</A><br />
<A HREF="#2.3.31">2.3.31  cbf_find_column</A><br />
<A HREF="#2.3.32">2.3.32  cbf_find_row</A><br />
<A HREF="#2.3.42">2.3.42  cbf_datablock_name</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>
<h4><A NAME="2.3.30">2.3.30  cbf_find_category</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_find_category (cbf_handle <i>handle</i>,
const char *<i>categoryname</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_find_category makes the category in the current data block with
name <i>categoryname</i> the current category.
<p>
The comparison is case-insensitive.
<p>
If the category does not exist, the function returns CBF_NOTFOUND.
<p>
The current column and row become undefined.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>categoryname</i><td valign="top">&nbsp;&nbsp;The name of the category to find.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.22">2.3.22  cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem</A><br />
<A HREF="#2.3.26">2.3.26  cbf_next_category, cbf_next_saveframe, cbf_next_blockitem</A><br />
<A HREF="#2.3.29">2.3.29  cbf_find_datablock</A><br />
<A HREF="#2.3.31">2.3.31  cbf_find_column</A><br />
<A HREF="#2.3.32">2.3.32  cbf_find_row</A><br />
<A HREF="#2.3.43">2.3.43  cbf_category_name</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />
<p><hr /><P>
<h4><A NAME="2.3.31">2.3.31  cbf_find_column</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_find_column (cbf_handle <i>handle</i>, const char *<i>columnname</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_find_column makes the columns in the current category with
name <i>columnname</i> the current column.
<p>
The comparison is case-insensitive.
<p>
If the column does not exist, the function returns CBF_NOTFOUND.
<p>
The current row is not affected.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>columnname</i><td valign="top">&nbsp;&nbsp;The name of column to find.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.19">2.3.19  cbf_rewind_column</A><br />
<A HREF="#2.3.27">2.3.27  cbf_next_column</A><br />
<A HREF="#2.3.29">2.3.29  cbf_find_datablock</A><br />
<A HREF="#2.3.30">2.3.30  cbf_find_category, cbf_find_saveframe, cbf_find_blockitem</A><br />
<A HREF="#2.3.32">2.3.32  cbf_find_row</A><br />
<A HREF="#2.3.44">2.3.44  cbf_column_name</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />

<p><hr /><P>
<h4><A NAME="2.3.32">2.3.32  cbf_find_row</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_find_row (cbf_handle <i>handle</i>, const char *<i>value</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_find_row makes the first row in the current column with value
<i>value</i> the current row.
<p>
The comparison is case-sensitive.
<p>
If a matching row does not exist, the function returns CBF_NOTFOUND.
<p>
The current column is not affected.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>value</i><td valign="top">&nbsp;&nbsp;The value of the row to find.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.24">2.3.24  cbf_rewind_row</A><br />
<A HREF="#2.3.28">2.3.28  cbf_next_row</A><br />
<A HREF="#2.3.29">2.3.29  cbf_find_datablock</A><br />
<A HREF="#2.3.30">2.3.30  cbf_find_category, cbf_find_saveframe, cbf_find_blockitem</A><br />
<A HREF="#2.3.31">2.3.31  cbf_find_column</A><br />
<A HREF="#2.3.33">2.3.33  cbf_find_nextrow</A><br />
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />

<p>
<h4><A NAME="2.3.33">2.3.33  cbf_find_nextrow</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_find_nextrow (cbf_handle <i>handle</i>, const char *<i>value</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_find_nextrow makes the makes the next row in the current column
with value <i>value</i> 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.
<p>
The comparison is case-sensitive.
<p>
If no more matching rows exist, the function returns CBF_NOTFOUND.
<p>
The current column is not affected.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>value</i><td valign="top">&nbsp;&nbsp;the value to search for.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.24">2.3.24  cbf_rewind_row</A><br />
<A HREF="#2.3.28">2.3.28  cbf_next_row</A><br />
<A HREF="#2.3.29">2.3.29  cbf_find_datablock</A><br />
<A HREF="#2.3.30">2.3.30  cbf_find_category, cbf_find_saveframe, cbf_find_blockitem</A><br />
<A HREF="#2.3.31">2.3.31  cbf_find_column</A><br />
<A HREF="#2.3.32">2.3.32  cbf_find_row</A><br />
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />

<p><hr /><P>
<h4><A NAME="2.3.34">2.3.34  cbf_count_datablocks</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_count_datablocks (cbf_handle <i>handle</i>,
unsigned int *<i>datablocks</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_count_datablocks puts the number of data blocks in *<i>datablocks</i>
.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>datablocks</i><td valign="top">&nbsp;&nbsp;Pointer to the destination data block count.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.35">2.3.35  cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems</A><br />
<A HREF="#2.3.36">2.3.36  cbf_count_columns</A><br />
<A HREF="#2.3.37">2.3.37  cbf_count_rows</A><br />
<A HREF="#2.3.38">2.3.38  cbf_select_datablock</A><br />

<p><hr /><P>
<h4><A NAME="2.3.35">2.3.35  cbf_count_categories</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_count_categories (cbf_handle <i>handle</i>,
unsigned int *<i>categories</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_count_categories puts the number of categories in the current data
block in *<i>categories</i>.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>categories</i><td valign="top">&nbsp;&nbsp;Pointer to the destination category count.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.34">2.3.34  cbf_count_datablocks</A><br />
<A HREF="#2.3.36">2.3.36  cbf_count_columns</A><br />
<A HREF="#2.3.37">2.3.37  cbf_count_rows</A><br />
<A HREF="#2.3.39">2.3.39  cbf_select_category, cbf_select_saveframe, cbf_select_blockitem</A><br />

<p><hr /><P>
<h4><A NAME="2.3.36">2.3.36  cbf_count_columns</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_count_columns (cbf_handle <i>handle</i>, unsigned int *<i>columns</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_count_columns puts the number of columns in the current category
in *<i>columns</i>.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>columns</i><td valign="top">&nbsp;&nbsp;Pointer to the destination column count.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.34">2.3.34  cbf_count_datablocks</A><br />
<A HREF="#2.3.35">2.3.35  cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems</A><br />
<A HREF="#2.3.37">2.3.37  cbf_count_rows</A><br />
<A HREF="#2.3.40">2.3.40  cbf_select_column</A><br />
<p>

<hr /><p>
<h4><A NAME="2.3.37">2.3.37  cbf_count_rows</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_count_rows (cbf_handle <i>handle</i>, unsigned int *<i>rows</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_count_rows puts the number of rows in the current category in *<i>rows</i>
.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>rows</i><td valign="top">&nbsp;&nbsp;Pointer to the destination row count.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.34">2.3.34  cbf_count_datablocks</A><br />
<A HREF="#2.3.35">2.3.35  cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems</A><br />
<A HREF="#2.3.36">2.3.36  cbf_count_columns</A><br />
<A HREF="#2.3.41">2.3.41  cbf_select_row</A><br />

<p><hr /><P>
<h4><A NAME="2.3.38">2.3.38  cbf_select_datablock</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_select_datablock (cbf_handle <i>handle</i>,
unsigned int <i>datablock</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_select_datablock selects data block number <i>datablock</i>
 as the current data block.
<p>
The first data block is number 0.
<p>
If the data block does not exist, the function returns CBF_NOTFOUND.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>datablock</i><td valign="top">&nbsp;&nbsp;Number of the data block to select.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.34">2.3.34  cbf_count_datablocks</A><br />
<A HREF="#2.3.39">2.3.39  cbf_select_category, cbf_select_saveframe, cbf_select_blockitem</A><br />
<A HREF="#2.3.40">2.3.40  cbf_select_column</A><br />
<A HREF="#2.3.41">2.3.41  cbf_select_row</A>
<p><hr /><P>
<h4><A NAME="2.3.39">2.3.39  cbf_select_category</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_select_category (cbf_handle <i>handle</i>,
unsigned int <i>category</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_select_category selects category number <i>category</i>
 in the current data block as the current category.
<p>
The first category is number 0.
<p>
The current column and row become undefined.
<p>
If the category does not exist, the function returns CBF_NOTFOUND.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>category</i><td valign="top">&nbsp;&nbsp;Number of the category to select.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.35">2.3.35  cbf_count_categories, cbf_count_saveframes, cbf_count_blockitems</A><br />
<A HREF="#2.3.38">2.3.38  cbf_select_datablock</A><br />
<A HREF="#2.3.40">2.3.40  cbf_select_column</A><br />
<A HREF="#2.3.41">2.3.41  cbf_select_row</A><br />
<p><hr /><P>
<h4><A NAME="2.3.40">2.3.40  cbf_select_column</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_select_column (cbf_handle <i>handle</i>, unsigned int <i>column</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_select_column selects column number <i>column</i>
 in the current category as the current column.
<p>
The first column is number 0.
<p>
The current row is not affected
<p>
If the column does not exist, the function returns CBF_NOTFOUND.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>column</i><td valign="top">&nbsp;&nbsp;Number of the column to select.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.36">2.3.36  cbf_count_columns</A><br />
<A HREF="#2.3.38">2.3.38  cbf_select_datablock</A><br />
<A HREF="#2.3.39">2.3.39  cbf_select_category, cbf_select_saveframe, cbf_select_blockitem</A><br />
<A HREF="#2.3.41">2.3.41  cbf_select_row</A><br />
<p><hr /><P>
<h4><A NAME="2.3.41">2.3.41  cbf_select_row</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_select_row (cbf_handle <i>handle</i>, unsigned int <i>row</i>);
<p>
<b>DESCRIPTION</b>
<p>
 cbf_select_row selects row number <i>row</i>
 in the current category as the current row.
<p>
The first row is number 0.
<p>
The current column is not affected
<p>
If the row does not exist, the function returns CBF_NOTFOUND.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>row</i><td valign="top">&nbsp;&nbsp;Number of the row to select.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.37">2.3.37  cbf_count_rows</A><br />
<A HREF="#2.3.38">2.3.38  cbf_select_datablock</A><br />
<A HREF="#2.3.39">2.3.39  cbf_select_category, cbf_select_saveframe, cbf_select_blockitem</A><br />
<A HREF="#2.3.40">2.3.40  cbf_select_column</A><br />
<p><hr /><P>
<h4><A NAME="2.3.42">2.3.42  cbf_datablock_name</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_datablock_name (cbf_handle <i>handle</i>,
const char **<i>datablockname</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_datablock_name sets *<i>datablockname</i>
 to point to the name of the current data block.
<p>
The data block name will be valid as long as the data block exists
and has not been renamed.
<p>
The name must not be modified by the program in any way.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>datablockname</i><td valign="top">&nbsp;&nbsp;Pointer to the
destination data block name pointer.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.29">2.3.29  cbf_find_datablock</A><br />

<p><hr /><P>
<h4><A NAME="2.3.43">2.3.43  cbf_category_name</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_category_name (cbf_handle <i>handle</i>,
const char **<i>categoryname</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_category_name sets *<i>categoryname </i>
to point to the name of the current category of the current data block.
<p>
The category name will be valid as long as the category exists.
<p>
The name must not be modified by the program in any way.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>categoryname</i><td valign="top">&nbsp;&nbsp;Pointer to the
destination category name pointer.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.30">2.3.30  cbf_find_category, cbf_find_saveframe, cbf_find_blockitem</A><br />

<p><hr /><P>
<h4><A NAME="2.3.44">2.3.44  cbf_column_name, cbf_set_column_name</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_column_name (cbf_handle <i>handle</i>, const char **<i>columnname</i>);<br />
int cbf_set_column_name (cbf_handle <i>handle</i>, const char *<i>newcolumnname</i>)
<p>
<b>DESCRIPTION</b>
<p>
cbf_column_name sets *<i>columnname</i>
to point to the name of the current column of the current category.
<p>
The column name will be valid as long as the column exists.
<p>
The name must not be modified by the program in any way.
<p>
cbf_set_column_name sets the name of the current column to
<i>newcolumnname</i>
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>columnname</i><td valign="top">&nbsp;&nbsp;Pointer to the
destination column name pointer.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>newcolumnname</i><td valign="top">&nbsp;&nbsp;New column name pointer.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.31">2.3.31  cbf_find_column</A><br />

<p><hr /><P>
<h4><A NAME="2.3.45">2.3.45  cbf_row_number</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_row_number (cbf_handle <i>handle</i>, unsigned int *<i>row</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_row_number sets *<i>row</i>
 to the number of the current row of the current category.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>row</i><td valign="top">&nbsp;&nbsp;Pointer to the destination row number.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.41">2.3.41  cbf_select_row</A><br />

<p><hr /><P>
<h4><A NAME="2.3.46">2.3.46  cbf_get_value, cbf_require_value</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_get_value (cbf_handle <i>handle</i>, const char **<i>value</i>);<br />
int cbf_require_value (cbf_handle <i>handle</i>, const char **<i>value</i>, const char *<i>defaultvalue</i> );
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_value sets *<i>value</i>
 to point to the ASCII value of the item at the current column and row.
cbf_require_value sets *<i>value</i>
 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 <i>defaultvalue</i>.

<p>
If the value is not ASCII, the function returns CBF_BINARY.
<p>
The value will be valid as long as the item exists and has not been set to a new value.

<p>
The value must not be modified by the program in any way.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>value</i><td valign="top">&nbsp;&nbsp;Pointer to the destination value pointer.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>defaultvalue</i><td valign="top">&nbsp;&nbsp;Default value character string.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.47">2.3.47  cbf_set_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.50">2.3.50  cbf_get_integervalue, cbf_require_integervalue</A><br />
<A HREF="#2.3.52">2.3.52  cbf_get_doublevalue, cbf_require_doublevalue</A><br />
<A HREF="#2.3.54">2.3.54  cbf_get_integerarrayparameters,  cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters, cbf_get_realarrayparameters_wdims</A><br />
<A HREF="#2.3.55">2.3.55  cbf_get_integerarray, cbf_get_realarray</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.64">2.3.64  cbf_require_column_doublevalue</A><br />


<p><hr /><P>
<h4><A NAME="2.3.47">2.3.47  cbf_set_value</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_set_value (cbf_handle <i>handle</i>, const char *<i>value</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_value sets the item at the current column and row to the ASCII
value <i>value</i>.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>value</i><td valign="top">&nbsp;&nbsp;ASCII value.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.51">2.3.51  cbf_set_integervalue</A><br />
<A HREF="#2.3.53">2.3.53  cbf_set_doublevalue</A><br />
<A HREF="#2.3.56">2.3.56  cbf_set_integerarray, cbf_set_integerarray_wdims, cbf_set_realarray, cbf_set_realarray_wdims</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.64">2.3.64  cbf_require_column_doublevalue</A><br />

<p><hr /><P>
<h4><A NAME="2.3.48">2.3.48  cbf_get_typeofvalue</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_get_typeofvalue (cbf_handle <i>handle</i>, const char **<i>typeofvalue</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_value sets *<i>typeofvalue</i>
to point an ASCII descriptor of the value of the item at the current column and row.
The strings that may be returned are:
<center>
<table border=0 cellpadding=3>
<tr>
<td>&quot;null&quot;</td><td>for a null value indicated by a &quot;.&quot; or a &quot;?&quot;</td>
</tr>
<tr>
<td>&quot;bnry&quot;</td><td>for a binary value</td>
</tr>
<tr>
<td>&quot;word&quot;</td><td>for an unquoted string</td>
</tr>
<tr>
<td>&quot;dblq&quot;</td><td>for a double-quoted string</td>
</tr>
<tr>
<td>&quot;sglq&quot;</td><td>for a single-quoted string</td>
</tr>
<tr>
<td>&quot;text&quot;</td><td>for a semicolon-quoted string (multiline text field) </td>
</tr>
<tr>
<td>&quot;prns&quot;</td><td>for a parenthesis-bracketed string (multiline text field) </td>
</tr>
<tr>
<td>&quot;brcs&quot;</td><td>for a brace-bracketed string (multiline text field)</td>
</tr>
<tr>
<td>&quot;bkts&quot;</td><td>for a square-bracket-bracketed string (multiline text field)</td>
</tr>
<tr>
<td>&quot;tsqs&quot;</td><td>for a treble-single-quote quoted string (multiline text field)</td>
</tr>
<tr>
<td>&quot;tdqs&quot;</td><td>for a treble-double-quote quoted string (multiline text field)</td>

</tr>
</table>
</center>
<P>
Not all types are valid for all type of CIF
files.  In partcular the types &quot;prns&quot;, &quot;brcs&quot;, &quot;bkts&quot; were
introduced with DDLm and are not valid in DDL1 or DDL2 CIFS.  The types &quot;tsqs&quot; and
&quot;tdqs&quot; are not formally part of the CIF syntax.
 
 
A field for which no value has been set sets
*<i>typeofvalue</i> to NULL rather than to the
string &quot;null&quot;.


<p>
The <i>typeofvalue</i> must not be modified by the program in any way.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>typeofvalue</i><td valign="top">&nbsp;&nbsp;Pointer to the destination type-of-value string pointer.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.47">2.3.47  cbf_set_value</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.50">2.3.50  cbf_get_integervalue,  cbf_require_integervalue</A><br />
<A HREF="#2.3.52">2.3.52  cbf_get_doublevalue, cbf_require_doublevalue</A><br />
<A HREF="#2.3.54">2.3.54  cbf_get_integerarrayparameters,  cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters, cbf_get_realarrayparameters_wdims</A><br />
<A HREF="#2.3.55">2.3.55  cbf_get_integerarray, cbf_get_realarray</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.64">2.3.64  cbf_require_column_doublevalue</A><br />

<p><hr /><P>
<h4><A NAME="2.3.49">2.3.49  cbf_set_typeofvalue</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_set_typeofvalue (cbf_handle <i>handle</i>, const char *<i>typeofvalue</i>);
<p>
<b>DESCRIPTION</b>
<p>
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 <i>typeofvalue</i>. The strings that may be used
are:
<center>
<table border=0 cellpadding=3>
<tr>
<td>&quot;null&quot;</td><td>for a null value indicated by a &quot;.&quot; or a &quot;?&quot;</td>
</tr>
<tr>
<td>&quot;bnry&quot;</td><td>for a binary value</td>
</tr>
<tr>
<td>&quot;word&quot;</td><td>for an unquoted string</td>
</tr>
<tr>
<td>&quot;dblq&quot;</td><td>for a double-quoted string</td>
</tr>
<tr>
<td>&quot;sglq&quot;</td><td>for a single-quoted string</td>
</tr>
<tr>
<td>&quot;text&quot;</td><td>for a semicolon-quoted string (multiline text field) </td>
</tr>
<tr>
<td>&quot;prns&quot;</td><td>for a parenthesis-bracketed string (multiline text field) </td>
</tr>
<tr>
<td>&quot;brcs&quot;</td><td>for a brace-bracketed string (multiline text field)</td>
</tr>
<tr>
<td>&quot;bkts&quot;</td><td>for a square-bracket-bracketed string (multiline text field)</td>
</tr>
<tr>
<td>&quot;tsqs&quot;</td><td>for a treble-single-quote quoted string (multiline text field)</td>
</tr>
<tr>
<td>&quot;tdqs&quot;</td><td>for a treble-double-quote quoted string (multiline text field)</td>

</tr>
</table>
</center>

Not all types may be used for all values.  Not all types are valid for all type of CIF
files.  In partcular the types &quot;prns&quot;, &quot;brcs&quot;, &quot;bkts&quot; were
introduced with DDLm and are not valid in DDL1 or DDL2 CIFS.  The types &quot;tsqs&quot; and
&quot;tdqs&quot; are not formally part of the CIF syntax.  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 &quot;sglq&quot;. 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 &quot;dblq&quot;.

<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>typeofvalue</i><td valign="top">&nbsp;&nbsp;ASCII string for desired type of value.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.47">2.3.47  cbf_set_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.51">2.3.51  cbf_set_integervalue</A><br />
<A HREF="#2.3.53">2.3.53  cbf_set_doublevalue</A><br />
<A HREF="#2.3.56">2.3.56  cbf_set_integerarray, cbf_set_integerarray_wdims, cbf_set_realarray, cbf_set_realarray_wdims</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.64">2.3.64  cbf_require_column_doublevalue</A><br />
<p><hr /><P>




<h4><A NAME="2.3.50">2.3.50  cbf_get_integervalue, cbf_require_integervalue</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_get_integervalue (cbf_handle <i>handle</i>, int *<i>number</i>);<br />
int cbf_require_integervalue (cbf_handle <i>handle</i>, int *<i>number</i>, int <i>defaultvalue</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_integervalue sets *<i>number</i>
 to the value of the ASCII item at the current column and row interpreted as a decimal
integer.
cbf_require_integervalue sets *<i>number</i>
 to the value of the ASCII item at the current column and row interpreted as a decimal
integer, setting it to <i>defaultvalue</i> if necessary.
<p>
If the value is not ASCII, the function returns CBF_BINARY.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>number</i><td valign="top">&nbsp;&nbsp;pointer to the number.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>defaultvalue</i><td valign="top">&nbsp;&nbsp;default number value.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.51">2.3.51  cbf_set_integervalue</A><br />
<A HREF="#2.3.52">2.3.52  cbf_get_doublevalue, cbf_require_doublevalue</A><br />
<A HREF="#2.3.54">2.3.54  cbf_get_integerarrayparameters,  cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters, cbf_get_realarrayparameters_wdims</A><br />
<A HREF="#2.3.55">2.3.55  cbf_get_integerarray, cbf_get_realarray</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.64">2.3.64  cbf_require_column_doublevalue</A><br />

<p><hr /><P>
<h4><A NAME="2.3.51">2.3.51  cbf_set_integervalue</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_set_integervalue (cbf_handle <i>handle</i>, int <i>number</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_integervalue sets the item at the current column and row to the integer value
<i>number</i>
 written as a decimal ASCII string.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>number</i><td valign="top">&nbsp;&nbsp;Integer value.</BR>
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.47">2.3.47  cbf_set_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.50">2.3.50  cbf_get_integervalue,  cbf_require_integervalue</A><br />
<A HREF="#2.3.51">2.3.51  cbf_set_integervalue</A><br />
<A HREF="#2.3.53">2.3.53  cbf_set_doublevalue</A><br />
<A HREF="#2.3.56">2.3.56  cbf_set_integerarray, cbf_set_integerarray_wdims, cbf_set_realarray, cbf_set_realarray_wdims</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.64">2.3.64  cbf_require_column_doublevalue</A><br />

<p><hr /><P>
<h4><A NAME="2.3.52">2.3.52  cbf_get_doublevalue, cbf_require_doublevalue</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_get_doublevalue (cbf_handle <i>handle</i>, double *<i>number</i>);<br />
int cbf_require_doublevalue (cbf_handle <i>handle</i>, double *<i>number</i>, double <i>defaultvalue</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_doublevalue sets *<i>number</i>
 to the value of the ASCII item at the current column and row interpreted as a decimal
floating-point number.
cbf_require_doublevalue sets *<i>number</i>
 to the value of the ASCII item at the current column and row interpreted as a decimal
floating-point number, setting it to <i>defaultvalue</i> if necessary.
<p>
If the value is not ASCII, the function returns CBF_BINARY.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>number</i><td valign="top">&nbsp;&nbsp;Pointer to the destination number.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>defaultvalue</i><td valign="top">&nbsp;&nbsp;default number value.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.50">2.3.50  cbf_get_integervalue,  cbf_require_integervalue</A><br />
<A HREF="#2.3.53">2.3.53  cbf_set_doublevalue</A><br />
<A HREF="#2.3.54">2.3.54  cbf_get_integerarrayparameters,  cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters, cbf_get_realarrayparameters_wdims</A><br />
<A HREF="#2.3.55">2.3.55  cbf_get_integerarray, cbf_get_realarray</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.64">2.3.64  cbf_require_column_doublevalue</A><br />

<p><hr /><P>
<h4><A NAME="2.3.53">2.3.53  cbf_set_doublevalue</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_set_doublevalue (cbf_handle <i>handle</i>,
const char *<i>format</i>, double <i>number</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_doublevalue sets the item at the current column and
row to the floating-point value <i>number</i>
written as an ASCII string with the format specified by
<i>format</i> as appropriate for the printf function.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>format</i><td valign="top">&nbsp;&nbsp;Format for the number.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>number</i><td valign="top">&nbsp;&nbsp;Floating-point value.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.47">2.3.47  cbf_set_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.51">2.3.51  cbf_set_integervalue</A><br />
<A HREF="#2.3.52">2.3.52  cbf_get_doublevalue, cbf_require_doublevalue</A><br />
<A HREF="#2.3.56">2.3.56  cbf_set_integerarray, cbf_set_integerarray_wdims, cbf_set_realarray, cbf_set_realarray_wdims</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.64">2.3.64  cbf_require_column_doublevalue</A><br />
<p><hr /><P>


<h4><A NAME="2.3.54">2.3.54  cbf_get_integerarrayparameters,<br />
  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_get_integerarrayparameters_wdims, cbf_get_integerarrayparameters_wdims_fs, cbf_get_integerarrayparameters_wdims_sf,
  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_get_realarrayparameters,<br />
  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_get_realarrayparameters_wdims, cbf_get_realarrayparameters_wdims_fs, cbf_get_realarrayparameters_wdims_sf</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_get_integerarrayparameters (cbf_handle <i>handle</i>,
unsigned int *<i>compression</i>,
int *<i>binary_id</i>,
size_t *<i>elsize</i>,
int *<i>elsigned</i>, int *<i>elunsigned</i>,
size_t *<i>elements</i>,
int *<i>minelement</i>, int *<i>maxelement</i>);<br />
&nbsp;<br />


int cbf_get_integerarrayparameters_wdims (cbf_handle <i>handle</i>,
unsigned int *<i>compression</i>,
int *<i>binary_id</i>,
size_t *<i>elsize</i>,
int *<i>elsigned</i>, int *<i>elunsigned</i>,
size_t *<i>elements</i>,
int *<i>minelement</i>, int *<i>maxelement</i>,
const char  **<i>byteorder</i>,
size_t       *<i>dimfast</i>,
size_t       *<i>dimmid</i>,
size_t       *<i>dimslow</i>,
size_t       *<i>padding</i>);<br />

int cbf_get_integerarrayparameters_wdims_fs (cbf_handle <i>handle</i>,
unsigned int *<i>compression</i>,
int *<i>binary_id</i>,
size_t *<i>elsize</i>,
int *<i>elsigned</i>, int *<i>elunsigned</i>,
size_t *<i>elements</i>,
int *<i>minelement</i>, int *<i>maxelement</i>,
const char  **<i>byteorder</i>,
size_t       *<i>dimfast</i>,
size_t       *<i>dimmid</i>,
size_t       *<i>dimslow</i>,
size_t       *<i>padding</i>);<br />

int cbf_get_integerarrayparameters_wdims_sf (cbf_handle <i>handle</i>,
unsigned int *<i>compression</i>,
int *<i>binary_id</i>,
size_t *<i>elsize</i>,
int *<i>elsigned</i>, int *<i>elunsigned</i>,
size_t *<i>elements</i>,
int *<i>minelement</i>, int *<i>maxelement</i>,
const char  **<i>byteorder</i>,
size_t       *<i>dimslow</i>,
size_t       *<i>dimmid</i>,
size_t       *<i>dimfast</i>,
size_t       *<i>padding</i>);<br />
&nbsp;<br />


int cbf_get_realarrayparameters (cbf_handle <i>handle</i>,
unsigned int *<i>compression</i>,
int *<i>binary_id</i>,
size_t *<i>elsize</i>,
size_t *<i>elements</i>);<br />
&nbsp;<br />

int cbf_get_realarrayparameters_wdims (cbf_handle <i>handle</i>,
unsigned int *<i>compression</i>,
int *<i>binary_id</i>,
size_t *<i>elsize</i>,
size_t *<i>elements</i>,
const char  **<i>byteorder</i>,
size_t       *<i>dimfast</i>,
size_t       *<i>dimmid</i>,
size_t       *<i>dimslow</i>,
size_t       *<i>padding</i>);<br />

int cbf_get_realarrayparameters_wdims_fs (cbf_handle <i>handle</i>,
unsigned int *<i>compression</i>,
int *<i>binary_id</i>,
size_t *<i>elsize</i>,
size_t *<i>elements</i>,
const char  **<i>byteorder</i>,
size_t       *<i>dimfast</i>,
size_t       *<i>dimmid</i>,
size_t       *<i>dimslow</i>,
size_t       *<i>padding</i>);<br />

int cbf_get_realarrayparameters_wdims_sf (cbf_handle <i>handle</i>,
unsigned int *<i>compression</i>,
int *<i>binary_id</i>,
size_t *<i>elsize</i>,
size_t *<i>elements</i>,
const char  **<i>byteorder</i>,
size_t       *<i>dimslow</i>,
size_t       *<i>dimmid</i>,
size_t       *<i>dimfast</i>,
size_t       *<i>padding</i>);

<p>



<b>DESCRIPTION</b>
<p>
cbf_get_integerarrayparameters sets *<i>compression</i>,
 *<i>binary_id</i>, *<i>elsize</i>,
 *<i>elsigned</i>, *<i>elunsigned</i>,
 *<i>elements</i>, *<i>minelement</i>
 and *<i>maxelement</i>
 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 *<i>compression</i>,
 *<i>binary_id</i>, *<i>elsize</i>,
 *<i>elements</i>
 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.
<P>
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 **<i>byteorder</i>,
*<i>dimfast</i>,
*<i>dimmid</i>,
*<i>dimslow</i>,
and *<i>padding</i> as well, providing the additional parameters
needed for a subsequent call to cbf_set_integerarray_wdims
or cbf_set_realarray_wdims.
<P>
The value returned in *<i>byteorder</i> 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.
<P>
The values returned in *<i>dimfast</i>, *<i>dimmid</i> and  *<i>dimslow</i>
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.
<P>
The value returned in *<i>padding</i> 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.
<P>
<p>
If the value is not binary, the function returns CBF_ASCII.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>compression</i><td valign="top">&nbsp;&nbsp;Compression method used.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>elsize</i><td valign="top">&nbsp;&nbsp;Size in bytes of each array element.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>binary_id</i><td valign="top">&nbsp;&nbsp;Pointer to the destination integer binary identifier.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>elsigned</i><td valign="top">&nbsp;&nbsp;Pointer to an integer.  Set to 1 if the elements can be read as signed integers.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>elunsigned</i><td valign="top">&nbsp;&nbsp;Pointer to an integer.  Set to 1 if the elements can be read as unsigned
integers.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>elements</i><td valign="top">&nbsp;&nbsp;Pointer to the destination number of elements.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>minelement</i><td valign="top">&nbsp;&nbsp;Pointer to the destination smallest element.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>maxelement</i><td valign="top">&nbsp;&nbsp;Pointer to the destination largest element.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>byteorder</i><td valign="top">&nbsp;&nbsp;Pointer to the destination byte order.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>dimfast</i><td valign="top">&nbsp;&nbsp;Pointer to the destination fastest dimension.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>dimmid</i><td valign="top">&nbsp;&nbsp;Pointer to the destination second fastest dimension.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>dimslow</i><td valign="top">&nbsp;&nbsp;Pointer to the destination third fastest dimension.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>padding</i><td valign="top">&nbsp;&nbsp;Pointer to the destination padding size.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.50">2.3.50  cbf_get_integervalue,  cbf_require_integervalue</A><br />
<A HREF="#2.3.52">2.3.52  cbf_get_doublevalue, cbf_require_doublevalue</A><br />
<A HREF="#2.3.55">2.3.55  cbf_get_integerarray, cbf_get_realarray</A><br />
<A HREF="#2.3.56">2.3.56  cbf_set_integerarray, cbf_set_integerarray_wdims, cbf_set_realarray, cbf_set_realarray_wdims</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.64">2.3.64  cbf_require_column_doublevalue</A><br />

<p><hr /><P>
<h4><A NAME="2.3.55">2.3.55  cbf_get_integerarray, cbf_get_realarray </A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_get_integerarray (cbf_handle <i>handle</i>,
int *<i>binary_id</i>,
void *<i>array</i>, size_t <i>elsize</i>, int <i>elsigned</i>,
size_t <i>elements</i>, size_t *<i>elements_read</i>);<br />
int cbf_get_realarray (cbf_handle <i>handle</i>,
int *<i>binary_id</i>,
void *<i>array</i>, size_t <i>elsize</i>,
size_t <i>elements</i>, size_t *<i>elements_read</i>);

<p>
<b>DESCRIPTION</b>
<p>
cbf_get_integerarray reads the binary value of the item at the current
column and row into an integer array.  The array consists of
<i>elements</i> elements of <i>elsize</i> bytes each, starting at
<i>array</i>.  The elements are signed if <i>elsigned</i>
 is non-0 and unsigned otherwise.  *<i>binary_id</i>
 is set to the binary section identifier and *<i>elements_read </i>
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
<i>elements</i> elements of <i>elsize</i> bytes each, starting at
<i>array</i>.   *<i>binary_id</i>
 is set to the binary section identifier and *<i>elements_read </i>
to the number of elements actually read.
<p>
If any element in the integer binary data cant fit into the destination
element, the destination is set the nearest possible value.
<p>
If the value is not binary, the function returns CBF_ASCII.
<p>
If the requested number of elements cant be read, the function
will read as many as
it can and then return CBF_ENDOFDATA.
<p>
Currently, the destination array must consist of chars,
shorts or ints (signed or unsigned).  If <i>elsize </i>
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.
<p>
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^<SUP>32</sup>-1 (unsigned) or -2^<SUP>31</sup> .. 2^<SUP>31</sup>-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.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>binary_id</i><td valign="top">&nbsp;&nbsp;Pointer to the destination
integer binary identifier.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>array</i><td valign="top">&nbsp;&nbsp;Pointer to the destination array.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>elsize</i><td valign="top">&nbsp;&nbsp;Size in bytes of each
destination array element.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>elsigned</i><td valign="top">&nbsp;&nbsp;Set to non-0 if the
destination array elements are signed.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>elements</i><td valign="top">&nbsp;&nbsp;The number of elements to read.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>elements_read</i><td valign="top">&nbsp;&nbsp;Pointer to the
destination number of elements actually read.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.<br />

SEE ALSO
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.50">2.3.50  cbf_get_integervalue,  cbf_require_integervalue</A><br />
<A HREF="#2.3.52">2.3.52  cbf_get_doublevalue, cbf_require_doublevalue</A><br />
<A HREF="#2.3.54">2.3.54  cbf_get_integerarrayparameters, cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters, cbf_get_realarrayparameters_wdims</A><br />
<A HREF="#2.3.56">2.3.56  cbf_set_integerarray, cbf_set_integerarray_wdims, cbf_set_realarray, cbf_set_realarray_wdims</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.64">2.3.64  cbf_require_column_doublevalue</A><br />
<p><hr /><P>
<h4><A NAME="2.3.56">2.3.56  cbf_set_integerarray,<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_set_integerarray_wdims, cbf_set_integerarray_wdims_fs, cbf_set_integerarray_wdims_sf,<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_set_realarray,<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_set_realarray_wdims, cbf_set_realarray_wdims_fs, cbf_set_realarray_wdims_sf</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_set_integerarray (cbf_handle <i>handle</i>,
unsigned int <i>compression</i>,
int <i>binary_id</i>,
void *<i>array</i>, size_t <i>elsize</i>, int <i>elsigned</i>,
size_t <i>elements</i>);<br />
&nbsp;<br />

int cbf_set_integerarray_wdims (cbf_handle <i>handle</i>,
unsigned int <i>compression</i>,
int <i>binary_id</i>,
void *<i>array</i>, size_t <i>elsize</i>, int <i>elsigned</i>,
size_t <i>elements</i>,  const char   *<i>byteorder</i>,
size_t        <i>dimfast</i>, size_t       <i>dimmid</i>,
size_t        <i>dimslow</i>, size_t       <i>padding</i>);<br />

int cbf_set_integerarray_wdims_fs (cbf_handle <i>handle</i>,
unsigned int <i>compression</i>,
int <i>binary_id</i>,
void *<i>array</i>, size_t <i>elsize</i>, int <i>elsigned</i>,
size_t <i>elements</i>,  const char   *<i>byteorder</i>,
size_t        <i>dimfast</i>, size_t       <i>dimmid</i>,
size_t        <i>dimslow</i>, size_t       <i>padding</i>);<br />

int cbf_set_integerarray_wdims_sf (cbf_handle <i>handle</i>,
unsigned int <i>compression</i>,
int <i>binary_id</i>,
void *<i>array</i>, size_t <i>elsize</i>, int <i>elsigned</i>,
size_t <i>elements</i>,  const char   *<i>byteorder</i>,
size_t        <i>dimslow</i>, size_t       <i>dimmid</i>,
size_t        <i>dimfast</i>, size_t       <i>padding</i>);<br />
&nbsp;<br />

int cbf_set_realarray (cbf_handle <i>handle</i>,
unsigned int <i>compression</i>,
int <i>binary_id</i>,
void *<i>array</i>, size_t <i>elsize</i>,
size_t <i>elements</i>);<br />
&nbsp;<br />

int cbf_set_realarray_wdims (cbf_handle <i>handle</i>,
unsigned int <i>compression</i>,
int <i>binary_id</i>,
void *<i>array</i>, size_t <i>elsize</i>,
size_t <i>elements</i>,  const char   *<i>byteorder</i>,
size_t        <i>dimfast</i>, size_t       <i>dimmid</i>,
size_t        <i>dimslow</i>, size_t       <i>padding</i>);<br />

int cbf_set_realarray_wdims_fs (cbf_handle <i>handle</i>,
unsigned int <i>compression</i>,
int <i>binary_id</i>,
void *<i>array</i>, size_t <i>elsize</i>,
size_t <i>elements</i>,  const char   *<i>byteorder</i>,
size_t        <i>dimfast</i>, size_t       <i>dimmid</i>,
size_t        <i>dimslow</i>, size_t       <i>padding</i>);<br />

int cbf_set_realarray_wdims_sf (cbf_handle <i>handle</i>,
unsigned int <i>compression</i>,
int <i>binary_id</i>,
void *<i>array</i>, size_t <i>elsize</i>,
size_t <i>elements</i>,  const char   *<i>byteorder</i>,
size_t        <i>dimslow</i>, size_t       <i>dimmid</i>,
size_t        <i>dimfast</i>, size_t       <i>padding</i>);<br />

<p>
<b>DESCRIPTION</b>
<p>
cbf_set_integerarray sets the binary value of the item at the current
column and row to an integer <i>array</i>.
 The array consists of <i>elements</i>
 elements of <i>elsize</i>
 bytes each, starting at <i>array</i>.  The elements
are signed if <i>elsigned</i>
 is non-0 and unsigned otherwise.  <i>binary_id</i>
 is the binary section identifier.
cbf_set_realarray sets the binary value of the item at the current
column and row to an integer <i>array</i>.
 The array consists of <i>elements</i>
 elements of <i>elsize</i>
 bytes each, starting at <i>array</i>.  <i>binary_id</i>
 is the binary section identifier.
 <P>
 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 <i>byteorder</i>,
 <i>dimfast</i>, <i>dimmid</i>, <i>dimslow</i> and <i>padding</i>
 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.
 
<p>
The array will be compressed using the compression scheme specifed
by <i>compression</i>.  Currently, the available schemes are:
<p>
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;CBF_CANONICAL<td valign="top">&nbsp;&nbsp;Canonical-code compression  (section 3.3.1)<br />
<TR><td valign="top">&nbsp;&nbsp;CBF_PACKED<td valign="top">&nbsp;&nbsp;CCP4-style packing   (section 3.3.2)
<TR><td valign="top">&nbsp;&nbsp;CBF_PACKED_V2<td valign="top">&nbsp;&nbsp;CCP4-style packing, version 2   (section 3.3.2)
<TR><TD VALIGN=TOP>&nbsp;&nbsp;CBF_BYTE_OFFSET<td valign="top">&nbsp;&nbsp;Simple &quot;byte_offset&quot; compression.
<TR><TD VALIGN=TOP>&nbsp;&nbsp;CBF_NIBBLE_OFFSET<td valign="top">&nbsp;&nbsp;Simple &quot;nibble_offset&quot; compression.
<TR><TD VALIGN=TOP>&nbsp;&nbsp;CBF_NONE<td valign="top">&nbsp;&nbsp;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.
</TABLE>
<p>
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.
<p>
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 <i>elsize </i>
is not equal to sizeof (char), sizeof (short) or sizeof (int), the function returns
CBF_ARGUMENT.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>compression</i><td valign="top">&nbsp;&nbsp;Compression method to use.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>binary_id</i><td valign="top">&nbsp;&nbsp;Integer binary identifier.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>array</i><td valign="top">&nbsp;&nbsp;Pointer to the source array.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>elsize</i><td valign="top">&nbsp;&nbsp;Size in bytes of each source array element.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>elsigned</i><td valign="top">&nbsp;&nbsp;Set to non-0 if the source array elements are signed.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>elements</i><td valign="top">&nbsp;&nbsp;The number of elements in the array<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.47">2.3.47  cbf_set_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.51">2.3.51  cbf_set_integervalue</A><br />
<A HREF="#2.3.53">2.3.53  cbf_set_doublevalue</A><br />
<A HREF="#2.3.54">2.3.54  cbf_get_integerarrayparameters,  cbf_get_integerarrayparameters_wdims, cbf_get_realarrayparameters, cbf_get_realarrayparameters_wdims</A><br />
<A HREF="#2.3.55">2.3.55  cbf_get_integerarray, cbf_get_realarray</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.64">2.3.64  cbf_require_column_doublevalue</A><br />

<p><hr /><P>
<h4><A NAME="2.3.57">2.3.57  cbf_failnez</A></h4>
<p>
<b>DEFINITION</b>
<p>
#include &quot;cbf.h&quot;<p>

#define cbf_failnez(f) {int err; err = (f); if (err) return err; }
<p>
<b>DESCRIPTION</b>
<p>
cbf_failnez is a macro used for error propagation throughout CBFlib.  cbf_failnez
executes the function <i>f</i>
 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
<p>
CBFlib error <i>f</i> in &quot;<i>symbol</i>&quot;
<p>
where <i>f</i> is the decimal value of the error and  <i>symbol</i> is the symbolic
form.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>f</i><td valign="top">&nbsp;&nbsp;Integer error value.<br />
</TABLE>
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.58">2.3.58  cbf_onfailnez</A><br />
<p><hr /><P>
<h4><A NAME="2.3.58">2.3.58  cbf_onfailnez</A></h4>
<p><b>DEFINITION</b>
<p>
#include &quot;cbf.h&quot;<p>

#define cbf_onfailnez(f,c) {int err; err = (f); if (err) {{c; }return err; }}
<p>
<b>DESCRIPTION</b>
<p>
cbf_onfailnez is a macro used for error propagation throughout CBFlib.
cbf_onfailnez executes the function <i>f</i>
and saves the returned error value.  If the error value is non-0,
cbf_failnez executes first the statement <i>c</i>
 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
<p>
CBFlib error <i>f</i> in &quot;<i>symbol</i>&quot;
<p>
where <i>f</i> is the decimal value of the error and  <i>symbol</i> is the symbolic
form.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>f</i><td valign="top">&nbsp;&nbsp;integer function to execute.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>c</i><td valign="top">&nbsp;&nbsp;statement to execute on failure.<br />
</TABLE>
<p><b>SEE ALSO</b>
<LI><A HREF="#2.3.57">2.3.57   cbf_failnez</A>



<p><hr /><P>
<h4><A NAME="2.3.59">2.3.59   cbf_require_datablock</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_require_datablock (cbf_handle  <i>handle</i>,
                             const char *<i>datablockname</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_require_datablock makes the data block with name <i>datablockname</i>
 the current data block, if it exists, or creates it if it does not.
<p>
The comparison is case-insensitive.
<p>
The current category becomes undefined.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>datablockname</i><td valign="top">&nbsp;&nbsp;The name of the data block to find
or create.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.21">2.3.21  cbf_rewind_datablock</A><br />
<A HREF="#2.3.25">2.3.25  cbf_next_datablock</A><br />
<A HREF="#2.3.30">2.3.29  cbf_find_datablock</A><br />
<A HREF="#2.3.30">2.3.30  cbf_find_category, cbf_find_saveframe, cbf_find_blockitem</A><br />
<A HREF="#2.3.31">2.3.31  cbf_find_column</A><br />
<A HREF="#2.3.32">2.3.32  cbf_find_row</A><br />
<A HREF="#2.3.42">2.3.42  cbf_datablock_name</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />


<p><hr /><P>
<h4><A NAME="2.3.60">2.3.60   cbf_require_category</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_require_category (cbf_handle  <i>handle</i>,
                             const char *<i>categoryname</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_rewuire_category makes the category in the current data block with
name <i>categoryname</i> the current category, if it exists, or creates
the catagory if it does not exist.
<p>
The comparison is case-insensitive.
<p>
The current column and row become undefined.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>categoryname</i><td valign="top">&nbsp;&nbsp;The name of the category to find.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.22">2.3.22  cbf_rewind_category, cbf_rewind_saveframe, cbf_rewind_blockitem</A><br />
<A HREF="#2.3.26">2.3.26  cbf_next_category, cbf_next_saveframe, cbf_next_blockitem</A><br />
<A HREF="#2.3.29">2.3.29  cbf_find_datablock</A><br />
<A HREF="#2.3.31">2.3.31  cbf_find_column</A><br />
<A HREF="#2.3.32">2.3.32  cbf_find_row</A><br />
<A HREF="#2.3.43">2.3.43  cbf_category_name</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.61">2.3.61  cbf_require_column</A><br />

							
<p><hr /><P>
<h4><A NAME="2.3.61">2.3.61   cbf_require_column</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_require_column (cbf_handle  <i>handle</i>,
                             const char *<i>columnname</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_require_column makes the columns in the current category with
name <i>columnname</i> the current column, if it exists,
or creates it if it does not.
<p>
The comparison is case-insensitive.
<p>
The current row is not affected.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>columnname</i><td valign="top">&nbsp;&nbsp;The name of column to find.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.19">2.3.19  cbf_rewind_column</A><br />
<A HREF="#2.3.27">2.3.27  cbf_next_column</A><br />
<A HREF="#2.3.29">2.3.29  cbf_find_datablock</A><br />
<A HREF="#2.3.30">2.3.30  cbf_find_category, cbf_find_saveframe, cbf_find_blockitem</A><br />
<A HREF="#2.3.32">2.3.32  cbf_find_row</A><br />
<A HREF="#2.3.44">2.3.44  cbf_column_name, cbf_set_column_name</A><br />
<A HREF="#2.3.59">2.3.59  cbf_require_datablock</A><br />
<A HREF="#2.3.60">2.3.60  cbf_require_category</A><br />



<p><hr /><P>
<h4><A NAME="2.3.62">2.3.62  cbf_require_column_value</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_require_column_value (cbf_handle <i>handle</i>,
const char *<i>columnname</i>,
const char **<i>value</i>,
const char *<i>defaultvalue</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_require_column_doublevalue
sets *<i>value</i>
 to the ASCII item at the current row for the column given
 with the name given by *<i>columnname</i>, or to the string
 given by <i>defaultvalue</i> if the
 item cannot be found.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>columnname</i><td valign="top">&nbsp;&nbsp;Name of the column containing the number.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>value</i><td valign="top">&nbsp;&nbsp;pointer to the location to receive the value.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>defaultvalue</i><td valign="top">&nbsp;&nbsp;Value to use if the requested
column and value cannot be found.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.47">2.3.47  cbf_set_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.51">2.3.51  cbf_set_integervalue</A><br />
<A HREF="#2.3.52">2.3.52  cbf_get_doublevalue, cbf_require_doublevalue</A><br />
<A HREF="#2.3.56">2.3.56  cbf_set_integerarray, cbf_set_integerarray_wdims, cbf_set_realarray, cbf_set_realarray_wdims</A><br />
<A HREF="#2.3.62">2.3.63  cbf_require_column_integervalue</A><br />
<A HREF="#2.3.63">2.3.64  cbf_require_column_doublevalue</A><br />




<p><hr /><P>
<h4><A NAME="2.3.63">2.3.63  cbf_require_column_integervalue</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_require_column_integervalue (cbf_handle <i>handle</i>,
const char *<i>columnname</i>,
int *<i>number</i>,
const int <i>defaultvalue</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_require_column_doublevalue
sets *<i>number</i>
 to the value of the ASCII item at the current row for the column given
 with the name given by *<i>columnname</i>, with the value interpreted as an
integer number, or to the number given by <i>defaultvalue</i> if the
item cannot be found.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>columnname</i><td valign="top">&nbsp;&nbsp;Name of the column containing the number.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>number</i><td valign="top">&nbsp;&nbsp;pointer to the location to receive the integer value.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>defaultvalue</i><td valign="top">&nbsp;&nbsp;Value to use if the requested
column and value cannot be found.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.47">2.3.47  cbf_set_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.51">2.3.51  cbf_set_integervalue</A><br />
<A HREF="#2.3.52">2.3.52  cbf_get_doublevalue, cbf_require_doublevalue</A><br />
<A HREF="#2.3.56">2.3.56  cbf_set_integerarray, cbf_set_integerarray_wdims, cbf_set_realarray, cbf_set_realarray_wdims</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.64  cbf_require_column_doublevalue</A><br />



<p><hr /><P>
<h4><A NAME="2.3.64">2.3.64  cbf_require_column_doublevalue</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_require_column_doublevalue (cbf_handle <i>handle</i>,
const char *<i>columnname</i>,
double *<i>number</i>,
const double <i>defaultvalue</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_require_column_doublevalue
sets *<i>number</i>
 to the value of the ASCII item at the current row for the column given
 with the name given by *<i>columnname</i>, with the value interpreted as a decimal
floating-point number, or to the number given by <i>defaultvalue</i> if the
item cannot be found.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>columnname</i><td valign="top">&nbsp;&nbsp;Name of the column containing the number.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>number</i><td valign="top">&nbsp;&nbsp;pointer to the location to receive the floating-point value.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>defaultvalue</i><td valign="top">&nbsp;&nbsp;Value to use if the requested
column and value cannot be found.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.3.46">2.3.46  cbf_get_value, cbf_require_value</A><br />
<A HREF="#2.3.47">2.3.47  cbf_set_value</A><br />
<A HREF="#2.3.48">2.3.48  cbf_get_typeofvalue</A><br />
<A HREF="#2.3.49">2.3.49  cbf_set_typeofvalue</A><br />
<A HREF="#2.3.51">2.3.51  cbf_set_integervalue</A><br />
<A HREF="#2.3.52">2.3.52  cbf_get_doublevalue, cbf_require_doublevalue</A><br />
<A HREF="#2.3.56">2.3.56  cbf_set_integerarray, cbf_set_integerarray_wdims, cbf_set_realarray, cbf_set_realarray_wdims</A><br />
<A HREF="#2.3.62">2.3.62  cbf_require_column_value</A><br />
<A HREF="#2.3.63">2.3.63  cbf_require_column_integervalue</A><br />


<p><hr /><P>
<h4><A NAME="2.3.65">2.3.65  cbf_get_local_integer_byte_order,  
cbf_get_local_real_byte_order, cbf_get_local_real_format </A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_get_local_integer_byte_order (char ** <i>byte_order</i>);<br />
int cbf_get_local_real_byte_order (char ** <i>byte_order</i>);<br />
int cbf_get_local_real_format (char ** <i>real_format</i> );
<p>
<b>DESCRIPTION</b>
<p>cbf_get_local_integer_byte_order returns the byte order of integers
on the machine on which the API is being run in the form of a character string 
returned as the value pointed to by <i>byte_order</i>. cbf_get_local_real_byte_order 
returns the byte order of reals on the machine on which the API is being run 
in the form of a character string  returned as the value pointed to by <i>byte_order</i>. 
cbf_get_local_real_format returns the format of floats on the machine on which 
the API is being run in the form of a character string returned as the value pointed to by
<i>real_format</i>.  The strings returned must not be modified in any way.
<P>
The values returned in <i>byte_order</i> may be the strings &quot;little_endian&quot;
or &quot;big-endian&quot;.  The values returned in <i>real_format</i> may be the strings
&quot;ieee 754-1985&quot; or &quot;other&quot;.  Additional values may be returned
by future versions of the API.
<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>byte_order</i><td valign="top">&nbsp;&nbsp;pointer to the returned string<br />
<TR><td valign="top">&nbsp;&nbsp;<i>real_format</i><td valign="top">&nbsp;&nbsp;pointer to the returned string<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.

<p><hr /><P>

<h4><A NAME="2.3.66">2.3.66  cbf_get_dictionary, cbf_set_dictionary, cbf_require_dictionary</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_get_dictionary (cbf_handle <i>handle</i>, cbf_handle * <i>dictionary</i>);<br />
int cbf_set_dictionary (cbf_handle <i>handle</i>, cbf_handle <i>dictionary_in</i>);<br />
int cbf_require_dictionary (cbf_handle <i>handle</i>, cbf_handle * <i>dictionary</i>)
<P>
<b>DESCRIPTION</b>
<p>
cbf_get_dictionary sets *<i>dictionary</i> to the handle of a CBF which has been 
associated with the CBF <i>handle</i> by cbf_set_dictionary.  cbf_set_dictionary
associates the CBF handle <i>dictionary_in</i> with <i>handle</i> as its dictionary.
cbf_require_dictionary sets *<i>dictionary</i> to the handle of a CBF which has been 
associated with the CBF <i>handle</i> by cbf_set_dictionary or creates a new
empty CBF and associates it with <i>handle</i>, returning the new handle in 
*<i>dictionary</i>.
<P>
<b>ARGUMENTS</b><br />
<table>
 <TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>dictionary</i><td valign="top">&nbsp;&nbsp;Pointer to CBF handle of dictionary.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>dictionary_in</i><td valign="top">&nbsp;&nbsp;CBF handle of dcitionary.<br />
</table>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.

<p><hr /><P>

<h4><A NAME="2.3.67">2.3.67 cbf_convert_dictionary</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_convert_dictionary (cbf_handle <i>handle</i>, cbf_handle <i>dictionary</i> )
<P>
<b>DESCRIPTION</b>
<p>
cbf_convert_dictionary converts <i>dictionary</i> as a DDL1 or DDL2 dictionary to
a CBF dictionary of category and item properties for <i>handle</i>, creating
a new dictionary if none exists or layering the definitions in  <i>dictionary</i>
onto the existing dictionary of <i>handle</i> if one exists.
<P>
If a CBF is read into <i>handle</i> after calling cbf_convert_dictionary, then
the dictionary will be used for validation of the CBF as it is read.
<P>
<b>ARGUMENTS</b><br />
<table>
 <TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>dictionary</i><td valign="top">&nbsp;&nbsp;CBF handle of dictionary.<br />
</table>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.

<p><hr /><P>


<h4><A NAME="2.3.68">2.3.68 cbf_find_tag, cbf_find_local_tag</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_find_tag (cbf_handle <i>handle</i>, const char *<i>tag</i>)<br />
int cbf_find_local_tag (cbf_handle <i>handle</i>, const char *<i>tag</i>)

<P>
<b>DESCRIPTION</b>
<p>

cbf_find_tag searches all of the CBF <i>handle</i> for the CIF tag given
by the string <i>tag</i> and makes it the current tag.  The search does
not include the dictionary, but does include save frames as well as
categories.
<P>
The string <i>tag</i> is the complete tag in either DDL1 or DDL2 format,
starting with the leading underscore, not just a category or column.
<P>
<b>ARGUMENTS</b><br />
<table>
 <TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>tag</i><td valign="top">&nbsp;&nbsp;CIF tag.<br />
</table>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.

<p><hr /><P>



<h4><A NAME="2.3.69">2.3.69 cbf_find_category_root, cbf_set_category_root, cbf_require_category_root</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_find_category_root (cbf_handle <i>handle</i>, const char* <i>categoryname</i>,
                                            const char** <i>categoryroot</i>);<br />
int cbf_set_category_root (cbf_handle <i>handle</i>, const char* <i>categoryname_in</i>,
                                            const char*<i>categoryroot</i>);<br />
int cbf_require_category_root (cbf_handle handle, const char* <i>categoryname</i>,
                                            const char** <i>categoryroot</i>);

<P>
<b>DESCRIPTION</b>
<p>
cbf_find_category_root sets *<i>categoryroot</i> to the root category
of which <i>categoryname</i> is an alias.   cbf_set_category_root
sets <i>categoryname_in</i> as an alias of <i>categoryroot</i> in the
dictionary associated with <i>handle</i>, creating the dictionary
if necessary.  cbf_require_category_root sets *<i>categoryroot</i> 
to the root category of which <i>categoryname</i> is an alias, if
there is one, or to the value of <i>categoryname</i>, if 
<i>categoryname</i> is not an alias. 
<P>
A returned <i>categoryroot</i> string must not be modified in any way.
<P>
<b>ARGUMENTS</b><br />
<table>
 <TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>categoryname</i><td valign="top">&nbsp;&nbsp;category name which may be an alias.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>categoryroot</i><td valign="top">&nbsp;&nbsp;pointer to a returned category root name.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>categoryroot_in</i><td valign="top">&nbsp;&nbsp;input category root name.<br />
</table>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.

<p><hr /><P>


<h4><A NAME="2.3.70">2.3.70 cbf_find_tag_root, cbf_set_tag_root, cbf_require_tag_root</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_find_tag_root (cbf_handle <i>handle</i>, const char* <i>tagname</i>,
                                            const char** <i>tagroot</i>);<br />
int cbf_set_tag_root (cbf_handle <i>handle</i>, const char* <i>tagname</i>,
                                            const char*<i>tagroot_in</i>);<br />
int cbf_require_tag_root (cbf_handle handle, const char* <i>tagname</i>,
                                            const char** <i>tagroot</i>);

<P>
<b>DESCRIPTION</b>
<p>
cbf_find_tag_root sets *<i>tagroot</i> to the root tag
of which <i>tagname</i> is an alias.   cbf_set_tag_root
sets <i>tagname</i> as an alias of <i>tagroot_in</i> in the
dictionary associated with <i>handle</i>, creating the dictionary
if necessary.  cbf_require_tag_root sets *<i>tagroot</i> 
to the root tag of which <i>tagname</i> is an alias, if
there is one, or to the value of <i>tagname</i>, if 
<i>tagname</i> is not an alias. 
<P>
A returned <i>tagroot</i> string must not be modified in any way.
<P>
<b>ARGUMENTS</b><br />
<table>
 <TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>tagname</i><td valign="top">&nbsp;&nbsp;tag name which may be an alias.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>tagroot</i><td valign="top">&nbsp;&nbsp;pointer to a returned tag root name.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>tagroot_in</i><td valign="top">&nbsp;&nbsp;input tag root name.<br />
</table>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.

<p><hr /><P>

<h4><A NAME="2.3.71">2.3.71 cbf_find_tag_category, cbf_set_tag_category</A></h4>
<p><b>PROTOTYPE</b>
<p>
#include &quot;cbf.h&quot;<p>

int cbf_find_tag_category (cbf_handle <i>handle</i>, const char* <i>tagname</i>,
                                            const char** <i>categoryname</i>);<br />
int cbf_set_tag_category (cbf_handle <i>handle</i>, const char* tagname,
                                            const char* <i>categoryname_in</i>);
<P>
<b>DESCRIPTION</b>
<p>
cbf_find_tag_category sets <i>categoryname</i> to the category associated
with <i>tagname</i> in the dictionary associated with <i>handle</i>.
cbf_set_tag_category upddates the dictionary associated with <i>handle</i>
to indicated that <i>tagname</i> is in category <i>categoryname_in</i>.
<P>
<b>ARGUMENTS</b><br />
<table>
 <TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>tagname</i><td valign="top">&nbsp;&nbsp;tag name.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>categoryname</i><td valign="top">&nbsp;&nbsp;pointer to a returned category name.<br />
 <TR><td valign="top">&nbsp;&nbsp;<i>categoryname_in</i><td valign="top">&nbsp;&nbsp;input category name.<br />
</table>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.

<p>

<hr /><hr />
<p>
<h4><A NAME="2.4">2.4 High-level function prototypes</A></H4>
<p>
<h4><A NAME="2.4.1">2.4.1 cbf_read_template</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_read_template (cbf_handle <i>handle</i>, FILE <i>*file</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_read_template reads the CBF or CIF file <I>file</I> into the CBF object
specified by <I>handle</I> and selects the first datablock as the current datablock.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;Pointer to a CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>file</i><td valign="top">&nbsp;&nbsp;Pointer to a file descriptor.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.

<p><hr /><P>
<h4><A NAME="2.4.2">2.4.2 cbf_get_diffrn_id, cbf_require_diffrn_id</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_diffrn_id (cbf_handle <i>handle</i>, const char **<i>diffrn_id</i>);<br />
int cbf_require_diffrn_id (cbf_handle <i>handle</i>, const char **<i>diffrn_id</i>, const char *<i>default_id</i>)
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_diffrn_id sets *<I>diffrn_id</I> to point to the ASCII value of the 
&quot;diffrn.id&quot; entry.
cbf_require_diffrn_id also sets *<I>diffrn_id</I> to point to the ASCII value of the 
&quot;diffrn.id&quot; entry, but, if the &quot;diffrn.id&quot; entry does not exist,
it sets the value in the CBF and in*<I>diffrn_id</I> to the character string given by 
<i>default_id</i>, creating the category and column is necessary.
<p>
The <I>diffrn_id</I> will be valid as long as the item exists and has not been set to a new value.
<p>
The <I>diffrn_id</I> must not be modified by the program in any way.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>diffrn_id</i><td valign="top">&nbsp;&nbsp;Pointer to the destination value pointer.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>default_id</i><td valign="top">&nbsp;&nbsp;Character string default value.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.3">2.4.3 cbf_set_diffrn_id</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_diffrn_id (cbf_handle <i>handle</i>, const char *<i>diffrn_id</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_diffrn_id sets the &quot;diffrn.id&quot; entry of the current datablock to the ASCII value <i>diffrn_id</i>.
<p>
This function also changes corresponding &quot;diffrn_id&quot; entries in the &quot;diffrn_source&quot;, &quot;diffrn_radiation&quot;, &quot;diffrn_detector&quot; and &quot;diffrn_measurement&quot; categories.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>diffrn_id</i><td valign="top">&nbsp;&nbsp;ASCII value.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.4">2.4.4 cbf_get_crystal_id</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_crystal_id (cbf_handle <i>handle</i>, const char **<i>crystal_id</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_crystal_id sets *<i>crystal_id</i> to point to the ASCII value of the &quot;diffrn.crystal_id&quot; entry.
<p>
If the value is not ASCII, the function returns CBF_BINARY.
<p>
The value will be valid as long as the item exists and has not been set to a new value.
<p>
The value must not be modified by the program in any way.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>crystal_id</i><td valign="top">&nbsp;&nbsp;Pointer to the destination value pointer.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.5">2.4.5 cbf_set_crystal_id</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_crystal_id (cbf_handle <i>handle</i>, const char *<i>crystal_id</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_crystal_id sets the &quot;diffrn.crystal_id&quot; entry to the ASCII value <i>crystal_id</i>.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>crystal_id</i><td valign="top">&nbsp;&nbsp;ASCII value.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.6">2.4.6 cbf_get_wavelength</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_wavelength (cbf_handle <i>handle</i>, double *<i>wavelength</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_wavelength sets *<i>wavelength</i> to the current wavelength in &Aring;.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>wavelength</i><td valign="top">&nbsp;&nbsp;Pointer to the destination.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.7">2.4.7 cbf_set_wavelength</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_wavelength (cbf_handle <i>handle</i>, double <i>wavelength</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_wavelength sets the current wavelength in &Aring; to <i>wavelength</i>.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>wavelength</i><td valign="top">&nbsp;&nbsp;Wavelength in &Aring;.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.8">2.4.8 cbf_get_polarization</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_polarization (cbf_handle <i>handle</i>, double *<i>polarizn_source_ratio</i>,
double *<i>polarizn_source_norm</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_polarization sets *<i>polarizn_source_ratio</i> and *<i>polarizn_source_norm</i>
to the corresponding source polarization parameters.
<p>
Either destination pointer may be NULL.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>polarizn_source_ratio</i><td valign="top">&nbsp;&nbsp;Pointer to the destination polarizn_source_ratio.
<TR><td valign="top">&nbsp;&nbsp;<i>polarizn_source_norm</i><td valign="top">&nbsp;&nbsp;Pointer to the destination polarizn_source_norm.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.9">2.4.9 cbf_set_polarization
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_polarization (cbf_handle <i>handle</i>, double <i>polarizn_source_ratio</i>,
double <i>polarizn_source_norm</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_polarization sets the source polarization to the values specified by <i>polarizn_source_ratio</i> and <i>polarizn_source_norm</i>.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>polarizn_source_ratio</i><td valign="top">&nbsp;&nbsp;New value of polarizn_source_ratio.
<TR><td valign="top">&nbsp;&nbsp;<i>polarizn_source_norm</i><td valign="top">&nbsp;&nbsp;New value of polarizn_source_norm.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.10">2.4.10 cbf_get_divergence</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_divergence (cbf_handle <i>handle</i>, double *<i>div_x_source</i>, double *<i>div_y_source</i>,
	double *<i>div_x_y_source</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_divergence sets *<i>div_x_source</i>, *<i>div_y_source</i> and *<i>div_x_y_source</i> to the corresponding source divergence parameters.
<p>
Any of the destination pointers may be NULL.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>div_x_source</i><td valign="top">&nbsp;&nbsp;Pointer to the destination div_x_source.
<TR><td valign="top">&nbsp;&nbsp;<i>div_y_source</i><td valign="top">&nbsp;&nbsp;Pointer to the destination div_y_source.
<TR><td valign="top">&nbsp;&nbsp;<i>div_x_y_source</i><td valign="top">&nbsp;&nbsp;Pointer to the destination div_x_y_source.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.11">2.4.11 cbf_set_divergence</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_divergence (cbf_handle <i>handle</i>, double <i>div_x_source</i>, double <i>div_y_source</i>,
	double <i>div_x_y_source</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_divergence sets the source divergence parameters to the values specified by <i>div_x_source</i>, <i>div_y_source</i> and <i>div_x_y_source</i>.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>div_x_source</i><td valign="top">&nbsp;&nbsp;New value of div_x_source.
<TR><td valign="top">&nbsp;&nbsp;<i>div_y_source</i><td valign="top">&nbsp;&nbsp;New value of div_y_source.
<TR><td valign="top">&nbsp;&nbsp;<i>div_x_y_source</i><td valign="top">&nbsp;&nbsp;New value of div_x_y_source.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.12">2.4.12 cbf_count_elements</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_count_elements (cbf_handle <i>handle</i>, unsigned int *<i>elements</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_count_elements sets *<i>elements</i>  to the number of detector elements.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>elements</i><td valign="top">&nbsp;&nbsp;Pointer to the destination count.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.13">2.4.13 cbf_get_element_number, cbf_get_element_id</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_element_number(cbf_handle <i>handle</i>, const char <i>*element_id</i>,
    const char <i>*array_id</i>,
    const char <i>*array_section_id</i>,
    unsigned int <i>*element_number</i>);<br />
int cbf_get_element_id (cbf_handle <i>handle</i>, unsigned int <i>element_number</i>, const char **<i>element_id</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_element_number sets <i>element_number</i> to a number that can be used
    in other cbf_simple calls to identify the detector element <i>element_id</i>
    and optionally the specific <i>array_id> and <i>array_section_id</i>.  
cbf_get_element_id sets *<i>element_id</i> to point to the ASCII value of the <i>element_number</i>'th &quot;diffrn_data_frame.detector_element_id&quot; entry, counting from 0.
    The <i>element_number</i> is the ordinal of the detector element in the
    DIFFRN_DETECTOR_ELEMENT category.  If an <i>array_section_id</a> is
    specified (i.e. is not NULL), the <i>element_number</i> is the sum of
    the ordinal of the detector element plus the number of detector elements
    multiplied by the ordinal of <i>array_section_id</i> for the specified
    <i>array_id> in the ARRAY_STRUCTURE_LIST_SECTION category.
<p>
If the detector element does not exist, the function returns CBF_NOTFOUND.
<p>
The <i>element_id</i> will be valid as long as the item exists and has not been set to a new value.
<p>
The <i>element_id</i> must not be modified by the program in any way.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.
<TR><td valign="top">&nbsp;&nbsp;<i>element_id</i><td valign="top">&nbsp;&nbsp;Pointer to the destination
    string for cbf_get_element_id, but the string itself for cbf_get_element_number.
<TR><td valign="top">&nbsp;&nbsp;<i>array_id</i><td valign="top">&nbsp;&nbsp;The optional array id or NULL.
<TR><td valign="top">&nbsp;&nbsp;<i>array_section_id</i><td valign="top">&nbsp;&nbsp;The optional
    array_section_id or NULL.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>


<h4><A NAME="2.4.14">2.4.14 cbf_get_gain</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_gain (cbf_handle <i>handle</i>, unsigned int <i>element_number</i>, double *<i>gain</i>, double *<i>gain_esd</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_gain sets *<i>gain</i> and *<i>gain_esd</i> to the corresponding gain parameters for element number <i>element_number</i>.
<p>
Either of the destination pointers may be NULL.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.
<TR><td valign="top">&nbsp;&nbsp;<i>gain</i><td valign="top">&nbsp;&nbsp;Pointer to the destination gain.
<TR><td valign="top">&nbsp;&nbsp;<i>gain_esd</i><td valign="top">&nbsp;&nbsp;Pointer to the destination gain_esd.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.15">2.4.15 cbf_set_gain</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_gain (cbf_handle <i>handle</i>, unsigned int <i>element_number</i>, double <i>gain</i>, double <i>gain_esd</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_gain sets the gain of element number <i>element_number</i> to the values specified by <i>gain</i> and <i>gain_esd</i>.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.
<TR><td valign="top">&nbsp;&nbsp;<i>gain</i><td valign="top">&nbsp;&nbsp;New gain value.
<TR><td valign="top">&nbsp;&nbsp;<i>gain_esd</i><td valign="top">&nbsp;&nbsp;New gain_esd value.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.16">2.4.16 cbf_get_overload</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_overload (cbf_handle <i>handle</i>, unsigned int <i>element_number</i>, double *<i>overload</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_overload sets *<i>overload</i> to the overload value for element number <i>element_number</i>.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.
<TR><td valign="top">&nbsp;&nbsp;<i>overload</i><td valign="top">&nbsp;&nbsp;Pointer to the destination overload.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.17">2.4.17 cbf_set_overload</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_overload (cbf_handle <i>handle</i>, unsigned int <i>element_number</i>, double <i>overload</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_overload sets the overload value of element number <i>element_number</i> to <i>overload</i>.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.
<TR><td valign="top">&nbsp;&nbsp;<i>overload</i><td valign="top">&nbsp;&nbsp;New overload value.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.18">2.4.18 cbf_get_integration_time</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_integration_time (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, double *<i>time</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_integration_time sets *<i>time</i> to the integration time in seconds.   The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>time</i><td valign="top">&nbsp;&nbsp;Pointer to the destination time.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.19">2.4.19 cbf_set_integration_time</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_integration_time (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, double <i>time</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_integration_time sets the integration time in seconds to the value specified by <i>time</i>.  The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>time</i><td valign="top">&nbsp;&nbsp;Integration time in seconds.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.20">2.4.20 cbf_get_timestamp</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_timestamp (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, double *<i>time</i>, int *<i>timezone</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_timestamp sets *<i>time</i> to the collection timestamp in seconds since January 1 1970.  *<i>timezone</i> is set to timezone difference from UTC in minutes.  The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>

Either of the destination pointers may be NULL.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>time</i><td valign="top">&nbsp;&nbsp;Pointer to the destination collection timestamp.
<TR><td valign="top">&nbsp;&nbsp;<i>timezone</i><td valign="top">&nbsp;&nbsp;Pointer to the destination timezone difference.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.21">2.4.21 cbf_set_timestamp</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_timestamp (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, double <i>time</i>, int <i>timezone</i>,
double <i>precision</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_timestamp sets the collection timestamp in seconds since January 1 1970 to the value specified by <i>time</i>.  The timezone difference from UTC in minutes is set to <i>timezone</i>.   If no timezone is desired, <i>timezone</i> should be CBF_NOTIM

EZONE.  The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
The precision of the new timestamp is specified by the value <i>precision</i> in seconds.  If <i>precision</i> is 0, the saved timestamp is assumed accurate to 1 second.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>time</i><td valign="top">&nbsp;&nbsp;Timestamp in seconds since January 1 1970.
<TR><td valign="top">&nbsp;&nbsp;<i>timezone</i><td valign="top">&nbsp;&nbsp;Timezone difference from UTC in minutes or CBF_NOTIMEZONE.
<TR><td valign="top">&nbsp;&nbsp;<i>precision</i><td valign="top">&nbsp;&nbsp;Timestamp precision in seconds.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.22">2.4.22 cbf_get_datestamp</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_datestamp (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, int *<i>year</i>, int *<i>month</i>, int *<i>day</i>,
int *<i>hour</i>, int *<i>minute</i>, double *<i>second</i>, int *<i>timezone</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_datestamp sets *<i>year</i>, *<i>month</i>, *<i>day</i>, *<i>hour</i>, *<i>minute</i> and *<i>second</i> to the corresponding values of the collection timestamp.  *<i>timezone</i> is set to timezone difference from UTC in minutes.  The parameter <

i>reserved</i> is presently unused and should be set to 0.
<p>
Any of the destination pointers may be NULL.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>year</i><td valign="top">&nbsp;&nbsp;Pointer to the destination timestamp year.
<TR><td valign="top">&nbsp;&nbsp;<i>month</i><td valign="top">&nbsp;&nbsp;Pointer to the destination timestamp month (1-12).
<TR><td valign="top">&nbsp;&nbsp;<i>day</i><td valign="top">&nbsp;&nbsp;Pointer to the destination timestamp day (1-31).
<TR><td valign="top">&nbsp;&nbsp;<i>hour</i><td valign="top">&nbsp;&nbsp;Pointer to the destination timestamp hour (0-23).
<TR><td valign="top">&nbsp;&nbsp;<i>minute</i><td valign="top">&nbsp;&nbsp;Pointer to the destination timestamp minute (0-59).
<TR><td valign="top">&nbsp;&nbsp;<i>second</i><td valign="top">&nbsp;&nbsp;Pointer to the destination timestamp second (0-60.0).
<TR><td valign="top">&nbsp;&nbsp;<i>timezone</i><td valign="top">&nbsp;&nbsp;Pointer to the destination timezone difference from UTC in minutes.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.23">2.4.23 cbf_set_datestamp</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_datestamp (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, int <i>year</i>, int <i>month</i>, int <i>day</i>, int <i>hour</i>,
int <i>minute</i>, double <i>second</i>, int <i>timezone</i>, double <i>precision</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_datestamp sets the collection timestamp in seconds since January 1 1970 to the value specified by <i>time</i>.  The timezone difference from UTC in minutes is set to <i>timezone</i>.   If no timezone is desired, <i>timezone</i> should be CBF_NOTIM

EZONE.  The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
The precision of the new timestamp is specified by the value <i>precision</i> in seconds.  If <i>precision</i> is 0, the saved timestamp is assumed accurate to 1 second.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>time</i><td valign="top">Timestamp in seconds since January 1 1970.
<TR><td valign="top">&nbsp;&nbsp;<i>timezone</i><td valign="top">Timezone difference from UTC in minutes or CBF_NOTIMEZONE.
<TR><td valign="top">&nbsp;&nbsp;<i>precision</i><td valign="top">Timestamp precision in seconds.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.24">2.4.24 cbf_set_current_timestamp</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_current_timestamp (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, int <i>timezone</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_current_timestamp sets the collection timestamp to the current time.  The timezone difference from UTC in minutes is set to <i>timezone</i>.   If no timezone is desired, <i>timezone</i> should be CBF_NOTIMEZONE.  If no timezone is used, the timest

amp will be UTC.  The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
The new timestamp will have a precision of 1 second.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused. &nbsp;&nbsp;Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>timezone</i><td valign="top">&nbsp;&nbsp;Timezone difference from UTC in minutes or CBF_NOTIMEZONE.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.25">2.4.25 cbf_get_image_size, cbf_get_image_size_fs, cbf_get_image_size_sf,<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_get_3d_image_size, cbf_get_3d_image_size_fs, cbf_get_3d_image_size_sf</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_image_size (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, unsigned int <i>element_number</i>,
size_t *<i>ndimslow</i>, size_t *<i>ndimfast</i>);<br />
int cbf_get_image_size_fs (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, unsigned int <i>element_number</i>,
size_t *<i>ndimfast</i>, size_t *<i>ndimslow</i>);<br />
int cbf_get_image_size_sf (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, unsigned int <i>element_number</i>,
size_t *<i>ndimslow</i>, size_t *<i>ndimfast</i>);<br />
&nbsp;<br />
int cbf_get_3d_image_size (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, unsigned int <i>element_number</i>,
size_t *<i>ndimslow</i>, size_t *<i>ndimmid</i>, size_t *<i>ndimfast</i>);<br />
int cbf_get_3d_image_size_fs (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, unsigned int <i>element_number</i>,
size_t *<i>ndimfast</i>, size_t *<i>ndimmid</i>, size_t *<i>ndimslow</i>);<br />
int cbf_get_3d_image_size_sf (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, unsigned int <i>element_number</i>,
size_t *<i>ndimslow</i>, size_t *<i>ndimmid</i>, size_t *<i>ndimfast</i>);

<p>
<b>DESCRIPTION</b>
<p>
cbf_get_image_size, cbf_get_image_size_fs and cbf_get_image_size_sf set *<i>ndimslow</i> and  *<i>ndimfast</i> to the slow and fast dimensions of the image array 
for element number <i>element_number</i>.   If the array is 1-dimensional, *<i>ndimslow</i> will be set 
to the array size and *<i>ndimfast</i> will be set to 1.  If the array is 3-dimensional an error code
will be returned.
cbf_get_3d_image_size, cbf_get_3d_image_size_fs and cbf_get_3d_image_size_sf set 
*<i>ndimslow</i>, *<i>ndimmid</i> and  *<i>ndimfast</i> to the slowest, next fastest and
fastest dimensions, respectively, of the 3D image array for element number <i>element_number</i>.  If the
array is 1-dimensional, *<i>ndimslow</i> will be set to the array size and *<i>ndimmid</i> and *<i>ndimfast</i> 
will be set to 1.  If the array is 2-dimensional *<i>ndimslow</i> and *<i>ndimmid</i> will be set as for
a call to cbf_get_image_size and *<i>ndimfast</i> will be set to 1.
<p>
The _fs calls give the dimensions in a fast-to-slow order.  The calls with no suffix and the
calls _sf calls give the dimensions in slow-to-fast order
<p>
Note that the ordering of dimensions is specified by values of the tag _array_structure_list.precedence
with a precedence of 1 for the fastest dimension, 2 for the next slower, etc., which is opposite to the 
ordering of the dimension arguments for these functions, except for the ones with the _fs suffix..
<p>
Any of the destination pointers may be NULL.
<p>
The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.
<TR><td valign="top">&nbsp;&nbsp;<i>ndimslow</i><td valign="top">&nbsp;&nbsp;Pointer to the destination slowest dimension.
<TR><td valign="top">&nbsp;&nbsp;<i>ndimmid</i><td valign="top">&nbsp;&nbsp;Pointer to the destination next faster dimension.
<TR><td valign="top">&nbsp;&nbsp;<i>ndimfast</i><td valign="top">&nbsp;&nbsp;Pointer to the destination fastest dimension.

</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.26">2.4.26 cbf_get_image, cbf_get_image_fs, cbf_get_image_sf,<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_get_real_image, cbf_get_real_image_fs, cbf_get_real_image_sf,<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_get_3d_image, cbf_get_3d_image_fs, cbf_get_3d_image_sf,<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_get_real_3d_image, cbf_get_real_3d_image_fs, cbf_get_real_3d_image_sf</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_image (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, int <i>elsign</i>, size_t <i>ndimslow</i>, size_t <i>ndimfast</i>);<br />
int cbf_get_image_fs (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, int <i>elsign</i>, size_t <i>ndimfast</i>, size_t <i>ndimslow</i>);<br />
int cbf_get_image_sf (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, int <i>elsign</i>, size_t <i>ndimslow</i>, size_t <i>ndimfast</i>);<br />
&nbsp;<br />
int cbf_get_real_image (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>,
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, size_t <i>ndimslow</i>, size_t <i>ndimfast</i>);<br />
int cbf_get_real_image_fs (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>,
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, size_t <i>ndimfast</i>, size_t <i>ndimslow</i>);<br />
int cbf_get_real_image_sf (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>,
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, size_t <i>ndimslow</i>, size_t <i>ndimfast</i>);<br />
&nbsp;<br />
int cbf_get_3d_image (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, int <i>elsign</i>, size_t <i>ndimslow</i>, size_t <i>ndimmid</i>, size_t <i>ndimfast</i>);<br />
int cbf_get_3d_image_fs (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, int <i>elsign</i>, size_t <i>ndimfast</i>, size_t <i>ndimmid</i>, size_t <i>ndimslow</i>);<br />
int cbf_get_3d_image_sf (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, int <i>elsign</i>, size_t <i>ndimslow</i>, size_t <i>ndimmid</i>, size_t <i>ndimfast</i>);<br />
&nbsp;<br />
int cbf_get_real_3d_image (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>,
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, size_t <i>ndimslow</i>, size_t <i>ndimmid</i>, size_t <i>ndimfast</i>);<br />
int cbf_get_real_3d_image_fs (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>,
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, size_t <i>ndimfast</i>, size_t <i>ndimmid</i>, size_t <i>ndimslow</i>);<br />
int cbf_get_real_3d_image_sf (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>,
unsigned int <i>element_number</i>, void *<i>array</i>,
size_t <i>elsize</i>, size_t <i>ndimslow</i>, size_t <i>ndimmid</i>, size_t <i>ndimfast</i>);<br />
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_image, cbf_get_image_fs and cbf_get_image_sf read the image array for element number <i>element_number</i> into an <i>array</i>.
The array consists of <i>ndimslow</i>&#215;<i>ndimfast</i> elements of <i>elsize</i> bytes each, starting at <i>array</i>.
The elements are signed if <i>elsign</i> is non-0 and unsigned otherwise.  cbf_get_real_image,
cbf_get_real_image_fs and cbf_get_real_image_sf
read the image array of IEEE doubles or floats for element number <i>element_number</i> 
into an <i>array</i>.  A real array is always signed.
cbf_get_3d_image, cbf_get_3d_image_fs and cbf_get_3d_image_sf read the 3D  image array for element number <i>element_number</i> into an <i>array</i>.
The array consists of <i>ndimslow</i>&#215;<i>ndimmid</i>&#215;<i>ndimfast</i> elements of <i>elsize</i> bytes each, 
starting at <i>array</i>.
The elements are signed if <i>elsign</i> is non-0 and unsigned otherwise.  cbf_get_real_3d_image, cbf_get_real_3d_image_fs, cbf_get_real_3d_image_sf
reads the 3D image array of IEEE doubles or floats for element number <i>element_number</i> 
into an <i>array</i>.  A real array is always signed.

<p>
The _fs calls give the dimensions in a fast-to-slow order.  The calls with no suffix and the
calls _sf calls give the dimensions in slow-to-fast order
<p>
The structure of the array as a 1-, 2- or 3-dimensional array should agree with the
structure of the array given in the ARRAY_STRUCTURE_LIST category.
If the array is 1-dimensional, <i>ndimslow</i> should be the array size and <i>ndimfast</i> and, for
the 3D calls, <i>ndimmid</i>, should be set to 1 both in the call and in the imgCIF
data being processed.  If the array is 2-dimensional and a 3D call
is used, <i>ndimslow</i> and <i>ndimmid</i> should be the array dimensions and <i>ndimfast</i>
should be set to 1 both in the call and in the imgCIF
data being processed.
<p>
If any element in the binary data can't fit into the destination element, the
destination is set the nearest possible value.
<p>
If the value is not binary, the function returns CBF_ASCII.
<p>
If the requested number of elements can't be read, the function will read as many as it
can and then return CBF_ENDOFDATA.
<p>
Currently, the destination <i>array</i> must consist of chars, shorts or ints (signed or unsigned)
for cbf_get_image, or IEEE doubles or floats for cbf_get_real_image. 
If <i>elsize</i> is not equal to sizeof (char), sizeof (short), sizeof (int), sizeof(double)
or sizeof(float), the function  returns CBF_ARGUMENT.
<p>
The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.
<TR><td valign="top">&nbsp;&nbsp;<i>array</i><td valign="top">&nbsp;&nbsp;Pointer to the destination array.
<TR><td valign="top">&nbsp;&nbsp;<i>elsize</i><td valign="top">&nbsp;&nbsp;Size in bytes of each destination array element.
<TR><td valign="top">&nbsp;&nbsp;<i>elsigned</i><td valign="top">&nbsp;&nbsp;Set to non-0 if the destination array elements are signed.
<TR><td valign="top">&nbsp;&nbsp;<i>ndimslow</i><td valign="top">&nbsp;&nbsp;Slowest array dimension.
<TR><td valign="top">&nbsp;&nbsp;<i>ndimmid</i><td valign="top">&nbsp;&nbsp;Next faster array dimension.
<TR><td valign="top">&nbsp;&nbsp;<i>ndimfast</i><td valign="top">&nbsp;&nbsp;Fastest array dimension.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.27">2.4.27 cbf_set_image, cbf_set_image_fs, cbf_set_image_sf,</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_set_real_image, cbf_set_real_image_fs, cbf_set_real_image_sf,<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_set_3d_image, cbf_set_3d_image_fs, cbf_set_3d_image_sf,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_set_real_3d_image, cbf_set_real_3d_image_fs, cbf_set_real_3d_image_sf</h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_image (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>, size_t <i>elsize</i>, 
int <i>elsign</i>, size_t <i>ndimslow</i>, size_t <i>ndimfast</i>);<br />
int cbf_set_image_fs(cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>, size_t <i>elsize</i>, 
int <i>elsign</i>, size_t <i>ndimfast</i>, size_t <i>ndimslow</i>);<br />
int cbf_set_image_sf(cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>, size_t <i>elsize</i>, 
int <i>elsign</i>, size_t <i>ndimslow</i>, size_t <i>ndimfast</i>);<br />
&nbsp;<br />
int cbf_set_real_image (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>,size_t <i>elsize</i>,
size_t <i>ndimslow</i>, size_t <i>ndimfast</i>);<br />
int cbf_set_real_image_fs(cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>,size_t <i>elsize</i>,
size_t <i>ndimfast</i>, size_t <i>ndimslow</i>);<br />
int cbf_set_real_image_sf(cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>,size_t <i>elsize</i>,
size_t <i>ndimslow</i>, size_t <i>ndimfast</i>);<br />
&nbsp;<br />
int cbf_set_3d_image (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>, size_t <i>elsize</i>, 
int <i>elsign</i>, size_t <i>ndimslow</i>, size_t <i>ndimmid</i>, size_t <i>ndimfast</i>);<br />
int cbf_set_3d_image_fs(cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>, size_t <i>elsize</i>, 
int <i>elsign</i>, size_t <i>ndimfast</i>, size_t <i>ndimmid</i>, size_t <i>ndimslow</i>);<br />
int cbf_set_3d_image_sf(cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>, size_t <i>elsize</i>, 
int <i>elsign</i>, size_t <i>ndimslow</i>, size_t <i>ndimmid</i>, size_t <i>ndimfast</i>);<br />
&nbsp;<br />
int cbf_set_real_3d_image (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>,size_t <i>elsize</i>,
size_t <i>ndimslow</i>, size_t <i>ndimmid</i>, size_t <i>ndimfast</i>);<br />
int cbf_set_real_3d_image_fs(cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>,size_t <i>elsize</i>,
size_t <i>ndimfast</i>, size_t <i>ndimmid</i>, size_t <i>ndimslow</i>);<br />
int cbf_set_real_3d_image_sf(cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, 
unsigned int <i>element_number</i>,
unsigned int compression, void *<i>array</i>,size_t <i>elsize</i>,
size_t <i>ndimslow</i>, size_t <i>ndimmid</i>, size_t <i>ndimfast</i>);<br />

<p>
<b>DESCRIPTION</b>
<p>
cbf_set_image, cbf_set_image_fs and cbf_set_image_sf write the image array for element number 
<i>element_number</i>.  The <i>array</i> 
consists of <i>ndimfast</i>&#215;<i>ndimslow</i> elements of <i>elsize</i> bytes each, starting 
at <i>array</i>.  The elements are signed if <i>elsign</i> is non-zero
and unsigned otherwise.  cbf_set_real_image, cbf_set_real_image_fs and cbf_set_real_image_sf 
write the image array for element number <i>element_number</i>.  The <i>array</i> 
consists of <i>ndimfast</i>&#215;<i>ndimslow</i> IEEE double or float elements of <i>elsize</i> 
bytes each, starting at <i>array</i>. 
cbf_set_3d_image, cbf_set_3d_image_fs and cbf_set_3d_image_sf write the 3D image array for 
element number <i>element_number</i>.  The <i>array</i> 
consists of <i>ndimfast</i>&#215;<i>ndimmid</i>&#215;<i>ndimslow</i> elements of <i>elsize</i> 
bytes each, starting at <i>array</i>.  The elements are signed if <i>elsign</i> is non-0
and unsigned otherwise.  cbf_set_real_3d_image, cbf_set_real_3d_image_fs and cbf_set_real_3d_image_sf
writes the 3D image array for element number <i>element_number</i>.  The <i>array</i> 
consists of <i>ndimfast</i>&#215;<i>ndimmid</i>&#215;<i>ndimslow</i> IEEE double or float elements of <i>elsize</i> 
bytes each, starting at <i>array</i>.
<p>
The _fs calls give the dimensions in a fast-to-slow order.  The calls with no suffix and the
calls _sf calls give the dimensions in slow-to-fast order
<p>
If the array is 1-dimensional, <i>ndimslow</i> should be the array size and <i>ndimfast</i> and,
for the 3D calls, <i>ndimmid</i>, should be set to 1.  If the array is 2-dimensional and
the 3D calls are used, <i>ndimslow</i> and <i>ndimmid</i> should be used for the array dimensions
and <i>ndimfast</i> should be set to 1.
<p>
The array will be compressed using the compression scheme specifed by compression.  Currently, 
the available schemes are:
<p>
<table>
<tr><td valign="top">CBF_CANONICAL<td valign="top">Canonical-code compression (section 3.3.1)
<tr><td valign="top">CBF_PACKED<td valign="top">CCP4-style packing (section 3.3.2)
<TR><td valign="top">CBF_PACKED_V2<td valign="top">&nbsp;&nbsp;CCP4-style packing, version 2   (section 3.3.2)
<TR><TD valign="top">CBF_BYTE_OFFSET<td valign="top">&nbsp;&nbsp;Simple &quot;byte_offset&quot; compression.
<TR><TD valign="top">CBF_NIBBLE_OFFSET<td valign="top">&nbsp;&nbsp;Simple &quot;nibble_offset&quot; compression.
<tr><td valign="top">CBF_NONE<td valign="top">No compression.
</table>
<p>
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.
<p>
Currently, the source <i>array</i> must consist of chars, shorts or ints (signed or unsigned)for 
cbf_set_image, or IEEE doubles or floats for cbf_set_real_image. 
If <i>elsize</i> is not equal to sizeof (short), sizeof (int), sizeof(double)
or sizeof(float), the function returns CBF_ARGUMENT.
<p>
The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.
<TR><td valign="top">&nbsp;&nbsp;<i>compression</i><td valign="top">&nbsp;&nbsp;Compression type.
<TR><td valign="top">&nbsp;&nbsp;<i>array</i><td valign="top">&nbsp;&nbsp;Pointer to the image array.
<TR><td valign="top">&nbsp;&nbsp;<i>elsize</i><td valign="top">&nbsp;&nbsp;Size in bytes of each image array element.
<TR><td valign="top">&nbsp;&nbsp;<i>elsigned</i><td valign="top">&nbsp;&nbsp;Set to non-0 if the image array elements are signed.
<TR><td valign="top">&nbsp;&nbsp;<i>ndimslow</i><td valign="top">&nbsp;&nbsp;Slowest array dimension.
<TR><td valign="top">&nbsp;&nbsp;<i>ndimmid</i><td valign="top">&nbsp;&nbsp;Second slowest array dimension.
<TR><td valign="top">&nbsp;&nbsp;<i>ndimfast</i><td valign="top">&nbsp;&nbsp;Fastest array dimension.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
    <h4><A NAME="2.4.28">2.4.28 cbf_count_axis_ancestors,
        cbf_get_axis_ancestor,
        cbf_get_axis_depends_on,<br />
        cbf_get_axis_equipment,
        cbf_get_axis_equipment_component,<br />
        cbf_get_axis_offset,<br />
        cbf_get_axis_rotation,
        cbf_get_axis_rotation_axis,<br />
        cbf_get_axis_setting,<br />
        cbf_get_axis_type,<br />
        cbf_get_axis_vector </A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_count_axis_ancestors (cbf_handle <i>handle</i>,
    const char *<i>axis_id</i>,
    unsigned int  *<i>ancestors</i>);<br />
<p>
int cbf_get_axis_ancestor (cbf_handle <i>handle</i>,
    const char *<i>axis_id</i>,
    const unsigned int <i>ancestor_index</i>,
    const char * *<i>ancestor</i>);<br />
<p>
int cbf_get_axis_depends_on (cbf_handle <i>handle</i>, const char *<i>axis_id</i>,
    const char * *<i>depends_on</i>);<br />
<p>
int cbf_get_axis_equipment (cbf_handle <i>handle</i>, const char *<i>axis_id</i>,
    const char * *<i>equipment</i>);<br />
<p>
int cbf_get_axis_equipment_component (cbf_handle <i>handle</i>,
    const char *<i>axis_id</i>,
    const char * *<i>equipment_component</i>);<br />
<p>
int cbf_get_axis_offset (cbf_handle <i>handle</i>, const char *<i>axis_id</i>,
    double *<i>offset1</i>,
    double *<i>offset2</i>,
    double *<i>offset3</i>);<br />
<p>
int cbf_get_axis_rotation (cbf_handle <i>handle</i>, const char *<i>axis_id</i>,
    double *<i>rotation</i>);<br />
<p>
int cbf_get_axis_rotation_axis (cbf_handle <i>handle</i>,
    const char *<i>axis_id</i>,
    const char * *<i>rotation_axis</i>);<br />
<p>
int cbf_get_axis_setting (cbf_handle <i>handle</i>, unsigned int <i>reserved</i>, const char *<i>axis_id</i>, double *<i>start</i>,
double *<i>increment</i>);<br />
<p>
int cbf_get_axis_type (cbf_handle <i>handle</i>, const char *<i>axis_id</i>,
    cbf_axis_type *<i>axis_type</i>);<br />
<p>
int cbf_get_axis_vector (cbf_handle <i>handle</i>, const char *<i>axis_id</i>,
    double *<i>vector1</i>,
    double *<i>vector2</i>,
    double *<i>vector3</i>);<br />
<p>
<b>DESCRIPTION</b>
<p>
cbf_count_axis_ancestors sets <i>ancestors</i> to the number of
ancestors of axis <i>axis_id</i>.
cbf_get_axis_ancestor sets *<i>ancestor</i> to the ancestor axis
of index <i>ancestor_index</i> of axis <i>axis_id</i>, starting
with <i>axis_id</i> for <i>ancestor_index</i> 0.
<p>
cbf_get_axis_depends_on sets *<i>depends_on</i> to the immediate
ancestor of <i>axis_id</i> or to &quot;.&quot; if there is no
such ancestor.
cbf_get_axis_equipment sets *<i>equipment</i> to the equipment of
    <i>axis_id</i> or to &quot;.&quot; if there is no
    such equipment.
cbf_get_axis_equipment_component sets *<i>equipment_component</i> to the equipment_component of
    <i>axis_id</i> or to &quot;.&quot; if there is no
    such equipment_component.
<p>
cbf_get_axis_offset sets *<i>offset1</i>, *<i>offset2</i> and
    *<i>offset3</i> to the components of the ofset of <i>axis_id</i>.
<p>
cbf_get_axis_rotation sets <i>rotation</i> to the rotation of
    <i>axis_id</i> or to 0 if there is no
    such rotation.
cbf_get_axis_rotation_axis sets *<i>rotation_axis</i> to the rotation_axis of
    <i>axis_id</i> or to &quot;.&quot; if there is no
    such rotation_axis.
<p>
cbf_get_axis_setting sets *<i>start</i> and *<i>increment</i> to the corresponding values of the axis <i>axis_id</i>.  Any of the destination pointers may be NULL.
<p>
cbf_get_axis_type sets <i>axis_type</i> to the type of <i>axis_id</i>.
<p>
cbf_get_axis_vector sets *<i>vector1</i>, *<i>vector2</i> and
    *<i>vector3</i> to the components of the vector of <i>axis_id</i>.
<p>
The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>axis_id</i><td valign="top">&nbsp;&nbsp;Axis id.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>ancestor_index</i><td valign="top">&nbsp;&nbsp;Integer index of the desired ancestor, starting with 0 for the current <i>axis_id</i>.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>ancestor</i><td valign="top">&nbsp;&nbsp;Pointer to destination ancestor name pointer.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>depends_on</i><td valign="top">&nbsp;&nbsp;Pointer to destination depends_on name pointer.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>equipment</i><td valign="top">&nbsp;&nbsp;Pointer to destination equipment name pointer.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>equipment_component</i><td valign="top">&nbsp;&nbsp;Pointer to destination equipment_component name pointer.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>offset1</i><td valign="top">&nbsp;&nbsp;Pointer to destination first offset component value.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>offset2</i><td valign="top">&nbsp;&nbsp;Pointer to destination second offset component value.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>offset3</i><td valign="top">&nbsp;&nbsp;Pointer to destination third offset component value.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>rotation</i><td valign="top">&nbsp;&nbsp;Pointer to destination rotation value.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>rotation_axis</i><td valign="top">&nbsp;&nbsp;Pointer to destination rotation_axisn name pointer.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>start</i><td valign="top">&nbsp;&nbsp;Pointer to the destination start value.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>increment</i><td valign="top">&nbsp;&nbsp;Pointer to the destination increment value.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>type</i><td valign="top">&nbsp;&nbsp;Pointer to destination axis type of type .</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>vector1</i><td valign="top">&nbsp;&nbsp;Pointer to destination first vector component value.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>vector2</i><td valign="top">&nbsp;&nbsp;Pointer to destination second vector component value.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>vector3</i><td valign="top">&nbsp;&nbsp;Pointer to destination third vector component value.</TR>

</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.29">2.4.29 cbf_set_axis_setting
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_axis_setting (cbf_handle <i>handle</i>, unsigned int  <i>reserved</i>, const char *<i>axis_id</i>, double <i>start</i>,
double <i>increment</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_axis_setting sets the starting and increment values of the axis <i>axis_id</i> to <i>start</i> and <i>increment</i>.
<p>
The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>axis_id</i><td valign="top">&nbsp;&nbsp;Axis id.
<TR><td valign="top">&nbsp;&nbsp;<i>start</i><td valign="top">&nbsp;&nbsp;Start value.
<TR><td valign="top">&nbsp;&nbsp;<i>increment</i><td valign="top">&nbsp;&nbsp;Increment value.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.30">2.4.30 cbf_construct_goniometer
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_construct_goniometer (cbf_handle <i>handle</i>, cbf_goniometer *<i>goniometer</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_construct_goniometer constructs a goniometer object using the description in the CBF object handle and initialises the goniometer handle *<i>goniometer</i>.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>goniometer</i><td valign="top">&nbsp;&nbsp;Pointer to the destination goniometer handle.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.31">2.4.31 cbf_free_goniometer</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_free_goniometer (cbf_goniometer <i>goniometer</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_free_goniometer destroys the goniometer object specified by <i>goniometer</i> and frees all associated memory.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>goniometer</i><td valign="top">&nbsp;&nbsp;Goniometer handle to free.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.32">2.4.32 cbf_get_rotation_axis
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_rotation_axis (cbf_goniometer <i>goniometer</i>, unsigned int <i>reserved</i>, double *<i>vector1</i>,
double *<i>vector2</i>, double *<i>vector3</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_rotation_axis sets *<i>vector1</i>, *<i>vector2</i>, and *<i>vector3</i> to the 3 components of the goniometer rotation axis used for the exposure.
<p>
Any of the destination pointers may be NULL.
<p>
The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>goniometer</i><td valign="top">&nbsp;&nbsp;Goniometer handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>vector1</i><td valign="top">&nbsp;&nbsp;Pointer to the destination x component of the rotation axis.
<TR><td valign="top">&nbsp;&nbsp;<i>vector2</i><td valign="top">&nbsp;&nbsp;Pointer to the destination y component of the rotation axis.
<TR><td valign="top">&nbsp;&nbsp;<i>vector3</i><td valign="top">&nbsp;&nbsp;Pointer to the destination z component of the rotation axis.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.33">2.4.33 cbf_get_rotation_range
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_rotation_range (cbf_goniometer <i>goniometer</i>, unsigned int  <i>reserved</i>, double *<i>start</i>,
double *<i>increment</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_rotation_range sets *<i>start</i> and *<i>increment</i> to the corresponding values of the goniometer rotation axis used for the exposure.
<p>
Either of the destination pointers may be NULL.
<p>
The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>goniometer</i><td valign="top">&nbsp;&nbsp;Goniometer handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>start</i><td valign="top">&nbsp;&nbsp;Pointer to the destination start value.
<TR><td valign="top">&nbsp;&nbsp;<i>increment</i><td valign="top">&nbsp;&nbsp;Pointer to the destination increment value.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.34">2.4.34 cbf_rotate_vector
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_rotate_vector (cbf_goniometer <i>goniometer</i>, unsigned int  <i>reserved</i>, double <i>ratio</i>, double <i>initial1</i>,
double <i>initial2</i>, double <i>initial3</i>, double *<i>final1</i>, double *<i>final2</i>, double *<i>final3</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_rotate_vector sets *<i>final1</i>, *<i>final2</i>, and *<i>final3</i> to the 3 components of the of the vector (<i>initial1</i>, <i>initial2</i>, <i>initial3</i>) after reorientation by applying the goniometer rotations.  The value <i>ratio</i> specif

ies 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.
<p>
Any of the destination pointers may be NULL.
<p>
The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>goniometer</i><td valign="top">&nbsp;&nbsp;Goniometer handle.
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.
<TR><td valign="top">&nbsp;&nbsp;<i>ratio</i><td valign="top">&nbsp;&nbsp;Goniometer setting.  0 = beginning of exposure, 1 = end.
<TR><td valign="top">&nbsp;&nbsp;<i>initial1</i><td valign="top">&nbsp;&nbsp;x component of the initial vector.
<TR><td valign="top">&nbsp;&nbsp;<i>initial2</i><td valign="top">&nbsp;&nbsp;y component of the initial vector.
<TR><td valign="top">&nbsp;&nbsp;<i>initial3</i><td valign="top">&nbsp;&nbsp;z component of the initial vector.
<TR><td valign="top">&nbsp;&nbsp;<i>final1</i><td valign="top">&nbsp;&nbsp;Pointer to the destination x component of the final vector.
<TR><td valign="top">&nbsp;&nbsp;<i>final2</i><td valign="top">&nbsp;&nbsp;Pointer to the destination y component of the final vector.
<TR><td valign="top">&nbsp;&nbsp;<i>final3</i><td valign="top">&nbsp;&nbsp;Pointer to the destination z component of the final vector.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.35">2.4.35 cbf_get_reciprocal
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_reciprocal (cbf_goniometer <i>goniometer</i>, unsigned int  <i>reserved</i>, double <i>ratio</i>,
double <i>wavelength</i>, double <i>real1</i>, double <i>real2</i>, double <i>real3</i>, double *<i>reciprocal1</i>,
double *<i>reciprocal2</i>, double *<i>reciprocal3</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_reciprocal sets *<i>reciprocal1</i>, * <i>reciprocal2</i>, and * <i>reciprocal3</i> to the 3 components of the of the reciprocal-space vector corresponding to the real-space vector (<i>real1</i>, <i>real2</i>, <i>real3</i>).  The reciprocal-space
vector is oriented to correspond to the goniometer setting with all axes at 0.  The value <i>wavelength</i> is the wavlength in &Aring; and the value <i>ratio</i> specifies the current goniometer setting and varies from 0.0 at the beginning of the exposur

e to 1.0 at the end, irrespective of the actual rotation range.
<p>
Any of the destination pointers may be NULL.
<p>
The parameter <i>reserved</i> is presently unused and should be set to 0.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>goniometer</i><td valign="top">&nbsp;&nbsp;Goniometer handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>reserved</i><td valign="top">&nbsp;&nbsp;Unused.  Any value other than 0 is invalid.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>ratio</i><td valign="top">&nbsp;&nbsp;Goniometer setting.  0 = beginning of exposure, 1 = end.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>wavelength</i><td valign="top">&nbsp;&nbsp;Wavelength in &Aring;.
<TR><td valign="top">&nbsp;&nbsp;<i>real1</i><td valign="top">&nbsp;&nbsp;x component of the real-space vector.
<TR><td valign="top">&nbsp;&nbsp;<i>real2</i><td valign="top">&nbsp;&nbsp;y component of the real-space vector.
<TR><td valign="top">&nbsp;&nbsp;<i>real3</i><td valign="top">&nbsp;&nbsp;z component of the real-space vector.
<TR><td valign="top">&nbsp;&nbsp;<i>reciprocal1</i><td valign="top">&nbsp;&nbsp;Pointer to the destination x component of the reciprocal-space vector.
<TR><td valign="top">&nbsp;&nbsp;<i>reciprocal2</i><td valign="top">&nbsp;&nbsp;Pointer to the destination y component of the reciprocal-space vector.
<TR><td valign="top">&nbsp;&nbsp;<i>reciprocal3</i><td valign="top">&nbsp;&nbsp;Pointer to the destination z component of the reciprocal-space vector.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.36">2.4.36 cbf_construct_detector, cbf_construct_reference_detector, cbf_require_reference_detector
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_construct_detector (cbf_handle <i>handle</i>, cbf_detector *<i>detector</i>, unsigned int <i>element_number</i>);
<p>
int cbf_construct_reference_detector (cbf_handle <i>handle</i>, cbf_detector *<i>detector</i>, unsigned int <i>element_number</i>);
<p>
int cbf_require_reference_detector (cbf_handle <i>handle</i>, cbf_detector *<i>detector</i>, unsigned int <i>element_number</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_construct_detector constructs a detector object for detector element number <i>element_number</i> 
using the description in the CBF object handle and initialises the detector handle *<i>detector</i>.
<p>
cbf_construct_reference_detector constructs a detector object for detector element number <i>element_number</i> 
using the description in the CBF object handle and initialises the detector handle *<i>detector</i> using the
reference settings of the axes.  cbf_require_reference_detector is similar, but try to force the
creations of missing intermediate categories needed to construct a detector object.

<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>detector</i><td valign="top">&nbsp;&nbsp;Pointer to the destination detector handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.37">2.4.37 cbf_free_detector</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_free_detector (cbf_detector <i>detector</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_free_detector destroys the detector object specified by <i>detector</i> and frees all associated memory.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>detector</i><td valign="top">&nbsp;&nbsp;Detector handle to free.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>

<h4><A NAME="2.4.38">2.4.38 cbf_construct_positioner, cbf_construct_reference_positioner,
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_construct_positioner (cbf_handle <i>handle</i>, cbf_positioner *<i>positioner</i>, const char *<i>axis_id</i>);
<p>
int cbf_construct_reference_positioner (cbf_handle <i>handle</i>, cbf_positioner *<i>positioner</i>, const char *<i>axis_id</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_construct_positioner constructs a positioner object for the axis given by <i>axis_id</i> 
using the description in the CBF object handle and initialises the positioner handle *<i>positioner</i>.
<p>
cbf_construct_reference positioner constructs a positioner object for the axis given by <i>axis_id</i> 
using the description in the CBF object handle and initialises the detector handle *<i>detector</i> using the
reference settings of the axes.

<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>positioner</i><td valign="top">&nbsp;&nbsp;Pointer to the destination positioner handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>axis_id</i><td valign="top">&nbsp;&nbsp;The identifier of the axis in the &quot;axis&quot; category.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.39">2.4.39 cbf_free_positioner</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_free_positioner (cbf_positioner <i>positioner</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_free_positioner destroys the positioner object specified by <i>positioner</i> and frees all associated memory.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>positioner</i><td valign="top">&nbsp;&nbsp;Positioner handle to free.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>



<h4><A NAME="2.4.40">2.4.40 cbf_get_beam_center, cbf_get_beam_center_fs, cbf_get_beam_center_sf,<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_set_beam_center, cbf_set_beam_center_fs, cbf_set_beam_center_sf,<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cbf_set_reference_beam_center, cbf_set_reference_beam_center_fs, cbf_set_reference_beam_center_sf
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_beam_center (cbf_detector <i>detector</i>, double *<i>indexslow</i>, double *<i>indexfast</i>, double *<i>centerslow</i>,
double *<i>centerfast</i>);<br />
int cbf_get_beam_center_fs (cbf_detector <i>detector</i>, double *<i>indexfast</i>, double *<i>indexslow</i>, double *<i>centerfast</i>,
double *<i>centerslow</i>);<br />
int cbf_get_beam_center_sf (cbf_detector <i>detector</i>, double *<i>indexslow</i>, double *<i>indexfast</i>, double *<i>centerslow</i>,
double *<i>centerfast</i>);
<p>
int cbf_set_beam_center (cbf_detector <i>detector</i>, double *<i>indexslow</i>, double *<i>indexfast</i>, double *<i>centerslow</i>,
double *<i>centerfast</i>);<br />
int cbf_set_beam_center_fs (cbf_detector <i>detector</i>, double *<i>indexfast</i>, double *<i>indexslow</i>, double *<i>centerfast</i>,
double *<i>centerslow</i>);<br />
int cbf_set_beam_center_sf (cbf_detector <i>detector</i>, double *<i>indexslow</i>, double *<i>indexfast</i>, double *<i>centerslow</i>,
double *<i>centerfast</i>);
<p>
int cbf_set_reference_beam_center (cbf_detector <i>detector</i>, double *<i>indexslow</i>, double *<i>indexfast</i>, double *<i>centerslow</i>,
double *<i>centerfast</i>);<br />
int cbf_set_reference_beam_center_fs (cbf_detector <i>detector</i>, double *<i>indexfast</i>, double *<i>indexslow</i>, double *<i>centerfast</i>,
double *<i>centerslow</i>);<br />
int cbf_set_reference_beam_center_sf (cbf_detector <i>detector</i>, double *<i>indexslow</i>, double *<i>indexfast</i>, double *<i>centerslow</i>,
double *<i>centerfast</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_beam_center sets *<i>centerfast</i> and *<i>centerslow</i> to the displacements in mm
along the detector axes from pixel (0, 0) to the point at which the beam intersects the
detector and *<i>indexfast</i> and *<i>indexslow</i> to the corresponding indices.
cbf_set_beam_center sets the offsets in the axis category for the detector element
axis with precedence 1 to place the beam center at the position given in mm by *<i>centerfast</i>
and *<i>centerslow</i> as the displacements in mm along the detector axes from pixel (0, 0)
to the point at which the beam intersects the detector at the indices given  *<i>indexfast</i> and
*<i>indexslow</i>.  cbf_set_reference_beam_center sets the displacments in the array_structure_list_axis
category to place the beam center at the position given in mm by *<i>centerfast</i>
and *<i>centerslow</i> as the displacements in mm along the detector axes from pixel (0, 0)
to the point at which the beam intersects the detector at the indices given  by *<i>indexfast</i> and
*<i>indexslow</i>.  In order to achieve consistent results, a reference detector should be used
for <i>detector</i> to have all axes at their reference settings.
<p>
Note that the precedence 1 axis is the fastest axis, so that *<i>centerfast</i> and *<i>indexfast</i>
are the fast axis components of the center and *<i>centerslow</i> and *<i>indexslow</i> are the
slow axis components of the center.
<p>
The _fs calls give the displacments in a fast-to-slow order.  The calls with no suffix and the
calls _sf calls give the displacements in slow-to-fast order
<p>
Any of the destination pointers may be NULL for getting the beam center.  For setting the beam
axis, either the indices of the center must not be NULL.
<p>
The indices are non-negative for beam centers within the detector surface, but the center for an axis with
a negative increment will be negative for a beam center within the detector surface.
<p>
For cbf_set_beam_center if the diffrn_data_frame category exists with a row for the corresponding element id,
the values will be set for _diffrn_data_frame.center_fast and _diffrn_data_frame.center_slow
in millimetres and the value of _diffrn_data_frame.center_units will be set to 'mm'.
<p>
For cbf_set_reference_beam_center if the diffrn_detector_element category exists with a row for the corresponding element id,
the values will be set for _diffrn_detector_element.reference_center_fast and _diffrn_detector_element.reference_center_slow
in millimetres and the value of _diffrn_detector_element.reference_units will be set to 'mm'.

<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>detector</i><td valign="top">&nbsp;&nbsp;Detector handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>indexfast</i><td valign="top">&nbsp;&nbsp;Pointer to the destination fast index.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>indexslow</i><td valign="top">&nbsp;&nbsp;Pointer to the destination slow index.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>centerfast</i><td valign="top">&nbsp;&nbsp;Pointer to the destination displacement along the fast axis.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>centerslow</i><td valign="top">&nbsp;&nbsp;Pointer to the destination displacement along the slow axis.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.41">2.4.41 cbf_get_detector_distance</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_detector_distance (cbf_detector <i>detector</i>, double *<i>distance</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_detector_distance sets *<i>distance</i> to the nearest distance from the sample position to the detector plane.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>detector</i><td valign="top">&nbsp;&nbsp;Detector handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>distance</i><td valign="top">&nbsp;&nbsp;Pointer to the destination distance.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.42">2.4.42 cbf_get_detector_normal</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_detector_normal (cbf_detector <i>detector</i>, double *<i>normal1</i>, double *<i>normal2</i>,
double *<i>normal3</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_detector_normal sets *<i>normal1</i>, *<i>normal2</i>, and *<i>normal3</i> to the 3 components of the of the normal vector to the detector plane.  The vector is normalized.
<p>
Any of the destination pointers may be NULL.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>detector</i><td valign="top">&nbsp;&nbsp;Detector handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>normal1</i><td valign="top">&nbsp;&nbsp;Pointer to the destination x component of the normal vector.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>normal2</i><td valign="top">&nbsp;&nbsp;Pointer to the destination y component of the normal vector.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>normal3</i><td valign="top">&nbsp;&nbsp;Pointer to the destination z component of the normal vector.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.43">2.4.43 cbf_get_detector_axis_slow, cbf_get_detector_axis_fast, cbf_get_detector_axes, cbf_get_detector_axes_fs, cbf_get_detector_axes_sf,
    cbf_get_detector_surface_axes</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_detector_axis_slow (cbf_detector <i>detector</i>, double *<i>slowaxis1</i>, double *<i>slowaxis2</i>,
double *<i>slowaxis3</i>);<br />
int cbf_get_detector_axis_fast (cbf_detector <i>detector</i>, double *<i>fastaxis1</i>, double *<i>fastaxis2</i>,
double *<i>fastaxis3</i>);<br />
int cbf_get_detector_axes (cbf_detector <i>detector</i>, double *<i>slowaxis1</i>, double *<i>slowaxis2</i>,
double *<i>slowaxis3</i>, double *<i>fastaxis1</i>, double *<i>fastaxis2</i>,
double *<i>fastaxis3</i>);<br />
int cbf_get_detector_axes_fs (cbf_detector <i>detector</i>, double *<i>fastaxis1</i>, double *<i>fastaxis2</i>,
double *<i>fastaxis3</i>, double *<i>slowaxis1</i>, double *<i>slowaxis2</i>,
double *<i>slowaxis3</i>);<br />
int cbf_get_detector_axes_sf (cbf_detector <i>detector</i>, double *<i>slowaxis1</i>, double *<i>slowaxis2</i>,
double *<i>slowaxis3</i>, double *<i>fastaxis1</i>, double *<i>fastaxis2</i>,
double *<i>fastaxis3</i>);<br />
int cbf_get_detector_surface_axes(cbf_detector <i>detector</i>,
    const char * * <i>axis_id1</i>,
    const char * * <i>axis_id2</i>);<br />
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_detector_axis_slow sets *<i>slowaxis1</i>, *<i>slowaxis2</i>, and *<i>slowaxis3</i> to the 3 components of
the slow axis of the specified detector at the current settings of all axes.
cbf_get_detector_axis_slow sets *<i>fastaxis1</i>, *<i>fastaxis2</i>, and *<i>fastaxis3</i> to the 3 components of
the fast axis of the specified detector at the current settings of all axes.
cbf_get_detector_axes, cbf_get_detector_axes_fs and int cbf_get_detector_axes_sf set  
*<i>slowaxis1</i>, *<i>slowaxis2</i>, and *<i>slowaxis3</i> to the 3 components of
the slow axis and *<i>fastaxis1</i>, *<i>fastaxis2</i>, and *<i>fastaxis3</i> to the 3 components of
the fast axis of the specified detector at the current settings of all axes.
cbf_get_detector_surface_axes sets *<i>axis_id1</i> and *<i>axis_id2</i>
to the names of the two surface axes of the detector or &quot;.&quot;,
<p>
Any of the destination pointers may be NULL.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>detector</i><td valign="top">&nbsp;&nbsp;Detector handle.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>slowaxis1</i><td valign="top">&nbsp;&nbsp;Pointer to the destination x component of the slow axis vector.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>slowaxis2</i><td valign="top">&nbsp;&nbsp;Pointer to the destination y component of the slow axis vector.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>slowaxis3</i><td valign="top">&nbsp;&nbsp;Pointer to the destination z component of the slow axis vector.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>fastaxis1</i><td valign="top">&nbsp;&nbsp;Pointer to the destination x component of the fast axis vector.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>fastaxis2</i><td valign="top">&nbsp;&nbsp;Pointer to the destination y component of the fast axis vector.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>fastaxis3</i><td valign="top">&nbsp;&nbsp;Pointer to the destination z component of the fast axis vector.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>axis_id1</i><td valign="top">&nbsp;&nbsp;Pointer to the destination first surface axis name.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>axis_id2</i><td valign="top">&nbsp;&nbsp;Pointer to the destination second surface axis name.</TR>
<TR><td valign="top">&nbsp;&nbsp;<i>axis_id3</i><td valign="top">&nbsp;&nbsp;Pointer to the destination third surface axis name.</TR>

</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.44">2.4.44 cbf_get_pixel_coordinates, cbf_get_pixel_coordinates_fs, cbf_get_pixel_coordinates_sf
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_pixel_coordinates (cbf_detector <I>detector</I>, double <i>indexslow</i>, double <i>indexfast</i>, double *<i>coordinate1</i>,
	double *<i>coordinate2</i>, double *<i>coordinate3</i>);<br />
int cbf_get_pixel_coordinates_fs (cbf_detector <I>detector</I>, double <i>indexfast</i>, double <i>indexslow</i>, double *<i>coordinate1</i>,
	double *<i>coordinate2</i>, double *<i>coordinate3</i>);<br />
int cbf_get_pixel_coordinates_sf (cbf_detector <I>detector</I>, double <i>indexslow</i>, double <i>indexfast</i>, double *<i>coordinate1</i>,
	double *<i>coordinate2</i>, double *<i>coordinate3</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_pixel_coordinates, cbf_get_pixel_coordinates_fs and cbf_get_pixel_coordinates_sf ses *<i>coordinate1</i>, *<i>coordinate2</i>, and *<i>coordinate3</i> 
to the vector position of pixel (<i>indexfast</i>, <i>indexslow</i>) on the detector surface.  If 
<i>indexslow</i> and <i>indexfast</i> are integers then the coordinates
correspond to the center of a pixel.
<p>
Any of the destination pointers may be NULL.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>detector</i><td valign="top">&nbsp;&nbsp;Detector handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>indexslow</i><td valign="top">&nbsp;&nbsp;Slow index.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>indexfast</i><td valign="top">&nbsp;&nbsp;Fast index.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>coordinate1</i><td valign="top">&nbsp;&nbsp;Pointer to the destination x component.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>coordinate2</i><td valign="top">&nbsp;&nbsp;Pointer to the destination y component.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>coordinate3</i><td valign="top">&nbsp;&nbsp;Pointer to the destination z component.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.45">2.4.45 cbf_get_pixel_normal, cbf_get_pixel_normal_fs, cbf_get_pixel_normal_sf
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_pixel_normal (cbf_detector <I>detector</I>, double <i>indexslow</i>, double <i>indexfast</i>,  double *<i>normal1</i>,
double *<i>normal2</i>, double *<i>normal3</i>);<br />
int cbf_get_pixel_normal_fs (cbf_detector <I>detector</I>, double <i>indexfast</i>, double <i>indexslow</i>,  double *<i>normal1</i>,
double *<i>normal2</i>, double *<i>normal3</i>);<br />
int cbf_get_pixel_normal (cbf_detector <I>detector</I>, double <i>indexslow</i>, double <i>indexfast</i>,  double *<i>normal1</i>,
double *<i>normal2</i>, double *<i>normal3</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_detector_normal, cbf_get_pixel_normal_fs and cbf_get_pixel_normal_sf set 
*<i>normal1</i>, *<i>normal2</i>, and *<i>normal3</i> to the 3 components of the of the normal vector 
to the pixel at (<i>indexfast</i>, <i>indexslow</i>).  The vector is normalized.
<p>
Any of the destination pointers may be NULL.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>detector</i><td valign="top">&nbsp;&nbsp;Detector handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>indexslow</i><td valign="top">&nbsp;&nbsp;Slow index.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>indexfast</i><td valign="top">&nbsp;&nbsp;Fast index.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>normal1</i><td valign="top">&nbsp;&nbsp;Pointer to the destination x component of the normal vector.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>normal2</i><td valign="top">&nbsp;&nbsp;Pointer to the destination y component of the normal vector.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>normal3</i><td valign="top">&nbsp;&nbsp;Pointer to the destination z component of the normal vector.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>
<h4><A NAME="2.4.46">2.4.46 cbf_get_pixel_area, cbf_get_pixel_area_fs, cbf_get_pixel_area_sf
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_pixel_area (cbf_detector <i>detector</i>, double <i>indexslow</i>, double <i>indexfast</i>, double *<I>area</I>,
double *<i>projected_area</i>);<br />
int cbf_get_pixel_area_fs(cbf_detector <i>detector</i>, double <i>indexfast</i>, double <i>indexslow</i>, double *<I>area</I>,
double *<i>projected_area</i>);<br />
int cbf_get_pixel_area_sf(cbf_detector <i>detector</i>, double <i>indexslow</i>, double <i>indexfast</i>, double *<I>area</I>,
double *<i>projected_area</i>);<br />
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_pixel_area, cbf_get_pixel_area_fs and cbf_get_pixel_area_sf set *<I>area</I> to the area of the pixel at (<i>indexfast</i>, <i>indexslow</i>) 
on the detector surface and *<i>projected_area</i> to the apparent area of the pixel as viewed 
from the sample position, with <i>indexslow</i> being the slow axis and <i>indexfast</i> being the fast axis.

<p>
Either of the destination pointers may be NULL.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>detector</i><td valign="top">&nbsp;&nbsp;Detector handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>indexfast</i><td valign="top">&nbsp;&nbsp;Fast index.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>indexslow</i><td valign="top">&nbsp;&nbsp;Slow index.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>area</i><td valign="top">&nbsp;&nbsp;Pointer to the destination area in mm2.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>projected_area</i><td valign="top">&nbsp;&nbsp;Pointer to the destination apparent area in mm2.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>

<h4><A NAME="2.4.47">2.4.47 cbf_get_pixel_size, cbf_get_pixel_size_fs, cbf_get_pixel_size_sf</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_pixel_size (cbf_handle <i>handle</i>, unsigned int <i>element_number</i>,
int <i>axis_number</i>, double *<i>psize</i>);<br />
int cbf_get_pixel_size_fs(cbf_handle <i>handle</i>, unsigned int <i>element_number</i>,
int <i>axis_number</i>, double *<i>psize</i>);<br />
int cbf_get_pixel_size_sf(cbf_handle <i>handle</i>, unsigned int <i>element_number</i>,
int <i>axis_number</i>, double *<i>psize</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_pixel_size and cbf_get_pixel_size_sf set *<i>psize</i> to point to the double value in millimeters of the
axis <i>axis_number</i> of the detector element <i>element_number</i>.  The <i>axis_number</i>
is numbered from 1, starting with the slowest axis.  cbf_get_pixel_size_fs sets *<i>psize</i> to point to 
the double value in millimeters of the axis <i>axis_number</i> of the detector element <i>element_number</i>.
The <i>axis_number</i>
is numbered from 1, starting with the fastest axis.
<p>If a negative axis number is given, the order of axes is reversed, so that -1
specifies the slowest axis for cbf_get_pixel_size_fs and the fastest axis for
cbf_get_pixel_size_sf.
<p>
If the pixel size is not given explcitly in the &quot;array_element_size&quot; category,
the function returns CBF_NOTFOUND.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.
<TR><td valign="top">&nbsp;&nbsp;<i>axis_number</i><td valign="top">&nbsp;&nbsp;The number of the axis, starting from 1 for the fastest for
cbf_get_pixel_size and cbf_get_pixel_size_fs and the slowest for cbf_get_pixel_size_sf.
<TR><td valign="top">&nbsp;&nbsp;<i>psize</i><td valign="top">&nbsp;&nbsp;Pointer to the destination pixel size.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>


<h4><A NAME="2.4.48">2.4.48 cbf_set_pixel_size, cbf_set_pixel_size_fs, cbf_set_pixel_size_sf</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_pixel_size (cbf_handle <i>handle</i>, unsigned int <i>element_number</i>,
int <i>axis_number</i>, double <i>psize</i>);<br />
int cbf_set_pixel_size_fs(cbf_handle <i>handle</i>, unsigned int <i>element_number</i>,
int <i>axis_number</i>, double <i>psize</i>);<br />
int cbf_set_pixel_size_sf(cbf_handle <i>handle</i>, unsigned int <i>element_number</i>,
int <i>axis_number</i>, double <i>psize</i>);<br />
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_pixel_size and cbf_set_pixel_size_sf set the item in the &quote;size&quote; column of the  &quot;array_structure_list&quot;
category at the row which matches axis <i>axis_number</i> of the detector element <i>element_number</i>
converting the double pixel size <i>psize</i> from meters to millimeters in storing it in the &quot;size&quot;
column for the axis <i>axis_number</i> of the detector element <i>element_number</i>.  The <i>axis_number</i>
is numbered from 1, starting with the slowest axis.
cbf_set_pixel_size_fs sets the item in the &quote;size&quote; column of the  &quot;array_structure_list&quot;
category at the row which matches axis <i>axis_number</i> of the detector element <i>element_number</i>
converting the double pixel size <i>psize</i> from meters to millimeters in storing it in the &quot;size&quot;
column for the axis <i>axis_number</i> of the detector element <i>element_number</i>.  The <i>axis_number</i>
is numbered from 1, starting with the fastest axis.
<p>If a negative axis number is given, the order of axes is reversed, so that -1
specifies the slowest axis for cbf_get_pixel_size_fs and the fastest axis for
cbf_get_pixel_size_sf.
<p>
If the &quot;array_structure_list&quot; category does not already exist, it is created.
<p>
If the appropriate row in the &quot;array_structure_list&quot; catgeory does not already exist, it is created.
<p>
If the pixel size is not given explcitly in the &quot;array_element_size category&quot;, the function returns CBF_NOTFOUND.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.
<TR><td valign="top">&nbsp;&nbsp;<i>axis_number</i><td valign="top">&nbsp;&nbsp;The number of the axis, fastest first, starting from 1.
<TR><td valign="top">&nbsp;&nbsp;<i>psize</i><td valign="top">&nbsp;&nbsp;The pixel size in millimeters.
</TABLE>
<p>
<b>RETURN VALUE</b>

<p>Returns an error code on failure or 0 for success.
<p><hr /><P>

<h4><A NAME="2.4.49">2.4.49 cbf_get_inferred_pixel_size, cbf_get_inferred_pixel_size_fs, cbf_get_inferred_pixel_size_sf
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_inferred_pixel_size (cbf_detector <i>detector</i>,
int <i>axis_number</i>,
double *<i>psize</i>);<br />
int cbf_get_inferred_pixel_size_fs(cbf_detector <i>detector</i>,
int <i>axis_number</i>,
double *<i>psize</i>);<br />
int cbf_get_inferred_pixel_size_sf(cbf_detector <i>detector</i>,
int <i>axis_number</i>,
double *<i>psize</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_inferred_pixel_size, cbf_get_inferred_pixel_size_sf set *<i>psize</i> to point to 
the double value in millimeters of the
pixel size for the axis <i>axis_number</i> value.  The slow index is treated as axis 1 and the next faster index is treated
as axis 2.  cbf_get_inferred_pixel_size_fs sets *<i>psize</i> to point to the double value in 
millimeters of the
pixel size for the axis <i>axis_number</i> value.  The fast index is treated as axis 1  and the next slower index is treated
as axis 2.
<p>If the axis number is negative, the axes are used in the reverse order so that an <i>axis_number</i>
of -1 indicates the fast axes in a call to cbf_get_inferred_pixel_size or cbf_get_inferred_pixel_size_sf
and indicates the fast axis in a call to cbf_get_inferred_pixel_size_fs.  
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>detector</i><td valign="top">&nbsp;&nbsp;Detector handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>axis_number</i><td valign="top">&nbsp;&nbsp;The number of the axis.
<TR><td valign="top">&nbsp;&nbsp;<i>psize</i><td valign="top">&nbsp;&nbsp;Pointer to the destination pizel size in mm.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>

<h4><A NAME="2.4.50">2.4.50 cbf_get_unit_cell
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_unit_cell (cbf_handle <i>handle</i>,
    double <i>cell</i>[6], double <i>cell_esd</i>[6] );
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_unit_cell sets <i>cell</i>[0:2] to the double values of the cell edge
lengths a, b and c in &Aring;ngstroms, <i>cell</i>[3:5] to the double values
of the cell angles &alpha;, &beta; and &gamma; in degrees,  <i>cell_esd</i>[0:2] to the double values of
the estimated strandard deviations of the cell edge lengths a, b and c in
&Aring;ngstroms, <i>cell_esd</i>[3:5] to the double values of the estimated
standard deviations of the the cell angles &alpha;, &beta; and &gamma; in degrees.
<p>The values returned are retrieved from the first row of the &quot;cell&quot;
category.  The value of "_cell.entry_id" is ignored.
<p><i>cell</i> or  <i>cell_esd</i> may be NULL.
<p>
If <i>cell</i> is NULL, the cell parameters are not retrieved.
<p>
If <i>cell_esd</i> is NULL, the cell parameter esds are not retrieved.
<p>
If the &quot;cell&quot; category is present, but some of the values
are missing, zeros are returned for the missing values.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>cell</i><td valign="top">&nbsp;&nbsp;Pointer to the destination array
of 6 doubles for the cell parameters.
<TR><td valign="top">&nbsp;&nbsp;<i>cell_esd</i><td valign="top">&nbsp;&nbsp;Pointer to the destination
array of 6 doubles for the cell parameter esds.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.  No errors is returned for
missing values if the &quot;cell&quot; category exists.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.4.51">2.4.51 cbf_set_unit_cell<br />
<A HREF="#2.4.52">2.4.52 cbf_get_reciprocal_cell<br />
<A HREF="#2.4.53">2.4.53 cbf_set_reciprocal_cell<br />
<A HREF="#2.4.54">2.4.54 cbf_compute_cell_volume<br />
<A HREF="#2.4.55">2.4.55 cbf_compute_reciprocal_cell<br />
<p><hr /><P>
<h4><A NAME="2.4.51">2.4.51 cbf_set_unit_cell
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_unit_cell (cbf_handle <i>handle</i>,
    double <i>cell</i>[6], double <i>cell_esd</i>[6] );
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_unit_cell sets the cell parameters to the double values given in <i>cell</i>[0:2]
 for the cell edge
lengths a, b and c in &Aring;ngstroms, the double values given in <i>cell</i>[3:5]
for the cell angles &alpha;, &beta; and &gamma; in degrees, the double values given in <i>cell_esd</i>[0:2] for
the estimated strandard deviations of the cell edge lengths a, b and c in
&Aring;ngstroms, and the double values given in <i>cell_esd</i>[3:5] for the estimated
standard deviations of the the cell angles &alpha;, &beta; and &gamma; in degrees.
<p>The values are placed in the first row of the &quot;cell&quot;
category.  If no value has been given for "_cell.entry_id", it is set to
the value of the &quot;diffrn.id&quot; entry of the current data block.
<p><i>cell</i> or  <i>cell_esd</i> may be NULL.
<p>
If <i>cell</i> is NULL, the cell parameters are not set.
<p>
If <i>cell_esd</i> is NULL, the cell parameter esds are not set.
<p>
If the &quot;cell&quot; category is not present, it is created.
If any of the necessary columns are not present, they are created.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>cell</i><td valign="top">&nbsp;&nbsp;Pointer to the array
of 6 doubles for the cell parameters.
<TR><td valign="top">&nbsp;&nbsp;<i>cell_esd</i><td valign="top">&nbsp;&nbsp;Pointer to the
array of 6 doubles for the cell parameter esds.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.4.50">2.4.50 cbf_get_unit_cell<br />
<A HREF="#2.4.52">2.4.52 cbf_get_reciprocal_cell<br />
<A HREF="#2.4.53">2.4.53 cbf_set_reciprocal_cell<br />
<A HREF="#2.4.54">2.4.54 cbf_compute_cell_volume<br />
<A HREF="#2.4.55">2.4.55 cbf_compute_reciprocal_cell<br />
<p><hr /><P>
<b>SEE ALSO</b>
<h4><A NAME="2.4.52">2.4.52 cbf_get_reciprocal_cell
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_reciprocal_cell (cbf_handle <i>handle</i>,
    double <i>cell</i>[6], double <i>cell_esd</i>[6] );
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_reciprocal_cell sets <i>cell</i>[0:2] to the double values of the
reciprocal cell edge
lengths a<sup>*</sup>, b<sup>*</sup> and c<sup>*</sup> in &Aring;ngstroms<sup>-1</sup>, <i>cell</i>[3:5] to the double values
of the reciprocal cell angles &alpha;<sup>*</sup>, &beta;<sup>*</sup> and &gamma;<sup>*</sup> in degrees,  <i>cell_esd</i>[0:2] to the double values of
the estimated strandard deviations of the reciprocal cell edge lengths a<sup>*</sup>,
 b<sup>*</sup> and c<sup>*</sup> in
&Aring;ngstroms<sup>-1</sup>, <i>cell_esd</i>[3:5] to the double values of the estimated
standard deviations of the the reciprocal cell angles &alpha;<sup>*</sup>, &beta;<sup>*</sup> and &gamma;<sup>*</sup> in degrees.
<p>The values returned are retrieved from the first row of the &quot;cell&quot;
category.  The value of "_cell.entry_id" is ignored.
<p><i>cell</i> or  <i>cell_esd</i> may be NULL.
<p>
If <i>cell</i> is NULL, the reciprocal cell parameters are not retrieved.
<p>
If <i>cell_esd</i> is NULL, the reciprocal cell parameter esds are not retrieved.
<p>
If the &quot;cell&quot; category is present, but some of the values
are missing, zeros are returned for the missing values.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>cell</i><td valign="top">&nbsp;&nbsp;Pointer to the destination array
of 6 doubles for the reciprocal cell parameters.
<TR><td valign="top">&nbsp;&nbsp;<i>cell_esd</i><td valign="top">&nbsp;&nbsp;Pointer to the destination
array of 6 doubles for the reciprocal cell parameter esds.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.  No errors is returned for
missing values if the &quot;cell&quot; category exists.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.4.50">2.4.50 cbf_get_unit_cell<br />
<A HREF="#2.4.51">2.4.51 cbf_set_unit_cell<br />
<A HREF="#2.4.53">2.4.53 cbf_set_reciprocal_cell<br />
<A HREF="#2.4.54">2.4.54 cbf_compute_cell_volume<br />
<A HREF="#2.4.55">2.4.55 cbf_compute_reciprocal_cell<br />
<p><hr /><P>
<h4><A NAME="2.4.53">2.4.53 cbf_set_reciprocal_cell
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_set_reciprocal_cell (cbf_handle <i>handle</i>,
    double <i>cell</i>[6], double <i>cell_esd</i>[6] );
<p>
<b>DESCRIPTION</b>
<p>
cbf_set_reciprocal_cell sets the reciprocal cell parameters to the
double values given in <i>cell</i>[0:2] for the reciprocal cell edge
lengths a<sup>*</sup>, b<sup>*</sup> and c<sup>*</sup>
in &Aring;ngstroms<sup>-1</sup>, the double values given in <i>cell</i>[3:5]
for the reciprocal cell angles
&alpha;<sup>*</sup>, &beta;<sup>*</sup> and &gamma;<sup>*</sup>
in degrees, the double values given in <i>cell_esd</i>[0:2] for
the estimated strandard deviations of the reciprocal cell edge lengths
 a<sup>*</sup>, b<sup>*</sup> and c<sup>*</sup> in
&Aring;ngstroms, and the double values given in <i>cell_esd</i>[3:5] for the estimated
standard deviations of the reciprocal cell angles
 &alpha;<sup>*</sup>, &beta;<sup>*</sup> and &gamma;<sup>*</sup>
in degrees.
<p>The values are placed in the first row of the &quot;cell&quot;
category.  If no value has been given for "_cell.entry_id", it is set to
the value of the &quot;diffrn.id&quot; entry of the current data block.
<p><i>cell</i> or  <i>cell_esd</i> may be NULL.
<p>
If <i>cell</i> is NULL, the reciprocal cell parameters are not set.
<p>
If <i>cell_esd</i> is NULL, the reciprocal cell parameter esds are not set.
<p>
If the &quot;cell&quot; category is not present, it is created.
If any of the necessary columns are not present, they are created.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>cell</i><td valign="top">&nbsp;&nbsp;Pointer to the array
of 6 doubles for the reciprocal cell parameters.
<TR><td valign="top">&nbsp;&nbsp;<i>cell_esd</i><td valign="top">&nbsp;&nbsp;Pointer to the
array of 6 doubles for the reciprocal cell parameter esds.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.4.50">2.4.50 cbf_get_unit_cell<br />
<A HREF="#2.4.51">2.4.51 cbf_set_unit_cell<br />
<A HREF="#2.4.52">2.4.52 cbf_get_reciprocal_cell<br />
<A HREF="#2.4.54">2.4.54 cbf_compute_cell_volume<br />
<A HREF="#2.4.55">2.4.55 cbf_compute_reciprocal_cell<br />
<p><hr /><P>

<h4><A NAME="2.4.54">2.4.54 cbf_compute_cell_volume
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_compute_cell_volume ( double <i>cell</i>[6], double *<i>volume</i> );

<p>
<b>DESCRIPTION</b>
<p>
cbf_compute_cell_volume sets *<i>volume</i> to point to the volume of the unit cell
computed from the double values in <i>cell</i>[0:2]
for the cell edge lengths a, b and c in &Aring;ngstroms and
 the double values given in <i>cell</i>[3:5]
for the cell angles &alpha;, &beta; and &gamma; in degrees.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>cell</i><td valign="top">&nbsp;&nbsp;Pointer to the array
of 6 doubles giving the cell parameters.
<TR><td valign="top">&nbsp;&nbsp;<i>volume</i><td valign="top">&nbsp;&nbsp;Pointer to the
doubles for cell volume.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.4.50">2.4.50 cbf_get_unit_cell<br />
<A HREF="#2.4.51">2.4.51 cbf_set_unit_cell<br />
<A HREF="#2.4.52">2.4.52 cbf_get_reciprocal_cell<br />
<A HREF="#2.4.53">2.4.53 cbf_set_reciprocal_cell<br />
<A HREF="#2.4.55">2.4.55 cbf_compute_reciprocal_cell<br />
<p><hr /><P>


<h4><A NAME="2.4.55">2.4.55 cbf_compute_reciprocal_cell
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_compute_reciprocal_cell ( double <i>cell</i>[6], double <i>rcell</i>[6] );


<p>
<b>DESCRIPTION</b>
<p>
cbf_compute_reciprocal_cell sets <i>rcell</i> to  point to the array of reciprocal cell
parameters computed from the double values <i>cell</i>[0:2] giving the cell edge
lengths a, b and c in &Aring;ngstroms, and the double values <i>cell</i>[3:5]
giving the cell angles &alpha;, &beta; and &gamma; in degrees.  The double values
<i>rcell</i>[0:2] will be set to the reciprocal cell
lengths a<sup>*</sup>, b<sup>*</sup> and c<sup>*</sup> in &Aring;ngstroms<sup>-1</sup>
and the double values <i>rcell</i>[3:5] will be set to the reciprocal cell
angles &alpha;<sup>*</sup>, &beta;<sup>*</sup> and &gamma;<sup>*</sup> in degrees.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>cell</i><td valign="top">&nbsp;&nbsp;Pointer to the array
of 6 doubles giving the cell parameters.
<TR><td valign="top">&nbsp;&nbsp;<i>rcell</i><td valign="top">&nbsp;&nbsp;Pointer to the destination array
of 6 doubles giving the reciprocal cell parameters.
<TR><td valign="top">&nbsp;&nbsp;<i>volume</i><td valign="top">&nbsp;&nbsp;Pointer to the
doubles for cell volume.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.4.50">2.4.50 cbf_get_unit_cell<br />
<A HREF="#2.4.51">2.4.51 cbf_set_unit_cell<br />
<A HREF="#2.4.52">2.4.52 cbf_get_reciprocal_cell<br />
<A HREF="#2.4.53">2.4.53 cbf_set_reciprocal_cell<br />
<A HREF="#2.4.54">2.4.54 cbf_compute_cell_volume<br />
<p><hr /><P>



<h4><A NAME="2.4.56">2.4.56 cbf_get_orientation_matrix, cbf_set_orientation_matrix
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_orientation_matrix (cbf_handle <i>handle</i>, double <i>ub_matrix</i>[9]); <br />
int cbf_set_orientation_matrix (cbf_handle <i>handle</i>, double <i>ub_matrix</i>[9]);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_orientation_matrix sets <i>ub_matrix</i> to point to the array of
orientation matrix entries in the &quot;diffrn&quot; category in the order
of columns:<P>
<center>
&quot;UB[1][1]&quot; &quot;UB[1][2]&quot; &quot;UB[1][3]&quot;<br />
&quot;UB[2][1]&quot; &quot;UB[2][2]&quot; &quot;UB[2][3]&quot;<br />
&quot;UB[3][1]&quot; &quot;UB[3][2]&quot; &quot;UB[3][3]&quot;
</center>  
<P>
cbf_set_orientation_matrix sets the values in the &quot;diffrn&quot; category
to the values pointed to by <i>ub_matrix</i>.
<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>ub_matrix</i><td valign="top">&nbsp;&nbsp;Source or destination array
of 9 doubles giving the orientation matrix parameters.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>




<h4><A NAME="2.4.57">2.4.57 cbf_get_bin_sizes, cbf_set_bin_sizes
</A></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_simple.h"
<p>
int cbf_get_bin_sizes(cbf_handle <i>handle</i>, unsigned int <i>element_number</i>, double * <i>slowbinsize</i>,
 double * <i>fastbinsize</i>); <br />
int cbf_set_bin_sizes(cbf_handle <i>handle</i>, unsigned int element_number, double <i>slowbinsize_in</i>,double <i>fastbinsize_in</i>);
<p>
<b>DESCRIPTION</b>
<p>
cbf_get_bin_sizes sets <i>slowbinsize</i> to point to the value of the
number of pixels composing one array element in the dimension that changes at
the second-fastest rate and <i>fastbinsize</i> to point to the value of the
number of pixels composing one array element in the dimension that changes at
the fastest rate for the dectector element with the ordinal <i>element_number</i>.
cbf_set_bin_sizes sets the the pixel bin sizes in the  
&quot;array_intensities&quot; category to the values of 
<i>slowbinsize_in</i> for the
number of pixels composing one array element in the dimension that changes at
the second-fastest rate and <i>fastbinsize_in</i> for the
number of pixels composing one array element in the dimension that changes at
the fastest rate for the dectector element with the ordinal <i>element_number</i>.
<P>
In order to allow for software binning involving fractions of pixels,
the bin sizes are doubles rather than ints.
<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.
<TR><td valign="top">&nbsp;&nbsp;<i>element_number</i><td valign="top">&nbsp;&nbsp;The number of the detector element counting from 0 by order of appearance in the &quot;diffrn_data_frame&quot; category.
<TR><td valign="top">&nbsp;&nbsp;<i>slowbinsize</i><td valign="top">&nbsp;&nbsp;Pointer to the returned number of pixels composing one array element in the dimension that changes at
the second-fastest rate.
<TR><td valign="top">&nbsp;&nbsp;<i>fastbinsize</i><td valign="top">&nbsp;&nbsp;Pointer to the returned number of pixels composing one array element in the dimension that changes at
the fastest rate.
<TR><td valign="top">&nbsp;&nbsp;<i>slowbinsize_in</i><td valign="top">&nbsp;&nbsp;The number of pixels composing one array element in the dimension that changes at
the second-fastest rate.
<TR><td valign="top">&nbsp;&nbsp;<i>fastbinsize_in</i><td valign="top">&nbsp;&nbsp;The number of pixels composing one array element in the dimension that changes at
the fastest rate.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns an error code on failure or 0 for success.
<p><hr /><P>

<h4><A NAME="2.4.58">2.4.58 cbf_get_axis_poise, cbf_get_goniometer_poise, cbf_get_axis_reference_poise
    </A></h4>
    <p><b>PROTOTYPE</b>
    <p>#include "cbf_simple.h"
    <p>
    int cbf_get_axis_poise(cbf_handle <i>handle</i>, double <i>ratio</i>,
    double * <i>vector1</i>, double * <i>vector2</i>, double * <i>vector3</i>,
    double * <i>offset1</i>, double * <i>offset2</i>, double * <i>offset3</i>,
    double * <i>angle</i>,
    const char * <i>axis_id</i>,
    const char * <i>frame_id</i>);<br />
    int cbf_get_goniometer_poise(cbf_goniometer <i>goniometer</i>, double <i>ratio</i>,
    double * <i>vector1</i>, double * <i>vector2</i>, double * <i>vector3</i>,
    double * <i>offset1</i>, double * <i>offset2</i>, double * <i>offset3</i>,
    double * <i>angle</i>);<br />
    int cbf_get_axis_reference_poise(cbf_handle <i>handle</i>,
    double * <i>vector1</i>, double * <i>vector2</i>, double * <i>vector3</i>,
    double * <i>offset1</i>, double * <i>offset2</i>, double * <i>offset3</i>,
    const char * <i>axis_id</i>);

    <p>
    <b>DESCRIPTION</b>
    <p>
    cbf_get_axis_poise sets <i>vector1</i>, <i>vector2</i>, <i>vector3</i> to
    point to the components of the axis vector for axis <i>axis_id</i>,
    <i>offset1</i>, <i>offset2</i>, <i>offset3</i> to point to the
    components of the axis base offset vector for axis <i>axis_id</i>, and
    <i>angle</i> to point to the angle of rotation of axis <i>axis_id</i>
    after application of the axis settings for frame <i>frame_id</i>, using
    <i>ratio</i>, a value between 0 and 1, indicating how far into the internal
    motion in the frame to go.  If <i>frame_id</i> is the string
    &quot;.&quot;, the first frame found is used.  If there is more than one
    frame, which frame will be found is indeterminate.  If <i>frame_id</i>
    is NULL, the overall setting for the scan are used, rather than those
    for any particular frame.  The vector and offset reported are the
    reference vector and offset of the axis <i>axis_id</i> transformed by
    application of all motions of the axes on which <i>axis_id</i> depends.
    <p>
    cbf_get_goniometer_poise <i>vector1</i>, <i>vector2</i>, <i>vector3</i> to
    point to the components of the axis vector for the goniometer axis,
    <i>offset1</i>, <i>offset2</i>, <i>offset3</i> to point to the
    components of the axis base offset vector for the goniometer axis, and
    <i>angle</i> to point to the angle of rotation of the goniometer axis
    after application of <b>all</b> axis settings in the <i>goniometer</i>
    deriving the vector, offset and angle from the resulting matrix.
    Calculation of the vector is indeterminate if the angle is zero.
    <p>
    cbf_get_axis_reference_poise sets <i>vector1</i>, <i>vector2</i>, <i>vector3</i> to
    point to the components of the axis vector for axis <i>axis_id</i>,
    <i>offset1</i>, <i>offset2</i>, <i>offset3</i> to point to the
    components of the axis base offset vector for axis <i>axis_id</i>
    unmodified by axis rotations.
    
    
    Any of the pointers may be specified as NULL.
    
    <P>
    <b>ARGUMENTS</b><br />
    <TABLE>
        <TR><td valign="top">&nbsp;&nbsp;<i>handle</i><td valign="top">&nbsp;&nbsp;CBF handle.</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>ratio</i><td valign="top">&nbsp;&nbsp;A number between 0 and 1 indication how far into the frame to go</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>vector1</i><td valign="top">&nbsp;&nbsp;Pointer to the first component of the axis vector</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>vector2</i><td valign="top">&nbsp;&nbsp;Pointer to the second component of the axis vector</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>vector3</i><td valign="top">&nbsp;&nbsp;Pointer to the third component of the axis vector</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>offset1</i><td valign="top">&nbsp;&nbsp;Pointer to the first component of the axis offset</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>offset2</i><td valign="top">&nbsp;&nbsp;Pointer to the second component of the axis offset</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>offset3</i><td valign="top">&nbsp;&nbsp;Pointer to the third component of the axis offset</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>angle</i><td valign="top">&nbsp;&nbsp;Pointer to the rotation angle</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>axis_id</i><td valign="top">&nbsp;&nbsp;The specified axis</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>frame_id</i><td valign="top">&nbsp;&nbsp;The specified frame</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>positioner</i><td valign="top">&nbsp;&nbsp;CBF goniometer</TR>
    </TABLE>
    <p>
    <b>RETURN VALUE</b>
    <p>
    Returns an error code on failure or 0 for success.
    <p><hr /><P>

<h4><a NAME="#2.4.59">2.4.59 cbf_airy_disk, cbf_airy_disk_volume
</a></h4>
<p><b>PROTOTYPE</b>
<p>#include "cbf_airy_disk.h"
    <p>
    int cbf_airy_disk(double <i>x</i>, double <i>y</i>,
    double <i>cenx</i>, double <i>ceny</i>, double <i>volume</i>, double <i>fwhm</i>,
    double * <i>value</i>);<br />
    int cbf_airy_disk_volume(double <i>xlo</i>, double <i>ylo</i>,
    double <i>xhi</i>, double <i>yhi</i>,
    double <i>cenx</i>, double <i>ceny</i>,
    double <i>volume</i>, double <i>fwhm</i>,
    double * <i>volumeout</i>);

    <p>
    <b>DESCRIPTION</b>
    <p>
    cbf_airy_disk sets <i>value</i> to point to the value taken at (<i>x</i>,<i>y</i>)
    of an truncated Airy function approximation to a point-spread function of
    total included volume <i>volume</i> and full width at half max <i>fwhm</i>
    centered on (<i>cenx</i>, <i>ceny</i>).
    <p>
    cbf_airy_disk_volume sets <volumeout</a> to point to the integral in the box
        with diagonal corners (<i>xlo</i>, <i>ylo</i>) and
        of (<i>xhi</i>, <i>yhi</i>) of a truncated Airy function approximation
        to a point-spread function of total included volume <i>volume</i> and
        full width at half max <i>fwhm</i>
        centered on (<i>cenx</i>, <i>ceny</i>).
        <p>
    The Airy function used is an 8-digit approximation up to the first minimum,
    after which it is forced to zero, so it cannot be used to simulate diffraction
    rings.
    
    <P>
    <b>ARGUMENTS</b><br />
    <TABLE>
        <TR><td valign="top">&nbsp;&nbsp;<i>x</i><td valign="top">&nbsp;&nbsp;the x-coordinate of
          a point in the real plane</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>y</i><td valign="top">&nbsp;&nbsp;the y-coordinate of
            a point in the real plane</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>xlo</i><td valign="top">&nbsp;&nbsp;the x-coordinate of
            a point in the real plane marking the left bound of integration</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>ylo</i><td valign="top">&nbsp;&nbsp;the y-coordinate of
            a point in the real plane marking the bottom bound of integration</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>xhi</i><td valign="top">&nbsp;&nbsp;the x-coordinate of
            a point in the real plane marking the right bound of integration</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>yhi</i><td valign="top">&nbsp;&nbsp;the y-coordinate of
            a point in the real plane marking the top bound of integration</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>cenx</i><td valign="top">&nbsp;&nbsp;the x-coordinate of
            a point in the real plane marking the PSF center</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>ceny</i><td valign="top">&nbsp;&nbsp;the y-coordinate of
            a point in the real plane marking the PSF center</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>volume</i><td valign="top">&nbsp;&nbsp;the total volume of the
            PSF</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>fwhm</i><td valign="top">&nbsp;&nbsp;the full-width at half
            max of the PSF</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>value</i><td valign="top">&nbsp;&nbsp;Pointer to the value of
            the Airy function</TR>
        <TR><td valign="top">&nbsp;&nbsp;<i>volumeout</i><td valign="top">&nbsp;&nbsp;Pointer to the value
            of the integral/TR>
    </TABLE>
    <p>
    <b>RETURN VALUE</b>
    <p>
    Returns an error code on failure or 0 for success.
    <p><hr /><P>


<h3><A NAME="2.5">2.5   F90 function interfaces</a></h3>
<P>At the suggestion of W. Kabsch, Fortran 90/95 routines have been added
to CBFlib.  As of this writing code has been written to allow the reading
of CBF_BYTE_OFFSET, CBF_PACKED and CBF_PACKED_V2 binary images.  This code
has been gather into FCBlib (Fortran Crystallographic Binary library) as
lib/libfcb.

<P>In general, most of the FCBlib functions return 0 for normal completion and a non-zero
value in case of an error.  In a few cases, such as FCB_ATOL_WCNT and FCB_NBLEN_ARRAY
in order to conform to the conventions for commonly used C-equivalent functions, 
the function return is the value being computed.
<p>
For each function, an interface is given to be included in the declarations of your
Fortran 90/95 code.  Some functions in FCBlIB are not intended for external
use and are subject to change:  FCB_UPDATE_JPA_POINTERS_I2,
FCB_UPDATE_JPA_POINTERS_I4, FCB_UPDATE_JPA_POINTERS_3D_I2,
FCB_UPDATE_JPA_POINTERS_3D_I4 and CNT2PIX.  These
names should not be used for user routines.
<P>
The functions involving reading of a CBF have been done strictly in Fortran
without the use of C code.  This has required some compromises and the use
of direct access I/O.   Rather than 
putting the buffer and its control variables into COMMON these are passed 
as local arguments to make the routines inherently 'threadsafe' in a parallel 
programming environment.  Note also, that a reading error could occur for the 
last record if it does not fill a full block.  The code is written to
recover from end-of-record and end-of-file errors, if possible.  On
many modern system, no special action is required, but
on some systems it may be necessary to make use of the padding
between the end of binary data and the terminal MIME boundary marker
in binary sections.  To ensure maximum portability of CBF files,
a padding of 4095 bytes is recommended.  Existing files without
padding can be converted to files with padding by use of the new
-p4 option for cif2cbf.
<P>
<h4><A NAME="2.5.1">2.5.1 FCB_ATOL_WCNT</a></h4>
<p><pre><b>      INTERFACE</b>
      INTEGER(8) FUNCTION FCB_ATOL_WCNT(<i>ARRAY</i>, <i>N</i>, <i>CNT</i>)
      INTEGER(1),INTENT(IN):: <i>ARRAY</i>(<i>N</i>)
      INTEGER,   INTENT(IN):: <i>N</i>
      INTEGER,  INTENT(OUT):: <i>CNT</i>
      END FUNCTION
      END INTERFACE</pre>
 <P>
FCB_ATOL_WCNT converts INTEGER(1) bytes in <i>ARRAY</i> of <i>N</i> bytes 
to an INTEGER(8) value returned as the function value.  The number of
bytes of <i>ARRAY</i> actually used before encountering a character
not used to form the number is returned in <i>CNT</i>.
<P>
The scan stops at the first byte in <i>ARRAY</i> that cannot be properly parsed as
part of the integer result.
<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>ARRAY</i><td valign="top">&nbsp;&nbsp;The array of INTEGER(1) bytes to be scanned
<TR><td valign="top">&nbsp;&nbsp;<i>N</i><td valign="top">&nbsp;&nbsp;The INTEGER size of <i>ARRAY</i>
<TR><td valign="top">&nbsp;&nbsp;<i>CNT</i><td valign="top">&nbsp;&nbsp;The INTEGER size of the portion of <i>ARRAY</i> scanned.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns the INTEGER(8) value derived from the characters <i>ARRAY</i>(1:<i>CNT</i>) scanned.
<p><hr /><P>

<h4><A NAME="2.5.2">2.5.2 FCB_CI_STRNCMPARR</a></h4>
<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_CI_STRNCMPARR(<i>STRING></i>, <i>ARRAY</i>, <i>N</i>, <i>LIMIT</i>)
      CHARACTER(LEN=*),INTENT(IN):: <i>STRING></i>
      INTEGER,         INTENT(IN):: <i>N</i>, <i>LIMIT</i>
      INTEGER(1),      INTENT(IN):: <i>ARRAY</i>(<i>N</i>)
      END FUNCTION
      END INTERFACE</pre>
<P>
The function FCB_CI_STRNCMPARR compares up to <i>LIMIT</i> characters of 
character string <i>STRING</i> and INTEGER(1) byte array <i>ARRAY</i> of
dimension <i>N</i> in a case-insensitive manner, returning 0 for a match.
<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>STRING</i><td valign="top">&nbsp;&nbsp;A character string
<TR><td valign="top">&nbsp;&nbsp;<i>ARRAY</i><td valign="top">&nbsp;&nbsp;The array of INTEGER(1) bytes to be scanned
<TR><td valign="top">&nbsp;&nbsp;<i>N</i><td valign="top">&nbsp;&nbsp;The INTEGER size of <i>ARRAY</i>
<TR><td valign="top">&nbsp;&nbsp;<i>N</i><td valign="top">&nbsp;&nbsp;The INTEGER limit on the number of characters to consider in the comparison
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns 0 if the string and array match, a non-zero value otherwise.
<p><hr /><P>

<h4><A NAME="2.5.3">2.5.3 FCB_EXIT_BINARY</a></h4>
<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_EXIT_BINARY(<i>TAPIN</i>,<i>LAST_CHAR</i>,<i>FCB_BYTES_IN_REC</i>,&amp;
                                      <i>BYTE_IN_FILE</i>,<i>REC_IN_FILE</i>,<i>BUFFER</i>,  &amp;
                                      <i>PADDING</i> )
      INTEGER,   INTENT(IN)   :: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>BYTE_IN_FILE</i>,<i>REC_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>LAST_CHAR</i>,<i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      INTEGER(8),INTENT(IN)   :: <i>PADDING</i>
      END FUNCTION
      END INTERFACE</pre>
<P>
The function FCB_EXIT_BINARY is used to skip from the end of a binary section
past any padding to the end of the text section that encloses the binary
section.  The values of the arguments must be consistent with those in the last call
to <A HREF="#2.5.5">FCB_NEXT_BINARY</a>
<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>TAPIN</i><td valign="top">&nbsp;&nbsp;The INTEGER Fortran 
device unit number assigned to image file.
<TR><td valign="top">&nbsp;&nbsp;<i>LAST_CHAR</i><td valign="top">&nbsp;&nbsp;The last character 
(as an INTEGER(1) byte) read.
<TR><td valign="top">&nbsp;&nbsp;<i>FCB_BYTES_IN_REC</i><td valign="top">&nbsp;&nbsp;The INTEGER
number of bytes in a record.
<TR><td valign="top">&nbsp;&nbsp;<i>BYTE_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER byte 
(counting from 1) of the byte to read.
<TR><td valign="top">&nbsp;&nbsp;<i>REC_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER record 
number (counting from 1) of next record to read.
<TR><td valign="top">&nbsp;&nbsp;<i>BUFFER</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) array of 
length <i>FCB_BYTES_IN_REC</i> to hold the appropriate record from <i>TAPIN</i>
<TR><td valign="top">&nbsp;&nbsp;<i>PADDING</i><td valign="top">&nbsp;&nbsp;The INTEGER(8) number of bytes 
of padding after the binary data and before the closing MIME boundary.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns 0 if the function is successful.  Returns whatever non-zero error value is reported by
<A HREF="#2.5.11">FCB_READ_LINE</a> if a necessary next line cannot be read.
<p>
<b>SEE ALSO</b>
<p>
<A HREF="#2.5.5">2.5.5  FCB_NEXT_BINARY</a><br />
<A HREF="#2.5.6">2.5.6  FCB_OPEN_CIFIN</a><br />
<A HREF="#2.5.9">2.5.9  FCB_READ_BYTE</a><br />
<A HREF="#2.5.11">2.5.11  FCB_READ_LINE</a>
<p><hr /><P>

<h4><A NAME="2.5.4">2.5.4 FCB_NBLEN_ARRAY</a></h4>
<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_NBLEN_ARRAY(<i>ARRAY</i>, <i>ARRAYLEN</i>)
      INTEGER,    INTENT(IN):: <i>ARRAYLEN</i>
      INTEGER(1), INTENT(IN):: <i>ARRAY</i>(<i>ARRAYLEN</i>)
      END FUNCTION
      END INTERFACE</pre>
<P>
The function FCB_NBLEN_ARRAY returns the trimmed length of the INTEGER(1)
byte array <i>ARRAY</i> of dimension <i>ARRAYLEN</i> after removal of
trailing ASCII blanks, horizontal tabs (Z'09'), newlines (Z'0A') and
carriage returns (Z'0D').  The resulting length may be zero.
<P>
The INTEGER trimmed length is returned as the function value.
<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>ARRAY</i><td valign="top">&nbsp;&nbsp;The array of bytes 
for which the trimmed length is required.
<TR><td valign="top">&nbsp;&nbsp;<i>ARRAYLEN</i><td valign="top">&nbsp;&nbsp;The dimension
of the array of bytes to be scanned.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns the trimmed length of the array <i>ARRAY</i>.
<p><hr /><P>
<h4><A NAME="2.5.5">2.5.5 FCB_NEXT_BINARY</a></h4>
<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_NEXT_BINARY(<i>TAPIN</i>,<i>LAST_CHAR</i>,<i>FCB_BYTES_IN_REC</i>,&amp;
                                      <i>BYTE_IN_FILE</i>,<i>REC_IN_FILE</i>,<i>BUFFER</i>,  &amp;
                                      <i>ENCODING</i>,<i>SIZE</i>,<i>ID</i>,<i>DIGEST</i>,          &amp;
                                      <i>COMPRESSION</i>,<i>BITS</i>,<i>VORZEICHEN</i>,<i>REELL</i>,&amp;
                                      <i>BYTEORDER</i>,<i>DIMOVER</i>,<i>DIM1</i>,<i>DIM2</i>,<i>DIM3</i>, &amp;
                                      <i>PADDING</i> )
      INTEGER,   INTENT(IN)   :: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>BYTE_IN_FILE</i>,<i>REC_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>LAST_CHAR</i>,<i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      INTEGER,   INTENT(OUT)  :: <i>ENCODING</i>
      INTEGER, INTENT(OUT)        :: <i>SIZE</i>    !Binary size
      INTEGER, INTENT(OUT)        :: <i>ID</i>      !Binary ID
      CHARACTER(len=*),INTENT(OUT):: <i>DIGEST</i>  !Message digest
      INTEGER,         INTENT(OUT):: <i>COMPRESSION</i>
      INTEGER,         INTENT(OUT):: <i>BITS</i>,<i>VORZEICHEN</i>,<i>REELL</i>
      CHARACTER(len=*),INTENT(OUT):: <i>BYTEORDER</i>
      INTEGER(8),      INTENT(OUT):: <i>DIMOVER</i>
      INTEGER(8),      INTENT(OUT):: <i>DIM1</i>
      INTEGER(8),      INTENT(OUT):: <i>DIM2</i>
      INTEGER(8),      INTENT(OUT):: <i>DIM3</i>
      INTEGER(8),      INTENT(OUT):: <i>PADDING</i>
      END FUNCTION
      END INTERFACE</pre>
<P>
The function FCB_NEXT_BINARY skips to the start of the next binary
section in the image file on unit <i>TAPIN</i> leaving the file
positioned for a subsequent read of the image data.  The skip may
prior to the text field that contains the binary section.  When
the text filed is reached, it will be scanned for a MIME boundary
marker, and, if it is found the subsequence MIME headers will
be used to populate the arguments <i>ENCODING</i>, <i>SIZE</i>,
<i>ID</i>, <i>DIGEST</i>, <i>COMPRESSION</i>, <i>BITS</i>,
<i>VORZEICHEN</i>,<i>REELL</i>, <i>BYTEORDER</i>, <i>DIMOVER</i>, 
<i>DIM1</i>, <i>DIM2</i>,<i>DIM3</i>, <i>PADDING</i>.

<P>
The value returned in <i>ENCODING</i> is taken from the
MIME header Content-Transfer-Encoding as an INTEGER.  It is returned
as 0 if not specified.  The reported value is one
of the integer values ENC_NONE (Z'0001') for BINARY encoding,
ENC_BASE64 (Z'0002') for BASE64 encoding,
ENC_BASE32K (Z'0004') for X-BASE32K encoding,
ENC_QP (Z'0008') for QUOTED-PRINTABLE encoding,
ENC_BASE10 (Z'0010') for BASE10 encoding,
ENC_BASE16 (Z'0020') for BASE16 encoding or
ENC_BASE8 (Z'0040') for BASE8  encoding.
<b>At this time FCBlib only supports
ENC_NONE BINARY encoding</b>.

<P>
The value returned in <i>SIZE</i> is taken from the
MIME header X-Binary-Size as an INTEGER.  It is returned
as 0 if not specified.
<P>
The value returned in <i>ID</i> is taken from the MIME header
X-Binary-ID as an INTEGER.  It is returned as 0 if not
specified. 
<P>
The value returned in <i>DIGEST</i> is taken from the
MIME header Content-MD5.  It is returned
as a character string.  If no digest is given, an empty
string is returned.
<P>
The value returned in <i>COMPRESSION</i> is taken from the
MIME header Content-Type in the conversions parameter.  The
reported value is one of the INTEGER values CBF_CANONICAL (Z'0050'),
CBF_PACKED (Z'0060'), CBF_PACKED_V2 (Z'0090'), CBF_BYTE_OFFSET (Z'0070'),
CBF_PREDICTOR (Z'0080'), CBF_NONE (Z'0040').  Two flags may be
combined with CBF_PACKED or CBF_PACKED_V2:  CBF_UNCORRELATED_SECTIONS (Z'0100')
or CBF_FLAT_IMAGE (Z'0200').  <b>At this time FCBlib does not support
CBF_PREDICTOR or CBF_NONE compression</b>.

<P>
The values returned in <i>BITS</i>, <i>VORZEICHEN</i> and <i>REELL</i>
are the parameters of the data types of the elements.  These values are
taken from the MIME header X-Binary-Element-Type, which has
values of the form "signed <i>BITS</i>-bit integer",
"unsigned <i>BITS</i>-bit integer", "signed <i>BITS</i>-bit real IEEE"
or "signed <i>BITS</i>-bit complex IEEE".  If no value is given,
<i>REELL</i> is reported as -1.  If the value in one of the integer
types, <i>REELL</i> is reported as 0.  If the value is one
of the real or complex types, <i>REELL</i> is reported as 1.
<b>In the current release of FCBlib only the integer types for
<i>BITS</i> equal to 16 or 32 are supported.</b>
  
<P>
The value returned in <i>BYTEORDER</i> is the byte order
of the data in the image file as reported in the MIME header.
The value, if specified, will be either the character string "LITTLE_ENDIAN"
or the character string "BIG_ENDIAN".  If no byte order is
specified, "LITTLE_ENDIAN" is reported.  This value is taken from
the MIME header X-Binary-Element-Byte-Order.  <b>As of this writing,
CBFlib will not generate "BIG_ENDIAN" byte-order files.  However,
both CBFlib and FCBlib read "LITTLE_ENDIAN" byte-order files, even 
on big-endian machines.</b>
<P>
The value returned in <i>DIMOVER</i> is the overall number
of elements in the image array, if specified, or zero, if not
specified.  This value is taken from the MIME header
X-Binary-Number-of-Elements.
The values returned in <i>DIM1</i>, <i>DIM2</i> and <i>DIM3</i>
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.  These
values are taken from the MIME header X-Binary-Size-Fastest-Dimension,
X-Binary-Size-Second-Dimension and X-Binary-Size-Third-Dimension
respectively.
<P>
The value returned in <i>PADDING</i> is the size of
the post-data padding, if any, if specified or zero,
if not specified.  The value is given as a count of octets.
This value is taken from the MIME header X-Binary-Size-Padding.

<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>TAPIN</i><td valign="top">&nbsp;&nbsp;The INTEGER Fortran 
device unit number assigned to image file.
<TR><td valign="top">&nbsp;&nbsp;<i>LAST_CHAR</i><td valign="top">&nbsp;&nbsp;The last character 
(as an INTEGER(1) byte) read.
<TR><td valign="top">&nbsp;&nbsp;<i>FCB_BYTES_IN_REC</i><td valign="top">&nbsp;&nbsp;The INTEGER
number of bytes in a record.
<TR><td valign="top">&nbsp;&nbsp;<i>BYTE_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER byte 
(counting from 1) of the byte to read.
<TR><td valign="top">&nbsp;&nbsp;<i>REC_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER record 
number (counting from 1) of next record to read.
<TR><td valign="top">&nbsp;&nbsp;<i>BUFFER</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) array of 
length <i>FCB_BYTES_IN_REC</i> to hold the appropriate record from <i>TAPIN</i>
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>ENCODING</i><td valign="top">&nbsp;&nbsp;INTEGER type of encoding for the binary section as reported in the MIME header.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>ID</i><td valign="top">&nbsp;&nbsp;INTEGER binary identifier as reported in the MIME header.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>SIZE</i><td valign="top">&nbsp;&nbsp;INTEGER size of compressed binary section as reported in the MIME header.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>DIGEST</i><td valign="top">&nbsp;&nbsp;The MD5 message digest as reported in the MIME header.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>COMPRESSION</i><td valign="top">&nbsp;&nbsp;INTEGER compression method as reported in the MIME header.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>BITS</i><td valign="top">&nbsp;&nbsp;INTEGER number of bits in each element as reported in the MIME header.<br />
<TR><TD VALIGN=TOP>&nbsp;&nbsp;<i>VORZEICHEN</i><td valign="top">&nbsp;&nbsp;INTEGER flag for signed or 
unsigned elements as reported in the MIME header. Set to 1 if the elements can be read as signed values,
0 otherwise.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>REELL</i><td valign="top">&nbsp;&nbsp;INTEGER flag for real elements as reported in the MIME header.  Set to 1 if the elements can be read as REAL<br />
<TR><td valign="top">&nbsp;&nbsp;<i>BYTEORDER</i><td valign="top">&nbsp;&nbsp;The byte order as reported in the MIME header.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>DIM1</i><td valign="top">&nbsp;&nbsp;Pointer to the destination fastest dimension.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>DIM2</i><td valign="top">&nbsp;&nbsp;Pointer to the destination second fastest dimension.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>DIM3</i><td valign="top">&nbsp;&nbsp;Pointer to the destination third fastest dimension.<br />
<TR><td valign="top">&nbsp;&nbsp;<i>PADDING</i><td valign="top">&nbsp;&nbsp;Pointer to the destination padding size.<br />
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns 0 if the function is successful.
<b>SEE ALSO</b>
<p>
<A HREF="#2.5.3">2.5.3  FCB_EXIT_BINARY</a><br />
<A HREF="#2.5.6">2.5.6  FCB_OPEN_CIFIN</a><br />
<A HREF="#2.5.9">2.5.9  FCB_READ_BYTE</a><br />
<A HREF="#2.5.11">2.5.11  FCB_READ_LINE</a>

<p><hr /><P>

<h4><A NAME="2.5.6">2.5.6 FCB_OPEN_CIFIN</a></h4>
<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_OPEN_CIFIN(<i>FILNAM</i>,<i>TAPIN</i>,<i>LAST_CHAR</i>,                &amp;
      <i>FCB_BYTES_IN_REC</i>,<i>BYTE_IN_FILE</i>,<i>REC_IN_FILE</i>,<i>BUFFER</i>)
      CHARACTER(len=*),INTENT(IN) :: <i>FILNAM</i>
      INTEGER,         INTENT(IN) :: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER(1),      INTENT(OUT):: <i>LAST_CHAR</i>
      INTEGER,         INTENT(OUT):: <i>BYTE_IN_FILE</i>,<i>REC_IN_FILE</i>
      INTEGER(1),    INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      INTEGER                        <i>FCB_RECORD_SIZE</i>
      END FUNCTION
      END INTERFACE</pre>
<P>
The function FCB_OPEN_CIFIN opens the CBF image file given by
the file name in the character string <i>FILNAM</i> on the
logical unit <i>TAPIN</i>.  The calling routine must provide
an INTEGER(1) byte buffer <i>BUFFER</i> of some appropriate
INTEGER size <i>FCB_BYTES_IN_REC</i>.  The size must be
chosen to suit the machine, but in most cases, 4096 will
work.  The values returned in <i>LAST_CHAR</i>, <i>BYTE_IN_FILE</i>,
and <i>REC_IN_FILE</i> are for use in subsequent FCBlib
I/O routines.

<P>
The image file will be checked for the initial characters "###CBF: ".  If
there is no match the error value CBF_FILEREAD is returned. 
<P> 
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>FILNAM</i><td valign="top">&nbsp;&nbsp;The
character string name of the image file to be opened.
<TR><td valign="top">&nbsp;&nbsp;<i>TAPIN</i><td valign="top">&nbsp;&nbsp;The INTEGER Fortran 
device unit number assigned to image file.
<TR><td valign="top">&nbsp;&nbsp;<i>LAST_CHAR</i><td valign="top">&nbsp;&nbsp;The last character 
(as an INTEGER(1) byte) read.
<TR><td valign="top">&nbsp;&nbsp;<i>FCB_BYTES_IN_REC</i><td valign="top">&nbsp;&nbsp;The INTEGER
number of bytes in a record.
<TR><td valign="top">&nbsp;&nbsp;<i>BYTE_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER byte 
(counting from 1) of the byte to read.
<TR><td valign="top">&nbsp;&nbsp;<i>REC_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER record 
number (counting from 1) of next record to read.
<TR><td valign="top">&nbsp;&nbsp;<i>BUFFER</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) array of 
length <i>FCB_BYTES_IN_REC</i> to hold the appropriate record from <i>TAPIN</i>
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns 0 if the function is successful.
<b>SEE ALSO</b>
<p>
<A HREF="#2.5.3">2.5.3  FCB_EXIT_BINARY</a><br />
<A HREF="#2.5.5">2.5.5  FCB_NEXT_BINARY</a><br />
<A HREF="#2.5.9">2.5.9  FCB_READ_BYTE</a><br />
<A HREF="#2.5.11">2.5.11  FCB_READ_LINE</a>

<p><hr /><P>


<h4><A NAME="2.5.7">2.5.7 FCB_PACKED: FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2, FCB_DECOMPRESS_PACKED_3D_I4</a></h4>

<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_DECOMPRESS_PACKED_I2 (<i>ARRAY</i>,<i>NELEM</i>,<i>NELEM_READ</i>, &amp;
        <i>ELSIGN</i>, <i>COMPRESSION</i>, <i>DIM1</i>, <i>DIM2</i>,  &amp;
        <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>BYTE_IN_FILE</i>,                   &amp;
        <i>REC_IN_FILE</i>,<i>BUFFER</i>)
      INTEGER(2),  INTENT(OUT):: <i>ARRAY</i>(<i>DIM1</i>,<i>DIM2</i>)
      INTEGER(8),  INTENT(OUT):: <i>NELEM_READ</i>
      INTEGER(8),   INTENT(IN):: <i>NELEM</i>
      INTEGER,      INTENT(IN):: <i>ELSIGN</i>, <i>COMPRESSION</i>
      INTEGER(8),   INTENT(IN):: <i>DIM1</i>,<i>DIM2</i> 
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      END FUNCTION
      END INTERFACE</pre>

<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_DECOMPRESS_PACKED_I4 (<i>ARRAY</i>,<i>NELEM</i>,<i>NELEM_READ</i>, &amp;
        <i>ELSIGN</i>, <i>COMPRESSION</i>, <i>DIM1</i>, <i>DIM2</i>,  &amp;
        <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>BYTE_IN_FILE</i>,                   &amp;
        <i>REC_IN_FILE</i>,<i>BUFFER</i>)
        
      INTEGER(4),  INTENT(OUT):: <i>ARRAY</i>(<i>DIM1</i>,<i>DIM2</i>)
      INTEGER(8),  INTENT(OUT):: <i>NELEM_READ</i>
      INTEGER(8),   INTENT(IN):: <i>NELEM</i>
      INTEGER,      INTENT(IN):: <i>ELSIGN</i>, <i>COMPRESSION</i>
      INTEGER(8),   INTENT(IN):: <i>DIM1</i>,<i>DIM2</i> 
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      END FUNCTION
      END INTERFACE</pre>

<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_DECOMPRESS_PACKED_3D_I2 (<i>ARRAY</i>,<i>NELEM</i>,<i>NELEM_READ</i>, &amp;
        <i>ELSIGN</i>, <i>COMPRESSION</i>, <i>DIM1</i>, <i>DIM2</i>, <i>DIM3</i>,  &amp;
        <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>BYTE_IN_FILE</i>,                   &amp;
        <i>REC_IN_FILE</i>,<i>BUFFER</i>)
      INTEGER(2),  INTENT(OUT):: <i>ARRAY</i>(<i>DIM1</i>,<i>DIM2</i>,<i>DIM3</i>)
      INTEGER(8),  INTENT(OUT):: <i>NELEM_READ</i>
      INTEGER(8),   INTENT(IN):: <i>NELEM</i>
      INTEGER,      INTENT(IN):: <i>ELSIGN</i>, <i>COMPRESSION</i>
      INTEGER(8),   INTENT(IN):: <i>DIM1</i>,<i>DIM2</i>,<i>DIM3</i> 
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      END FUNCTION
      END INTERFACE</pre>

<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_DECOMPRESS_PACKED_3D_I4 (<i>ARRAY</i>,<i>NELEM</i>,<i>NELEM_READ</i>, &amp;
        <i>ELSIGN</i>, <i>COMPRESSION</i>, <i>DIM1</i>, <i>DIM2</i>, <i>DIM3</i>,  &amp;
        <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>BYTE_IN_FILE</i>,                   &amp;
        <i>REC_IN_FILE</i>,<i>BUFFER</i>)
      INTEGER(4),  INTENT(OUT):: <i>ARRAY</i>(<i>DIM1</i>,<i>DIM2</i>,<i>DIM3</i>)
      INTEGER(8),  INTENT(OUT):: <i>NELEM_READ</i>
      INTEGER(8),   INTENT(IN):: <i>NELEM</i>
      INTEGER,      INTENT(IN):: <i>ELSIGN</i>, <i>COMPRESSION</i>
      INTEGER(8),   INTENT(IN):: <i>DIM1</i>,<i>DIM2</i>,<i>DIM3</i> 
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      END FUNCTION
      END INTERFACE</pre>
<p>The functions FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4, 
FCB_DECOMPRESS_PACKED_3D_I2 and FCB_DECOMPRESS_PACKED_3D_I4, decompress
images compress according the the CBF_PACKED or CBF_PACKED_V2
compression described in section <A HREF="#3.3.2">3.3.2</a> on 
J. P. Abrahams CCP4 packed compression.

<P>The relevant function should be called immediately after
a call to <A HREF="#2.5.5">FCB_NEXT_BINARY</a>, using the values
returned by <A HREF="#2.5.5">FCB_NEXT_BINARY</a> to select
the appropriate version of the function.
<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>ARRAY</i><td valign="top">&nbsp;&nbsp;The array to receive the image
<TR><td valign="top">&nbsp;&nbsp;<i>NELEM</i><td valign="top">&nbsp;&nbsp;The INTEGER(8) number of elements to be read
<TR><td valign="top">&nbsp;&nbsp;<i>NELEM_READ</i><td valign="top">&nbsp;&nbsp;The INTEGER(8) returned value of the number of elements actually read
<TR><td valign="top">&nbsp;&nbsp;<i>ELSIGN</i><td valign="top">&nbsp;&nbsp;The INTEGER value of the flag for signed (1) OR unsigned (0) data
<TR><td valign="top">&nbsp;&nbsp;<i>COMPRESSION</i><td valign="top">&nbsp;&nbsp;The compression of the image
<TR><td valign="top">&nbsp;&nbsp;<i>DIM1</i><td valign="top">&nbsp;&nbsp;The INTEGER(8) value of the fastest dimension of <i>ARRAY</i>
<TR><td valign="top">&nbsp;&nbsp;<i>DIM2</i><td valign="top">&nbsp;&nbsp;The INTEGER(8) value of the second fastest dimension
<TR><td valign="top">&nbsp;&nbsp;<i>DIM3</i><td valign="top">&nbsp;&nbsp;The INTEGER(8) value of the third fastest dimension
<TR><td valign="top">&nbsp;&nbsp;<i>TAPIN</i><td valign="top">&nbsp;&nbsp;The INTEGER Fortran 
device unit number assigned to image file.
<TR><td valign="top">&nbsp;&nbsp;<i>FCB_BYTES_IN_REC</i><td valign="top">&nbsp;&nbsp;The INTEGER
number of bytes in a record.
<TR><td valign="top">&nbsp;&nbsp;<i>BYTE_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER byte 
(counting from 1) of the byte to read.
<TR><td valign="top">&nbsp;&nbsp;<i>REC_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER record 
number (counting from 1) of next record to read.
<TR><td valign="top">&nbsp;&nbsp;<i>BUFFER</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) array of 
length <i>FCB_BYTES_IN_REC</i> to hold the appropriate record from <i>TAPIN</i>
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns 0 if the function is successful.
<P>
<b>SEE ALSO</b>
<p>
<A HREF="#2.5.3">2.5.3  FCB_EXIT_BINARY</a><br />
<A HREF="#2.5.5">2.5.5  FCB_NEXT_BINARY</a><br />
<A HREF="#2.5.6">2.5.6  FCB_OPEN_CIFIN</a><br />
<A HREF="#2.5.9">2.5.9  FCB_READ_BYTE</a><br />
<A HREF="#2.5.11">2.5.11  FCB_READ_LINE</a>



<p><hr /><P>

<h4><A NAME="2.5.8">2.5.8 FCB_READ_BITS</a></h4>
<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_READ_BITS(<i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>BUFFER</i>,     &amp;
                     <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>,<i>BCOUNT</i>,<i>BBYTE</i>,             &amp;
                     <i>BITCOUNT</i>,<i>IINT</i>,<i>LINT</i>)
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      INTEGER,   INTENT(INOUT):: <i>BCOUNT</i>
      INTEGER(1),INTENT(INOUT):: <i>BBYTE</i>
      INTEGER,      INTENT(IN):: <i>BITCOUNT</i>
      INTEGER,      INTENT(IN):: <i>LINT</i>
      INTEGER(4),  INTENT(OUT):: <i>IINT</i>(<i>LINT</i>)
      END FUNCTION
      END INTERFACE</pre>
<P>
The function FCB_READ_BITS gets the integer value starting at
<i>BYTE_IN_FILE</i> from file TAPIN continuing through BITCOUNT bits,
with sign extension.  <i>BYTE_IN_FILE</i> is left at the entry value
and not incremented.  The resulting, sign-extended integer value
is stored in the INTEGER(4) array <i>IINT</i> of dimension <i>LINT</i>
with the least significant portion in <i>IINT</i>(1).
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>TAPIN</i><td valign="top">&nbsp;&nbsp;The INTEGER Fortran 
device unit number assigned to image file.
<TR><td valign="top">&nbsp;&nbsp;<i>FCB_BYTES_IN_REC</i><td valign="top">&nbsp;&nbsp;The INTEGER
number of bytes in a record.
<TR><td valign="top">&nbsp;&nbsp;<i>BUFFER</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) array of 
length <i>FCB_BYTES_IN_REC</i> to hold the appropriate record from <i>TAPIN</i>
<TR><td valign="top">&nbsp;&nbsp;<i>REC_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER record 
number (counting from 1) of next record to read.
<TR><td valign="top">&nbsp;&nbsp;<i>BYTE_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER byte 
(counting from 1) of the byte to read.
<TR><td valign="top">&nbsp;&nbsp;<i>BCOUNT</i><td valign="top">&nbsp;&nbsp;The INTEGER count of
bits remaining unused from the last call to FCB_READ_BITS.
<TR><td valign="top">&nbsp;&nbsp;<i>BBYTE</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) byte
containing the unused bits from the last call to FCB_READ_BITS.
<TR><td valign="top">&nbsp;&nbsp;<i>BITCOUNT</i><td valign="top">&nbsp;&nbsp;The INTEGER count of
the number of bits to be extracted from the image file.
<TR><td valign="top">&nbsp;&nbsp;<i>IINT</i><td valign="top">&nbsp;&nbsp;The INTEGER(4) array 
into which to store the value extracted from the image file.
<TR><td valign="top">&nbsp;&nbsp;<i>LINT</i><td valign="top">&nbsp;&nbsp;The INTEGER length
of the array  <i>IINT</i>.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns 0 if the function is successful.  Because of the use of direct access I/O in blocks of
size <i>FCB_BYTES_IN_REC</i> the precise location of the end of file may not be detected.
<P>
<b>SEE ALSO</b>
<p>
<A HREF="#2.5.3">2.5.3  FCB_EXIT_BINARY</a><br />
<A HREF="#2.5.5">2.5.5  FCB_NEXT_BINARY</a><br />
<A HREF="#2.5.6">2.5.6  FCB_OPEN_CIFIN</a><br />
<A HREF="#2.5.9">2.5.9  FCB_READ_BYTE</a><br />
<A HREF="#2.5.11">2.5.11  FCB_READ_LINE</a>


<p><hr /><P>

<h4><A NAME="2.5.9">2.5.9 FCB_READ_BYTE</a></h4>
<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_READ_BYTE(<i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>BUFFER</i>,     &amp;
                             <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>,<i>IBYTE</i>)
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      INTEGER(1),  INTENT(OUT):: <i>IBYTE</i>
      END FUNCTION
      END INTERFACE</pre>
<P>
The function FCB_READ_BYTE reads the byte at the position <i>BYTE_IN_FILE</i>
in the image file <i>TAPIN</i>.  The first byte in the file is at
<i>BYTE_IN_FILE</i> = 1. <i>BYTE_IN_FILE</i> should be set to the
desired value before the call to the function and is not incremented within the
function.
<P>
The function attempts to suppress the error caused by a read
of a short last record, and in most systems cannot determine
the exact location of the end of the image file, returning
zero bytes until the equivalent of a full final record has been
read.
<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>TAPIN</i><td valign="top">&nbsp;&nbsp;The INTEGER Fortran 
device unit number assigned to image file.
<TR><td valign="top">&nbsp;&nbsp;<i>FCB_BYTES_IN_REC</i><td valign="top">&nbsp;&nbsp;The INTEGER
number of bytes in a record.
<TR><td valign="top">&nbsp;&nbsp;<i>BUFFER</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) array of 
length <i>FCB_BYTES_IN_REC</i> to hold the appropriate record from <i>TAPIN</i>
<TR><td valign="top">&nbsp;&nbsp;<i>REC_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER record 
number (counting from 1) of next record to read.
<TR><td valign="top">&nbsp;&nbsp;<i>BYTE_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER byte 
(counting from 1) of the byte to read.
<TR><td valign="top">&nbsp;&nbsp;<i>IBYTE</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) byte
found in the image file at the byte position <i>BYTE_IN_FILE</i>.
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns 0 if the function is successful.  Because of the use of direct access I/O in blocks of
size <i>FCB_BYTES_IN_REC</i> the precise location of the end of file may not be detected.
<P>
<b>SEE ALSO</b>
<p>
<A HREF="#2.5.3">2.5.3  FCB_EXIT_BINARY</a><br />
<A HREF="#2.5.5">2.5.5  FCB_NEXT_BINARY</a><br />
<A HREF="#2.5.6">2.5.6  FCB_OPEN_CIFIN</a><br />
<A HREF="#2.5.8">2.5.9  FCB_READ_BITS</a><br />
<A HREF="#2.5.11">2.5.11  FCB_READ_LINE</a>

<p><hr /><P>

<h4><A NAME="2.5.10">2.5.10 FCB_READ_IMAGE_I2, FCB_READ_IMAGE_I4, FCB_READ_IMAGE_3D_I2, FCB_READ_IMAGE_3D_I4</a></h4>

<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_READ_IMAGE_I2(<i>ARRAY</i>,<i>NELEM</i>,<i>NELEM_READ</i>, &amp;
        <i>ELSIGN</i>, <i>COMPRESSION</i>, <i>DIM1</i>, <i>DIM2</i>,                         &amp;
        <i>PADDING</i>,<i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>BYTE_IN_FILE</i>,             &amp;
        <i>REC_IN_FILE</i>,<i>BUFFER</i>)
      
      INTEGER(2),  INTENT(OUT):: <i>ARRAY</i>(<i>DIM1</i>,<i>DIM2</i>)
      INTEGER(8),  INTENT(OUT):: <i>NELEM_READ</i>
      INTEGER(8),   INTENT(IN):: <i>NELEM</i>
      INTEGER,      INTENT(IN):: <i>ELSIGN</i>
      INTEGER,     INTENT(OUT):: <i>COMPRESSION</i>
      INTEGER(8),   INTENT(IN):: <i>DIM1</i>,<i>DIM2</i> 
      INTEGER(8),  INTENT(OUT):: <i>PADDING</i>
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      END FUNCTION
      END INTERFACE</pre>

<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_READ_IMAGE_I4(<i>ARRAY</i>,<i>NELEM</i>,<i>NELEM_READ</i>, &amp;
        <i>ELSIGN</i>, <i>COMPRESSION</i>, <i>DIM1</i>, <i>DIM2</i>,                         &amp;
        <i>PADDING</i>,<i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>BYTE_IN_FILE</i>,             &amp;
        <i>REC_IN_FILE</i>,<i>BUFFER</i>)
      INTEGER(4),  INTENT(OUT):: <i>ARRAY</i>(<i>DIM1</i>,<i>DIM2</i>)
      INTEGER(8),  INTENT(OUT):: <i>NELEM_READ</i>
      INTEGER(8),   INTENT(IN):: <i>NELEM</i>
      INTEGER,      INTENT(IN):: <i>ELSIGN</i>
      INTEGER,     INTENT(OUT):: <i>COMPRESSION</i>
      INTEGER(8),   INTENT(IN):: <i>DIM1</i>,<i>DIM2</i> 
      INTEGER(8),  INTENT(OUT):: <i>PADDING</i>
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      END FUNCTION
      END INTERFACE</pre>

<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_READ_IMAGE_3D_I2(<i>ARRAY</i>,<i>NELEM</i>,<i>NELEM_READ</i>, &amp;
        <i>ELSIGN</i>, <i>COMPRESSION</i>, <i>DIM1</i>, <i>DIM2</i>, <i>DIM3</i>,                      &amp;
        <i>PADDING</i>,<i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>BYTE_IN_FILE</i>,                &amp;
        <i>REC_IN_FILE</i>,<i>BUFFER</i>)
      INTEGER(2),  INTENT(OUT):: <i>ARRAY</i>(<i>DIM1</i>,<i>DIM2</i>,<i>DIM3</i>)
      INTEGER(8),  INTENT(OUT):: <i>NELEM_READ</i>
      INTEGER(8),   INTENT(IN):: <i>NELEM</i>
      INTEGER,      INTENT(IN):: <i>ELSIGN</i>
      INTEGER,     INTENT(OUT):: <i>COMPRESSION</i>
      INTEGER(8),   INTENT(IN):: <i>DIM1</i>,<i>DIM2</i>,<i>DIM3</i> 
      INTEGER(8),  INTENT(OUT):: <i>PADDING</i>
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      END FUNCTION
      END INTERFACE</pre>

<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_READ_IMAGE_3D_I4(<i>ARRAY</i>,<i>NELEM</i>,<i>NELEM_READ</i>, &amp;
        <i>ELSIGN</i>, <i>COMPRESSION</i>, <i>DIM1</i>, <i>DIM2</i>, <i>DIM3</i>,                      &amp;
        <i>PADDING</i>,<i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>BYTE_IN_FILE</i>,                &amp;
        <i>REC_IN_FILE</i>,<i>BUFFER</i>)
      INTEGER(4),  INTENT(OUT):: <i>ARRAY</i>(<i>DIM1</i>,<i>DIM2</i>,<i>DIM3</i>)
      INTEGER(8),  INTENT(OUT):: <i>NELEM_READ</i>
      INTEGER(8),   INTENT(IN):: <i>NELEM</i>
      INTEGER,      INTENT(IN):: <i>ELSIGN</i>
      INTEGER,     INTENT(OUT):: <i>COMPRESSION</i>
      INTEGER(8),   INTENT(IN):: <i>DIM1</i>,<i>DIM2</i>,<i>DIM3</i> 
      INTEGER(8),  INTENT(OUT):: <i>PADDING</i>
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>
      INTEGER,   INTENT(INOUT):: <i>REC_IN_FILE</i>,<i>BYTE_IN_FILE</i>
      INTEGER(1),INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>)
      END FUNCTION
      END INTERFACE</pre>
<P>

The function FCB_READ_IMAGE_I2 reads a 16-bit twos complement
INTEGER(2) 2D image.  The function FCB_READ_IMAGE_I4 read
a 32-bit twos complement INTEGER(4) 2D image.  The function
FCB_READ_IMAGE_3D_I2 reads a 16-bit twos complement
INTEGER(2) 3D image.  The function
FCB_READ_IMAGE_3D_I4 reads a 32-bit twos complement
INTEGER(4) 3D image.  In each case the image is compressed
either by a BYTE_OFFSET algorithm by W. Kabsch based on a proposal 
by A. Hammersley or by a PACKED algorithm by J. P. Abrahams as
used in CCP4, with modifications by P. Ellis and H. J. Bernstein.
<P>The relevant function automatically first calls
<A HREF="#2.5.5">FCB_NEXT_BINARY</a> to skip to the
next binary section and then starts to read.  An error return
will result if the parameters of this call are inconsistent
with the values in MIME header.

<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>ARRAY</i><td valign="top">&nbsp;&nbsp;The array to receive the image
<TR><td valign="top">&nbsp;&nbsp;<i>NELEM</i><td valign="top">&nbsp;&nbsp;The INTEGER(8) number of elements to be read
<TR><td valign="top">&nbsp;&nbsp;<i>NELEM_READ</i><td valign="top">&nbsp;&nbsp;The INTEGER(8) returned value of the number of elements actually read
<TR><td valign="top">&nbsp;&nbsp;<i>ELSIGN</i><td valign="top">&nbsp;&nbsp;The INTEGER value of the flag for signed (1) OR unsigned (0) data
<TR><td valign="top">&nbsp;&nbsp;<i>COMPRESSION</i><td valign="top">&nbsp;&nbsp;The actual compression of the image
<TR><td valign="top">&nbsp;&nbsp;<i>DIM1</i><td valign="top">&nbsp;&nbsp;The INTEGER(8) value of the fastest dimension of <i>ARRAY</i>
<TR><td valign="top">&nbsp;&nbsp;<i>DIM2</i><td valign="top">&nbsp;&nbsp;The INTEGER(8) value of the second fastest dimension
<TR><td valign="top">&nbsp;&nbsp;<i>DIM3</i><td valign="top">&nbsp;&nbsp;The INTEGER(8) value of the third fastest dimension
<TR><td valign="top">&nbsp;&nbsp;<i>TAPIN</i><td valign="top">&nbsp;&nbsp;The INTEGER Fortran 
device unit number assigned to image file.
<TR><td valign="top">&nbsp;&nbsp;<i>FCB_BYTES_IN_REC</i><td valign="top">&nbsp;&nbsp;The INTEGER
number of bytes in a record.
<TR><td valign="top">&nbsp;&nbsp;<i>BYTE_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER byte 
(counting from 1) of the byte to read.
<TR><td valign="top">&nbsp;&nbsp;<i>REC_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER record 
number (counting from 1) of next record to read.
<TR><td valign="top">&nbsp;&nbsp;<i>BUFFER</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) array of 
length <i>FCB_BYTES_IN_REC</i> to hold the appropriate record from <i>TAPIN</i>
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns 0 if the function is successful.
<P>
<b>SEE ALSO</b>
<p>
<A HREF="#2.5.3">2.5.3  FCB_EXIT_BINARY</a><br />
<A HREF="#2.5.5">2.5.5  FCB_NEXT_BINARY</a><br />
<A HREF="#2.5.6">2.5.6  FCB_OPEN_CIFIN</a><br />
<A HREF="#2.5.7">2.5.7  FCB_DECOMPRESS: FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2, FCB_DECOMPRESS_PACKED_3D_I4</a><br />
<A HREF="#2.5.9">2.5.9  FCB_READ_BYTE</a><br />
<A HREF="#2.5.11">2.5.11  FCB_READ_LINE</a>

<p><hr /><P>

<h4><A NAME="2.5.11">2.5.11 FCB_READ_LINE</a></h4>
<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_READ_LINE(<i>TAPIN</i>,<i>LAST_CHAR</i>,<i>FCB_BYTES_IN_REC</i>,  &amp;
			 <i>BYTE_IN_FILE</i>,<i>REC_IN_FILE</i>,<i>BUFFER</i>,<i>LINE</i>,<i>N</i>,<i>LINELEN</i>)
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>N</i>
      INTEGER,   INTENT(INOUT):: <i>BYTE_IN_FILE</i>,<i>REC_IN_FILE</i>
      INTEGER,     INTENT(OUT):: <i>LINELEN</i>
      INTEGER(1),INTENT(INOUT):: <i>LAST_CHAR</i>,<i>BUFFER</i>,(<i>FCB_BYTES_IN_REC</i>)
      INTEGER(1),  INTENT(OUT):: <i>LINE</i>(<i>N</i>)
      END FUNCTION
      END INTERFACE</pre>
<P>
The function FCB_READ_LINE reads successive bytes into the INTEGER(1) byte array <i>LINE</i> of
dimension <i>N</i>), stopping at <i>N</i> bytes or the first error or the first
CR (Z'0D') or LF (Z'0A'), whichever comes first.  It discards an LF after a CR.
The variable <i>LAST_CHAR</i> is checked for the last character from the
previous line to make this determination.
<P>
The actual number of bytes read into the line, not including any terminal
CR or LF is stored in <i>LINELEN</i>.
<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>TAPIN</i><td valign="top">&nbsp;&nbsp;The INTEGER Fortran 
device unit number assigned to image file.
<TR><td valign="top">&nbsp;&nbsp;<i>LAST_CHAR</i><td valign="top">&nbsp;&nbsp;The INTEGER(1)
byte holding the ASCII value of the last character read for each line read.
<TR><td valign="top">&nbsp;&nbsp;<i>FCB_BYTES_IN_REC</i><td valign="top">&nbsp;&nbsp;The INTEGER
number of bytes in a record.
<TR><td valign="top">&nbsp;&nbsp;<i>BYTE_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER byte 
(counting from 1) of the byte to read.
<TR><td valign="top">&nbsp;&nbsp;<i>REC_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER record 
number (counting from 1) of next record to read.
<TR><td valign="top">&nbsp;&nbsp;<i>BUFFER</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) array of 
length <i>FCB_BYTES_IN_REC</i> to hold the appropriate record from <i>TAPIN</i>.
<TR><td valign="top">&nbsp;&nbsp;<i>LINE</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) array of 
length <i>N</i> to hold the line to be read from <i>TAPIN</i>.
<TR><td valign="top">&nbsp;&nbsp;<i>N</i><td valign="top">&nbsp;&nbsp;The INTEGER dimension of
<i>LINE</i>.
<TR><td valign="top">&nbsp;&nbsp;<i>LINELEN</i><td valign="top">&nbsp;&nbsp;The INTEGER number
of characters read into LINE.

</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns 0 if the function is successful.
<P>
<b>SEE ALSO</b>
<p>
<A HREF="#2.5.3">2.5.3  FCB_EXIT_BINARY</a><br />
<A HREF="#2.5.5">2.5.5  FCB_NEXT_BINARY</a><br />
<A HREF="#2.5.6">2.5.6  FCB_OPEN_CIFIN</a><br />
<A HREF="#2.5.7">2.5.7  FCB_DECOMPRESS: FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2, FCB_DECOMPRESS_PACKED_3D_I4</a><br />
<A HREF="#2.5.9">2.5.9  FCB_READ_BYTE</a>


<h4><A NAME="2.5.12">2.5.12 FCB_READ_XDS_I2</a></h4>
<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_READ_XDS_I2(<i>FILNAM</i>,<i>TAPIN</i>,<i>NX</i>,<i>NY</i>,<i>IFRAME</i>,<i>JFRAME</i>)
      CHARACTER(len=*),INTENT(IN) :: <i>FILNAM</i>
      INTEGER,         INTENT(IN) :: <i>TAPIN</i>,<i>NX</i>,<i>NY</i>
      INTEGER(2),      INTENT(OUT):: <i>IFRAME</i>(<i>NX</i>*<i>NY</i>)
      INTEGER(4),      INTENT(OUT):: <i>JFRAME</i>(<i>NX</i>,<i>NY</i>)
      END FUNCTION
      END INTERFACE</pre>
<P>
The function FCB_READ_XDS_I2 read a 32-bit integer twos complement
image into a 16-bit INTEGER(2) XDS image using the CBF_BYTE_OFFSET,
CBF_PACKED or CBF_PACKED_V2 compressions for the 32-bit data.  The
BYTE_OFFSET algorithm is a variant of the September 2006 version by 
W. Kabsch which was based on a suggestion by A. Hammersley and which
was further modified by H. Bernstein.

<P>The file named <i>FILNAM</i> is opened on the logical unit <i>TAPIN</i>
and <A HREF="#2.5.5">FCB_NEXT_BINARY</a> is used to skip to the next
binary image.  The binary image is then decompressed to produce an
XDS 16-bit integer image array <i>IFRAME</i> which is <i>NX</i> by <i>NY</i>.
The dimensions must agree with the dimensions specified in MIME header.

<P>
The conversion from a 32-bit integer I32 to 16-bit XDS pixel I16 is 
done as per W. Kabsch as follows:  The value I32 is limited to the range
-1023 &le; I32 &le;  1048576.  If I32 is outside that range it is truncated
to the closer boundary.  The generate I16, the 16-bit result, if I32 &gt;
32767, it is divided by 32 (producing a number between 1024 and 32768),
and then negated (producing a number between -1024 and -32768).
<P>For CBF_BYTE_OFFSET this conversion can be done on the fly directly
into the target array <i>IFRAME</i>, but
for the CBF_PACKED or CBF_PACKED_V2, the full 32 bit precision is
needed during the decompression, forcing the use of an intermediate
INTEGER(4) array <i>JFRAME</i> to hold the 32-bit image in that case.
<P>
The image file is closed after reading one image.

<P>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>FILNAM</i><td valign="top">&nbsp;&nbsp;The
character string name of the image file to be opened.
<TR><td valign="top">&nbsp;&nbsp;<i>TAPIN</i><td valign="top">&nbsp;&nbsp;The INTEGER Fortran 
device unit number assigned to image file.
<TR><td valign="top">&nbsp;&nbsp;<i>NX</i><td valign="top">&nbsp;&nbsp;The INTEGER fast
dimension of the image array. 
<TR><td valign="top">&nbsp;&nbsp;<i>NY</i><td valign="top">&nbsp;&nbsp;The INTEGER slow
dimension of the image array. 
<TR><td valign="top">&nbsp;&nbsp;<i>IFRAME</i><td valign="top">&nbsp;&nbsp;The INTEGER(2)
XDS image array. 
<TR><td valign="top">&nbsp;&nbsp;<i>JFRAME</i><td valign="top">&nbsp;&nbsp;The INTEGER(4)
32-bit image scratch array needed for CBF_PACKED or CBF_PACKED_V2 images. 
</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns 0 if the function is successful, CBF_FORMAT (=1) if it cannot handle 
this CBF format (not implemented), -1 if it cannot determine endian architecture 
of this machine, -2: if it cannot open the image file, -3: if it finds the wrong image 
format and -4 if it cannot read the image.
<P>
<p><hr /><P>

<h4><A NAME="2.5.13">2.5.13 FCB_SKIP_WHITESPACE</a></h4>
<p><pre><b>      INTERFACE</b>
      INTEGER FUNCTION FCB_SKIP_WHITESPACE(<i>TAPIN</i>,<i>LAST_CHAR</i>,             &amp;
		       <i>FCB_BYTES_IN_REC</i>,<i>BYTE_IN_FILE</i>,<i>REC_IN_FILE</i>,<i>BUFFER</i>,&amp;
		       <i>LINE</i>,<i>N</i>,<i>LINELEN</i>,<i>ICUR</i>,<i>FRESH_LINE</i>)
      INTEGER,      INTENT(IN):: <i>TAPIN</i>,<i>FCB_BYTES_IN_REC</i>,<i>N</i>
      INTEGER,   INTENT(INOUT):: <i>BYTE_IN_FILE</i>,<i>REC_IN_FILE</i>,<i>LINELEN</i>,<i>ICUR</i>, &amp;
				 <i>FRESH_LINE</i>
      INTEGER(1),INTENT(INOUT):: <i>BUFFER</i>(<i>FCB_BYTES_IN_REC</i>),<i>LINE</i>(<i>N</i>),      &amp;
				 LAST_CHAR
      END INTERFACE</pre>
<P>
The function FCB_SKIP_WHITESPACE skips forward on the current INTEGER(1) byte array 
<i>LINE</i> of size <i>N</i> with valid data in <i>LINE</i>(1:<i>LINELEN</i>) from 
the current position <i>ICUR</i> moving over MIME header whitespace and comments, 
reading new lines into <i>LINE</i> if needed. The flag <i>FRESH_LINE</i> indicates that a fresh line
should be read on entry.
<p>
<b>ARGUMENTS</b><br />
<TABLE>
<TR><td valign="top">&nbsp;&nbsp;<i>TAPIN</i><td valign="top">&nbsp;&nbsp;The INTEGER Fortran 
device unit number assigned to image file.
<TR><td valign="top">&nbsp;&nbsp;<i>LAST_CHAR</i><td valign="top">&nbsp;&nbsp;The INTEGER(1)
byte holding the ASCII value of the last character read for each line read.
<TR><td valign="top">&nbsp;&nbsp;<i>FCB_BYTES_IN_REC</i><td valign="top">&nbsp;&nbsp;The INTEGER
number of bytes in a record.
<TR><td valign="top">&nbsp;&nbsp;<i>BYTE_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER byte 
(counting from 1) of the byte to read.
<TR><td valign="top">&nbsp;&nbsp;<i>REC_IN_FILE</i><td valign="top">&nbsp;&nbsp;The INTEGER record 
number (counting from 1) of next record to read.
<TR><td valign="top">&nbsp;&nbsp;<i>BUFFER</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) array of 
length <i>FCB_BYTES_IN_REC</i> to hold the appropriate record from <i>TAPIN</i>.
<TR><td valign="top">&nbsp;&nbsp;<i>LINE</i><td valign="top">&nbsp;&nbsp;The INTEGER(1) array of 
length <i>N</i> to hold the line to be read from <i>TAPIN</i>.
<TR><td valign="top">&nbsp;&nbsp;<i>N</i><td valign="top">&nbsp;&nbsp;The INTEGER dimension of
<i>LINE</i>.
<TR><td valign="top">&nbsp;&nbsp;<i>LINELEN</i><td valign="top">&nbsp;&nbsp;The INTEGER number
of characters read into LINE.
<TR><td valign="top">&nbsp;&nbsp;<i>ICUR</i><td valign="top">&nbsp;&nbsp;The INTEGER position
within the line.
<TR><td valign="top">&nbsp;&nbsp;<i>FRESH_LINE</i><td valign="top">&nbsp;&nbsp;The INTEGER flag
that a fresh line is needed.

</TABLE>
<p>
<b>RETURN VALUE</b>
<p>
Returns 0 if the function is successful.
<P>
<b>SEE ALSO</b>
<p>
<A HREF="#2.5.3">2.5.3  FCB_EXIT_BINARY</a><br />
<A HREF="#2.5.5">2.5.5  FCB_NEXT_BINARY</a><br />
<A HREF="#2.5.6">2.5.6  FCB_OPEN_CIFIN</a><br />
<A HREF="#2.5.7">2.5.7  FCB_DECOMPRESS: FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2, FCB_DECOMPRESS_PACKED_3D_I4</a><br />
<A HREF="#2.5.9">2.5.9  FCB_READ_BYTE</a>
</p>
    <hr/>
    <div id="2.6">
      <h2>2.6 HDF5 abstraction layer and convenience functions</h2>
      <div>
	<p>The HDF5 abstraction layer mostly follows the HDF5 naming convention of <code>H5Xfunction_name</code>, where
	<code>X</code> is usually a single letter identifying the section of the API that the function resides in. A
	<code>cbf_</code> prefix is used on all functions to avoid naming conflicts and make it clear that all these
	functions use the CBFlib error handling method whenever an error may occur.</p>
	<p>The main purpose of this API is to not to reimplement the HDF5 API, but to make common HDF5-related tasks
	easier when working with HDF5 files within CBFlib. The API therefore doesn't attempt to cover every possible use
	of HDF5, but to simplify common tasks. Use of the HDF5 API is not unexpected in library or user code, but
	functions in this section should be preferred in order to reduce development time and the amount of debugging
	required. A relatively comprehensive test program is provided, this should be used to verify that the functions in
	this section of the API are performing as expected and can be used as a source of example code.</p>
      </div>
	<p>This section describes functions available for working with:</p>
      <ul>
        <li>
          <strong>Attributes:</strong>
			<ul>
            <li>
              <a href="#2.6.1">2.6.1 cbf_H5Acreate</a>
            </li>
            <li>
              <a href="#2.6.2">2.6.2 cbf_H5Afind</a>
            </li>
            <li>
              <a href="#2.6.3">2.6.3 cbf_H5Aread</a>
            </li>
            <li>
              <a href="#2.6.4">2.6.4 cbf_H5Aread_string</a>
            </li>
            <li>
              <a href="#2.6.5">2.6.5 cbf_H5Awrite</a>
            </li>
            <li>
              <a href="#2.6.6">2.6.6 cbf_H5Arequire_cmp2</a>
            </li>
            <li>
              <a href="#2.6.7">2.6.7 cbf_H5Arequire_cmp2_ULP</a>
            </li>
            <li>
              <a href="#2.6.8">2.6.8 cbf_H5Arequire_string</a>
            </li>
            <li>
              <a href="#2.6.9">2.6.9 cbf_H5Afree</a>
            </li>
			</ul>
		</li>
        <li>
          <strong>Datasets:</strong>
			<ul>
            <li>
              <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
            </li>
            <li>
              <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
            </li>
            <li>
              <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
            </li>
            <li>
              <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
            </li>
            <li>
              <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
            </li>
            <li>
              <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
            </li>
            <li>
              <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
            </li>
            <li>
              <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
            </li>
            <li>
              <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
            </li>
            <li>
              <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
            </li>
            <li>
              <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
            </li>
			</ul>
		</li>
        <li>
          <strong>Files:</strong>
			<ul>
            <li>
              <a href="#2.6.21">2.6.21 cbf_H5Fopen</a>
            </li>
            <li>
              <a href="#2.6.22">2.6.22 cbf_H5Fclose</a>
            </li>
			</ul>
		</li>
        <li>
          <strong>Groups:</strong>
			<ul>
            <li>
              <a href="#2.6.23">2.6.23 cbf_H5Gcreate</a>
            </li>
            <li>
              <a href="#2.6.24">2.6.24 cbf_H5Gfind</a>
            </li>
            <li>
              <a href="#2.6.25">2.6.25 cbf_H5Grequire</a>
            </li>
            <li>
              <a href="#2.6.26">2.6.26 cbf_H5Gfree</a>
            </li>
			</ul>
		</li>
        <li>
          <strong>Identifiers:</strong>
			<ul>
            <li>
              <a href="#2.6.27">2.6.27 cbf_H5Ivalid</a>
            </li>
			</ul>
		</li>
        <li>
          <strong>Objects:</strong>
			<ul>
            <li>
              <a href="#2.6.28">2.6.28 cbf_H5Ocmp</a>
            </li>
            <li>
              <a href="#2.6.29">2.6.29 cbf_H5Ofree</a>
            </li>
			</ul>
		</li>
        <li>
          <strong>Dataspaces:</strong>
			<ul>
            <li>
              <a href="#2.6.30">2.6.30 cbf_H5Screate</a>
            </li>
            <li>
              <a href="#2.6.31">2.6.31 cbf_H5Sfree</a>
            </li>
			</ul>
		</li>
        <li>
          <strong>Datatypes:</strong>
          <ul>
            <li>
              <a href="#2.6.32">2.6.32 cbf_H5Tcreate_string</a>
            </li>
            <li>
              <a href="#2.6.33">2.6.33 cbf_H5Tfree</a>
            </li>
	</ul>
        </li>
      </ul>
      <div>
	<h4>Rank of a dataset</h4>
	<p>Where a <code>rank</code> is required it must be equal to the length of the <code>dim</code>, <code>max</code>
	&amp; <code>chunk</code> parameters, if they are given, and should be:</p>
	<ul>
		<li><code>0</code>, for scalar data</li>
		<li><code>1</code>, for vector data</li>
		<li><code>2</code>, for matrix data</li>
		<li><code>3</code>, for volume data</li>
		<li>etc...</li>
	</ul>
        <p>The maximum rank is defined by the HDF5 library, a negative rank makes no sense and will often be treated as an error.</p>
      </div>
      <div>
	<h4>HDF5-specific datatypes</h4>
	<p>Any <code>type</code> parameters defining types for data stored in a file should usually be a value returned by
	<code>cbf_H5Tcreate_string</code> or one of the standard or IEEE types:</p>
	<table class="hdf5-types">
		<tr>
            <td class="col0">
              <code>H5T_STD_I8LE</code>
            </td>
            <td class="col1">
              <code>H5T_STD_I16LE</code>
            </td>
            <td class="col2">
              <code>H5T_STD_I32LE</code>
            </td>
            <td class="col3">
              <code>H5T_STD_I64LE</code>
            </td>
		</tr>
		<tr>
            <td class="col0">
              <code>H5T_STD_U8LE</code>
            </td>
            <td class="col1">
              <code>H5T_STD_U16LE</code>
            </td>
            <td class="col2">
              <code>H5T_STD_U32LE</code>
            </td>
            <td class="col3">
              <code>H5T_STD_U64LE</code>
            </td>
		</tr>
		<tr>
            <td class="col0">
              <code>H5T_STD_I8BE</code>
            </td>
            <td class="col1">
              <code>H5T_STD_I16BE</code>
            </td>
            <td class="col2">
              <code>H5T_STD_I32BE</code>
            </td>
            <td class="col3">
              <code>H5T_STD_I64BE</code>
            </td>
		</tr>
		<tr>
            <td class="col0">
              <code>H5T_STD_U8BE</code>
            </td>
            <td class="col1">
              <code>H5T_STD_U16BE</code>
            </td>
            <td class="col2">
              <code>H5T_STD_U32BE</code>
            </td>
            <td class="col3">
              <code>H5T_STD_U64BE</code>
            </td>
		</tr>
		<tr>
            <td class="col0">
              <code>H5T_IEEE_F32LE</code>
            </td>
            <td class="col1">
              <code>H5T_IEEE_F64LE</code>
            </td>
            <td class="col0">
              <code>H5T_IEEE_F32BE</code>
            </td>
            <td class="col1">
              <code>H5T_IEEE_F64BE</code>
            </td>
		</tr>
        </table>
        <p>Any <code>type</code> parameters defining types for data stored in memory should usually
	be a value returned by <code>cbf_H5Tcreate_string</code> or one of the native types:</p>
	<table class="hdf5-types">
		<tr>
            <td class="col0">
              <code>H5T_NATIVE_SCHAR</code>
            </td>
            <td class="col1">
              <code>H5T_NATIVE_SHORT</code>
            </td>
            <td class="col2">
              <code>H5T_NATIVE_INT</code>
            </td>
            <td class="col3">
              <code>H5T_NATIVE_LONG</code>
            </td>
            <td class="col4">
              <code>H5T_NATIVE_LLONG</code>
            </td>
		</tr>
		<tr>
            <td class="col0">
              <code>H5T_NATIVE_UCHAR</code>
            </td>
            <td class="col1">
              <code>H5T_NATIVE_USHORT</code>
            </td>
            <td class="col2">
              <code>H5T_NATIVE_UINT</code>
            </td>
            <td class="col3">
              <code>H5T_NATIVE_ULONG</code>
            </td>
            <td class="col4">
              <code>H5T_NATIVE_ULLONG</code>
            </td>
		</tr>
		<tr>
            <td class="col0">
              <code>H5T_NATIVE_FLOAT</code>
            </td>
            <td class="col1">
              <code>H5T_NATIVE_DOUBLE</code>
            </td>
            <td class="col2">
              <code>H5T_NATIVE_LDOUBLE</code>
            </td>
		</tr>
        </table>
        <p>Functions are rarely (if ever) limited to the above values, and can take any valid HDF5 datatype. The above is
	not a complete list of all available types, check the HDF5 documentation for such a list if you need one.</p>
      </div>
      <div>
	<h4>Comparing data</h4>
	<p>Some of the functions in this section will require a comparison function and some comparison parameters to be
	provided. The function should return zero if the data in the two arrays are considered equal and non-zero otherwise, note that
	this is the same as <code>C</code>'s <code>strcmp()</code>. The signature of the comparison functions used here
	is:</p>
        <p>
          <code>int compare 
	(const void * expected,
	 const void * existing,
	 size_t length,
	const void * params)</code>
        </p>
	<p>This will be called with:</p>
        <table class="params">
          <tr style="background:none;">
            <th style="border-top-left-radius:5px;">Type</th>
            <th>Name</th>
            <th style="border-top-right-radius:5px;">Description</th>
          </tr>
          <tr>
            <td class="type">const void *</td>
            <td class="name">expected</td>
            <td class="desc">A pointer to the array of requested values that was passed to the function.</td>
          </tr>
          <tr>
            <td class="type">const void *</td>
            <td class="name">existing</td>
            <td class="desc">An array of existing values read from the object.</td>
          </tr>
          <tr>
            <td class="type">size_t</td>
            <td class="name">length</td>
            <td class="desc">The length of the <code>expected</code> and <code>existing</code> arrays.</td>
          </tr>
          <tr>
            <td class="type">const void *</td>
            <td class="name">params</td>
            <td class="desc">A pointer to the comparison parameters which were passed to the calling function.</td>
          </tr>
	</table>
        <p>The comparison parameters allow more complex comparisons to be performed, such as a check that the numbers are 'close
	enough' as determined by some variable measure of closeness. It is the caller's responsibility to ensure that the comparison
	function is appropriate for the type of data expected and that <code>params</code> is of the appropriate type for the
	comparison function. The parameters <code>expected</code> and <code>existing</code> should normally be cast to the appropriate
	type before being used.</p>
	<p>An example function for comparing <code>int</code>s, taken from the implementation of CBFlib:</p>
        <code>
          <pre>/*
Compare two arrays of ints.
Most parameters are defined as being 'const' even though
the expected signature allows them to be mutable.
*/
int cmp_int
    (const void * const expected,
     const void * const existing,
     size_t length,
     const void * const params)
{
	/*
    Cast the array pointers to the appropriate type, preserving the const-ness of the data.
    I won't be using any parameters for this comparison, so just ignore that argument.
	*/
    const int * A = expected;
    const int * B = existing;

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

	/*
    Return a value indicating whether the arrays are equal.
	*/
    return length;
}</pre>
        </code>
        <p>Some older functions use a simpler 3-argument comparison function, which doesn't have a parameter that can be used
	to pass some extra information to or retrieve information from the function.</p>
      </div>
	<hr/>
      <div class="function" id="2.6.1">
        <h4>2.6.1 cbf_H5Acreate</h4>
        <p>Create a new attribute. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Acreate (const hid_t location, hid_t *const attr, const char *const name, const hid_t type, const hid_t space)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Creates a new attribute of the object <code>location</code> with name given by <code>name</code>, optionally returning it in the <code>attr</code> variable. An error will occur if a similarly named attribute already exists.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>The hdf5 group/file in which to put the attribute. </p>
            </td>
          </tr>
          <tr>
            <td class="name">attr</td>
            <td class="desc">
              <p>A pointer to a HDF5 object identifier that is set to the location of a valid object if the function succeeds, otherwise is left untouched. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the existing/new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">type</td>
            <td class="desc">
              <p>The type of data to be stored in the attribute. </p>
            </td>
          </tr>
          <tr>
            <td class="name">space</td>
            <td class="desc">
              <p>The dataspace of the attribute. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.2">2.6.2 cbf_H5Afind</a>
          </li>
          <li>
            <a href="#2.6.3">2.6.3 cbf_H5Aread</a>
          </li>
          <li>
            <a href="#2.6.4">2.6.4 cbf_H5Aread_string</a>
          </li>
          <li>
            <a href="#2.6.5">2.6.5 cbf_H5Awrite</a>
          </li>
          <li>
            <a href="#2.6.6">2.6.6 cbf_H5Arequire_cmp2</a>
          </li>
          <li>
            <a href="#2.6.7">2.6.7 cbf_H5Arequire_cmp2_ULP</a>
          </li>
          <li>
            <a href="#2.6.8">2.6.8 cbf_H5Arequire_string</a>
          </li>
          <li>
            <a href="#2.6.9">2.6.9 cbf_H5Afree</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.6.2">
        <h4>2.6.2 cbf_H5Afind</h4>
        <p>Try to locate an existing attribute. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Afind (const hid_t location, hid_t *const attr, const char *const name, const hid_t type, const hid_t space)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Checks for the existance of an attribute with the given <code>name</code> at <code>location</code> with a datatype of <code>type</code> and dataspace of <code>space</code>. Will return <code>CBF_NOTFOUND</code> if it cannot be found, or open it if it already exists.</p>
        <p>If <code>type</code> is not a datatype then no check of the attribute datatype will be done. If <code>space</code> is not a dataspace then no checks of the attribute dataspace wil be done.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>The hdf5 group/file in which to put the attribute. </p>
            </td>
          </tr>
          <tr>
            <td class="name">attr</td>
            <td class="desc">
              <p>A pointer to a HDF5 object identifier that is set to the location of a valid object if the function succeeds, otherwise is left untouched. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the existing/new attribute. </p>
            </td>
          </tr>
          <tr>
            <td class="name">type</td>
            <td class="desc">
              <p>The type of data stored in the attribute, or an invalid identifier if it should not be checked. </p>
            </td>
          </tr>
          <tr>
            <td class="name">space</td>
            <td class="desc">
              <p>The dataspace of the attribute, or an invalid identifier if it should not be checked. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.1">2.6.1 cbf_H5Acreate</a>
          </li>
          <li>
            <a href="#2.6.3">2.6.3 cbf_H5Aread</a>
          </li>
          <li>
            <a href="#2.6.4">2.6.4 cbf_H5Aread_string</a>
          </li>
          <li>
            <a href="#2.6.5">2.6.5 cbf_H5Awrite</a>
          </li>
          <li>
            <a href="#2.6.6">2.6.6 cbf_H5Arequire_cmp2</a>
          </li>
          <li>
            <a href="#2.6.7">2.6.7 cbf_H5Arequire_cmp2_ULP</a>
          </li>
          <li>
            <a href="#2.6.8">2.6.8 cbf_H5Arequire_string</a>
          </li>
          <li>
            <a href="#2.6.9">2.6.9 cbf_H5Afree</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.6.3">
        <h4>2.6.3 cbf_H5Aread</h4>
        <p>Read an entire attribute from a file. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Aread (const hid_t attr, const hid_t type, void *const buf)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Reads all of the data from <code>attr</code> into <code>buf</code>, which should have been allocated as the native type indicated by <code>mem_type</code>.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">attr</td>
            <td class="desc">
              <p>A valid hdf5 handle for an attribute. </p>
            </td>
          </tr>
          <tr>
            <td class="name">type</td>
            <td class="desc">
              <p>The type of data in memory. </p>
            </td>
          </tr>
          <tr>
            <td class="name">buf</td>
            <td class="desc">
              <p>The location where the data is to be stored. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.1">2.6.1 cbf_H5Acreate</a>
          </li>
          <li>
            <a href="#2.6.2">2.6.2 cbf_H5Afind</a>
          </li>
          <li>
            <a href="#2.6.4">2.6.4 cbf_H5Aread_string</a>
          </li>
          <li>
            <a href="#2.6.5">2.6.5 cbf_H5Awrite</a>
          </li>
          <li>
            <a href="#2.6.6">2.6.6 cbf_H5Arequire_cmp2</a>
          </li>
          <li>
            <a href="#2.6.7">2.6.7 cbf_H5Arequire_cmp2_ULP</a>
          </li>
          <li>
            <a href="#2.6.8">2.6.8 cbf_H5Arequire_string</a>
          </li>
          <li>
            <a href="#2.6.9">2.6.9 cbf_H5Afree</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.6.4">
        <h4>2.6.4 cbf_H5Aread_string</h4>
        <p>Read an entire string attribute from a file. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Aread_string (const hid_t attr, const char **const val)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Read a string attribute into memory, returning a pointer that must be free'd by the caller in <code>val</code>.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">attr</td>
            <td class="desc">
              <p>The attribute to read from. </p>
            </td>
          </tr>
          <tr>
            <td class="name">val</td>
            <td class="desc">
              <p>A pointer to a place the string may be stored. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.1">2.6.1 cbf_H5Acreate</a>
          </li>
          <li>
            <a href="#2.6.2">2.6.2 cbf_H5Afind</a>
          </li>
          <li>
            <a href="#2.6.3">2.6.3 cbf_H5Aread</a>
          </li>
          <li>
            <a href="#2.6.5">2.6.5 cbf_H5Awrite</a>
          </li>
          <li>
            <a href="#2.6.6">2.6.6 cbf_H5Arequire_cmp2</a>
          </li>
          <li>
            <a href="#2.6.7">2.6.7 cbf_H5Arequire_cmp2_ULP</a>
          </li>
          <li>
            <a href="#2.6.8">2.6.8 cbf_H5Arequire_string</a>
          </li>
          <li>
            <a href="#2.6.9">2.6.9 cbf_H5Afree</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.6.5">
        <h4>2.6.5 cbf_H5Awrite</h4>
        <p>Write an entire attribute to a file. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Awrite (const hid_t attr, const hid_t type, void *const buf)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Writes all of the data from <code>buf</code>, which should contain data if the type indicated by <code>mem_type</code>, into <code>attr</code>.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">attr</td>
            <td class="desc">
              <p>A valid hdf5 handle for an attribute. </p>
            </td>
          </tr>
          <tr>
            <td class="name">type</td>
            <td class="desc">
              <p>The type of data in memory. </p>
            </td>
          </tr>
          <tr>
            <td class="name">buf</td>
            <td class="desc">
              <p>The address of the data to be written. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.1">2.6.1 cbf_H5Acreate</a>
          </li>
          <li>
            <a href="#2.6.2">2.6.2 cbf_H5Afind</a>
          </li>
          <li>
            <a href="#2.6.3">2.6.3 cbf_H5Aread</a>
          </li>
          <li>
            <a href="#2.6.4">2.6.4 cbf_H5Aread_string</a>
          </li>
          <li>
            <a href="#2.6.6">2.6.6 cbf_H5Arequire_cmp2</a>
          </li>
          <li>
            <a href="#2.6.7">2.6.7 cbf_H5Arequire_cmp2_ULP</a>
          </li>
          <li>
            <a href="#2.6.8">2.6.8 cbf_H5Arequire_string</a>
          </li>
          <li>
            <a href="#2.6.9">2.6.9 cbf_H5Afree</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.6.6">
        <h4>2.6.6 cbf_H5Arequire_cmp2</h4>
	<p>Check for an attribute with the given space/type/value, or set one if it doesn't exist.</p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Arequire_cmp2 (const hid_t ID, const char *const name, const int rank, const hsize_t *const dim, const hid_t fileType, const hid_t memType, const void *const value, void *const buf, int(*cmp)(const void *, const void *, size_t))</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Checks the existance of an attribute of the given name, size, type and value. Equal value is determined by a custom comparison function which may use some extra data for more sophisticated tests. A new attribute with the given properties will be created if none currently exist, the function will fail if an incompatible attribute exists.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">ID</td>
            <td class="desc">
              <p>The HDF5 object that the attribute will be applied to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the attribute. </p>
            </td>
          </tr>
          <tr>
            <td class="name">rank</td>
            <td class="desc">
              <p>The number of dimensions of the attribute data, 0 for scalar data. </p>
            </td>
          </tr>
          <tr>
            <td class="name">dim</td>
            <td class="desc">
              <p>The length of each dimension, not used for scalar data. </p>
            </td>
          </tr>
          <tr>
            <td class="name">fileType</td>
            <td class="desc">
              <p>The HDF5 type of the attribute data in the file. </p>
            </td>
          </tr>
          <tr>
            <td class="name">memType</td>
            <td class="desc">
              <p>The HDF5 type of the attribute data in memory. </p>
            </td>
          </tr>
          <tr>
            <td class="name">value</td>
            <td class="desc">
              <p>The data to be written to the attribute. </p>
            </td>
          </tr>
          <tr>
            <td class="name">buf</td>
            <td class="desc">
              <p>A buffer to be used when reading an existing attribute of the same size. </p>
            </td>
          </tr>
          <tr>
            <td class="name">cmp</td>
            <td class="desc">
              <p>A comparison function to test if a previously set value is equal to the value I asked for. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.1">2.6.1 cbf_H5Acreate</a>
          </li>
          <li>
            <a href="#2.6.2">2.6.2 cbf_H5Afind</a>
          </li>
          <li>
            <a href="#2.6.3">2.6.3 cbf_H5Aread</a>
          </li>
          <li>
            <a href="#2.6.4">2.6.4 cbf_H5Aread_string</a>
          </li>
          <li>
            <a href="#2.6.5">2.6.5 cbf_H5Awrite</a>
          </li>
          <li>
            <a href="#2.6.7">2.6.7 cbf_H5Arequire_cmp2_ULP</a>
          </li>
          <li>
            <a href="#2.6.8">2.6.8 cbf_H5Arequire_string</a>
          </li>
          <li>
            <a href="#2.6.9">2.6.9 cbf_H5Afree</a>
          </li>
        </ul>
      </div>
	<hr />
      <div class="function" id="2.6.7">
        <h4>2.6.7 cbf_H5Arequire_cmp2_ULP</h4>
        <p>Check for an attribute with the given space/type/value, or set one if it doesn't exist. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Arequire_cmp2_ULP (const hid_t ID, const char *const name, const int rank, const hsize_t *const dim, const hid_t fileType, const hid_t memType, const void *const value, void *const buf, int(*cmp)(const void *, const void *, size_t, const void *), const void *const cmp_params)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Checks the existance of an attribute of the given name, size, type and value. Equal value is determined by a custom comparison function which may use some extra data for more sophisticated tests. A new attribute with the given properties will be created if none currently exist, the function will fail if an incompatible attribute exists.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">ID</td>
            <td class="desc">
              <p>The HDF5 object that the attribute will be applied to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the attribute. </p>
            </td>
          </tr>
          <tr>
            <td class="name">rank</td>
            <td class="desc">
              <p>The number of dimensions of the attribute data, 0 for scalar data. </p>
            </td>
          </tr>
          <tr>
            <td class="name">dim</td>
            <td class="desc">
              <p>The length of each dimension, not used for scalar data. </p>
            </td>
          </tr>
          <tr>
            <td class="name">fileType</td>
            <td class="desc">
              <p>The HDF5 type of the attribute data in the file. </p>
            </td>
          </tr>
          <tr>
            <td class="name">memType</td>
            <td class="desc">
              <p>The HDF5 type of the attribute data in memory. </p>
            </td>
          </tr>
          <tr>
            <td class="name">value</td>
            <td class="desc">
              <p>The data to be written to the attribute. </p>
            </td>
          </tr>
          <tr>
            <td class="name">buf</td>
            <td class="desc">
              <p>A buffer to be used when reading an existing attribute of the same size. </p>
            </td>
          </tr>
          <tr>
            <td class="name">cmp</td>
            <td class="desc">
              <p>A comparison function to test if a previously set value is equal to the value I asked for. </p>
            </td>
          </tr>
          <tr>
            <td class="name">cmp_params</td>
            <td class="desc">
              <p>A pointer to a data structure which may be used by the comparison function. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.1">2.6.1 cbf_H5Acreate</a>
          </li>
          <li>
            <a href="#2.6.2">2.6.2 cbf_H5Afind</a>
          </li>
          <li>
            <a href="#2.6.3">2.6.3 cbf_H5Aread</a>
          </li>
          <li>
            <a href="#2.6.4">2.6.4 cbf_H5Aread_string</a>
          </li>
          <li>
            <a href="#2.6.5">2.6.5 cbf_H5Awrite</a>
          </li>
          <li>
            <a href="#2.6.6">2.6.6 cbf_H5Arequire_cmp2</a>
          </li>
          <li>
            <a href="#2.6.8">2.6.8 cbf_H5Arequire_string</a>
          </li>
          <li>
            <a href="#2.6.9">2.6.9 cbf_H5Afree</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.6.8">
        <h4>2.6.8 cbf_H5Arequire_string</h4>
	<p>Check for a scalar string attribute with a given value, or set one if it doesn't exist.</p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Arequire_string (const hid_t location, const char *const name, const char *const value)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Forwarding function that calls <code>cbf_H5Arequire_cmp2_ULP</code> with the appropriate arguments to compare two strings. The <code>strcmp</code> function is used for string comparison, with a small wrapper to verify array length:</p>
        <code>
          <pre>/** a possible implementation of a function to compare two strings for equality */
static int cmp_string
    (const void * const a,
     const void * const b,
     const size_t N,
     const void * const params)
{
	/* first ensure the arrays have one element each */
    if (1 != N) return 1;
	/* then forward to 'strcmp' for the actual comparison */
    else return strcmp(a,b);
}</pre>
        </code>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>HDF5 object to which the string attribute should/will belong. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the attribute. </p>
            </td>
          </tr>
          <tr>
            <td class="name">value</td>
            <td class="desc">
              <p>The value which the attribute should/will have. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.1">2.6.1 cbf_H5Acreate</a>
          </li>
          <li>
            <a href="#2.6.2">2.6.2 cbf_H5Afind</a>
          </li>
          <li>
            <a href="#2.6.3">2.6.3 cbf_H5Aread</a>
          </li>
          <li>
            <a href="#2.6.4">2.6.4 cbf_H5Aread_string</a>
          </li>
          <li>
            <a href="#2.6.5">2.6.5 cbf_H5Awrite</a>
          </li>
          <li>
            <a href="#2.6.6">2.6.6 cbf_H5Arequire_cmp2</a>
          </li>
          <li>
            <a href="#2.6.7">2.6.7 cbf_H5Arequire_cmp2_ULP</a>
          </li>
          <li>
            <a href="#2.6.9">2.6.9 cbf_H5Afree</a>
          </li>
        </ul>
      </div>
	<hr />
      <div class="function" id="2.6.9">
        <h4>2.6.9 cbf_H5Afree</h4>
        <p>Close a HDF5 attribute. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Afree (const hid_t ID)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Attempt to close an attribute, but don't modify the identifier that described it.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">ID</td>
            <td class="desc">
              <p>The HDF5 attribute to be closed. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.1">2.6.1 cbf_H5Acreate</a>
          </li>
          <li>
            <a href="#2.6.2">2.6.2 cbf_H5Afind</a>
          </li>
          <li>
            <a href="#2.6.3">2.6.3 cbf_H5Aread</a>
          </li>
          <li>
            <a href="#2.6.4">2.6.4 cbf_H5Aread_string</a>
          </li>
          <li>
            <a href="#2.6.5">2.6.5 cbf_H5Awrite</a>
          </li>
          <li>
            <a href="#2.6.6">2.6.6 cbf_H5Arequire_cmp2</a>
          </li>
          <li>
            <a href="#2.6.7">2.6.7 cbf_H5Arequire_cmp2_ULP</a>
          </li>
          <li>
            <a href="#2.6.8">2.6.8 cbf_H5Arequire_string</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.6.10">
        <h4>2.6.10 cbf_H5Dcreate</h4>
	<p>Creates a new dataset in the given location.</p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Dcreate (const hid_t location, hid_t *const dataset, const char *const name, const int rank, const hsize_t *const dim, const hsize_t *const max, const hsize_t *const chunk, const hid_t type)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>The <code>dataset</code> parameter gives a location to store the dataset for use by the caller, for example to add an attribute to it. If non-zero the returned handle MUST be free'd by the caller with <code>cbf_H5Dfree</code>.</p>
        <p>The dimensions of the dataset to create are given in <code>dim</code>. The maximum extents of the dataset are given in <code>max</code>, which uses the values in <code>dim</code> as defaults if set to a null pointer. Each element of <code>max</code> must be at least as large as the corresponding element of <code>dim</code>. The dataset created will be a fixed-size dataset unless one of the elements of <code>max</code> is set to <code>H5S_UNLIMITED</code>.</p>
        <p>A chunk size must be given in the <code>chunk</code> argument if any element of <code>max</code> is set to <code>H5S_UNLIMITED</code> or is greater than the corresponding element of <code>dim</code>. If the dataset should not be chunked then a null pointer should be given.</p>
        <p>The <code>dim</code>, <code>max</code> and <code>chunk</code> arrays - if given - must each contain <code>rank</code> elements.</p>
	<p>This function will fail if a link with the same name already exists in <code>location</code>.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>The hdf5 group/file in which to put the dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">dataset</td>
            <td class="desc">
              <p>An optional pointer to a location where the dataset handle should be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">rank</td>
            <td class="desc">
              <p>The rank of the data. </p>
            </td>
          </tr>
          <tr>
            <td class="name">dim</td>
            <td class="desc">
              <p>The dimensions of the dataset to create. Unused if <code>rank == 0</code>. </p>
            </td>
          </tr>
          <tr>
            <td class="name">max</td>
            <td class="desc">
              <p>The maximum size of each dimension. Unused if <code>rank == 0</code>. </p>
            </td>
          </tr>
          <tr>
            <td class="name">chunk</td>
            <td class="desc">
              <p>The chunk size for the dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">type</td>
            <td class="desc">
              <p>The type of each data element in the file. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
          </li>
          <li>
            <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
          </li>
          <li>
            <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
          </li>
          <li>
            <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
          </li>
          <li>
            <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
          </li>
          <li>
            <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
          </li>
          <li>
            <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
          </li>
          <li>
            <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
          </li>
          <li>
            <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
          </li>
          <li>
            <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.11">
        <h4>2.6.11 cbf_H5Dfind2</h4>
	<p>Look for a dataset with the given properties.</p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Dfind2 (const hid_t location, hid_t *const dataset, const char *const name, const int rank, const hsize_t *const max, hsize_t *const buf, const hid_t type)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Returns <code>CBF_NOTFOUND</code> without modifying <code>dataset</code> if no dataset exists and fails without modifying <code>dataset</code> if one with different properties exists. A dataset will be 'found' if it has the same name and a maximum size which is at least as big as the size requested in <code>max</code>.</p>
        <p>A buffer of <code>rank</code> elements pointed to by <code>buf</code> may be used to store the array of maximum extents for a potentially matching dataset, in order to avoid the use of <code>malloc</code> &amp; <code>free</code> for very small amounts of memory.</p>
        <p>Use as:</p>
        <code>
          <pre>/* Get the return code from the function call, */
const int found = cbf_H5Dfind(location, &amp;dataset, ...);
/* and check what it was: */
if (CBF_SUCCESS==found) {
	/* A dataset already existed and I have a handle for it: */
    use_existing_dataset(dataset);
} else if (CBF_NOTFOUND==found) {
	/* No matching dataset existed, so I can create one: */
	cbf_H5Dcreate(location, &amp;dataset, ...);
    use_new_datset(dataset);
} else {
	/*
    The function call failed, do something with the error.
    In this case, store it for later use and print a message.
	*/
    error |= found;
     cbf_debug_print(cbf_strerror(error));
}
/* clean up: */
cbf_H5Dfree(dataset);</pre>
        </code>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>The hdf5 group/file in which to put the dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">dataset</td>
            <td class="desc">
              <p>A pointer to a HDF5 object identifier that is set to the location of a valid object if the function succeeds, otherwise is left in an undefined state. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the existing/new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">rank</td>
            <td class="desc">
              <p>The rank of the data, must be equal to the length of the <code>max</code> and <code>buf</code> arrays, if they are given. </p>
            </td>
          </tr>
          <tr>
            <td class="name">max</td>
            <td class="desc">
              <p>The (optional) maximum size of each dimension, pointer or an array of length <code>rank</code> where <code>0 &lt;= max[i] &lt;= H5S_UNLIMITED</code> for <code>i = [0, rank)</code>, unused if <code>rank == 0</code>. </p>
            </td>
          </tr>
          <tr>
            <td class="name">buf</td>
            <td class="desc">
              <p>An optional buffer with <code>rank</code> elements which may be used to store the current maximum dimensions of a potential match to avoid a malloc/free call. </p>
            </td>
          </tr>
          <tr>
            <td class="name">type</td>
            <td class="desc">
              <p>The type of each data element in the file. If an invalid type is given a dataset of any type may be returned. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>CBF_SUCCESS if a matching dataset was found, CBF_NOTFOUND if nothing with the same name was found, some other error code otherwise. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
          </li>
          <li>
            <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
          </li>
          <li>
            <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
          </li>
          <li>
            <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
          </li>
          <li>
            <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
          </li>
          <li>
            <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
          </li>
          <li>
            <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
          </li>
          <li>
            <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
          </li>
          <li>
            <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
          </li>
          <li>
            <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.12">
        <h4>2.6.12 cbf_H5Drequire</h4>
	<p>Ensure that a dataset exists, returning a handle to an existing dataset or creating a new dataset if needed.</p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Drequire (const hid_t location, hid_t *const dataset, const char *const name, const int rank, const hsize_t *const max, const hsize_t *const chunk, hsize_t *const buf, const hid_t type)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Ensure a dataset of the given <code>rank</code> exists and can hold at least as many elements as specified in <code>max</code>. If no dataset exists then one will be created with dimensions of [0, 0, ... 0]. <code>cbf_H5Dfind</code> and <code>cbf_H5Dcreate</code> are used in the implementation of this function.</p>
        <p>An existing dataset may be found using <code>cbf_H5Dfind2(location, dataset, name, rank, max, buf, type)</code>. If no dataset can be found then a dataset will be created by setting each element of a buffer of length <code>rank</code> to zero and using <code>cbf_H5Dcreate(location, dataset, name, rank, buffer, max, chunk, type)</code>. A buffer of <code>rank</code> elements may be provided to avoid using malloc to allocate memory for a small array whose size may already be known.</p>
        <p>The value pointed to by <code>dataset</code> should be a valid object identifier if the function exits successfully, and will be left in an undefined state otherwise.</p>
        <p>This is roughly equivalent to:</p>
        <code>
          <pre>const int error = cbf_H5Dfind2(location, dataset, name, rank, max, buf, type);
if (CBF_NOTFOUND==error) {
	int i;
	for (i = 0; i != rank; ++i) buf[i] = 0;
	return cbf_H5Dcreate(location, dataset, name, rank, buf, max, chunk, type);
} else {
	/* 'error' may be 'CBF_SUCCESS' or could indicate an error: */
	return error;
}</pre>
        </code>
        <p>but contains more sophisticated error handling code and allows for some parameters to be omitted.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>The hdf5 group/file in which to put the dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">dataset</td>
            <td class="desc">
              <p>A pointer to a location to store the dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the existing/new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">rank</td>
            <td class="desc">
              <p>The rank of the data. </p>
            </td>
          </tr>
          <tr>
            <td class="name">max</td>
            <td class="desc">
              <p>The (optional) maximum size of each dimension. </p>
            </td>
          </tr>
          <tr>
            <td class="name">chunk</td>
            <td class="desc">
              <p>The chunk size used if creating a new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">buf</td>
            <td class="desc">
              <p>An optional buffer with <code>rank</code> elements. </p>
            </td>
          </tr>
          <tr>
            <td class="name">type</td>
            <td class="desc">
              <p>The type of each data element in the file. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
          </li>
          <li>
            <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
          </li>
          <li>
            <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
          </li>
          <li>
            <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
          </li>
          <li>
            <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
          </li>
          <li>
            <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
          </li>
          <li>
            <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
          </li>
          <li>
            <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
          </li>
          <li>
            <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
          </li>
          <li>
            <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.13">
        <h4>2.6.13 cbf_H5Dinsert</h4>
	<p>Add some data to a datset, expanding the dataset to the appropriate size if needed.</p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Dinsert (const hid_t dataset, const hsize_t *const offset, const hsize_t *const stride, const hsize_t *const count, hsize_t *const buf, const void *const value, const hid_t type)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Insert a slice of data into <code>dataset</code> with the appropriate <code>offset</code> &amp; <code>stride</code>, ensuring that no existing data is lost due to resizing the dataset but not checking that previous data isn't being overwritten.</p>
        <p>The <code>offset</code>, <code>stride</code>, <code>count</code> and <code>buf</code> arrays must each have <code>rank</code> elements. If <code>stride</code> is set to the null pointer then a default of <code>[1, 1, 1, ..., 1]</code> will be used. An optional buffer may be provided in <code>buf</code> to avoid using malloc to allocate a small amount of memory whose size may actually be known at compile time.</p>
        <p>The <code>value</code> array should contain <code>count[0] * count[1] * ... * count[rank-1] === product(count)</code> elements of data.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">dataset</td>
            <td class="desc">
              <p>The dataset to write the data to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">offset</td>
            <td class="desc">
              <p>Where to start writing the data. </p>
            </td>
          </tr>
          <tr>
            <td class="name">stride</td>
            <td class="desc">
              <p>The number of elements in the dataset to step for each element to be written. </p>
            </td>
          </tr>
          <tr>
            <td class="name">count</td>
            <td class="desc">
              <p>The number of elements in each dimension to be written. </p>
            </td>
          </tr>
          <tr>
            <td class="name">buf</td>
            <td class="desc">
              <p>An optional buffer to avoid using the heap for small amounts of memory. </p>
            </td>
          </tr>
          <tr>
            <td class="name">value</td>
            <td class="desc">
              <p>The address of the data to be written. </p>
            </td>
          </tr>
          <tr>
            <td class="name">type</td>
            <td class="desc">
              <p>The type of data in memory. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
          </li>
          <li>
            <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
          </li>
          <li>
            <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
          </li>
          <li>
            <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
          </li>
          <li>
            <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
          </li>
          <li>
            <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
          </li>
          <li>
            <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
          </li>
          <li>
            <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
          </li>
          <li>
            <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
          </li>
          <li>
            <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.14">
        <h4>2.6.14 cbf_H5Dset_extent</h4>
        <p>Change the extent of a chunked dataset to the values in dim. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Dset_extent (const hid_t dataset, const hsize_t *const dim)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Forwards to a HDF5 function to change the extent of <code>dataset</code>. The <code>dim</code> array must have the same number of elements as the rank of the dataset, but this can't be checked within this function.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">dataset</td>
            <td class="desc">
              <p>A handle for the dataset whose extent is to be changed. </p>
            </td>
          </tr>
          <tr>
            <td class="name">dim</td>
            <td class="desc">
              <p>The new extent of the dataset, if the function succeeds. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
          </li>
          <li>
            <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
          </li>
          <li>
            <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
          </li>
          <li>
            <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
          </li>
          <li>
            <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
          </li>
          <li>
            <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
          </li>
          <li>
            <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
          </li>
          <li>
            <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
          </li>
          <li>
            <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
          </li>
          <li>
            <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.15">
        <h4>2.6.15 cbf_H5Dwrite2</h4>
	<p>Add some data to the specified position in the dataset, without checking what (if anything) was there before.</p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Dwrite2 (const hid_t dataset, const hsize_t *const offset, const hsize_t *const stride, const hsize_t *const count, const void *const value, const hid_t type)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Assumes the dataset has the appropriate size to contain all the data and overwrites any existing data that may be there. The <code>rank</code> of the dataset is assumed to be known, and the size of the array parameters is not tested. When <code>rank</code> is zero - in the case of scalar datasets - the <code>offset</code>, <code>stride</code> and <code>count</code> parameters are meaningless and should be omitted by setting them to zero.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">dataset</td>
            <td class="desc">
              <p>The dataset to write the data to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">offset</td>
            <td class="desc">
              <p>Where to start writing the data, as an array of <code>rank</code> numbers. </p>
            </td>
          </tr>
          <tr>
            <td class="name">stride</td>
            <td class="desc">
              <p>The number of elements in the dataset to step for each element to be written, where null is equivalent to a stride of [1, 1, 1, ..., 1], as an array of <code>rank</code> numbers. </p>
            </td>
          </tr>
          <tr>
            <td class="name">count</td>
            <td class="desc">
              <p>The number of elements in each dimension to be written, as an array of <code>rank</code> numbers. </p>
            </td>
          </tr>
          <tr>
            <td class="name">value</td>
            <td class="desc">
              <p>The address of the data to be written. </p>
            </td>
          </tr>
          <tr>
            <td class="name">type</td>
            <td class="desc">
              <p>The type of data in memory. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
          </li>
          <li>
            <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
          </li>
          <li>
            <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
          </li>
          <li>
            <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
          </li>
          <li>
            <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
          </li>
          <li>
            <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
          </li>
          <li>
            <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
          </li>
          <li>
            <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
          </li>
          <li>
            <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
          </li>
          <li>
            <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.16">
        <h4>2.6.16 cbf_H5Dread2</h4>
        <p>Extract some existing data from a dataset at a known position with memtype. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Dread2 (const hid_t dataset, const hsize_t *const offset, const hsize_t *const stride, const hsize_t *const count, void *const value, const hid_t type)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Read some data from a given location in the dataset to an existing location in memory. Does not check the length of the array parameters, which should all have <code>rank</code> elements or (in some cases) be <code>null</code>. When <code>rank</code> is zero - in the case of scalar datasets - the <code>offset</code>, <code>stride</code> and <code>count</code> parameters are meaningless and should be omitted by setting them to zero.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">dataset</td>
            <td class="desc">
              <p>The dataset to read the data from. </p>
            </td>
          </tr>
          <tr>
            <td class="name">offset</td>
            <td class="desc">
              <p>Where to start writing the data, as an array of <code>rank</code> numbers. </p>
            </td>
          </tr>
          <tr>
            <td class="name">stride</td>
            <td class="desc">
              <p>The number of elements in the dataset to step for each element to be written, where null is equivalent to a stride of [1, 1, 1, ..., 1], as an array of <code>rank</code> numbers. </p>
            </td>
          </tr>
          <tr>
            <td class="name">count</td>
            <td class="desc">
              <p>The number of elements in each dimension to be written, as an array of <code>rank</code> numbers. </p>
            </td>
          </tr>
          <tr>
            <td class="name">value</td>
            <td class="desc">
              <p>The location where the data is to be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">type</td>
            <td class="desc">
              <p>The type of data in memory. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
          </li>
          <li>
            <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
          </li>
          <li>
            <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
          </li>
          <li>
            <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
          </li>
          <li>
            <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
          </li>
          <li>
            <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
          </li>
          <li>
            <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
          </li>
          <li>
            <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
          </li>
          <li>
            <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
          </li>
          <li>
            <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.17">
        <h4>2.6.17 cbf_H5Drequire_scalar_F64LE2</h4>
        <p>Write a scalar 64-bit floating point number as a dataset with comparison. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Drequire_scalar_F64LE2 (const hid_t location, hid_t *const dataset, const char *const name, const double value, int(*cmp)(const void *, const void *, size_t))</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Convenience function using the HDF5 abstraction layer to avoid the need to consider array-related parameters for a scalar dataset.It ensures that a scalar 64-bit IEEE floating point dataset exists with the appropriate name and (for an existing dataset) the correct value as determined by the comparison function <code>cmp</code>.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>The group containing the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">dataset</td>
            <td class="desc">
              <p>An optional pointer to a place to store the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">value</td>
            <td class="desc">
              <p>The value of the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">cmp</td>
            <td class="desc">
              <p>A comparison function to test if a previously set value is equal to the value I asked for. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
          </li>
          <li>
            <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
          </li>
          <li>
            <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
          </li>
          <li>
            <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
          </li>
          <li>
            <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
          </li>
          <li>
            <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
          </li>
          <li>
            <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
          </li>
          <li>
            <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
          </li>
          <li>
            <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
          </li>
          <li>
            <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.18">
        <h4>2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</h4>
        <p>Write a scalar 64-bit floating point number as a dataset with a user-defined comparison. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Drequire_scalar_F64LE2_ULP (const hid_t location, hid_t *const dataset, const char *const name, const double value, int(*cmp)(const void *, const void *, size_t, const void *), const void *const cmp_params)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Convenience function using the HDF5 abstraction layer to avoid the need to consider array-related parameters for a scalar dataset. It ensures that a scalar 64-bit IEEE floating point dataset exists with the appropriate name and (for an existing dataset) the correct value as determined by the user-supplied comparison function <code>cmp</code>.</p>
        <p>It is implemented using some of the other dataset functions:</p>
        <ul>
          <li>cbf_H5Dfind2</li>
          <li>cbf_H5Dcreate</li>
          <li>cbf_H5Dread2</li>
          <li>cbf_H5Dwrite2</li>
        </ul>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>The group containing the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">dataset</td>
            <td class="desc">
              <p>An optional pointer to a place to store the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">value</td>
            <td class="desc">
              <p>The value of the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">cmp</td>
            <td class="desc">
              <p>A comparison function to test if a previously set value is equal to the value I asked for. </p>
            </td>
          </tr>
          <tr>
            <td class="name">cmp_params</td>
            <td class="desc">
              <p>Some extra data which may be required by the comparison function. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
          </li>
          <li>
            <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
          </li>
          <li>
            <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
          </li>
          <li>
            <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
          </li>
          <li>
            <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
          </li>
          <li>
            <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
          </li>
          <li>
            <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
          </li>
          <li>
            <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
          </li>
          <li>
            <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
          </li>
          <li>
            <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.19">
        <h4>2.6.19 cbf_H5Drequire_flstring</h4>
        <p>Write a single fixed-length string as a dataset. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Drequire_flstring (const hid_t location, hid_t *const dataset, const char *const name, const char *const value)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Convenience function using the HDF5 abstraction layer to avoid the need to consider array-related parameters for a scalar dataset and to automatically set the string type to the correct size.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>The group containing the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">dataset</td>
            <td class="desc">
              <p>An optional pointer to a place to store the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the new dataset. </p>
            </td>
          </tr>
          <tr>
            <td class="name">value</td>
            <td class="desc">
              <p>The value of the new dataset. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
          </li>
          <li>
            <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
          </li>
          <li>
            <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
          </li>
          <li>
            <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
          </li>
          <li>
            <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
          </li>
          <li>
            <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
          </li>
          <li>
            <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
          </li>
          <li>
            <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
          </li>
          <li>
            <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
          </li>
          <li>
            <a href="#2.6.20">2.6.20 cbf_H5Dfree</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.6.20">
        <h4>2.6.20 cbf_H5Dfree</h4>
	<p>Close a HDF5 dataset.</p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Dfree (const hid_t ID)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
	<p>Attempt to close a dataset, but don't modify the identifier that described it.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">ID</td>
            <td class="desc">
              <p>The HDF5 dataset to be closed. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.10">2.6.10 cbf_H5Dcreate</a>
          </li>
          <li>
            <a href="#2.6.11">2.6.11 cbf_H5Dfind2</a>
          </li>
          <li>
            <a href="#2.6.12">2.6.12 cbf_H5Drequire</a>
          </li>
          <li>
            <a href="#2.6.13">2.6.13 cbf_H5Dinsert</a>
          </li>
          <li>
            <a href="#2.6.14">2.6.14 cbf_H5Dset_extent</a>
          </li>
          <li>
            <a href="#2.6.15">2.6.15 cbf_H5Dwrite2</a>
          </li>
          <li>
            <a href="#2.6.16">2.6.16 cbf_H5Dread2</a>
          </li>
          <li>
            <a href="#2.6.17">2.6.17 cbf_H5Drequire_scalar_F64LE2</a>
          </li>
          <li>
            <a href="#2.6.18">2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP</a>
          </li>
          <li>
            <a href="#2.6.19">2.6.19 cbf_H5Drequire_flstring</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.21">
        <h4>2.6.21 cbf_H5Fopen</h4>
	<p>Attempt to open an HDF5 file by file name.</p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Fopen (hid_t *const file, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Will try to open a file of the given name with suitable values for some of it's properties to make memory leaks less likely.</p>
        <p><em>Warning:</em> this function will destroy any existing data in the file, do not pass the name of any file containing data you want to keep.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">file</td>
            <td class="desc">
              <p>A pointer to an HDF5 ID where the newly opened file should be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name of the file to attempt to open. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.22">2.6.22 cbf_H5Fclose</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.22">
        <h4>2.6.22 cbf_H5Fclose</h4>
	<p>Close a HDF5 file.</p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Fclose (const hid_t ID)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
	<p>Attempt to close a file, but don't modify the identifier that described it.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">ID</td>
            <td class="desc">
              <p>The HDF5 file to be closed. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.21">2.6.21 cbf_H5Fopen</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.23">
        <h4>2.6.23 cbf_H5Gcreate</h4>
        <p>Attempt to create a group. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Gcreate (const hid_t location, hid_t *const group, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Helper function to attempt to create a HDF5 group identified by <code>name</code> and return an error code, to make error handling more consistant. This will fail if a link with the same name already exists in <code>parent</code>.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>The group that will contain the newly created group. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>A pointer to a HDF5 ID type where the group will be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name that the group will be given. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.24">2.6.24 cbf_H5Gfind</a>
          </li>
          <li>
            <a href="#2.6.25">2.6.25 cbf_H5Grequire</a>
          </li>
          <li>
            <a href="#2.6.26">2.6.26 cbf_H5Gfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.24">
        <h4>2.6.24 cbf_H5Gfind</h4>
        <p>Check if a group exists. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Gfind (const hid_t location, hid_t *const group, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Checks for the existance of a group with the given <code>name</code> and <code>parent</code>. Will return <code>CBF_NOTFOUND</code> if it cannot be found, or open it if it already exists. An error code will be returned if something other than a group exists at the specified location.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>The group to be searched. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>A pointer to a HDF5 ID type where the group will be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The path (ie, name) of the group to be found. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.23">2.6.23 cbf_H5Gcreate</a>
          </li>
          <li>
            <a href="#2.6.25">2.6.25 cbf_H5Grequire</a>
          </li>
          <li>
            <a href="#2.6.26">2.6.26 cbf_H5Gfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.25">
        <h4>2.6.25 cbf_H5Grequire</h4>
        <p>Ensure a group exists. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Grequire (const hid_t location, hid_t *const group, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Checks for the existance of a group with the given <code>name</code> and <code>parent</code>. Will create the group if it cannot be found, or open it if it already exists. It is an error if a matching group cannot be found or created. This uses <code>cbf_H5Gcreate</code> to create any new groups.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">location</td>
            <td class="desc">
              <p>The group that will contain the newly created group. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>A pointer to a HDF5 ID type where the group will be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name that the group will be given. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.23">2.6.23 cbf_H5Gcreate</a>
          </li>
          <li>
            <a href="#2.6.24">2.6.24 cbf_H5Gfind</a>
          </li>
          <li>
            <a href="#2.6.26">2.6.26 cbf_H5Gfree</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.6.26">
        <h4>2.6.26 cbf_H5Gfree</h4>
	<p>Close a HDF5 group.</p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Gfree (const hid_t ID)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
	<p>Attempt to close a group, but don't modify the identifier that described it.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">ID</td>
            <td class="desc">
              <p>The HDF5 group to be closed. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.23">2.6.23 cbf_H5Gcreate</a>
          </li>
          <li>
            <a href="#2.6.24">2.6.24 cbf_H5Gfind</a>
          </li>
          <li>
            <a href="#2.6.25">2.6.25 cbf_H5Grequire</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.27">
        <h4>2.6.27 cbf_H5Ivalid</h4>
        <p>Check the validity of an object identifier. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Ivalid (const hid_t ID)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Function to check validity of a HDF5 identifier. HDF5's predefined types are never counted as valid by this function, so it can't be used to test the validity of a type constant. Types obtained by using H5Tcopy are safe to test.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">ID</td>
            <td class="desc">
              <p>An HDF5 object identifier. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>Non-zero if the type is valid, zero otherwise.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.28">2.6.28 cbf_H5Ocmp</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.28">
        <h4>2.6.28 cbf_H5Ocmp</h4>
        <p>A missing HDF5 function. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>htri_t cbf_H5Ocmp (const hid_t id0, const hid_t id1)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Compare two HDF5 object ID's for equality. This follows the standard practice of returning zero if objects should be considered equal, and the HDF5 practice of returning a negative number if there is an error.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">id0</td>
            <td class="desc">
              <p>An HDF5 identifier. </p>
            </td>
          </tr>
          <tr>
            <td class="name">id1</td>
            <td class="desc">
              <p>An HDF5 identifier. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>0 if equal, a positive value if not equal, or a negative value if there is an error. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.27">2.6.27 cbf_H5Ivalid</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.6.29">
        <h4>2.6.29 cbf_H5Ofree</h4>
        <p>Close a HDF5 object identifier. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Ofree (const hid_t ID)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Attempt to close an object identifier of unknown type, but don't modify the identifier that described it.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">ID</td>
            <td class="desc">
              <p>The HDF5 object to be closed. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.6.28">2.6.28 cbf_H5Ocmp</a>
          </li>
          <li>
            <a href="#2.6.27">2.6.27 cbf_H5Ivalid</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.6.30">
        <h4>2.6.30 cbf_H5Screate</h4>
        <p>Create a dataspace with some given values. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Screate (hid_t *const ID, const int rank, const hsize_t *const dim, const hsize_t *const max)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
	<p>Helper function which creates a HDF5 dataspace.</p>
        <p>Maximum dimensions can be set to infinity by passing <code>H5S_UNLIMITED</code> in the appropriate slot of the <code>max</code> parameter. If <code>rank</code> is zero then neither <code>dim</code> nor <code>max</code> are used and a scalar dataspace is created. If <code>rank</code> is non-zero and <code>dim</code> is a null pointer then <code>ID</code> will not be modified and the function will fail. If <code>rank</code> is non-zero and <code>max</code> is a null pointer the maximum length is set to the current length as given by <code>dim</code>.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">ID</td>
            <td class="desc">
              <p>A pointer to a HDF5 identifier that will contain the new dataspace. </p>
            </td>
          </tr>
          <tr>
            <td class="name">rank</td>
            <td class="desc">
              <p>The number of dimensions of the new dataspace. </p>
            </td>
          </tr>
          <tr>
            <td class="name">dim</td>
            <td class="desc">
              <p>The current size of each dimension of the dataspace, should be an array of length <code>rank</code> . </p>
            </td>
          </tr>
          <tr>
            <td class="name">max</td>
            <td class="desc">
              <p>The maximum size of each dimension, should be an array of length <code>rank</code> . </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.31">2.6.31 cbf_H5Sfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.31">
        <h4>2.6.31 cbf_H5Sfree</h4>
        <p>Close a HDF5 dataspace identifier. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Sfree (const hid_t ID)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Attempt to close a dataspace identifier, but don't modify the identifier that described it.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">ID</td>
            <td class="desc">
              <p>The HDF5 dataspace to be closed. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.30">2.6.30 cbf_H5Screate</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.32">
        <h4>2.6.32 cbf_H5Tcreate_string</h4>
        <p>Get a HDF5 string datatype to describe a sting of the specified length. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Tcreate_string (hid_t *const type, const size_t len)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Convenience function to create a string datatype suitable for use when storing a string of length <code>len</code>, returning it in the identifier pointed to by <code>type</code>.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">type</td>
            <td class="desc">
              <p>A pointer to a the HDF5 handle of the new datatype, which should be free'd with <code>cbf_H5Tfree</code></p>
            </td>
          </tr>
          <tr>
            <td class="name">len</td>
            <td class="desc">
              <p>The length of the string datatype - should be <code>strlen()</code> or <code>H5T_VARIABLE</code></p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.33">2.6.33 cbf_H5Tfree</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.6.33">
        <h4>2.6.33 cbf_H5Tfree</h4>
        <p>Close a HDF5 datatype identifier. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_H5Tfree (const hid_t ID)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Attempt to close a datatype identifier, but don't modify the identifier that described it.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">ID</td>
            <td class="desc">
              <p>The HDF5 datatype to be closed. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.6.32">2.6.32 cbf_H5Tcreate_string</a>
          </li>
	</ul>
      </div>
    </div>
	<hr />
    <div id="2.7">
      <h2>2.7 High-level NeXus-related functions</h2>
      <div>
        <p>These functions primarily allow interaction with a <code>cbf_h5handle</code> without being exposed to its structure or the complexities of using it correctly.
	Wherever possible these functions should be used instead of directly accessing a <code>cbf_h5handle</code> or <code>cbf_config_t</code> in order make code easier
	to read, to maintain the integrity of the data structures and to ensure all resources allocated to these object are correctly cleaned up.</p>
      </div>
      <p>This section describes functions available for working with:</p>
      <ul>
        <li>
          <strong>CBF's HDF5 handles:</strong>
			<ul>
            <li>
              <a href="#2.7.1">2.7.1 cbf_h5handle_get_file</a>
            </li>
            <li>
              <a href="#2.7.2">2.7.2 cbf_h5handle_set_file</a>
            </li>
            <li>
              <a href="#2.7.3">2.7.3 cbf_h5handle_get_entry</a>
            </li>
            <li>
              <a href="#2.7.4">2.7.4 cbf_h5handle_set_entry</a>
            </li>
            <li>
              <a href="#2.7.5">2.7.5 cbf_h5handle_require_entry</a>
            </li>
            <li>
              <a href="#2.7.6">2.7.6 cbf_h5handle_require_entry_definition</a>
            </li>
            <li>
              <a href="#2.7.7">2.7.7 cbf_h5handle_get_sample</a>
            </li>
            <li>
              <a href="#2.7.8">2.7.8 cbf_h5handle_set_sample</a>
            </li>
            <li>
              <a href="#2.7.9">2.7.9 cbf_h5handle_require_sample</a>
            </li>
            <li>
              <a href="#2.7.10">2.7.10 cbf_h5handle_get_beam</a>
            </li>
            <li>
              <a href="#2.7.11">2.7.11 cbf_h5handle_set_beam</a>
            </li>
            <li>
              <a href="#2.7.12">2.7.12 cbf_h5handle_require_beam</a>
            </li>
            <li>
              <a href="#2.7.13">2.7.13 cbf_h5handle_get_instrument</a>
            </li>
            <li>
              <a href="#2.7.14">2.7.14 cbf_h5handle_set_instrument</a>
            </li>
            <li>
              <a href="#2.7.15">2.7.15 cbf_h5handle_find_instrument</a>
            </li>
            <li>
              <a href="#2.7.16">2.7.16 cbf_h5handle_require_instrument</a>
            </li>
            <li>
              <a href="#2.7.17">2.7.17 cbf_h5handle_get_detector</a>
            </li>
            <li>
              <a href="#2.7.18">2.7.18 cbf_h5handle_set_detector</a>
            </li>
            <li>
              <a href="#2.7.19">2.7.19 cbf_h5handle_find_detector</a>
            </li>
            <li>
              <a href="#2.7.20">2.7.20 cbf_h5handle_require_detector</a>
            </li>
            <li>
              <a href="#2.7.21">2.7.21 cbf_h5handle_get_goniometer</a>
            </li>
            <li>
              <a href="#2.7.22">2.7.22 cbf_h5handle_set_goniometer</a>
            </li>
            <li>
              <a href="#2.7.23">2.7.23 cbf_h5handle_require_goniometer</a>
            </li>
            <li>
              <a href="#2.7.24">2.7.24 cbf_h5handle_get_monochromator</a>
            </li>
            <li>
              <a href="#2.7.25">2.7.25 cbf_h5handle_set_monochromator</a>
            </li>
            <li>
              <a href="#2.7.26">2.7.26 cbf_h5handle_require_monochromator</a>
            </li>
            <li>
              <a href="#2.7.27">2.7.27 cbf_h5handle_get_source</a>
            </li>
            <li>
              <a href="#2.7.28">2.7.28 cbf_h5handle_set_source</a>
            </li>
            <li>
              <a href="#2.7.29">2.7.29 cbf_h5handle_require_source</a>
            </li>
            <li>
              <a href="#2.7.30">2.7.30 cbf_free_h5handle</a>
            </li>
            <li>
              <a href="#2.7.31">2.7.31 cbf_create_h5handle3</a>
            </li>
            <li>
              <a href="#2.7.32">2.7.32 cbf_write_cbf_h5file</a>
            </li>
            <li>
              <a href="#2.7.33">2.7.33 cbf_write_cbf2nx</a>
            </li>
            <li>
              <a href="#2.7.34">2.7.34 cbf_write_minicbf_h5file</a>
            </li>
            <li>
              <a href="#2.7.35">2.7.35 cbf_write_nx2cbf</a>
            </li>
			</ul>
		</li>
        <li>
          <strong>miniCBF configuration settings:</strong>
			<ul>
            <li>
              <a href="#2.7.36">2.7.36 cbf_config_create</a>
            </li>
            <li>
              <a href="#2.7.37">2.7.37 cbf_config_parse</a>
            </li>
            <li>
              <a href="#2.7.38">2.7.38 cbf_config_free</a>
            </li>
            <li>
              <a href="#2.7.39">2.7.39 cbf_config_strerror</a>
            </li>
			</ul>
		</li>
	</ul>
      <div>
	<h4>Reading miniCBF configuration settings</h4>
        <p>This example demonstrates how a miniCBF configuration file should be parsed, what should be checked before the extracted settings are used and what should
	be cleaned up by the caller afterwards:</p>
        <code>
          <pre>/* Declare some important variables */
int configError = cbf_configError_success;
FILE * configFile = fopen("config.txt","r");
cbf_config_t * const configSettings = cbf_config_create();

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

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

/* Clean up the settings to avoid memory leaks */
cbf_config_free(configSettings);</pre>
        </code>
      </div>
	<hr />
      <div class="function" id="2.7.1">
        <h4>2.7.1 cbf_h5handle_get_file</h4>
        <p>Get the current id of the file within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_get_file (const cbf_h5handle nx, hid_t *const file)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Check the handle for the presence of a file, optionally returning it. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>A handle to query for the presence of the requested information. </p>
            </td>
          </tr>
          <tr>
            <td class="name">file</td>
            <td class="desc">
              <p>A place to store the file (if found), or null if the file isn't wanted. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.2">2.7.2 cbf_h5handle_set_file</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.2">
        <h4>2.7.2 cbf_h5handle_set_file</h4>
        <p>Set the id of the file within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_set_file (const cbf_h5handle nx, const hid_t file)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Sets the file id within the handle to the given value. Doesn't check or modify any attributes in any way. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The handle to add information to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">file</td>
            <td class="desc">
              <p>The file to be set as the current file id. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.1">2.7.1 cbf_h5handle_get_file</a>
          </li>
	</ul>
      </div>
      <hr/>
      <div class="function" id="2.7.3">
        <h4>2.7.3 cbf_h5handle_get_entry</h4>
        <p>Get the current id and name of the entry group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_get_entry (const cbf_h5handle nx, hid_t *const group, const char **const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Check the handle for the presence of an entry group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.</p>
        <p>The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>A handle to query for the presence of the requested information. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>A place to store the group (if found), or null if the group isn't wanted. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>A place to store the name of the group (if found), or null if the name isn't wanted. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.4">2.7.4 cbf_h5handle_set_entry</a>
          </li>
          <li>
            <a href="#2.7.5">2.7.5 cbf_h5handle_require_entry</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.4">
        <h4>2.7.4 cbf_h5handle_set_entry</h4>
        <p>Set the id and name of the entry group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_set_entry (const cbf_h5handle nx, const hid_t group, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Sets the entry group and name within the handle to the given values. Doesn't check or modify the <code>NX_class</code> attribute in any way. The handle will take ownership of the group id iff this function succeeds. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The handle to add information to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>The group to be set as the current entry group </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name which the group should be given. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.3">2.7.3 cbf_h5handle_get_entry</a>
          </li>
          <li>
            <a href="#2.7.5">2.7.5 cbf_h5handle_require_entry</a>
          </li>
	</ul>
      </div>
      <hr/>
      <div class="function" id="2.7.5">
        <h4>2.7.5 cbf_h5handle_require_entry</h4>
        <p>Ensure I have an entry in the hdf5 handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_require_entry (const cbf_h5handle nx, hid_t *const group, const char *name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>This will check if the entry group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The <code>NX_class</code> attributes are not checked.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The HDF5 handle to use. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>An optional pointer to a place where the group should be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The group name, or null to use the default name of <code>"entry"</code>. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.3">2.7.3 cbf_h5handle_get_entry</a>
          </li>
          <li>
            <a href="#2.7.4">2.7.4 cbf_h5handle_set_entry</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.6">
        <h4>2.7.6 cbf_h5handle_require_entry_definition</h4>
        <p>Ensure I have an entry in the hdf5 handle with definition. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_require_entry_definition (const cbf_h5handle nx, hid_t *const group, const char *name, const char *definition, const char *version, const char *URL)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>This will check if the entry group and definition within the handle matches any existing group of the same name within the current file and has a definition designation that agrees. If the group name doesn't match a new group is opened or created and added to the handle. If the <code>definition</code> does not match, it is replaced with the new one. If the <code>version</code> attribute does not match it is replaced with the new one. If the <code>URL&gt;</code> attribute does not match it is replace with the new one. The <code>NX_class</code> attributes are not checked, but if a new entry is created it will be created with <code>NX_class</code> NXentry.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The HDF5 handle to use. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>An optional pointer to a place where the group ID should be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The group name, or null to use the default name of <code>"entry"</code>. </p>
            </td>
          </tr>
          <tr>
            <td class="name">definition</td>
            <td class="desc">
              <p>The definition name, or null to not specify a definition name. </p>
            </td>
          </tr>
          <tr>
            <td class="name">version</td>
            <td class="desc">
              <p>The version string, or null to not specify a version string. </p>
            </td>
          </tr>
          <tr>
            <td class="name">URL</td>
            <td class="desc">
              <p>The URL at which the definition is stored, or null to not specify a URL </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.3">2.7.3 cbf_h5handle_get_entry</a>
          </li>
          <li>
            <a href="#2.7.4">2.7.4 cbf_h5handle_set_entry</a>
          </li>
          <li>
            <a href="#2.7.5">2.7.5 cbf_h5handle_require_entry</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.7">
        <h4>2.7.7 cbf_h5handle_get_sample</h4>
        <p>Get the current id and name of the sample group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_get_sample (const cbf_h5handle nx, hid_t *const group, const char **const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Check the handle for the presence of an sample group and its name, optionally returning any combination of them. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>A handle to query for the presence of the requested information. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>A place to store the group (if found), or null if the group isn't wanted. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>A place to store the name of the group (if found), or null if the name isn't wanted. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.8">2.7.8 cbf_h5handle_set_sample</a>
          </li>
          <li>
            <a href="#2.7.9">2.7.9 cbf_h5handle_require_sample</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.8">
        <h4>2.7.8 cbf_h5handle_set_sample</h4>
        <p>Set the id and name of the sample group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_set_sample (const cbf_h5handle nx, const hid_t group, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Sets the sample group and name within the handle to the given values. Doesn't check or modify the <code>NX_class</code> attribute in any way. The handle will take ownership of the group id iff this function succeeds. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The handle to add information to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>The group to be set as the current sample group </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name which the group should be given. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.7">2.7.7 cbf_h5handle_get_sample</a>
          </li>
          <li>
            <a href="#2.7.9">2.7.9 cbf_h5handle_require_sample</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.9">
        <h4>2.7.9 cbf_h5handle_require_sample</h4>
        <p>Ensure I have a sample in the hdf5 handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_require_sample (const cbf_h5handle nx, hid_t *const group, const char *name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>This will check if the sample group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The <code>NX_class</code> attributes are not checked.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The HDF5 handle to use. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>An optional pointer to a place where the group should be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The group name, or null to use the default name of <code>"sample"</code>. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.7">2.7.7 cbf_h5handle_get_sample</a>
          </li>
          <li>
            <a href="#2.7.8">2.7.8 cbf_h5handle_set_sample</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.10">
        <h4>2.7.10 cbf_h5handle_get_beam</h4>
        <p>Get the current id and name of the beam group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_get_beam (const cbf_h5handle nx, hid_t *const group, const char **const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Check the handle for the presence of a beam group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.</p>
        <p>The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>A handle to query for the presence of the requested information. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>A place to store the group (if found), or null if the group isn't wanted. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>A place to store the name of the group (if found), or null if the name isn't wanted. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.11">2.7.11 cbf_h5handle_set_beam</a>
          </li>
          <li>
            <a href="#2.7.12">2.7.12 cbf_h5handle_require_beam</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.11">
        <h4>2.7.11 cbf_h5handle_set_beam</h4>
        <p>Set the id and name of the beam group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_set_beam (const cbf_h5handle nx, const hid_t group, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Sets the beam group and name within the handle to the given values. Doesn't check or modify the <code>NX_class</code> attribute in any way. The handle will take ownership of the group id iff this function succeeds. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The handle to add information to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>The group to be set as the current beam group </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name which the group should be given. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.10">2.7.10 cbf_h5handle_get_beam</a>
          </li>
          <li>
            <a href="#2.7.12">2.7.12 cbf_h5handle_require_beam</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.12">
        <h4>2.7.12 cbf_h5handle_require_beam</h4>
        <p>Ensure I have a beam in the hdf5 handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_require_beam (const cbf_h5handle nx, hid_t *const group, const char *name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>This will check if the beam group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The <code>NX_class</code> attributes are not checked.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The HDF5 handle to use. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>An optional pointer to a place where the group should be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The group name, or null to use the default name of <code>"beam"</code>. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.10">2.7.10 cbf_h5handle_get_beam</a>
          </li>
          <li>
            <a href="#2.7.11">2.7.11 cbf_h5handle_set_beam</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.13">
        <h4>2.7.13 cbf_h5handle_get_instrument</h4>
        <p>Get the current id and name of the instrument group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_get_instrument (const cbf_h5handle nx, hid_t *const group, const char **const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Check the handle for the presence of an instrument group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.</p>
        <p>The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>A handle to query for the presence of the requested information. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>A place to store the group (if found), or null if the group isn't wanted. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>A place to store the name of the group (if found), or null if the name isn't wanted. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
	<p>An error code.</p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.14">2.7.14 cbf_h5handle_set_instrument</a>
          </li>
          <li>
            <a href="#2.7.15">2.7.15 cbf_h5handle_find_instrument</a>
          </li>
          <li>
            <a href="#2.7.16">2.7.16 cbf_h5handle_require_instrument</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.14">
        <h4>2.7.14 cbf_h5handle_set_instrument</h4>
        <p>Set the id and name of the instrument group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_set_instrument (const cbf_h5handle nx, const hid_t group, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Sets the instrument group and name within the handle to the given values. Doesn't check or modify the <code>NX_class</code> attribute in any way. The handle will take ownership of the group id iff this function succeeds. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The handle to add information to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>The group to be set as the current instrument group </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name which the group should be given. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.13">2.7.13 cbf_h5handle_get_instrument</a>
          </li>
          <li>
            <a href="#2.7.15">2.7.15 cbf_h5handle_find_instrument</a>
          </li>
          <li>
            <a href="#2.7.16">2.7.16 cbf_h5handle_require_instrument</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.15">
        <h4>2.7.15 cbf_h5handle_find_instrument</h4>
        <p>Find an existing instrument group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_find_instrument (const cbf_h5handle nx, hid_t *const group, const char **const name)</code>
        </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc"/>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc"/>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc"/>
          </tr>
        </table>
      </div>
      <hr/>
      <div class="function" id="2.7.16">
        <h4>2.7.16 cbf_h5handle_require_instrument</h4>
        <p>Ensure I have an instrument in the hdf5 handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_require_instrument (const cbf_h5handle nx, hid_t *const group, const char *name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>This will check if the instrument group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The <code>NX_class</code> attributes are not checked.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The HDF5 handle to use. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>An optional pointer to a place where the group should be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The group name, or null to use the default name of <code>"instrument"</code>. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.13">2.7.13 cbf_h5handle_get_instrument</a>
          </li>
          <li>
            <a href="#2.7.14">2.7.14 cbf_h5handle_set_instrument</a>
          </li>
          <li>
            <a href="#2.7.15">2.7.15 cbf_h5handle_find_instrument</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.17">
        <h4>2.7.17 cbf_h5handle_get_detector</h4>
        <p>Get the current id and name of the detector group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_get_detector (const cbf_h5handle nx, hid_t *const group, const char **const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Check the handle for the presence of an detector group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.</p>
        <p>The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>A handle to query for the presence of the requested information. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>A place to store the group (if found), or null if the group isn't wanted. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>A place to store the name of the group (if found), or null if the name isn't wanted. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.18">2.7.18 cbf_h5handle_set_detector</a>
          </li>
          <li>
            <a href="#2.7.19">2.7.19 cbf_h5handle_find_detector</a>
          </li>
          <li>
            <a href="#2.7.20">2.7.20 cbf_h5handle_require_detector</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.18">
        <h4>2.7.18 cbf_h5handle_set_detector</h4>
        <p>Set the id and name of the detector group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_set_detector (const cbf_h5handle nx, const hid_t group, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Sets the detector group and name within the handle to the given values. Doesn't check or modify the <code>NX_class</code> attribute in any way. The handle will take ownership of the group id iff this function succeeds. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The handle to add information to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>The group to be set as the current detector group </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name which the group should be given. </p>
            </td>
          </tr>
	</table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
	<ul class="see-also">
          <li>
            <a href="#2.7.17">2.7.17 cbf_h5handle_get_detector</a>
          </li>
          <li>
            <a href="#2.7.19">2.7.19 cbf_h5handle_find_detector</a>
          </li>
          <li>
            <a href="#2.7.20">2.7.20 cbf_h5handle_require_detector</a>
          </li>
	</ul>
      </div>
	<hr />
      <div class="function" id="2.7.19">
        <h4>2.7.19 cbf_h5handle_find_detector</h4>
        <p>Find an existing detector group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_find_detector (const cbf_h5handle nx, hid_t *const group, const char **const name)</code>
        </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc"/>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc"/>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc"/>
          </tr>
        </table>
      </div>
      <hr/>
      <div class="function" id="2.7.20">
        <h4>2.7.20 cbf_h5handle_require_detector</h4>
        <p>Ensure I have a detector in the hdf5 handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_require_detector (const cbf_h5handle nx, hid_t *const group, const char *name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>This will check if the detector group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The <code>NX_class</code> attributes are not checked.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The HDF5 handle to use. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>An optional pointer to a place where the group should be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The group name, or null to use the default name of <code>"detector"</code>. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.17">2.7.17 cbf_h5handle_get_detector</a>
          </li>
          <li>
            <a href="#2.7.18">2.7.18 cbf_h5handle_set_detector</a>
          </li>
          <li>
            <a href="#2.7.19">2.7.19 cbf_h5handle_find_detector</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.21">
        <h4>2.7.21 cbf_h5handle_get_goniometer</h4>
        <p>Get the current id and name of the goniometer group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_get_goniometer (const cbf_h5handle nx, hid_t *const group, const char **const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Check the handle for the presence of an goniometer group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.</p>
        <p>The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>A handle to query for the presence of the requested information. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>A place to store the group (if found), or null if the group isn't wanted. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>A place to store the name of the group (if found), or null if the name isn't wanted. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.22">2.7.22 cbf_h5handle_set_goniometer</a>
          </li>
          <li>
            <a href="#2.7.23">2.7.23 cbf_h5handle_require_goniometer</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.22">
        <h4>2.7.22 cbf_h5handle_set_goniometer</h4>
        <p>Set the id and name of the goniometer group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_set_goniometer (const cbf_h5handle nx, const hid_t group, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Sets the goniometer group and name within the handle to the given values. Doesn't check or modify the <code>NX_class</code> attribute in any way. The handle will take ownership of the group id iff this function succeeds. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The handle to add information to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>The group to be set as the current goniometer group </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name which the group should be given. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.21">2.7.21 cbf_h5handle_get_goniometer</a>
          </li>
          <li>
            <a href="#2.7.23">2.7.23 cbf_h5handle_require_goniometer</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.23">
        <h4>2.7.23 cbf_h5handle_require_goniometer</h4>
        <p>Ensure I have a goniometer in the hdf5 handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_require_goniometer (const cbf_h5handle nx, hid_t *const group, const char *name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>This will check if the goniometer group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The <code>NX_class</code> attributes are not checked.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The HDF5 handle to use. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>An optional pointer to a place where the group should be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The group name, or null to use the default name of <code>"goniometer"</code>. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.21">2.7.21 cbf_h5handle_get_goniometer</a>
          </li>
          <li>
            <a href="#2.7.22">2.7.22 cbf_h5handle_set_goniometer</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.24">
        <h4>2.7.24 cbf_h5handle_get_monochromator</h4>
        <p>Get the current id and name of the monochromator group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_get_monochromator (const cbf_h5handle nx, hid_t *const group, const char **const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Check the handle for the presence of an monochromator group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.</p>
        <p>The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>A handle to query for the presence of the requested information. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>A place to store the group (if found), or null if the group isn't wanted. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>A place to store the name of the group (if found), or null if the name isn't wanted. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.25">2.7.25 cbf_h5handle_set_monochromator</a>
          </li>
          <li>
            <a href="#2.7.26">2.7.26 cbf_h5handle_require_monochromator</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.25">
        <h4>2.7.25 cbf_h5handle_set_monochromator</h4>
        <p>Set the id and name of the monochromator group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_set_monochromator (const cbf_h5handle nx, const hid_t group, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Sets the monochromator group and name within the handle to the given values. Doesn't check or modify the <code>NX_class</code> attribute in any way. The handle will take ownership of the group id iff this function succeeds. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The handle to add information to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>The group to be set as the current monochromator group </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name which the group should be given. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.24">2.7.24 cbf_h5handle_get_monochromator</a>
          </li>
          <li>
            <a href="#2.7.26">2.7.26 cbf_h5handle_require_monochromator</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.26">
        <h4>2.7.26 cbf_h5handle_require_monochromator</h4>
        <p>Ensure I have a monochromator in the hdf5 handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_require_monochromator (const cbf_h5handle nx, hid_t *const group, const char *name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>This will check if the monochromator group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The <code>NX_class</code> attributes are not checked.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The HDF5 handle to use. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>An optional pointer to a place where the group should be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The group name, or null to use the default name of <code>"monochromator"</code>. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.24">2.7.24 cbf_h5handle_get_monochromator</a>
          </li>
          <li>
            <a href="#2.7.25">2.7.25 cbf_h5handle_set_monochromator</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.27">
        <h4>2.7.27 cbf_h5handle_get_source</h4>
        <p>Get the current id and name of the source group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_get_source (const cbf_h5handle nx, hid_t *const group, const char **const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Check the handle for the presence of an source group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.</p>
        <p>The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>A handle to query for the presence of the requested information. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>A place to store the group (if found), or null if the group isn't wanted. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>A place to store the name of the group (if found), or null if the name isn't wanted. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.28">2.7.28 cbf_h5handle_set_source</a>
          </li>
          <li>
            <a href="#2.7.29">2.7.29 cbf_h5handle_require_source</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.28">
        <h4>2.7.28 cbf_h5handle_set_source</h4>
        <p>Set the id and name of the source group within the given handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_set_source (const cbf_h5handle nx, const hid_t group, const char *const name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Sets the source group and name within the handle to the given values. Doesn't check or modify the <code>NX_class</code> attribute in any way. The handle will take ownership of the group id iff this function succeeds. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The handle to add information to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>The group to be set as the current source group </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The name which the group should be given. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.27">2.7.27 cbf_h5handle_get_source</a>
          </li>
          <li>
            <a href="#2.7.29">2.7.29 cbf_h5handle_require_source</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.29">
        <h4>2.7.29 cbf_h5handle_require_source</h4>
        <p>Ensure I have a source in the hdf5 handle. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_h5handle_require_source (const cbf_h5handle nx, hid_t *const group, const char *name)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>This will check if the source group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The <code>NX_class</code> attributes are not checked.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The HDF5 handle to use. </p>
            </td>
          </tr>
          <tr>
            <td class="name">group</td>
            <td class="desc">
              <p>An optional pointer to a place where the group should be stored. </p>
            </td>
          </tr>
          <tr>
            <td class="name">name</td>
            <td class="desc">
              <p>The group name, or null to use the default name of <code>"source"</code>. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.27">2.7.27 cbf_h5handle_get_source</a>
          </li>
          <li>
            <a href="#2.7.28">2.7.28 cbf_h5handle_set_source</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.30">
        <h4>2.7.30 cbf_free_h5handle</h4>
        <p>Free a handle for an HDF5 file. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_free_h5handle (cbf_h5handle h5handle)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Checks if the handle appears to be valid, the free's the handle and any data that the handle owns. </p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">h5handle</td>
            <td class="desc">
              <p>The handle to be free'd. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.31">2.7.31 cbf_create_h5handle3</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.31">
        <h4>2.7.31 cbf_create_h5handle3</h4>
        <p>Allocates space for a HDF5 file handle and associates it with the given file. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_create_h5handle3 (cbf_h5handle *handle, hid_t file)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>This function expects the user to create or open a hdf5 file with the appropriate parameters for what they are trying to do, replacing older functions which would create a file with the <code>H5F_ACC_TRUNC</code> flag and <code>H5F_CLOSE_STRONG</code> property.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">handle</td>
            <td class="desc">
              <p>A pointer to a handle which is to be allocated. </p>
            </td>
          </tr>
          <tr>
            <td class="name">file</td>
            <td class="desc">
              <p>A HDF5 file to store within the newly created handle. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.30">2.7.30 cbf_free_h5handle</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.32">
        <h4>2.7.32 cbf_write_cbf_h5file</h4>
        <p>Extract the data from a CBF file &amp; put it into a NeXus file. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_write_cbf_h5file (cbf_handle handle, cbf_h5handle h5handle)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Equivalent to <code>cbf_write_cbf2nx(handle,h5handle,0,0,0)</code>.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">handle</td>
            <td class="desc">
              <p>The CBF file to extract data from. </p>
            </td>
          </tr>
          <tr>
            <td class="name">h5handle</td>
            <td class="desc">
              <p>The NeXuS file to write data to. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.34">2.7.34 cbf_write_minicbf_h5file</a>
          </li>
          <li>
            <a href="#2.7.33">2.7.33 cbf_write_cbf2nx</a>
          </li>
          <li>
            <a href="#2.7.35">2.7.35 cbf_write_nx2cbf</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.33">
        <h4>2.7.33 cbf_write_cbf2nx</h4>
        <p>Extract the data from a CBF file &amp; put it into a NeXus file. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_write_cbf2nx (cbf_handle handle, cbf_h5handle h5handle, const char *const datablock, const char *const scan, const int list)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Extracts data from <code>handle</code> and generates a NeXus file in <code>h5handle</code>. This will attempt to extract metadata and image data from each scan (or the named scan) within each datablock (or the the named datablock) and insert it into a given index into the NXentry group specified in <code>h5handle</code>.</p>
        <p>Each scan in the CBF file corresponds to one NXentry in NeXus, so a CBF datablock with multiple scans must be converted by calling this function with the appropriate value of <code>scan</code> once for each scan in the datablock.</p>
        <p>The flags (within <code>h5handle</code>) determine:</p>
        <ul>
          <li>Compression algorithm: zlib/CBF/none</li>
          <li>Plugin registration method: automatic/manual</li>
        </ul>
        <p>The strings given by <code>h5handle-&gt;scan_id</code> and <code>h5handle-&gt;sample_id</code> define:</p>
        <ul>
          <li>The presence and value of an identifier for the scan, stored in <code>/*:NXentry/entry_identifier</code>.</li>
          <li>The presence and value of an identifier for the sample, stored in <code>/*:NXentry/*:NXsample/sample_identifier</code>.</li>
        </ul>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">handle</td>
            <td class="desc">
              <p>The CBF file to extract data from. </p>
            </td>
          </tr>
          <tr>
            <td class="name">h5handle</td>
            <td class="desc">
              <p>The NeXuS file to write data to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">datablock</td>
            <td class="desc">
              <p>The name of the datablock to convert, or NULL to convert all datablocks. </p>
            </td>
          </tr>
          <tr>
            <td class="name">scan</td>
            <td class="desc">
              <p>The name of the scan to convert, or NULL if there is only one scan in the datablock. </p>
            </td>
          </tr>
          <tr>
            <td class="name">list</td>
            <td class="desc">
              <p>Boolean flag to determine if a list of processed items is printed. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.32">2.7.32 cbf_write_cbf_h5file</a>
          </li>
          <li>
            <a href="#2.7.34">2.7.34 cbf_write_minicbf_h5file</a>
          </li>
          <li>
            <a href="#2.7.35">2.7.35 cbf_write_nx2cbf</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.34">
        <h4>2.7.34 cbf_write_minicbf_h5file</h4>
        <p>Extract the data from a miniCBF file &amp; put it into a NeXus file. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_write_minicbf_h5file (cbf_handle handle, cbf_h5handle h5handle, const cbf_config_t *const axisConfig)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Extracts the miniCBF data directly - by parsing the header - and uses that plus the configuration options from <code>axisConfig</code> to generate a NeXus file in <code>h5handle</code>. This can extract metadata and image data from miniCBF files containing multiple datablocks which each contain a single image and insert it into a given index into the NXentry group specified in <code>h5handle</code>.</p>
        <p>Currently, only <code>Pilatus 1.2</code> format headers are supported.</p>
        <p>The flags determine:</p>
        <ul>
          <li>Compression algorithm: zlib/CBF/none</li>
          <li>Plugin registration method: automatic/manual</li>
        </ul>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">handle</td>
            <td class="desc">
              <p>The miniCBF file to extract data from. </p>
            </td>
          </tr>
          <tr>
            <td class="name">h5handle</td>
            <td class="desc">
              <p>The NeXus file to write data to. </p>
            </td>
          </tr>
          <tr>
            <td class="name">axisConfig</td>
            <td class="desc">
              <p>The configuration settings desribing the axes and their relation to the sample and to each other. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.32">2.7.32 cbf_write_cbf_h5file</a>
          </li>
          <li>
            <a href="#2.7.35">2.7.35 cbf_write_nx2cbf</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.35">
        <h4>2.7.35 cbf_write_nx2cbf</h4>
        <p>Extract data from a nexus file and store it in a CBF file. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_write_nx2cbf (cbf_h5handle nx, cbf_handle cbf)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Reads NeXus-format data from the entry group defined in the <code>nx</code> handle, extracting data related to the frame with index <code>nx-&gt;slice</code> and in CBF-format within the the <code>cbf</code> handle.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">nx</td>
            <td class="desc">
              <p>The handle defining the NeXus data to be converted. </p>
            </td>
          </tr>
          <tr>
            <td class="name">cbf</td>
            <td class="desc">
              <p>The handle in which to store the resulting CBF data. </p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>An error code. </p>
        <p>
          <strong>SEE ALSO</strong>
        </p>
        <ul class="see-also">
          <li>
            <a href="#2.7.32">2.7.32 cbf_write_cbf_h5file</a>
          </li>
          <li>
            <a href="#2.7.34">2.7.34 cbf_write_minicbf_h5file</a>
          </li>
        </ul>
      </div>
      <hr/>
      <div class="function" id="2.7.36">
        <h4>2.7.36 cbf_config_create</h4>
        <p>Obtain a new handle for some configuration settings. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>cbf_config_t* cbf_config_create ()</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Allocates a new collection of configuration settings on the heap, and initialises it. The returned pointer should be destroyed by the caller.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <p>This function takes no arguments.</p>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>A newly allocated object for miniCBF configuration settings, or NULL. </p>
      </div>
      <hr/>
      <div class="function" id="2.7.37">
        <h4>2.7.37 cbf_config_parse</h4>
        <p>Read a minicbf configuration file into the given handle, writing errors to logfile. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>int cbf_config_parse (FILE *const configFile, FILE *const logFile, cbf_config_t *const vec)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Parses a configuration file to extract a collection of configuration settings for a miniCBF file, storing them in the given configuration settings object. The pointer should have been obtained by a call to <code>cbf_config_create</code>. The configuration file format is described in the <code>minicbf2nexus</code> documentation.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">configFile</td>
            <td class="desc">
              <p>The file from which the config settings should be read. </p>
            </td>
          </tr>
          <tr>
            <td class="name">logFile</td>
            <td class="desc">
              <p>A stream to be used for logging error messages. </p>
            </td>
          </tr>
          <tr>
            <td class="name">vec</td>
            <td class="desc">
              <p>An object describing the configuration settings.</p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>A parser error code. </p>
      </div>
      <hr/>
      <div class="function" id="2.7.38">
        <h4>2.7.38 cbf_config_free</h4>
        <p>Free any heap memory associated with the given cbf_hdf5_configItemVectorhandle object. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>void cbf_config_free (const cbf_config_t *const vector)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>Destroys an existing collection of configuration settings. The settings should have been obtained by a call to <code>cbf_config_create</code>.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">vector</td>
            <td class="desc">
              <p>The configuration data to be free'd.</p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>Nothing. </p>
      </div>
      <hr/>
      <div class="function" id="2.7.39">
        <h4>2.7.39 cbf_config_strerror</h4>
        <p>Convert a parse error to a descriptive string. </p>
        <p>
          <strong>PROTOTYPE</strong>
        </p>
        <p>
          <code>#include "cbf_hdf5.h"</code>
          <br/>
          <code>const char* cbf_config_strerror (const int error)</code>
        </p>
        <p>
          <strong>DESCRIPTION</strong>
        </p>
        <p>The returned string is "none" for success, "unknown error" if the given error code is not recognised and a non-empty string briefly describing the error otherwise.</p>
        <p>The returned string must not be free'd.</p>
        <p>
          <strong>ARGUMENTS</strong>
        </p>
        <table class="params">
          <tr>
            <td class="name">error</td>
            <td class="desc">
              <p>An error returned by a <code>cbf_config_*</code> function.</p>
            </td>
          </tr>
        </table>
        <p>
          <strong>RETURN VALUE</strong>
        </p>
        <p>A string describing the error. </p>
      </div>
    </div>
      <hr/>


<h3><A NAME="3.">3.  File format</A></h3>


<h4><A NAME="3.1">3.1  General description</A></h4>
<p>
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.
<p>
<h4><A NAME="3.2">3.2  Format of the binary sections</A></h4>
<p>
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".
<p>
The specific format of the binary sections differs between an
imgCIF and a CBF file.
<h4><A NAME="3.2.1">3.2.1  Format of imgCIF binary sections</A></h4>
<p>

Each binary section is encoded as a semicolon-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
<p>
<PRE>
--CIF-BINARY-FORMAT-SECTION--
</PRE>
<p>
at the beginning of a line.  The initial &quot;--&quot; 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: &quot;Content-Transfer-Encoding&quot;.
If the value given on this
header is &quot;BINARY&quot;, this is a CBF and the
data will be presented as raw binary, containing a
count (in the header described in <A HREF="#3.2.2">
3.2.2  Format of CBF binary sections</A>)
so that we'll know when to
start looking for more information.
<p>
If the value given for &quot;Content-Transfer-Encoding&quot;
is one of the real encodings: &quot;BASE64&quot;,
&quot;QUOTED-PRINTABLE&quot;, &quot;X-BASE8&quot;,
&quot;X-BASE10&quot; or &quot;X-BASE16&quot;, 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, <A HREF="cif_img_1.5.4.html">cif_img_1.5.4.dic</A>,
as one html file, or as <a href=index.html>separate pages for each defintion</a>.
<p>
For certain compressions (e.g. CBF_PACKED) MIME headers are
essential to determine the parameters of the compression.
The full list of MIME headers recognized by and generated by CBFlib is:
<p>
<ul>
<li>Content-Type:
<li>Content-Transfer-Encoding:
<li>Content-MD5:
<li>X-Binary-Size:
<li>X-Binary-ID:
<li>X-Binary-Element-Type:
<li>X-Binary-Element-Byte-Order:
<li>X-Binary-Number-of-Elements:
<li>X-Binary-Size-Fastest-Dimension:
<li>X-Binary-Size-Second-Dimension:
<li>X-Binary-Size-Third-Dimension:
<li>X-Binary-Size-Padding:
</ul>
<p>
<ul>
<li>Content-Type:
<P>
The &QUOT;Content-Type&QUOT; header tells us what
sort of data we have (currently always
&QUOT;application/octet-stream&QUOT; for a miscellaneous
stream of binary data) and, optionally, the
conversions that were applied to the original data.
The default is to compress the data with
the &quot;CBF-PACKED&quot; algorithm.
              The Content-Type may be any of the discrete types permitted
              in RFC 2045; 'application/octet-stream' is recommended.
              If an octet stream was compressed, the compression should
              be specified by the parameter 
                'conversions=&quot;<b>X</b>-CBF_PACKED&quot;'
              or the parameter
                'conversions=&quot;<b>X</b>-CBF_PACKED_V2&quot;'
              or the parameter 
                'conversions=&quot;<b>X</b>-CBF_CANONICAL&quot;'
              or the parameter 
                'conversions=&quot;<b>X</b>-CBF_BYTE_OFFSET&quot;'
              or the parameter
                'conversions=&quot;<b>X</b>-CBF_NIBBLE_OFFSET&quot;'
<P>
              If the parameter
                'conversions=&quot;<b>X</b>-CBF_PACKED&quot;'
              or 
                'conversions=&quot;<b>X</b>-CBF_PACKED_V2&quot;'
              is given it may be further modified with the parameters
                '&quot;uncorrelated_sections&quot;'
              or
                '&quot;flat&quot;'
<P>              
              If the '&quot;uncorrelated_sections&quot;' parameter is
              given, each section will be compressed without using
              the prior section for averaging.
              
              If the '&quot;flat&quot;' parameter is given, each the
              image will be treated as one long row.
<P>

<li>Content-Transfer-Encoding:
<P>
              The &quot;Content-Transfer-Encoding&quot; may be 'BASE64',
              'Quoted-Printable', '<b>X</b>-BASE8', '<b>X</b>-BASE10',
              '<b>X</b>-BASE16' or '<b>X</b>-BASE32K', for an imgCIF or 'BINARY'
              for a CBF.  The octal, decimal and hexadecimal transfer
              encodings are provided for convenience in debugging and
              are not recommended for archiving and data interchange.
<P>
              In a CIF, one of the parameters 'charset=us-ascii',
              'charset=utf-8' or 'charset=utf-16' may be used on the
              Content-Transfer-Encoding to specify the character set
              used for the external presentation of the encoded data.
              If no charset parameter is given, the character set of
              the enclosing CIF is assumed.  In any case, if a BOM
              flag is detected (FE FF for big-endian UTF-16, FF FE for
              little-endian UTF-16 or EF BB BF for UTF-8) is detected,
              the indicated charset will be assumed until the end of the
              encoded data or the detection of a different BOM.  The
              charset of the Content-Transfer-Encoding is not the character
              set of the encoded data, only the character set of the
              presentation of the encoded data and should be respecified
              for each distinct STAR string.
<P>
              In an imgCIF file, the encoded binary data begins after
              the empty line terminating the header.  In an imgCIF file,
              the encoded binary data ends with the terminating boundary
              delimiter '\n--CIF-BINARY-FORMAT-SECTION----'
              in the currently effective charset or with the '\n; '
              that terminates the STAR string.
<P>
              In a CBF, the raw binary data begins after an empty line
              terminating the header and after the sequence:
<P>
<PRE>
              Octet   Hex   Decimal  Purpose
                0     0C       12    (ctrl-L) Page break
                1     1A       26    (ctrl-Z) Stop listings in MS-DOS
                2     04       04    (Ctrl-D) Stop listings in UNIX
                3     D5      213    Binary section begins
</PRE>
              None of these octets are included in the calculation of
              the message size or in the calculation of the
              message digest.
<P>


<li>Content-MD5:
<P>
              An MD5 message digest may, optionally, be used. The 'RSA Data
              Security, Inc. MD5 Message-Digest Algorithm' should be used.
              No portion of the header is included in the calculation of the
              message digest.  The optional &quot;Content-MD5&quot; header provides a much
more sophisticated check on the integrity
of the binary data than size checks alone can provide.
<P>
<li>X-Binary-Size:
<P>
              The &quot;X-Binary-Size&quot; header specifies the size of the
              equivalent binary data in octets.  
              This is the size <b>after</b> any
compressions, but before any ascii encodings.
This is useful in making a simple check for a
missing portion of this file. The 8 bytes for the
Compression type (see below)
are not counted in this field,
so the value of &quot;X-Binary-Size&quot; is 8 less than
the quantity in bytes 12-19 of the raw binary data (<A HREF="#3.2.2">
3.2.2  Format of CBF binary sections</A>).

<P>
<li>X-Binary-ID:
<p>
The &quot;X-Binary-ID&quot; header should contain the
same value as was given for &quot;_array_data.binary_id&quot;.
<P>
<li>X-Binary-Element-Type:
<P>
             The &quot;X-Binary-Element-Type&quot; header specifies the type of
              binary data in the octets, using the same descriptive
              phrases as in <a href="#_array_structure.encoding_type">_array_structure.encoding_type</a>.  The default
              value is 'unsigned 32-bit integer'.
<P>
<li>X-Binary-Element-Byte-Order:
<P>
The &quot;X-Binary-Element-Byte-Order&quot; can specify either 
'&quot;BIG_ENDIAN&quot;' or '&quot;LITTLE_ENDIAN&quot;' byte order
of the image data.  CBFlib only writes '&quot;LITTLE_ENDIAN&quot;',
and in general can only process LITTLE_ENDIAN
even on machines that are BIG_ENDIAN. 
<P>

<li>X-Binary-Number-of-Elements:
<P>
The &quot;X-Binary-Number-of-Elements&quot; specifies the
number of elements (not the number of octets) in the decompressed, decoded image.
<P>
<li>X-Binary-Size-Fastest-Dimension:
<P>
The optional &quot;X-Binary-Size-Fastest-Dimension&quot; specifies
the number of elements (not the number of octets) in one row
of the fastest changing dimension of the binary data array.
This information must be in the MIME header for proper
operation of some of the decompression algorithms.
<P>
<li>X-Binary-Size-Second-Dimension:
<P>
The optional &quot;X-Binary-Size-Second-Dimension&quot; specifies
the number of elements (not the number of octets) in one column
of the second-fastest changing dimension of the binary data array.
This information must be in the MIME header for proper
operation of some of the decompression algorithms.
<P>
<li>X-Binary-Size-Third-Dimension:
<P>
The optional &quot;X-Binary-Size-Third-Dimension&quot; specifies
the number of sections
for the third-fastest changing dimension of the binary data array.
<P>
<li>X-Binary-Size-Padding:
<P>
The optional &quot;X-Binary-Size-Padding&quot; specifies the size
in octets of an optional padding
after the binary array data and before the closing flags for
a binary section.  CBFlib always writes this padding as zeros,
but this information should be in the MIME header for a binary
section that uses padding, especially if non-zero padding is
used.

</ul>

<p>
A blank line separator immediately precedes the start of the
encoded binary data.  Blank spaces
may be added prior to the preceding &quot;line separator&quot;
if desired (e.g. to force word or block
alignment).
<p>
Because CBFLIB may jump forward in the file from the MIME header,
the length of encoded
data cannot be greater than the value defined
by &quot;X-Binary-Size&quot; (except when &quot;X-Binary-Size&quot;
is zero, which means that the size is unknown), unless
&quot;X-Binary-Size-Padding&quot; is specified to
allow for the padding.
At exactly the byte following the full binary section
as defined by the length and padding values is the end of
binary section identifier. This consists of the
line-termination sequence followed by:
<p>
<PRE>
--CIF-BINARY-FORMAT-SECTION----
;
</PRE>
<p>
with each of these lines followed by a line-termination sequence.
This brings us back into a
normal CIF environment.  This identifier is, in a sense,
redundant because the binary data length
value tells the a program how many bytes to jump over to
the end of the binary data.  This
redundancy has been deliberately added for error checking,
and for possible file recovery in the
case of a corrupted file and this identifier must be
present at the end of every block of binary data.
<p>

<h4><A NAME="3.2.2">3.2.2  Format of CBF binary sections</A></h4>
<p>




<p>
In a CBF file, each binary section is encoded as a ;-delimited string,
starting  with an
arbitrary number of pure-ASCII characters.
<p>
<b>Note:</b> For historical reasons, CIFlib has the option of writing simple
header and footer sections: &quot;START OF BINARY SECTION&quot; at
the start of a binary section and
&quot;END OF BINARY SECTION&quot; at the end of a binary section,
or writing MIME-type header
and footer sections (<A HREF="3.2.1">3.2.1
Format of imgCIF binary sections</A>).
If the simple header is used, the actual ASCII text is ignored when the
binary section is read.  <b>Use of the simple binary header is deprecated.</b>
<p>
The MIME header is
recommended.
<p>
Between the ASCII header and the actual CBF binary data is a series of
bytes (&quot;octets&quot;) to try to stop the listing of the header,
bytes which define the binary identifier which should match the
&quot;binary_id&quot; defined in the header, and bytes which define the
length of the binary section.<p><br />
<Table>
<TR><TH>             Octet   <TH>Hex   <TH>Decimal  <TH>Purpose
<TR><td valign="top">&nbsp;&nbsp;              1     <td valign="top">&nbsp;&nbsp;0C       <td valign="top">&nbsp;&nbsp;12    <td valign="top">&nbsp;&nbsp;(ctrl-L) End of Page
<TR><td valign="top">&nbsp;&nbsp;              2     <td valign="top">&nbsp;&nbsp;1A       <td valign="top">&nbsp;&nbsp;26    <td valign="top">&nbsp;&nbsp;(ctrl-Z) Stop listings in MS-DOS
<TR><td valign="top">&nbsp;&nbsp;              3     <td valign="top">&nbsp;&nbsp;04       <td valign="top">&nbsp;&nbsp;04    <td valign="top">&nbsp;&nbsp;(Ctrl-D) Stop listings in UNIX
<TR><td valign="top">&nbsp;&nbsp;              4     <td valign="top">&nbsp;&nbsp;D5      <td valign="top">&nbsp;&nbsp;213   <td valign="top">&nbsp;&nbsp;Binary section begins
<TR><td valign="top">&nbsp;&nbsp;             5..5+n-1<td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;&nbsp; <td valign="top">&nbsp;&nbsp;Binary data (n octets)
</TABLE><br />
<p>
NOTE:  When a MIME header is used, only bytes 5 through 5+n-1 are considered in
computing the size and the message digest, and only these bytes are
encoded for the equivalent imgCIF file using the indicated
Content-Transfer-Encoding.
<p>
If no MIME header has been requested (a deprecated use), then bytes 5 through 28 are
used for three
8-byte words to hold the binary_id, the size and the compression type:
<p>
<TABLE>
<TR><TD VALIGN=TOP>&nbsp;&nbsp;              5..12  <td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;&nbsp; <td valign="top">&nbsp;&nbsp;Binary Section Identifier<br />
                                    (See _array_data.binary_id)<br />
                                    64-bit, little endian
<TR><TD VALIGN=TOP>&nbsp;&nbsp;             13..20 <td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;&nbsp; <td valign="top">&nbsp;&nbsp;The size (n) of the<br />
                                    binary section in octets<br />
                                    (i.e. the offset  from octet<br />
                                    29 to the first byte following<br />
                                    the data)
<TR><TD VALIGN=TOP>&nbsp;&nbsp;             21..28<td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;&nbsp; <td valign="top">&nbsp;&nbsp;Compression type:<br />
                                      <TABLE ALIGN=CENTER>
                                      <TR><td valign="top">&nbsp;&nbsp;CBF_NONE       <td valign="top">&nbsp;&nbsp;0x0040 (64)
                                      <TR><td valign="top">&nbsp;&nbsp;CBF_CANONICAL  <td valign="top">&nbsp;&nbsp;0x0050 (80)
                                      <TR><td valign="top">&nbsp;&nbsp;CBF_PACKED     <td valign="top">&nbsp;&nbsp;0x0060 (96)
                                      <TR><td valign="top">&nbsp;&nbsp;CBF_PACKED_V2   <td valign="top">&nbsp;&nbsp;0x0090 (144)
                                      <TR><td valign="top">&nbsp;&nbsp;CBF_BYTE_OFFSET <td valign="top">&nbsp;&nbsp;0x0070 (112)
                                      <TR><td valign="top">&nbsp;&nbsp;CBF_NIBBLE_OFFSET <td valign="top">&nbsp;&nbsp;0x00A0 (160)
                                      <TR><td valign="top">&nbsp;&nbsp;CBF_PREDICTOR   <td valign="top">&nbsp;&nbsp;0x0080 (128)
                                      <TR><td valign="top">&nbsp;&nbsp;...            <td valign="top">&nbsp;&nbsp;&nbsp;
                                      </TABLE>
</TABLE>
<p>
The binary data then follows in bytes 29 through 29+n-1.

<p>

The binary characters serve specific purposes:
<p>

<ul type=circle>

<li> The Control-L (from-feed) will terminate printing of the current page
     on most operating systems.
<p>

<li> The Control-Z will stop the listing of the file on MS-DOS
     type operating systems.
<p>

<li> The Control-D will stop the listing of the file on Unix
     type operating systems.
<p>

<li> The unsigned byte value 213 (decimal) is binary 11010101.
     (Octal 325, and hexadecimal D5).
     This has the eighth bit set so can be used for error checking
     on 7-bit transmission. It is also asymmetric, but with the first
     bit also set in the case that the bit order could be reversed
     (which is not a known concern).
<p>

<li> (The carriage return, line-feed pair before the START_OF_BIN
     and other lines can also be used to check that the file has not
     been corrupted e.g. by being sent by ftp in ASCII mode.)
<p>

<p><br />
      At present four compression schemes are implemented
     are defined:  CBF_NONE (for no compression), CBF_CANONICAL (for
     and entropy-coding scheme based on the canonical-code algorithm
     described by Moffat, <i>et al</i>. (<i>International
     Journal of High Speed Electronics and Systems</i>, Vol 8, No 1 (1997)
     179-231)), CBF_PACKED or CBF_PACKED_V2 for J. P. Abrahams CCP4-style 
     packing schemes and CBF_BYTE_OFFSET
     for a simple byte_offset compression scheme..  Other
     compression schemes will be added to
     this list in the future.
</ul>
<p>
For historical reasons, CBFlib can read or write a binary
string without a MIME header.   The structure of a binary string with simple
headers is:
<p>
<Table>
<tr><th ALIGN=LEFT VALIGN=TOP>Byte<th ALIGN=LEFT>ASCII<br />symbol<th ALIGN=LEFT>Decimal&nbsp;<br />value<th ALIGN=LEFT VALIGN=TOP>Description
<tr><td valign="top">&nbsp;&nbsp;1<td valign="top">&nbsp;&nbsp;;<td valign="top">&nbsp;&nbsp;59<td valign="top">&nbsp;&nbsp;Initial ; delimiter<br />
<tr><td valign="top">&nbsp;&nbsp;2<td valign="top">&nbsp;&nbsp;carriage-return<td valign="top">&nbsp;&nbsp;13<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;3<td valign="top">&nbsp;&nbsp;line-feed<td valign="top">&nbsp;&nbsp;10<td valign="top">&nbsp;&nbsp;The CBF new-line code is carriage-return, line-feed<br />
<tr><td valign="top">&nbsp;&nbsp;4<td valign="top">&nbsp;&nbsp;S<td valign="top">&nbsp;&nbsp;83<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;5<td valign="top">&nbsp;&nbsp;T<td valign="top">&nbsp;&nbsp;84<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;6<td valign="top">&nbsp;&nbsp;A<td valign="top">&nbsp;&nbsp;65<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;7<td valign="top">&nbsp;&nbsp;R<td valign="top">&nbsp;&nbsp;83<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;8<td valign="top">&nbsp;&nbsp;T<td valign="top">&nbsp;&nbsp;84<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;9<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;32<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;10<td valign="top">&nbsp;&nbsp;O<td valign="top">&nbsp;&nbsp;79<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;11<td valign="top">&nbsp;&nbsp;F<td valign="top">&nbsp;&nbsp;70<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;12<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;32<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;13<td valign="top">&nbsp;&nbsp;B<td valign="top">&nbsp;&nbsp;66<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;14<td valign="top">&nbsp;&nbsp;I<td valign="top">&nbsp;&nbsp;73<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;15<td valign="top">&nbsp;&nbsp;N<td valign="top">&nbsp;&nbsp;78<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;16<td valign="top">&nbsp;&nbsp;A<td valign="top">&nbsp;&nbsp;65<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;17<td valign="top">&nbsp;&nbsp;R<td valign="top">&nbsp;&nbsp;83<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;18<td valign="top">&nbsp;&nbsp;Y<td valign="top">&nbsp;&nbsp;89<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;19<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;32<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;20<td valign="top">&nbsp;&nbsp;S<td valign="top">&nbsp;&nbsp;83<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;21<td valign="top">&nbsp;&nbsp;E<td valign="top">&nbsp;&nbsp;69<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;22<td valign="top">&nbsp;&nbsp;C<td valign="top">&nbsp;&nbsp;67<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;23<td valign="top">&nbsp;&nbsp;T<td valign="top">&nbsp;&nbsp;84<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;24<td valign="top">&nbsp;&nbsp;I<td valign="top">&nbsp;&nbsp;73<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;25<td valign="top">&nbsp;&nbsp;O<td valign="top">&nbsp;&nbsp;79<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;26<td valign="top">&nbsp;&nbsp;N<td valign="top">&nbsp;&nbsp;78<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;27<td valign="top">&nbsp;&nbsp;carriage-return<td valign="top">&nbsp;&nbsp;13<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;28<td valign="top">&nbsp;&nbsp;line-feed<td valign="top">&nbsp;&nbsp;10<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;29<td valign="top">&nbsp;&nbsp;form-feed<td valign="top">&nbsp;&nbsp;12<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;30<td valign="top">&nbsp;&nbsp;substitute<td valign="top">&nbsp;&nbsp;26<td valign="top">&nbsp;&nbsp;Stop the listing of the file in MS-DOS<br />
<tr><td valign="top">&nbsp;&nbsp;31<td valign="top">&nbsp;&nbsp;end-of-transmission<td valign="top">&nbsp;&nbsp;4<td valign="top">&nbsp;&nbsp;Stop the listing of the file in unix<br />
<tr><td valign="top">&nbsp;&nbsp;32<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;213<td valign="top">&nbsp;&nbsp;First non-ASCII value<br />
<tr><td valign="top">&nbsp;&nbsp;33 .. 40<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;Binary section identifier (64-bit little-endien)<br />
<tr><td valign="top">&nbsp;&nbsp;41 .. 48<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;Offset from byte 57 to the first ASCII character following the binary data<br />
<tr><td valign="top">&nbsp;&nbsp;49 .. 56<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;Compression type<br />
<tr><td COLSPAN=2>57 .. 57 + <i>n</i>-1<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;Binary data (<i>n</i>bytes)<br />
<tr><td valign="top">&nbsp;&nbsp;57 + <i>n</i>
<td valign="top">&nbsp;&nbsp;carriage-return<td valign="top">&nbsp;&nbsp;13<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;58 + <i>n</i>
<td valign="top">&nbsp;&nbsp;line-feed<td valign="top">&nbsp;&nbsp;10<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;59 + <i>n</i>
<td valign="top">&nbsp;&nbsp;E<td valign="top">&nbsp;&nbsp;69<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;60 + <i>n</i>
<td valign="top">&nbsp;&nbsp;N<td valign="top">&nbsp;&nbsp;78<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;61 + <i>n</i>
<td valign="top">&nbsp;&nbsp;D<td valign="top">&nbsp;&nbsp;68<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;62 + <i>n</i>
<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;32<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;63 + <i>n</i>
<td valign="top">&nbsp;&nbsp;O<td valign="top">&nbsp;&nbsp;79<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;64 + <i>n</i>
<td valign="top">&nbsp;&nbsp;F<td valign="top">&nbsp;&nbsp;70<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;65 + <i>n</i>
<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;32<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;66 + <i>n</i>
<td valign="top">&nbsp;&nbsp;B<td valign="top">&nbsp;&nbsp;66<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;67 + <i>n</i>
<td valign="top">&nbsp;&nbsp;I<td valign="top">&nbsp;&nbsp;73<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;68 + <i>n</i>
<td valign="top">&nbsp;&nbsp;N<td valign="top">&nbsp;&nbsp;78<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;69 + <i>n</i>
<td valign="top">&nbsp;&nbsp;A<td valign="top">&nbsp;&nbsp;65<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;70 + <i>n</i>
<td valign="top">&nbsp;&nbsp;R<td valign="top">&nbsp;&nbsp;83<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;71 + <i>n</i>
<td valign="top">&nbsp;&nbsp;Y<td valign="top">&nbsp;&nbsp;89<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;72 + <i>n</i>
<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;32<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;73 + <i>n</i>
<td valign="top">&nbsp;&nbsp;S<td valign="top">&nbsp;&nbsp;83<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;74 + <i>n</i>
<td valign="top">&nbsp;&nbsp;E<td valign="top">&nbsp;&nbsp;69<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;75 + <i>n</i>
<td valign="top">&nbsp;&nbsp;C<td valign="top">&nbsp;&nbsp;67<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;76 + <i>n</i>
<td valign="top">&nbsp;&nbsp;T<td valign="top">&nbsp;&nbsp;84<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;77 + <i>n</i>
<td valign="top">&nbsp;&nbsp;I<td valign="top">&nbsp;&nbsp;73<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;78 + <i>n</i>
<td valign="top">&nbsp;&nbsp;O<td valign="top">&nbsp;&nbsp;79<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;79 + <i>n</i>
<td valign="top">&nbsp;&nbsp;N<td valign="top">&nbsp;&nbsp;78<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;80 + <i>n</i>
<td valign="top">&nbsp;&nbsp;carriage-return<td valign="top">&nbsp;&nbsp;13<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;81 + <i>n</i>
<td valign="top">&nbsp;&nbsp;line-feed<td valign="top">&nbsp;&nbsp;10<td valign="top">&nbsp;&nbsp;<br />
<tr><td valign="top">&nbsp;&nbsp;82 + <i>n</i>
<td valign="top">&nbsp;&nbsp;;<td valign="top">&nbsp;&nbsp;59<td valign="top">&nbsp;&nbsp;Final ; delimiter<br />
</table><br />


<h4><A NAME="3.3">3.3  Compression schemes</A></h4>
<p>
Two schemes for lossless compression of integer arrays (such as images) have been
implemented in this version of CBFlib:
<p>
1. An entropy-encoding scheme using canonical coding<br />
2. A CCP4-style packing scheme.
3. A simple and efficient byte-offset compression.
4. A slightly more complex nibble-offset compression.
<p>
All encode the difference (or error) between the current element in the array and
the prior element or neighboring elements.
<p>

<h4><A NAME="3.3.1">3.3.1  Canonical-code compression</A></h4>
<p>
The canonical-code compression scheme encodes errors in two ways: directly or indirectly.
 Errors are coded directly using a symbol corresponding to the error value.  Errors
are coded indirectly using a symbol for the number of bits in the (signed) error,
followed by the error iteslf.
<p>
At the start of the compression, CBFlib constructs a table containing a set of symbols,
one for each of the 2^<SUP>n</sup>
 direct codes from -2^<SUP>(n-1)</sup>
 .. 2^<SUP>(n-1)</sup>-1,
one for a stop code, and one for each of the <i>maxbits</i>
-<i>n</i>
 indirect codes, where <i>n</i>
 is chosen at compress time and <i>maxbits</i>
 is the maximum number of bits in an error.  CBFlib then assigns to each symbol a
bit-code, using a shorter bit code for the more common symbols and a longer bit code
for the less common symbols.  The bit-code lengths are calculated using a Huffman-type
algorithm, and the actual bit-codes are constructed using the canonical-code algorithm
described by Moffat, <i>et al</i>. (<i>International
Journal of High Speed Electronics and Systems</i>, Vol 8, No 1 (1997) 179-231).
<p>
The structure of the compressed data is:
<p>
<TABLE ALIGN=CENTER>
<TR><TH ALIGN=LEFT>Byte<TH>Value
<TR><td valign="top">&nbsp;&nbsp;1 .. 8<td valign="top">&nbsp;&nbsp;Number of elements (64-bit little-endian number)<br />
<TR><td valign="top">&nbsp;&nbsp;9 .. 16<td valign="top">&nbsp;&nbsp;Minimum element<br />
<TR><td valign="top">&nbsp;&nbsp;17 .. 24<td valign="top">&nbsp;&nbsp;Maximum element<br />
<TR><td valign="top">&nbsp;&nbsp;25 .. 32<td valign="top">&nbsp;&nbsp;(reserved for future use)<br />
<TR><td valign="top">&nbsp;&nbsp;33<td valign="top">&nbsp;&nbsp;Number of bits directly coded, <I>n</I>
<TR><td valign="top">&nbsp;&nbsp;34<td valign="top">&nbsp;&nbsp;Maximum number of bits encoded, <I>maxbits</I>
<TR><td valign="top">&nbsp;&nbsp;35 .. 35+2^<SUP>n</SUP>-1<td valign="top">&nbsp;&nbsp;Number of bits in each direct code<br />
<TR><td valign="top">&nbsp;&nbsp;35+2^<SUP>n</SUP><td valign="top">&nbsp;&nbsp;Number of bits in the stop code<br />
<TR><td valign="top">&nbsp;&nbsp;35+2^<SUP>n</SUP>+1 .. 35+2^<SUP>n</SUP>+<I>maxbits</I>-<I>n</I>
<td valign="top">&nbsp;&nbsp;Number of bits in each indirect code<br />
<TR><td valign="top">&nbsp;&nbsp;35+2^<SUP>n</SUP>+<I>maxbits</I>-<I>n</I>+1 ..
<td valign="top">&nbsp;&nbsp;Coded data<br />
</TABLE>

<H4><A NAME="3.3.2">3.3.2  CCP4-style compression</A></H4>
<p>
Starting with CBFlib 0.7.7, CBFlib supports three variations on CCP4-style
compression:  the &quot;flat&quot; version supported in versions of
CBFlib prior to release 0.7.7, as well as both version 1 and version 2
of J. P. Abrahams &quot;pack_c&quot; compression.  
<P>
The CBF_PACKED and CBF_PACKED_V2 compression and decompression code
incorporated in CBFlib is derived in large part from the J. P. Abrahams
pack_c.c compression code in CCP4.  This code is incorporated in
CBFlib under the GPL and the LGPL with both the permission
Jan Pieter Abrahams, the original author of pack_c.c (email from Jan Pieter 
Abrahams of 15 January 2007) and of the CCP4 project (email from Martyn 
Winn on 12 January 2007).  The cooperation of J. P. Abrahams and
of the CCP4 project is gratefully acknowledged.
<P>
The basis for all three versions is a scheme to pack offsets (differences from a
base value) into a small-endian bit stream.  The stream is organized
into blocks.  Each block begins with a header of 6 bits in the flat
packed version and version 1 of J. P. Abrahams compression, and 7 bits
in version 2 of J. P. Abrahams compression.  The header gives the
number of offsets that follow and the number of bits in each offset.
Each offset is a signed, 2's complement integer.
<P>
The first 3 bits in the header gives the logarithm base 2 of
the numer of offsets that follow the header.  For example, if
a header has a zero in bits, only one offset follows the header.
If those same bits contain the number n, the number of offsets
in the block is 2<SUP>n</SUP>.
<P>
The following 3 bits (flat and version 1) or 4 bits (version 2)
contains a number giving an index into a table of bit-lengths
for the offsets.  All offsets in a given block are of the same
length.
<P>
Bits 3 .. 5 (flat and version 1) or bits 3 .. 6 (version 2)
encode the number of bits in each offset as follows:<br />
<TABLE ALIGN=CENTER>
<TR><TH ALIGN=CENTER>Value in<br /> bits 3 .. 5</TH>
<TH ALIGN=CENTER>Number of bits<br /> in each V1 offset<p></TH>
<TH ALIGN=CENTER>Number of bits<br /> in each V2 offset<p></TH>
</TR>
<TR><TD ALIGN=CENTER>0</TD><TD ALIGN=CENTER>0</TD><TD ALIGN=CENTER>0</TD>
<TR><TD ALIGN=CENTER>1</TD><TD ALIGN=CENTER>4</TD><TD ALIGN=CENTER>3</TD>
<TR><TD ALIGN=CENTER>2</TD><TD ALIGN=CENTER>5</TD><TD ALIGN=CENTER>4</TD>
<TR><TD ALIGN=CENTER>3</TD><TD ALIGN=CENTER>6</TD><TD ALIGN=CENTER>5</TD>
<TR><TD ALIGN=CENTER>4</TD><TD ALIGN=CENTER>7</TD><TD ALIGN=CENTER>6</TD>
<TR><TD ALIGN=CENTER>5</TD><TD ALIGN=CENTER>8</TD><TD ALIGN=CENTER>7</TD>
<TR><TD ALIGN=CENTER>6</TD><TD ALIGN=CENTER>16</TD><TD ALIGN=CENTER>8</TD>
<TR><TD ALIGN=CENTER>7</TD><TD ALIGN=CENTER>max</TD><TD ALIGN=CENTER>9</TD>
<TR><TD ALIGN=CENTER>8</TD><TD ALIGN=CENTER>&nbsp;</TD><TD ALIGN=CENTER>10</TD>
<TR><TD ALIGN=CENTER>9</TD><TD ALIGN=CENTER>&nbsp;</TD><TD ALIGN=CENTER>11</TD>
<TR><TD ALIGN=CENTER>10</TD><TD ALIGN=CENTER>&nbsp;</TD><TD ALIGN=CENTER>12</TD>
<TR><TD ALIGN=CENTER>11</TD><TD ALIGN=CENTER>&nbsp;</TD><TD ALIGN=CENTER>13</TD>
<TR><TD ALIGN=CENTER>12</TD><TD ALIGN=CENTER>&nbsp;</TD><TD ALIGN=CENTER>14</TD>
<TR><TD ALIGN=CENTER>13</TD><TD ALIGN=CENTER>&nbsp;</TD><TD ALIGN=CENTER>15</TD>
<TR><TD ALIGN=CENTER>14</TD><TD ALIGN=CENTER>&nbsp;</TD><TD ALIGN=CENTER>16</TD>
<TR><TD ALIGN=CENTER>15</TD><TD ALIGN=CENTER>&nbsp;</TD><TD ALIGN=CENTER>max</TD>
</TABLE>
<P>
The value &quot;max&quot; is determined by the compression version and the
element size.  If the compression used is &quot;flat&quot;, then &quot;max&quot; is 65.
If the compression is version 1 or version 2 of the JPA compression, then
&quot;max&quot; is the number of bits in each element, i.e. 8, 16, 32 or 64
bits.
<P>
The major difference between the three variants of packed compression is the
choice of the base value from which the offset is measured.   In all cases
the first offset is measured from zero, i.e. the first offset is the value
of the first pixel of the image.  If &quot;flat&quot;
is chosen or if the dimensions of the data array are not given, then the
remaining offset are measure against the prior value, making it similar
in approach to the &quot;byte offset&quot; compression described in
section <a href="3.3.3">3.3.3  Byte offset compression</a>, but with a
more efficient representation of the offsets.
<P>
In version 1 and version 2 of the J. P. Abrahams compression, the
offsets are measured against an average of earlier pixels.  If there
is only one row only the prior pxiel is used, starting with the same
offsets for that row as for &quot;flat&quot;.  After the first row,
three pixels from the prior row are used in addition to using the
immediately prior pixel.  If there are multiple sections,
and the sections are marked as correlated, after the first section,
4 pixels from the prior section are included in the average.
The CBFlib code differs from the pack_c code in the handling
of the beginnings and ends of rows and sections.  The pack_c
code will use pixels from the other side of the image in doing the
averaging.  The CBFlib code drops pixels from the other side of
the image from the pool.  The details follow.
<P>
After dealing with the special case of the first pixel,
The algorithm uses an array of pointers, trail_char_data.
The assignment of pixels to the pool to be averaged begins
with trail_char_data[0] points to the pixel immediately prior 
to the next pixel to be processed, either in the same row 
(fastest index) or, at the end of the prior row if the next 
data element to be processed is at the end of a row.  The
location of the pixel pointed to by trail_char_data[0]
is used to compute the locations of the other pixels
in the pool.  It will be dropped from the pool before
averaging if it is on the opposite side of the image. 
The pool will consist of 1, 2, 4 or 8 pixels.
<P>  
Assume ndim1, ndim2, ndim3 are the indices of the same
pixel as trail_char_data[0] points to.  These indices
are incremented to be the indices of the next pixel
to be processed before populating trail_char_data.
<P>   
On exit, trail_char_data[0 .. 7] will have been populated with
pointers to the pixels to be used in forming the average.
Pixels that will not be used will be set to NULL.   Note
that trail_char_data[0] may be set to NULL.             
<P>   
If we mark the next element to be processed with a &quot;*&quot; 
and the entries in trail_char_data with their array indices 
0 .. 7, the  possible patterns of settings in the general case are:
<P>
    current section:
<P>
<PRE><TT>
    
         - - - - 0 * - - - -
         - - - - 3 2 1 - - - 
         - - - - - - - - - -
</TT>
</PRE>
<P>
    prior section:
<P>
<PRE><TT>
    
         - - - - - 4 - - - -
         - - - - 7 6 5 - - - 
         - - - - - - - - - -
</TT>
</PRE>
<P>             
    If there is no prior section (i.e. ndim3 is 0, or 
    the CBF_UNCORRELATED_SECTIONS flag is set
    to indicate discontinuous sections), the values
    for trail_char_data[4 .. 7] will all be NULL.  When
    there is a prior section, trail_char_data[5..7] are
    pointers to the pixels immediately below the
    elements pointed to by trail_char_data[1..3], except
    trail_char_data[4] is one element further along
    its row to be directly below the next element to
    be processed.
<P>
    
    The first element of the first row of the first section
    is a special case, with no averaging. 
<P>

    In the first row of the first section (ndim2 == 0,
    and ndim3 == 0), after the first element (ndim1 > 0), 
    only trail_char_data[0] is used
<P>
    current section:
<P>
<PRE><TT>
        
         - - - - 0 * - - - -
</TT>
</PRE>
<P>

    For subsequent rows of the first section (ndim2 > 0,
    and ndim3 == 0), for the first element (ndim1 == 0), 
    two elements from the prior row are used:
<P>    
    current section:
<P>
<PRE><TT>
    
         * - - - - - - - - -
         2 1 - - - - - - - -
         - - - - - - - - - -
</TT>
</PRE>
<P>
    while for element after the first element, but before
    the last element of the row, a full set of 4 elements 
    is used:
 <P>  
    current section:
<P>
<PRE><TT>
    
         - - - - 0 * - - - -
         - - - - 3 2 1 - - - 
         - - - - - - - - - -
</TT>
</PRE>
<P>
         
    For the last element of a row (ndim1 == dim1-1), two
    elements are used
<P>
    current section:
<P>
<PRE><TT>
   
         - - - - - - - - 0 *
         - - - - - - - - - 2 
         - - - - - - - - - -
</TT>
</PRE>
<P>
         
    For sections after the first section, provided the
    CBF_UNCORRELATED_SECTIONS flag is not set in the compression,
    for each non-NULL entry in trail_char_data [0..3] an entry 
    is made in trail_char_data [4..7], except for the
    first element of the first row of a section.  In that
    case an entry is made in trail_char_data[4].

<p>
The structure of the compressed data is:<br />
<TABLE ALIGN=CENTER>
<TR><TH>Byte</TH><TH>Value</TH>
<TR><td valign="top">&nbsp;&nbsp;1 .. 8</TD><td valign="top">&nbsp;&nbsp;Number of elements (64-bit little-endian number)</TD></TR>
<TR><td valign="top">&nbsp;&nbsp;9 .. 16</TD><td valign="top">&nbsp;&nbsp;Minumum element (currently unused)</TD></TR>
<p>
<TR><td valign="top">&nbsp;&nbsp;17 .. 24</TD><td valign="top">&nbsp;&nbsp;Maximum element (currently unused)</TD></TR>
<p>
<TR><td valign="top">&nbsp;&nbsp;25 .. 32</TD><td valign="top">&nbsp;&nbsp;(reserved for future use)</TD></TR>
<p>
<TR><td valign="top">&nbsp;&nbsp;33 ..</TD><td valign="top">&nbsp;&nbsp;Coded data</TD></TR>
</TABLE>
<P>
<H4><A NAME="3.3.3">3.3.3   Byte_offset compression</A></H4>
<p>


<p>
Starting with CBFlib 0.7.7, CBFlib supports a simple and efficient &quot;byte_offset&quot;
algorithm originally proposed by Andy Hammerley and modified by Wolgang Kabsch and
Herbert Bernstein.  The original proposal was called &quot;byte_offsets&quot;.  We
distinguish this variant by calling it &quot;byte_offset&quot;.  The major differences
are that the &quot;byte_offsets&quot; algorithm started with explicit storage
of the first element of the array as a 4-byte signed two's integer, and checked
for image edges to changes the selection of prior pixel.  The CBFlib
&quot;byte_offset&quot; alogorithm starts with an assumed zero before the
first pixel and represents the value of the first pixel as an offset
of whatever number of size is needed to hold the value, and for speed, treats the
entire image as a simple linear array, allowing use of the last
pixel of one row as the base against which to compute the offset for
the first element of the next row.

<p>
The algorithm is simple and easily implemented.
This algorithm can never achieve better than a factor of two compression
relative to 16-bit raw data or 4 relative to 32-bit raw data, but for 
most diffraction data the compression will indeed be very close to
these ideal values.  It also has the advantage that 
integer values up to 32 bits (or 31 bits and sign) may be stored efficiently 
without the need for special over-load tables. It is a fixed algorithm 
which does not need to calculate any image statistics, so is fast.
<p>
The algorithm works because of the following property of almost all
diffraction data and much other image data: The value of one element
tends to be close to the value of the adjacent elements, and the vast
majority of the differences use little of the full dynamic range.
However, noise in experimental data means that run-length encoding is 
not useful (unless the image is separated into different bit-planes). If
a variable length code is used to store the differences, with the number
of bits used being inversely proportional to the probability of
occurrence, then compression ratios of 2.5 to 3.0 may be achieved. 
However, the optimum encoding becomes dependent of the exact properties 
of the image, and in particular on the noise. Here a lower compression 
ratio is achieved, but the resulting algorithm is much simpler and more 
robust.
<p>
The &quot;byte_offset&quot; compression algorithm is the following:
<p>
<ol>
<li>Start with a base pixel value of 0.

<li>Compute the difference delta between the next pixel value
and the base pixel value.

<li>If -127 &le; delta &le; 127, output delta as one byte,
make the current pixel value the base pixel value and return to step 2.

<li>Otherwise output -128 (80 hex).

<li>We still have to output delta.  If -32767 &le; delta &le; 32767,
output delta as a little_endian 16-bit quantity,
make the current pixel value the base pixel value and return to step 2.

<li>Otherwise output -32768 (8000 hex, little_endian, i.e. 00 then
80)

<li>We still have to output delta.  If -2147483647 &le; delta &le; 2147483647,
output delta as a little_endian 32 bit quantity,
make the current pixel value the base pixel value and return to step 2.

<li>Otherwise output -2147483648 (80000000 hex, little_endian, i.e.
00, then 00, then 00, then 80) and then output the pixel value
as a little-endian 64 bit quantity,
make the current pixel value the base pixel value and return to step 2.

</ol>
<p>
The &quot;byte_offset&quot; decompression algorithm is the following:
<p>
<ol>
<li>Start with a base pixel value of 0.

<li>Read the next byte as delta

<li>If -127 &le; delta &le; 127, add delta to the base pixel value,
make that the new base pixel value, place it on the
output array and return to step 2.

<li>If delta is 80 hex, read the next two bytes as a little_endian
16-bit number and make that delta.

<li>If -32767 &le; delta &le; 32767, add delta to the base pixel value,
make that the new base pixel value, place it on the
output array and return to step 2.

<li>If delta is 8000 hex, read the next 4 bytes as a little_endian
32-bit number and make that delta

<li>If -2147483647 &le; delta &le; 2147483647, add delta to the base pixel value,
make that the new base pixel value, place it on the
output array and return to step 2.

<li>If delta is 80000000 hex, read the next 8 bytes as a little_endian
64-bit number and make that delta,  add delta to the base pixel value,
make that the new base pixel value, place it on the
output array and return to step 2.
</ol>
<p>

Let us look at an example, of two 1000 x 1000 flat field
images presented as a mimimal imgCIF file.  The first image
uses 32-bit unsigned integers and the second image uses
16-bit unsigned integers.
<P>
The imgCIF file begins with some identifying comments (magic
numbers) to track the version of the dictionary and library:
<P>
<div>
<pre>
###CBF: VERSION 1.5
# CBF file written by CBFlib v0.7.7
</pre>
</div>
<P>
This is followed by the necessary syntax to start a CIF
data block and by whatever tags and values are appropriate
to describe the experiment.  The minimum is something like
<P>
<div>
<pre>
data_testflat
</pre>
</div>
<P>
eventually we come to the actual binary data, which begins
the loop header for the array_data category
<P>
<div>
<pre>
loop_
_array_data.data
</pre>
</div>
<P>
with any additional tags needed, and then the data itself,
which starts with the mini-header:
<P>
<div>
<pre>
;
--CIF-BINARY-FORMAT-SECTION--
Content-Type: application/octet-stream;
     conversions="x-CBF_BYTE_OFFSET"
Content-Transfer-Encoding: BINARY
X-Binary-Size: 1000002
X-Binary-ID: 1
X-Binary-Element-Type: "unsigned 32-bit integer"
X-Binary-Element-Byte-Order: LITTLE_ENDIAN
Content-MD5: +FqUJGxXhvCijXMFHC0kaA==
X-Binary-Number-of-Elements: 1000000
X-Binary-Size-Fastest-Dimension: 1000
X-Binary-Size-Second-Dimension: 1000
X-Binary-Size-Padding: 4095
</pre>
</div>
<P>
followed by an empty line and then the sequence of characters:
<P>
<div>
<pre>
^L^Z^D&lt;D5&gt;
</pre>
</div>
<P>
followed immediately by the compressed data.
<P>
The binary data begins with the hex byte 80 to flag
the need for a value that will not fit in one byte.
That is followed by the small_endian hex value 3E8
saying that the first delta is 1000.  Then 999,999
bytes of zero follow, since this is a flat field,
with all values equal to zero.  That gives us our
entire 1000x1000  compressed flat field.  However,
because we asked for 4095 bytes of padding, there
is an additional 4095 bytes of zero that are not
part of the compressed field.  They are just pad
and can be ignored.  Finally, after the pad, the
CIF text field that began with
<P>
<div>
<pre>
;
--CIF-BINARY-FORMAT-SECTION--
</pre>
</div>
<P>
is completed with
<P>
<div>
<pre>
--CIF-BINARY-FORMAT-SECTION----
;
</pre>
</div>
<P>
notice the extra <tt>--</tt>
<P>
The second flat field then follows, with a very
similar mini-header:
<P>
<div>
<pre>
;
--CIF-BINARY-FORMAT-SECTION--
Content-Type: application/octet-stream;
     conversions="x-CBF_BYTE_OFFSET"
Content-Transfer-Encoding: BINARY
X-Binary-Size: 1000002
X-Binary-ID: 2
X-Binary-Element-Type: "unsigned 16-bit integer"
X-Binary-Element-Byte-Order: LITTLE_ENDIAN
Content-MD5: +FqUJGxXhvCijXMFHC0kaA==
X-Binary-Number-of-Elements: 1000000
X-Binary-Size-Fastest-Dimension: 1000
X-Binary-Size-Second-Dimension: 1000
X-Binary-Size-Padding: 4095

^L^Z^D&lt;D5&gt;
</pre>
</div>
<P>

The only difference is that we have declared this
array to be 16-bit and have chosen a different
binary id (2 instead of 1).  Even the checksum is the same.

    
<P>
<H4><A NAME="3.3.4">3.3.4   Nibble_offset compression</A></H4>
<p>
    
The nibble offset algorithm is a variant on
A. P. Hammersley's byte offset algorithm.  The
major differences are that the compression modes
are &quot;sticky&quot;, the compression can be reset at
any point to allow for block parallelism, and
the basic unit of compression is the nibble,
but for very clean data, the dibit is also supported.
<p>
The data stream starts with and in general uses
a mode-setting octet presented in one if three
forms, a single dibit a0, two dibits a0, a1, or
two dibits and a nibble a0, a1, b:

    <center>
    <table border=2>
    <tr><th>a0 a1 b</th>    <th>octet</th>     <th>meaning</th></tr>
    <tr><td>00 00 0000</td> <td>0x00</td>      <td>reset to zero</td></tr>
    <tr><td>01</td>         <td>0x01</td>      <td>up 1 mode</td></tr>
    <tr><td>10</td>         <td>0x02</td>      <td>dibit mode</td></tr>
    <tr><td>11</td>         <td>0x03</td>      <td>up n modes</td></tr>
    <tr><td>00 01</td>      <td>0x04</td>      <td>nibble mode</td></tr>
    <tr><td>00 11</td>      <td>0x0C</td>      <td>6-bit mode</td></tr>
    <tr><td>00 10</td>      <td>0x08</td>      <td>byte mode</td></tr>
    <tr><td>00 00 0011</td> <td>0x30</td>      <td>12-bit word mode</td></tr>
    <tr><td>00 00 0001</td> <td>0x10</td>      <td>16-bit word mode</td></tr>
    <tr><td>00 00 0010</td> <td>0x20</td>      <td>32-bit word mode</td></tr>
    <tr><td>00 00 0100</td> <td>0x40</td>      <td>64-bit word mode</td></tr>
    <tr><td>00 00 1100</td> <td>0xC0</td>      <td>specify starting address</td></tr>
    </table>
    </center>
    <p>
    The reset to zero is followed by a new mode octet
    A reset to zero resets the prior value for delta to zero
    <p>
    The up n modes code is followed immediately
    by a dibit specifying 2 less than the number of modes
    by which to change, and then by a delta in the mode.
    <p>
    Note that up n modes has no effect until
    an actual mode has been set and can be used immediately
    after a reset to pad to nibble, octet or double-word
    boundaries.
    <p>
    Once a mode is established, it is followed by a stream
    of deltas of that size (for modes 2 or 4-64) or by one delta
    of that size and then a stream of deltas of the size that
    was in effect before an up or down giving little-endian
    offsets from the currently accumulated value.  If the
    offset is one of the following in the indicated mode
    <p>
    <center>
    <table border=2>
    <tr><td>dibit mode</td> <td>0x2</td></tr>
    <tr><td>nibble mode</td> <td>0x8</td></tr>
    <tr><td>6-bit mode</td> <td>0x20</td></tr>
    <tr><td>byte mode</td> <td>0x80</td></tr>
    <tr><td>12-bit word mode</td> <td>0x800</td></tr>
    <tr><td>16-bit word mode</td> <td>0x8000</td></tr>
    <tr><td>32-bit word mode</td> <td>0x8000 0000</td></tr>
    <tr><td>64-bit word mode</td> <td>0x8000 0000 0000 0000</td></tr>
    </table>
    </center>
    <p>
    it is followed by the new mode as 1 or 2 dibits or
    2 dibits and a nibble a1 a1 b.  If a1 is 1 or 2 or 3,
    that is the new mode.  If a1 is zero and a2 is 1 or 2
    the new mode is a2*4.  If a2 is 3 the new mode is
    a2*2.  If both a1 and a2 are zero, the new mode is
    b*16 unless b is 3.  If b is 3 the new mode is b*4
<p>
    The 0xC0 flag is followed by a second mode giving
    the number of bytes of image starting offset address
    followed by the image offset address followed by the
    mode of that data.   0xC0 also acts as a reset.
    Use of the 0xC0 flag is not required.  Addresses
    default to sequential starting from 0, but is
    provided to faciliate parallel compression.
<p>


<h4><A NAME="3.4">3.4  Access to CBFlib compressions from HDF5</A></h4>
    
Starting with CBFlib release 0.9.2.11, a plugin module in provided
to allow access to CBFlib compressions from HDF5 1.8.11 and later.
For general documentation on HDF5 dynamically loaded filters,
see
    <a href="http://www.hdfgroup.org/HDF5/doc/Advanced/DynamicallyLoadedFilters/HDF5DynamicallyLoadedFilters.pdf">
    http://www.hdfgroup.org/HDF5/doc/Advanced/DynamicallyLoadedFilters/HDF5DynamicallyLoadedFilters.pdf</a>
The discussion here will be confined to use of the CBFlib compressions
plugin.
<p>The filter has been registered with the HDF5 group as 32006, and
cbf.h includes the symbolic name for the filter CBF_H5Z_FILTER_CBF.
<p>
The source and header of the CBFlib filter plugin are cbf_hdf5_filter.c
and cbf_hdf5_filter.h.  To use the filter in C applications, you
will need to include cbf_hdf5_filter.h in the application and have the cbflib.so
library in the search path used by HDF5 1.8.11.  The HDF group says
    
<p>
<blockquote>
The default directory for an HDF5 filter plugin library is defined on
UNIX- like systems as quot;/usr/local/hdf5/lib/plugin&quot;<br />
and on Windows systems as &quot;%ALLUSERSPROFILE%/hdf5/lib/plugin&quot;.
The default path can be overwritten by a user with the HDF5_PLUGIN_PATH
environment variable.  Several directories can be specified for the search
path using &quot;:&quot; as a path separator for UNIX-like
systems and &quot;;&quot; for Windows.
</blockquote>
<p>
In the Makefile, tests are done by defining HDF5_PLUGIN_PATH to point
to the build kit shared library directory:
<p>
    HDF5_PLUGIN_PATH=$(SOLIB); export HDF5_PLUGIN_PATH;
<p>
In most cases that should be sufficient to allow code to read HDF5 files with
datasets compressed with this filter.
<p>
In order to write files that use this filter, several relevant values must
first be stored into an unsigned int array, cd_values.  The header,
cbf_hdf5_filter.h, defines the follwing symbolic values for the indices
of this array:
    
    <p>
    <center>
    <table border=2>
    <tr><th> symbol</th><th>value</th><th>meaning</th></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_NELMTS      </td><td>11</td><td>size of cd_values</td></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_COMPRESSION </td><td>0</td><td>one of the compressions (see <A HREF="#3.2.2">3.2.2</a>)</td></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_RESERVED    </td><td>1</td><td>reserved for future use, should be set to zero</td></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_BINARY_ID   </td><td>2</td><td>binary ID of the array (default 1)</td></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_ELSIZE      </td><td>3</td><td>element size in octets</td></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_ELSIGN      </td><td>4</td><td>1 if signed, 0 if unsigned</td></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_REAL        </td><td>5</td><td>1 if a real array, 0 if an integer array</td></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_DIMOVER     </td><td>6</td><td>the total number of elements in the array</td></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_DIMFAST     </td><td>7</td><td>the fast dimension</td></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_DIMMID      </td><td>8</td><td>the middle dimension</td></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_DIMSLOW     </td><td>9</td><td>the slow domension</td></tr>
    <tr><td> CBF_H5Z_FILTER_CBF_PADDING     </td><td>10</td><td>the padding</td></tr>
    </table>
    </center>
    <p>

<p>
Only chunked data may be written using this filter.  The recommended
chunk size is a single image.  The filter writes the chunks using
the imgCIF binary section format described in section <a href="#3.2.1">3.2.1</a>
including the MIME header.  If each chunk is the size of an image,
programs such as XDS can use the patterns of the MIME header to
skip directly to a frame even in a complex HDF5 file.  Typical
code to write such chunks would first define the cd_values array and an array of chunk
dimensions and create the properties to be used in creating a dataset, as in
<pre>
    unsigned int cd_values[CBF_H5Z_FILTER_CBF_NELMTS];
    hsize_t chunk[3];
    hid_t valspace;
    chunk[0] = 1;
    chunk[1] = dimmid;
    chunk[2] = dimfast;
    cd_values[CBF_H5Z_FILTER_CBF_COMPRESSION] = compression;
    cd_values[CBF_H5Z_FILTER_CBF_RESERVED]    = 0;
    cd_values[CBF_H5Z_FILTER_CBF_BINARY_ID]   = id;
    cd_values[CBF_H5Z_FILTER_CBF_PADDING]     = padding;
    cd_values[CBF_H5Z_FILTER_CBF_ELSIZE]      = (bits+7)/8;
    cd_values[CBF_H5Z_FILTER_CBF_ELSIGN]      = sign;
    cd_values[CBF_H5Z_FILTER_CBF_REAL]        = realarray;
    cd_values[CBF_H5Z_FILTER_CBF_DIMFAST]     = dimfast;
    cd_values[CBF_H5Z_FILTER_CBF_DIMMID]      = dimmid;
    cd_values[CBF_H5Z_FILTER_CBF_DIMSLOW]     = dimslow;
    valprop = H5Pcreate(H5P_DATASET_CREATE);
    H5Pset_chunk(valprop,3,chunk);
    H5Pset_filter(valprop,CBF_H5Z_FILTER_CBF,H5Z_FLAG_OPTIONAL,CBF_H5Z_FILTER_CBF_NELMTS,cd_values);
</pre>




<H4><A NAME="4.">4.  Installation</A></H4>
<p>
CBFlib should be built on a disk with at least 400 megabytes of free space.
<A HREF="../CBFlib-0.9.2.11.tar.gz">CBFlib-0.9.2.11.tar.gz</A> is a "gzipped" tar of
the code as it now stands.  Place the gzipped tar in the directory
that is intended to contain a new directory, named 
CBFlib_0.9.2.11 (the &quot;top-level&quot; directory)
and  uncompress it with gunzip and unpack it with tar:
<p>
<PRE>
     gunzip CBFlib.tar.gz
     tar xvf CBFLIB.tar
</PRE>
<p>
As with prior releases, to run the test programs, you will also need 
Paul Ellis's sample MAR345 image,
example.mar2300, and
Chris Nielsen's sample ADSC Quantum 315 image, 
mb_LP_1_001.img as sample data.  Both these files will be
extracted by the Makefile from CBFlib_0.7.7_Data_Files.  Do
not download copies into the top level directory.
<p>
After unpacking the archive, the top-level directory should contain
a makefile:
<p>
<TABLE ALIGN=CENTER>
<TR><td valign="top">&nbsp;&nbsp;Makefile<td valign="top">&nbsp;&nbsp;Makefile for unix
</TABLE>
<p>
and the subdirectories:
<p>
<TABLE ALIGN=CENTER>
<TR><td valign="top">&nbsp;&nbsp;src/<td valign="top">&nbsp;&nbsp;CBFLIB source files
<TR><td valign="top">&nbsp;&nbsp;include/<td valign="top">&nbsp;&nbsp;CBFLIB header files
<TR><td valign="top">&nbsp;&nbsp;m4/<td valign="top">&nbsp;&nbsp;CBFLIB m4 macro files (used to build .f90 files)
<TR><td valign="top">&nbsp;&nbsp;examples/<td valign="top">&nbsp;&nbsp;Example program source files
<TR><td valign="top">&nbsp;&nbsp;doc/<td valign="top">&nbsp;&nbsp;Documentation
<TR><td valign="top">&nbsp;&nbsp;lib/<td valign="top">&nbsp;&nbsp;Compiled CBFLIB library
<TR><td valign="top">&nbsp;&nbsp;bin/<td valign="top">&nbsp;&nbsp;Executable example programs
<TR><td valign="top">&nbsp;&nbsp;html_images/<td valign="top">&nbsp;&nbsp;JPEG images used in rendering the HTML files
</TABLE>
<p>
For instructions on compiling and testing the library, go to
the top-level directory and type:
<p>
<PRE>
     make
</PRE>
<p>
The CBFLIB source and header files are in the "src" and "include" subdirectories.
The FCBLIB source and m4 files are in the "src" and "m4" subdirectories.
  The files are:
<TABLE ALIGN=CENTER>
<TR><TH ALIGN=LEFT>src/<TH ALIGN=LEFT>include/<TH ALIGN=LEFT>m4/
                      <TH ALIGN=LEFT>Description
<TR><td valign="top">&nbsp;&nbsp;cbf.c<td valign="top">&nbsp;&nbsp;cbf.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;CBFLIB API functions
<TR><td valign="top">&nbsp;&nbsp;cbf_alloc.c<td valign="top">&nbsp;&nbsp;cbf_alloc.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Memory allocation functions
<TR><td valign="top">&nbsp;&nbsp;cbf_ascii.c<td valign="top">&nbsp;&nbsp;cbf_ascii.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Function for writing ASCII values
<TR><td valign="top">&nbsp;&nbsp;cbf_binary.c<td valign="top">&nbsp;&nbsp;cbf_binary.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Functions for binary values
<TR><td valign="top">&nbsp;&nbsp;cbf_byte_offset.c<td valign="top">&nbsp;&nbsp;cbf_byte_offset.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Byte-offset compression
<TR><td valign="top">&nbsp;&nbsp;cbf_canonical.c<td valign="top">&nbsp;&nbsp;cbf_canonical.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Canonical-code compression
<TR><td valign="top">&nbsp;&nbsp;cbf_codes.c<td valign="top">&nbsp;&nbsp;cbf_codes.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Encoding and message digest functions
<TR><td valign="top">&nbsp;&nbsp;cbf_compress.c<td valign="top">&nbsp;&nbsp;cbf_compress.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;General compression routines
<TR><td valign="top">&nbsp;&nbsp;cbf_context.c<td valign="top">&nbsp;&nbsp;cbf_context.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Control of temporary files
<TR><td valign="top">&nbsp;&nbsp;cbf_file.c<td valign="top">&nbsp;&nbsp;cbf_file.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;File in/out functions
<TR><td valign="top">&nbsp;&nbsp;cbf_lex.c<td valign="top">&nbsp;&nbsp;cbf_lex.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Lexical analyser
<TR><td valign="top">&nbsp;&nbsp;cbf_packed.c<td valign="top">&nbsp;&nbsp;cbf_packed.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;CCP4-style packing compression
<TR><td valign="top">&nbsp;&nbsp;cbf_predictor.c<td valign="top">&nbsp;&nbsp;cbf_predictor.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Predictor-Huffman compression (not implemented)
<TR><td valign="top">&nbsp;&nbsp;cbf_read_binary.c<td valign="top">&nbsp;&nbsp;cbf_read_binary.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Read binary headers
<TR><td valign="top">&nbsp;&nbsp;cbf_read_mime.c<td valign="top">&nbsp;&nbsp;cbf_read_mime.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Read MIME-encoded binary sections
<TR><td valign="top">&nbsp;&nbsp;cbf_simple.c<td valign="top">&nbsp;&nbsp;cbf_simple.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Higher-level CBFlib functions
<TR><td valign="top">&nbsp;&nbsp;cbf_string.c<td valign="top">&nbsp;&nbsp;cbf_string.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Case-insensitive string comparisons
<TR><td valign="top">&nbsp;&nbsp;cbf_stx.c<td valign="top">&nbsp;&nbsp;cbf_stx.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Parser (generated from cbf.stx.y)
<TR><td valign="top">&nbsp;&nbsp;cbf_tree.c<td valign="top">&nbsp;&nbsp;cbf_tree.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;CBF tree-structure functions
<TR><td valign="top">&nbsp;&nbsp;cbf_uncompressed.c<td valign="top">&nbsp;&nbsp;cbf_uncompressed.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Uncompressed binary sections
<TR><td valign="top">&nbsp;&nbsp;cbf_write.c<td valign="top">&nbsp;&nbsp;cbf_write.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Functions for writing
<TR><td valign="top">&nbsp;&nbsp;cbf_write_binary.c<td valign="top">&nbsp;&nbsp;cbf_write_binary.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Write binary sections
<TR><td valign="top">&nbsp;&nbsp;cbf.stx.y<td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">
                      <td valign="top">&nbsp;&nbsp;bison grammar to define cbf_stx.c (see WARNING)
<TR><td valign="top">&nbsp;&nbsp;md5c.c<td valign="top">&nbsp;&nbsp;md5.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;RSA message digest software from mpack
<TR><td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;global.h<td valign="top">
                      <td valign="top">&nbsp;&nbsp;&nbsp;
<TR><td valign="top">&nbsp;&nbsp;fcb_atol_wcnt.f90<td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Function to convert a string to an integer
<TR><td valign="top">&nbsp;&nbsp;fcb_ci_strncmparr.f90<td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Function to do a case-insensitive comparison of a string to
                      a byte array
<TR><td valign="top">&nbsp;&nbsp;fcb_nblen_array.f90<td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Function to determine the non-blank length of a byte array
<TR><td valign="top">&nbsp;&nbsp;fcb_read_byte.f90<td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Function to read a single byte
<TR><td valign="top">&nbsp;&nbsp;fcb_read_line.f90<td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Function to read a line into a byte array
<TR><td valign="top">&nbsp;&nbsp;fcb_skip_whitespace.f90<td valign="top">&nbsp;&nbsp;&nbsp;<td valign="top">
                      <td valign="top">&nbsp;&nbsp;Function to skip whitespace and comments in a MIME header
<TR><td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;fcb_exit_binary.m4
                      <td valign="top">&nbsp;&nbsp;Function to skip past the end of the current binary text field
<TR><td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;fcb_next_binary.m4
                      <td valign="top">&nbsp;&nbsp;Function to skip to the next binary
<TR><td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;fcb_open_cifin.m4
                      <td valign="top">&nbsp;&nbsp;Function to open a CBF file for reading
<TR><td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;fcb_packed.m4
                      <td valign="top">&nbsp;&nbsp;Functions to read a JPA CCP4 compressed image
<TR><td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;fcb_read_bits.m4
                      <td valign="top">&nbsp;&nbsp;Functions to read nay number of bits as an integer
<TR><td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;fcb_read_image.m4
                      <td valign="top">&nbsp;&nbsp;Functions to read the next image in I2, I4, 3D_I2 and 3D_I4 format
<TR><td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;fcb_read_xds_i2.m4
                      <td valign="top">&nbsp;&nbsp;Function to read a single xds image.
<TR><td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;<td valign="top">&nbsp;&nbsp;fcblib_defines.m4
                      <td valign="top">&nbsp;&nbsp;General m4 macro file for FCBLIB routines. 
</TABLE>
<p>
In the "examples" subdirectory, there are 2 additional files
used by the example programs (section 5) for reading MAR300,
MAR345 or ADSC CCD images:
<p>
<TABLE ALIGN=CENTER>
<TR><td valign="top">&nbsp;&nbsp;img.c<td valign="top">&nbsp;&nbsp;img.h<td valign="top">&nbsp;&nbsp;Simple image library
</TABLE>
<p>
and the example programs themselves:
<p>
<TABLE ALIGN=CENTER>
<TR><td valign="top">&nbsp;&nbsp;makecbf.c<td valign="top">&nbsp;&nbsp;Make a CBF file from an image
<TR><td valign="top">&nbsp;&nbsp;img2cif.c<td valign="top">&nbsp;&nbsp;Make an imgCIF or CBF from an image
<TR><td valign="top">&nbsp;&nbsp;cif2cbf.c<td valign="top">&nbsp;&nbsp;Copy a CIF/CBF to a CIF/CBF
<TR><TD valign="top">&nbsp;&nbsp;convert_image.c<td valign="top">&nbsp;&nbsp;Convert an image file to a cbf using a template file
<TR><TD valign="top">&nbsp;&nbsp;cif2c.c<td valign="top">&nbsp;&nbsp;Convert a template cbf file into a function to produce the same template in an
internal cbf data structure
<TR><TD valign="top">&nbsp;&nbsp;testcell.C<td valign="top">&nbsp;&nbsp;Exercise the cell functions
</TABLE>
<p>
as well as three template files:  template_adscquantum4_2304x2304.cbf,
template_mar345_2300x2300.cbf, and template_adscquantum315_3072x3072.cbf.
<p>Two additional examples (test_fcb_read_image.f90 and test_xds_binary.f90) are created from two files
(test_fcb_read_image.m4 and test_xds_binary.m4) in the m4 directory.
<p>
The documentation files are in the "doc" subdirectory:
<p>
<TABLE ALIGN=CENTER>
<TR><td valign="top">&nbsp;&nbsp;CBFlib.html<td valign="top">&nbsp;&nbsp;This document (HTML)
<TR><td valign="top">&nbsp;&nbsp;CBFlib.txt<td valign="top">&nbsp;&nbsp;This document (ASCII)
<TR><td valign="top">&nbsp;&nbsp;CBFlib_NOTICES.html<td valign="top">&nbsp;&nbsp;Important NOTICES -- PLEASE READ
<TR><td valign="top">&nbsp;&nbsp;CBFlib_NOTICES.txt<td valign="top">&nbsp;&nbsp;Important NOTICES -- PLEASE READ
<TR><td valign="top">&nbsp;&nbsp;gpl.txt<td valign="top">&nbsp;&nbsp;GPL -- PLEASE READ
<TR><td valign="top">&nbsp;&nbsp;lgpl.txt<td valign="top">&nbsp;&nbsp;LGPL -- PLEASE READ
<TR><td valign="top">&nbsp;&nbsp;cbf_definition_rev.txt<td valign="top">&nbsp;&nbsp;Draft CBF/ImgCIF definition (ASCII)
<TR><td valign="top">&nbsp;&nbsp;cbf_definition_rev.html<td valign="top">&nbsp;&nbsp;Draft CBF/ImgCIF definition (HTML)
<TR><td valign="top">&nbsp;&nbsp;cif_img.html<td valign="top">&nbsp;&nbsp;CBF/ImgCIF extensions dictionary (HTML)
<TR><td valign="top">&nbsp;&nbsp;cif_img.dic<td valign="top">&nbsp;&nbsp;CBF/ImgCIF extensions dictionary (ASCII)
<TR><td valign="top">&nbsp;&nbsp;ChangeLog,html<td valign="top">&nbsp;&nbsp;Summary of change history (HTML)
<TR><td valign="top">&nbsp;&nbsp;ChangeLog<td valign="top">&nbsp;&nbsp;Summary of change history (ASCII)
</TABLE>

<H4><A NAME="5.">5.  Example programs</A></H4>
<p>
The example programs makecbf.c, img2cif.c and convert_image.c read an image file
from a MAR300, MAR345 or ADSC CCD detector and then uses CBFlib to
convert it to CBF format (makecbf) or either imgCIF or CBF format (img2cif).
 makecbf writes the CBF-format image to disk, reads it in again, and
then compares it to the original.  img2cif just writes
the desired file.  makecbf works only from stated files on disk, so that
random I/O can be used.  img2cif includes code to process files
from stdin and to stdout.  convert_image reads a template as well
as the image file and produces a complete CBF.  The program
convert_minicbf reads a minimal CBF file with just and image
and some lines of text specifying the parameters of the
data collection as done at SLS and combines the result with
a template to produce a full CBF.  The program cif2cbf can 
be used to convert among carious compression and encoding
schemes.  The program sauter_test.C is a C++ test program
contributed by Nick Sauter to help in resolving a memory
leak he found.
The programs adscimg2cbf and cbf2adscimg are a &quot;jiffies&quot; contributed
by Chris Nielsen of ADSC to convert ADSC images to imgCIF/CBF format and
vice versa.
<p>
makecbf.c is a good example of how many of the CBFlib functions can be
used.
To compile makecbf and the other example programs use the Makefile in the top-level
directory:
<p>
<PRE>
     make all
</PRE>
This will place the programs in the bin directory.
<p>
<h4>makecbf</h4>
<p>
To run makecbf with the example image, type:
<p>
<PRE>
     ./bin/makecbf example.mar2300 test.cbf
</PRE>
<p>

The program img2cif has the following command line interface:
<p>

<PRE>
 img2cif     [-i  input_image]                               \
             [-o  output_cif]                                \
             [-c  {p[acked]|c[annonical]|[n[one]}]           \
             [-m  {h[eaders]|n[oheaders]}]                   \
             [-d  {d[igest]|n[odigest]}]                     \
             [-e  {b[ase64]|q[uoted-printable]|              \
                   d[ecimal]|h[exadecimal]|o[ctal]|n[one]}]  \
             [-b  {f[orward]|b[ackwards]}]                   \
             [input_image] [output_cif]

 the options are:

 -i  input_image (default: stdin)
     the input_image file in MAR300, MAR345 or ADSC CCD detector
     format is given.  If no input_image file is specified or is
     given as "-", an image is copied from stdin to a temporary file.

 -o  output_cif (default: stdout)
     the output cif (if base64 or quoted-printable encoding is used)
     or cbf (if no encoding is used).  if no output_cif is specified
     or is given as "-", the output is written to stdout

 -c  compression_scheme (packed, canonical or none, default packed)

 -m  [no]headers (default headers for cifs, noheaders for cbfs)
     selects MIME (N. Freed, N. Borenstein, RFC 2045, November 1996)
     headers within binary data value text fields.

 -d  [no]digest  (default md5 digest [R. Rivest, RFC 1321, April
     1992 using"RSA Data Security, Inc. MD5 Message-Digest
     Algorithm"] when MIME headers are selected)

 -e  encoding (base64, quoted-printable, decimal, hexadecimal,
     octal or none, default: base64) specifies one of the standard
     MIME encodings (base64 or quoted-printable) or a non-standard
     decimal, hexamdecimal or octal encoding for an ascii cif
     or "none" for a binary cbf

 -b  direction (forward or backwards, default: backwards)
     specifies the direction of mapping of bytes into words
     for decimal, hexadecimal or octal output, marked by '&gt;' for
     forward or '&lt;' for backwards as the second character of each
     line of output, and in '#' comment lines.

</PRE>
<p>
<h4>cif2cbf</h4>
<p>
The test program cif2cbf uses many of the same command line options as img2cif, but
accepts either a CIF or a CBF as input instead of an image file:
<P>
<pre>
    cif2cbf [-i input_cif] [-o output_cbf] \
      [-u update_cif] \
      [-c {p[acked]|c[annonical]|{b[yte_offset]}|\
        {v[2packed]}|{f[latpacked]}|{I|nIbble_offset}|n[one]}] \
      [-C highclipvalue] \
      [-D ] \
      [-I {0|2|4|8}] \
      [-R {0|4|8}] \
      [-L {0|4|8}] \
      [-m {h[eaders]|noh[eaders]}] \
        [-m {d[imensions]|nod[imensions}] \
      [-d {d[igest]|n[odigest]|w[arndigest]}] \
      [-B {read|liberal|noread}] [-B {write|nowrite}] \
      [-S {read|noread}] [-S {write|nowrite}] \
      [-T {read|noread}] [-T {write|nowrite}] \
      [-e {b[ase64]|q[uoted-printable]|\
        d[ecimal]|h[examdecimal|o[ctal]|n[one]}] \
      [-b {f[orward]|b[ackwards]}\
      [-p {1|2|4}\
      [-v dictionary]* [-w] [-W]\
      [-5 {r|w|rw|rn|wn|rwn|n[oH5]}\
      [-O] \
      [input_cif] [output_cbf]

  the options are:

       the options are:                                                  
                                                                         
       -i input_cif (default: stdin)                                     
         the input  file in CIF or CBF  format.  If input_cif is not     
         specified or is given as "-", it is copied from stdin to a      
         temporary file.                                                 
                                                                         
       -o output_cbf (default: stdout)                                   
         the output cif (if base64 or quoted-printable encoding is used) 
         or cbf (if no encoding is used).  if no output_cif is specified 
         or is given as "-", the output is written to stdout             
         if the output_cbf is /dev/null, no output is written.           
                                                                         
       -u update_cif (no default)                                        
         and optional second input file in CIF or CBF format containing  
         data blocks to be merged with data blocks from the primary      
         input CIF or CBF                                                
                                                                         
       The remaining options specify the characteristics of the          
       output cbf.  Most of the characteristics of the input cif are     
       derived from context, except when modified by the -B, -S, -T, -v  
       and -w flags.                                                     
                                                                         
       -b byte_order (forward or backwards, default forward (1234) on    
         little-endian machines, backwards (4321) on big-endian machines 
                                                                         
       -B [no]read or liberal (default noread)                           
         read to enable reading of DDLm style brackets                   
         liberal to accept whitespace for commas                         
                                                                         
       -B [no]write (default write)                                      
         write to enable writing of DDLm style brackets                  
                                                                         
       -c compression_scheme (Packed, Canonical, Byte_offset,            
         V2packed, Flatpacked, nIbble or None,                           
         default packed)                                                 
                                                                         
       -C highclipvalue                                                  
         specifies a double precision value to which to clip the data    
                                                                         
       -d [no]digest or warndigest  (default md5 digest [R. Rivest,      
         RFC 1321, April 1992 using"RSA Data Security, Inc. MD5          
         Message-Digest Algorithm"] when MIME headers are selected)      
                                                                         
       -D test cbf_construct_detector                                    
                                                                         
       -e encoding (base64, k, quoted-printable or none, default base64) 
         specifies one of the standard MIME encodings for an ascii cif   
         or "none" for a binary cbf                                      
                                                                         
       -I 0 or integer element size                                      
         specifies integer conversion of the data, 0 to use the input    
         number of bytes, 2, 4 or 8 for short, long or long long         
         output integers                                                 
                                                                         
       -L lowclipvalue                                                   
         specifies a double precision value to cut off the data from     
         below                                                           
                                                                         
       -m [no]headers (default headers)                                  
         selects MIME (N. Freed, N. Borenstein, RFC 2045, November 1996) 
         headers within binary data value text fields.                   
                                                                         
       -m [nod]imensions (default dimensions)                            
         selects detailed recovery of dimensions from the input CIF      
         for use in the MIME header of the output CIF                    
                                                                         
       -p K_of_padding (0, 1, 2, 4) for no padding after binary data     
         1023, 2047 or 4095 bytes of padding after binary data           
                                                                         
       -R 0 or integer element size                                      
         specifies real conversion of the data, 0 to use the input       
         number of bytes,  4 or 8 for float or double output reals       
                                                                         
       -S [no]read or (default noread)                                   
         read to enable reading of whitespace and comments               
                                                                         
       -S [no]write (default write)                                      
         write to enable writing of whitespace and comments              
                                                                         
       -T [no]read or (default noread)                                   
         read to enable reading of DDLm style triple quotes              
                                                                         
       -T [no]write (default write)                                      
         write to enable writing of DDLm style triple quotes             
                                                                         
       -v dictionary specifies a dictionary to be used to validate       
         the input cif and to apply aliases to the output cif.           
         This option may be specified multiple times, with dictionaries  
         layered in the order given.                                     
                                                                         
       -w process wide (2048 character) lines                            
                                                                         
       -W write wide (2048 character) lines                              
                                                                         
       -5 hdf5mode specifies whether to read and/or write in hdf5 mode   
          the n parameter will cause the CIF H5 datablock to be deleted  
          on both read and write, for both CIF, CBF and HDF5 files       
                                                                         
       -O when in -5 w (hdf5 write) mode, -O forces the use of opaque    
          objects for CBF binaries                                       
                                                                         
                                                                         

</pre>
<p>
<h4>convert_image</h4>
<p>
The program convert_image requires two arguments: <i>imagefile</i> and <i>cbffile</i>.
Those are the primary input and output.  The detector type is extracted from the
image file or from the command line, converted to lower case and used to construct the name of a template
cbf file to use for the copy.  The template file name is of the form
template_<i>name</i>_<i>columns</i>x<i>rows</i>.  The full set of options is:
<p>
<pre>

  convert_image [-i input_img] [-o output_cbf] [-p template_cbf]\
    [-d detector name]  -m [x|y|x=y] [-z distance]              \
    [-c category_alias=category_root]*                          \
    [-t tag_alias=tag_root]* [-F] [-R]                          \
    [input_img] [output_cbf]

  the options are:

  -i input_img (default: stdin)
    the input file as an image in smv, mar300, or mar345  format.
    If input_img is not specified or is given as "-", it is copied
    from stdin to a temporary file.

  -p template_cbf
    the template for the final cbf to be produced.  If template_cbf
    is not specified the name is constructed from the first token
    of the detector name and the image size as
       template_&lt;type&gt;_&lt;columns&gt;x&lt;rows&gt;.cbf

  -o output_cbf (default: stdout )
    the output cbf combining the image and the template.  If the
    output_cbf is not specified or is given as "-", it is written
    to stdout.

  -d detectorname
    a detector name to be used if none is provided in the image
    header.

  -F
    when writing packed compression, treat the entire image as
    one line with no averaging

  -m [x|y|x=y] (default x=y, square arrays only)
    mirror the array in the x-axis (y -&gt; -y)
                     in the y-axis (x -&gt; -x)
                  or in x=y ( x -&gt; y, y-&gt; x)

  -r n
    rotate the array n times 90 degrees counter clockwise
    x -&gt; y, y -&gt; -x for each rotation, n = 1, 2 or 3

  -R
    if setting a beam center, set reference values of
    axis settings as well as standard settings

  -z distance
    detector distance along Z-axis

  -c category_alias=category_root
  -t tag_alias=tagroot
    map the given alias to the given root, so that instead
    of outputting the alias, the root will be presented in the
    output cbf instead.  These options may be repeated as many
    times as needed.
</pre>

<p>
<h4>convert_minicbf</h4>
<p>
The program convert_minicbf requires two arguments: <i>minicbf</i> and <i>cbffile</i>.
Those are the primary input and output.  The detector type is extracted from the
image file or from the command line, converted to lower case and used to construct the name of a template
cbf file to use for the copy.  The template file name is of the form
template_<i>name</i>_<i>columns</i>x<i>rows</i>.  The full set of options is:
<p>
<pre>

  convert_minicbf [-i input_cbf] [-o output_cbf] [-p template_cbf]\
    [-q] [-C convention]                                        \
    [-d detector name]  -m [x|y|x=y] [-z distance]              \
    [-c category_alias=category_root]*                          \
    [-t tag_alias=tag_root]* [-F] [-R]                          \
    [input_cbf] [output_cbf]

  the options are:

  -i input_cbf (default: stdin)
    the input file as a CBF with at least an image.

  -p template_cbf
    the template for the final cbf to be produced.  If template_cbf
    is not specified the name is constructed from the first token
    of the detector name and the image size as
       template_&lt;type&gt;_&lt;columns&gt;x&lt;rows&gt;.cbf

  -o output_cbf (default: stdout )
    the output cbf combining the image and the template.  If the
    output_cbf is not specified or is given as "-", it is written
    to stdout.

  -q
    exit quickly with just the miniheader expanded
    after the data.  No template is used.

  -Q
    exit quickly with just the miniheader unexpanded
    before the data.  No template is used.

  -C convention
    convert the comment form of miniheader into the
        _array_data.header_convention convention
        _array_data.header_contents
    overriding any existing values

  -d detectorname
    a detector name to be used if none is provided in the image
    header.

  -F
    when writing packed compression, treat the entire image as
    one line with no averaging

  -m [x|y|x=y] (default x=y, square arrays only)
    mirror the array in the x-axis (y -&gt; -y)
                     in the y-axis (x -&gt; -x)
                  or in x=y ( x -> y, y-> x)

  -r n
    rotate the array n times 90 degrees counter clockwise
    x -> y, y -> -x for each rotation, n = 1, 2 or 3

  -R
    if setting a beam center, set reference values of
    axis settings as well as standard settings

  -z distance
    detector distance along Z-axis

  -c category_alias=category_root
  -t tag_alias=tagroot
    map the given alias to the given root, so that instead
    of outputting the alias, the root will be presented in the
    output cbf instead.  These options may be repeated as many
    times as needed.

</pre>

<P>
<h4>testreals, testflat and testflatpacked</h4>
<P>
The example programs testreals, testflat and testflatpacked exercise
the handling of reals, byte_offset compression and packed compression.
Each is run without any arguments.  testreals will read real images
from the data file testrealin.cbf and write a file with real images
in testrealout.cbf, which should be identical to testrealin.cbf.
testflat and testflatpacked read 4 1000x1000 2D images and one 50x60x70
3D image and produce an output file that should be identical to the
input.  testflat reads testflatin.cbf and produces testflatout.cbf using
CBF_BYTE_OFFSET compression. testflatpacked reads testflatpackedin.cbf
and produces testflatpackedout.cbf.  The images are:
<ul>
<li>A 1000 x 1000 array of 32-bit integers forming a flat field with all
pixels set to 1000.
<li>A 1000 x 1000 array of 16-bit integers forming a flat field with all
pixels set to 1000.
<li>A 1000 x 1000 array of 32-bit integers forming a flat field with all
pixels set to 1000, except for -3 along the main diagonal and its transpose.
<li>A 1000 x 1000 array of 16-bit integers forming a flat field with all
pixels set to 1000, except for -3 along the main diagonal and its transpose.
<li>A 50 x 60 x 70 array of 32-bit integers in a flat field of 1000, except for
     -3 along the main diagonal and the values i+j+k (counting from zero)
     every 1000th pixel
</ul>
<P>
<h4>test_fcb_read_image, test_xds_binary </h4>
<P>
The example programs test_fcb_read_image and test_xds_binary are designed
read the output of testflat and testflatpacked using the FCBlib routines
in lib/libfcb.  test_xds_binary reads only the first image and closes
the file immediately.  test_fcb_read_image reads all 5 images from the
input file.  The name of the input file should be provided on stdin,
as in:
<P>
<ul>
<li>echo testflatout.cbf | bin/test_xds_binary
<li>echo testflatpackedout.cbf | bin/test_xds_binary
<li>echo testflatout.cbf | bin/test_fcb_read_image
<li>echo testflatpackedout.cbf | bin/test_fcb_read_image
</ul>
<P>
In order to compile these programs correctly for the G95 compiler
it is important to set the record size for reading to be no larger
than the padding after binary images.  This in controlled in 
Makefile by the line

M4FLAGS = -Dfcb_bytes_in_rec=131072

which provides good performance for gfortran.  For g95, this
line must be changed to

M4FLAGS = -Dfcb_bytes_in_rec=4096
<P>
<h4>sauter_test</h4>
<P>
 The program sauter_test.C is a C++ test program
contributed by Nick Sauter to help in resolving a memory
leak he found.  The program is run as bin/sauter_test
and should run long enough to allow a check with
top to ensure that it has constant memory demands.
In addition, starting with release 0.7.8.1, the
addition of -DCBFLIB_MEM_DEBUG to the compiler
flags will cause detailed reports on memory use
to stderr to be reported.
<P>
<h4>adscimg2cbf</h4>
<P>
The example program adscimg2cbf accepts any number of raw or compressed ADSC images with
.img, .img.gz, .img.bz2 or .img.Z extensions and converts each of them to an imgCIF/CBF
file with a .cbf extension.
<p>
<pre>

  adscimg2cbf [--flag[,modifier]] file1.img ... filen.img     (creates file1.cbf ... filen.cbf)
         Image files may also be compressed (.gz, .bz2, .Z)

  Flags:
    --cbf_byte_offset   Use BYTE_OFFSET compression (DEFAULT)
    --cbf_packed        Use CCP4 packing (JPA) compression.
    --cbf_packed_v2     Use CCP4 packing version 2 (JPA) compression.
    --no_compression    No compression.

  The following two modifiers can be appended to the flags (syntax: --flag,modifier):
    flat            Flat (linear) images.
    uncorrelated    Uncorrelated sections.
</pre>
<p>
<h4>adscimg2cbf</h4>
<P>
The example program cbf2adscimg accepts any number of cbfs of ADSC images created by
adscimg1cbf or convert_image and produces raw or compressed adsc image files with
.img, .img.gz or .img.bz2 extensions.
<p>
<pre>

  cbf2adscimg [--flag] file1.cbf ... filen.cbf     (creates file1.img ... filen.img)
         Image files may be compressed on output: (.gz, .bz2) by using the flags below.\n");

  Flags:
    --gz    Output a .gz file  (e.g., filen.img.gz).
    --bz2   Output a .bz2 file (e.g., filen.img.bz2).
</pre>
<p>
<h4>tiff2cbf</h4>
<p>
The test program tiff2cbf converts a tiff data file to a cbf data file.  The program
converts the tiff data samples directly into a minicbf with the tiff header
stored at the value of _array_data.header_contents.  This conversion is
supported for the sample formats SAMPLEFORMAT_UINT (unsigned integer data),
SAMPLEFORMAT_INT (unsigned integer data), SAMPLEFORMAT_INT (signed integer data),
SAMPLEFORMAT_IEEEFP (IEEE floating point data),  SAMPLEFORMAT_COMPLEXINT
(complex signed int) and SAMPLEFORMAT_COMPLEXIEEEFP (complex ieee floating).
Conversions from these formats to other CBF formats can be handled by cif2cbf.
If you wish to convert and xxx.tif written with IEEE floating point samples
into a CBF with integer values compressed by byte-offset compression
for use by XDS, creating an xxx_view.cbf with values clipped between 0 and 100,
and an xxx_xds.cbf with unclipped values for processing:
<p>
<pre>

  tiff2cbf xxx.tif xxx.cbf
  cif2cbf -I 4 -C 100. -L 0. -e n -c b -i xxx.cbf -o xxx_view.cbf
  cif2cbf -I 4 -e n -c b -i xxx.cbf -o xxx_xds.cbf
  
</pre>
<p>
  
  <h4>minicbf2nexus</h4>
  <p>This program takes some minicbf files describing a single scan and
      axis configuration settings for them and creates a nexus file containing 
      the same data. As this is an early version of the program it lacks a lot 
of useful functionality and should not be assumed to be stable.</p>
  <p>It currently takes several command line arguments:</p>
  <ul>
  	<li>
  		<p><code>-c</code><br/>
  		<code>--compression</code><br/>
  		These are optional and take a single case-insensitive argument which describes the compression used for the
  		dataset.</p>
  		<p>Currently implemented values are:</p>
  		<ul>
  			<li><code>cbf</code><br/>Use the same CBFlib compression method as the miniCBF data uses</li>
  			<li><code>none</code><br/>Don't compress the data</li>
  			<li><code>zlib</code><br/>Use zlib compression</li>
  		</ul>
  		<p>More compression options will be added in later versions, including options for CBFlib compression
  		schemes.</p>
  	</li>
  	<li>
  		<p><code>-C</code><br/>
  		<code>--config</code><br/>
  		This takes a single argument giving the file name of a configuration file which describes how the axes of the
  		minicbf file relate to each other.</p>
  	</li>
  	<li>
  		<p><code>-g</code><br/>
  		<code>--group</code><br/>
  		This takes a string defining the name of the group where the data should be inserted. Currently, the file will
  		begin in an empty state and this will cause a group of the given name to be created, but this will eventually
  		allow data to be inserted into an existing user-defined group.</p>
  	</li>
  	<li>
  		<p><code>-o</code><br/>
  		<code>--output</code><br/>
  	  	This takes a single argument which is used as the filename for the new nexus file. Any existing files of the
  	  	same name are overwritten without warning, so be careful that the name of any existing files that you wish to
  	  	keep are not passed as an argument here.</p>
	</li>
	<li>
		<p><code>-Z</code><br/>
		<code>--register</code><br/>
		Takes a single case-insensitive argument of '<code>manual</code>' or '<code>plugin</code>' defining the method
		of plugin registration used. May be specified multiple times to define a system default (via an alias) and
		optionally over-ride it later.</p>
		</li>
	<li>
		<p>Other arguments are interpreted as file names identifying the miniCBF files to be packed into the new NeXus
		file. These must currently be pilatus v1.2 miniCBF files, but this restriction will be relaxed in later
		versions.</p>
	</li>
  </ul>
  <p>An example, from the test scripts, is:</p>
  <code>minicbf2nexus
  -c zlib
  -C config
  X4_test_1.cbf X4_test_2&amp;3.cbf X4_test_4.cbf X4_test_5.cbf
  -o minicbf.h5</code>
  <p>Where test files 1, 4 &amp; 5 are each single-image miniCBF files and test file 2 &amp; 3 is created by 'cat'ing together
  two single-image miniCBF files</p>
  
  <p>The config file used for this example is:</p>
  <pre><code><span class="comment"># some sample config settings for a miniCBF file</span>

map Start_angle to CBF_axis_omega
map Phi to CBF_axis_phi
map Kappa to CBF_axis_kappa

Sample depends-on CBF_axis_phi

CBF_axis_phi vector [1 0 0] depends-on CBF_axis_kappa
CBF_axis_kappa vector [0 1 0] depends-on .
CBF_axis_omega vector [0 0 0]
</code></pre>
	<p>Text from any <code>#</code> character to the end of the line is ignored as a comment.</p>
	<p>Axes are declared by the <code>map</code> keyword as the name of the axis in the minicbf file, which must match exactly, followed by the keyword <code>to</code> and then the name that will be given to the axis in the resulting nexus file. Each axis is treated as a rotation axis and should have a <code>vector</code> which defines the axis of rotation in the 3D coordinate frame used by nexus, this should be 3 numbers within square brackets separated by spaces and does not need to be normalised. Each axis may also depend on a nother axis by using the keyword <code>depends-on</code> folowed by the name of the nexus axis it depends on, or <code>.</code> if it does not depend on another axis, omitting a dependency as shown on the final line of the example above is not recommended as it will eventually be a fatal error. The <code>vector</code> and <code>depends-on</code> declarations do not need to be on the same line.</p>
	<p>The <code>Sample</code> keyword is used to define a dependency for the sample being scanned and should be followed by a <code>depends-on</code> declaration which defines the name of the nexus axis that the sample depends on.</p>
	<p>The final line of the config file should be blank to allow for some simple integrity tests.</p>
	<p>A continuous chain of dependencies should be formed from the sample to the nexus coordinate system, otherwise there is insufficient information available to properly describe the orientation of the sample. This will be enforced in later versions, with a fatal error if insufficient information is provided.</p>
	
	<h4>cbf2nexus</h4>
	<p>This program takes some CBF files describing a single scan and converts them to a single NeXus file containing
	the same data.  It can also be used to merge a CBF file into an existing NeXus file.</p>
	<p>It currently takes several command line arguments:</p>
  <ul>
  	<li>
  		<p><code>-c</code><br/>
  		<code>--compression</code><br/>
  		These are optional and take a single case-insensitive argument which describes the compression used for the
  		dataset.</p>
  		<p>Currently implemented values are:</p>
  		<ul>
  			<li><code>cbf</code><br/>Use the same CBFlib compression method as the miniCBF data uses</li>
  			<li><code>none</code><br/>Don't compress the data</li>
  			<li><code>zlib</code><br/>Use zlib compression</li>
  		</ul>
  		<p>More compression options will be added in later versions, including options for CBFlib compression
  		schemes.</p>
  	</li>
  	<li>
  		<p><code>-g</code><br/>
  		<code>--group</code><br/>
  		This takes a string defining the name of the group where the data should be inserted. Currently, the file will
  		begin in an empty state and this will cause a group of the given name to be created, but this will eventually
  		allow data to be inserted into an existing user-defined group.</p>
  	</li>
  	<li>
  		<p><code>-o</code><br/>
  		<code>--output</code><br/>
  	  	This takes a single argument which is used as the filename for the new nexus file. Any existing files of the
  	  	same name are overwritten without warning, so be careful that the name of any existing files that you wish to
  	  	keep are not passed as an argument here.</p>
	</li>
	<li>
		<p><code>-u</code><br/>
		<code>--update</code><br/>
		This take a single argument which is used as the filename for an existing nexus file, to which the nexus 
		translation of the input file will be added.  This is a direct change in the specified file.  It is not
		making a copy first.
	<li>
		<p><code>-Z</code><br/>
		<code>--register</code><br/>
		Takes a single case-insensitive argument of '<code>manual</code>' or '<code>plugin</code>' defining the method
		of plugin registration used. May be specified multiple times to define a system default (via an alias) and
			optionally over-ride it later. This is only relevant if the NeXus file is written with CBF compression algorithms,
			it doesn't have any effect for uncompressed data or data compressed uning HDF5's built-in compression algorithms.</p>
		</li>
	<li>
			<p><code>--datablock</code><br/>
			Gives the name of a datblock to attempt to extract data from, or may be omitted to extract data from all datablocks.</p>
	</li>
		<li>
			<p><code>--scan</code><br/>
			Gives the name of a scan to attempt to extract data from, or may be omitted if there is only one scan in the datablock(s).</p>
		</li>
		<li>
			<p><code>--experiment_id</code><br/>
			Should be a unique identifier for the scan, which will be stored in <code>/*:NXentry/entry_identifier</code>.</p>
		</li>
		<li>
			<p><code>--sample_id</code><br/>
			Should be a unique identifier for the sample, which will be stored in <code>/*:NXentry/*:NXsample/sample_identifier</code>.</p>
		</li>
		<li>
			<p><code>--list</code> &amp; <code>--no-list</code><br/>
			Determines whether the list of recognised data items is printed or not. These may be used multiple times, the last specified value is the one that is actually used.</p>
		</li>
		<li>
			<p>Other arguments are interpreted as file names identifying the CBF files to be packed into the new NeXus file.</p>
		</li>
  </ul>
	
  <p>An example, from the test scripts, is:</p>
  <code>cbf2nexus -c zlib adscconverted.cbf adscconverted.cbf -o cbf.zlib.h5</code>
  <p>This creates a single NeXus file containing two copies of the 'adscconverted' CBF file.</p>
  
	<h4>nexus2cbf</h4>
	<p>This program converts a single frame of data from a nexus file to a cbf file with a given name. The primary purpose of this program
	is to help verify that data can be recovered after being converted to NeXus format, to check that it hasn't been lost or mangled.</p>
	<p>It currently takes several command line arguments:</p>
		<ul>
		<li>
		<p><code>-f</code><br/>
		<code>--frame</code><br/>
		This should be an integer, in the range <code>[0, frameCount)</code>, defining the index of the frame that is to be extracted, and defaults to 0.</p>
		</li>
		<li>
			<p><code>-g</code><br/>
			<code>--group</code><br/>
			This takes a string defining the name of the group where the data should be inserted. Currently, the file will
			begin in an empty state and this will cause a group of the given name to be created, but this will eventually
			allow data to be inserted into an existing user-defined group.</p>
		</li>
		<li>
			<p><code>-o</code><br/>
			<code>--output</code><br/>
			This takes a single argument which is used as the filename for the new NeXus file. Any existing files of the
			same name are overwritten without warning, so be careful that the name of any existing files that you wish to
			keep are not passed as an argument here.</p>
		</li>
		<li>
			<p><code>-Z</code><br/>
			<code>--register</code><br/>
			Takes a single case-insensitive argument of '<code>manual</code>' or '<code>plugin</code>' defining the method
			of plugin registration used. May be specified multiple times to define a system default (via an alias) and
			optionally over-ride it later. This is only relevant if the NeXus file was written with CBF compression algorithms,
			it doesn't have any effect for uncompressed data or data compressed uning HDF5's built-in compression algorithms.</p>
		</li>
		<li>
			<p>The remaining argument(s) should be the file name of the NeXus file that is to be converted.</p>
		</li>
	</ul>
  
  <h4>testhdf5</h4>
  <p>This program runs a set of unit tests on the <a href="#2.6">HDF5 abstraction layer</a>. These are designed to ensure everything is working correctly, to help locate bugs and prevent regressions. A short summary will be printed detailing the number of tests passed, the number of tests failed and the number of components skipped. If any tests fail or are skipped then some additional output should be produced to help identify the cause of the error so that it is easier to fix.</p>
  <p>The program does not take any command-line arguments, and creates a file called <code>testfile.h5</code> in its working directory for use in the tests.</p>
  
  <h4>testulp</h4>
  <p>This program runs a set of unit tests on the ULP comparison functions. These are designed to ensure everything is working correctly, to help locate bugs and prevent regressions. A short summary will be printed detailing the number of tests passed, the number of tests failed and the number of components skipped. If any tests fail or are skipped then some additional output should be produced to help identify the cause of the error so that it is easier to fix.</p>
  <p>The program does not take any command-line arguments.</p>
  

  <hr />

<hr />
<hr />
Updated 22 February 2015.
Contact:
<script language="javascript" type="text/javascript">
<!--
      var name = "yaya@";
      var domain = "bernstein-plus-sons";
      var domext = ".com";
      document.write ("<a href=\"mailto:" + name + domain + domext + "\">" + name + " <b>at</b> " + domain + " <b>dot</b> "+  domext+"</a>"); 
// -->
</script>
<noscript>
yaya <b>at</b> bernstein-plus-sons <b>dot</b> com
</noscript>
</font>
</BODY>
</HTML>