#
# @(#)INSTALL.VMS	6.8 96/01/19
#
# xmcd - Motif(tm) CD Audio Player
#
# by Ti Kan
# OpenVMS port by Rick Jones
#


INTRODUCTION
------------

Please read through the following notes before attempting to compile
and 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 and the wm2xmcd
database translator are not currently supported.


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 location on the
Internet. One such location is the Digital FTP site:

	ftp://ftp.digital.com/pub/../.b/VMS

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

Create an XMCD Library:

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

    Example:

	$ CRE/DIR SYS$COMMON:[XMCD]

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
    (SYS$COMMON:[XMCD] in the example above).  

    If xmcd is to be used on a cluster, each user on their stand-alone
    system can 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.

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 directory HLPFILES.DIR under the XMCD_D area.

    Create the HELP area in the xmcd library and copy the help files to
    it.

	$ CRE/DIR SYS$COMMON:[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 screen.

Setting up the CD database area:

    If you have room on your disk there is a CD database which holds a
    number of files with the names of albums, and song titles which
    xmcd uses to display the appropriate informations for the CD you
    are listing to.  Also if a CD is not part of the database you can
    add the information to the database so that the next time you play
    the CD xmcd has the information.  The CD database is also a
    GZIPed/TARed file that you need to restore.  Restore this in the
    top level of the library area.  Once done your library area should
    look like this (from the example above):

	$ DIR SYS$COMMON:[XMCD]

	Directory SYS$COMMON:[XMCD]

	CDDB.DIR;1		 1
	COMMON.CFG;1		11
	DEVICE.CFG;1		20
	HELP.DIR;1		 5

Pointing to the XMCD library:

    You need to set up xmcd such that it can find the library directory.

    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.  Amongst these is the
    path to the xmcd library, and the mailing address of the CD database
    mail site.  To allow xmcd to use this file copy the XMCD.AD file
    to DECW$USER_DEFAULT:XMCD.DAT (or DECW$SYSTEM_DEFAULTS:XMCD.DAT if
    you want to make it system-wide or cluster-wide).  If you do not
    have the DECW$USER_DEFAULT logical defined you need to do that now
    so DECWindows can locate the file.  For example, define
    DECW$USER_DEFAULT to point to your top level directory:

	$ define DECW$USER_DEFAULT SYS$LOGIN:

    Then copy XMCD.AD to DECW$USER_DEFAULT:XMCD.DAT.  If you don't copy
    XMCD.DAT file to 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.

    Once done you need to edit the XMCD.DAT file to change the location
    of the library, the mail command and any colors you want changed.

    In the XMCD.DAT file there is a line to define the xmcd library that
    looks like this:

	XMcd*libdir:		/usr/lib/X11/xmcd

    Change this line to point to the location of where you the xmcd
    library is located.  From our example:

	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.

    Next, you will see the e-mail address of the CDDB mail site.  This
    allows you to contribute to the xmcd public CD database just by
    clicking a button.  If you do not have e-mail access to the Internet
    then skip this step.

    You will see two lines one for the site, and the other for the
    command:

	XMcd*cddbMailSite:	xmcd-cddb@amb.org
	XMcd*cddbMailCmd:	mailx -s '%S' %A <%F >/dev/null 2>&1

    If you have a gateway to the Internet, change the first line to
    prefix the node name of the gateway to the address.  For example:

	XMcd*cddbMailSite:	GATEWY::"""xmcd-cddb@amb.org"""

    Note the number of quotation marks around the Internet
    specification.

    Next change the mail command to:

	XMcd*cddbMailCmd:	mail /sub="%S" %F %A  

    Note: The case and order of the "S", "F", and "A" parameters are
    important.

Set the database to world read/write access:

    Make sure you set the file protection on the xmcd library and all
    files under it to W:RWE.  You need write access to add titles to the 
    database.  From our example:

	$ SET FILE/PROT=W:RWE SYS$COMMON:[000000]XMCD.DIR
	$ SET FILE/PROT=W:RWE SYS$COMMON:[XMCD...]*.*;*

    If you copied xmcd.dat to the DECW$SYSTEM_DEFAULTS: area you also need
    to make this file world readable.

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


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 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 the command 
   @vue$library:vue$cdplayer.com.  This file tells DECwindows how to
   run the application.

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) Next cut the following DCL command file out of this file and 
   copy it to vue$library:vue$cdplayer.com.

This assumes that xmcd was copied to SYS$SYSTEM:.

----------------X cut here X------------------
$!
$!  Command procedure to executive the CD application in DECwindows
$!
$! vue$suppress_output_popup
$!
$! See if we should skip the dialog box
$!
$    vue$get_symbol vue$show_hidden_dialogs
$    vue$read show_hidden_dialogs
$
$    if show_hidden_dialogs then goto select_qualifiers
$	vue$get_qualifiers
$	goto do_cd
$
$select_qualifiers:
$	vue$popup_qualifiers
$
$do_cd:
$
$ set proc/priv=(diagnose,phy_io)
$ run sys$system:xmcd 
$
$ vue$check_verb_loop
$ vue$read loop
$ if "''loop'" .eqs. "TRUE" then goto select_qualifiers
----------------X cut here X------------------

Make sure that this file (VUE$LIBRARY:VUE$CDPLAYER.COM) is W:RE
protected, and that xmcd.exe is W:RE in the SYS$SYSTEM: directory.


