5.7.2 Column Information Routines

1

Get the number of rows or columns in the current FITS table. The number of rows is given by the NAXIS2 keyword and the number of columns is given by the TFIELDS keyword in the header of the table.

  int fits_get_num_rows / ffgnrw
      (fitsfile *fptr, > long *nrows, int *status);

  int fits_get_num_rowsll / ffgnrwll
      (fitsfile *fptr, > LONGLONG *nrows, int *status);

  int fits_get_num_cols / ffgncl
      (fitsfile *fptr, > int *ncols, int *status);

2

Get the table column number (and name) of the column whose name matches an input template name. If casesen = CASESEN then the column name match will be case-sensitive, whereas if casesen = CASEINSEN then the case will be ignored. As a general rule, the column names should be treated as case INsensitive.

The input column name template may be 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 (with the first column = 1). The `*' wild card 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). 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 as a warning that a unique match was not found. To find the other cases that match the template, call the routine again leaving the input status value equal to COL_NOT_UNIQUE and the next matching name will then be returned. Repeat this process until a status = COL_NOT_FOUND is returned.

The FITS Standard recommends that only letters, digits, and the underscore character be used in column names (with no embedded spaces). Trailing blank characters are not significant.

  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)

3

Return the data type, vector repeat value, and the width in bytes of a column in an ASCII or binary table. Allowed values for the data type in ASCII tables are: TSTRING, TSHORT, TLONG, TFLOAT, and TDOUBLE. Binary tables also support these types: TLOGICAL, TBIT, TBYTE, TLONGLONG, TCOMPLEX and TDBLCOMPLEX. The negative of the data type code value is returned if it is a variable length array column. Note that in the case of a 'J' 32-bit integer binary table column, this routine will return data type = TINT32BIT (which in fact is equivalent to TLONG). With most current C compilers, a value in a 'J' column has the same size as an 'int' variable, and may not be equivalent to a 'long' variable, which is 64-bits long on an increasing number of compilers.

The 'repeat' parameter returns the vector repeat count on the binary table TFORMn keyword value. (ASCII table columns always have repeat = 1). The 'width' parameter returns the width in bytes of a single column element (e.g., a '10D' binary table column will have width = 8, an ASCII table 'F12.2' column will have width = 12, and a binary table'60A' character string column will have width = 60); Note that CFITSIO supports the local convention for specifying arrays of fixed length 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 means that each row of the table contains 5 12-character substrings within the 60-character field, and thus in this case this routine will return typecode = TSTRING, repeat = 60, and width = 12. (The TDIMn keyword may also be used to specify the unit string length; The pair of keywords TFORMn = '60A' and TDIMn = '(12,5)' would have the same effect as TFORMn = '60A12'). The number of substrings in any binary table character string field can be calculated by (repeat/width). A null pointer may be given for any of the output parameters that are not needed.

The second routine, fit_get_eqcoltype is similar except that in the case of scaled integer columns it returns the 'equivalent' data type that is needed to store the scaled values, and not necessarily the physical data type of the unscaled values as stored in the FITS table. For example if a '1I' column in a binary table has TSCALn = 1 and TZEROn = 32768, then this column effectively contains unsigned short integer values, and thus the returned value of typecode will be TUSHORT, not TSHORT. Similarly, if a column has TTYPEn = '1I' and TSCALn = 0.12, then the returned typecode will be TFLOAT.

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

  int fits_get_coltypell / ffgtclll
      (fitsfile *fptr, int colnum, > int *typecode, LONGLONG *repeat,
       LONGLONG *width, int *status)

  int fits_get_eqcoltype / ffeqty
      (fitsfile *fptr, int colnum, > int *typecode, long *repeat,
       long *width, int *status)

  int fits_get_eqcoltypell / ffeqtyll
      (fitsfile *fptr, int colnum, > int *typecode, LONGLONG *repeat,
       LONGLONG *width, int *status)

4

Return the display width of a column. This is the length of the string that will be returned by the fits_read_col routine when reading the column as a formatted string. The display width is determined by the TDISPn keyword, if present, otherwise by the data type of the column.

  int fits_get_col_display_width / ffgcdw
      (fitsfile *fptr, int colnum, > int *dispwidth, int *status)

5

Return the number of and size of the dimensions of a table column in a binary table. 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)

  int fits_read_tdimll / ffgtdmll
      (fitsfile *fptr, int colnum, int maxdim, > int *naxis,
       LONGLONG *naxes, int *status)

6

Decode the input TDIMn keyword string (e.g. '(100,200)') and return the number of and size of the dimensions of a binary table column. If the input tdimstr character string is null, then this routine returns naxis = 1 and naxes[0] equal to the repeat count in the TFORM keyword. This routine is called by fits_read_tdim.

  int fits_decode_tdim / ffdtdm
      (fitsfile *fptr, char *tdimstr, int colnum, int maxdim, > int *naxis,
       long *naxes, int *status)

  int fits_decode_tdimll / ffdtdmll
      (fitsfile *fptr, char *tdimstr, int colnum, int maxdim, > int *naxis,
       LONGLONG *naxes, int *status)

7

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

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

  int fits_write_tdimll / ffptdmll
      (fitsfile *fptr, int colnum, int naxis, LONGLONG *naxes, > int *status)