HOME GUIDE OPERATIONS DOCS ERRORS FORMATS INSTALL NEW TIPS WEB SITES

DOCUMENT FILES

Document files are keyed, formatted, sequential files created by executing the SD operation and certain additional operations with register output. Document files are used to permanently store the contents of a group of registers (e.g., shift coordinates, angles, etc.) as realized in different images (specified by keys). Any subsequent SPIDER run can retrieve these register values by their keys.

Document files are also used for communication between Web and SPIDER. For example the "particle picking" operation in Web 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 batch and procedure files, or include/exclude images of a series from processing depending on the result of previous operation.

FORMAT FOR DOC FILES

123456789 123456789 123456789 123456789 123456789 1234565789 123456789 123456789 
KEY# REGS/  VALUE     VALUE       VALUE       VALUE       VALUE      VALUE
     LINE 

 ; dat/dat   18-Jul-94  AT 14:29:48   jnk000.dat
    1 2  20.000      21.000      21.000      21.000      81.000      81.000
   12 2  20.000      56.000      21.000      25.000      21.000      81.000
  102 2  20.000      16.000      33.000      21.000      61.000      81.000
 8345 2  20.000      21.000      21.000      26.000      21.000      81.000
28345 2  20.000      21.000      21.000      26.000      21.000      81.000
 ;  6 2  20.000      22.000      21.000      21.000      44.000      81.000
Lines with a ";" in the second col. are considered comment lines.

FORTRAN FORMAT: (I5,I2,6G12.3)

HEADERS FROM DOC. FILE HANDLING ROUTINES

FOR OPENING DOC FILES

C----------------------------------------------------------------------
C
C OPENDOC(DOCNAM,ADDEXT,NLET,NDOC,GETNAME,
C        ISOLDFILE,APPEND,MESSAGE,NEWFILE,IRTFLG)
C
C PURPOSE:    SUBROUTINE TO OPEN DOCUMENT FILE 
C
C PARAMETERS:     DOCNAM        NAME OF DOC FILE             SENT
C                 ADDEXT        LOGICAL FLAG TO ADD .EXT     SENT
C                 NLET          NO. OF CHAR. IN DOCNAM       RETURNED
C                 NDOC          UNIT FOR DOC FILE            SENT
C                 GETNAME       FLAG TO REQUEST NAME         SENT
C                 ISOLDFILE     FLAG THAT FILE IS EXISTING   SENT
C                 APPEND        FLAG TO OPEN FILE AS APPEND  SENT
C                 MESSAGE       FLAG TO WRITE COMMENT        SENT
C                 NEWFILE       FLAG THAT FILE WAS NEW       RETURNED
C                 IRTFLG        ERROR FLAG (0 IS NORMAL)     RETURNED
C
C----------------------------------------------------------------------

FOR FINDIND INFO FROM DOC FILES


C  DOCINFO(DOCNAM,NDOC,MAXKEYT,MAXREGT,SAYIT,IRTFLG)
C
C  PURPOSE:  DETERMINES MAXKEY AND MAXREG INSIDE A DOCUMENT FILE. 
C
C  PARAMETERS:
C         DOCNAM        DOC. FILE NAME INCLUDING EXTENSION        (SENT)
C         NDOC          LOGICAL UNIT FOR DOC FILE                 (SENT)
C         MAXKEYT       NUMBER OF HIGHEST KEY                 (RETURNED)
C         MAXREGT       MAX. NUMBER OF REGISTERS PER LINE        (RETURNED)
C                       (THIS IS 1 LESS THAN COLS. NEEDED FOR
C                       RECOVERY WITH UNSDAL, ETC.)
C         IRTFLG        ERROR FLAG (O IS NORMAL RETURN)       (RETURNED)
C     
C  TYPICAL DOC FILE LINES:
C        KEY #REGS/LINE    VALUES ........
C  COL: 123456789 123456789 123456789 123456789 123456789 1234565789
C          1 4   20.070000   17.379999   17.379999   17.379999
C        99994   20.070000   17.379999   17.379999   17.379999
C         -1 5   21.070000   12.379999   12.379999   16.379999
C        ; COMMENT LINE (PREVIOUS LINE IS A CONTINUATION FOR KEY 9999)
C
C--*********************************************************************

FOR REMOVING INFO FROM DOC FILES


