               ==========================================
               Cdrtools Version 2.01 (2.01.01a14) for VMS
               ==========================================

========================================================================

      Functional changes for VMS.  2006-09-13 SMS.
      --------------------------------------------

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

   This kit includes MMS/MMK product builders which are new for cdrtools
version 2.x.  Objects, object libraries, executables, and any other
system-specific files should now be placed into system-specific
subdirectories in the source tree, such as [.ALPHA], [.IA64], or [.VAX]. 
If the large-file option is specifed (non-VAX), [.ALPHAL] or [.IA64L]. 
(See below for details.)

   Command-line case is preserved by all programs if SET PROCESS
/PARSE_STYLE = EXTENDED is in effect (non-VAX, where C run-time library
support exists).  This obviates quoting upper-case options.

   All programs now have an exit handler to restore process base
priority ("nice(0)").  CDDA2WAV and CDRECORD normally raise it (where
privileges allow), but did not previously restore it.  How much they
raise it is now set by the macro NICE_DECR (currently 8, had been 20) in
the VMS section of [.INCLUDE]XMCONFIG.H.

   CDDA2WAV, CDRECORD, MKISOFS, and READCD now use some VMS-specific
parameters on open operations for major files.  This typically enables
double buffers, read-ahead, write-behind, and larger extend quantities. 
Users who do not override the RMS defaults (SET RMS_DEFAULT) should see
significant I/O speed improvements.  Users may override the new default
parameters using SET RMS_DEFAULT explicitly to set different ones.

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

   MKISOFS Changes
   ---------------

   - New "-E" option to show ISO 9660 header (Environment) information. 
This shows, for example, ".mkisofsrc" file data not explicitly specified
on the command line.  The "-v" option now also shows whether
".mkisofsrc" was used.  These changes are enabled by defining the C
macro "SMS", which is done by the by the VMS builders.  (Look for "SMS"
in [.MKISOFS]DESCRIP_SRC.MMS.)
   - ODS5 extended file name support (not well tested).
   - Various bug fixes.  (See below for details.)
   - The new MKISOFS option, "-find", is not available on VMS, as it's
currently implemented using fork().  (Also, "inodes" are different on
VMS, requiring some minor additional work.)

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

   MKISOFS Diagnostic Programs
   ---------------------------

   There are some diagnostic programs related to ISO-9660 file systems
hidden in the [.MKISOFS.DIAG] directory.  Executables for the working
ones should be created in the same directory as MKISOFS.EXE, and
suitable foreign-command symbols may be created for them, if desired. 
(See Foreign-Command Symbols, below.)  The working ones are:

   - isodebug  print mkisofs debug info from ISO-9660 image.
   - isoinfo   perform directory like listings of iso9660 images.
   - isovfy    verify the integrity of an iso9660 image.

Not yet working (due to UNIX screen handling, at least) are the more
interactive programs:

   - isodump  display the contents of iso9660 images.
   - devdump  display the contents of device or filesystem images.

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

   VMS CD/DVD Device Specification
   -------------------------------

   In this release, a CD/DVD drive may be specified using a normal VMS
device name (physical or logical).  For example, "dev=dkb500" or
"dev=cdrw" (where "cdrw" is a logical name which has been defined to
identify an appropriate device).  As in previous cdrecord/cdrtools
versions, the old standard cdrecord/cdrtools format is also allowed. 
That is, "dev=i,j,k" (where i, j, and k are integers), rather than a
simple VMS device name.  The "dev=i,j,k" specification is translated
into a VMS device name as shown below.

      i:   0   1   2   3   4   5   6   7   8   9  ...   32  33
         dka dkb dkc dkd gka gkb gkc gkd dqa dqb  ...  dqy dqz

      j: SCSI ID

      k: SCSI LUN (usually 0)

   For example, "dev=1,5,0" specifies DKB500, and "dev=8,0,0" specifies
DQA0.  If a SCSI adapter beyond "D" is needed, the simplest method would
be to specify the actual VMS device name instead of using the "i,j,k"
scheme.  However, to use the "i,j,k" scheme in such a case, one could
specify some nonexistent DQ device (like "dev=33,1,1"), and then define
a logical name to redirect the phony device name (here, DQZ101) back to
the real device.  For example, if the CD/DVD drive were DKF300:

      $ define DQZ101 DKF300
      $ cdrecord dev=33,1,1 -prcap

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

   GKDRIVER
   --------

   Some VAX systems (with older hardware and/or older VMS versions) will
