Section 5.4.9. How to read CIF data

The CIFtbx approach to reading CIF data is illustrated using a simple example program CIF_IN (Fig. 5.4.9.1), which reads the file test.cif (Fig. 5.4.9.2) and tests the input data items against the dictionary file cif_core.dic. The resulting output is shown in Fig. 5.4.9.3.

Figure 5.4.9.1 | top | pdf | Sample program CIF_IN. See text for explanation.

Figure 5.4.9.2 | top | pdf | Example CIF read by the sample program CIF_IN shown in Fig. 5.4.9.1.

Figure 5.4.9.3 | top | pdf | Printout from the example program CIF_IN run on the test file of Fig. 5.4.9.2.

The program CIF_IN may be divided into the following steps, each tagged with the relevant reference letter in the comment records of the listing shown in Fig. 5.4.9.1.

A : Define the local variables. The CIFtbx variables are added with the line include 'ciftbx.cmn'.

B : Assign device numbers to the files using the command init_. The device number 1 refers to the input CIF, 3 to the scratch file and 6 (stdout) to the error-message files. The device number 2 refers to an output CIF, if we were to choose to write one.

C : Open a specific dictionary file named cif_core.dic with the command dict_. The code valid signals that the input data items are to be validated against the dictionary. In this application, dict_ is invoked in an IF statement that tests whether the command is successful.

D : Open the CIF test.cif with the command ocif_ and test that the file is opened.

E : Invoke the data_ command, containing a blank block code, to `open' the next data block. The block name encountered is placed in the variable bloc_, which in this application is printed.

F : Read the cell-length values and their standard uncertainties with the numb_ command, and print these out. Test whether all of the requested data items are found.

G : The char_ function is used to read a single character string.

H : The name_ function is used to get the data name of the next data item encountered.

I : This sequence illustrates how text lines are read. The char_ function is used to read each line and the text_ variable is tested to see whether another text line exists in this data item.

J : This sequence illustrates how a looped list of items is read. Individual items are read using char_ or numb_ functions and the existence of another packet of items is tested with the variable loop_.

The resulting printout is shown in Fig. 5.4.9.3. In this figure, note the following:

(i) The first six lines of the printout are output by CIFtbx routines, not by the program CIF_IN. They occur when the data_ command is executed and data items in the block mumbo_jumbo are read from the CIF and checked against the dictionary file. Note that this is when the CIFtbx routines store the pointers and attributes of all items in the data block. All subsequent commands use these pointers to access the data.

(ii) The `####' string in front of _cell_length_a in the input CIF makes this line a comment and makes it inaccessible to CIF_IN.

(iii) Data items may be read from a CIF in any order but looped items must normally be in the same list. If one needs to access looped items in different lists simultaneously, the bkmrk_ command is used to preserve CIFtbx loop pointers.