Documentation for DBGET4 - Fortran interface to TSP databanks by Clint Cummins, 8/2004 clint@stanford.edu http://www.tspintl.com Contents of this documentation file: A. Files for example B. Calling interfaces to subroutines C. Compiler-specific sources D. Limitations in use for supplied subroutines E. Actual file format for TSP databanks A. Files for example: dbg4.for include file listing all subroutines dbg4t.for main program for example - reads series X from DBTEST.TLB dbopnr.for opens a databank for reading dbget4.for reads one series from an open databank dbfdi.for, etc. databank subroutines used by dbget4 dbget.for, dbverp.for, dbopnc.for Lahey compiler-specific sources dbget.f77, dbverp.f77, dbopnc.f77 generic compiler sources dbg4.lnk link file for Lahey F77L-EM/32 (386LINK) dbg4.tsp create DBTEST.TLB, using TSP DBTEST.TLB databank for example. Contains series T and X. dbg4.txt this documentation file B. Calling interfaces to subroutines 1. DBOPNR - open databank for reading Before calling, choose a Fortran UNIT number for i/o, and set PUNIT to its value (in COMMON block /FILINF/ ). Example of use: CHARACTER*128 LNAME INTEGER*2 ECODE COMMON /FILINF/ PUNIT INTEGER PUNIT PUNIT = 1 LNAME='DBTEST.TLB' CALL DBOPNR(LNAME,ECODE) IF (ECODE.NE.0) THEN WRITE(*,*) ' ECODE from DBOPNR is not zero: ',ECODE ENDIF 2. DBVERG - read the databank version field from an open databank It should be equal to 2; otherwise the databank contains invalid data. This can occur if trying to read a databank created on a Mac or non-Intel unix (such as Sun) on a PC. Example of use: CALL DBVERG(POS,IVERS) IF (IVERS.NE.2) THEN WRITE(*,*) ' Incompatible databank version number: ',IVERS GOTO 900 ENDIF 3. DBOPNC - create new databank and open it for writing interface is the same as DBOPNR - see source code for DBOPNC 4. DBOPNW - open existing databank for writing interface is the same as DBOPNR - see source code for DBOPNW 5. DBGET4 - read a series (and its doc) from an open databank LENGTH - on input, contains maximum possible length of DATA vector in calling program. On output, contains actual length of DATA read (never larger than input LENGTH). DATA - values for TSP series, in single precision DOC - documentation for TSP series (if any). An integer array with 4 bytes per element. The first 8 bytes are a time stamp, like 12/25/04. Remaining bytes are documentation created with the DOC command. LDOC - on input, contains maximum possible length of DOC vector in calling program. On output, contains actual length of DOC read (never larger than input LDOC). Example of use: CNAME = 'X' LENGTH = IPDATA LDOC = IPDOC CALL DBGET4(CNAME,LENGTH,DATA, * YEAR,PERIOD,FREQ,DOC,LDOC,ECODE) IF (ECODE.NE.0) THEN WRITE(*,*) ' ECODE from DBGET4 is not zero: ',ECODE GOTO 900 ENDIF WRITE(*,100) CNAME,LENGTH,YEAR,PERIOD,FREQ,LDOC 100 FORMAT(' series=[',A,'], length=',I6,' starting ',I4,':',I2, * ' freq=',I2,' length of Doc=',I4) IF (LDOC.NE.0) WRITE(*,101) (DOC(I),I=1,LDOC) 101 FORMAT(1X,16A4) WRITE(*,*) ' data=',(DATA(I),I=1,LENGTH) 6. DBPUT4 - write a series (and its doc) to an open databank interface is the same as DBGET4 C. Compiler-specific sources The files: dbget.for, dbverp.for, dbopnc.for are compiler-specific. Why? TSP databanks are direct access files with a record length of 256 bytes. In early versions of the Lahey Fortran compiler, a "header record" (which contained the record length) was written before RECORD number 1. Other compilers, such as Watcom and later Lahey compilers (unless special compiler options are used), will read this header record instead of the first data record when RECORD=1. So, for these later compilers, we have to create a blank first record, and then read or write to physical record "n+1" when accessing databank record "n". The files supplied for this example are for Lahey compilers with compiler options set to create the "header record". To use other compilers, or Lahey without this option, use the files: dbget.f77, dbverp.f77, dbopnc.f77 D. Limitations in use for supplied subroutines TSP databanks may contain a wide variety of TSP variables, such as series, matrices, and equations. The subroutines DBGET4 and DBPUT4 will only read the most common type of TSP variable, a single precision series (type 3), with its imbedded frequency, starting date/period, and any included documentation. These subroutines also cannot handle variable names longer than 8 bytes. For reference, here is a list of types of variables which might appear in a TSP databank, but cannot be read by DBGET4: Type Description 1 scalar (CONST) or vector [double precision] 2 double precision series (8 bytes per number) 4 scalar (PARAM) [double precision] 6 equation (FRML) 7 identity (IDENT) 8 model (list of equations and endogenous variables - MODEL) 10 .LNGTAB - list of variable names longer than 8 bytes 11 general matrix [double precision] 12 symmetric matrix [double precision] 13 upper triangular matrix [double precision] 14 diagonal matrix [double precision] Most of these are actually fairly easy to read, except equations and models. E. Actual file format for TSP databanks TSP databanks are direct access files with a record length of 256 bytes. As mentioned in section (C.) above, the first such record on a PC is blank. The first usable record is always a "directory" record. It contains variable names, along with their lengths, types, and locations. It also contains a pointer to the next directory record (if any). The second usable record is always a "data" record. It contains data for the variable(s) in the first directory record. Later records are either directory or data records. The minimum number of physical records in a PC databank is therefore 3, or 768 bytes.