Tables for
Volume G
Definition and exchange of crystallographic data
Edited by S. R. Hall and B. McMahon

International Tables for Crystallography (2006). Vol. G, ch. 5.4, p. 526

Section 5.4.2. An overview of the library

H. J. Bernsteina* and S. R. Hallb

aDepartment of Mathematics and Computer Science, Kramer Science Center, Dowling College, Idle Hour Blvd, Oakdale, NY 11769, USA, and bSchool of Biomedical and Chemical Sciences, University of Western Australia, Crawley, Perth, WA 6009, Australia
Correspondence e-mail:

5.4.2. An overview of the library

| top | pdf |

The CIFtbx library is made up of functions, subroutines and variables that can be added to application programs as `commands' to read and write CIF data. They may also be used to automatically validate incoming and outgoing CIF data. The self-checking aspects of some functions ensure that data are syntactically correct and, when used with DDL dictionaries, that individual items conform to their formal definitions.

The CIFtbx commands are invoked in user software as standard Fortran function or subroutine calls. For example, to open the dictionary file `core.dic' one uses the logical function dict_ as follows. [Scheme scheme1] The argument 'core.dic' is the local file identifier for the relevant dictionary. The argument 'valid' signals that checking should be done against the data definitions in this dictionary. The local logical variable FN is returned as .true. if dict_ opens the file core.dic correctly; otherwise the function is returned as .false..

Some CIFtbx commands are issued as subroutine calls. For example, to clear the internal data tables the programmer inserts the command [Scheme scheme2]

The arguments in CIFtbx commands have been kept to a minimum. Most of the parameter setting is handled automatically by reading and setting variables held in common blocks supplied as the file ciftbx.cmn. The type declarations for all the commands are also provided in the file ciftbx.cmn, and the programmer must ` include' this file in each application program, function or subroutine invoking CIFtbx commands.

The flexibility of the CIF syntax can present some challenges to an author of applications reading or writing CIF data. This is because the information in a CIF may be in any order, have data names as either upper or lower case, and have an arbitrary spacing between data items. For example, one may extract the cell parameters from the front of a CIF and place them at the end, change all the data names from lower case to upper case, and introduce a blank line between each data name and its value, and yet the data (value) content of the output CIF will be identical to that input. CIFtbx provides the application writer with the tools to handle such presentation details seamlessly without altering the basic information content.

Most importantly, CIFtbx allows applications to be `object-oriented', in that data items are simply requested by name without prior knowledge of the file structure. It also allows for more advanced data processing in which data items are parsed sequentially, and typed and validated via the dictionary. This enables items to be read independently of the names, and the data typing is automatically determined and returned. In this way, where needed, applications can go beyond the position-independent context of a CIF.

The main purpose of CIFtbx is to manipulate CIF data. However, there is much in common between CIF and the Extensible Markup Language XML (Bray et al., 1998[link]), and facilities have been added to CIFtbx to facilitate writing output in XML as well as CIF format.

CIFtbx provides four basic kinds of facilities for programmers:

(i) commands to initialize later handling;

(ii) commands to read CIF data;

(iii) commands to write CIF data;

(iv) variables for monitor and control signals.

These commands are described in detail below.


Bray, T., Paoli, J. & Sperberg-McQueen, C. M. (1998). Extensible Markup Language (XML). W3C recommendation 10-February-1998. .

to end of page
to top of page