mcutil(1)mcutil(1)NAMEmcutil - Media changer manipulation utility
SYNOPSISmcutil [-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
[invert1] [invert2]]
OPTIONS
In the command synopsis, all of the function flags are mutually exclu‐
sive. 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 following element types: slot, drive, transport, or port. You may
use additional characters. For example, slots instead of s, but only
the first character is recognized. The n variable is the digit repre‐
senting the logical 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
Common Options
The following are the common options, shown as common_flags in the syn‐
opsis section. These flags are used in combination with each other, in
combination with one of the following function options, or both: Over‐
rides 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. Outputs debugging information
to stderr.
Function Options
The following are the function flags listed in alphabetical order:
Allows removal of media. (Enables the media changer for extracting
media.) 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. There‐
fore, if the media changer is not attached to the system, an error may
result. Prints the media changer movement capability information. Sev‐
eral 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: It is legal to move media
from an etype_source element type to an etype_dest element type. 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 drives: slot <-> drive Provides the sta‐
tus 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
arguments 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 trans‐
port slot
The above command line is just like using the -e flag without
any arguments, except that the output will appear in the order
of the arguments provided. It is not an error to ask for ele‐
ment types which do not exist for a target jukebox. It is an
error if the request is for a specific address. The first com‐
mand line in the following example produces 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 output: The element_type is one of the following:
slot, drive, transport, or port. number is the logical element
address (a base 10 integer). states provides the states of the
element, which can be any meaningful combination of the follow‐
ing: Indicates that the element does not contain media. Indi‐
cates that the element contains media. Indicates that the ele‐
ment is serviceable by the media changer. Identifies the physi‐
cal 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 operator. Indicates that an exception
(error) occurred within the media changer. The two base 10 num‐
bers (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 codes. 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 brack‐
ets, which indicates the tag type. This prefix appears as fol‐
lows: <tag_type> Prints the usage information to stdout. Prints
the inquiry data for the media changer. This data includes the
media changer's manufacturer and version number. Initializes
element status, causing the media changer to check all elements
for media and any other status relevant to that element. It may
be useful or necessary to issue this command in the following
instances: 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
initialization function varies greatly. Moves a medium from one
element to another via a transport element. If a transport ele‐
ment (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. Positions the transport (transport:0 by
default) in front of the specified element. Prevents removal.
Disallows the media changer from placing any media. Outputs the
version of the mcutil program. 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 destination
can be the same - this results in an exchange of media between
the two elements. If a transport element is not provided, trans‐
port: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.
DESCRIPTION
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 conditions 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
capability 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 description (if you can not write to the /etc/mcicap file).
RESTRICTIONS
The mcutil command interfaces to a variety of media changer devices;
therefore, not every function flag is supported on each device.
EXAMPLES
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. The following sample com‐
mand line moves media from slot 0 to slot 1: # mcutil-M hp10 -m s:0
s:1 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 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). The following is example out‐
put from the previous status function command line: slot 0
[full,access] 11 <primary>:000080
FILES
The media changer capability database
RELATED INFORMATION
Files: mcicap(4), mc(7).
mcutil(1)