International
Tables for
Crystallography
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, pp. 528-529

Section 5.4.6. Variables

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:  yaya@bernstein-plus-sons.com

5.4.6. Variables

| top | pdf |

The CIFtbx library also contains a large number of variables declared in the common blocks in the file ciftbx.cmn that provide signals to the programmer on various aspects of the data reading and writing processes. These variables are described below in four broad categories, as shown in Table 5.4.6.1[link]: general monitor variables, general control variables, input monitor variables and output control variables.

Table 5.4.6.1| top | pdf |
CIFtbx variables

General monitorGeneral controlInput monitorOutput control
  alias_   aliaso_
      align_
  append_    
    bloc_  
    decp_ pdecp_
    diccat_  
    dicname_  
    dictype_  
    dicver_  
      esdlim_
file_      
    glob_ globo_
  line_    
    list_  
    long_  
longf_      
    loop_  
    lzero_ plzero_
  nblank_   nblanko_
    posdec_ pposdec_
    posend_ pposend_
    posnam_ pposnam_
    posval_ pposval_
precn_      
    quote_ pquote_
  recbeg_    
  recend_    
recn_      
    save_ saveo_
    strg_  
      tabl_
  tabx_   ptabx_
    tagname_  
tbxver_      
    text_  
    type_  
      xmlout_
      xmlong_

Note that for all but special applications only the basic variables list_, loop_, strg_, text_ and type_ are usually used. These variables supplement the argument lists of the various commands, providing essential status information.

5.4.6.1. General monitor variables

| top | pdf |

These variables are returned by CIFtbx and provide information about the general status of processing.

file_: character string containing the file name of the current input file.

longf_: integer variable containing the length of the file name in file.

precn_: integer variable containing the line number (starting from 1) of the last line written to the output CIF.

recn_: integer variable containing the line number (starting from 1) of the last line read from the input CIF.

tbxver_: character*32 variable that is the CIFtbx version and date in the form 'CIFtbx version N.N.N DD MMM YYYY ' (some older versions of CIFtbx use a two-digit year and have a comma after the version number).

5.4.6.2. General control variables

| top | pdf |

These variables control CIFtbx commands. The user may accept the default values or may store new values into these variables to change the behaviour of the commands.

alias_: logical variable to control the use of data-name aliases for input items. If set to .true., aliases from the input dictionary may be used (see Section 5.4.7[link]). The default is .true..

append_: logical variable to control reuse of the direct-access file. If set to .true., it will cause each call to ocif_ to append the information found to the current CIF. The default is .false..

line_: integer variable to set the input/output line limit for processing a CIF. The default value is 80 characters. This limit counts the visible printable characters of the line, not the system-dependent line terminators.

nblank_: logical variable to control the treatment of input blank strings. If set to .true., char_ or test_, it will return the type as `null' rather than `char' when encountering a quoted blank.

recbeg_: integer variable to give the record number of the first record to be used. May be changed by the user to restrict access to a CIF.

recend_: integer variable to give the record number of the last record to be used. May be changed by the user to restrict access to a CIF.

tabx_: logical variable is set to .true. for tab stops to be expanded to blanks during the reading of a CIF. The default is .true..

5.4.6.3. Input monitor variables

| top | pdf |

These variables are returned by CIFtbx tools and are used to decide on subsequent actions in the program. The lengths of the character strings that hold data names and block names are controlled by the parameter NUMCHAR in the common-block declarations.

bloc_: character string containing the current data-block name.

decp_: logical variable is .true. if a decimal point is present in the input numeric value.

diccat_: character string containing the category name specified in the attached dictionaries.

dicname_: character string containing the root alias data name (see Section 5.4.7[link]) specified in the attached dictionaries or, after a call to dict_, the name of the dictionary.

dictype_: character string containing the data-type code specified in the attached dictionaries. These types may be more specific (e.g. `float' or `int') than the types given by the variable type_ (e.g. `numb').

dicver_: character string containing the version of a dictionary after a call to dict_.

glob_: logical variable is .true. if the current data block is a global block. The application is responsible for managing the relationship of global data to other data blocks.

