mcutil(1) General Commands Manual mcutil(1)
NAME
mcutil - Media changer manipulation utility
SYNOPSIS
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 [invert1] [invert2]]
OPTIONS
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 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 representing 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 synopsis section. These flags are used in combination with each other,
in combination 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 phys-
ical media changer. See the mcicap(4) Reference Page for information on the media changer capability database. Outputs debugging informa-
tion 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.
Therefore, if the media changer is not attached to the system, an error may result. Prints the media changer movement capability informa-
tion. Several lines of output are produced. Listed first are element types that can provide storage. Following that listing are descrip-
tions 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 status of the elements of the media changer. Note It is recommended that the initial-
ize 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 transport 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 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 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 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 operator. 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 codes. physi-
cal_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> 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 ele-
ment to another via a transport element. If a transport element (t:n) is not provided, transport:0 is assumed. The source and desti-
nation 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 plac-
ing any media. Outputs the version of the mcutil program. Exchanges (moves) two media. Moves the medium that is in the source ele-
ment (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, 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.
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 vari-
able 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/mci-
cap 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 command 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 output 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)