libtblf(3F) Fortran Library Routines libtblf(3F) NAME topenr, tgettyp, tblread, tgetc, tgetd, tgeti, tgetr, tindp, tpinfo,isblank, itstat, tshcase, ntkey, tgetkc, tgetki, tgetkr, tindk, ikname, tfiltyp, topenw, tsetc, tsetd, tseti, tsetr, tlink, tdelp ,tnewp,tsetk, tblwrit, tcls SYNOPSIS subroutine topenr(ilu, filename, nparms) integer ilu, nparms character*(*) filename integer function tgettyp(ilu) integer ilu subroutine tblread(ilu) integer ilu subroutine tgetc(ilu, pindex, pvalc) integer ilu, pindex character*(*) pvalc subroutine tgetd(ilu, pindex, pvald) integer ilu, pindex double precision pvald subroutine tgeti(ilu, pindex, pvali) integer ilu, pindex integer pvali subroutine tgetr(ilu, pindex, pvalr) integer ilu, pindex real pvalr subroutine tindp(ilu, parm, pindex) integer ilu, pindex character*(*) parm subroutine tpinfo(ilu, pindex, pname, ptype, pblank, punit, pscale, poffset, pcol, plen) integer ilu, pindex, pcol, plen real pscale, poffset character*(*) pname, ptype, punit, pblank integer function isblank(ilu, pindex) integer pindex integer function itstat() subroutine tshcase(shflag) integer shflag integer function ntkey(ilu) integer ilu subroutine tgetkc(ilu, kindex, kvalc) integer ilu, kindex character*(*) kvalc subroutine tgetki(ilu, kindex, kvali) integer ilu, kindex integer kvali subroutine tgetkr(ilu, kindex, kvalr) integer ilu, kindex real kvalr subroutine tindk(ilu, kname, kindex, ktype, kunit, kval) integer ilu, kindex, kval character*(*) kname, ktype, kunit subroutine tkname(ilu, kindex, kname, ktype, kunit, kval) integer ilu, kindex, kval character*(*) kname, ktype, kunit subroutine tfiltyp(olu, filetype) integer olu, filetype subroutine topenw(olu, filename) integer olu character*(*) filename subroutine tsetc(olu, pindex, cval) integer olu, pindex character*(*) cval subroutine tsetd(olu, pindex, dval) integer olu, pindex double precision dval subroutine tseti(olu, pindex, ival) integer olu, pindex integer ival subroutine tsetr(olu, pindex, rval) integer olu, pindex real rval subroutine tlink(ilu, olu) integer ilu, olu subroutine tdelp(olu, pindex) integer olu, pindex subroutine tnewp(olu, pname, ptype, pblamk, punit, pscal, poff, pfmt, plen, pindex) integer olu, plen, pindex character*(*) pname, ptype, pblank, punit, pscal, poff, pfmt subroutine tsetk(olu, kname, ktype, kval, kfmt, kcomnt) integer olu character*(*) kname, ktype, kval, kcomnt subroutine tblwrit(olu) integer olu subroutine tcls(lu) integer lu DESCRIPTION These subroutines are the table handling routines to read, write or manipulte the table files. (see FORMAT for possible table types). TABLE FILE READING: The subroutines described below can be used to retrieve information from the existing table files. The argument in ilu in all these subroutines defines the Fortran logical unit. TOPENR(ilu, filename, nparms) - opens and reads header information in the file. filename = unix file name nparms = return value of number of columns (or parameters) in the file INTEGER FUNCTION TGETTYP(ilu) - returns type of table file tgettyp = 0 for IPAC Ascii table tgettyp = 1 for FITS Binary table tgettyp = 2 for FITS Ascii table TBLREAD(ilu) - reads the next record from the file TGETC(ilu, pindex, pvalc) - returns the value of a character string parameter pindex = column number whose value is desired pvalc = return value of character string TGETD(ilu, pindex, pvald) - returns the value of a double precision parameter pindex = column number whose value is desired pvald = return value of double precision parameter TGETI(ilu, pindex, pvali) - returns the value of an integer parameter pindex = column number whose value is desired pvali = return value of integer parameter TGETR(ilu, pindex, pvalr) - returns the value of a real parameter pindex = column number whose value is desired pvalr = return value of real parameter TINDP(ilu, pname, pindex) - returns the column number associated with a given name pname = name of parameter whose column number is desired pindex = return value of column number TPINFO(ilu,pindex,pname,ptype,pblank,punit,pscale,poffs,pcol,plen) - returns information about a given column pindex = column number pname = return value of parameter name in this column ptype = return value of parameter type pblank = return string value of parameter 'blank' value punit = return string value of parameter units pscale = return real value of parameter scaling factor poffs = return real value of parameter offset value pcol = return integer value of starting column for this parameter plen = return integer value of number of columns used for this parameter INTEGER FUNCTION ISBLANK(ilu, pindex) - returns the 'blank' status of a parameter isblank = TRUE(1) if the field is 'blank'. ('blank' can be defined in the table header but default to a blank string) pindex = column number to be checked INTEGER FUNCTION ITSTAT() - returns the status flag (set by all subroutines) itstat = 0 : Normal status itstat > 0 : Error (No such file, File read error, etc) itstat < 0 : EOF on read TSHCASE(shflag) - makes character strings case insensitive shflag = 1 : integer makes case insensitive shflag = 0 : case is considered while comparing character strings (default) TABLE FILE KEYWORD READING: These subroutines returns information on the keywords in the existing table files. INTEGER FUNCTION NTKEY(ilu) - returns the number of keyword parameters. TGETKC(ilu, kindex, kvalc) - returns the value of a char- acter string keyword . kindex = keyword number whose value is desired kvalc = return value of character string keyword TGETKI(ilu, kindex, kvali) - returns the value of an integer keyword . kindex = keyword number whose value is desired kvali = return value of an integer keyword TGETKR(ilu, kindex, kvalr) - returns the value of a real keyword . kindex = keyword number whose value is desired kvalr = return value of a real keyword TINDK(ilu, kname, kindex, ktype, kunit, kval) - returns the keyword info associated with a given name kname = keyword name whose info is desired kindex = return value of keyword number ktype = return value of a string containing keyword format (e.g 'real') kunit = return value of the string containing units for this keyword kval = number of values for this keyword TKNAME(ilu, kindex, kname, ktype, kunit, kval) - returns the keyword info associated with a given number kindex = keyword number whose info is desired kname = return value of keyword name ktype = return value of a string containing keyword format (e.g 'real') kunit = return value of the string containing units for this keyword kval = number of values for this keyword TABLE FILE WRITING: Following is the set of subroutines to create new table files or manipulate (add or delete columns) the existing files. The variable olu in all these subroutine defines the Fortarn logical unit number used to write output files. TFILTYP(olu, filetype) - sets the type of output table filetype = 0 for IPAC Ascii table filetype = 1 for FITS Binary table filetype = 2 for FITS Ascii table TOPENW(olu, filename) - opens an output file filename = unix file name To update the existing file open the file with TOPENR on some Fortran logical unit ilu call TOPENW with filename = ' ' call TLINK (see below) to link the input and output units TLINK (ilu, olu) - links an input unit to an output unit The columns in the input file are copied to the output file unless they are deleted using TDELP. The new columns can be added using TNEWP. TDELP(olu, pindex) - deletes an input file column from the output file pindex = column number of deleted parameter TNEWP(olu, pname, ptype, pblank, punit, pscale, poffs, pfmt, plen, pindex) - adds a new column to an output file pname = string defining new parameter name ptype = string defining parameter type . pblank = string defining parameter 'blank' value punit = string defining parameter units pscale = string defining parameter scaling factor poffs = string defining parameter offset value pfmt = string defining parameter format in which data is to be written out plen = number of characters in format (or name if larger) pindex = return value of column number for the new parameter TSETK(olu, kname, ktype, kval, kfmt, kcomnt) - adds the keyword in the output file header (FITS files only). kname = character string containing new keyword name ktype = character string containing new keyword type (e.g 'real') kval = character string containing value of the key word kfmt = character string containing format iwith which keyword value is written out kcomnt = character string containing comment to go with this keyword TSETC(olu, pindex, cval) - sets the value of a character type parameter (new parameter only). pindex = column number (returned by TNEWP) whose value is to be set cval = character value of new parameter TSETD(olu, pindex, dval) - sets the value of a double pre- cision type parameter (new parameter only). pindex = column number (returned by TNEWP) whose value is to be set dval = double precision value of new parameter TSETI(olu, pindex, ival) - sets the value of integer type parameter (new parameter only). pindex = column number (returned by TNEWP) whose value is to be set ival = integer value of new parameter TSETR(olu, pindex, rval) - sets the value of real type parameter (new parameter only). pindex = column number (returned by TNEWP) whose value is to be set rval = real value of new parameter TBLANK(olu, pindex) - sets the value of a parameter as 'blank' pindex = column number whose value is to be set as 'blank' TBLWRIT(olu) - writes a record to the specified output file TCLS(lu) - closes table file opened on Fortarn logical unit lu FORMAT Table I/O subroutines are capable of handling three types of table as follows. 1. IPAC Ascii Tables These are the ascii tables of data columns with the following rules. Tables without any header information are acceptable as long as there are not any blank fields in the first line. The data in the table is interpretable as real numbers only (i.e. no character strings) and each data entry in the first line is right justified in its field. Lines that begin with \ (first column) are either comments or keywords defintion. Keyword lines begin with '\REAL', '\CHAR', or '\INT' according to keyword data type. They have the format 'keyword = value(s)'. Multiple values should be seperated by blank. A maximum of 10 values is allowed for each keyword. Lines that start with | define the header lines. The characters | on the line are also used to define the beginning of the fields. The first line with | characters is used to define the field names. The header information and the data for each field can be placed anywhere between the starting position (i.e. | ) to the last position (which is one character before next | ). The next header line defines the type of the field. Possible types are (lower as well as upper case) r for real, d for double precision, i for integers and c for character strings. If there are any subsequent header lines (starting with | ) they contain (in order): 'blanks' for each field, the units for each field, scale factors, and offsets. (The latter two are used only for real fields). Following is an example of IPAC ascii table. \-------------------------------------------------------------- \CHAR example = 'this is an example file' \ | x | y | source name | nsource | xx | yy | | real | real | character | int | r | r | 5.2 3.11 ab #123a 1212345 2.5 2 5.2 3.11 ab #123a 2123 2.5 2 Please note the possible data placements for each field. 2. FITS Binary Tables These are the tables which are "3-D" extension to the standard FITS tables. The data entries in these files could be multi-dimensional arrays and the data is written in binary format instead of usual ascii. The record size is 2880 bytes and the header records have the same format and keywords as for statndard FITS files with the following exceptions. The first keyword in the header record should be 'XTENSION' and should have a value of 'A3DTABLE'. BITPIX is a required keyword which should have a value of 8. NAXIS is a required keyword which must have a value of 2 for these tables. The keyword TFORMnnn (which defines the format for nth field in FITS Ascii) is the size, data type and the possible format for the field nnn. The forms of this keyword are rAnn, rEnn.n, rInn, rDnn.n for characters, single precision, integers, double precision where r is the repeat count (if absent, it is assumed to be 1). 2. FITS Ascii Tables These are the files written in standard format of FITS ascii tables of data records 2880 bytes. EXAMPLE Following is an example of a Fortran program which reads a table file and output another table file containing the columns of input file together with 3 newly defined columns. program example character*80 filin, filout ,elt1 integer elt3 integer iu,ou c the common block to get the debugging from table i/o routines. set idebug = 1 common/tdebug/idebug data iu, ou/90, 91/ c get the parameter (file names, output file type) from the command line call getarg(1,filin) call getarg(2,filout) call getarg(3,iftype) c***open input table file call topenr(iu, filin, nparms) c***set the output file type and open it call tfiltyp(ou,iftype) call topenw(ou, filout) c link the input/output files call tlink(iu, ou) c define 3 new columns in output file call tnewp(ou,'elt 1','char',' ',' ',' ',' ','a20',20,ind1) call tnewp(ou,'elt 2','real',' ',' ',' ',' ','f20.3',20,ind2) call tnewp(ou,'elt 3','int ',' ',' ',' ',' ','i20',20,ind3) c start reading input table data records and generating output file i=0 40 continue c set the values for new parameters elt1 = ' this is an example' elt2 = 2**i/10.0 elt3 = 2**i call tsetc(ou, ind1, elt1) call tsetr(ou, ind2, elt2) call tseti(ou, ind3, elt3) c read record from input file call tread(iu) c EOF if(itstat(). LT .0) go to 100 c ERROR if(itstat(). GT .0) go to 90 i=i+1 c combine input file columns with new columns and write it out call twrite(ou) go to 40 90 print*,' Error on file read at rec no = ',i go to 110 100 print*,' Number of Sources Processed = ',i 110 continue c close input file call tcls(iu) c close output file. if filout is ' ', then move output file to input file . call tcls(ou) stop end AUTHOR Iffat Khan 1993 Example by Tom Barlow: C---------------------------------------------------------------------- C Read stars out of IPAC (.als) table. C subroutine rdipac_als(infile,n,id,x,y,mag) C implicit none character*(*) infile integer*4 n,id(*) real*8 x(*),y(*),mag(*) integer*4 iu,idx_id,idx_x,idx_y,idx_mag,nparms,itstat C Input unit. iu=2 call topenr(iu,infile,nparms) call tshcase(1) call tindp(iu,'Index',idx_id) call tindp(iu,'x',idx_x) call tindp(iu,'y',idx_y) call tindp(iu,'Mag',idx_mag) n=0 1 continue n=n+1 call tblread(iu) if (itstat().lt.0) goto 5 call tgeti(iu,idx_id,id(n)) call tgetd(iu,idx_x,x(n)) call tgetd(iu,idx_y,y(n)) call tgetd(iu,idx_mag,mag(n)) goto 1 5 continue n=n-1 call tcls(iu) return end