functions in fits.i -

 _fits_alphabet  
 

             _fits_bad_keyword(c)  
 
     Returns error message due to invalid FITS keyword.  C is an array of  
     characters that compose the bad FITS keyword.  

             _fits_bintable_header(fh, nbytes, nrows, tfields)  
 
     Set/update header  information in  FITS handle FH  for a  binary table  
     extension.  NBYTES is the number of  bytes per row of the table, NROWS  
     is  the number  of table  rows  and TFIELDS  is the  number of  fields  
     (columns in  the table).  FITS  card "XTENSION" with  value "BINTABLE"  
     must already exists  in the header (this is  not checked).  FITS cards  
     "BITPIX",  "NAXIS",   "NAXIS1",  "NAXIS2",  "PCOUNT",   "GCOUNT",  and  
     "TFIELDS" get created/updated by this routine.  The value of PCOUNT is  
     computed by the routine and returned to the caller.  

             _fits_digitize   - char -> number conversion array;  
             _fits_multiplier - multiplier;  
             _fits_alphabet   - allowed characters in FITS keys;  
             _fits_max_id     - maximum possible ID value.  
 
     Private  arrays  used  to   convert  FITS  keyword  to/from  numerical  
     identifiers.  If you experiment  a strange behaviour of FITS routines,  
     it may  be because one  of these arrays  get corrupted; in  that case,  
     just  run subroutine fits_init  to reinitialize  things (you  may also  
     have to rehash your FITS handles: see fits_rehash).  

 _fits_false  
 

             _fits_format_comment(key)  
 
       -or- _fits_format_comment(key, text)  
     Private routine  to format  FITS commentary card,  return an  array of  
     80-character string(s).   Text comment, if longer  than 72 characters,  
     will result in more than one comment cards.  

             _fits_format_complex(key, value)  
 
       -or- _fits_format_complex(key, value, comment)  
     Private routine to format FITS complex card, return a 80-character  
     string.  

             _fits_format_integer(key, value)  
 
       -or- _fits_format_integer(key, value, comment)  
     Private routine to format FITS integer card, return a 80-character  
     string.  

             _fits_format_logical(key, value)  
 
       -or- _fits_format_logical(key, value, comment)  
     Private  routine to format  FITS logical  card, return  a 80-character  
     string.  

             _fits_format_real(key, value)  
 
       -or- _fits_format_real(key, value, comment)  
     Private routine to format FITS real card, return a 80-character  
     string.  
     Note: FITS standard imposes that the ASCII representation of a real  
           number makes 20 characters;  the full precision of 64-bit values  
           can not be represented with this restriction.  

             _fits_format_string(key, value)  
 
       -or- _fits_format_string(key, value, comment)  
     Private routine to format FITS string card, return a 80-character  
     string.  
     Note: enclose input string in quotes, replacing each quote in input  
           string by 2 quotes.  Since opening quote should appear in  
           column 11 and closing quote in columns 20 to 80 of the FITS  
           card, make sure that string is not longer than 68 characters  
           (too long strings get silently truncated).  

             _fits_get_cards(fh, cards, ids)  
 
     Stores  in  variables CARDS  and  IDS  the  FITS cards  and  numerical  
     identifiers from header in FITS  handle FH.  The returned value is the  
     number of FITS cards (including empty ones).  

             _fits_id(hdr)  
 
     Return array  of numerical identifier  for FITS header data  HDR which  
     must be  an array(char, 80,  N).  Any invalid  FITS key will  have its  
     identifier set to -1.  

 _fits_id_bitpix  
 

 _fits_id_bscale  
 

 _fits_id_bzero  
 

 _fits_id_comment  
 

 _fits_id_end  
 

 _fits_id_gcount  
 

 _fits_id_history  
 

 _fits_id_naxis  
 

 _fits_id_pcount  
 

             _fits_id_simple    _fits_id_bitpix   _fits_id_naxis  
             _fits_id_end       _fits_id_comment  _fits_id_history  
             _fits_id_xtension  _fits_id_bscale   _fits_id_bzero  
             _fits_id_gcount    _fits_id_pcount  
 
     Numerical  identifers of  common FITS  keywords. If  you  experiment a  
     strange behaviour  of FITS  routines, it may  be because one  of these  
     values get corrupted;  in that case, just run  subroutine fits_init to  
     reinitialize things.  

             _fits_id_special  
 
     Private  array  of  all  numerical  identifers of  common  FITS  keys:  
     "SIMPLE",  "BITPIX",  "NAXIS", "END",  "",  "COMMENT", "HISTORY",  and  
     "XTENSION".  

 _fits_id_xtension  
 

             _fits_key(id)  
 
     Private routine used by fits_key, only  useful if ID is a valid scalar  
     numerical identifier.  

             fits_match(fh, pattern)  
 
     Return array of int's which are non-zero where FITS card names in FITS  
     handle  FH  match PATTERN.   PATTERN  must be  a  scalar  string or  a  
     numerical identifier.  As a  special case, if  PATTERN is of  the form  
     "KEYWORD#" (i.e.  last character of  PATTERN is a '#'), then any human  
     readable integer will match the '#', e.g. "NAXIS#" will match "NAXIS3"  
     and "NAXIS11" but not "NAXIS" nor "QNAXIS4.  
     Global/extern  variable  _fits_match_id  is  set  with  the  numerical  
     identifier of PATTERN (without last '#' if any).  

 _fits_max_id  
 

 _fits_multiplier  
 

             fits_parse(card);  
 
       -or- fits_parse(card, id);  
     Return value  of a single  FITS card (CARD  is a scalar  string).  The  
     type of the scalar result is as follow:  
        - string for a string or a commentary FITS card  
        - char ('T' for true or 'F' for false) for a logical FITS card  
        - long for an integer FITS card  
        - double for a real FITS card  
        - complex for a complex FITS card  
     Trailing   spaces   (which    are   irrelevant   according   to   FITS  
     specifications)   get   discarded   from   the  returned   value   for  
     string-valued cards (not commentary cards).  
     In order to save a call to  fits_id, if ID is non-nil it is assumed to  
     be the numerical identifier of the card, i.e. fits_id(CARD).  
     The   comment  part   of   CARD  is   stored   into  external   symbol  
     _fits_parse_comment which is a string (possibly nil) for a valued card  
     and void (i.e. []) for a commentary card.  
     If the  SAFE keyword is true,  the routine returns an  empty result in  
     case of error.  

             _fits_strict  
 
     Private flag: apply strict FITS compliance?  Never change this flag  
     directly but rather call `fits_init'.  

             _fits_tolower  
             _fits_toupper  
 
     Private arrays to convert char to upper/lowercase letters.  

 _fits_toupper  
 

             _fits_true  
             _fits_false  
 
     True/false FITS values ('T' and 'F' respectively). */  

             _fits_warn, msg;  
 
     Private FITS routine: print out warning message MSG. */  

             fits - an introduction to Yorick interface to FITS files.  
 
     The  routines  provided by  this  (standalone)  package  are aimed  at  
     reading/writing  FITS (Flexible Image Transport  System) files from/to  
     Yorick.  These  routines attempt to follow the  FITS standard (version  
     1.1)  as defined in  NOST report  [1].  Nevertheless  the user  may be  
     aware of some  limitations (some of which are  unavoidable with such a  
     "flexible" format as FITS):  
      - It  is still possible to  produce a non-standard  FITS file because  
        (for obvious  efficiency reasons)  routines in this  package cannot  
        check  everything.  At  least, FITS  routines check  that compliant  
        FITS keywords  are used and that  mandatory cards (SIMPLE/XTENSION,  
        BITPIX,  NAXIS, ...)   get written  in the  correct order  and with  
        correct value types (see  fits_set).  Nevertheless, the user has to  
        know only  very little  about FITS standard  to be able  to produce  
        valid FITS files.  
      - In this version  of the package, headers of  any FITS extension can  
        be read/produced but  you can only read/write Yorick  array data or  
        binary tables, i.e.  corresponding to primary data and FITS "IMAGE"  
        or  "BINTABLE" extensions  (see  fits_read_array, fits_write_array,  
        fits_read_bintable, and fits_write_bintable).  Support for standard  
        extensions (such  as ASCII  table "TABLE") is  planned but  not yet  
        done.  
      - There  is   no  special   handling  of  IEEE  special  values  NaN,  
        +/-Infinity (using such values is  likely to raise a floating point  
        error catched by Yorick).  
      - You  cannot read/write  compressed  FITS  files.   You'll  have  to  
        pre-decompress or post-compress files  (you can use Yorick "system"  
        function to that end).  
      - It is (not yet) possible to re-open an existing FITS file to modify  
        it.  But it would be very easy to allow for appending extensions to  
        an existing file (should be provided very soon).  
     Some simple driver routines  are provided to allow for reading/writing  
     Yorick arrays from/to FITS file  and may be sufficient for basic usage  
     (see fits_read and fits_write).  
   READING AN EXISTING FITS FILE  
     There is a simplified driver fits_read  (which see) to read data in an  
     existing FITS file.  The following example demontrates how to read the  
     contents of a FITS file with the basic routines:  
     fh = fits_open(name);                 // open existing file and read  
                                           // header of 1st (primary) HDU  
     data1 = fits_read_array(fh);          // read all "image" data in 1st HDU  
     slice = fits_read_array(fh, which=n); // read N-th data slice in current  
                                           // HDU  
     fits_next_hdu, fh;                    // move to next HDU and read header  
     data2 = fits_read_array(fh);          // read data of secondary HDU  
     ...;  
   CREATING A NEW FITS FILE:  
     There is a (very) simplified driver fits_write (which see) to create a  
     new  FITS  file to  store  a  Yorick  array.  The  following  examples  
     demontrates how to write a moderately complex FITS file with the basic  
     routines (assuming DATA1 is a 2-dimensional array):  
       fh = fits_open(name, 'w');      // create new file  
       fits_set, fh, "SIMPLE", 'T',    "true FITS file";  
       fits_set, fh, "BITPIX", bitpix, "bits per pixel";  
       fits_set, fh, "NAXIS",  naxis,  "number of dimensions";  
       fits_set, fh, "NAXIS1", dim1,   "length of 1st dimension";  
       fits_set, fh, "NAXIS2", dim2,   "length of 2nd dimension";  
       fits_set, fh, "EXTEND", 'T', "this file may contain FITS extensions";  
       fits_set, fh, ...               // set any number of other cards with  
       ...                             // several calls to fits_set  
       fits_write_header, fh;          // write header part of current HDU  
       fits_write_array, fh, data1;    // write data part of current HDU  
       fits_new_hdu, fh, "IMAGE";        // append new "IMAGE" extension  
       fits_set, fh, "BITPIX", bitpix, "bits per pixel";  
       fits_set_dims, fh, dimsof(data2); // set all dimensions in one call  
       fits_set, fh, ...                 // set any number of other cards with  
       ...  
       fits_write_header, fh;            // write header part of extension  
       fits_write_array, fh, data2;      // write data part of extension  
       fits_close, fh;                   // close stream of FITS handle, the  
                                         // header can still be examined  
     Note  that the cards  with the  dimensions of  the data  array (NAXIS,  
     NAXIS1, ...)  which  are explicitly set with fits_set  for the primary  
     header can  also be instanciated  in a more  simple way thanks  to the  
     function fits_set_dims as shown for the second HDU.  
     Alternatively, The function fits_create can be used to open a new file  
     and setup  a basic primary header.   In this case, the  first lines of  
     the above examples become:  
       fh = fits_create(name, extend=1,  
                        bitpix=fits_bitpix_of(data1),  
                        dimlist=dimsof(data1));  
       fits_set, fh, ...               // set any number of other cards with  
       ...                             // several calls to fits_set  
       fits_write_header, fh;          // write header part of current HDU  
       fits_write_array, fh, data1;    // write data part of current HDU  
     If you intend to write more than one HDU, do not forget to set card  
     EXTEND to true in the primary header (this is done in the two examples  
     above with fits_open and with fits_create).  
   LIST OF ROUTINES  
     By convention, in this Yorick package, all public symbols (routines or  
     variables)  are prefixed  with  "fits_" and  all  private symbols  are  
     prefixed with "_fits_".  The following (public) routines are provided:  
     File routines:  
       fits_check_file     - check whether a file may be a FITS file  
       fits_open           - open existing FITS file or create new FITS file  
       fits_close          - close file stream in FITS handle  
       fits_create         - creates a new FITS file with minimal header  
       fits_filename       - get full path name of FITS stream  
     Header/HDU routines:  
       fits_current_hdu    - returns number of current HDU  
       fits_goto_hdu       - go to a given HDU number  
       fits_list           - get list of extensions in a FITS file  
       fits_next_hdu       - move to next HDU and parse the header part  
       fits_pad_hdu        - pad current HDU to a multiple of 2880 bytes  
       fits_rewind         - goto first (primary) HDU  
       fits_new_hdu        - start a new FITS extension  
       fits_read_header    - read header part of current HDU  
       fits_write_header   - write header part of current HDU  
     Card routines:  
       fits_delete         - delete card(s) from header of current HDU  
       fits_get            - get value of FITS card(s) in current HDU  
       fits_get_bitpix     - get BITPIX value  
       fits_get_bscale     - get BSCALE value  
       fits_get_bzero      - get BZERO value  
       fits_get_cards      - get all cards matching a pattern  
       fits_get_comment    - get value(s) of COMMENT card(s)  
       fits_get_coordinate - get coordinate information for a given axis  
       fits_get_data_size  - get size of data part in current HDU.  
       fits_get_dims       - get dimension list of array data  
       fits_get_gcount     - get GCOUNT value  
       fits_get_history    - get value(s) of HISTORY card(s)  
       fits_get_keywords   - get list of defined keywords  
       fits_get_list       - get list of integer values  
       fits_get_naxis      - get NAXIS value  
       fits_get_pcount     - get PCOUNT value  
       fits_get_xtension   - get name of FITS primary/extension HDU  
       fits_move_card      - move FITS card  
       fits_parse          - parse FITS card(s)  
       fits_set            - set value of FITS card(s) in current HDU  
       fits_set_dims       - set FITS card(s) for dimension list of array  
     Reading/writing data (also see binary table routines):  
       fits_read           - simple driver to read "IMAGE" or "BINTABLE" data  
       fits_write          - simple driver to write "IMAGE" data  
       fits_new_image      - creates a new "IMAGE" HDU  
       fits_read_array     - read array data from current HDU  
       fits_write_array    - write array data in current HDU  
     Binary tables:  
       fits_new_bintable   - creates a new "BINTABLE" HDU  
       fits_read_bintable  - read binary table from current HDU  
       fits_write_bintable - write binary table in current HDU  
       fits_pack_bintable  - make table columns into a single array  
     Expert users routines:  
       fits_get_special    - get FITS value of mandatory FITS key  
       fits_init           - (re)initialize FITS internals  
       fits_id             - get numerical identifier of a single card  
       fits_ids            - get numerical identifier of FITS card(s)  
       fits_key            - converts numerical identifier into string  
       fits_match          - find FITS card(s) which match a pattern  
       fits_rehash         - recalculate the numerical identifiers of cards  
     Miscellaneous routines:  
       fits_best_scale     - compute best BSCALE and BZERO parameters  
       fits_bitpix_info    - get description of FITS bits-per-pixel value  
       fits_bitpix_of      - compute FITS bits-per-pixel value  
       fits_bitpix_type    - convert FITS bits-per-pixel value to data type  
       fits_check_bitpix   - test if FITS bits-per-pixel value is valid  
       fits_date           - get current time as standard FITS date string  
       fits_is_integer     - checks whether argument is integer  
       fits_is_integer_scalar - checks whether argument is integer scalar  
       fits_is_real_scalar - checks whether argument is real scalar  
       fits_is_scalar      - checks whether argument is scalar or not  
       fits_is_string_scalar - checks whether argument is scalar string or not  
       fits_map            - map scalar function onto array argument  
       fits_move           - move element of an array in-place  
       fits_nth            - format a string in the form: "1st", "2nd", ...  
       fits_tolower        - convert string(s) to lower case letters  
       fits_toupper        - convert string(s) to upper case letters  
       fits_trim           - removes trailing spaces  
       fits_strcmp         - compare strings according to FITS conventions  
   CHANGES WITH RESPECT TO "OLD" FITS PACKAGES  
     This  package is  intended to  be used  in place  of the  old "fits.i"  
     (written by me  and distributed along with Yorick)  which had too many  
     limitations and restrictions to allow for further extensions.  However  
     the API provided by this novel package is quite different from the old  
     one (in particular  the FITS header is no longer  stored into a Yorick  
     structure but in some "opaque"  object: a FITS handle).  Hopefully the  
     new package provides all the  routines needed to deal with this opaque  
     handle but  the name of the  routines (all prefixed  with "fits_") and  
     their calling sequences have changed.  
     The new FITS interface was written with the aim of being:  
       (1) conformable with FITS standards (although try to be not too strict  
           when _reading_ files)  
       (2) flexible and extensible  
       (3) fast (e.g. fits_get takes ~ 150 microseconds for a FITS header  
           with 200 cards on an PIII @ 1GHz)  
   FITS HANDLE  
     In this package, a FITS handle  (denoted FH in the documentation) to a  
     FITS file  is intended to  be an "opaque"  object.  Actually, it  is a  
     list of 4 items organized as follow:  
        _lst(cards, ids, descr, stream)  
        cards  = vector of strings which are the header cards of the  
                 current HDU;  
        ids    = vector of card identifier values (this is for fast search  
                 of cards);  
        descr  = descriptor, vector of long integers:  
                   DESCR(1)= current HDU number (1 for primary HDU);  
                   DESCR(2)= file address of the current HDU  
                   DESCR(3)= file address of the data part for the current HDU  
                   DESCR(4)= file address of the next HDU in read mode,  
                             number of written bytes in write mode  
                   DESCR(5)= file mode: 'r' (read) or 'w' (write)  
        stream = void (no associated file) or stream for input or output;  
     Of course the  end-user should never directly access  the items of the  
     FITS handle  but rather  use the provided  FITS routines (so  that, in  
     order  to  warant portability  of  the user  level  code,  it will  be  
     sufficient  to  only modify  routines  in  this  package whenever  the  
     internals of the FITS handle change).  
   WISH LIST  
     The following is a list of missing features or things I would like to  
     test:  
       1. Implement  support  for  "random groups"  records  (FITS keywords  
          GROUPS, PCOUNT  and GCOUNT) and other  "standard" FITS extensions  
          (only "IMAGE" and "BINTABLE" are implemented): ASCII table, ...  
       2. Extensively test the package (this is mainly because I lack  
          of sample FITS files written by other software).  
       3. Deal with compressed FITS files; this will be possible thanks to  
          the "channel" interface in Yeti (my own extension of Yorick).  
       4. Enhance  the consistency  checks  (for instance,  in the  current  
          version, you can read/write an "image" into a "table" extension).  
   GLOSSARY  
     HDU - Header and Data Unit  
     Indexed Keyword -  
   REFERENCES  
     [1] "Definition of Flexible Image Transport System (FITS)", NASA/Science  
         Office of Standards and Technology, report NOST 100-1.1, September 29,  
         1995.  
     [2] "A User's Guide for the Flexible Image Transport System (FITS)"  
         http://archive.stsci.edu/fits/users_guide/  

             fits_best_scale(bitpix, data)  
 
       -or- fits_best_scale(bitpix, cmin, cmax)  
     Returns [BSCALE,BZERO]  where BSCALE and BZERO are  optimal values for  
     rescaling to BITPIX  file type.  BITPIX must correspond  to an integer  
     type (BITPIX = 8, 16 or 32).  The array DATA contains all the physical  
     values  to save to  the file;  alternatively, CMIN  and CMAX  give the  
     minimal and maximal values in physical data.  

             fits_bitpix_info(bitpix)  
 
     Return string information about FITS bits-per-pixel value.  

             fits_bitpix_of(x)  
 
       -or- fits_bitpix_of(x, native=1)  
     Return FITS bits-per-pixel value BITPIX for binary data X which can be  
     an array or a data  type (structure definition).  If keyword NATIVE is  
     true, the routine assumes that  binary data will be read/write to/from  
     FITS file using native machine data representation.  The default is to  
     conform to FITS standard and to  assume that XDR binary format will be  
     used in FITS file.  

             fits_bitpix_type(bitpix)  
 
       -or- fits_bitpix_type(bitpix, native=1)  
     Returns Yorick data type given by FITS bits-per-pixel value BITPIX.  
     If keyword NATIVE is true, return the native data type matching BITPIX.  

             fits_check_bitpix(bitpix)  
 
     Test if FITS bits-per-pixel value BITPIX is valid.  

             fits_check_file(filename)  
 
       -or- fits_check_file(filename, errmode)  
     Returns 1/0  depending whether FILENAME is  a valid FITS  file or not.  
     If ERRMODE is true (non-nil  and non-zero), unreadable file results in  
     false result otherwise it is  a runtime error.  Note that the checking  
     is very simple: it is sufficient that the first FITS card in the first  
     2880 bytes has keyword "SIMPLE" with logical value 'T' (true).  

             fits_close(fh)  
 
     Closes stream in FITS handle  FH.  The header information stored in FH  
     remain unchanged  (e.g. you can keep  editing the header  in FH).  The  
     returned  value is FH.   Note that  if you  destroy all  references to  
     handle FH, the  associated file (if any) gets  automatically closed by  
     Yorick.  

             fits_create(filename)  
 
     Creates  a new  FITS  file FILENAME  and  returns a  FITS handle  with  
     mandatory cards (i.e. SIMPLE, BITPIX, NAXIS, NAXISn) and some optional  
     cards (i.e. EXTEND, BSCALE and BZERO) already initialized.  
     Keyword  BITPIX can  be  used to  set  FITS "bits-per-pixel"  (default  
     is BITPIX=8, i.e. byte data).  
     Keyword DIMLIST  should be used to  specify the dimension  list of the  
     array data that  is intended to be written in  primary HDU.  The value  
     of DIMLIST is similar to the result returned by dimsof.  
     Keyword EXTEND can  be used to indicate whether  the file may contains  
     FITS extensions.  It is probably a good idea to always use EXTEND=1.  
     Keyword TEMPLATE can be set with  an existing FITS handle to copy some  
     FITS cards  of the template into  the new header.  The  FITS card that  
     are  _never_  copied  are:  "SIMPLE", "XTENSION",  "BITPIX",  "NAXIS",  
     "NAXIS#" (with  # an integer),  "BSCALE" and "BZERO"; the  other cards  
     get copied.  See keywords BSCALE and BZERO if you specifically want to  
     set these values.  
     Keywords BSCALE and BZERO can  be used to specify physical value scale  
     and offset.   See fits_write_array to figure out  how keywords BITPIX,  
     BSCALE and BZERO are used to convert data values into file values.  
     Keywords HISTORY  and COMMENT can be  set to add some  comments in the  
     new handle.  The values of these keywords may be array of strings.  
     Keywords ENCODING and OVERWRITE have the same meaning as in fits_open  
     routine (to see).  

             fits_current_hdu(fh);  
 
     Return number of current Header Data Unit in FITS handle FH.  

             fits_date()  
 
     Returns current Universal Time date as a string conforming to FITS  
     standard: "DD/MM/YY"  

             fits_delete, fh, pattern;  
 
     Delete all cards  matching PATTERN from current header  of FITS handle  
     FH (see fits_match for the syntax of PATTERN).  

             fits_eof(fh)  
 
     Returns non-zero if FITS handle FH is at end of file.  

             fits_filename(fh)  
 
     Return path name  of file associated with FITS handle  FH (in fact the  
     argument may also be any Yorick open stream).  

             fits_get(fh, pattern, comment)  
 
     Get  (array  of)  value(s)   for  FITS  cards  matching  PATTERN  (see  
     fits_match) in current header of FITS handle FH.  If present, argument  
     COMMENT is  an output symbol  where the corresponding comment  part of  
     selected card(s)  will be stored.   In order to avoid  namespace clash  
     due to Yorick's  scoping rules, COMMENT should be  declared as a local  
     symbol in the calling function, e.g.:  
       local comment;  
       value = fits_get(fh, pattern, comment);  
     If no  cards match PATTERN, the  value of keyword  DEFAULT is returned  
     and COMMENT is set to the null string.  
     The data  type of  the returned value  depends on the  particular card  
     type: a  char ('T' or  'F') is returned  for a logical-valued  card, a  
     long is returned for an  integer-valued card, a double is returned for  
     a real-valued  card, a complex  is returned for a  complex-valued card  
     (either integer  or floating  point), and a  string is returned  for a  
     commentary  or  a  string-valued  card.  Trailing  spaces  (which  are  
     irrelevant  according  to  FITS  specifications)  get  discarded  from  
     the returned value for string-valued cards (not commentary cards).  
     If multiple cards match PATTERN, their values must be of the same type  
     unless keyword PROMOTE is true, in which case the routine promotes all  
     card values to a suitable "highest" type.  
     Request fo commentary cards  (i.e. PATTERN is "HISTORY", "COMMENT", or  
     "") may returns several cards.  

             fits_get_bitpix(fh)  
 
       -or- fits_get_bitpix(fh, fix)  
     Get  BITPIX   value  from  current   HDU  in  FITS  handle   FH.   See  
     fits_get_special for the meaning of FIX.  

             fits_get_bscale(fh)  
 
       -or- fits_get_bzero(fh)  
     Get BSCALE and BZERO values  for FITS handle FH.  These parameters are  
     used to convert file values into physical values according to:  
         physical_value = BZERO + BSCALE * file_value  
     if the corresponding card is  missing, BSCALE and BZERO default to 1.0  
     and 0.0 respectively.  

             fits_get_cards(fh, pattern);  
 
     Return cards from  FITS handle FH which match  PATTERN (see fits_match  
     for the syntax of PATTERN).  

 fits_get_coordinate  
 

             fits_get_data_size(fh)  
 
       -or- fits_get_data_size(fh, fix)  
     Computes  the number  of bytes  in data  part of  current HDU  of FITS  
     handle FH.  This value is computed  according to the header part of FH  
     and may be different from the  number of bytes actually written in the  
     data part of the current HDU.  

             fits_get_dims(fh)  
 
       -or- fits_get_dims(fh, fix)  
     Get all  NAXIS* values from current  HDU in FITS handle  FH and return  
     vector  [NAXIS, NAXIS1,  NAXIS2, ...].   If the  value of  any  of the  
     "NAXIS#" card is  zero, then there is no data in  the current unit and  
     fits_get_dims returns [] (nil) in this case.  See fits_get_special for  
     the meaning of FIX.  

             fits_get_gcount(fh)  
 
       -or- fits_get_pcount(fh)  
     Get PCOUNT and  GCOUNT values for FITS handle FH.   PCOUNT shall be an  
     integer  equal  to  the  number  of parameters  preceding  each  group  
     (default value 0).  GCOUNT shall be  an integer equal to the number of  
     random groups present (default value  1).  The total number of bits in  
     the data  array (exclusive of  fill that is  needed after the  data to  
     complete the last record) is given by the following expression:  
         NBITS = abs(BITPIX)*GCOUNT*(PCOUNT + NAXIS1*NAXIS2*...*NAXISm)  

             fits_get_history(fh)  
 
       -or- fits_get_comment(fh)  
     Get COMMENT and  HISTORY values for FITS handle FH.   The result is an  
     array of string(s) or nil if no such cards exists in the header of the  
     current unit.  

             fits_get_keywords(fh)  
 
       -or- fits_get_keywords(fh, ordered)  
     Get list  of FITS keywords defined  in current HDU of  FITS handle HF.  
     The returned value is an array of strings. If ORDERED is true (non-nil  
     and non-zero),  the keywords get  sorted.  Note: the "END"  keyword is  
     always missing in a (non-corrupted) FITS handle.  

             fits_get_list(fh, key)  
 
      Get value of FITS card KEY in FH and returns it as a vector of integers.  
      This function is intended to parse, e.g. the TDIM# cards in BINTABLE  
      extensions.  The syntax of the card must be a string of the form:  
        '(ARG1,ARG2,...)'  
      where ARG1, etc are human readable integer values.  

             fits_get_naxis(fh)  
 
       -or- fits_get_naxis(fh, fix)  
     Get  NAXIS   value  from   current  HDU  in   FITS  handle   FH.   See  
     fits_get_special for the meaning of FIX.  

             fits_get_special(fh, key, id, location, fix)  
 
     Get  value of  a special  FITS card  given its  key  string, numerical  
     identifier and absolute  LOCATION (1 for first FITS  card).  If FIX is  
     true,  various further  verifications  are made  and,  if FITS  strict  
     checking mode is  off, the header may be fixed  in case of unambiguous  
     error.  

             fits_get_xtension(fh)  
 
     Get XTENSION value from current HDU in FITS handle FH.  The returned  
     value is a scalar string in upper case letters with the name of the  
     extension (without trailing spaces); "IMAGE" is returned for the  
     primary HDU.  

             fits_goto_hdu(fh, hdu)  
 
     Move FITS handle FH to Header  Data Unit number HDU (starting at 1 for  
     the primary HDU) and parse the  header part of the new unit.  Contents  
     of FH  is updated with  header part of  new HDU.  To allow  for linked  
     calls, the returned value is FH.  

 fits_id  
 

             fits_id(card)  
 
       -or- fits_ids(cards)  
     Convert  FITS  card(s) or  FITS  card  name(s)  into unique  numerical  
     identifier.  CARD is a scalar string and CARDS (with an S) is an array  
     of string(s) (including a  scalar).  Only the keyword part (characters  
     1:8) of CARD(S) is relevant; cards shorter than 8 characters yield the  
     same identifier as if they were padded (right filled) with spaces.  In  
     other words, all the values  returned by the following expressions are  
     identical:  
       fits_id("SIMPLE = T / conforming FITS file");  
       fits_id("SIMPLE ");  
       fits_id("SIMPLE");  

             fits_index_of_table_field(fh, name)  
 
     Returns index(es) of FITS table columns with their TTYPE# value  
     matching array of string(s) NAME.  The table header is read from  
     current HDU of FITS handle FH.  

             fits_info, fh;  
 
       -or- fits_info, fh, hdu  
       -or- fits_info, filename;  
       -or- fits_info, filename, hdu;  
     Prints header contents of current HDU in FITS handle FH or all HDU's  
     in FITS file FILENAME.  If argument HDU is given, only this header unit  
     get printed out (HDU may be an array).  

             fits_init;  
 
     (Re)initializes FITS private  data.  Normally you do not  have to call  
     this  routine  because  this  routine  is  automatically  called  when  
     "fits.i" is  parsed by Yorick.   You may however need  to explicitely  
     call  fits_init  if  you  suspect  that some  FITS  private  data  get  
     corrupted or if you want to tune FITS strict/sloopy behaviour.  
     If keyword SLOOPY  is true (non-nil and non-zero)  some discrepancy is  
     allowed (for reading FITS file only); otherwise strict FITS compliance  
     is applied.  If SLOOPY is true, lower case Latin letters have the same  
     meaning  as their  upper  case counterparts,  most control  characters  
     become identical to regular spaces.  
     According to FITS standard, the only characters permitted for keywords  
     are  upper  case  (capital)  Latin alphabetic,  numbers,  hyphen,  and  
     underscore.  Leading and embedded blanks are forbidden.  If you cannot  
     read a FITS file because it does not confrom to this rule, you can use  
     keyword ALLOW (a string or an array of characters) to allow additional  
     characters for FITS keywords.  For instance:  
       fits_init, allow="/."; // fix for invalid headers made by IRAF  
     make characters '/'  and '.'  acceptable in FITS  keywords.  Note that  
     you  must apply fits_rehash  (to see)  to _every_  FITS handle  in use  
     whenever you change  the set of allowed characters  (because this will  
     probably corrupt the values of numerical identifiers of FITS card) ...  
     It is  therefore a good idea  to change the set  of allowed characters  
     before using any FITS routines.  
     Keyword  BLANK can  be  used to  add  more characters  that should  be  
     considered as blanks (spaces)  when parsing FITS header/keywords.  The  
     value  of BLANK  must  be a  string  or an  array  of characters,  for  
     instance: BLANK="\t\r\v\n".  Note that this break strict compliance to  
     FITS standard.  

             fits_is_integer(x)  
 
     Returns true if array X is of integer type.  

             fits_is_integer_scalar(x)  
 
     Returns true if array X is a scalar of integer type.  

             fits_is_real_scalar(x)  
 
     Returns true if array X if of real type (i.e. double or float).  

             fits_is_scalar(x)  
 
     Returns true if X is a scalar.  

             fits_is_string_scalar(x)  
 
     Returns true if array X is a scalar of string type.  

             fits_key(id)  
 
     Convert  (array   of)  FITS   numerical  identifier(s)  ID   into  the  
     corresponding string FITS keyword(s) without trailing spaces.  

             fits_list, fh;  
 
       -or- fits_list(fh)  
     Get the names of  the FITS extensions in FH.  FH can  be the name of a  
     FITS file  or a FITS handle  FH (the input handle  is left unchanged).  
     When called  as a  subroutine, the list  is printed to  terminal; when  
     called as  a function, the returned  value is a string  array with the  
     names of the FITS extensions in FH.  

             fits_map(op, src)  
 
     Map scalar function OP onto array argument SRC to mimics element-wise  
     unary operation.  

 fits_match  
 

             fits_move, a, i, j;  
 
     Move I-th element of array A  in place of J-th element.  The operation  
     is done in-place.  

             fits_move_card(fh, from, to);  
 
     Change location of FROM-th card to  index TO into FITS handle FH.  The  
     operation is made in place.  

             fits_new_bintable(fh)  
 
       -or- fits_new_bintable(fh, comment)  
     Starts a new  binary table FITS extension.  This  routine starts a new  
     FITS extension with  name "BINTABLE" and pre-set FITS  cards needed to  
     describe the  table with fake values  (the correct values  will be set  
     when  fits_write_bintable  is called  to  actually  write the  table).  
     After calling this  routine, the user can add new  FITS cards (but not  
     XTENSION,  BITPIX,   NAXIS,  NAXIS1,  NAXIS2,   GCOUNT,  nor  PCOUNT).  
     Optional argument COMMENT is the comment string for the XTENSION card.  
     The returned value is FH.  

             fits_new_hdu(fh, xtension)  
 
       -or- fits_new_hdu(fh, xtension, comment)  
     Starts a new extension in FITS  file open for writing.  FH is the FITS  
     handle, XTENSION is  the name of the FITS extension  and COMMENT is an  
     optional string comment.  After calling fits_new_hdu, there is no need  
     to call:  
       fits_set, FH, "XTENSION", XTENSION, COMMENT;  
     since this is already done by this routine.  However, beware that FITS  
     standard requires that, if any  extension is present in the file, that  
     the keyword "EXTEND" with logical  value 'T' (true) must appear in the  
     primary header.  

             fits_new_image(fh, data)  
 
       -or- fits_new_image(fh, bitpix=..., dimlist=...)  
     Starts a new image (array) FITS extension in handle FH and returns FH.  
     This routine starts a new FITS extension with name "IMAGE" and pre-set  
     FITS cards  needed to describe  the array data according  to keywords:  
     BITPIX, DIMLIST, BZERO, and BSCALE.   If argument DATA is given, it is  
     used  to guess  the  bits per  pixel  and the  dimension  list if  not  
     specified by the keywords BITPIX and DIMSLIST respectively.  

             fits_next_hdu(fh)  
 
     Move FITS handle FH to next Header Data Unit and parse the header part  
     of the  new unit.  Contents of FH  is updated with header  part of new  
     HDU.  To allow for linked calls, the returned value is FH.  

             fits_nth(n)  
 
     Returns a string in the form "1st", "2nd", "3rd" or "#th" where # is  
     the human readable value of integer N.  

             fits_open(filename)  
 
       -or- fits_open(filename, filemode)  
     Opens  the FITS  file FILENAME  according to  FILEMODE.   The returned  
     value is a FITS handle used  in most other FITS routines.  FILEMODE is  
     one of:  
       "r" or 'r' - read mode,  the header of the primary  HDU get read and  
                    is parsed.  
       "w" or 'w' - write   mode,  new  file  is  created  (unless  keyword  
                    OVERWRITE is true, FILENAME must not already exists).  
       "a" or 'a' - append  mode, stream  get positionned  at last HDU, the  
                    header of the last HDU get read and parsed.  
     The default FILEMODE is "r" -- open an existing FITS file for reading.  
     Keyword ENCODING can  be used to change the data  encoding of the FITS  
     file which is  "xdr" for a regular FITS file  (XDR means eXternal Data  
     Representation,  which is  natively  used by  all  IEEE compliant  big  
     endian machine).  The value of the keyword is a string like:  
       "xdr", "sun"    - eXternal Data Representation (the default)  
       "native"        - native data representation (i.e. no conversion)  
       "i86", "pc"     - IEEE little endian machines  
       ...  
     see documentation for "__sun" for  a list of supported encodings. Note  
     that  using  an encoding  different  from  IEEE  big endian  (or  XDR)  
     violates FITS standard.  
     Keyword OVERWRITE can be used to force overwriting of an existing file  
     (otherwise it is an error to create a file that already exists).  

             fits_pack_bintable(ptr)  
 
       -or- fits_pack_bintable(ptr, list)  
     Packs binary  table PTR  into a  single array; PTR  must be  a pointer  
     array  (e.g. as  the one  returned by  fits_read_bintable  which see).  
     Second  argument LIST  can be  specified  to select  or re-order  some  
     fields: LIST is a vector of indices of selected and re-ordered fields,  
     the result will be as if  PTR(LIST) was given as unique argument.  The  
     returned array is NROWS-by-NCOLS where NROWS is the first dimension of  
     all fields (which must be the same) and NCOLS is the sum of the second  
     dimension of all fields.  

             fits_pad_hdu(fh)  
 
     Fix file size in handle FH to a multiple of FITS blocking factor (2880  
     bytes) by writting null or space characters at the end of the file and  
     update FH offsets accordingly.  FH must be open for writing.  

 fits_parse  
 

                       a = fits_read(filename)  
 
       -or- local fh; a = fits_read(filename, fh)  
     Open  FITS file  FILENAME and  read data.   FH is  an  optional output  
     symbol where  the FITS handle  will be stored  for future use  such as  
     moving  to  a  FITS  extension  in  the  same  file  and  reading  its  
     header/data.  (Note:  a FITS handle is  a Yorick list  that contains a  
     file  handle and  all header  information from  the current  HDU.)  By  
     default, the data get read from  the first HDU but this can be changed  
     with the HDU keyword (default  HDU=1, i.e., primary HDU).  If data get  
     read  from the  primary  HDU or  a  FITS image  extension, the  result  
     returned  by  the  function  fits_read()  is a  numerical  array  (see  
     fits_read_array); if the data get  read from a binary table extension,  
     the result is a vector of pointers (see fits_read_bintable).  
     Keyword ENCODING has the same meaning as in fits_open (which see).  
     Keywords WHICH and RESCALE have the same meaning as in fits_read_array  
     (which see).  These keywords are ignored if HDU to read is not primary  
     HDU nor an "image" extension.  
     Keywords   PACK   and   SELECT   have   the   same   meaning   as   in  
     fits_read_bintable (which see).  

             fits_read_array(fh)  
 
     Gets "image" (actually a Yorick array) from current HDU of FITS handle  
     FH.  Note that the result may be [] (nil) if the current unit contains  
     no data.  
     Keyword  WHICH may  be  used  to indicate  which  sub-array should  be  
     returned.  WHICH always  applies to the last dimension  of the "image"  
     data  stored in current  HDU.  For  instance, if  the array  DATA with  
     dimensions  (235,453,7)  is  stored  in  the  current  FITS  HDU,  the  
     sub-array DATA(,,4) can be obtained by:  
         fits_read_array(FH, which=4);  
     If keyword RESCALE is true,  returned values get rescaled according to  
     FITS keywords BSCALE and BZERO.  If RESCALE=2 and one of BSCALE and/or  
     BZERO exists in  the FITS header and  BITPIX was 8, 16, 32,  or -32, a  
     single precision  array (float)  is returned.  If  RESCALE is  not set  
     (nil), the  default is to  rescale data values  if BSCALE is not  1 or  
     BZERO is not  0 (i.e. the default is RESCALE=1).  In  order to get raw  
     data (i.e. as written in the file), use RESCALE=0.  

             fits_read_bintable(fh)  
 
     Reads a binary table in current  HDU of FITS handle FH and returns the  
     fields of  the table as  a pointer array  (i-th field of the  table is  
     pointed  by  i-th  pointer  element).   Empty fields  and  fields  for  
     unsupported data  types (bit array  and array descriptor) result  in a  
     null pointer (&[]).  The geometry  of the arrays pointed by the result  
     will be  NROWS-by-NCOLS(i) where  NROWS is the  number of rows  in the  
     table and NCOLS(i) is the repeat  count of the i-th field in the table  
     (see fits_write_bintable).  If NCOLS(i)  = 1, the i-th pointer element  
     is the address of a NROWS vector, i.e. not a NROWS-by-1 array.  
     Keyword SELECT can be used to retain only some fields of the table (or  
     re-order them).  For instance,  use SELECT=[2,5,3] to return only 2nd,  
     5th and 3rd fields (in that  order) of the table.  The fields can also  
     be selected by their names, e.g. SELECT=["flux","distance"] (note that  
     trailing spaces and case is not significant for the field names).  
     If keyword  PACK is  true, fits_pack_bintable (which  see) is  used to  
     pack the  columns of  the binary table  into a single  array (possibly  
     after selection/re-ordering by SELECT).  
     If keyword TRIM is true,  then trailing spaces get removed from string  
     fields (this has no effect if RAW_STRING is true).  
     If keyword RAW_STRING is true,  fields made of char's ('A' format) are  
     returned as  arrays of char's.  The  default is to  convert 'A' format  
     fields into 1-by-NROWS array of strings.  
     If  keyword  RAW_LOGICAL is  true,  logical  fields  ('L' format)  are  
     returned as  arrays of char's.  The  default is to  convert 'L' format  
     fields  into array of  int's as  follows: 'T'  -> 1  (true), 'F'  -> 0  
     (false), and any other character ->  -1 (bad).  The 'bad' value can be  
     set by keyword BAD (default is -1).  

             fits_read_bintable_as_hashtable(fh)  
 
       -or- fits_read_bintable_as_hashtable(fh, h)  
     Read  binary table  in current  HDU (see  fits_read_bintable)  of FITS  
     handle FH  and make it into a  hash table.  If optional  argument H is  
     given, it  must be  an existing  hash table to  be augmented  with the  
     contents of the binary table.  The (augmented) hash table is returned.  
     This function can only be used with the hash table extension.  
     The  members of  the  hash table  get  named after  the  value of  the  
     'TTYPEn' card  converted to lowercase  (where n is the  field number).  
     For missing  'TTYPEn' cards,  the value of  keyword FORMAT is  used to  
     define the member name  as swrite(format=FORMAT,n).  The default value  
     for FORMAT is "_%d".  If  FORMAT is specified, it must contain exactly  
     one directive to write an  integer and no other format directives.  If  
     a card 'TUNITn' exists, its  value is stored into member with "_units"  
     appended to the corresponding field name.  
     Keywords SELECT, RAW_STRING, RAW_LOGICAL and BAD have the same meaning  
     as in fits_read_bintable.  

             fits_read_header(fh)  
 
     (Re)read  and parse  header of  current  HDU of  FITS handle  FH.  
     Contents of FH is updated with  header part of new HDU.  To allow  
     for linked calls,  the returned value is FH.   If the current HDU  
     is empty (i.e. last HDU in the file), the header will be empty.  

             fits_rehash(fh);  
 
     (Re)compute array of numerical identifier for FITS handle FH (operation  
     is done in-place) and return FH.  

             fits_rewind(fh)  
 
     Move FITS handle FH to primary Header Data Unit and parse the header part  
     of the unit.  FH is returned when called as a function.  

             fits_set, fh, key, value;  
 
       -or- fits_set, fh, key, value, comment;  
     Set (or adds) FITS card in header  of FITS handle FH.  KEY is the card  
     name (FITS keyword)  and must be a scalar string,  VALUE is the scalar  
     value of the card and COMMENT is an optional string comment.  
     Commentary cards -- for which KEY  is one of "COMMENT, "HISTORY" or ""  
     (blank) -- get appended to the  existing cards in the header of FH (if  
     the VALUE of a commentary card is too long, it may occupy several FITS  
     cards).   For any  other  kind of  cards,  the new  card replaces  the  
     existing one, if any; or  get appended to the existing cards.  Special  
     cards that must appear in a precise order ("SIMPLE", "BITPIX", "NAXIS"  
     and "NAXIS#") must  be added in the correct order  (their value can be  
     modified afterward).  The "END"  card is not  needed since it  will be  
     automatically written when required.  

             fits_set_dims(fh, dimlist)  
 
      Set NAXIS  and NAXIS1,  NAXIS2, ... values  into current HDU  of FITS  
      handle FH according to dimension list DIMLIST.  DIMLIST may be empty.  

             fits_strcmp(a, b)  
 
     Returns non-zero where (array of) strings A and B are the same in FITS  
     sense, i.e., ignore case and trailing ordinary spaces (code 0x20). For  
     instance, "Hello" and "HELLO " are the same strings.  

 fits_tolower  
 

             fits_tolower(s)  
 
       -or- fits_toupper(s)  
     Converts a string or an array of strings S to lower/upper case letters.  

             fits_trim(s)  
 
     Removes trailing  spaces (character 0x20) from scalar  string S (note:  
     trailing spaces are not significant in FITS).  

             fits_write, filename, data;  
 
       -or- fits_write(filename, data)  
     Creates a new FITS file FILENAME  and write array DATA in primary HDU.  
     When called  as a function,  the result is  a FITS handle that  can be  
     used to append extensions to the file.  
     FITS "bits-per-pixel"  can be specified by  keyword BITPIX; otherwise,  
     BITPIX   is   automatically   guessed   from  the   data   type   (see  
     fits_bitpix_of).  
     Keywords  EXTEND, TEMPLATE, HISTORY  COMMENT, BSCALE,  BZERO, ENCODING  
     and OVERWRITE have the same meaning as in fits_create (to see).  
     If BITPIX is explicitely specified  and corresponds to an integer file  
     type (8, 16 or 32) and neither BSCALE nor BZERO are specified, optimal  
     BSCALE  and BZERO  values  will be  automatically  computed thanks  to  
     fits_best_scale (which see).  

             fits_write_array, fh, data;  
 
     Write  array DATA  into  curent HDU  of  FITS handle  FH.   DATA is  a  
     so-called "image"  in FITS jargon but  it can be a  numerical array of  
     any-dimension.   FITS cards BITPIX,  BSCALE and  BZERO are  taken into  
     account to convert data values into file values.  The file values are:  
         (DATA  - BZERO)/BSCALE  
     with BZERO=0 and  BSCALE=1 by default (i.e. if not found  in FH) or if  
     keyword RESCALE  is explicitely set  to zero.  The values  are further  
     subject to rounding  to the nearest integer and  clipping for positive  
     BITPIX.  If  keyword RESCALE is  explicitely set to false  (zero), the  
     file values get written without BSCALE/BZERO scale conversion.  
     The N dimensions of DATA must  match the values of the NAXIS1, NAXIS2,  
     ..., NAXISn  cards of  the FITS  file (it is  assumed that  the header  
     information  stored in  FH  are synchronized  to  the header  actually  
     written) extra dimensions in the  FITS file are considered as possible  
     data slices.  By  default, the first data slice  get written.  Keyword  
     WHICH may be used to write a given slice of data.  The value WHICH may  
     be less or equal zero to choose  a slice with respect to the last one.  
  EXAMPLE:  
     The following  example creates a FITS file  with a 100-by-45-by-4-by-7  
     "image" data made of random  values computed and written one 100-by-45  
     slice at a time:  
       fh = fits_create("newfile.fits", bitpix=16, dimlist=[4,100,45,4,7],  
                        bscale=1e-4, bzero=0.0);  
       fits_write_header, fh;  
       nslices = 4*7; // product of last FITS dimensions  
       for (i=1 ; i<=nslices ; ++i)  
         fits_write_array, fh, random(100, 45), which=i;  
       fits_close, fh;  

             fits_write_bintable(fh, ptr)  
 
     Writes contents  of pointer PTR in  a binary table in  FITS handle FH.  
     Arrays pointed  by PTR  become the  fields of the  table (in  the same  
     order as  in PTR) and must  all have 1  or 2 dimensions with  the same  
     first  dimension  (i.e. the  number  of  rows  in the  table),  second  
     dimensions can have any values and may all be different: they count as  
     the number of 'columns' of the field.  In other words:  
       *PTR(i) = i-th  field  in the table,  is an  NROWS-by-NCOLS(i) array  
                 where  NROWS  is the  number  of  rows  in the  table  and  
                 NCOLS(i) is  the repeat  count of the  i-th field;  it can  
                 also be simply a NROWS element vector if NCOLS(i) = 1.  
     In the current  version of the routine, only  arrays of numbers (char,  
     short, int,  long, float,  double or complex)  and vectors  of strings  
     (you  can  use several  vectors  to  circumvent  this limitation)  are  
     supported.  Before writing  the data part of a  binary table, you must  
     creates proper header:  
        fits_new_bintable, fh;        // starts a new binary table  
        fits_set, fh, "...", ...;     // (optional) set more info. in header  
        fits_set, ...;  
        fits_write_bintable, fh, ptr; // write binary table  
     If  FITS cards "TFORM#"  (with #  equal to  the field  number) already  
     exists   in  the  current   header,  fits_write_bintable   checks  the  
     consistency of the  corresponding data field in PTR  (and performs any  
     required conversion);  otherwise, the format  is automatically guessed  
     and set accordingly in the header of the binary table.  
     If keyword LOGICAL is true (non nil and non-zero) then arrays of int's  
     in  PTR  are considered  as  logical arrays  and  saved  as arrays  of  
     characters: 'F' for false, 'T' for true or '\0' for bad/invalid value.  
     Following Yorick's convention, a "false"  value is integer zero in the  
     arrays of  int's and  a "true" is  any non-zero integer.   However, if  
     LOGICAL has the  special value 2, then strictly  positive integers are  
     treated as "true" values and strictly negative integers are treated as  
     invlaid  values.  Note  that this  only  affect arrays  of int's  (not  
     long's  nor short's nor  char's).  The  default is  to save  arrays of  
     int's as array of 32 bits integers.  
     The returned value is FH.  

             fits_write_header(fh)  
 
     Write  header  information of  FITS  handle  FH  into current  HDU  of  
     associated file.   It is possible to  re-write header as  long as this  
     would not overwrite existing written data if any (i.e. the new header,  
     rounded up  to a multiple of 2880  bytes, must not be  longer than the  
     old one or there must be no data written.  

             obsolete FITS routines  
 
     In order to help you to upgrade your code and use the new FITS API,  
     you can use the following equivalence table:  
       fitsAddComment, hdr, str;    ==>  fits_set, fh, "COMMENT", str;  
       fitsAddHistory, hdr, str;    ==>  fits_set, fh, "HISTORY", str;  
       fitsWrite, name, data;       ==>  fits_write, name, data;  
       fitsWrite, name, data, hdr;  ==>  fits_write_array, fh, data;  
       fitsRead(name);              ==>  fits_read(name);  
       data = fitsRead(name, hdr);  ==>  data = fits_read(name, fh);  
     where NAME is the file name, STR is a string comment, HDR is the  
     header structure (obsolete but see fitsMakeOldHeader), FH is  
     the (new) FITS handle and DATA is an array of numbers.  
     The following old routines have no real equivalent:  
       fitsHeader  
       fitsFixHeader  
       fitsRescale  

             FitsHeader - a Yorick structure  defined to store (part of) FITS  
 
     header information.  The structure has the following members:  
     bitpix   - bits-per-pixel:  8  pixel values are unsigned bytes  
                                16  pixel values are signed 2-byte integers  
                                32  pixel values are signed 4-byte integers  
                               -32  pixel values are 4-byte floating points  
                               -64  pixel values are 8-byte floating points  
     naxis    - number of axis  
     axis(k)  - number of pixel along k-th axis  
     bscale   - pixelValue = BZERO+BSCALE*fileValue  
     bzero    - pixelValue = BZERO+BSCALE*fileValue  
     bunit    - brightness unit  
     datamax  - maximum data value in the file  
     datamin  - minimum data value in the file  
     object   - image name  
     date     - date of file creation (dd/mm/yy)  
     date_obs - date of data acquisition (dd/mm/yy)  
     origin   - institution  
     instrume - data acquisition instrument  
     telescop - data acquisition telescope  
     observer - observer name/identification  
     history  - newline separated history lines  
     comment  - newline separated comment lines  
     epoch    - epoch of coordinate system (year)  
     crval(k) - coord = CRVAL+(pixel-CRPIX)*CDELT  
     crpix(k) - coord = CRVAL+(pixel-CRPIX)*CDELT  
     cdelt(k) - coord = CRVAL+(pixel-CRPIX)*CDELT  
     ctype(k) - type of physical coordinate  
     crota(k) - rotation angle of axis No. #  

 fitsMakeOldHeader  
 

 fitsObsolete  
 

 fitsOldHeaderKeywords  
 

             fitsMakeOldHeader(fh)  
 
     Convert header information in FITS handle FH into the obsolete FitsHeader  
     structure.