mcicap(4)mcicap(4)NAMEmcicap - media changer capability database
SYNOPSIS
/etc/mcicap
DESCRIPTION
The mcicap file is a database consisting of media changer descriptions.
Each entry within the mcicap file describes a specific media changer,
or a model of media changer.
The entries within the mcicap file are used by certain functions within
the media changer driver software. For example, entries are necessary
for all media changers that you plan on accessing with the mcutil com‐
mand.
An mcicap file entry has the following form:
name|alt_name|another_alt_name:capability:capability: ...
This form is described as follows: The vertical bars (|) are part of
the entry. Fields are separated by colons (:). The first field lists
all names that are used for the particular media changer, separated by
vertical bars (|). The first name (name) is the most common abbrevia‐
tion for the media changer. The first and second names should contain
no blanks. The third name (another_alt_name) is optional and may con‐
tain blanks for readability; it should be a long name, fully identify‐
ing the media changer. Following the media changer's names are its
capabilities. Each capability is separated by a colon (:). Capabili‐
ties may be in any order, and are described in the following section.
An entry may continue onto multiple lines by inserting a backslash (\)
as the last character of the line that you wish to continue.
Capabilities
The capabilities that you list in an mcicap file entry each consist of
two-letter codes, possibly followed by further information. The vari‐
ous capabilities fall under three categories: The capability code, if
present in the entry, means that the media changer has a particular
feature. For example, the HP100 media changer has auto-eject. There‐
fore, the entry for a HP100 media changer includes the ae code. The
capability code must be followed by a pound sign (#) and a number. For
example, the following ns capability code setting indicates that there
are 144 slot elements:
ns#144 The capability code must be followed by an equal sign and
a string. The string must be enclosed within double quotes if
it contains any whitespace; otherwise, double quotes are
optional. For example, the following dt capability code setting
indicates that the data transfer unit is a disk type:
dt=disk
Capability Codes
A listing of all capability codes appears in this section. For clar‐
ity, the following conventions are used: Boolean capability codes are
shown exactly as they would appear in an entry (as a two-letter code)
Numeric capability codes are followed by #n String capability codes
are followed by =string
The following is a list of all capability codes: Auto-eject. Indicates
that the media changer does not need to send an explicit eject sequence
to a drive when the drive is the source of a move or exchange opera‐
tion. Bar code reader. Indicates that the media changer has the abil‐
ity to return the bar code information printed on the medium. The
information is returned in the volume tag field (the last field) in the
output of the element status function. The element status function is
the -e option to the mcutil command. Device names. Contains a list
(separated by commas) of the device names for the accessible drives.
If the first character of a device name is a slash (/), then the name
is a full path to the device. If the first character of a name is not
a slash, then the /dev directory path is assumed as a prefix. For exam‐
ple, the following are equivalent device name capability code settings:
dn="mc0,mc5"
dn="/dev/changer/mc0, /dev/changer/mc5" Data transfer unit type.
Contains the disk or tape string. This information is needed
for the eject command if the device requires an explicit eject
operation. It is useful to provide this information regardless
of the status of the auto-eject capability because the mcutil
command can be used to provide configuration information.
Including the dt capability field could provide the mcutil com‐
mand, and therefore the user, with more information. Exchange
medium. Indicates that the media changer supports the exchange
medium capability as stated in the SCSI-II standards documenta‐
tion. Interface arguments. Contains interface-specific infor‐
mation. Media changers using the scsi2 interface type do not
use this field. The uagent interface requires the bus target
and logical unit number (LUN) identifiers of the media changer.
For example, the following interface argument setting is for a
device on bus 0, target 1, and LUN 1:
ia="0 1 1" Initialize element status. Indicates that the media
changer supports an initialize element status capability as
stated in the SCSI-II standards documentation. Interface type.
Specifies the interface type to connect to the media changer.
Currently, the scsi2 and uagent interface types are supported.
The scsi2 interface type uses the SCSI CAM Media Changer inter‐
face (see mc(7)) and therefore requires the SCSI CAM Media
Changer Driver to be built into the running kernel. The uagent
interface requires the CAM systems uagent driver, which is con‐
tained in any kernel running the SCSI CAM system. The /dev/cam
pseudo device is required and is used by the uagent driver to
communicate with the media changer. Log select/sense. Indi‐
cates that the media changer supports a logging interface capa‐
bility as stated in the SCSI-II standards documentation. Media
changer device file. Names the device file that is used for
controlling the media changer. For the scsi2 interface type it
is the device file that connects to the SCSI CAM Media Changer
Driver. For the uagent interface, the /dev/cam file is almost
always used.
MD=range
MP=range
MS=range
Physical maps. Maps the physical addresses of the slot (MS), drive
(MD), port (MP), and transport (MT) elements to their logical
addresses. Most SCSI-II compliant media changers provide element
address information so these entries are not required. The use of
physical map codes within an mcicap file entry is indicated when your
jukebox is not SCSI-II compliant, or when you wish to override the
jukebox addressing. By overriding the jukebox addressing you could,
for example, prevent a particular drive from being used. If you wish
to provide physical mapping information, see your jukebox hardware man‐
ual for the physical addresses of the elements.
The range value can be one of the following: A range from a
lower number to a higher number, indicated by using a minus sign
(-). For example, the following MS code setting indicates that
the physical address for the slot elements are 116, 117, 118,
and 119:
MS=116-119 A list of numbers or ranges separated by commas. For
example, the following MD code setting indicates that the physi‐
cal addresses for the drive elements are 111, 112, 113, 114,
115, 311, 210, 211, and 212:
MD=111-115,311,210-212
The media changer driver software maps logical addresses to physical
addresses. For each element type (slot, drive, port, or transport) the
logical addresses are mapped to the physical addresses consecutively
starting at logical address zero.
The following are examples of address mappings: Maps the physical slot
addresses 116, 117, 118, and 119 to the logical slot addresses 0, 1, 2,
and 3. Maps the physical drive addresses 111, 112, 113, 114, 115, 311,
210, 211, and 212 to the logical drive addresses 0, 1, 2, 3, 4, 5, 6,
7, and 8.
Note that for the above examples to map exactly as depicted, you should
indicate in your mcicap file entry the precise number of elements. In
other words, the two previous examples should include the following
capability code settings in the mcicap file entries:
ns#4
nd#9
Defaults for Mapping
If the quantity of a type of element or its physical addresses are not
provided within an mcicap file entry, then the jukebox is queried by
the driver software. If the quantity of a type of element becomes
known to the driver software but not all (or none) of the physical
addresses become known, then the "missing" physical addresses are
assumed to be the same as the corresponding logical addresses. Mode
select/sense. Indicates that the media changer supports a mode
select/sense capability as stated in the SCSI-II standards documenta‐
tion. Number of slots. Specifies the number of slot type elements.
The media changer, when queried by the media changer driver, may pro‐
vide the number of slot type elements that it supports. The ns capa‐
bility code setting overrides the number provided by the media changer.
Number of drives. Specifies the number of drive type elements. The
media changer, when queried by the media changer driver, may provide
the number of drive type elements that it supports. The nd capability
code setting overrides the number provided by the media changer. Num‐
ber of import/export ports. Specifies the number of port type ele‐
ments. The media changer, when queried by the media changer driver,
may provide the number of port type elements that it supports. The np
capability code setting overrides the number provided by the media
changer. Number of transports. Specifies the number of transport type
elements. The media changer, when queried by the media changer driver,
may provide the number of transport type elements that it supports.
The nt capability code setting overrides the number provided by the
media changer. Prevent/allow functionality. Indicates that the media
changer supports a prevent/allow capability as stated in the SCSI-II
standards documentation. Position-to-element. Indicates that the
media changer supports a position-to-element capability as stated in
the SCSI-II standards documentation. Read diagnostics. Indicates that
the media changer supports a read diagnostics capability as stated in
the SCSI-II standards documentation. Read element status. Indicates
that the media changer supports a read element status capability as
stated in the SCSI-II standards documentation. Release/reserve ele‐
ment. Indicates that the media changer supports a release/reserve ele‐
ment capability as stated in the SCSI-II standards documentation. Type
compatible entry field. Equates the string value to the first name of
a previous entry in the mcicap file. The entry in which the tc field
exists is compatible (has the same capabilities) as a previously
defined entry - the entry indicated by the string value. This allows
capabilities which are associated with the media changer model to be
defined once, while the more specific media changer information - such
as that regarding connectivity and device naming - is defined with each
individual media changer's logical name. For a sample of how to use
the tc field see the EXAMPLE section near the end of these reference
pages. Two-sided medium. Indicates that the jukebox media is double
sided; also indicates that the media changer transport mechanism can
perform an invert operation. Volume tag. Indicates that the jukebox
returns volume tag information (when valid) as part of the output for
the element status function. The element status function is the -e
option to the mcutil command.
Preparing Descriptions
The amount of information that must be provided in the mcicap file
entry is dependent on the particular jukebox. It is possible to have a
very short entry because the media changer can provide certain informa‐
tion. For example, the HP100 is typical of most SCSI-II compliant
media changers because the number and address of each element can be
provided by the media changer. Therefore, that information is not
required in the mcicap file entry. Some jukeboxes require an explicit
command to eject the media from the drive before a move from a drive
can be accomplished. Therefore, for some jukeboxes, you must provide
certain information within the mcicap file entry - information such as
device names - that allows for particular media changer operations.
Such an operation would be opening a drive and giving the eject com‐
mand.
If an mcicap file entry provides information that the media changer
also provides, the mcicap file entry takes precedence. For example, if
the media changer states it has X number of slots, the mcicap file
entry for that media changer changes that number by providing a ns
capability code setting. In this way you can, for example, make the
HP100 media changer look and act like it has fewer slots available.
The most effective way to prepare a media changer description is by
imitating the description of a similar media changer in the mcicap
file; then build up a description gradually. To check the validity of
a particular media changer description, use the mcutil command. To
test a new media changer description, set the MCICAP environment vari‐
able to the path name of the file containing the description. The mcu‐
til command reads that file rather than the /etc/mcicap file. The MCI‐
CAP environment variable can also be set to the mcicap file entry (to
avoid having the mcutil utility read a file). See the mcutil reference
page for more information.
RESTRICTIONS
A very unusual media changer may expose deficiencies in the ability of
the mcicap file to describe it. Also, an unusual media changer may
expose deficiencies in the mcutil command.
EXAMPLES
The following entry, which describes the TL800, is typical of an entry
in the mcicap file:
TL800|backup_tape_changer|remote_backup_TC:
:ae:re:is:ls:pe:pa:rs:
:dt=tape:
:mc=/dev/mc9:it=scsi2:dn="/dev/changer/mc9":
FILES
File containing media changer descriptions.
RELATED INFORMATION
Commands: mcutil(1)
Files: mc(7) delim off
mcicap(4)