need to use (or work better if they use) the GKDRIVER generic SCSI
driver for the CD/DVD drive, instead of the usual DKDRIVER SCSI disk
driver.  The indicating symptom might be an I/O failure like this:

      cdda2wav: invalid argument. Cannot send SCSI cmd via ioctl
      %SYSTEM-?-BADPARAM, bad parameter value

or many (recoverable) errors like this:

      cdda2wav: not owner. ReadCD MMC 12: scsi sendcmd: retryable error

   One way to select an alternate device driver involves editing
SYS$MANAGER:SYCONFIG.COM to control which driver is used for the CD/DVD
device.  The suggested changes shown below do three things:
      1. Prevent all the system devices from being automatically
         configured (because that would connect the CD/DVD device using
         the default DKDRIVER),
      2. Arrange to specify GKDRIVER for the CD/DVD device(s), and then
      3. Automatically configure all the other devices.

   The first change is to uncomment this line in SYCONFIG.COM:

$!      STARTUP$AUTOCONFIGURE_ALL == 0

This prevents SYS$STARTUP:VMS$DEVICE_STARTUP.COM from configuring any
devices.  Then (also in SYCONFIG.COM), add the appropriate SYSGEN
commands to do the configuration as desired.  (Refer to
VMS$DEVICE_STARTUP.COM to ensure that all the desirable things which it
would normally do are moved into SYCONFIG.COM.)  In this example, the
CD/DVD drive is on the "A" SCSI adapter at SCSI ID 5 (normally DKA500):

$ mcr sysgen
    ! Do the normal tasks from SYS$STARTUP:VMS$DEVICE_STARTUP.COM.
    connect fta0 /noadapter /drivername = ftdriver
    connect mpa0 /noadapter /drivername = pipedriver
    ! Connect the CD-R/RW drive using the generic SCSI driver.
    connect gka500 /noadapter
    ! Auto-configure everything (else).
    autoconfigure all
    exit

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

   Foreign-Command Symbols
   -----------------------

   Also, as in previous cdrecord/cdrtools versions, it's usual to define
foreign-command symbols for the programs.  It may be helpful to gather
the various program executables from their individual directories, and
put them all into some more convenient directory.

      CDDA2WAV :== $ dev:[dir]CDDA2WAV.EXE
      CDRECORD :== $ dev:[dir]CDRECORD.EXE
      MKISOFS  :== $ dev:[dir]MKISOFS.EXE
      READCD   :== $ dev:[dir]READCD.EXE

Symbol definitions like these could be added to the system-wide
SYS$MANAGER:SYLOGIN.COM procedure, to a user's SYS$LOGIN:LOGIN.COM
procedure, to or to some other convenient procedure, as appropriate.

   Alternatively, the DCL$PATH logical name can be defined to include
the directory (or directories) where these programs are located.

========================================================================

      Build procedure for VMS.  2006-06-07 SMS.
      -----------------------------------------

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

   Source Tree Preparation
   -----------------------

   The original source tree contains some symbolic links to various
header files (apparently to avoid having to tell the C compiler where to
find them).  VMSTAR extracts these links as one-line text files which
say something like:

      *** This file is a link to <path_to_actual_file>

   The VMS builders are able to find the header files in their original
locations (using /INCLUDE), and these link files only cause problems for
the VMS builders.

   If VMSTAR is used to recreate the source tree, then the procedure
[.VMS]DISCARD_LINK_FILES.COM should be run ("@") to rename the header
link files from "XXX.h" to "XXX.h_link":

      @ [.vms]discard_link_files.com

Link files other than those for the header files should be harmless, and
are not affected by this action.

   If a VMS-oriented Zip archive is used instead of a UNIX-oriented
"tar" archive to recreate the source tree, then this procedure should be
unnecessary (but harmless).

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

   Local Customization
   -------------------

   Some program features may be enabled or disabled in a local