C----------------------------------------------------------------------
C
C PURPOSE: RETRIEVE PARAMETERS FROM A SINGLE SPECIFED KEY FOUND IN
C          A DOC. FILE.  OPENS FILE IF NECESSARY.   
C                
C UNSAV(DOCNAM,NOPEN,NDOC,IKEY,PLIST,NLIST,LERR,NSS)
C
C PARAMETERS:
C	DOCNAM		NAME OF DOC FILE - CHAR. ARRAY           (SENT)
C	NOPEN		SWITCH =<0,  SUPRESSES ERROR MESSAGES    (SENT)
C	                SWITCH = 0,  FIRST TIME - OPEN DOC FILE
C			SWITCH = 1,  DOC FILE ALREADY OPENED
C	NDOC		LUN NUMBER FOR DOC FILE                  (SENT)
C	IKEY		KEY WANTED IN DOC FILE                   (SENT)
C	PLIST  		ARRAY OF FLOATING POINT
C                           NUMBERS RETRIEVED           (SENT/RETURNED)
C	NLIST  		NUMBER OF ELEMENTS IN ARRAY              (SENT)
C	LERR		(ON INPUT NEGATIVE LERR SUPRESSES
C                            TITLE OUTPUT)
C                       FLAG = 0, NO ERRORS IN DOC FILE
C			FLAG = 1, ERROR IN DOC FILE 
C			FLAG = 2, DOC FILE NOT FOUND   (SENT/RETURNED)
C	NSS		FLAG = 0, ALL KEYS ARE SEARCHED, DOC
C			IS REWOUND
C			FLAG = 1, SEQUENTIAL MODE; FIRST MATCHING
C			KEY IS USED, DOC IS NOT REWOUND          (SENT)
C
C----------------------------------------------------------------------
C
C  UNSDAL(DOCNAM,ICALL,NDOC,IKEY,PLIST,NLIST,DBUF,MAXKEY,MAXREG,
C          NKEY,IRTFLG)
C
C  PURPOSE:  RECOVERS ARRAY OF REGISTERS FROM DOCUMENT FILES.  IF IKEY
C            IS <0 RECOVERS THE LINE OF REGISTERS FROM THE COMMENT
C            LINE HAVING THAT COMMENT KEY ONLY. 
C
C  PARAMETERS:
C         DOCNAM        DOC. FILE NAME INCLUDING EXTENSION        (SENT)
C         ICALL         FLAG SHOWING DOC FILE IS IN DBUF NOW (SENT/RET.)                 
C                       ICALL = 1 (GET LINE FROM OPEN ARRAY)
C                       ICALL = 0 (MUST OPEN & READ FILE) 
C         NDOC          LOGICAL UNIT FOR DOC FILE                 (SENT)
C         IKEY          KEY FOR LINE OF REG. RETURNED IN PLIST    (SENT)
C         PLIST         ARRAY TO HOLD OUTPUT FROM KEY IKEY    (RETURNED)
C         NLIST         NUMBER OF REGISTERS RETRIEVED ON A        (SENT)
C                       LINE (1ST VALUE RETRIEVED ON EACH
C                       LINE IS KEY NO. NOT A REGISTER)          
C         DBUF          BUFFER TO RETRIEVE ARRAY FROM 
C                           DOC. FILE                         (RETURNED)
C         MAXKEY        NUMBER OF HIGHEST LINE THAT CAN BE        (SENT) 
C                       RETRIEVED IN ARRAY DBUF 
C         MAXREG        ONE PLUS MAX. NUMBER OF REGISTERS PER     (SENT)
C                       LINE THAT CAN BE RETRIEVED IN DBUF.             (SENT)
C         NKEY          NUMBER OF HIGHEST KEY FOUND IN FILE   (RETURNED)
C         IRTFLG        ERROR FLAG (O IS NORMAL RETURN)      (SENT/RET.)
C
C     
C  TYPICAL DOC FILE LINES:
C        KEY #REGS/LINE    VALUES ........
C  COL: 123456789 123456789 123456789 123456789 123456789 1234565789
C          1 4   20.070000   17.379999   17.379999   17.379999
C       999994   20.070000   17.379999   17.379999   17.379999
C         -1 5   21.070000   12.379999   12.379999   16.379999
C        ; COMMENT LINE (PREVIOUS LINE IS A CONTINUATION FOR KEY 99999)
C        : 1 4   20.070000   17.379999   17.379999   17.379999
C        ; COMMENT LINE (PREVIOUS LINE IS A COMMENT KEY LINE)
C
C  WHEN RETRIEVED THE LINE FOR KEY 1 IS PLACED IN LINE 1  OF DBUF AND
C  THE FIRST VALUE ON LINE ONE IS THE KEY NUMBER: 1 AND THE SECOND VALUE
C  OF LINE ONE IN DBUF IS: 20.07
C
C  THE LINE OF DBUF CORRESPONDING TO IKEY IS RETURNED IN PLIST
C  IF IKEY IS NOT FOUND AN ERROR MESSAGE IS PRINTED BUT DBUF
C  IS STILL RETURNED OK.
C
C  NOTE: AS OF 6/22/96, WE ARE ALLOWING KEYS UP TO 99999. I.E USING THE
C         FIRST COLUMN.     ML
C
C----------------------------------------------------------------------
C
C  RDDOCQ(CFUNC,NDOC,CDUM)
C
C  PURPOSE:  SUBROUTINE TO UNSAVE SPECIFIED REGISTERS, 
C            SOLICITS FILENAME
C            REGISTERS ARE SPECIFED ON COMMAND LINE.
C
C  PARAMETERS:    CFUNC   OPERATION READ INTO DRIVER           (SENT)
C                 NDOC    LUN NUMBER OF FILE                   (SENT)
C                 CDUM    UNUSED
C
C  USAGE:         UD      RETRIEVES A LINE OF REGISTERS FROM DOC FILE
C                 UD S    SEQUENTIAL RETRIEVE
C                 UD E    CLOSES THE LAST DOC. FILE OPENED WITH UD
C
C
C  CALLS          UNSAV
C
C----------------------------------------------------------------------
C
C   RDDOCA2Q(CFUNC,NALPH,NDOC,DBUF,MAXKEY,MAXREG)
C
C   PURPOSE:  THIS ROUTINE DUPLICATES FUNCTION OF RDDOCQ(UNSAVE DOCUMENT)
C             BUT IT USES IN-CORE STORAGE, WHICH MAKES SUBSEQUENT READ 
C             ACCESSES VERY QUICK.  IT SOLICITS DOC FILE NAME.  THE
C             REGISTERS ARE SPECIFED ON THE COMMAND LINE
C   
C   PARAMETERS:     CFUNC     CALLING LINE FROM DRIVER    (SENT) 
C                   NALPH     NUMBER OF LETTERS IN CFUNC  (SENT)
C                   NDOC      LUN FOR DOC FILE            (SENT)
C                   DBUF      BUFFER FOR DOC FILE DATA    (RETURNED)
C                   MAXKEY    MAX KEY THAT FITS           (SENT)
C                   MAXREG    MAX REG THAT FITS           (SENT)
C
C   USAGE:    'UD IC' --  FIRST ACCESS: READ CONTENTS OF ENTIRE DOCUMENT 
C                           INTO CORE
C             'UD IC' --  SUBSEQUENT ACCESSES: READ DIRECTLY FROM CORE
C             'UD ICE' -- TERMINATE CORE ACCESS OF CURRENT DOCUMENT
C
C   CALLS:    UNSDAL
C
C-------------------------------------------------------------------------
C
C  INTEGER FUNCTION LKUPDC(ISYMB,IBUF)
C
C  PURPOSE:   LKUPDC RETURNS AN INTEGER LOOKED UP IN DOCUMENT FILE 
C             DOCNAM.  DOCNAM IS SOLICITED IN THE INITIALIZATION CALL
C             WHICH IS: CALL LKUPDC(0,IBUF)
C             DOC FILE FORMAT:  REG 1 IS IMAGE NUMBER
C                                 REG 2 IS ASCII SYMBOL
C                                 (KEY IS MEANINGLESS)
C             NOTE: 10-SEPT-92 al.  I HAVE REWRITTEN THIS TO WORK THE
C             WAY THE DOCUMENTATION SAYS IT WILL WORK. I AM AWARE THAT
C             IT IS NOT EFFECIENT OR ELEGANT!
C
C  CALLS:     UNSDAL
C
C-------------------------------------------------------------------------
C
C
C  DOCCOM(DOCNAM,NDOC,IKEY,PLIST,NLIST,LERR)
C
C  PURPOSE:  RECOVERS LINE OF REGISTERS FROM  A COMMENT KEY LINE 
C
C  PARAMETERS:
C         DOCNAM        DOC. FILE NAME INCLUDING EXTENSION        (SENT)
C         NDOC          LOGICAL UNIT FOR DOC FILE                 (SENT)
C         IKEY          KEY FOR LINE OF REGISTERS RETURNED 
C                           IN PLIST                              (SENT)
C         PLIST         ARRAY TO HOLD OUTPUT FROM KEY IKEY    (RETURNED)
C         NLIST         NUMBER OF REGISTERS TO BE RETRIEVED 
C                       FROM THE LINE (1ST VALUE RETRIEVED ON 
C                       EACH LINE IS NOT A REGISTER)              (SENT)
C         IRTFLG        ERROR FLAG (O IS NORMAL RETURN)       (RETURNED)
C
C  TYPICAL DOC COMMENT KEY FILE LINE:
C        KEY #REGS/LINE    VALUES ........
C  COL: 123456789 123456789 123456789 123456789 123456789 1234565789
C        ; COMMENT KEY LINE FOLLOWS
C        ; 1 4   20.070000   17.379999   17.379999   17.379999
C
C
C----------------------------------------------------------------------
C

