unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



mcutil(1)							    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	fol-
  lowing element types:	slot, drive, transport,	or port. You may use addi-
  tional characters. For example, slots	instead	of s, but only the first
  character is recognized. The n variable is the digit representing the	logi-
  cal 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 combina-
  tion with one	of the following function options, or both:

  -M media_changer_name
      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 physi-
      cal media	changer. See the mcicap(4) Reference Page for information on
      the media	changer	capability database.

  -d  Outputs debugging	information to stderr.


  Function Options


  The following	are the	function flags listed in alphabetical order:

  -A  Allows removal of	media. (Enables	the media changer for extracting
      media.)

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

  -c  Prints the media changer movement	capability information.	Several	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:

      etype_source -> etype_dest
	  It is	legal to move media from an etype_source element type to an
	  etype_dest element type.

      etype_source <-> etype_dest
	  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	->&gt; 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	<&lt;->&gt; drive

  -e[etype | etype:n | etype:n-n]...
      Provides the status 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	argu-
      ments 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	argu-
      ments, 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	pro-
      duces 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:

      element_type
	  The element_type is one of the following: slot, drive, transport,
	  or port.

      number
	  number is the	logical	element	address	(a base	10 integer).

      states
	  states provides the states of	the element, which can be any mean-
	  ingful combination of	the following:

	  empty
	      Indicates	that the element does not contain media.

	  full
	      Indicates	that the element contains media.

	  access
	      Indicates	that the element is serviceable	by the media changer.

	  source=n
	      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).

	  invert
	      Indicates	that the element contains media	in an inverted state.

	  imp/exp(import/export)
	      Indicates	that the element contains media	placed by the opera-
	      tor.

	  except(x, x)
	      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.

      physical_address
	  physical_address is the element's physical address (a	base 10
	  integer), which is assigned by the media changer.

      [tag_info]
	  [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>

  -h  Prints the usage information to stdout.

  -i  Prints the inquiry data for the media changer. This data includes	the
      media changer's manufacturer and version number.

  -I  Initializes element status, causing the media changer to check all ele-
      ments 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 initiali-
      zation function varies greatly.

  -m etype_src:n etype_dest:n [t:n [invert]]
      Moves a medium from one element to another via a transport element. If
      a	transport element (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.

  -p [common_flags] etype:n [t:n]
      Positions	the transport (transport:0 by default) in front	of the speci-
      fied element.

  -P  Prevents removal.	Disallows the media changer from placing any media.

  -v  Outputs the version of the mcutil	program.

  -x etype_src:n etype_dest1:n etype_dest2:n [t:n [invert1] [invert2]]
      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 destina-
      tion 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 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 condi-
  tions	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 capa-
  bility 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 descrip-
  tion (if you can not write to	the /etc/mcicap	file).


RESTRICTIONS

  The mcutil command interfaces	to a variety of	media changer devices; there-
  fore,	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.

   1.  The following sample command line moves media from slot 0 to slot 1:
	    # mcutil -M	hp10 -m	s:0 s:1

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

   3.  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).

   4.  The following is	example	output from the	previous status	function com-
       mand line:
	    slot 0 [full,access] 11 <&lt;primary>&gt;:000080



FILES

  /etc/mcicap
      The media	changer	capability database

RELATED	INFORMATION

  Files: mcicap(4), mc(7).