list_: integer variable containing the sequence number of the current looped list. This value may be used by the application to identify variables that are in different lists or that are not in a list (a zero value).

long_: integer variable containing the length of the data string in strg_.

loop_: logical variable is .true. if another loop packet is present in the current looped list.

lzero_: logical variable is .true. if the input numeric value is of the form [sign]0.nnnn rather than [sign].nnnn.

posdec_: integer variable containing the column number (position along the line, counting from 1 at the left) of the decimal point for the last number read.

posend_: integer variable containing the column number (position along the line, counting from 1 at the left) of the last character for the last string or number read.

posnam_: integer variable containing the starting column (position along the line, counting from 1 at the left) of the last name or comment read.

posval_: integer variable containing the starting column (position along the line, counting from 1 at the left) of the last data value read.

quote_: character variable giving the quotation symbol found delimiting the last string read.

save_: logical variable is .true. if the current data block is a save frame, otherwise .false..

strg_: character variable containing the data name or string representing the data value last retrieved.

tagname_: character variable containing the data name of the current data item as it was found in the CIF. May differ from dicname_ because of aliasing.

text_: logical variable is .true. if another text line is present in the current input text block.

type_: character variable containing the data-type code of the current input data item. This will be one of the four-character strings `null' (for missing data, the period or the question mark), `numb' (for numeric data), `char' (for most character data) or `text' (for semicolon-delimited multi-line character data). For most purposes the type `text' is a subtype of the type `char', not a distinct data type. CIFtbx permits multi-line text fields to be used whenever character strings are expected.

5.4.6.4. Output control variables

| top | pdf |

These variables are specified to control the processing by CIFtbx commands that write CIFs.

aliaso_: logical variable to control the use of data-name aliases for output items. If set to .true., preferred synonyms from the input dictionary may be output (see Section 5.4.7[link]). The default is .false..

align_: logical variable to control the column alignment of data values in loop_ lists output to a CIF. The default is .true..

esdlim_: integer variable to set the upper limit of appended standard uncertainty (e.s.d.) integers output by pnumb_. The default value is 19, which limits standard uncertainties to the range 2–19.

globo_: logical variable which if set to .true. will cause the output data block from pdata_ to be written as a global block.

nblanko_: logical variable controls the treatment of output blank strings. If set to .true., output quoted blank strings will be converted to an unquoted period (i.e. to a data item of type null). Recall that CIFtbx treats an unquoted period or question mark as being of type null.

pdecp_: logical variable controls the treatment of output decimal numbers. If set to .true., a decimal point will be inserted into numbers output by pnumb_ or pnumbd_. If set to .false., a decimal point will be output only when needed. The default is .false..

plzero_: logical variable controls the treatment of leading zeros in output decimal numbers. If set to .true., a zero will be inserted before a leading decimal point. The default is .false..

pposdec_: integer variable to set the column number (position along the line, counting from 1 at the left) of the decimal point for the next number to be output.

pposend_: integer variable to set the position of the ending column for the next number or character string to be output. Used to pad with zeros or blanks.

pposnam_: integer variable to set the starting column of the next name or comment to be output.

pposval_: integer variable to set the position of the starting column of the next data value to be output.

pquote_: character variable containing the quotation symbol to be used for the next string written.

saveo_: logical variable is set to .true. for pdata_ to output a save frame, otherwise a data block is output.

ptabx_: logical variable is set to .true. for tab stops to be expanded to blanks during the creation of a CIF. The default is .true..

tabl_: logical variable is set to .true. for tab stops to be used in the alignment of output data. The default is .true..

xmlout_: logical variable is set to .true. to change the output style to XML conventions. Note that this is not a CML (Murray-Rust & Rzepa, 1999[link]) output, but a literal translation from the input CIF. The default is .false..

xmlong_: logical variable is set to .true. to change the style of XML output if xmlout_ is .true.. When .true. (the default), XML tag names are the full CIF tag names with the leading underscore, _, removed. When .false., an attempt is made to strip the leading category name as well.

References

Murray-Rust, P. & Rzepa, H. (1999). Chemical markup, XML and the Worldwide Web. 1. Basic principles. J. Chem. Inf. Comput. Sci. 39, 928–942.








































to end of page
to top of page