idlastro / Miscellaneous (Non-Astronomy) Procedures: BLKSHIFT

[Source code]

NAME
BLKSHIFT
PURPOSE
Shift a block of data to a new position in a file (possibly overlapping)
CALLING SEQUENCE
BLKSHIFT, UNIT, POS, [ DELTA, TO=TO, /NOZERO, ERRMSG=ERRMSG, 
          BUFFERSIZE=BUFFERSIZE ]
DESCRIPTION
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) then
the file is truncated at the new end.using TRUNCATE_LUN.
INPUTS
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.
KEYWORD PARAMETERS
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.   Note that in same systems (e.g. MacOS) the gaps will
         always be zeroed whether or not /NOZERO is set.
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.  
                     BLKSHIFT, UNIT, POS, DElTA, 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)
ORIGINAL AUTHOR
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craig.markwardt@nasa.gov
MODIFICATION HISTORY
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 
Assume since V5.5, remove VMS support  W. Landsman  Sep 2006
Assume since V5.6, TRUNCATE_LUN available  W. Landsman Sep 2006
MacOS can point beyond EOF    W. Landsman   Aug 2009
Use V6.0 notation  W. Landsman Aprl 2014