unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



mcicap(4)							    mcicap(4)



NAME
  mcicap - 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 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 capa-
       bility 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

  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:

       Boolean capabilities
      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. Therefore, the entry for a HP100 media changer includes
      the ae code.

       Numeric capabilities
      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

       String capabilities
      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 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:

  ae  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 operation.

  br  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.

  dn=string
      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"

  dt=string
      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	mcu-
      til command can be used to provide configuration information.  Includ-
      ing the dt capability field could	provide	the mcutil command, and
      therefore	the user, with more information.

  ex  Exchange medium.	Indicates that the media changer supports the
      exchange medium capability as stated in the SCSI-II standards documen-
      tation.

  ia=string
      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"

  is  Initialize element status.  Indicates that the media changer supports
      an initialize element status capability as stated	in the SCSI-II stan-
      dards documentation.

  it=string
      Interface	type.  Specifies the interface type to connect to the media
      changer.	Currently, the scsi2 and uagent	interface types	are sup-
      ported.  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	ker-
      nel 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.

  ls  Log select/sense.	 Indicates that	the media changer supports a logging
      interface	capability as stated in	the SCSI-II standards documentation.

  mc=string
      Media changer device file.  Names	the device file	that is	used for con-
      trolling 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

  MT=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 phy-
      sical 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 fol-
      lowing 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	phy-
	    sical 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:

	     MS=116-119
      Maps the physical	slot addresses 116, 117, 118, and 119 to the logical
      slot addresses 0,	1, 2, and 3.

	     MD=111-115,311,210-212
      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 correspond-
	    ing	logical	addresses.

  ms  Mode select/sense.  Indicates that the media changer supports a mode
      select/sense capability as stated	in the SCSI-II standards documenta-
      tion.

  ns#n
      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.

  nd#n
      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.

  np#n
      Number 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.

  nt#n
      Number of	transports.  Specifies the number of transport type elements.
      The media	changer, when queried by the media changer driver, may pro-
      vide the number of transport type	elements that it supports.  The	nt
      capability code setting overrides	the number provided by the media
      changer.

  pa  Prevent/allow functionality.  Indicates that the media changer supports
      a	prevent/allow capability as stated in the SCSI-II standards documen-
      tation.

  pe  Position-to-element.  Indicates that the media changer supports a
      position-to-element capability as	stated in the SCSI-II standards
      documentation.

  rd  Read diagnostics.	 Indicates that	the media changer supports a read
      diagnostics capability as	stated in the SCSI-II standards	documenta-
      tion.

  re  Read element status.  Indicates that the media changer supports a	read
      element status capability	as stated in the SCSI-II standards documenta-
      tion.

  rs  Release/reserve element.	Indicates that the media changer supports a
      release/reserve element capability as stated in the SCSI-II standards
      documentation.

  tc=string
      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.

  ts  Two-sided	medium.	 Indicates that	the jukebox media is double sided;
      also indicates that the media changer transport mechanism	can perform
      an invert	operation.

  vt  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 information.  For	exam-
  ple, 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 imitat-
  ing 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.

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

  /etc/mcicap
      File containing media changer descriptions.

RELATED	INFORMATION

  Commands: mcutil(1)

  Files: mc(7)