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.Oo 49.Ar arg3 Oo ... 50.Oc 51.Oc 52.Sh DESCRIPTION 53.Nm 54is used to control the operation of medium changers, such as those found 55in tape and optical disk jukeboxes. 56.Pp 57The options are as follows: 58.Bl -tag -width indent 59.It Fl f Ar changer 60Use the device 61.Ar changer 62rather than the default device 63.Pa /dev/ch0 . 64.El 65.Pp 66The default changer may be overridden by setting the environment variable 67.Ev CHANGER 68to the desired changer device. 69.Pp 70A medium changer apparatus is made up of 71.Em elements . 72There are five element types: 73.Em picker 74(medium transport), 75.Em slot 76(storage), 77.Em portal 78(import/export), 79.Em drive 80(data transfer), and 81.Em voltag 82(select by volume identifier). The 83.Em voltag 84pseudo-element type allows the selection of tapes by their volume tag 85(typically a barcode on the tape). 86.Pp 87In this command description, the shorthand 88.Em ET 89will be used to represent an element type, and 90.Em EU 91will be used to represent an element unit. 92For example, to represent the first robotic arm in the changer, the 93.Em ET 94would be 95.Dq picker 96and the 97.Em EU 98would be 99.Dq 0 . 100.Pp 101.Sh SUPPORTED COMMANDS 102.Bl -tag -width indent 103.It Ic move Xo 104.Ar <from ET> <from EU> <to ET> <to EU> 105.Op Cm inv 106.Xc 107Move the media unit from 108.Ar <from ET/EU> 109to 110.Ar <to ET/EU> . 111If the optional modifier 112.Cm inv 113is specified, the media unit will be inverted before insertion. 114.It Ic exchange Xo 115.Ar <src ET> <src EU> <dst1 ET> <dst1 EU> 116.Op Ar <dst2 ET> <dst2 ET> 117.Op Cm inv1 118.Op Cm inv2 119.Xc 120Perform a media unit exchange operation. The media unit in 121.Ar <src ET/EU> 122is moved to 123.Ar <dst1 ET/EU> 124and the media unit previously in 125.Ar <dst1 ET/EU> 126is moved to 127.Ar <dst2 ET/EU> . 128In the case of a simple exchange, 129.Ar <dst2 ET/EU> 130is omitted and the values 131.Ar <src ET/EU> 132are used in their place. 133The optional modifiers 134.Cm inv1 135and 136.Cm inv2 137specify whether the media units are to be inverted before insertion into 138.Ar <dst1 ET/EU> 139and 140.Ar <dst2 ET/EU> 141respectively. 142.Pp 143Note that not all medium changers support the 144.Ic exchange 145operation; the changer must have multiple free pickers or emulate 146multiple free pickers with transient storage. 147.It Ic return Xo 148.Ar <from ET> <from EU> 149.Xc 150Return the media unit to its source element. 151This command will query the status of the specified media unit, and 152will move it to the element specified in its source attribute. 153This is a convenient way to return media from a drive or portal 154to its previous element in the changer. 155.Pp 156.It Ic position Xo 157.Ar <to ET> <to EU> 158.Op Cm inv 159.Xc 160Position the picker in front of the element described by 161.Ar <to ET/EU> . 162If the optional modifier 163.Cm inv 164is specified, the media unit will be inverted before insertion. 165.Pp 166Note that not all changers behave as expected when issued this command. 167.It Ic params 168Report the number of slots, drives, pickers, and portals in the changer, 169and which picker unit the changer is currently configured to use. 170.It Ic getpicker 171Report which picker unit the changer is currently configured to use. 172.It Ic setpicker Xo 173.Ar <unit> 174.Xc 175Configure the changer to use picker 176.Ar <unit> . 177.Pp 178.It Ic ielem Xo 179.Op Ar <timeout> 180.Xc 181Perform an 182.Em INITIALIZE ELEMENT STATUS 183operation on the changer. The optional 184.Ar <timeout> 185parameter may be given to specify a timeout in seconds for the 186operations. This may be used if the operation takes unusually long 187because of buggy firmware or the like. 188.It Ic voltag Xo 189.Op Fl fca 190.Ar <ET> 191.Ar <EU> 192.Op Ar <label> 193.Op Ar <serial> 194.Xc 195Change volume tag for an element in the media changer. This command 196is only supported by few media changers. If it is not supported by a 197device, using this command will usually result in a "Invalid Field in 198CDB" error message on the console. 199.Pp 200If the 201.Fl c 202flag is specified, the volume tag of the specified element is 203cleared. If the 204.Fl f 205flag is specified, the volume tag is superseded with the specified 206volume tag even if a volume tag is already defined for the element. 207It is an error to not specify the 208.Fl f 209flag when trying to set a label for an element which already has 210volume tag information defined. 211.Pp 212The command works with the primary volume tag or, if the 213.Fl a 214flag is given, with the alternate volume tag. 215.It Ic status Xo 216.Op Fl vVsSbIa 217.Op Ar <type> 218.Xc 219Report the status of all elements in the changer. If 220.Ar <type> 221is specified, report the status of all elements of type 222.Ar <type> . 223.It Fl v 224Print the primary volume tag for each loaded medium, if any. The volume 225tag is printed as 226.Dq <LABEL:SERIAL> . 227.It Fl V 228Print the alternate volume tag for each loaded medium, if any. 229.It Fl s 230Print the additional sense code and additional sense code qualifier for 231each element. 232.It Fl S 233Print the element source address for each element. 234.It Fl b 235Print SCSI bus information for each element. Note that this information 236is valid only for drives. 237.It Fl I 238Print the internal element addresses for each element. The internal 239element address is not normally used with this driver. It is reported 240for diagnostic purposes only. 241.It Fl a 242Print all additional information (as in 243.Fl vVsSba 244). 245.El 246.Pp 247The status bits are defined as follows: 248.Bl -tag -width indent 249.It FULL 250Element contains a media unit. 251.It IMPEXP 252Media was deposited into element by an outside human operator. 253.It EXCEPT 254Element is in an abnormal state. 255.It ACCESS 256Media in this element is accessible by a picker. 257.It EXENAB 258Element supports passing media (exporting) to an outside human operator. 259.It INENAB 260Element supports receiving media (importing) from an outside human operator. 261.El 262.Pp 263.Sh EXAMPLES 264.Bl -tag -width indent 265.It Li chio move slot 3 drive 0 266Move the media in slot 3 (fourth slot) to drive 0 (first drive). 267.It Li chio move voltag VOLUME01 drive 0 268Move the media with the barcode VOLUME01 to drive 0 (first drive). 269.It Li chio return drive 0 270Remove the tape from drive 0 (first drive) and return it to its original 271location in the rack. 272.It Li chio setpicker 2 273Configure the changer to use picker 2 (third picker) for operations. 274.El 275.Sh FILES 276.Bl -tag -width /dev/ch0 -compact 277.It Pa /dev/ch0 278default changer device 279.El 280.Sh SEE ALSO 281.Xr mt 1 , 282.Xr mount 8 283.Sh AUTHORS 284.An -nosplit 285The 286.Nm 287program and SCSI changer driver were written by 288.An Jason R. Thorpe Aq thorpej@and.com 289for And Communications, 290.Pa http://www.and.com/ . 291.Pp 292Additional work by 293.An Hans Huebner 294.Aq hans@artcom.de 295and 296.An Steve Gunn 297.Aq csg@waterspout.com . 298