fitsIo "C" Routines

These routines allow FITS files to be read in to region structures and written out. The fitsIo routines support reading and writing the following data types -

The FITS files can be either standard files (SIMPLE=T) or not (SIMPLE=F). The FITS format supports U8, S16, S32 and FL32. For standard FITS files, S8, U16 and U32 are transformed using BZERO values of 128, 32768 and 21474883648 respectively. For nonstandard FITS files, the data are not transformed.

For each routine, valid values for the DEFDIRENUM argument can be found in shCFitsIo.h. If any of these values are used, then the defaults (defined by calling shDirSet) for directory, file extension or both, will be added to the passed in FITS file specification before the file is opened.

  • shRegReadAsFits
  • shRegWriteAsFits
  • shHdrReadAsFits
  • shHdrWriteAsFits
  • 
    
    

    shRegReadAsFits

    This routine will read a FITS file into a region structure. The FITS header lines containing the following keywords are removed and any necessary information is stored in the region structure -

    The REGION parameter must not be a physical region or a subregion and it must not have any subregions.

    C SYNTAX: RET_CODE shRegReadAsFits ( REGION *a_regPtr, /* IN: Pointer to region */ char *a_file, /* IN: Name of FITS file */ int a_checktype, /* IN: Flag to signify if should match file and region data type ( = 1) */ int a_keeptype, /* IN: Flag to signify if new region should keep the type of the specified region and any read in pixels should be converted to this type. */ DEFDIRENUM a_FITSdef, /* IN: Default file specification used to expand a_file. */ FILE *a_inPipePtr, /* IN: If != NULL then is a pipe to read from */ int a_readtape /* IN: Flag to indicate that we must fork/exec an instance of "dd" to read a tape drive */ ) RETURNS: SH_SUCCESS - Successful completion. SH_UNK_PIX_TYPE - FITS file has unsupported data type. SH_IS_PHYS_REG - Region is a physical region. SH_IS_SUB_REG - Region is a subregion. SH_HAS_SUB_REG - Region has subregions. SH_REGINFO_ERR - Could not get region information using shRegInfoGet. SH_ENVSCAN_ERR - Could not get full path to FITS file. SH_PIX_TYP_NOMATCH - FITS file data type did not equal that of region. SH_FITS_PIX_READ_ERR - Error when reading the pixels from the FITS file. SH_FITS_OPEN_ERR - Error opening the FITS file and reading the header. SH_INV_FITS_FILE - FITS header has invalid format. SH_INVARG - Invalid argument in SH_MALLOC_ERR - Space could not be temp allocated for a file spec. SH_NO_FITS_KWRD - Couldn't find header keyword that should be there. SH_IS_SUB_MASK - The mask associated with the region is a submask. SH_HAS_SUB_MASK - The mask associated with the region has submasks. SH_MASKINFO_ERR - Could not get mask information using shMaskInfoGet. SH_INV_BSCALE_KWRD - Could not get BSCALE keyword from header. SH_NO_BSCALE_KWRD - Could not find a BSCALE keyword in the header. SH_NO_BZERO_KWRD - Could not find a BZERO keyword in the header. SH_TAPE_BAD_FILE_PTR - Attempting to read from tape and an open pipe. SH_TAPE_DD_FAIL - Failed to create a dd process to process tape. SH_TAPE_DD_ERR - Error in dd process during tape processing.
    
    
    
    

    shRegWriteAsFits

    This routine will write a region structure into a FITS file. FITS header lines containing the following keywords are added to the header -

    The following combinations of FITS file type and pixel data type are illegal -

    These data types can only be written out in standard FITS files.

    C SYNTAX: RET_CODE shRegWriteAsFits ( REGION *a_reg, /* IN: Name of region */ char *a_file, /* IN: Name of FITS file */ FITSFILETYPE a_type, /* IN: Type of FITS file, either STANDARD or NONSTANDARD */ int a_naxis, /* IN: NAXIS value */ DEFDIRENUM a_FITSdef, /* IN: Default file specification used to expand a_file */ FILE *a_outPipePtr, /* IN: If != NULL then a pipe to write to */ int a_writetape /* IN: If != 0, fork/exec off a "dd" to pipe data to */ ) RETURNS: SH_SUCCESS - Successful completion. SH_TYPEMISMATCH - Illegal combination of pixel data type & file type. SH_REGINFO_ERR - Could not get region information using shRegInfoGet. SH_ENVSCAN_ERR - Could not get full path to FITS file. SH_HEADER_FULL - Header is full could not add in needed keywords. SH_FITS_OPEN_ERR - Could not open the requested FITS file. SH_FITS_PIX_WRITE_ERR - Error when writing the pixels to the FITS file. SH_NO_FITS_KWRD - Error when after adding keywords to header. SH_TAPE_BAD_FILE_PTR - Attempting to write from tape and an open pipe. SH_TAPE_DD_FAIL - Failed to create a dd process to process tape. SH_TAPE_DD_ERR - Error in dd process during tape processing.
    
    
    

    shHdrReadAsFits

    This routine will read a FITS file into a header structure. No editing is performed on the header.

    C SYNTAX: RET_CODE shHdrReadAsFits ( HDR *a_hdrPtr, /* IN: Pointer to header */ char *a_file, /* IN: Name of FITS file */ DEFDIRENUM a_FITSdef, /* IN: Default file specification used to expand a_file. */ FILE *a_inPipePtr, /* IN: If != NULL then is a pipe to read from */ int a_readtape /* IN: Flag which indicates we must fork/exec an instance of "dd" to read tape */ ) RETURNS: SH_SUCCESS - Successful completion. SH_ENVSCAN_ERR - Could not get full path to FITS file. SH_FITS_OPEN_ERR - Error opening the FITS file and reading the header. SH_MALLOC_ERR - Space could not be temp allocated for a file spec. SH_TAPE_BAD_FILE_PTR - Attempting to read from tape and an open pipe. SH_TAPE_DD_FAIL - Failed to create a dd process to process tape. SH_TAPE_DD_ERR - Error in dd process during tape processing.
    
    
    
    

    shHdrWriteAsFits

    This routine will write a header structure into a FITS file. The header must contain all the appropriate keywords if the a_regPtr parameter is NULL. These include the following -

  • SIMPLE
  • BITPIX
  • NAXIS and appropriate NAXISnn
  • END
  • If the a_regPtr parameter is valid, the header is treated as in the shRegWriteAsFits case and lines containing the following keywords are added to the header - C SYNTAX: RET_CODE shHdrWriteAsFits ( HDR *a_hdrPtr /* IN: Name of header */ char *a_file, /* IN: Name of FITS file */ FITSFILETYPE a_type, /* IN: Type of FITS file, either STANDARD or NONSTANDARD */ int a_naxis, /* IN: NAXIS value */ DEFDIRENUM a_FITSdef, /* IN: Default file specification used to expand a_file */ REGION *a_regPtr, /* IN: pointer to region that header corresponds to */ FILE *a_outPipePtr, /* IN: If != NULL then a pipe to write to */ int a_writetape /* IN: If != 0 then fork/exec "dd" and write to it */ ) RETURNS: SH_SUCCESS - Successful completion. SH_ENVSCAN_ERR - Could not get full path to FITS file. SH_HEADER_FULL - Header is full could not add in needed keywords. SH_FITS_OPEN_ERR - Could not open the requested FITS file. SH_NO_FITS_KWRD - Error when after adding keywords to header. SH_TAPE_BAD_FILE_PTR - Attempting to write from tape and an open pipe. SH_TAPE_DD_FAIL - Failed to create a dd process to process tape. SH_TAPE_DD_ERR - Error in dd process during tape processing.