configuration file, [.VMS]DESCRIP_LOCAL.MMS.  (A template file is
preserved as [.VMS]DESCRIP_LOCAL.MMS_TEMPLATE.)  Comments in the file
explain the options (briefly), and how to enable or disable them.

   Currently, this file affects only some features in the audio
extraction program, cdda2wav.

   This file should be edited as desired before building the products.

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

   Building the Products
   ---------------------

   MMS/MMK product builders are distributed throughout the source tree,
and in the [.VMS] directory:

      [.vms]append_version.com
      [.vms]collect_deps.com
      [.vms]vax_old.opt
      [...]descrip*.mms

Any older *.COM procedures which may still be found in the source tree
are obsolete, and should not be used.

   In the simplest case, build the products so:

      SET DEFAULT [.VMS]
      MMS                     ! Or MMK.  See below for more options.

   MMK or old versions of MMS may need to have additional macros defined
on the command line, but helpful messages should explain what to do
when.  (Old MMS versions on VAX may need MMS$ARCH_NAME.  MMK will
probably need MMSDESCRIPTION_FILE.)

   Popular targets and options (which should be explained in
[.VMS]DESCRIP.MMS) include:

      MMS CLEAN
      MMS CLEAN_ALL
      MMS CLEAN_EXE
      MMS CLEAN_OLB

      MMS /MACRO = (LIST=1)
      MMS /MACRO = (LARGE=1)  ! Non-VAX.  Important for DVD support,
                              ! where files bigger than 2GB are likely.

   Inside the major subdirectories, "MMS /DESCRIP = [-.VMS] [...]"
should work.

   To (re-)generate the source dependency ("[...]DESCRIP_DEPS.MMS")
files, MMS (V3.5 or newer?) is needed:

      MMS /EXTENDED /DESCRIPTION = descrip_mkdeps.mms /SKIP

To save time during program development, when these are changing often,
it helps to save the intermediate .MMSD files (output from CC
/MMS_DEPENDENCIES), so:

      MMS /EXTENDED /DESCRIPTION = descrip_mkdeps.mms /MACRO = NOSKIP=1

   For details, see the comments in [.VMS]DESCRIP_MKDEPS.MMS.

   Linking on old VMS VAX versions may generate warnings:

      %LINK-W-MULPSC, conflicting attributes for psect LIB$INITIALIZE
           in module LIB$INITIALIZE file SYS$COMMON:[SYSLIB]STARLET.OLB;

A LINK options file ([.VMS]VAX_OLD.OPT) is supplied which should help. 
Try adding '/MACRO = ("LINKOPTS=[-.VMS]VAX_OLD.OPT/OPTIONS")' to the
MMS/MMK command.

   The cdrtools programs use C run-time library features which were not
available before VMS V7.0.  Building on VMS versions earlier than V7.0
is possible using the "backport library" features provided by DEC C V5.6
and later compilers.  The details are described in the file
SYS$LIBRARY:DECC$CRTL.README, which is supplied with these compilers. 
This file also describes the options available to deal with time zones
and the newer UTC-based time functions.

   The builders (specifically, the .FIRST actions in
[.VMS]DESCRIP_SRC_CMN.MMS) check the VMS version, and, if it is pre-V7,
define the logical names DECC$CRTLMAP (as SYS$LIBRARY:DECC$CRTL.EXE) and
LNK$LIBRARY (as SYS$LIBRARY:DECC$CRTL.OLB), unless the user has already
defined them.  This should persuade the compiler to use a suitably high
value for __CRTL_VER when compiling, and a suitably complete C RTL when
linking.  Environments with non-default configurations may require
changes from the code supplied, but it should be possible to confine any
needed changes to this one region.

   In case of problems with the builders or the products, it's often
helpful to include various software version data (VMS, C compiler, C
RTL) in any problem report.  The source kit includes a short program to
make this easier.  A normal build should create the executable:

      [.LIBVMS.<arch>]DECC_VER.EXE

When reporting any problems, please run this program, and include its
output in the problem report.  If problems with the build cause a
failure before this executable is built, a more limited build in the
[.LIBVMS] directory may have a better chance:

      set default [.libvms]
      mms /descrip = [-.vms] [... any other options ...]

