mcicap - media changer capability database
/etc/mcicap
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 command.
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 abbreviation
for the media changer. The first and second names
should contain no blanks. The third name
(another_alt_name) is optional and may contain blanks for
readability; it should be a long name, fully identifying
the media changer. Following the media changer's names
are its capabilities. Each capability is separated by a
colon (:). Capabilities 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 [Toc] [Back]
The capabilities that you list in an mcicap file entry
each consist of two-letter codes, possibly followed by
further information. The various 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 autoeject.
Therefore, 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 [Toc] [Back]
A listing of all capability codes appears in this section.
For clarity, 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: Autoeject.
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 operation. Bar code
reader. Indicates that the media changer has the ability
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 example, 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 command, 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 documentation. Interface arguments.
Contains interface-specific information.
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 interface (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 contained 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.
Indicates that the media changer supports a logging
interface capability 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 manual 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 physical 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 documentation. Number of
slots. Specifies the number of slot type elements. The
media changer, when queried by the media changer driver,
may provide the number of slot type elements that it supports.
The ns capability 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. Number of
import/export ports. Specifies the number of port type
elements. 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-toelement
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 element. Indicates
that the media changer supports a release/reserve element
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 [Toc] [Back]
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 information. 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 command.
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
variable to the path name of the file containing the
description. The mcutil command reads that file rather
than the /etc/mcicap file. The MCICAP 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.
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.
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":
File containing media changer descriptions.
Commands: mcutil(1)
Files: mc(7) delim off
mcicap(4)
[ Back ] |
