@(#)INSTALL.VMS	6.19 99/04/11

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

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, the wm2xmcd database
translator and the cddbcmd utility are not currently supported.


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

Please see the PLATFORM file for minimum operating system version
requirements.  Also, DEC C version 5.6 or later is required.

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


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

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.

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

    Create the DOCS area in the xmcd library and copy the documentation
    files to it.

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

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

5. Setting up the CD database area:

    The CD database area is for storing CD artist, disc title, track
    titles and other information.  This is your local repository of the
    CD database.  If your xmcd binary was compiled with socket support,
    it can query one of the Internet CDDB(tm) servers for CD
    information.  Otherwise, you can type in the information for your
    music collection and save it to your local CD database.  If the
    cddbRemoteAutoSave parameter in COMMON.CFG is set to a non-zero value,
    the CD information obtained from the Internet CDDB servers will be
    automatically saved to your local database, so that the next time
    the same CD is loaded, xmcd would not need to access the network to
    query the CDDB server again.

    To set this up, create the main CD database area and all the
    music category areas under it:

	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB.BLUES]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB.CLASSICAL]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB.COUNTRY]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB.DATA]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB.FOLK]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB.JAZZ]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB.MISC]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB.NEWAGE]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB.REGGAE]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB.ROCK]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.CDDB.SOUNDTRACK]

   These music categories are defined by CDDB, but you can also add your
   own categories in the local database.  To enable your own local categories,
   make the appropriate directories as above, and add the category names to
   your cddbPath parameter in the COMMON.CFG file.

   Note: The CDDB will only accept submissions in the official categories.

6. Pointing to the XMCD library:

    Your xmcd library directory should now be complete:

	$ DIR SYS$SYSDEVICE:[XMCD]

	Directory SYS$SYSDEVICE:[XMCD]

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

    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$SYSTEM_DEFAULTS:XMCD.DAT for system-wide or cluster-wide use.
    DECW$USER_DEFAULTS:XMCD.DAT may contain personal settings which are
    different from those in DECW$SYSTEM_DEFAULTS:XMCD.DAT.
    If you do not have the DECW$USER_DEFAULTS logical defined you need to 
    do that now so DECWindows can locate the file with your personal
    settings. 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.

    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 master 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:	cddb-submit@submit.cddb.com
	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:	SMTP%"""cddb-submit@submit.cddb.com"""

    Note the number of quotation marks around the Internet
    specification.

    Next change the mail command to:

	XMcd.cddbMailCmd:	MAILL/SUBJECT="%S" %F %A

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

7. 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$SYSDEVICE:[000000]XMCD.DIR
	$ SET FILE/PROT=W:RWE SYS$SYSDEVICE:[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

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

    Copy the INSTWEB.COM command file from the MISC_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 VMSWRAP.COM needs to make use of
      ANALYZE/SYSTEM which requires this privilege.

    - Copy the VMSWRAP.COM and GENIDX.COM command procedures 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
	$ VMSWRAP :== @disk:[dir]VMSWRAP.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.

    - Edit xmcd's COMMON.CFG and find the BrowserRemote parameter.
      Change both the BrowserRemote and BrowserDirect commands as follows:

	browserRemote:	VMSWRAP "-remote" "openURL(%U)"
	browserDirect:	VMSWRAP "%U"
  
      Disregard the comments in the file regarding the different browsers
      and their syntax - VMSWRAP.COM deals with this automatically.

    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
    CD database category name and %I is the 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]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG.BLUES]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG.CLASSICAL]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG.COUNTRY]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG.DATA]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG.FOLK]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG.JAZZ]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG.MISC]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG.NEWAGE]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG.REGGAE]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG.ROCK]
	$ CRE/DIR SYS$SYSDEVICE:[XMCD.DISCOG.SOUNDTRACK]

    - Copy the DISCOG.HTM, BKGND.GIF and XMCD14.GIF files in the MISC_D
      area to the SYS$SYSDEVICE:[XMCD.DISCOG] area.  Rename the DISCOG.HTM
      to DISCOG.HTML at the destination location.

    - Edit xmcd's COMMON.CFG and find the discographyURL: line.
      Change it to look like the following:

	discographyURL: %L.DISCOG.%C.%I]INDEX.HTML

      Xmcd will automatically generate this file and remote-control the
      web browser to open it when you invoke the Local Discography.

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

    - Execute the GENIDX.COM procedure to create the local discography
      per-category HTML index files. GENIDX.COM is set up to resubmit
      itself every day to the queue SYS$BATCH to keep up with the changes
      in your local discography. If the procedure cannot find this queue
      it will try to submit itself to a queue called XMCD$BATCH.  If the
      latter does not exist either it will exit and have to be executed
      manually from time to time.

      If you do not have the queue SYS$BATCH on your system, and you want
      this procedure to be run automatically each day you may setup
      the queue XMCD$BATCH by entering the following command:

	$ INITIALIZE/QUEUE/START/BATCH/JOB_LIMIT=2 XMCD$BATCH

      You may want to add this command to your system startup file
      (SYS$MANAGER:SYSTARTUP_VMS.COM).

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

      The possibility to have XV display GIFs or JPEGs was added because
      the viewing quality is much better with XV than with any of the 
      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 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.



