request(1)

NAME
     request - Creates a removable-media file

SYNOPSIS
     request [-f file_id] [-g group] [-i information] -m media
     [-N] [-n version] [-o owner]
     [-p position1[/position2/position3/ ...]]  [-s size]
     [-v vsn1[/vsn2/vsn3/ ...]]  file

     request [-f file_id] [-g group] [-i information]
     [-l vsnfile] -m media [-N] [-n version] [-o owner] [-s size]
     file

AVAILABILITY
     SUNWsamfs

DESCRIPTION
     The request command creates a removable-media file, which is
     a file that resides only on one or more removable media
     cartridges.  Such a file does not reside in online magnetic
     disk storage.  Removable media files allow you to read data
     from tape or magneto-optical cartridges directly to memory.
     Creating removable media files allows you to use cartridges
     in an automated library without having them under the
     control of SAM-QFS. In addition, removable media files can
     also be used for disaster recovery purposes.

     A removable media file can be written to more than one
     volume if the file is large.  This creates a volume overflow
     file.

     The -m media option to this command specifies the media type
     and is a required option.

     The Volume Serial Name (VSN) for the removable media file
     specifies the cartridges to which the removable media file
     will be written.  The VSNs can be specified in one of two
     ways:

     o  By specifying the -v vsn option.  If you specify the VSN
        using this option, you can also use the -p option to
        supply the position of the removable media file on the
        media.  You must be superuser to specify the -p option.

     o  By specifying the -l vsnfile option.

     Note that you cannot specify both the -v option and the -l
     option on the same request command line.

     When an application writes to a removable media file by
     using the open(2) system call with the oflag argument set to
     O_WRONLY, O_RDWR, O_CREAT, or O_TRUNC, the SAM-QFS file

     system is updated to reflect the data's position on the
     cartridge.  Subsequent read access using the open(2) call
     with oflag set to O_RDONLY results in a read of the data
     written during creation.

OPTIONS
     This command accepts several options.  In the following
     list, the options are grouped according to function.

General Options
     The following general options can be used for any type of
     removable-media cartridge:

     -l vsnfile
               Specifies the name of the file that contains the
               list of VSNs.

               Within a vsnfile, VSNs must be specified one per
               line.  Each line must contain a VSN name.  The vsn
               cannot be more than 6 characters in length for a
               tape or 31 characters in length for
               magneto-optical media.

               You can also specify the position within the
               vsnfile.  If specifying the position, begin each
               line with the VSN name, followed by a space
               character, and followed by a decimal or
               hexadecimal number that indicates the position on
               the medium.  If specifying in hexadecimal, precede
               the position indicator by Ox characters.

               Each VSN in the vsnfile must reside in a local
               automated library.

               This option cannot be specified in conjunction
               with the -v option.

     -m media  Specifies the media type.  For media, specify a
               media type as described on the mcf(4) man page.
               This is a required option.

     -p position1[/position2/position3/ ...]
               A number that specifies the position of the
               removable media file on the cartridge.  This
               option must be specified in conjunction with the
               -v option.  The number of positions specified must
               match the number of vsns specified on the -v
               option.

               The position can be specified in decimal or
               hexadecimal.  To specify hexadecimal, precede the
               position with 0x.  If specified, the media is

               positioned to position on each VSN.  The number of
               positions specified must match the number of VSNs.

               Note that SAM-QFS utilities usually print the
               position of the file on the medium in hexadecimal.
               You must be superuser to specify a position.

     -s size   Specifies the required size in bytes.  When file
               is opened for write access, sufficient space on
               the media must be available before the first write
               is done.

     -v vsn1[/vsn2/vsn3/ ...]
               Specifies one or more VSNs to which the removable
               media will be written.  The vsn cannot be more
               than 6 characters in length for a tape or 31
               characters in length for magneto-optical media.

               If more than one VSN is specified, separate them
               with slash characters (/).

               If you want to specify the position on the media,
               use the -p position argument in conjunction with
               this argument.

               Each vsn specified must reside in a local
               automated library.

               This option cannot be specified in conjunction
               with the -l option.

     file      Specifies the name of the file to be written to
               removable media.  This can be a full path name.
               The file must reside in a SAM-QFS file system.
               After the removable-media file is created,
               subsequent access to the file results in access to
               the specified removable-media cartridge.

Tape Media Options
     For tape files, each write to the media results in one tape
     block.  Each read of the media returns either a tape block
     or the first buffer-size bytes of the tape block, whichever
     is smaller.  The buffer size must be equal to or larger than
     the tape block in order to read the entire block.

     The following option can be used only if the removable media
     file is being written to tape media:

     -N   Specifies that the media is a foreign tape.  That is,
          the tape was not written in a SAM-QFS environment.  The
          tape must be barcoded, write protected, opened for read
          access only, and positioned to 0.

Magneto-Optical Media Options
     The following options can be used only if the removable
     media file is being written to magneto-optical media:

     -f file_id
               Specifies the recorded file name of the file to
               access (up to 31 characters).  The default is the
               file name portion (basename) of the path specified
               by file.  For requests in which file is greater
               than 31 characters, no default exists, and the -f
               argument is required.

     -n version
               Version number of the file.  If version is 0, the
               most current version is used for read access, and
               a new version is created for write access.  The
               default value is 0.  For write access, the file is
               updated with the new version number.

     -o owner  Specifies the owner.  Can be up to 31 characters.
               The default is the current user.  For
               magneto-optical disk files that are to be used to
               read archive images, the owner specification must
               be -o sam_archive.

     -g group  Specifies the group identifier.  Can be up to 31
               characters.  The default is the user's current
               group.  For magneto-optical disk files that are to
               be used to read archive images, the group
               specification must be -g sam_archive.

     -i information
               Specified a user information string.  The
               information string is written in the file's label
               at creation time.  Can be up to 159 characters.

EXAMPLES
     Example 1.  This example command is used to recover data
     from a tape-resident archive file at position 286
     hexadecimal on DLT volume YYY:

     request -m lt -v YYY -p 0x286 /sam1/xxx

     Example 2.  This example command shows how to specify
     multiple VSNs:

     request -m lt -v YYY/VVV/WWW -p 0x286/0x3f07/0x0x4 /sam1/xox

     Example 3.  This example has the same effect as the command
     line in Example 2, but it uses the -l option:

     request -m lt -l vsns /sam1/xox

     File vsns is as follows:

     YYY 0x286
     VVV 0x3f07
     WWW 0x0x4

SEE ALSO
     basename(1).

     open(2).

     mcf(4).

NOTES
     Removable-media files are not supported over NFS.