1 XCOPY
  A program to copy files, with one major improvement on VMS COPY.

  Should the copy fail (for example, because one file is on a remote node,
  and the connection is lost), XCOPY returns (to SYS$OUTPUT, and DCL via
  symbols) sufficient information about the failure to enable the copy to
  be restarted from the point of failure. Only disk-to-disk transfers are
  supported.

  Format:

  $ XCOPY infile [,infile...] outfile [/qualifiers]
2 More_about_XCOPY
  I wrote XCOPY after spending two days trying to send a number of
  300-block files over a 1200 baud dial-up DECnet connection, which had
  a mean uptime of about five minutes. XCOPY allows you to restart any
  failed transfer, even halfway through a wildcard, from the block at
  which it failed. 

  XCOPY typically works at half the speed of VMS COPY. However, if you
  even suspect that your network connection might go down, it will probably
  pay for itself very quickly.

  Talking about paying: this program is FREE. Users of PC software may be
  familiar with a phenomenon called shareware, whereby you pay for software
  after you use it. I do not exclude the possibility that this program may
  evolve into shareware or even prepaid software at some future time, and I
  reserve all rights to the software. You may copy it freely and give it
  away to anybody you like, as long as this text, and the equivalent
  notices in the sources, remain intact. If you find XCOPY so useful that
  you feel an urge to pay for it, send $10 to your favourite charity.

  You should have received both C and Pascal source versions of XCOPY. The
  Pascal version is for demonstration purposes only; all distributed
  executable version are compiled from the C version. If you have access
  to VAX C (or if you have access to VAX Pascal and are an optimist), you
  are encouraged to review the program and compile it yourself before
  using it, not because I think that the software is so wonderful that
  you must read it (1000 lines in one module does not constitute wonderful
  coding practice, for a start), but because this is a good way to protect
  yourself against some of the less savoury characters out there.

  XCOPY requires no privileges to run (obviously, NETMBX is needed for
  remote operations). Do not install it with privileges !

  If you have any questions, comments, or bugs to report, please contact:

         Nick Brown
         c/o Albert van Dalsumlaan 119
         3584 HC Utrecht
         The Netherlands

  Please do not send tapes in the first instance as the above address is
  only for forwarding of letters; anything heavier will be thrown away. If
  you report a fixable bug I will endeavour get in touch with you to
  arrange a fix. If you require a reply, please send an International
  Reply Coupon; this is a kind of stamp that works anywhere, available
  from any Post Office. Send one that is valid for anywhere in the world,
  since I don't know where I'm going to be.

  Naturally, since this is free software, I accept no responsibility for
  any loss or damage to any data. Nor do I offer any warranty that this
  software works as described under any particular circumstances. In
  other words, no price, no guarantee.

  Quick advertisement: my other masterpieces, FRAG (yes, yet another disk
  fragmentation indicator), and WHO (a sort of super network-wide SHOW
  USERS/SYSTEM/etc), should also be available somewhere in the vicinity
  of this program. Please feel free to use and/or distribute them.
2 Parameters
Infile
 Infile

  The file, or list of files, to be copied. Wildcards are supported and
  (are intended to) work similarly to VMS COPY. Exact compatibility is
  certainly NOT provided; for example, any error (such as a missing
  target directory) causes XCOPY to stop, whereas VMS COPY would process
  the remaining input files.

Outfile
 Outfile

  The name of the output file to be created. Missing or wildcarded
  parts of the filespec default to the same as the input file, in
  (approximately) the same way as VMS COPY. If /FIRST_BLOCK (see Qualifiers)
  is greater than 0, the program will attempt to open an existing output
  file.
2 Qualifiers

/CONFIRM
 /CONFIRM
 /NOCONFIRM (default)

  Specifies that the user be prompted for confirmation of each file copy.
  Possible responses are YES, NO, ALL, or QUIT. ALL causes all subsequent
  copies to be done without confirmation; QUIT terminates XCOPY immediately.

/FIRST_BLOCK
 /FIRST_BLOCK=n

  Specifies the first block of the file to be copied. The default is 0,
  which implies that the whole file will be copied. (A value of 1 also
  causes the whole file to be copied, but in this case XCOPY assumes that
  the file already exists; for example, after a previous XCOPY failed
  writing the first block of a file).

  When more than one input file is specified, this qualifier only applies
  to the first file copied (also determined by /WILD_FILE). Subsequent
  files are created as if they were copied with /FIRST_BLOCK=0.

