request - Creates a removable-media file
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]
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
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
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.
This command accepts several options. In the following
list, the options are grouped according to function.
The following general options can be used for any type of
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
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
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
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
-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
Each vsn specified must reside in a local
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:
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.
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.
Specified a user information string. The
information string is written in the file's label
at creation time. Can be up to 159 characters.
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
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:
Removable-media files are not supported over NFS.