========================================================================

      Source changes for VMS.  2006-09-13 SMS.
      ----------------------------------------

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

      [.cdda2wav]cdda2wav.c

   Changed to use the NICE_DECR macro in nice().
   Added VMS-specific open() parameters for access callback function.

      [.cdda2wav]lconfig.h_vms (NEW)

   General update according to [.cdda2wav]lconfig.h_in.
   Added conditionality for HAVE_STRCASECMP.

      [.cdda2wav]scsi_cmds.c

   Fixed an fprintf() format problem ("%hd" for int expression).

      [.cdda2wav]vms.c (NEW)

   Set up initialization (non-VAX) to set DECC$* variables.

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

      [.cdrecord]cdrecord.c

   INSERT_YOUR_EMAIL_ADDRESS_HERE
   Changed to use the NICE_DECR macro in nice().
   Minor spelling corrections.

      [.cdrecord]vms.c (NEW)

   Set up exit handler to restore base process priority.
   Set up initialization (non-VAX) to set DECC$* variables.

      [.cdrecord]xio.c

   Added VMS-specific open() parameters for access callback function.

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

      [.include]mconfig.h

   Added macros to substitute libschily *printf() functions for the
corresponding VMS C RTL functions.
   Added a default definition of the NICE_DECR macro (for non-VMS
systems).

      [.include]schily.h

   Added "#ifndef _OPENFD_SRC" conditionality around "#define _openfd
_openfd64" in the "#if defined(HAVE_LARGEFILES)" section.

      [.include]timedefs.h

   Added "struct timeval" declaration for systems which lack it.

      [.include]ttydefs.h

   Fixed typos: "_INCL_SYS_IOCTl_H" -> "_INCL_SYS_IOCTL_H".

      [.include]xmconfig.h

   Restored many "HAVE_xxxx" definitions for newer VMS C RTL.  Added
some more.  Added NICE_DECR to provide an OS-specific nice() value.
   Updated HOST_CPU, HOST_OS, and HOST_VENDOR for VMS.
   Added byte- and bit-order macros for VMS.
   Defined macros _OPENFD_SRC and _openfd to switch to a VMS-specific
replacement for _openfd().  Defined a VMS-specific O_BINARY flag value
for internal use.

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

      [.libscg]scsi-vms.c

   Added simple VMS device name support.
   Added an explicit check for privileges DIAGNOSE and PHY_IO.
   Added a check to avoid molesting mounted disk devices.
   Added an IA64-specific work-around for a system crash (MACHINECHK) on
   IA64.  (EHH.)

      [.libscg]scsihelp.c

   Changed a message to say "VMS" instead of "UNIX" on VMS.

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

      [.libschily]fnmatch.c

   Removed an explicit directory from a "#include" directive.

      [.libschily]format.c

   Changed to avoid redefining the USE_LONGLONG macro.

      [.libschily]gethostid.c

   Added "#include <schily.h>" to get the prototype of seterrno().

      [.libschily]saveargs.c

   Changed to simplify the full VMS path for argv[ 0] to just the
program name.

      [.libschily]snprintf.c

   Changed "snprintf" macro handling to allow an OS-specific definition
in [.include]mconfig.h.

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

      [.libschily.stdio]filewrite.c

   Changed "fwrite(buf, 1, len, f)" to "fwrite(buf, len, 1, f)" to get
one record of length "len", instead of "len" records of length one,
which repairs the appearance of some error messages when the program
output is directed to a file with variable-length record format (as with
SET HOST /LOG).

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

      [.libvms] (NEW)

      [.libvms]decc_ver.c

   Diagnostic program to report various software version data (VMS, C
compiler, C RTL).

      [.libvms]vms_init.c

   Exit handler.
   DECC$* initialization.
   RMS default parameter sensing.
   Access callback function.

      [.libvms]vms_init.h

   Header file for vms_init.c.

      [.libvms]vms_misc.c

   VMS-specific _openfd() replacement function, openfd_vms().
   Conditional str[n]casecmp() function.
   ODS5 extended file name infrastructure.

      [.libvms]vms_misc.h

   Header file for vms_misc.c.

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

      [.mkisofs]defaults.h

   Renamed to [.mkisofs]mdefaults.h to avoid confusion with
[.cdrecord]defaults.h.

      [.mkisofs]match.h

   Removed an explicit directory from a "#include" directive.

      [.mkisofs]mkisofs.c

   Added "-E" option for ISO 9660 header (environment) display.
