@(#)INSTALL.VMS	6.26 01/07/16

INSTRUCTIONS FOR OPENVMS
------------------------

Please read through the following notes before attempting to install 
xmcd on the Digital OpenVMS platform.

Please note that only the xmcd (X11/Motif-based) CD player is supported
under OpenVMS.  The command-line based cda utility is not supported.


COMPILER AND OS MINIMUM VERSIONS
--------------------------------

The required minimum OpenVMS version is 6.2
The required minimum DEC C   version is 5.6

On Alpha machines equipped with an IDE/ATAPI CD drive, the minimum
OpenVMS version is 7.1-2 with a new SYS$DQDRIVER.EXE installed,
at least the following or a later release:
 
                image name: "SYS$DQDRIVER"
                image file identification: "X-21"
                image file build identification: "X6N6-SSB-0000"
                link date/time: 17-APR-2000 12:32:19.68
                linker identification: "A11-39"

The above driver can be found on the OpenVMS Freeware CD V5.0.
On OpenVMS version 7.3 and later no new SYS$DQDRIVER is needed.

If you are compiling on a OpenVMS 6.x system, you will need to set
the logical names DECC$CRTLMAP and LNK$LIBRARY to point to the C 
library area.


BUILDING XMCD
-------------

To build xmcd for the OpenVMS operating system you need to first unpack
the xmcd GZIPed file, then use VMSTAR to restore the directory tree for
xmcd.  GUNZIP, and VMSTAR can be found at various locations on the
Internet. One such location is this site:

	http://gatekeeper.research.compaq.com/cgi-bin/grep-index

After unpacking the xmcd package you have to decide whether you want to
excute the INSTALLVMS.COM procedure or if you want to install xmcd manually.

Running INSTALLVMS.COM results in a fully functional installation.

However, it does neither include advanced features like driving XV as an
external image viewer nor does it include changing the configuration
files as for xmcd's look and the parameters describing the capabilities
of your CD drive. All of the latter is not necessary to run xmcd, but
you might find that XV displays images with better quality than Netscape,
and you might want to enable your CD drive's balance control capability
(if it has it) or similar.

For details on modifying xmcd's configuration files see the related
manual installation instructions below.


AUTOMATIC INSTALLATION BY INSTALLVMS.COM
-----------------------------------------

  The INSTALLVMS.COM procedure residing in the xmcd top-level directory
  will install xmcd on OpenVMS on your behalf.

  The first phase deals with compiling and linking the image.  Before it
  starts you will be prompted to answer the question whether your system
  has  TCP/IP and socket support. This is for the Gracenote CDDB(tm)
  functionality.

  In the second phase it will prompt you to answer a few simple
  questions as for the CD drive you want to use with xmcd and whether
  you previously have installed a xmcd 2.x version. Depending on your
  system's configuration it also may ask for the directories your
  browser executables are resident in.

  If you indicated to have a xmcd 2.x version installed, it will move
  your local CD database files to the xmcd 3.x environment. Therefore 
  you will also be asked whether you are satisfied with the backup of 
  your disks.
  Before the files are being moved, you will be prompted to specify the
  xmcd 2.x version's top-level directory.  If Local Discography files
  are found, they also will be copied to your xmcd 3.x environment 
  and then converted to a new format.

  On completion of the installation procedure you need to restart your
  login session to have all the changes take effect. After logging in
  again you can use the foreign command XMCD to start the application
  from the command line. 

  It is strongly recommended to make use of INSTALLVMS.COM instead of
  installing xmcd manually. Advanced features like driving XV as an
  external image viewer may be added manually afterwards.


MANUAL INSTALLATION 
-------------------

  "To those who like it the hard way, we salute you".


  If your system has TCP/IP and socket support, you may want to enable
  the remote CD database functionality.  See the MAKEVMS.COM file in
  the CDDB_D area for information.

  Set your default back to the top level of the xmcd source code tree.
  Execute the command file MAKEVMS.COM.  This initiates the compile
  and linking of all source files.  The executable binary that results
  is XMCD.EXE found in the [.XMCD_D] directory.  There will also be a
  foreign command XMCD that you can use to run the program.


    INSTALLING AND CONFIGURING XMCD
    -------------------------------

    1. Create an XMCD Library:

	You need to set up an xmcd library directory which contains
	COMMON.CFG and DEVICE.CFG, the help and documentation files,
	the CD database and Local Discography areas.

	Example:

	    $ CRE/DIR SYS$SYSDEVICE:[XMCD]

	You can use a different directory than SYS$SYSDEVICE:[XMCD]
	if you wish.  Substitute all occurrences of SYS$SYSDEVICE:[XMCD]
	in the examples below with the actual directory you use.  Be sure
	this directory is world-readable and the files in there are
	world-readable and executable.
	Of course you also may use the directory created by VMSTAR as the
	xmcd library directory.

    2. Setting up the config file:

	In the LIBDI_D area there are two configuration files COMMON.CFG,
	and DEVICE.CFG.  The COMMON.CFG file contains general parameters,
	whereas DEVICE.CFG defines device-specific parameters.

	In the COMMON.CFG file there are a number of defaults, you must
	change the line that specifies the name of the CD device you plan
	to use.  The default looks like this:

	    device:		/dev/rcd0

	Change this to the name of the CD device you are going to use.
	For example:

	    device:		DKA500:

	You may need to change some of the parameters in the DEVICE.CFG
	file depending upon the specific model of CD-ROM you have.

	Copy both the COMMON.CFG and DEVICE.CFG files (with the
	change to the device name) to the xmcd library directory
	(Created in step 1 above).  

	If xmcd is to be used on a cluster, a node-specific version of
	these files may be created in the same place by adding -NODENAME
	to the file names (e.g., COMMON.CFG-SNOOPY and DEVICE.CFG-SNOOPY).
	These node-specific configuration files will take precedence over
	the generic ones.

	Each user on their stand-alone system can also customize the xmcd
	default CD-ROM device and xmcd behavior by creating a subdirectory
	named XMCDCFG.DIR off their top level user directory, and then
	putting a copy of the COMMON.CFG and DEVICE.CFG files there.

	Example:

	    $ CRE/DIR DISK1$:[RJONES.XMCDCFG]

	If a user wishes to override any parameters in the COMMON.CFG and
	DEVICE.CFG files then they can edit their local copy and make the
	needed changes.  Note that some parameters are considered
	"privileged" and will be ignored by xmcd in the local version of
	these files.  See the comments in the files for details.

    3. Setting up the help file area:

	The help files need to be in a subdirectory of the xmcd library
	called HELP.DIR.  The help files themselves come from the xmcd tar
	file from the subdirectories under HLPFILES.DIR in the XMCD_D area.

	Create the HELP area in the xmcd library:

	    $ CRE/DIR SYS$SYSDEVICE:[XMCD.HELP]

	Then, move the helpfiles to the help area:

	    $ RENA SYS$SYSDEVICE:[XMCD.XMCD_D.HLPFILES]*.*
		SYS$SYSDEVICE:[XMCD.HELP]

	Help under xmcd is context sensitive.  Using the right mouse button
	on a part of xmcd that offers help will invoke that help window.

    4. Setting up the documentation file area:

	The documentation files need to be in a subdirectory of the xmcd
	library called DOCS.DIR.  The documentation files themselves come
	from the xmcd tar file from the directory under the DOCS_D area.

	Move the xmcd docs file from the source code area to the library
	area:

	    $ RENA SYS$SYSDEVICE:[XMCD]DOCS_D.DIR SYS$SYSDEVICE:[XMCD]DOCS.DIR

	You can browse these documentation files using the xmcd help system.

    5. Installing the xmcd X resource file:

	There is a X resources file called XMCD.AD in the XMCD_D area.
	This holds the definitions for window colors, fonts, messages,
	labels, and other customizable items.  Xmcd must be able to find
	this file in order to run.  To allow xmcd to use this file copy
	the XMCD.AD file to DECW$SYSTEM_DEFAULTS:XMCD.DAT for system-wide
	or cluster-wide use.

	You need to make this file world readable.

	    $ SET FILE/PROT=W:RE DECW$SYSTEM_DEFAULTS:XMCD.DAT

	You may also create a DECW$USER_DEFAULTS:XMCD.DAT file which may
	contain personal settings which are different from those in
	DECW$SYSTEM_DEFAULTS:XMCD.DAT.  For example,
	define DECW$USER_DEFAULTS to point to your login directory:

	    $ define DECW$USER_DEFAULTS SYS$LOGIN:

	Then copy XMCD.AD to DECW$USER_DEFAULTS:XMCD.DAT and apply your
	personal settings there.  You only need to put in there the
	parameters that differ from the defaults in the
	DECW$SYSTEM_DEFAULTS:XMCD.DAT file.  If you don't copy XMCD.DAT
	to the DECW$SYSTEM_DEFAULTS: area then remember to define the
	logical DECW$USER_DEFAULT in your LOGIN.COM file so that it gets
	defined each time you log in.

    6. Pointing to the xmcd library:

	Your xmcd library directory should now be complete:

	    $ DIR SYS$SYSDEVICE:[XMCD]

	    Directory SYS$SYSDEVICE:[XMCD]

	    COMMON.CFG;1
	    DEVICE.CFG;1
	    DOCS.DIR;1
	    HELP.DIR;1

	You need to set up xmcd such that it can find the library directory.
	This is done via the XMCD_LIBDIR definition:

	    $ DEFINE/SYS XMCD_LIBDIR "SYS$SYSDEVICE:[XMCD"

	Note that the right bracket is missing.  This is intentional.
	The program will concatenate the directory names to form a path
	name for library subdirectories.  You should put this in the
	the system startup procedure (SYS$MANAGER:SYSTARTUP_VMS.COM).  If
	that is not possible, you can put it (without the /SYS qualifier) in
	your personal LOGIN.COM so that it is done automatically each time
	you log in. 

    7. Set up CD information directory (optional):

	If you have xmcd version 2.x previously installed on your system,
	there is a CDDB.DIR directory under your xmcd library.  This has
	been deprecated, but this release of xmcd will continue to read
	files from that directory, if you rename it to be CDINFO.DIR.
	CDINFO.DIR has to be resident in this release's top level directory.

    8. Set up xmcd to drive a web browser (optional):

	Copy the INSTWEB.COM command file from the MISC_D area and the 
	WWWWARP.CFG configuration file from the CDINFO_D area to the
	xmcd library directory. You may then execute INSTWEB.COM in that 
	directory. This will ask you a number of questions and then
	install wwwWarp support for xmcd.

	If you wish to add wwwWarp support manually (i.e., not using the
	INSTWEB.COM command), follow the instructions below.

	- Make sure you have a copy of NETSCAPE.EXE or/and MOSAIC.EXE in 
	  SYS$SYSTEM: (e.g., SYS$SYSDEVICE:[SYS0.SYSEXE]).

	- Check whether you have the CMKRNL (Change Mode Kernel) privilege.
	  This is essential, because GOBROWSER.COM needs to make use of
	  ANALYZE/SYSTEM which requires this privilege.

	- Edit the WWWWARP.CFG file and locate the "Xmcd man page" and
	  "Xmcd Local Discography" entries.  Change them to look like
	  the following:

	    "Xmcd man page"				Alt-m	f.goto \
		    "%L.DISCOG]XMCD.HTML"
	    "Xmcd Local Discography"		Shift-L	f.goto \
		    "%L.DISCOG.%C.%I]INDEX.HTML"


	- Copy the GOBROWSER.COM and GENIDX.COM command procedure files to
	  xmcd's library directory.  These files are found in the MISC_D
	  area.

	- Modify your LOGIN.COM to add following lines:

	    $ IF F$MODE() .NES. "OTHER" THEN DEFINE/GROUP XMCD_BROWSER MOSAIC
	    $ GOBROWSER :== @disk:[dir]GOBROWSER.COM
	    $ GENIDX    :== @disk:[dir]GENIDX.COM

	    First line:  If you prefer Mosaic as your default browser, just
			 insert this line into your LOGIN.COM.
			 If you prefer Netscape, exchange MOSAIC with
			 NETSCAPE in this line. Of course you need to have
			 the Mosaic and/or Netscape executable (see below).
	    Second line: 'disk:[dir]' is meant to be xmcd's library directory.

	  Restart your login session, or execute the above commands manually
	  so that they can take effect.


	Now you are done and should be able to use xmcd's wwwWarp features.

	One more hint if you have the GRPPRV privilege:
	-----------------------------------------------

	If you have both Mosaic and Netscape handy, you can change the
	browser for xmcd on the fly:

	- Go to a text window where you can enter DCL commands.
	- Enter
	  DEFINE/GROUP XMCD_BROWSER 'mybrowser'

	  Where 'mybrowser' is NETSCAPE or MOSAIC

	- Go to xmcd's wwwWarp window and select a site - now the designated
	  browser will pop up.

	This means you can use both browsers simultaneously or override the
	default specified in your LOGIN.COM prior to starting xmcd.  You
	can also go to a text window, change the browser as described above
	and then start an alternate browser by simply clicking on some site
	in xmcd's wwwWarp window.

    9. Setting up the Local Discographies area (optional):

	The Local Discographies area is for storing files pertaining to your
	CD collection.  These files can be documents, images, sound files,
	etc., that are associated with each CD.  You may deposit these files
	under the SYS$SYSDEVICE:[XMCD.DISCOG.%C.%I] directory (where %C is
	the CDDB genre/subgenre names and %I is the xmcd 8-digit disc ID),
	and then use xmcd's wwwWarp feature to view or play these files.
	A plug-in for the browser may be required for some file types.

	This is used only if you enable wwwWarp support (see "Setting up
	xmcd to drive a web browser" above).

	To set this up, follow these steps:

	- Create the main Local Discographies area and all the music category
	  areas under it:

	    $ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG]
	    $ GENIDX

	- Copy the DISCOGVMS.HTM, BKGND.GIF and XMCDLOGO.GIF files in the
	  MISC_D area to the SYS$SYSDEVICE:[XMCD.DISCOG] area.  Rename the
	  DISCOGVMS.HTM to DISCOG.HTML at the destination location.  Also
	  copy the XMCD.HTM file under XMCD_D to the
	  SYS$SYSDEVICE:[XMCD.DISCOG] area and rename it XMCD.HTML.

	- If you already have a xmcd 2.x Local Discography area with
	  CD-related INDEX.HTML files, you may backup these files to the
	  structure created by GENIDX. Please note the differences in
	  subdirectory names between xmcd 2.x and 3.x. Also be aware that
	  the HTML links in these INDEX.HTML files partially won't work
	  any longer. The automatic installation done by INSTALLVMS.COM
	  fixes this problem.

	- To enable browsing your local discography directories you need
	  to define the logical $DISCOGDIR by adding the following line
	  to your personal LOGIN.COM (in an appropriate place after the
	  lines containing the XMCD_BROWSER definition):

	    $ DEFINE/JOB $DISCOGDIR DKA0:[XMCD.DISCOG.] -
	       /TRANSLATION_ATTRIBUTES=(TERMINAL,CONCEALED)

	- If you prefer to only display images (f.i. CD covers) stored in
	  your Local Discographies area you may add the following line
	  to your personal LOGIN.COM (in an appropriate place next to the
	  line containing the XMCD_BROWSER definition):

	    $ IF F$MODE() .NES. "OTHER" THEN DEFINE/GROUP XMCD_VIEWER XV

	  If you add this line to your LOGIN.COM, only local images as
	  defined in STARTVIEWER.COM will be displayed by XV.
	  If you do not add this line to your personal LOGIN.COM xmcd
	  always will use the browser of your choice for displaying images
	  (like it does anyway with other non-local URLs).

	  One more hint if you have the GRPPRV privilege:
	  -----------------------------------------------

	  If you have Mosaic and/or Netscape and XV handy and if you make
	  use of XV for only displaying images, you can change the viewer
	  for xmcd on the fly:

	  - Go to a text window where you can enter DCL commands.
	  - Enter
	    DEFINE/GROUP XMCD_VIEWER 'myviewer'

	    Where 'myviewer' is either NETSCAPE or MOSAIC or XV

	  - Go to xmcd's wwwWarp window and select a site - now the
	    designated browser will pop up. If you select "Local Discograhy"
	    the designated viewer will pop up.

	  This means you can use all browsers/viewers simultaneously or
	  override the defaults specified in your LOGIN.COM prior to
	  starting xmcd.  You can also go to a text window, change the
	  browser or viewer as described above and then start an alternate
	  browser or viewer by simply clicking on some site or item in
	  xmcd's wwwWarp menu.

	  The possibility to have XV display GIFs or JPEGs was added because
	  the viewing quality is better with XV than with the web browsers.
	  Furthermore the picture's size is preselectable when using XV
	  (see STARTVIEWER.COM) and it won't take half your screen to view
	  an image (f.i. a scanned CD cover).


RUNNING XMCD
------------

You need to have the DIAGNOSE and PHY_IO privileges in order to run
xmcd.

	$ SET PROC/PRIV=(DIAGNOSE,PHY_IO)

You can just enter $ RUN XMCD or use the XMCD foreign command at the
DCL prompt to start xmcd.

If you like to add xmcd to your Session Manager Application pull down
menu do the following:

1) Pull the Options Menu down in the Session Manager window, and
   select the Menus... option.

