mcutil - Media changer manipulation utility
mcutil [-A | -C | -c | - h | - i | - P | - I | -v] [common_flags]
mcutil [-e] [common_flags] -etype | -etype:n | -etype:n-n ...
mcutil [-m] [common_flags] etype_src:netype_dest:n [t:n [invert]]
mcutil [-p] [common_flags] etype:n [t:n]
mcutil [-m] [common_flags] etype_src:netype_dest:n etype_dest2:n [t:n
In the command synopsis, all of the function flags are mutually exclusive.
That is, of the following flags one, or none may be used: -A, -C, -c, -h,
-i, -P, -v, -e, -I, -m, -p, and -x.
All etype arguments and those starting with etype, such as etype_src, can
be one of the following characters: s, d,t, or p. These stand for the fol-
lowing element types: slot, drive, transport, or port. You may use addi-
tional characters. For example, slots instead of s, but only the first
character is recognized. The n variable is the digit representing the logi-
cal address of a specific element. For example slot:0 represents the first
slot of the jukebox.
When a range can be specified, the logical address is followed by a minus
sign and ending address. The range is inclusive. For example, the following
command line specifies slot 3 through, and including 5:
# mcutil -e s:3-5
The following are the common options, shown as common_flags in the synopsis
section. These flags are used in combination with each other, in combina-
tion with one of the following function options, or both:
Overrides the MCITYPE environment variable, or the default name mc0 (if
MCITYPE is not set). The media_changer_name specifies which entry in
the mcicap file is used to provide connection information to the physi-
cal media changer. See the mcicap(4) Reference Page for information on
the media changer capability database.
-d Outputs debugging information to stderr.
The following are the function flags listed in alphabetical order:
-A Allows removal of media. (Enables the media changer for extracting
-C Prints the complete configuration information for the media changer.
The information presented represents the information provided in the
mcicap file. The entry in the mcicap file has the ability to provide
all the information necessary regarding the media changer. If it does
not provide all the information, then the media changer may be queried
by the mcutil program for the rest of the information. Therefore, if
the media changer is not attached to the system, an error may result.
-c Prints the media changer movement capability information. Several lines
of output are produced. Listed first are element types that can provide
storage. Following that listing are descriptions of legal parameters
for the move and exchange functions (options -m and -x). Those
descriptions use the following syntax:
etype_source -> etype_dest
It is legal to move media from an etype_source element type to an
etype_dest element type.
etype_source <-> etype_dest
It is legal to exchange media between an etype_source element type
and an etype_dest element type.
Note that in the previous syntax lines, there may be more than one
etype_source or etype_dest element type listed. Multiple element types
are separated by single spaces. The following is an example output line
from the mcutil command using the -c option:
slot ->> drive port
The previous line indicates that the slot element type is a legal
source for the move function with a legal destination of a drive or
port element type. The following example output line indicates that the
exchange function may be used to exchange media between slots and
slot <<->> drive
-e[etype | etype:n | etype:n-n]...
Provides the status of the elements of the media changer. Note It is
recommended that the initialize element status function (the -I option)
be used before using this function. Using the -e flag without any argu-
ments returns the status of all known elements. Providing an argument
of an element type without a range returns the status of all elements
of that type. More than one element type (or element type and range)
may be given. Providing the element types in a particular order allows
the output to be customized. For example, the following command line
provides status on all known elements in the media changer:
mcutil -e drive port transport slot
The above command line is just like using the -e flag without any argu-
ments, except that the output will appear in the order of the arguments
provided. It is not an error to ask for element types which do not
exist for a target jukebox. It is an error if the request is for a
specific address. The first command line in the following example pro-
duces no output for a jukebox that does not have ports, while the
second command line produces a bad address error:
mcutil -e port
mcutil -e port:0
The mcutil command with the -e flag provides the following fields of
The element_type is one of the following: slot, drive, transport,
number is the logical element address (a base 10 integer).
states provides the states of the element, which can be any mean-
ingful combination of the following:
Indicates that the element does not contain media.
Indicates that the element contains media.
Indicates that the element is serviceable by the media changer.
Identifies the physical element address (n) where the media
came from. In other words, n is the last location of the media,
before it was moved to this location (element).
Indicates that the element contains media in an inverted state.
Indicates that the element contains media placed by the opera-
Indicates that an exception (error) occurred within the media
changer. The two base 10 numbers (x,x) are provided to diagnose
the problem. They are media changer dependent code numbers.
Refer to the media changer's hardware manual to translate the
physical_address is the element's physical address (a base 10
integer), which is assigned by the media changer.
[tag_info] is an optional field. It contains up to three tags: the
primary, alternate, and vendor tags. Each tag is marked with a
title prefix within angle brackets, which indicates the tag type.
This prefix appears as follows: <tag_type>
-h Prints the usage information to stdout.
-i Prints the inquiry data for the media changer. This data includes the
media changer's manufacturer and version number.
-I Initializes element status, causing the media changer to check all ele-
ments for media and any other status relevant to that element. It may
be useful or necessary to issue this command in the following
+ after a power failure.
+ after the medium has been changed by an operator.
+ after the configurations have been changed.
The time required for a media changer to perform this status initiali-
zation function varies greatly.
-m etype_src:n etype_dest:n [t:n [invert]]
Moves a medium from one element to another via a transport element. If
a transport element (t:n) is not provided, transport:0 is assumed. The
source and destination elements may be the same, but this may result in
an error depending upon the media changer. For example, to invert media
with a media changer which supports two sided media, the source and
destination are the same. Note that the transport element must be
explicitly mentioned (by indicating its logical address n) when
requesting an invert operation via the keyword invert.
-p [common_flags] etype:n [t:n]
Positions the transport (transport:0 by default) in front of the speci-
-P Prevents removal. Disallows the media changer from placing any media.
-v Outputs the version of the mcutil program.
-x etype_src:n etype_dest1:n etype_dest2:n [t:n [invert1] [invert2]]
Exchanges (moves) two media. Moves the medium that is in the source
element (etype_src:n) to the first destination (etype_dest1:n). Moves
the medium that is originally in the first destination to the second
destination (etype_dest2:n). The source element and the second destina-
tion can be the same - this results in an exchange of media between the
two elements. If a transport element is not provided, transport:0 is
assumed. In addition to being moved, media may be inverted. Since
there are two media involved in this command, it is necessary to
specify which media should be inverted by the keywords invert1 and
invert2. The invert1 and invert2 keywords refer to the source medium
and the medium originally contained in destination 1, respectively.
Note that the transport element must be explicitly mentioned when
requesting an invert of either media. Support for this command requires
that the media changer can handle two units of media at the same time,
or that it can emulate this capability.
The mcutil utility provides a means to manipulate media changer devices.
The utility uses the media_changer_name to locate an entry in the mcicap
file, which contains configuration information. If the media_changer_name
is not provided either via the MCITYPE environment variable or the -M
option to the mcutil command, then the default name of mc0 is used. The
MCICAP environment variable is used by the mcutil utility for configuration
information (instead of reading the mcicap file), if the following condi-
tions are true:
+ The MCICAP environment variable is set to a string that does not begin
with a slash.
+ The media_changer_name specified in the MCICAP environment variable
string agrees with the one provided to the mcutil command. (Either via
the MCITYPE variable or the -Moption to the mcutil command.)
If the MCICAP environment variable string begins with a slash, then it is
used (instead of /etc/mcicap) as the pathname for the media changer capa-
bility database file. Note that the MCICAP environment variable is not
required. Setting the MCICAP environment variable can speed up entry, help
debug new media changer descriptions, or allow a new media changer descrip-
tion (if you can not write to the /etc/mcicap file).
The mcutil command interfaces to a variety of media changer devices; there-
fore, not every function flag is supported on each device.
Note that the first two sample command lines in this section specify an
entry in the media changer capability database (the mcicap file). That
entry is for the media changer named hp10.
1. The following sample command line moves media from slot 0 to slot 1:
# mcutil -M hp10 -m s:0 s:1
2. The following sample command line moves the media from slot 1 to drive
0 via transport 0. At the same time, the media is inverted:
# mcutil -M hp10 -m s:1 d:0 t:0 invert
3. The following is an example of a status function command line:
# mcutil -e slot:0
Note here that for any element type parameter, you may use a single
letter or additional letters (as in the previous command line where
slot is spelled out).
4. The following is example output from the previous status function com-
slot 0 [full,access] 11 <<primary>>:000080
The media changer capability database
Files: mcicap(4), mc(7).