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_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. It is recommended that all the column names in a given table be unique within the first 8 characters, and strongly recommended that the names be unique within 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)

3

Return the datatype, vector repeat value, and the width in bytes of a column in an ASCII or binary table. Allowed values for the datatype in ASCII tables are: TSTRING, TSHORT, TLONG, TFLOAT, and TDOUBLE. Binary tables also support these types: TLOGICAL, TBIT, TBYTE, TCOMPLEX and TDBLCOMPLEX. The negative of the datatype 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 datatype = 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 value (e.g., a '10D' binary table column will have width = 8; an ASCII table 'F12.2' column will have width = 12); Note that this routine 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 routine will return typecode = TSTRING, repeat = 60, and width = 12. A null pointer may be given for any of the output parameters that are not needed.  

  int fits_get_coltype / ffgtcl
      (fitsfile *fptr, int colnum, > int *typecode, long *repeat,
       long *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)

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)

7

Write 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)