IBM Tape Device Drivers IBM Programming Reference GA32-0566-09 IBM Tape Device Drivers IBM Programming Reference GA32-0566-09 ii IBM Tape Device Drivers: Programming Reference Contents Note! ................ v Close error codes ........... 94 IOCTL error codes ........... 95 Preface .............. vii Chapter 3. HP-UX tape and medium Chapter 1. Common extended features . 1 changer device driver ........ 97 Tape drive functions and device driver ioctls ... 1 HP-UX programming interface ........ 97 Media partitioning ............ 1 IOCTL operations ............ 100 Data safe (append-only) mode ........ 3 General SCSI IOCTL operations ...... 100 Read Position long/extended form and Locate(16) SCSI medium changer IOCTL operations ... 108 commands ............... 3 SCSI tape drive IOCTL operations ..... 118 Logical Block Protection .......... 4 Base operating system tape drive IOCTL Programmable Early Warning (PEW) ...... 4 operations ............. 149 Log Sense page and subpage ......... 5 Service aid IOCTL operations ....... 151 Mode Sense page and subpage ........ 5 Verify Tape ............... 5 Chapter 4. Linux tape and medium RAO - Recommended Access Order ...... 5 changer device driver ........ 159 Software interface ............ 159 Chapter 2. AIX tape and medium Entry points ............. 159 changer device driver ......... 7 Medium changer devices ........ 161 Software interface for tape devices ....... 7 General IOCTL operations ......... 161 Software interface for medium changer devices ... 7 Overview.............. 162 Special files ............... 8 Tape drive IOCTL operations ........ 173 Special files for tape devices ........ 8 Overview.............. 173 Special files for medium changer devices .... 9 Tape drive compatibility IOCTL operations ... 208 Opening the special file for I/O ...... 10 MTIOCTOP ............. 208 The extended open operation ....... 10 MTIOCGET ............. 208 Writing to the special file ......... 12 MTIOCPOS ............. 208 Reading from the special file ....... 12 Medium changer IOCTL operations ...... 209 Reading with the TAPE_SHORT_READ extended SCSI IOCTL commands ......... 209 parameter .............. 12 Return codes ............. 217 Reading with the TAPE_READ_REVERSE General error codes .......... 217 extended parameter .......... 13 Open error codes ........... 217 Closing the special file.......... 13 Close error codes ........... 218 Device and volume information logging ..... 14 Read error codes ........... 218 Log file ............... 14 Write error codes ........... 218 Persistent reservation support and IOCTL IOCTL error codes........... 219 operations ............... 15 ODM attributes and configuring persistent Chapter 5. Solaris tape and medium reserve support ............ 15 changer device driver ........ 221 Default device driver host reservation key ... 16 IOCTL operations ............ 221 Preempting and clearing another host reservation 16 General SCSI IOCTL operations ...... 221 Openx() extended parameters ....... 16 SCSI medium changer IOCTL operations ... 232 AIX tape persistent reserve IOCTLs ..... 17 SCSI tape drive IOCTL operations ..... 242 Atape persistent reserve IOCTLs ...... 20 Base operating system tape drive IOCTL General IOCTL operations ......... 24 operations ............. 278 Overview .............. 24 Downward compatibility tape drive IOCTL Tape IOCTL operations .......... 41 operations ............. 281 Overview .............. 41 Service aid IOCTL operations ....... 287 Medium changer IOCTL operations ...... 81 Return codes ............. 292 Overview .............. 81 General error codes .......... 293 Return codes .............. 92 Open error codes ........... 293 Codes for all operations ......... 92 Close error codes ........... 294 Open error codes ........... 93 Read error codes ........... 294 Write error codes ........... 94 Write error codes ........... 294 Read error codes ........... 94 © Copyright IBM Corp. 1999, 2016 iii IOCTL error codes........... 295 SGI IRIX 3494 Enterprise tape library ..... 343 Opening a special file ......... 295 Solaris 3494 Enterprise tape library driver .... 344 Writing to a special file ......... 296 Opening the library device ........ 344 Reading from a special file ........ 297 Closing the library device ........ 344 Closing a special file .......... 298 Issuing the library commands ....... 344 Issuing IOCTL operations to a special file ... 299 Building and linking applications with the library subroutines .......... 345 Chapter 6. Windows tape device Windows 3494 Enterprise tape library service .. 345 drivers .............. 301 Opening the library device ........ 345 Closing the library device ........ 346 Windows programming interface ....... 301 Issuing the library commands ....... 346 User-callable entry points ........ 301 Building and linking applications with the Tape Media Changer driver entry points ... 302 library subroutines .......... 346 Medium Changer IOCTLs ........ 310 3494 Enterprise tape library system calls .... 348 | Preempt reservation .......... 311 Library device number ......... 349 Vendor-specific (IBM) device IOCTLs for MTIOCLM (Library Mount) ....... 349 DeviceIoControl ........... 313 MTIOCLDM (Library Demount) ...... 351 Variable and fixed block read/write processing 331 MTIOCLQ (Library Query) ........ 353 Event log............... 332 MTIOCLSVC (Library Set Volume Category) 358 MTIOCLQMID (Library Query Message ID) .. 360 Chapter 7. 3494 Enterprise tape library MTIOCLA (Library Audit) ........ 361 driver ............... 339 MTIOCLC (Library Cancel)........ 362 AIX 3494 Enterprise tape library driver..... 339 MTIOCLSDC (Library Set Device Category) .. 363 Opening the Special File for I/O ...... 339 MTIOCLRC (Library Release Category).... 365 Header definitions and structure ...... 339 MTIOCLRSC (Library Reserve Category) ... 366 Parameters ............. 339 MTIOCLSCA (Library Set Category Attribute) 368 Reading and writing the Special File .... 339 MTIOCLDEVINFO (Device List) ...... 369 Closing the Special File ......... 339 MTIOCLDEVLIST (Expanded Device List)... 369 HP-UX 3494 Enterprise tape library driver.... 340 MTIOCLADDR (Library Address Information) 371 Opening the library device ........ 340 MTIOCLEW (Library Event Wait) ..... 373 Closing the library device ........ 340 Error description for the library I/O control Issuing the library commands ....... 340 requests .............. 376 Building and linking applications with the library subroutines .......... 341 Notices .............. 379 Linux 3494 Enterprise tape library driver .... 341 Opening the library device ........ 342 Index ............... 381 Closing the library device ........ 342 Issuing the library commands ....... 342 Building and linking applications with the library subroutines .......... 343 iv IBM Tape Device Drivers: Programming Reference Note! Before using this information and the product that it supports, be sure to read the general information under “Notices” on page 379. Ninth Edition (March 2016) This edition replaces and makes obsolete GC35-0483-06, GC35-0346-10, GA32-0566-00, GA32-0566-01, GA32-0566-02, GA32-0566-03, GA32-0566-04, GA32-0566-05, GA32-0566-06, GA32-0566-07, and GA32-0566-08. Changes or additions are indicated by a vertical line in the left margin. © Copyright IBM Corp. 1999, 2016 v vi IBM Tape Device Drivers: Programming Reference Preface These publications and URLs provide user information and installation assistance for IBM® tape drive, medium changer, and library device drivers. Special printing instructions This Device Driver manual contains different sections for each type of operating platform, for example, AIX, HP-UX, Linux, Oracle Solaris, and Windows. The manual also contains a separate section on these operating systems for the 3494 Enterprise tape library. Note: When the page range is selected for the section you want to print, the print page range is based on the page controls for Adobe Acrobat, not the page that is printed on the actual document. Enter the Adobe page numbers to print. If you want to print one or more separate sections of the manual, follow these steps. 1. Go to the beginning of the section and note the page number. 2. Go to the last page in the section and note that page number. 3. Select File > Print, then choose Pages and enter the page range for the section. Only the page range that is entered prints. 4. Repeat these steps to print extra sections. Importantprinternote Thisareaindicatesthe Ignore thepagenumber pagesthatwillactually appearingonthepageitself printinyourspecified whenenteringpageranges rangeofpages. foryourprinter. Figure 1. How to print Adobe pdf files Attention: Only one Table of Contents and one Index is available for this entire book. If you want to print those items, you must repeat the process, by entering the page range of the Table of Contents and the Index page range. © Copyright IBM Corp. 1999, 2016 vii Related information Reference material, including the Adobe pdf version of this publication, is available at http://www-01.ibm.com/support/docview.wss?uid=ssg1S7003032. A companion publication that covers installation and user aspects for the device drivers is IBM Tape Device Drivers: Installation and Users Guide, GC27-2130-00, at http://www-01.ibm.com/support/docview.wss?uid=ssg1S7002972. AIX The following URL points to information about IBM System p (also known as pSeries) servers: http://www-1.ibm.com/servers/eserver/pseries. HP-UX The following URL relates to HP HP-UX systems: http://www.hp.com. Linux The following URLs