                                                17 November 2017.  SMS.

                     Mtools 4.0.18 for VMS (4.0.18a1)
                     ================================

------------------------------------------------------------------------

         Disclaimer
         ----------

   No claims of any sort are made herein.  The main Mtools developers
are probably unaware of this effort.  (Any suggestions for improving the
code in the VMS-specific sections are welcome, but low expectations are
more realistic than high ones.

------------------------------------------------------------------------

         Description
         -----------

   This note accompanies a quick VMS port of Mtools version 4.0.18. 
Mtools is "a collection of utilities to access MS-DOS disks from Unix
without mounting them."  Some of the most obvious features seem to work
(mostly), but many have not been tested.

   Built and tested (slightly) in these environments:

OpenVMS Alpha V8.4, HP C V7.3-010

OpenVMS IA64 V8.4, HP C V7.3-019

OpenVMS VAX V7.3, Compaq C V6.4-005

------------------------------------------------------------------------

         Mtools Web Resources
         --------------------

   Main Web page:

      https://www.gnu.org/software/mtools/intro.html

   HTML documentation:
      
      https://www.gnu.org/doc/doc.html

------------------------------------------------------------------------

         Building Mtools on VMS
         ----------------------

   Extract the files from the distribution kit.  The kit includes
objects and executables for Alpha, IA64, and VAX, in the corresponding
host-specific subdirectories.  These builds were done with large-file
support (except VAX).  MMS or MMK is required.  MMS commands are shown
in the examples, but MMK should work.  (An exception is for automatic
dependency generation.  See [.vms]descrip_mkdeps.mms for details.)

   Normally (starting in the main source directory):

      MMS /DESCRIP = [.vms]

      On Alpha, the builders will initially assume that large-file
      support is available, but will test large-file support before
      continuing.  If large-file support is not available, the build
      will fail, and a message will advise the user to add "NOLARGE" to
      the build command.

   To disable large-file support using the DCL builder, use a command
like the following:

     MMS /DESCRIP = [.vms] /MACRO = (NOLARGE=1)

   Changes to the code should have removed all the compiler warnings,
but some informational complaints remain, notably several
%CC-I-QUESTCOMPARE (mostly associated with "maximize()").  These should
be harmless, although annoying.

   The Mzip command does SCSI I/O using the IO$_DIAGNOSE function code,
use of which requires the privileges DIAGNOSE and PHY_IO.  This means
that it will work only for an appropriately privileged user, unless the
Mtools executable is linked /NOTRACEBACK and INSTALLed with the
appropriate privileges.  By default, the Mtools executable is linked
/NOTRACEBACK.  To get a LINK with /TRACEBACK, specify the MMS macro,
TRC:

      MMS /DESCRIP = [.vms] CLEAN_EXE
      MMS /DESCRIP = [.vms] /MACRO = TRC=1

A command to install the executable image should look like this:

      INSTALL ADD dev:[dir]MTOOLS.EXE /PRIVILEGED = (DIAGNOSE, PHY_IO)

   Note that the VMS SCSI I/O code is designed to refuse to molest a
mounted device, to avoid causing trouble, even with elevated privileges.

------------------------------------------------------------------------

         Installation - Foreign Commands
         -------------------------------

   Set the symbol for the primary foreign command:

      MTOOLS :== $ actual_device:[actual.directory]MTOOLS.EXE


   Mtools is described as "a collection of utilities", but all of them
are combined in one Mtools executable.  Individual utilities are
accessed as Mtools commands.  When the primary foreign command has been
defined, individual commands may be specified using the "-c" option. 
For example, to run Mformat or Mdir:

      mtools -c mformat [mformat options and other arguments ...]
      mtools -c mdir [mdir options and other arguments ...]
      [...]

Additional foreign command symbols may be defined for each program
name using the "-c" option:

      MDIR == "$ MTOOLS_BIN:MTOOLS.EXE -c mdir"
      MFORMAT == "$ MTOOLS_BIN:MTOOLS.EXE -c mformat"
      [...]

(The quotation marks are used to preserve the case of "-c" in the symbol
definition.  On VMS, the case of the command itself ("mdir", "mformat",
and so on) is not significant.)
 
   On a UNIX system, it's common to create links from the individual
program names to the Mtools executable.  On VMS, this may be done using
SET FILE /ENTER for each of the program names, and defining foreign
command symbols for each (shown for large-file Alpha):

      MTOOLS_BIN = F$ENVIRONMENT( "DEFAULT")- "]"+ ".ALPHAL]"
      DEFINE MTOOLS_BIN 'MTOOLS_BIN'

      SET FILE MTOOLS_BIN:MTOOLS.EXE /ENTER = MTOOLS_BIN:MDIR.EXE
      MDIR :== $ MTOOLS_BIN:MDIR.EXE

      SET FILE MTOOLS_BIN:MTOOLS.EXE /ENTER = MTOOLS_BIN:MFORMAT.EXE
      MFORMAT :== $ MTOOLS_BIN:MFORMAT.EXE

      [...]


   If the multiple directory entries are created using SET FILE /ENTER,
then the DCL$PATH mechanism may be used instead of defining all the
foreign command symbols.  If foreign command symbols are used, then it
may make more sense to use the "-c" version of the symbols, and not
bother creating the multiple directory entries, too.

   For a list of the available commands, run Mtools with no options:

      $ mtools
      Supported commands:
      mattrib, mbadblocks, mcat, mcd, mclasserase, mcopy, mdel, mdeltree
      mdir, mdoctorfat, mdu, mformat, minfo, mlabel, mmd, mmount
      mpartition, mrd, mread, mmove, mren, mshowfat, mshortname, mtoolstest
      mtype mwrite, mzip

------------------------------------------------------------------------

         Installation - Configuration Files
         ----------------------------------

      Configuration File Locations:

   MTOOLS:mtools.conf   replaces "/etc/mtools.conf" (or "/etc/mtools").
   SYS$LOGIN:_mtoolsrc  replaces "$(HOME)/.mtoolsrc".

MTOOLS is a logical name which may be defined system-wide or in a more
restricted context.

   The configuration file describes the available drives (floppy, Zip,
USB flash, and so on).  (It may also specify character-set translation
tables for DOS file names.)  A device description here includes drive
geometry and various option flags.  On VMS, physical drives need a
VMS-specific flag, "vms_block", which tells Mtools to use the
VMS-specific block-I/O code for that device.  Another VMS-specific flag,
"vms_nounload", is optional, and causes Mtools to dismount the device
without physically unloading it.  A Zip drive may eject the medium
automatically at dismount if this option is omitted.

   Some plausible default device descriptions are compiled-in
(devices.c), but entries in a configuration file should override the
default device descriptions.

   An example "mtools.conf" file is included in the [.VMS] directory as
"mtools.conf_example".  In this example file, logical names are used for
the devices ("MTOOLS_A" for an RX26 floppy drive, for example).  This
allows the user to specify a specific device by defining the appropriate
logical name (instead of editing the configuration file).  The system
manager may define system logical names for the typical devices, but a
user may always define a job or process logical name to override them.


      MCWD file location:

   Mtools may store a DOS default device and directory specification in
the MCWD file.  (This allows the DOS default directory to persist
between Mtools commands.)  The MCWD file may be at:

   MCWD (a logical name, if defined),
   SYS$LOGIN:_mtools_cwd  replaces  "$(HOME)/.mcwd" (or "/tmp/.mcwd").

------------------------------------------------------------------------

         VMS Usage Notes
         ---------------

   If a drive is not already mounted, MTOOLS will mount it, then
dismount it upon completion.  "ALLOCATE <device>" may be used before
running Mtools, to avoid conflicts between users during an Mtools
session.  Similarly, "MOUNT /FOREIGN <device>" may be used before
running Mtools, to reduce the number of automatic mount-dismount
actions.  Note that in a subprocess, "ALLOCATE <device>" should be used
before an explicit "MOUNT /FOREIGN <device>".  Otherwise, the master
process will own the device, and attempts to use it in the subprocess
will fail with a "%SYSTEM-W-DEVALLOC, device already allocated to
another user" complaint.

   A VMS file should be specified using UNIX notation.  Generally, the
results will be better if SET DEFAULT is used to get to the proper
directory first.

   A DOS file may be specified using DOS or UNIX-like notation.  (On
UNIX systems, allowing the use of "/" instead of "\" avoids problems
with "\" characters being treated as special by the shell.  On VMS, "\"
is not special to DCL.)

   A VMS directory (for use with "-s") should be specified by including
the ".DIR", or a trailing slash ("/").  For example, "TEST.DIR" or
"TEST/" for [.TEST].  The directory depth wildcard, "..." is not
supported.  Use "-s", instead.

   On non-VAX systems, with SET PROCESS /PARSE_STYLE = EXTENDED, Mtools
will preserve the case of the command line.  If the user specifies
lower-case file names on the command line, the result may be unintended
lower-case extended names in DOS destinations, for example:

test         <DIR>     2006-03-11   0:28  test

instead of:

TEST         <DIR>     2006-03-10  16:36

   On VAX systems (or with SET PROCESS /PARSE_STYLE = TRADITIONAL),
command-line options and arguments with upper-case content must be
quoted to avoid conversion to lower case by the C run-time library.  For
example, '"TEST/"' will be upper-case, while 'test/' or 'TEST/' will be
(converted to) lower case.

   For complex file lists, multiple commands may be needed to get the
desired results.

   In many cases, destination directories must be created explicitly
before files may be copied into them.


      Typical activities:

   DOS-format (initialize) a floppy disk ("a:"):

      mtools -c mformat a:

   DOS-format (initialize) a Zip ("z:") or USB flash drive ("u:"):

      mtools -c mformat z:              ! Format.
      mtools -c mpartition -c z:        ! Partition.

   Create and DOS-format (initialize) an image file (file "flop.img",
   drive "::") corresponding to a 3.5-inch HD (1.44MB) floppy disk:

      mtools -c mformat -C -i flop.img -f 1440 ::

   Make a directory ("DEST") on a floppy ("a:"):

      mtools -c mmd a:/DEST 

   Copy a single VMS file ("[.VMS]VMS_NOTES.TXT") into that newly
   created directory on a floppy ("a:"):

      mtools -c mcopy -v vms/vms_notes.txt a:/DEST

   Copy a VMS directory tree ("[.TEST...]") to a floppy ("a:"):

      mtools -c mcopy -v -s TEST/ a:

   Copy a VMS directory tree ("[.TEST...]") to a floppy image file
   ("flop.img", "::"):

      mtools -c mcopy -i flop.img -v -s TEST/ ::

   List all the files on a floppy ("a:"):

      mtools -c mdir -s a:

   List all the files on a floppy image file ("flop.img", "::"):

      mtools -c mdir -i flop.img -s ::

   Eject a Zip disk ("z:"):

      mtools -c mzip -e z:

------------------------------------------------------------------------

      News
      ----

   Version 4.0.18a1 (BETA)  2017-11-17
   -----------------------------------

- General update to version 4.0.18.  Some changes from previous versions
  probably need more work to fit the current code.

- The VMS builders have been changed to enable large-file support by
  default on non-VAX systems (with a test on Alpha, to make sute that it
  works).  The MMS macro TRC has been added to get more easily a LINK
  with /TRACEBACK.  See comments in [.vms]descrip.mms for details.

- The kit files are now stored on an ODS5 volume with the original case
  preserved.  Accordingly, the DCL script vms_name_fix.sh has been
  deleted from the kit.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

   Version 3.9.11a  2008-02-15
   ---------------------------

- General update to version 3.9.11, including the patches dated
  "20070601".

- Changed some error messages in init.c, mformat.c, and plain_io.c, to
  reflect the configuration file names specified in mtoolsPaths.h,
  instead of using local string constants which may differ (and which
  are certainly wrong on VMS).

- Added some preliminary non-VMS-specific code to config.c, init.c,
  mpartition.c, and partition.h to fix problems with a USB SD card
  reader (a partitioned "disk" with an extended boot record).  A new
  configuration file keyword, "ebr", identifies a device with this
  property.  Note: The mformat and mpartition commands have NOT been
  changed to handle this properly, so they should not be used on a
  "disk" with this structure.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

   Version 3.9.10b  2006-06-08
   ---------------------------

- In mcopy, VMS source files with ODS5 extended file names typically
  caused errors, with complaints like "test/a^.b.c: no such file or
  directory".

- Various mtools programs could fail with confusing error messages when
  a VMS file specification including a directory was used for an image
  file ("-i").  For example: 
        $ mtools -c mdir -i [-]FLOP.IMG ::
        *** Dummy fork() ***
        Pipe read error: no such file or directory
  For some (unknown) reason, mtools attempted to do a UNIX-style
  wildcard expansion on the image file specification, and the method
  used (fork(), /bin/sh echo) failed on VMS.  Now, this wildcard
  expansion is not attempted on VMS.

- The VMS SCSI I/O code now includes an explicit privilege check
  (DIAGNOSE and PHY_IO), and a check to prevent molesting ("mzip -e") a
  mounted device, with better error messages if these checks fail.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

   Version 3.9.10a  2006-03-14
   ---------------------------

- New.  Bugs and limitations may abound.

------------------------------------------------------------------------

      Changes to Source Files
      -----------------------

   Files new for VMS (all in [.VMS]):

      collect_deps.com    Dependency collector for descrip_mkdeps.mms.

      config.h_vms        VMS-specific config.h.

      decc_ver.c          Diagnostic program to provide build
                          environment information.

      descrip.mms         Main MMK or MMS description ("make") file.

      descrip_config.mms  config.h description file.

      DESCRIP_DEPS.MMS    Source dependency description file.

      descrip_mkdeps.mms  Source dependency generator description file.

      descrip_src.mms     Source list description file.

      mtools.conf_example Example "mtools.conf" file for VMS.

      vms.c               Various VMS-specific code: DEC C run-time
                          initialization, ODS2-ODS5 file system
                          detection, block-I/O functions.

      vms.h               VMS-specific header file.  Declarations of
                          replacement data types/structures and function
                          prototypes for VMS.C.

      UNIX shell script to restore original
                          mixed-case and multi-dot file names after
                          storage on an ODS2 file system.

      VMS_NOTES.TXT       These notes.

      vms_scsi.c          VMS-specific replacement for "scsi.c".


   Files modified for VMS:

      config.c          Added VMS-specific device options and
                        configuration file names.

      devices.c         Changed to add some default devices for VMS
                        (with VMS-specific flag values).

      expand.c          Changed to avoid UNIX-style wildcard expansion
                        on VMS.

      fat.c             Changed some messages.

      file_name.c       Changed "_basename()" to "mt_basename()".

      floppyd_io.c      Compiler warning reduction.  Typography.

      init.c            Changed to handle better a partitioned "disk"
                        with hidden sectors (an SD card in a USB card
                        reader).  Changed to close/dismount a device
                        before exit() after some fatal errors.  Changed
                        some messages to reflect actual configuration
                        file names.

      llong.c           Compiler warning reduction.

      mainloop.c        Various changes to accomodate VMS file names.

      mainloop.h        Changed not to try to "#include <sys/param.h>"
                        if HAVE_SYS_PARAM_H was not defined.

      mcopy.c           Spelling error reduction.  Typography.

      mformat.c         Compiler warning reduction (including repair of
                        an inappropriate variable declaration).  Changed
                        some messages to reflect actual configuration
                        file names.

      misc.c            Changed the MCWD file specification for VMS.

      missFuncs.c       Changed "_basename()" to "mt_basename()".

      mpartition.c      Changed to handle better a partitioned "disk"
                        with hidden sectors (for example, an SD card in
                        a USB card reader).

      mtools.c          Changed to accomodate VMS file names.

      mtools.h          Added VMS-specific device flag macros.

      mtoolsPaths.h     Changed the configuration file specifications
                        for VMS.

      mzip.c            Changed on VMS to use the new scsi_close()
                        function instead of a normal UNIX I/O close(),
                        and to avoid using the (inappropriate)
                        closeExec() function.

      partition.h       Added a structure for the Extended/Master Boot
                        Record which is used by the new code in init.c.

      patchlevel.c      Changed the program version string.

      plain_io.c        Changed to use VMS block-I/O when specified.
                        Compiler warning reduction.  Spelling error
                        reduction.  Typography.  Changed some messages
                        to reflect actual configuration file names.

      privileges.c      Changed to "#include <unistd.h>" if
                        HAVE_UNISTD_H is defined, for compiler warning
                        reduction.

      scsi.h            Added a prototype of the new scsi_close()
                        function on VMS.  Changed the prototype argument
                        list for scsi_cmd() to agree with that of the
                        actual function.

      sysincludes.h     Changed declarations and macros related to
                        various *basename*() functions,

      unixdir.c         Changed to accomodate VMS file names.

------------------------------------------------------------------------

   When reporting problems with Mtools for VMS, especially build
problems, it is often useful to reveal precise compiler, run-time
library, and VMS version information.  The program decc_ver.c (included
in the kit) is intended to make that easier.

------------------------------------------------------------------------

   Steven M. Schweda               sms@antinode.info
   382 South Warwick Street        (+1) 651-699-9818
   Saint Paul  MN  55105-2547

