                                                14 March 2006.  SMS.

                     Mtools 3.9.10 for VMS (3.9.10a)
                     ===============================

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

         Disclaimer
         ----------

   No claims of any sort are made herein.  The main Mtools developers
are probably unaware of this effort.  (This may help to avoid
embarassment to me, as the code is rather ragged.  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 3.9.10, "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.  This release should be
considered to be of "experimental" quality.

   Built and tested (slightly) in these environments:

OpenVMS Alpha V7.3-2, HP C V7.1-015

OpenVMS IA64 V8.2-1, HP C V7.2-001

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

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

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

   Main Web page:

      http://mtools.linux.lu/

   HTML documentation:

      http://mtools.linux.lu/mtools.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 option
(explained below) "LARGE" (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] /MACRO = (LARGE=1)  ! Non-VAX
      MMS /DESCRIP = [.VMS]                     ! VAX

   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()") and one
%CC-I-SUBSCRBOUNDS.  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 or LOG_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.  To get the Mtools executable linked
/NOTRACEBACK, use the LINKOPTS MMS macro:

      MMS /DESCRIP = [.VMS] /MACRO = (LARGE=1) CLEAN_EXE
      MMS /DESCRIP = [.VMS] /MACRO = (LARGE=1, "LINKOPTS=/NOTRACEBACK")

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

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

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

         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, 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.

   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:
      mtools -c mpartition -c z:

   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 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.

      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.

      VMS_NAME_FIX.SH     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:

      BUFFER.C          Compiler warning reduction.

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

      FILE_NAME.C       Changed "_basename()" to "mt_basename()".

      FLOPPYD_IO.C      Compiler warning reduction.

      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.

      MFORMAT.C         Compiler warning reduction (including repair of
                        an inappropriate variable declaration).

      MISC.C            Changed the MCWD file specification for VMS.

      MISSFUNCS.C       Changed "_basename()" to "mt_basename()".

      MPARTITION.C      Compiler warning reduction.

      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.

      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.

      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.

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

   The accompanying source kit may suffer from storage on an ODS2 file
system, which does not preserve case or allow multiple dots in a file
name.  Building this kit should work on VMS, but it may be expected to
fail on other systems.  To use this kit on a non-VMS system, the files
may need to be renamed to restore their original mixed-case and/or
multi-dot names.  The UNIX shell script "vms_name_fix.sh" (or something
like it) should do the job.

   When reporting problems, especially build problems, with Mtools for
VMS, 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               (+1) 651-699-9818  (voice)
   382 South Warwick Street        sms@antinode.org
   Saint Paul  MN  55105-2547

