next up previous contents Back To Software Index
Next: Low-Level Table Access Up: FITS ASCII and Previous: FITS ASCII and

Column Information Routines

Get the table column number (and name) of the column whose name matches an input template name. The table column names are defined by the TTYPEn keywords in the FITS header. If a column does not have a TTYPEn keyword, then these routines assume that the name consists of all blank characters. These 2 routines perform the same function except that ffgcno only returns the number of the matching column whereas ffgcnn also returns the name of the column. If casesen = TRUE then the column name match will be case-sensitive.

The input column name template (templt) is either the exact name of the column to be searched for, or it may contain wild card characters (*, ?, or #), or it may contain the integer number of the desired column (where the number is expressed as ASCII digits). The first 2 wild cards behave similarly to UNIX filename matching: the '*' character matches any sequence of characters (including zero characters) and the '?' character matches any single character. The # wildcard will match any consecutive string of decimal digits (0-9). As an example, the template strings `AB?DE', `AB*E', and `AB*CDE' will all match the string 'ABCDE'. If more than one column name in the table matches the template string, then the first match is returned and the status value will be set to COL_NOT_UNIQUE (237) as a warning that a unique match was not found. To find the other cases that match the template, simply call the routine again leaving the input status value equal to 237 and the next matching name will then be returned. Repeat this process until a status = COL_NOT_FOUND (219) is returned. If these routines fail to match the template to any of the columns in the table, they lastly check if the template can be interpreted as a simple positive integer (e.g., '7', or '512') and if so, they return that column number. If no matches are found then a status = COL_NOT_FOUND (219) error is returned.

Note that the FITS Standard recommends that only letters, digits, and the underscore character be used in column names (with no embedded spaces in the name). Trailing blank characters are not significant. It is recommended that the column names in a given table be unique within the first 8 characters, and HIGHLY recommended that the names be unique withing the first 16 characters.

  int fits_get_colnum / ffgcno
      (fitsfile *fptr, int casesen, char *templt, > int *colnum,
       int *status)

  int fits_get_colname / ffgcnn
      (fitsfile *fptr, int casesen, char *templt, > char *colname,
       int *colnum, int *status)

Get the datatype of a column in an ASCII or binary table. This routine returns an integer code value corresponding to the datatype of the column. (See the ffbnfm and ffasfm routines in the Utilities section of this document for a list of the code values). The negative of the code value is returned if it is a variable length array column. The vector repeat count (which is alway 1 for ASCII table columns) is also returned. If the specified column has an ASCII character datatype (code = 16) then the width of a unit string in the column is also returned. Note that this routine supports the local convention for specifying arrays of strings within a binary table character column, using the syntax TFORM = 'rAw' where 'r' is the total number of characters (= the width of the column) and 'w' is the width of a unit string within the column. Thus if the column has TFORM = '60A12' then this routine will return typecode = 16, repeat = 60, and width = 12.

  int fits_get_coltype / ffgtcl
      (fitsfile *fptr, int colnum, > int *typecode, long *repeat,
       long *width, int *status)

Get information about an existing ASCII table column.

int fits_get_acolparms / ffgacl
    (fitsfile *fptr, int colnum, > char *ttype, long *tbcol,
     char *tunit, char *tform, double *scale, double *zero,
     char *nulstr, char *tdisp, int *status)

Get information about an existing binary table column. DATATYPE is a character string which returns the datatype of the column as defined by the TFORMn keyword (e.g., 'I', 'J','E', 'D', etc.). In the case of an ASCII character column, typecode will have a value of the form 'An' where 'n' is an integer expressing the width of the field in characters. For example, if TFORM = '160A8' then ffgbcl will return typechar='A8' and repeat=20. All the returned parameters are scalar quantities.

  int fits_get_bcolparms / ffgbcl
      (fitsfile *fptr, int colnum, > char *ttype, char *tunit,
       char *typechar, long *repeat, double *scale, double *zero,
       long *nulval, char *tdisp, int  *status)

Put (append) a TDIMn keyword whose value has the form '(l,m,n...)' where l, m, n... are the dimensions of a multidimension array column in a binary table.

  int fits_write_tdim / ffptdm
      (fitsfile *fptr, int colnum, int naxis, long *naxes, > int *status)

Return the number of and size of the dimensions of a table column. Normally this information is given by the TDIMn keyword, but if this keyword is not present then this routine returns naxis = 1 and naxes[0] equal to the repeat count in the TFORM keyword.

  int fits_read_tdim / ffgtdm
      (fitsfile *fptr, int colnum, int maxdim, > int *naxis,
       long *naxes, int *status)

Return optimal number of rows to read or write at one time for maximum I/O efficiency. Refer to the ``Optimizing Code'' section in Chapter 5 for more discussion on how to use this routine.

  int fits_get_rowsize / ffgrsz
      (fitsfile *fptr, long *nrows, *status)

next up previous contents Back To Software Index
Next: Low-Level Table Access Up: FITS ASCII and Previous: FITS ASCII and