                           arcRead and arcWrite Utilities
                           ------------------------------

     To use the arcRead and arcWrite utilities, the user must perform a few
initial configuration tasks.  The code used by the utilities to access the
autochanger requires several device files to be set up by the user with 
appropriate permissions.  Note that the utilities currently only support
series 700 workstations running HP-UX version 9.0x.

1.  Create a passthru device file for the autochanger's controller device.
    To do so, you must be root (to use the mknod(1) commmand), and you must
    know the bus and SCSI addresses of the autochanger.

    Example:

    mknod /dev/ac.passthru c 105 0x201300

    In this example, we create a passthru device file called /dev/ac.passthru
    for an autochanger which is on the internal S700 SCSI bus at SCSI target
    ID 3.  The 'c' parameter indicates the device file is a character
    special (as opposed to a block special); the 105 is the passthru driver's
    major number.  The minor number, 0x201300, follows this format:

      nibble 5   nibble 4   nibble 3   nibble 2   nibble 1   nibble 0
    |----------|----------|----------|----------|----------|----------|
    |           Bus Address          |  tgt ID  |  LUN ID  |     0    |
    |----------|----------|----------|----------|----------|----------|

    The bus address can be found by an ioscan command.  Typically, the
    autochanger itself will not show up in the ioscan, but the drives in
    the autochanger will.  If the autochanger is on the built-in S700 
    SCSI bus, the bus address will be 0x201.  If it is on an EISA card,
    it will usually be something like 0x401, 0x402, 0x403, or 0x404.

2.  Change permissions of the device file.  If you plan to be running the
    arc* utilities as a non-root user, you must change the permissions so
    that normal users have read-write permission to the device file.  To do 
    so, use the chmod(1) command.

    Example:

    chmod 666 /dev/ac.passthru

3.  Create disk device files for the drives in the autochanger.  This 
    procedure is exactly like creating the device file for the autochanger,
    except the character special major number for the disk driver on S700
    HP-UX 9.0x is 47.  

    Example:

    mknod /dev/acdrv.1 c 47 0x201400

4.  Change permissions of the device files.  Again, if non-root users are
    going to be executing the arc* utilities, the drive device files must
    have read-write permissions set to allow normal users access.  Follow
    the instructions under step 2 above for each of the drive device files
    you created in step 3.

                              Surface Mapping
                              ---------------

     The arc* utilities require that the user specify which surfaces in the
autochanger are to be used for the import or export.  The surface list is
given on the command line, and has the following format:

     <slot>         ::= [integer number >= 1]
     <surface>      ::= <slot>[A | B]
     <surface list> ::= <surface> [surface]*

     Example:  1a 1b 2a 2b 5a

                               arcRead Usage
                               -------------


     The arcRead utility uses the NSR Archive object to import NSR volumes
and and restore files to a native filesystem.  If the -r (restore) option
is not specified, arcRead simply imports the metadata from the NSR volumes
and prints to screen some basic information about every file in the archive.

Usage:

arcRead -d devfile [-y] [-r directory] surface_list

-d devfile:    Devfile is the passthru device file for the autochanger.
[-y]:          Optional.  If this option is given, the test will ask the
               user to provide device file mappings for drives in the
               autochanger.  Otherwise, the test will attempt to create
               device files for the drives (you must be root for this to
               succeed).
[-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.
surface_list:  A list of one or more entries of the form [slot_number][A|B].

Example:

./arcRead -d ac1 -y 1A 1B 3A 3B

                                arcWrite Usage
                                --------------

     The arcWrite utility uses the NSR Archive object to export a directory
tree of files from a native filesystem to NSR format.  It copies the file
data to optical and then uses the Archive object to write the file metadata
in NSR format.

Usage:

arcWrite -d devfile -s srcdir -v volsetname -f filesetname [-y] surface_list

-d devfile:  Devfile is the passthru device file for the autochanger
-s srcdir:  Source directory.  This directory, and all its children,
            will be exported to optical in NSR format.
-v volsetname:  Volume set name (96 bytes max)
-f filesetname: File set name (32 bytes max)
[-y]:  Optional.  If this option is given, the test will ask the user
       to provide device file mappings for drives in the autochanger.
       Otherwise, the test will attempt to create device files for the
       drives (you must be root for this to succeed).
surface_list:  A list of one or more entries of the form [slot_number][A|B]

NOTES:  all surfaces must have the same sector size and media type (i.e.,
        all must be WORM or all must be rewritable).

Example:

arcWrite -d /dev/ac1 -s /users -v "Archive 1" -f "User directories" -y 1a 1b
2a 2b 4a 4b
