Instructions for using CifSieve ------------------------------- These instructions are for operating CifSieve; for installation instructions, see file INSTALLATION in this directory. INDEX: 1. Outline 2. Making the cifsiv_ function 3. Using the cifsiv_ function 4. Notes for Fortran programmers 5. Problems ===================================================================== 1. Outline ---------- CifSieve is intended for programmers who do not particularly want to spend a lot of time writing input statements for every Cif item they need. CifSieve automates the process of matching Cif items to program variable names, thereby freeing up programmer time for more worthwhile pursuits. A function, cifsiv_, is generated and compiled. When called, this function writes the values of a series of Cif items into programmer -- specified variable names. 2. Making the cifsiv_ function ------------------------------ The variable name --- CIF item name matchup is done by editing the DDL file where the CIF item name is defined. Two DDL file types are currently extant: DDL1 and DDL2. DDL1 is by far the simpler and is the original format of the CIF core dictionary. DDL2 is more complex and is the format of the macromolecular CIF dictionary. Either format is supported. Steps: 1. Copy the master DDL file from somewhere. This copy is called 'your DDL file' in the following instructions. It is also possible to create one from scratch. The DDL file reader is forgiving and the format is pretty obvious. Something like the following is OK for DDL1: data_anything _item_name _my_cif_item_name _variable_name myvariablename[10000] _item_type numb data_something _item_name _etc_etc_etc _variable_name junko _item_type char Underscores at the beginning of item names and attributes are vital for correct syntax and the parser will fail if they are not present. 2. Edit your DDL file, inserting the attribute _variable_name followed by the name of the variable you wish to hold the value of this CIF item. See above for an example. Do not put _variable_name inside loops. If an _item_name occurs in a loop, the variable name you specify will be dimensioned as an array with each element referring to the respective member of the loop. 3. Save your edited DDL file. 4. Run BuildSiv by typing 'BuildSiv ' eg 'BuildSiv smallmm_cif 2'. If option '-e' is given before , variable definitions and read capability for esds will be included as well. The variable name will simply be the name given by the programmer plus 'esd' at the end. 5. An object file, cifsiv.o, is produced together with a header file cifvars.h and some source code files which may be deleted. 3. Using the cifsiv_ function ------------------------------ The generated object file should be linked together with any other object files in your program. It should *not* be linked with the 'flex' library as it does not use any of those functions. In fact, linking with this library may cause problems, as this library provides a 'main' program which may conflict with the user's 'main' program.. The cifsiv_ function is called as follows: cifsiv_(char* filename, char* blockname), where filename refers to the CIF file to be input and blockname refers to the data block within that file. The 'cifvars.h' file should be #included in any source code files which wish to access the values of the variables containing the CIF data. Errors in reading the CIF can be checked by monitoring the value of 'errornum', which should be set to zero before calling cifsiv. If 'errornum' is non--zero, variable 'errormes' will contain an error message indicating the reason for the problem. Note that cifsiv tries to recover from an error, and at worst will only discard the particular loop block or data item affected. 4. Notes for Fortran Programmers --------------------------------- Fortran programmers should include the option '-f' before in Step 4 above. A Fortran header file, forcif.inc, will be output and can be included or pasted into any fortran subroutine which wishes to access the values read in from the CIF. The user--defined variables are defined as common block elements in this include file. Function cifsiv_ is called without the underscore and with three arguments: CALL CIFSIV(, , BLOCKBEG), where the first two arguments are the same as for the C function, and the third argument is the name of the first variable in the Fortran common block (always called "BLOCKBEG" in the current implementation). The cifsiv_ function thus generated is also C--callable, at the expense of more typing in order to access the variable name. As the variable names are now elements of a structure, for which only the address is available, they should be accessed using the -> operator. Examination of the cifvars.h file generated by the -f option shows that the correct access method is as follows: no -f option -f option Variable name: mylabel cifcmnptr->mylabel Note also that no underscore is appended when calling from Fortran, but is used when calling from C. If you are not using the gcc/g77 combination, check your compiler to make sure this is default behaviour. 5. Problems ----------- See the points mentioned in file 'INSTALLATION' concerning compatibility of flex and lex and bison and yacc. If a syntax error is detected when reading your edited DDL file, check file 'ddlout' to see at what point it occured. If it is after your definitions have been output, you can just delete the rest of the DDL file and try again. Note that macromolecular dictionary version 0.9.01 contains a syntax error in definition __refine.ls_weighting_scheme, where the string " 'based on measured e.s.d.'s' " occurs. The second apostrophe closes the string, making the character 's' a syntax error. Error messages from the DDL parsers are at present extremely uninformative. This will be rectified in the next release.