FOR PUTTING INFO INTO DOC FILES


C-------------------------------------------------------------------------
C
C
C    SAVDN1(NDOC,DOCNAM,DLIST,NLIST,NRUN,IAP)
C
C    PURPOSE:    SUBROUTINE TO SAVE PARAMETERS IN DOCUMENT FILE 
C                ALREADY OPENED, CALLED INSIDE A PROGRAM
C
C    PARAMETERS:   NDOC    LUN NUMBER OF FILE TO SAVE REGISTERS   (SENT)
C                  DOCNAM  NAME FOR DOC FILE (WITHOUT EXTENSION!) (SENT)
C                  DLIST   ARRAY CONTAINING FLOATING PT. NUMBERS  (SENT)
C                                 TO BE SAVED.
C	           NLIST   NUMBER OF ELEMENTS IN ARRAY            (SENT)
C                  NRUN    0 IF FIRST CALL (OPENS FILE), ELSE 1   (SENT)
C                  IAP     1 IF OPEN/APPEND, 0 IF OPEN/REWIND     (SENT)
C
C--------------------------------------------------------------------------
C
C  SAVD(NDOC,DLIST,NLIST,IRTFLG)
C
C  PURPOSE: SAVE PARAMETERS IN DOCUMENT FILE, CALLED INSIDE PROGRAMS, 
C           SOLICITS FILENAME & OPEN DOC FILE ON FIRST CALL
C
C  PARAMETERS:
C       NDOC     LUN NUMBER OF FILE TO SAVE REGISTERS             (SENT)
C	DLIST    ARRAY CONTAINING FLOATING PT. NUMBERS            (SENT)
C                      TO BE SAVED.
C	NLIST    NUMBER OF ELEMENTS IN ARRAY                      (SENT)
c       IRTFLG   ERROR FLAG (0 IS NORMAL)                     (RETURNED)
C
C  NOTE:         HAS SAVDC ENTRY POINT!!!!
C
C----------------------------------------------------------------------

