Document Files

Document files are keyed, formatted, sequential files created by the command line operations: SD, DOC CREATE, DOC SORT, DOC MERGE, DOC SUBTRACT, DOC MIRROR, SD SHUFFLE, and certain additional operations. Document files are used to permanently store information such as the contents of a group of SPIDER registers like, image numbers, angles, or any other such numerical listing. Each listing is identified by a key number. Any subsequent SPIDER run can retrieve the register values, etc., by their keys.

Document files are also used for communication between Web and SPIDER. For example the "particle picking" operation in creates a set of document files used by certain operations in SPIDER.

Document files may also be used to define a processing protocol; switch on and off the execution of procedure files, or include/exclude images of a series from processing depending on the result of previous operation.

FORMAT FOR DOC FILES

The current which was introduced in SPIDER 11.0 (Feb 2004) has variable length columns with each column separated by at least one blank. (Previously under some circumstances columns could exist without any interspersed blank). The implementation will successfully read all existing older document files and will support keys > 999999 and more than 9 register columns. The current format is also easy to parse outside of SPIDER.

Lines with a ";" in the second column are considered comments or 'comment key' lines.

A sample document file follows:

 KEY#  REGS/  VALUE      VALUE      VALUE      VALUE      VALUE      VALUE  ... (no set limit)
       LINE
---------------------------------------------------------------------------------
 ;tst/tst   16-JUN-1999 AT 13:03:18   jnkdoc001.tst
    9 1  11.000    
   99 2  11.000      12.000    
  999 3  11.000      12.000      13.000    
 9999 4  11.000      12.000      13.000      14.000    
99999 5  11.000      12.000      13.000      14.000      15.000    
999999 6  11.000      12.000      13.000      14.000      15.000      16.000    
 ; /COMMENT KEY -88 CONTAINS -88                                                 
 ;-88 2 -88.000     -88.000    
 ;  KEY 5556 HAS 7 REGISTERS
 5556 7  5554.0      6.0000      13.000      14.000      15.000      16.000      16.000    
 ;  KEY 987654 HAS 11 REGISTERS
   987654 11    11.0 12.0 13.000  14.000 15.000 16.000 17.000 -1.76E-13 -19.0 10.0E2 21.2   

---------------------------------------------------------------------------------

Data columns (registers) are usually written into the new format using Fortran format specification 1PGE12.5 so there are 6 decimal places worth of precision in each value which is written by SPIDER.

The pre SPIDER 11.0 format was as follows:

123456789 123456789 123456789 123456789 123456789 1234565789 123456789 123456789

 KEY# REGS/  VALUE      VALUE      VALUE      VALUE      VALUE      VALUE (limit is 9)
     LINE
---------------------------------------------------------------------------------
 ;tst/tst   16-JUN-1999 AT 13:03:18   jnkdoc001.tst
    9 1  11.000    
   99 2  11.000      12.000    
  999 3  11.000      12.000      13.000    
 9999 4  11.000      12.000      13.000      14.000    
99999 5  11.000      12.000      13.000      14.000      15.000    
9999996  11.000      12.000      13.000      14.000      15.000      16.000    
 ; /COMMENT KEY -88 CONTAINS -88                                                 
 ;-88 2 -88.000     -88.000    
 ;  KEY 5556 HAS 7 REGISTERS
 5556 7  5554.0      6.0000      13.000      14.000      15.000      16.000      16.000    

---------------------------------------------------------------------------------

DATA IS WRITTEN WITH FORTRAN FORMAT: (I6,I1,9G12.3)

DOC. FILE HANDLING ROUTINES

OPENING DOC FILES
opendoc.f

Opens doc file
FOR FINDING INFO FROM DOC FILES
lundoc.f

Handles most lower level document file I/O.

listdc.f

List document file to results file or terminal with headings
FOR COMMAND LINE OPERATIONS THAT REMOVE INFO FROM DOC FILES
rddocq.f

Supports operation to retrieve a line of registers from doc. file. Can set these values in registers given on command line.

rddocn.f

Finds number of columns and keys in doc a file. Can set these values in registers given on command line.
FOR COMMAND LINE OPERATIONS THAT PLACE INFO INTO DOC FILES
savdocq.f

Save particular registers in a document file. Called from command line.
SUPPORT SUBROUTINES FOR REMOVING INFO FROM DOC FILES
unsdal.f

Recovers array of registers from document files. Leaves doc. file contents in memory.

getdocdat.f

Allocate memory to store doc file and retrieve all of doc. file contents.

unsav.f

Retrieve parameters from a single specifed key found in a doc. file. Opens file if necessary.
SUPPORT SUBROUTINES FOR PUTTING INFO INTO DOC FILES
savd.f

Save parameters in document file, called inside a program, solicits filename & open doc file on first call. If file exists it will open for append, not replace.

savdn1.f

Save parameters in document file which may be already opened (called inside a program)
FOR SORTING, MERGING, OR SUBTRACTING DOC. FILES
docs1.f

Create, sort, merge, 'subtract' document files.

shuffledoc.f

Shuffle contents of a document file.

SUPPORT ROUTINES IN: lundoc.f
lundocgetcom

Read a specifed comment key from a doc file.

lundocsayhdr

Echo first header line from a doc file.

lundocreddat

Read a specifed key of a doc file.

lundocrednxt

Read the next key of a doc file.

lundocwrtdat

Write a specifed key of a doc file.

lundocinfo

Determine maxkey and maxreg inside a document file.

lundocparse

Parse "4,[v1],[v2],[v3]" syntax line where values after the first are all references to register variables.

Source: docfile.html Page updated: 02/9/05 ArDean Leith

Document Files

FORMAT FOR DOC FILES

DOC. FILE HANDLING ROUTINES

OPENING DOC FILES

FOR FINDING INFO FROM DOC FILES

FOR COMMAND LINE OPERATIONS THAT REMOVE INFO FROM DOC FILES

FOR COMMAND LINE OPERATIONS THAT PLACE INFO INTO DOC FILES

SUPPORT SUBROUTINES FOR REMOVING INFO FROM DOC FILES

SUPPORT SUBROUTINES FOR PUTTING INFO INTO DOC FILES

FOR SORTING, MERGING, OR SUBTRACTING DOC. FILES

SUPPORT ROUTINES IN: lundoc.f