BLKSHIFT

   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov

   Shift a block of data to a new position in a file (possibly overlapping)

   File I/O

   BLKSHIFT, UNIT, POS, [ DELTA, TO=TO, /NOZERO, ERRMSG=ERRMSG,
             BUFFERSIZE=BUFFERSIZE ]

  BLKSHIFT moves a block of data forward or backward, to a new
  position in a data file.  The old and new positions of the block
  can overlap safely.
  The new position can be specified with either the DELTA parameter,
  which gives the number of bytes to move forward (positive delta) or
  backward (negative delta); or the TO keyword, which give the new
  absolute starting position of the block.
  The block can be moved beyond the current end of file point, in
  which case the intervening gap is filled with zeros (optionally).
  The gap left at the old position of the block is also optionally
  zero-filled.    If a set of data up to the end of the file is being
  moved forward (thus making the file smaller) and the IDL version is
  5.6 or larger (so that the TRUNCATE_LUN procedure is available) then
  the file is truncated at the new end.

   UNIT - a logical unit number, opened for reading and writing.
   POS - POS[0] is the position of the block in the file, in bytes,
         before moving.  POS[1], if present, is the size of the block
         in bytes.  If POS[1] is not given, then the block is from
         POS[0] to the end of the file.
   DELTA - the (optional) offset in bytes between the old and new
           positions, from the start of the block.  Positive values
           indicate moving the data forward (toward the end of file),
           and negative values indicate moving the data backward
           (toward the beginning of the file).  One of DELTA and TO
           must be specified; DELTA overrides the TO keyword.
           Attempts to move the block beyond the end of the file will
           succeed.  A block can never be moved beyond the beginning
           of the file; it will be moved to the beginning instead.

   TO - the absolute file offset in bytes for the new start of the
        block.  One of DELTA and TO must be specified; DELTA
        overrides the TO keyword.
   NOZERO - if set, then newly created gaps will not be explicitly
            zeroed.  However, for some operating systems (Mac and
            VMS), zeroing is required and will be done anyway.
   ERRMSG - If defined and passed, then any error messages will be
            returned to the user in this parameter rather than
            depending on the MESSAGE routine in IDL.  If no errors
            are encountered, then a null string is returned.  In
            order to use this feature, ERRMSG must be defined first,
            e.g.
                       ERRMSG = ''
                       FXBGROW, ERRMSG=ERRMSG, ...
                       IF ERRMSG NE '' THEN ...
   BUFFERSIZE - the maximum buffer size for transfers, in bytes.
                Larger values of this keyword impose larger memory
                requirements on the application; smaller values will
                lead to more transfer operations.
                Default: 32768 (bytes)

   Written, CM, Apr 2000
   Documented and re-written, CM, 20 Jul 2000
   Renamed from FXSHIFT to BLKSHIFT, CM, 21 Jul 2000
   Documentation, CM, 12 Dec 2002
   Truncate if moving data block forward from  the end of file
             using TRUNCATE_LUN   W. Landsman Feb. 2005

[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]