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