CIFLIB [11, 12] is a software library that was developed to provide an application interface to information in CIF format.
The entity relationship diagram of the CIFLIB class library in Figure 2 illustrates that CIFLIB follows the essentially relational organization used in the mmCIF dictionary. CIFLIB provides functions which perform the following types of operations:
Figure 2:
Abbreviated extended entity relationship diagram of the CIFLIB class library.
Figure 3:
Functional diagram of CIFLIB illustrating the intended use of the library
in supporting CIF access for a variety of application program types.
Figure 3 shows how this software library facilitates integrating the CIF interchange format with other applications. As the figure illustrates, CIFLIB provides complete access to the DDL, CIF dictionaries and CIF data files. This library can be used to build wrappers and filters around existing applications which need to access CIF data. Since CIFLIB provides complete access to the dictionary data model, the library can be conveniently used as an in-memory database or as a loader for an external database.
Accessing data in CIF format using CIFLIB is a multistep process. CIFLIB first reads the DDL dictionary. Once the DDL is loaded and checked against internally coded rules based on DDL 2.1, a CIF dictionary which is based on this DDL is read and checked. This process can be quite time consuming for large dictionaries, so a provision has been made to retain the state of any file which has been checked in an auxiliary file. This auxiliary file will be used in preference to the original file in subsequent file accesses if its modification date is more recent. Finally, CIF data files are read and checked with respect to the CIF dictionary. In any file access, CIFLIB provides complete access to the data blocks containing the DDL, the CIF dictionary, and any number of blocks containing user data.
Each CIF file may be divided into data block sections. CIFLIB treats each data block as an independent database loaded into the data model defined in its associated dictionary. The CIF DDL is at the top of the chain and provides the data model for a CIF dictionary. The CIF dictionary in turn provides the data model for CIF data files. CIFLIB provides functions to read, write and merge data blocks. Any number of data blocks can be managed by the library.
Within each individual data block, category groups provide a mechanism for organizing categories into conceptually meaningful collections. CIFLIB provides functions to obtain the list of category groups defined within a data block as well as the names of the member categories of each group.
The library provides a set of functions for accessing category level features within a data block. These functions provide a complete list of the categories specified within a data block, the list of data items specified within each category, and the number of rows of data in a category. The attributes of a category defined in the CIF dictionary such as the category description, category examples, member data items, key data items, and member subcategories can also be obtained.
Functions are provided to read, write and update individual data items, rows of data items, and columns of data items. These functions also check the integrity of item values with respect the their dictionary definitions. Access to all of the item attributes defined in the CIF dictionary is provided, and convenience functions are provided for the most commonly used attributes such as alias names, data type, default value, and enumeration.
CIFLIB provides a set of functions which give information about parent/child relationships, and provide access to the parent and child item values. The parent and child relationships returned by the functions in this section span a single generation; however, complicated hierarchies of parentage can be easily traced.
Although the extended DDL uses different conventions for naming data, it provides a mechanism to reference alternative data names. The mmCIF dictionary uses this feature to show the correspondence between the mmCIF data items and the existing core CIF data items. Because the mmCIF dictionary incorporates all of the definitions in the core CIF dictionary, it is possible for software developed for the extended DDL to use the mmCIF dictionary to read, write and check data items derived from either dictionary.