NOTE:

These tools have been improved and/or augmented with extra features
since this was written, but it still provides a reasonable overview,
and is therefore provided...

|-----------------------------------------------------------------------------|
|                             arcTools Usage Notes                            |
|-----------------------------------------------------------------------------|
-----------------
1.  GENERAL NOTES
-----------------

     Both arcRead and arcWrite make use of two separate configuration files to 
get information about device files and NSR volumes.  These two files are
detailed below.
     
1.1  acrc File

     This file is used to specify the device files corresponding to the
physical autochanger and its drives.  The acrc file is a text file in
human readable and editable form which accepts the following two rules:

1.1.1  acdev = <ac_device_file>

     In this rule, "acdev" is a keyword, as is the equal sign.  
<ac_device_file> is the pathname of the passthru device file corresponding
to the autochanger's controller device.

1.1.2  drive <drivenum> = <drv_device_file>

     In this rule, "drive" is a keyword, as is the equal sign.
<drivenum> is the number of the drive as given by the autochanger's front
panel; <drv_device_file> is the pathname of the character special disk device
file corresponding to the drive.

1.2  Jukebox Status file

     The status file contains information about available (unused) surfaces,
volume sets, and filesets.  Normally users will not need to interact directly
with the file, as arcRead and arcWrite generate and modify the file as
necessary.  The file accepts three rules:

1.2.1  volset <vsname> = <surface_list>

     "volset" and the equal sign are keywords.  <vsname> is a quoted string
containing the volume set name; if the volume set name contains either
backslashes or double quotes, those characters must be preceded by a 
backslash.  A <surface_list> is one or more terms of the form <slot_num><side>,
where <slot_num> is a positive integer and <side> is either 'a' or 'b'.
Example:  volset "small volume set" = 1a 1b 2a 2b

1.2.2  fileset <fsname> in <vsname>

     "fileset" and the equal sign are keywords.  <fsname> is a quoted string
containing the file set name (see 1.2.1 about names containing double quotes
or backslashes); <vsname> is the quoted string representing the name of the
volume set to which the fileset belongs.

1.2.3  avail <sector_size> <media_type> = <surface_list>

     "avail" and the equal sign are keywords.  This rule specifies which
surfaces (as given by the <surface_list>) are available for use, catagorized
by sector size (1024 or 512) and media type ("mo" or "worm").

1.3  Environment Variables

     Both arcRead and arcWrite understand two environment variables to specify
the acrc and jukebox status files.  Normally, if these environment variables
are set, users do not need to specify command line options for arcRead and
arcWrite to specify the acrc and jukebox status files.  If command line 
options are given to specify the files, the command line options OVERRIDE
the environment variable settings.

1.3.1  ACRC_FILE

     The environment variable ACRC_FILE specifies the pathname of the acrc
file.  

1.3.2  JBSTAT_FILE

     The environment variable JBSTAT_FILE specifies the pathname of the jukebox
status file.

-----------------
2.  ARCREAD USAGE
-----------------

Usage:

arcRead [-a acrcFile] [-s jbstatFile] [-r directory ] [-f fsname] 
        [-c cmrFile] [-l logFile] [-I] [-g volname] [-o outFile] -v vsname

[-a acrcFile]:    Optional.  Pathname of the acrc configuration file.
[-s jbStatFile]:  Optional.  Pathname of the jukebox status file.
[-r directory]:   Optional.  If this option is given, the test will
                  restore the files to the specified directory.  Note
                  that you must ensure that the target directory has
                  sufficient free space.
[-f fsname]:      Optional.  The file set name to import, quoted if 
                  necessary.  If not specified, the most recent fileset is
                  imported from the given volume set.
[-c cmrFile]:     Optional.  Used the specified cmrfile to compare metadata
                  from the imported fileset.
[-l logFile]:     Optional.  Specify the name of the difference file output
                  by the CMR validation.  Default is arcRead.out
[-I]:             Optional.  Do not do import
[-g volname]:     Optional.  Grow the volume set by one volume.
[-o outFile]:     Optional.  Overrides all other options; inventories the
                  jukebox and generates a status file with the specified
                  name.  
-v vsname:        Mandatory.  The volume set name, quoted if necessary.

Example:  

arcRead -a .acrc -s /tmp/jbstat.1 -v "Volset 1" -f "Fileset "

ENVIRONMENT VARIABLES:

The acrc file and the jukebox status file can both be specified by 
environment variables:

ACRC_FILE:    Environment variable containing the acrc file pathname.
JBSTAT_FILE:  Environment variable containing the jukebox status file 
              pathname.

Note that the -a and -s options will override any value in the corresponding
environment variable, and the -a and -s options are mandatory if the
environment variables are not set.

------------------
3.  ARCWRITE USAGE
------------------

Usage:

