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