Name

---

      CHECKSUM32

Purpose

---

      To compute the 32bit checksum of an array (ones-complement arithmetic)

Explanation

---

      The 32bit checksum is adopted in the FITS Checksum convention
      http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html

Calling Sequence

---

      CHECKSUM32, array, checksum, [/FROM_IEEE, /NoSAVE]

Inputs

---

      array - any numeric idl array. If the number of bytes in the array is
              not a multiple of four then it is padded with zeros internally
              (the array is returned unchanged). Convert a string array
              (e.g. a FITS header) to bytes prior to calling CHECKSUM32.

Outputs

---

      checksum - unsigned long scalar, giving sum of array elements using
                  ones-complement arithmetic

Optional Input Keyword

---

      /FROM_IEEE - If this keyword is set, then the input is assumed to be in
          big endian format (e.g. an untranslated FITS array). This keyword
          only has an effect on little endian machines (e.g. Linux boxes).
      /NoSAVE - if set, then the input array is not saved upon exiting. Use
          the /NoSave keyword to save time if the input array is not needed
          in further computations.

Method

---

      Uses TOTAL() to sum the array into a double precision variable. The
      overflow bits beyond 2^32 are then shifted back to the least significant
      bits. Due to the limited precision of a DOUBLE variable, the summing
      is done in chunks determined by MACHAR(). Adapted from FORTRAN code in
      heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/general/checksum/node30.html
      Could probably be done in a cleverer way (similar to the C
      implementation) but then the array-oriented TOTAL() function could not
      be used.

Restrictions

---

      (1) Not valid for object or pointer data types

Example

---

      Find the 32 bit checksum of the array x = findgen(35)
      IDL> checksum32, x, s ===> s = 2920022024
  FUNCTION CALLED:
      HOST_TO_IEEE, IS_IEEE_BIG(), N_BYTES()

Modification History

---

      Written W. Landsman June 2001
      Work correctly on little endian machines, added /FROM_IEEE and /NoSave
                  W. Landsman November 2002
      Pad with zeros when array size not a multiple of 4 W.Landsman Aug 2003
      Always copy to new array, somewhat slower but more robust algorithm
          especially for Linux boxes W. Landsman Sep. 2004
      Sep. 2004 update not implemented correctly (sigh) W. Landsman Dec 2004
      No need to byteswap 4 byte datatypes on little endian W. L. May 2009
      Use /INTEGER keyword to TOTAL() function W.L. June 2009