1.\" $NetBSD: chio.1,v 1.4 1997/10/02 00:41:25 hubertf Exp $ 2.\" 3.\" Copyright (c) 1996 Jason R. Thorpe <thorpej@and.com> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgements: 16.\" This product includes software developed by Jason R. Thorpe 17.\" for And Communications, http://www.and.com/ 18.\" 4. The name of the author may not be used to endorse or promote products 19.\" derived from this software without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" $FreeBSD$ 34.\" 35.Dd May 14, 1998 36.Dt CHIO 1 37.Os 38.Sh NAME 39.Nm chio 40.Nd medium changer control utility 41.Sh SYNOPSIS 42.Nm 43.Op Fl f Ar changer 44.Ar command 45.Op Fl <flags> 46.Ar arg1 47.Ar arg2 48.Op Ar arg3 Op ... 49.Sh DESCRIPTION 50The 51.Nm 52utility is used to control the operation of medium changers, such as those 53found in tape and optical disk jukeboxes. 54.Pp 55The options are as follows: 56.Bl -tag -width indent 57.It Fl f Ar changer 58Use the device 59.Ar changer 60rather than the default device 61.Pa /dev/ch0 . 62.El 63.Pp 64The default changer may be overridden by setting the environment variable 65.Ev CHANGER 66to the desired changer device. 67.Pp 68A medium changer apparatus is made up of 69.Em elements . 70There are five element types: 71.Em picker 72(medium transport), 73.Em slot 74(storage), 75.Em portal 76(import/export), 77.Em drive 78(data transfer), and 79.Em voltag 80(select by volume identifier). The 81.Em voltag 82pseudo-element type allows the selection of tapes by their volume tag 83(typically a barcode on the tape). 84.Pp 85In this command description, the shorthand 86.Em ET 87will be used to represent an element type, and 88.Em EU 89will be used to represent an element unit. 90For example, to represent the first robotic arm in the changer, the 91.Em ET 92would be 93.Dq picker 94and the 95.Em EU 96would be 97.Dq 0 . 98.Sh SUPPORTED COMMANDS 99.Bl -tag -width indent 100.It Ic move Xo 101.Ar <from ET> <from EU> <to ET> <to EU> 102.Op Cm inv 103.Xc 104Move the media unit from 105.Ar <from ET/EU> 106to 107.Ar <to ET/EU> . 108If the optional modifier 109.Cm inv 110is specified, the media unit will be inverted before insertion. 111.It Ic exchange Xo 112.Ar <src ET> <src EU> <dst1 ET> <dst1 EU> 113.Op Ar <dst2 ET> <dst2 ET> 114.Op Cm inv1 115.Op Cm inv2 116.Xc 117Perform a media unit exchange operation. The media unit in 118.Ar <src ET/EU> 119is moved to 120.Ar <dst1 ET/EU> 121and the media unit previously in 122.Ar <dst1 ET/EU> 123is moved to 124.Ar <dst2 ET/EU> . 125In the case of a simple exchange, 126.Ar <dst2 ET/EU> 127is omitted and the values 128.Ar <src ET/EU> 129are used in their place. 130The optional modifiers 131.Cm inv1 132and 133.Cm inv2 134specify whether the media units are to be inverted before insertion into 135.Ar <dst1 ET/EU> 136and 137.Ar <dst2 ET/EU> 138respectively. 139.Pp 140Note that not all medium changers support the 141.Ic exchange 142operation; the changer must have multiple free pickers or emulate 143multiple free pickers with transient storage. 144.It Ic return Xo 145.Ar <from ET> <from EU> 146.Xc 147Return the media unit to its source element. 148This command will query the status of the specified media unit, and 149will move it to the element specified in its source attribute. 150This is a convenient way to return media from a drive or portal 151to its previous element in the changer. 152.Pp 153.It Ic position Xo 154.Ar <to ET> <to EU> 155.Op Cm inv 156.Xc 157Position the picker in front of the element described by 158.Ar <to ET/EU> . 159If the optional modifier 160.Cm inv 161is specified, the media unit will be inverted before insertion. 162.Pp 163Note that not all changers behave as expected when issued this command. 164.It Ic params 165Report the number of slots, drives, pickers, and portals in the changer, 166and which picker unit the changer is currently configured to use. 167.It Ic getpicker 168Report which picker unit the changer is currently configured to use. 169.It Ic setpicker Xo 170.Ar <unit> 171.Xc 172Configure the changer to use picker 173.Ar <unit> . 174.Pp 175.It Ic ielem Xo 176.Op Ar <timeout> 177.Xc 178Perform an 179.Em INITIALIZE ELEMENT STATUS 180operation on the changer. The optional 181.Ar <timeout> 182parameter may be given to specify a timeout in seconds for the 183operations. This may be used if the operation takes unusually long 184because of buggy firmware or the like. 185.It Ic voltag Xo 186.Op Fl fca 187.Ar <ET> 188.Ar <EU> 189.Op Ar <label> 190.Op Ar <serial> 191.Xc 192Change volume tag for an element in the media changer. This command 193is only supported by few media changers. If it is not supported by a 194device, using this command will usually result in an "Invalid Field in 195CDB" error message on the console. 196.Pp 197If the 198.Fl c 199flag is specified, the volume tag of the specified element is 200cleared. If the 201.Fl f 202flag is specified, the volume tag is superseded with the specified 203volume tag even if a volume tag is already defined for the element. 204It is an error to not specify the 205.Fl f 206flag when trying to set a label for an element which already has 207volume tag information defined. 208.Pp 209The command works with the primary volume tag or, if the 210.Fl a 211flag is given, with the alternate volume tag. 212.It Ic status Xo 213.Op Fl vVsSbIa 214.Op Ar <type> 215.Xc 216Report the status of all elements in the changer. If 217.Ar <type> 218is specified, report the status of all elements of type 219.Ar <type> . 220.It Fl v 221Print the primary volume tag for each loaded medium, if any. The volume 222tag is printed as 223.Dq <LABEL:SERIAL> . 224.It Fl V 225Print the alternate volume tag for each loaded medium, if any. 226.It Fl s 227Print the additional sense code and additional sense code qualifier for 228each element. 229.It Fl S 230Print the element source address for each element. 231.It Fl b 232Print SCSI bus information for each element. Note that this information 233is valid only for drives. 234.It Fl I 235Print the internal element addresses for each element. The internal 236element address is not normally used with this driver. It is reported 237for diagnostic purposes only. 238.It Fl a 239Print all additional information (as in 240.Fl vVsSba ) . 241.El 242.Pp 243The status bits are defined as follows: 244.Bl -tag -width indent 245.It FULL 246Element contains a media unit. 247.It IMPEXP 248Media was deposited into element by an outside human operator. 249.It EXCEPT 250Element is in an abnormal state. 251.It ACCESS 252Media in this element is accessible by a picker. 253.It EXENAB 254Element supports passing media (exporting) to an outside human operator. 255.It INENAB 256Element supports receiving media (importing) from an outside human operator. 257.El 258.Sh EXAMPLES 259.Bl -tag -width indent 260.It Li chio move slot 3 drive 0 261Move the media in slot 3 (fourth slot) to drive 0 (first drive). 262.It Li chio move voltag VOLUME01 drive 0 263Move the media with the barcode VOLUME01 to drive 0 (first drive). 264.It Li chio return drive 0 265Remove the tape from drive 0 (first drive) and return it to its original 266location in the rack. 267.It Li chio setpicker 2 268Configure the changer to use picker 2 (third picker) for operations. 269.El 270.Sh FILES 271.Bl -tag -width /dev/ch0 -compact 272.It Pa /dev/ch0 273default changer device 274.El 275.Sh SEE ALSO 276.Xr mt 1 , 277.Xr mount 8 278.Sh AUTHORS 279.An -nosplit 280The 281.Nm 282program and SCSI changer driver were written by 283.An Jason R. Thorpe Aq thorpej@and.com 284for And Communications, 285.Pa http://www.and.com/ . 286.Pp 287Additional work by 288.An Hans Huebner 289.Aq hans@artcom.de 290and 291.An Steve Gunn 292.Aq csg@waterspout.com . 293