2) Select the Item Name text box.  The Item Name text box is just
   above where it says "DCL Command" and just left of "Options Qualifiers".
   Add the name that you want to give to this application.  For example
   CDPlayer.

3) Select the DCL Command text box, and add a suitable command according to this

    example:

      $SYS$SYSDEVICE:[XMCD]XMCD.EXE
   

4) Select the Up arrow button (just to the right of "Options Qualifiers")

   The application name is now in the Item Names Menu, and it should be 
   highlighted.  

5) To the left of the Item Names menu there is a left arrow button.
   Select this button and the application will be displayed in the
   Applications Menu.

6) Choose the Apply button then the Cancel button.

7) Then in the Options Menu in the Session Manager window choose
   Save Session Manager.


SPECIAL IDE/ATAPI DRIVE NOTES
-----------------------------

While starting xmcd if you get a pop up warning message "Device is not
SCSI-2 compliant", change the setting of the scsiVersionCheck parameter
in your DEVICE.CFG file to False.

If you encounter error messages while attempting to play a CD and
the time display does not advance, change the setting of the curposFormat
parameter in your DEVICE.CFG file.

If you encounter errors while using xmcd's volume or balance sliders,
or the channel routing control buttons, it is due to the SYS$DQDRIVER
or the CD drive itself not implementing these features.  Change the
following parameters to False in your DEVICE.CFG file to disable the
controls in xmcd:

	volumeControlSupport
	balanceControlSupport
	channelRouteSupport

If you made any changes to the DEVICE.CFG file as described above,
restart xmcd to have them take effect.