("#ifdef SMS", enabled by the VMS builders.)
   Changed to notify user of use or non-use of init file with "-E" or
"-v".  ("#ifdef SMS", enabled by the VMS builders.)
   Changed to use new IPATH_SEPARATOR macro ('/') for CD paths instead
of PATH_SEPARATOR, which is different (']') for VMS.
   Changed not to use "/" as a separator when forming the ".mkisofsrc"
init file path in VMS.  (Should be [S]PATH_SEPARATOR if/when used?)
   Changed to tolerate blank lines in the init file.
   Changed to use "NLA0:" instead of "/dev/null" on VMS.
   Added VMS-specific fopen() parameters for access callback function.
   Added non-C-RTL storage for "optarg".
   Moved some storage declarations to outside of "#ifdef USE_FIND".

      [.mkisofs]mkisofs.h

   Changed '#include "defaults.h"' to '#include "mdefaults.h"'.
   Added a prototype for the new function, write_one_file_progress().
   Added "#define IPATH_SEPARATOR '/'".

      [.mkisofs]name.c

   Changed to use a header file definition of the ".DIR;1" string, and
to make a case-insensitive comparison with it to accomodate ODS5
extended file names.

      [.mkisofs]rock.c

   Added '#include "vms.h"' (before "device.h") to get different major()
and minor() macros.

      [.mkisofs]tree.c

   Added '#include "vms.h"' (before "device.h") to get different major()
and minor() macros.
   Removed an explicit directory from a "#include" directive.
   Added one more use of "vms_path_fixup()", needed with new C RTL.
   Added some code to remove caret escape characters from ODS5 extended
file names.  (Not well tested.)

      [.mkisofs]vms.c

   Removed code for functions now in the C RTL or no longer used:
closedir. getopt, opendir, readdir, [VMS_]stat, strdup.
   Set up initialization (non-VAX) to set DECC$* variables.
   Changed vms_path_fixup() and RMS I/O functions to cope with ODS5
extended file names.
   Changed vms_write_one_file() to use the same progress messages as
write_one_file(). 

      [.mkisofs]vms.h

   Removed code for functions now in the C RTL or no longer used.
   Added macro kit for NAML structure for ODS5 extended file names.
   Added function prototypes for vms_path_fixup() and
vms_write_one_file().

      [.mkisofs]write.c

   Separated progress message code into a new function,
write_one_file_progress(), now used by both vms_write_one_file() and
write_one_file().

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

      [.mkisofs.diag]dump.c
      [.mkisofs.diag]isodebug.c
      [.mkisofs.diag]isodump.c
      [.mkisofs.diag]isodump.c
      [.mkisofs.diag]isovfy.c

   Removed explicit directories from "#include" directives.  (With the
change from [.mkisofs]defaults.h to [.mkisofs]mdefaults.h, this change
should work everywhere.)

      [.mkisofs.diag]vms_diag.c (NEW)

   Set up initialization (non-VAX) to set DECC$* variables.

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

      [.readcd]vms.c (NEW)

   Set up initialization (non-VAX) to set DECC$* variables.

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

      [.scgcheck]scgcheck.c

   Minor spelling corrections.

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

      [.vms] (NEW)

      [.vms]append_version.com

   Command procedure used to extract a version number from cdrecord.c,
for use in other programs.

      [.vms]collect_deps.com

   Command procedure used to collect individual generated MMS dependency
files, making the dependency paths relative.

      [.vms]descrip.mms

   Main MMS description file.

      [.vms]descrip_local.mms

   Local customization MMS description file.

      [.vms]descrip_local.mms_template

   Template for the local customization MMS description file.

      [.vms]descrip_mkdeps.mms

   Dependency generation MMS description file.

      [.vms]descrip_src.mms

   Source MMS description file.

      [.vms]descrip_src_cmn.mms

   Common source MMS description file.

      [.vms]descrip_src_flags.mms

   Compiler and linker flags MMS description file.

      [.vms]discard_link_files.com

   Command procedure used to locate and rename troublesome header link
files which may be created by VMSTAR.

      [.vms]vax_old.opt

   Link options file used to reduce warning messages on old VMS
versions.

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

========================================================================

