
                   VMS HISTO-SCOPE INSTALLATION GUIDE
                   
                   
Fermilab users with setup installed should install Histo-Scope in the
LIB: directory as described below:

Create a directory to contain the Histo-Scope product and restore the BACKUP
save set, for example:

   $ CREATE/DIR LIB:[LIB.HISTO]
   $ CREATE/DIR LIB:[LIB.HISTO.V3_0]
   $ BACKUP/LOG LIB:[LIB_SAVESETS]HISTO-V3_0.BCK/SAVE/SEL=[LIB.HISTO.V3_0...] -
     LIB:[LIB.HISTO.V3_0...]
   $ SET FILE/ENTER=LIB:[LIB.HISTO]CURRENT.DIR LIB:[LIB.HISTO]V3_0.DIR

However, the installer of Histo-Scope also needs to provide a directory in
which Histo-Scope users have read AND WRITE permission on a disk that either
has no quotas or on which all Histo-Scope users will have a quota.  The
installer of Histo-Scope may need the system manager to provide this directory.
The system manager will also need to define the logical name HISTO_PROCESS_DIR
as a system-wide logical name that points to this directory.  Possibilities
for creating HISTO_PROCESS_DIR include: USR$SCRATCH:[HISTO], a system disk
that does not have user quotas, or even LIB:[LIB.HISTO.PROCESS_DIR].

The special directory is necessary because Histo-Scope provides the
capability to browse data from running programs, and uses this directory
to establish contact between the Histo-Scope tool and user programs.
Every program that calls hs_initialize will create a one-line file that
registers itself as a potential Histo-Scope client.  The user of the
Histo-Scope tool will see his process listed by Histo-Scope and can then
select his process for browsing.  The goal of having one directory,
readable and writeable by all Histo-Scope users on the system is so that
all physicists on an experiment can access a running program even though
they have different login accounts.  This is also consistent with how
Histo-Scope works on Unix where the identification files are created in
/tmp.  The protection mechanisms used by Histo-Scope are those inherent
in Multinet and VMS.  Histo-Scope does not bypass any VMS or Multinet 
protections.  Histo-Scope also cleans up the HISTO_PROCESS_DIR directory 
periodically.

The Histo-Scope setup file prints a warning message if HISTO_PROCESS_DIR
is not defined to ensure that these additional steps are performed after
installation.

The following are example steps to finish the installation of Histo-Scope:

   1) The system manager creates the directory:
   
        $ CREATE/DIR USR$SCRATCH:[HISTO]/OWNER=LIB
        
   2) The appropriate protection for the directory is set:
        
        $ SET PROTECTION=(GROUP:RWE,WORLD:RWE) USR$SCRATCH:[000000]HISTO.DIR
        
   3) The system manager adds the logical name definition to SYLOGICALS.COM
      or SYSTARTUP_V5.COM:
      
        $ DEFINE/SYS/EXEC HISTO_PROCESS_DIR USR$SCRATCH:[HISTO]

You can verify that everything is set up properly by running an example 
program:

     $ SETUP HISTO
     $ RUN HISTO_ROOT:[EXAMPLES]APIEXAMPLE

On VMS, Histo-Scope requires TGV Multinet for the TCP/IP communications
between the data-generating process and the Histo-Scope process.  In one 
version of VMS Multinet, Version 3.3, The MULTINET_SOCKET_LIBRARY shareable 
image did not include the routine for getsockname, which is required
by any application that calls HS_INITIALIZE and is linked with the
Histo-Scope libraries.  TGV has a patch for the V3.3 shareable and should
have fixed this problem in their next release of Multinet.  If you need
to obtain a copy of the patched Multinet shareable image send mail to 
service@TGV.COM.

If you find that running the Histo-Scope executable (HISTO_DIR:HISTO.EXE)
gives you an error message complaining of shareable image version mis-matches,
you can rebuild Histo-Scope by copying HISTO_ROOT:[REBUILD_HISTO]*.* or just
SET DEFAULT to this directory.  Then type:

     $ @HISTO_DIR:GENERATE

which will re-build HISTO.EXE, which can be copied or re-named to the
HISTO_DIR directory.


If Histo-Scope will be used with YBOS, the BCOPY_SHR shareable image must
be created by setting up whatever you need to access YBOS and CERN, then:

    $ SET DEFAULT HISTO_ROOT:[REBUILD_BCOPY_SHR]
    $ @GENERATE_BCOPY_SHR

And then copying BCOPY_SHR.EXE to HISTOLIB_DIR after verifying that it
works properly.  For additional information, please refer to:

    HISTO_ROOT:[DOC]YBOS_USAGE_NOTE.TXT