arcWrite [-a acrcFile] [-s jbStatFile] [-g volname] [-m mtype] [-z size] 
         [-c cmrFile] [-E] [-k] -v vsname -f fsname -d srcdir

[-a acrcFile]:    Optional.  Pathname of the acrc configuration file.
[-s jbStatFile]:  Optional.  Pathname of the jukebox status file.
[-g volname]:     Optional if -v is specified.  Grow the volume set
                  by one volume, with the specified name.
[-m mtype]:       Optional if vsname exists.  Media type of grow volumes.
                  Valid values are "mo" and "worm".
[-z size]:        Optional if vsname exists.  Sector size of grow volumes.
                  Valid values are 512 and 1024.
[-c cmrFile]:     Optional.  Overrides default CMR file name (export.out)
[-E]:             Optional.  Specifies that no fileset export is to occur;
                  volumes in the volume set are only labeled.
[-k]:             Optional.  Overrides ALL OTHER options.  Kills the volume
                  set specified with the -v option and frees its volumes to
                  the available lists.  Does not do an export.  USE WITH CARE.
-v vsname:        Mandatory.  Export to the specified volume set.
-f fsname:        Mandatory.  Specifies the name of the exported file set.
-d srcdir:        Mandatory.  Specifies the source directory for export.

Example:

arcWrite -a .acrc -s /tmp/jbstat.1 -v "Volset 1" -f "Fileset 2" -d /users

ENVIRONMENT VARIABLES:

The acrc file and the jukebox status file can both be specified by
environment variables:

ACRC_FILE:    Contains the acrc file pathname.
JBSTAT_FILE:  Contains the jukebox status file pathname.

Note that the -a and -s options will override any value in the corresponding
environment variable, and the -a and -s options are mandatory if the
environment variables are not set.

---------------
4.  JBINV USAGE
---------------

     jbinv is a ksh script that generates jukebox status files.  It is 
normally used when "bootstrapping" a new autochanger to the system (or prior
to the first usage of arcRead or arcWrite), or after volumes have been added
to or removed from the jukebox.

Usage:

jbinv [-a acrcFile] -s jbStatFile

-a acrcFile:    specify acrc file.  Optional if ACRC_FILE environment
                variable is set.
-s jbStatFile:  Name of the output jukebox status file.

----------------
5.  KILLVS USAGE
----------------

     killvs is a ksh script that destroys ("kills") volume sets, and frees
their volumes for use as available volumes.  It updates the jukebox status
file appropriately if one is specified.

Usage:

killvs [-a acrcFile] [-s jbstatFile] -v vsname

-a acrcFile:   specify acrc file.  Optional if ACRC_FILE environment
               variable is set.
-s jbstatFile: specify jukebox status file.  Optional if the
               JBSTAT_FILE environment variable is set.
-v vsname:     Name of the volume set to destroy.

     NOTE:  Currently there is a bug in the command-line parsing in the script.
If the volume set name contains white space, it will not be parsed correctly.
If you want to kill a volume set whose name contains white space, run 
arcWrite instead of killvs with the same arguments (quoting the vsname 
appropriately).

-------------------
6.  NUKELABEL USAGE
-------------------

     nukeLabel is a ksh script which destroys NSR volume labels using raw
disk I/O.  It is particularly useful while debugging the Archive object
labeling features, or if an export failed midway through the process, which
might leave the volumes labeled, so that they cannot be subsequently used
as unlabeled volumes, yet not labeled enough to add as a volume set.  You
must have the executable program "acpt_move" in your path for this script to
work.

Usage:

nukeLabel:  A simple ksh script to forcibly overwrite any NSR volume 
            labels from a surface.  
 
Usage:  nukeLabel acdev drivedev element flip

acdev:     Passthru character device file for the autochanger's controller
drivedev:  Disk character device file for a drive in the autochanger
element:   Element number of the surface to nuke.  Note that element number
           is NOT the same as slot number.  To convert from slot number to
           element number, use the following equations:

           For HP autochangers prior to Sunspot:  element = slot_num + 10
           For Sunspot and Solar Flare:           element = slot_num + 30

flip:      This parameter should be 0 if side A is desired, 1 for side B.

     This script assumes that you have the passthru move medium program
acpt_move in your path.  The executable has been checked into HMS under
nsr/msVerify/acpt_move.

-------------------
7.  ARCBROWSE USAGE
-------------------

     arcBrowse is basically arcRead with a few extra features, so its
command-line arguments are identical, except that you cannot specify -I, -o,
-c, or -l (okay, so the arguments aren't exactly identical).  arcBrowse
imports the specified fileset and puts the you into a small simulated
shell (the "bsh", or browseShell).  Type 'help' to get a list of valid
commands and their arguments.  The restore capability of arcBrowse is 
a bit more flexible than arcRead in that it allows you to restore subtrees
of the imported fileset to the native file system.
