8 June 2006. SMS. Mtools 3.9.10 for VMS (3.9.10b) =============================== ------------------------------------------------------------------------ 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 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. 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. 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, 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, 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 " may be used before running Mtools, to avoid conflicts between users during an Mtools session. Similarly, "MOUNT /FOREIGN " 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 2006-03-11 0:28 test instead of: TEST 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.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. 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. CONFIG.C Added VMS-specific device options. 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. 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 " 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 " 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 sms@antinode.org 382 South Warwick Street (+1) 651-699-9818 Saint Paul MN 55105-2547