FOR SORTING DOC FILES


C----------------------------------------------------------------------
C
C
C SORTDOC(MAXDIM)
C
C PURPOSE:              SORTS A DOC FILE,  SOLICITS DOC FILE NAME FOR
C                       INPUT AND OUTPUT
C
C PARAMETERS:           MAXDIM             UNUSED
C
C CALLS:                UNSDAL
C
C----------------------------------------------------------------------

FOR LISTING DOC FILES


C--------------------------------------------------------------------------
C
C  LISTDC(FCHAR,DOCNAM,DUM,NDOC,ISEQ)
C
C  PURPOSE:       LIST DOCUMENT FILE TO RESULTS FILE OR TERMINAL 
C                 WITH HEADINGS
C
C  PARAMETERS:    FCHAR     80 CHARACTER LINE STARTING WITH LD   (SENT)
C                 DOCNAM    DOCUMENT FILE NAME WITH EXTENSION    (SENT)
C                 DUM       UNUSED
C                 NDOC      LOGICAL UNIT NUMBER                  (SENT)
C                 ISEQ      INDICATES WHETHER THE FILE HAS 
C                           SEQUENTIAL(ISEQ=1)
C                           OR RANDOM (ISEQ=0) KEY ORDER         (SENT)
C
C  NOTE:          ALLOWABLE LENGTH OF EACH HEADING IS 8.
C
C--------------------------------------------------------------------------

Source: docfile.html     Updated: 01/15/98     ArDean Leith
© Copyright Notice /       Enquiries: spider@wadsworth.org