/LAST_BLOCK
 /LAST_BLOCK=n

  Specifies the last block of the file to be copied. The default is the
  end of file block. This qualifier is principally intended for use in
  XCOPY program development and/or checkout.

/LOG
 /LOG
 /NOLOG (default)

  Specified that a success message be produced after the file is copied.

/RMS_IOSIZE
 /RMS_IOSIZE=n

  Specified the number of blocks to be copied by RMS in a single operation.
  A higher value will generally increase the performance of XCOPY over
  faster transmission media (such as Ethernet), while a lower value will
  minimise the amount of data that needs to be retransmitted if the
  operation needs to be restarted.

  The default value is 4 blocks, the minimum is 1, and the maximum is 127.
  Disk blocks are 512 bytes in size.

/TRACE
 /TRACE[=n]
 /NOTRACE (default)

  Specifies that a message will be output every N blocks, confirming the
  progress of the copy. If N is omitted, a message will be output after
  approximately every 10 percent of the file has been copied. If /NOTRACE
  is specified, or if the /TRACE qualifier is omitted, no such message
  will be produced.

  The value of N is rounded up to the nearest multiple of the value of the
  qualifier /RMS_IOSIZE.

  /TRACE also implies /LOG.

/WILD_FILE
 /WILD_FILE=n

  Specifies the first file within the input wildcard list to be specified.
  This qualifier is used when restarting a failed wildcard or filename-list
  copy. In practical terms it means "skip n-1 files" before selecting the
  first one to copy.

  Note that if the expansion of the input filespec has changed since the
  previous time XCOPY was run (for example, because one of the files has
  been deleted in the meantime), the effects of restarting are
  unpredictable.
2 DCL_symbols

   In the event of failure, the DCL symbol XCOPY_FAILED_BLOCK contains (as
   a decimal string) the number of the failed block, and XCOPY_FAILED_FILE
   contains the file number (relative to the input filespec) of the file
   containing the failed block. XCOPY can then be restarted with the
   qualifiers /FIRST_BLOCK='XCOPY_FAILED_BLOCK' and
   /WILD_FILE='XCOPY_FAILED_FILE'.

   If the copy succeeds, XCOPY_FAILED_BLOCK is set to 0, and
   XCOPY_FAILED_FILE to the number of files in the input file
   specification list, plus one. Restarting XCOPY with these values will
   not copy anything.
2 Examples

  1.   $ XCOPY BIGFILE.DAT REMOTE::DUA0:[DIR]
       %XCOPY-F-WRITEFAIL, failed writing block 246 of
        REMOTE::DUA0:[DIR]BIGFILE.DAT;1
       $ XCOPY BIGFILE.DAT REMOTE::DUA0:[DIR] /FIRST=246

       The copy is restarted from the first untransmitted block.

  2.   $ XCOPY SMALLFILE.DAT REMOTE::DUA0:[DIR] /TRACE=20
       %XCOPY-S-COPYING, starting copy of DUA1:[EXAMPLE]SMALLFILE.DAT;1
       to REMOTE::DUA0:[DIR]SMALLFILE.DAT
       %XCOPY-I-TRACE, successfully copied block 20
       %XCOPY-I-TRACE, successfully copied block 40
       %XCOPY-S-COPIED, DUA1:[EXAMPLE]SMALLFILE.DAT;1 copied to
        REMOTE::DUA0:[DIR]SMALLFILE.DAT;1 (47 blocks)

       This shows the successful copy of a file.

  3.   $ XCOPY_FAILED_BLOCK = 0
       $ XCOPY_FAILED_FILE = 0
       $ loop:
       $ on error then goto loop
       $ XCOPY 'P1' 'P2' /TRACE /FIRST_BLOCK='XCOPY_FAILED_BLOCK' -
                                /WILD_FILE='XCOPY_FAILED_FILE'

       This DCL procedure fragment shows, in elementary form, how to write
       a procedure which will copy files and retry until successful. This
       example does not handle such things as retry counts, restart delays,
       etc, which would be required in a practical situation.
