Vous êtes sur la page 1sur 361

IBM Tape Device Drivers



Installation and Users Guide

GC27-2130-20

IBM Tape Device Drivers



Installation and Users Guide

GC27-2130-20

Note!
Before this information and the product that it supports is used, be sure to read the general information under Notices.

Twenty-first Edition (November 2014)


This twenty-first edition of the IBM Tape Device Drivers Installation and Users Guide, GC27-2130-20, replaces and
makes obsolete the following manual: IBM Tape Device Drivers Installation and Users Guide, GC27-2130-19.
Copyright IBM Corporation 2007, 2014.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Read this first


Accessing online technical support
For online technical support for your Library, visit:
http://www.ibm.com/support/.

Registering for My Notification


My Notification registration provides email notification when firmware levels have
been updated and are available for download and installation. To register for My
Notification:
1. Visit the web at http://www-01.ibm.com/software/support/einfo.html.
2. Click My Notifications.
Note: Library firmware and tape drive firmware are verified and released
together. When updating to the latest firmware, verify that all installed
components such as tape drives, and library are at the latest levels noted
on the Support website. Mixing different levels of library and tape drive
firmware is not supported and can cause unpredictable results.

Contacting IBM technical support


In the USA: Call 1-800-IBM_SERV (1-800-426-7378).
All other Countries/Regions: Visit http://www.ibm.com.
To open a Service Request online: Under Support & downloads, click Open a
service request.

Copyright IBM Corp. 2007, 2014

iii

iv

IBM Tape Device Drivers Installation and Users Guide

Contents
Read this first . . . . . . . . . . . . iii
Accessing online technical support.
Registering for My Notification . .
Contacting IBM technical support .

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

. iii
. iii
. iii

Figures . . . . . . . . . . . . . . . ix
Tables . . . . . . . . . . . . . . . xi
Preface . . . . . . . . . . . . . . xiii
Related information . . . . . . . . . . . xiii
IBM tape products . . . . . . . . . . . xiii
Additional information . . . . . . . . . xv
Sending your comments . . . . . . . . . . xv
Special printing instructions . . . . . . . . xvi

Introduction . . . . . . . . . . . . xvii
Chapter 1. Common extended features . 1
Path failover and load balancing. . . . . . .
Automatic failover . . . . . . . . . .
Dynamic load balancing . . . . . . . .
Dynamic Runtime Attributes . . . . . . . .
Supported devices and feature codes . . . . .
Data encryption . . . . . . . . . . . .
Tape and library requirements . . . . . .
Planning for application-managed tape
encryption . . . . . . . . . . . . .
Planning for system-managed tape encryption.
Planning for library-managed tape encryption .
Encryption feature codes . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.

1
1
5
6
6
7
7

10
10
13
14

Chapter 2. AIX Tape and Medium


Changer device driver . . . . . . . . 15
Product requirements . . . . . . . . . .
Installation and configuration instructions . . .
Installation procedure . . . . . . . . .
Configuring Tape and Medium Changer devices
Configuring limitations . . . . . . . .
Deconfiguring tape devices . . . . . . .
Deconfiguring Medium Changer devices . .
Uninstalling . . . . . . . . . . . .
Tape drive, media, and device driver parameters .
Configuration parameters. . . . . . . .
Media parameters . . . . . . . . . .
Special files . . . . . . . . . . . . .
Special files for tape devices . . . . . . .
Special files for Medium Changer devices . .
Persistent Naming Support . . . . . . . .
Changing the logical name after initial boot .
Control Path failover support for tape libraries .
Configuring and unconfiguring path failover
support. . . . . . . . . . . . . .
Primary and alternative paths . . . . . .
Copyright IBM Corp. 2007, 2014

. 15
. 15
. 16
17
. 17
. 18
. 18
. 18
. 19
. 19
. 25
. 26
. 26
. 27
. 28
. 29
. 30
. 30
. 30

Querying primary and alternative path


configurations . . . . . . . . . . .
Configuring and unconfiguring primary and
alternative devices . . . . . . . . . .
Data Path failover and load balancing support for
tape drives . . . . . . . . . . . . .
Installing Data Path failover license key . . .
Configuring and unconfiguring path failover
support. . . . . . . . . . . . . .
Primary and alternative paths . . . . . .
Querying primary and alternative path
configuration . . . . . . . . . . . .
Configuring and unconfiguring primary and
alternative devices . . . . . . . . . .
System-managed encryption . . . . . . . .
Device driver configuration . . . . . . .
Querying tape drive configuration. . . . .
Testing data encryption configuration and
connectivity . . . . . . . . . . . .
Error logging . . . . . . . . . . . .
Field support information . . . . . . .
Problem determination . . . . . . . . .
Dump support . . . . . . . . . . .
Device and volume information logging . . .
Log file . . . . . . . . . . . . . .
Tape log utility . . . . . . . . . . .
Reservation conflict logging . . . . . . .
Error logging . . . . . . . . . . . .
Error log templates . . . . . . . . . .
Automatic dump facility . . . . . . . .
Dynamic Runtime Attributes . . . . . .
Trace facility . . . . . . . . . . . .
Atape System Trace (ATRC) utility . . . .
Component tracing . . . . . . . . . .
Atape Component Trace (ACTRC) utility . .
Tape drive service aids . . . . . . . . .
Tape drive service aids details . . . . . .
Performance considerations . . . . . . . .
Data path . . . . . . . . . . . . .
Common AIX utilities . . . . . . . . .
AIX iostat utility for tape performance . . .
Before Support is called . . . . . . . .

. 31
. 31
. 32
. 32
. 32
. 33
. 33
.
.
.
.

34
34
34
35

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

35
35
35
35
35
36
37
37
37
38
38
40
40
41
41
41
42
42
42
45
45
45
46
46

Chapter 3. HP-UX Tape and Medium


Changer device driver . . . . . . . . 47
Product requirements . . . . . . .
ATDD implementation . . . . .
Hardware requirements . . . . .
Software requirements . . . . . .
Software interface to the device driver
Installation and configuration instructions
Configuration limitations . . . . .
Installing and configuring PCI drivers
Supported configuration parameters . .
Configuration parameter definitions .

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

47
47
48
48
48
49
49
49
57
58

Special files . . . . . . . . . . . . .
Persistent Naming Support . . . . . . . .
Control Path failover support for tape libraries .
Configuring and unconfiguring path failover
support. . . . . . . . . . . . . .
Primary and alternative paths . . . . . .
Querying primary and alternative path
configurations . . . . . . . . . . .
Disabling and enabling primary and alternative
paths . . . . . . . . . . . . . .
Data Path failover and load balancing support for
tape drives . . . . . . . . . . . . .
Configuring and unconfiguring path failover
support. . . . . . . . . . . . . .
Primary and alternative paths . . . . . .
Querying primary and alternative path
configuration . . . . . . . . . . . .
Disabling and enabling primary and alternative
paths . . . . . . . . . . . . . .
Problem determination . . . . . . . . .
Error logging . . . . . . . . . . . .
Sense data logging . . . . . . . . . .
Support_info script . . . . . . . . . .
Tracing facility . . . . . . . . . . .
Problems and solutions . . . . . . . .

. 61
. 63
. 63
. 63
. 64
. 65
. 65
. 65
. 66
. 67
. 67
.
.
.
.
.
.
.

68
68
68
68
68
69
70

Chapter 4. Linux Tape and Medium


Changer device driver . . . . . . . . 73
Product requirements . . . . . . . . . .
Installation and Configuration instructions . . .
Conventions used . . . . . . . . . .
Configuration limitations . . . . . . . .
Components created during installation . . .
Installation procedure . . . . . . . . .
Updating procedure . . . . . . . . .
Querying the installed package . . . . . .
Configuring Tape and Medium Changer devices
on Intel-compatible systems . . . . . . .
Configuring Tape and Medium Changer devices
on IBM System p models . . . . . . . .
Configuring Tape and Medium Changer devices
on IBM System z models . . . . . . . .
Uninstallation procedure . . . . . . . .
Tape drive, media, and device driver parameters .
Configuration parameters. . . . . . . .
Nonchangeable parameters . . . . . . .
Changeable parameters . . . . . . . .
Special files . . . . . . . . . . . . .
Special files for the tape device . . . . . .
Special files for the Medium Changer device .
Persistent Naming Support . . . . . . .
Control Path failover support for tape libraries .
Configuring and unconfiguring path failover
support. . . . . . . . . . . . . .
Primary and alternative paths . . . . . .
Querying primary and alternative path
configuration . . . . . . . . . . . .
Disabling and enabling primary and alternative
paths . . . . . . . . . . . . . .
Data Path failover and load balancing support for
tape drives . . . . . . . . . . . . .

vi

.
.
.
.
.
.
.
.

73
73
74
74
74
75
76
76

. 76
. 77
.
.
.
.
.
.
.
.
.
.
.

77
79
79
79
80
82
85
85
86
86
88

. 88
. 89
. 89
. 90
. 90

IBM Tape Device Drivers Installation and Users Guide

Primary and alternative paths . . . . . . . 91


Querying primary and alternative path
configuration . . . . . . . . . . . . . 92
Disabling and enabling primary and alternative
paths . . . . . . . . . . . . . . . 92
Tape Reserve Type . . . . . . . . . . . 92
Open source device driver - lin_tape . . . . . . 92
Comparing IBMtape and lin_tape . . . . . . 93
Installation . . . . . . . . . . . . . 93
Driver parameters and special device files . . . 93
Taking devices offline and completing
maintenance . . . . . . . . . . . . . 94
Path failover support . . . . . . . . . . 94
lin_taped daemon . . . . . . . . . . . 94
System-managed encryption . . . . . . . . . 94
Configuring device drivers . . . . . . . . 94
Querying tape drive configuration. . . . . . 96
Problem determination . . . . . . . . . . 96
Tracing driver modules . . . . . . . . . 96
Configuring and running the lin_taped daemon 96
Reservation conflict logging . . . . . . . 101

Chapter 5. Solaris Tape and Medium


Changer Device Driver . . . . . . . 103
Product requirements. . . . . . . . . . .
Installation and configuration instructions . . . .
Preventing conflicts with other device drivers
Preinstallation considerations . . . . . . .
Installing and updating IBMtape . . . . . .
Configuring IBM tape devices with Fibre
Channel and SAS HBAs . . . . . . . . .
Configuring limitations . . . . . . . . .
Solaris Zones support . . . . . . . . .
Configuration parameters . . . . . . . .
Dynamic Runtime Attributes . . . . . . .
Removing IBMtape . . . . . . . . . .
Adding or removing devices . . . . . . .
Unconfiguring tape devices. . . . . . . .
Tapelist Utility Program . . . . . . . . .
Special files . . . . . . . . . . . . . .
Device behaviors . . . . . . . . . . .
File naming conventions. . . . . . . . .
Persistent Naming Support . . . . . . . . .
Control Path failover support for libraries . . . .
Configuring and deconfiguring Path Failover
support . . . . . . . . . . . . . .
Primary and alternative paths . . . . . . .
Querying primary and alternative path
configuration . . . . . . . . . . . .
Disabling and enabling primary and alternative
paths . . . . . . . . . . . . . . .
Data Path failover and load balancing support for
tape drives . . . . . . . . . . . . . .
Configuring and deconfiguring Path Failover
support . . . . . . . . . . . . . .
Primary and alternative paths . . . . . . .
Querying primary and alternative path
configuration . . . . . . . . . . . .
Disabling and enabling primary and alternative
paths . . . . . . . . . . . . . . .
System-managed encryption . . . . . . . .

103
104
104
105
105
111
116
116
119
123
124
124
125
125
127
128
128
129
131
131
131
132
132
132
132
134
134
135
135

Device driver configuration . . . . .


Querying tape drive configuration . . .
Testing data encryption configuration and
connectivity . . . . . . . . . . .
Field support information . . . . . .
Problem determination . . . . . . . .
Functional verification . . . . . . .
Sense data logging . . . . . . . .
Installation problems . . . . . . . .
Tape monitor daemon (tmd) . . . . .
Tracing facility . . . . . . . . . .
Dynamic tracing utility . . . . . . .
Setting the IBM_trace level for static tracing
Running the diags_info script . . . . .
iostat command . . . . . . . . .
Reservation conflict logging . . . . .

.
.

. 135
. 136

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

136
136
137
137
137
138
138
139
141
141
142
142
142

Chapter 6. Windows Tape and Medium


Changer device driver . . . . . . . 145

Product requirements. . . . . . . . . .
Installation and configuration instructions . . .
Windows Server 2003, Windows Server 2008,
and Windows Server 2012 instructions . . .
Configuring limitations . . . . . . . .
Persistent Naming Support on Windows Server
2003, Windows Server 2008, and Windows Server
2012 . . . . . . . . . . . . . . .
Control Path failover support for tape libraries .
Configuring and unconfiguring Control Path
failover support . . . . . . . . . .
Querying primary and alternative path
configuration . . . . . . . . . . .
Checking disablement of Control Path failover
setting . . . . . . . . . . . . . .
Data Path failover support for tape drives . . .
Configuring and unconfiguring Data Path
failover support . . . . . . . . . .
Reserve Type if DPF is disabled . . . . .
Querying primary and alternative path
configuration . . . . . . . . . . .
Checking disablement of Data Path failover
setting . . . . . . . . . . . . . .
System-managed encryption . . . . . . .
Device driver configuration . . . . . .
Configuration file . . . . . . . . . .
Querying tape drive configuration settings .
Problem determination . . . . . . . . .
Windows Server 2003 instructions . . . .
Reservation conflict logging . . . . . .
Max retry busy . . . . . . . . . . .

. 145
. 145
. 146
. 150

. 150
. 151
. 151
. 151
. 151
. 152
. 152
. 152
. 152
.
.
.
.
.
.
.
.
.

152
153
153
154
154
154
155
156
157

Chapter 7. 3494 Enterprise Tape


Library support . . . . . . . . . . 159
MTLIB program . . . . . . . . . .
Syntax and examples . . . . . . . .
MTEVENT program . . . . . . . . .
Library driver information . . . . . . .
Software interface . . . . . . . . .
Library Manager event notification . . .
Synchronous and asynchronous operations

.
.
.
.
.
.
.

.
.
.
.
.
.
.

159
159
169
170
170
170
170

Operation Complete notification . . . . .


Unsolicited notification . . . . . . . .
Driver message queue . . . . . . . .
Volume categories . . . . . . . . . .
IBM Virtual Tape Server subsystem attachment
3494 Library emulation . . . . . . . . .
Overview. . . . . . . . . . . . .
3494 Emulation design . . . . . . . .
3494 API Emulation and MTLIB program . .
SMC library names . . . . . . . . .
Volume categories . . . . . . . . . .
Asynchronous library operations . . . . .
Performance considerations. . . . . . .
AIX . . . . . . . . . . . . . . .
Data flow . . . . . . . . . . . .
Product requirements. . . . . . . . .
Installation instructions . . . . . . . .
Special files . . . . . . . . . . . .
3494 Enterprise tape library attachment test .
Problem determination . . . . . . . .
HP-UX . . . . . . . . . . . . . .
Data flow . . . . . . . . . . . .
Product requirements. . . . . . . . .
Installation instructions . . . . . . . .
3494 Enterprise tape library attachment test .
Problem determination . . . . . . . .
Linux . . . . . . . . . . . . . . .
Data flow . . . . . . . . . . . .
Product requirements. . . . . . . . .
Installation instructions . . . . . . . .
3494 Enterprise tape library attachment test .
Problem determination . . . . . . . .
Solaris . . . . . . . . . . . . . . .
Data flow . . . . . . . . . . . .
Product requirements. . . . . . . . .
Installation instructions . . . . . . . .
3494 Enterprise tape library attachment test .
Problem determination . . . . . . . .
Windows . . . . . . . . . . . . . .
Data flow . . . . . . . . . . . .
Product requirements. . . . . . . . .
Installation instructions . . . . . . . .
3494 Enterprise tape library attachment test .
Problem determination . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

170
171
171
171
172
173
173
173
174
174
174
175
175
176
176
177
177
183
183
184
185
185
186
187
191
191
191
192
192
193
196
196
197
197
198
199
202
202
203
203
204
205
209
209

Chapter 8. IBM Tape Diagnostic Tool


(ITDT) . . . . . . . . . . . . . . . 211
Purpose . . . . . . . . . . . . . . .
Accessing ITDT . . . . . . . . . . . .
Supported systems . . . . . . . . . . .
Standard Edition (ITDT-SE). . . . . . . .
Graphical Edition (ITDT-GE) . . . . . . .
Supported equipment . . . . . . . . . .
IBM Tape Diagnostic Tool - Standard Edition . . .
Installing ITDT - Standard Edition . . . . .
Starting ITDT - Standard Edition . . . . . .
Standard Edition - known issues and limitations
Standard Edition - Start menu commands . . .
Standard Edition - Scan menu commands . . .
Standard Edition - Tapeutil menu commands
Standard Edition - Program options . . . . .
Contents

211
212
212
213
213
214
215
215
219
222
225
226
245
257

vii

Standard Edition - Tapeutil scripting commands


IBM Tape Diagnostic Tool - Graphical Edition . .
Installing ITDT - Graphical Edition . . . . .
Graphical Edition - known issues and
limitations . . . . . . . . . . . . .
ITDT-GE user interface description . . . . .
Graphical Edition - Scan menu commands . .
Graphical Edition - visualizing log files. . . .
Graphical Edition - Tapeutil menu commands

257
285
285
285
287
290
303
304

Appendix A. Accessing
documentation and software online . . 321
Appendix B. Verifying correct
attachment of your devices . . . . . 325
Appendix C. Managing the microcode
on the IBM tape drive . . . . . . . . 327
Notices . . . . . . . . . . . . . . 329
Index . . . . . . . . . . . . . . . 331

viii

IBM Tape Device Drivers Installation and Users Guide

Figures
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.

Current attachment array . . . . . . . xviii


Dual HBA and multi-port drives . . . . . . 2
Dual HBA and single-port drive . . . . . . 3
Single HBA and multi-port drive . . . . . . 4
Dual HBA and multi-port drives . . . . . . 4
Single HBA and multi-port drives . . . . . 5
Sample configuration file . . . . . . . . 12
Data flow for AIX Device Driver (Atape)
15
Data path for AIX device driver (Atape)
45
Data flow for HP-UX device driver (ATDD)
47
Data flow for Linux device driver (lin_tape)
73
Data flow for Solaris Device Driver (IBMtape) 103
Data flow for Windows device driver
(IBMmag) . . . . . . . . . . . . . 145
Installation application in Windows Explorer 147
Windows logo testing screen . . . . . . 149
Checked folder . . . . . . . . . . . 155
Syntax diagram for mtlib program . . . . 160
3494/SMC library data flow . . . . . . . 173
LIBSMC and OS components . . . . . . 174
Data flow for AIX 3494 Enterprise Tape
Library Driver . . . . . . . . . . . 176
Data flow for HP-UX 3494 Enterprise tape
library driver . . . . . . . . . . . 186
Data flow for Linux 3494 Enterprise tape
library driver . . . . . . . . . . . 192
Data flow for Solaris 3494 Enterprise tape
library driver . . . . . . . . . . . 198
Data flow for Windows 3494 Enterprise tape
library driver . . . . . . . . . . . 204
Welcome/Startup screen . . . . . . . . 216
License screen . . . . . . . . . . . 216
Machine credentials screen . . . . . . . 217
Installation progress screen . . . . . . . 217
Installation complete screen . . . . . . . 218
Start screen menu . . . . . . . . . . 226
Scan menu . . . . . . . . . . . . 227

Copyright IBM Corp. 2007, 2014

32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.

More scan options . . . . . . . .


Device List screen . . . . . . . .
Data Delete question . . . . . . .
Test running . . . . . . . . . .
Test results . . . . . . . . . .
Dump . . . . . . . . . . . .
Firmware Update screen . . . . . .
Scrollable Data screen . . . . . . .
Encryption Start screen . . . . . .
Full Write results . . . . . . . .
Tape Usage screen . . . . . . . .
System Test results . . . . . . . .
TCP/IP screen: Read data . . . . .
TCP/IP Port command . . . . . .
TCP/IP Port command results . . . .
Graphical Edition user interface . . .
Graphical Edition preferences . . . .
Graphical Edition interface . . . . .
Scan . . . . . . . . . . . .
Test . . . . . . . . . . . . .
Test results . . . . . . . . . .
Configure TCP/IP Ports . . . . . .
Dump results . . . . . . . . .
Check for Device Updates - FixCentral
components . . . . . . . . . .
Check for Device Updates - code level
Overwrite data?. . . . . . . . .
Transfer size . . . . . . . . . .
Tape Usage . . . . . . . . . .
System Test . . . . . . . . . .
Copy Services . . . . . . . . .
Graphic Edition: log view . . . . .
Tapeutil Control Center . . . . . .
Tapeutil scan results . . . . . . .
Generic tapeutil scan . . . . . . .
Configure TCP/IP Ports command in the
Graphical Edition . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

227
228
230
231
232
233
234
235
237
239
240
241
244
253
253
287
288
289
290
291
292
293
294

.
.
.
.
.
.
.
.
.
.

. 295
296
. 297
. 298
. 299
. 300
. 303
. 304
. 305
. 306
. 307

. 318

ix

IBM Tape Device Drivers Installation and Users Guide

Tables
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.

Supported devices and feature codes . . . . 7


Interoperability between IPv4 and IPv6 clients
and servers . . . . . . . . . . . . 12
Feature codes (encryption) . . . . . . . 14
Special files for tape devices . . . . . . . 26
Special files for Medium Changer devices
28
Error description . . . . . . . . . . . 46
HP-UX: Device-specific parameter definitions 58
HP-UX: Driver-specific parameters (Global)
59
Special files . . . . . . . . . . . . 61
New special files in HP-UX 11i v3 . . . . . 62
Trace flags . . . . . . . . . . . . . 69
Problems, reasons, and solutions . . . . . 70
Troubleshooting (problems and solutions)
71
Linux: Components created during lin_tape
installation . . . . . . . . . . . . . 74
Linux: Special files for IBM tape devices
86
Attached changer devices . . . . . . . . 89
Attached tape devices . . . . . . . . . 91
Comparing IBMtape and lin_tape . . . . . 93
Solaris: IBMtape components . . . . . . 104
Solaris: IBMtape install or update . . . . . 106
Solaris Device Driver - IBMtape - equipment
listing example 1 . . . . . . . . . . 106
Solaris Device Driver - IBMtape - equipment
listing example 2 . . . . . . . . . . 109
Solaris Device Driver - IBMtape - equipment
listing example 3 . . . . . . . . . . 110
Solaris Device Driver - IBMtape - equipment
listing example 4 . . . . . . . . . . 110
Solaris: configuration parameters recognized
by IBMtape . . . . . . . . . . . . 122
IBM SCSI Tape/Medium Changer special files
for Solaris. . . . . . . . . . . . . 129

Copyright IBM Corp. 2007, 2014

27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.

Solaris: Example of Control Path failover


support command output . . . . .
Example of Data Path failover support
command output . . . . . . . .
Solaris: tracing facility . . . . . .
Device query. . . . . . . . . .
Volume query . . . . . . . . .
Expanded volume query . . . . . .
Expanded volume data with usage . .
Inventory count data . . . . . . .
Tape library device number . . . . .
Expanded tape library device list . . .
Library data . . . . . . . . . .
Statistical data . . . . . . . . .
Inventory query. . . . . . . . .
Category inventory query . . . . .
Reserve category command . . . . .
Reserve category list . . . . . . .
Category attribute list . . . . . . .
Library address information . . . .
SMIT main menu . . . . . . . .
SMIT devices menu . . . . . . .
SMIT tape drive menu . . . . . .
SMIT tape drive type menu . . . . .
Add an LMCP Logical Device menu . .
LMCP COMMAND STATUS window
Configure an LMCP selection list . . .
Configure a Defined LMCP COMMAND
STATUS window . . . . . . . .
Abort code definitions . . . . . .
Codes and root causes . . . . . .
Device addressing . . . . . . . .
Supported platforms . . . . . . .
Driver descriptions . . . . . . .

. 132

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

134
139
162
163
163
163
163
164
164
165
166
167
168
168
169
169
169
180
180
181
181
181
182
. 182

.
.
.
.
.
.

.
.
.
.
.
.

182
237
245
247
272
322

xi

xii

IBM Tape Device Drivers Installation and Users Guide

Preface
These publications and URLs provide user information and installation assistance
for IBM tape drive, medium changer, and library device drivers.

Related information
Reference material, including the Adobe PDF version of this publication, is
available at the following url: http://www-01.ibm.com/support/
docview.wss?uid=ssg1S7002972
A companion publication that covers programming aspects for the device drivers
is:
IBM Tape Device Drivers: Programming Reference, GA32-0566.

IBM tape products


IBM tape product publications
|
|

v IBM TS1120, TS1130, TS1140, and TS1150 Tape Drives and TS1120 Controller
Introduction and Planning Guide, GA32-0555
v IBM TS1120 Tape Drive and Controller Operator Guide, GA32-0556
v IBM TS3500 Tape Library Operator Guide, GA32-0560
v IBM TS3500 Tape Library Introduction and Planning Guide, GA32-0559

v
v
v
v
v
v
v
v
v
v
v
v

IBM TS4500 Tape Library Introduction and Planning Guide, SC27-5990


IBM 3953 Library Manager Model L05 Operator Guide, GA32-0558
IBM 3953 Tape System Introduction and Planning Guide, GA32-0557
IBM Tape Drive 3592 SCSI Reference, GA32-0570
IBM Introduction and Planning Guide 3592 Models J1A, E05, E06, EU6, E07, E08,
and J70, C06, C07 Controllers, GA32-0555
IBM Operator Guide 3592 Models J1A, E05, E06, EU6, E07, E08, J70 and C06,
GA32-0556
IBM LTO Ultrium 3-H Tape Drive Setup, Operator, and Service Guide, SC23-5231
IBM TS2230 Tape Drive Setup, Operator, and Service Guide, GC27-2099
IBM TS2230 Tape Drive Installation Quick Reference, GC27-2100
IBM TS2240 Tape Drive Setup, Operator, and Service Guide, GC27-2151
IBM TS2240 Tape Drive Installation Quick Reference, GC27-2167
IBM TS2250 Tape Drive Setup, Operator, and Service Guide, GC27-2275

v IBM TS2250 Tape Drive Installation Quick Reference, GC27-2276


v IBM TS2260 Tape Drive Setup, Operator, and Service Guide, GC27-2226
v IBM TS2260 Tape Drive Installation Quick Reference, GC27-2276
v IBM 3580 Tape Drive Models L33/L3H Setup, Operator, and Service Guide, GC26-7708
v IBM 3580 Tape Drive Models L33/L3H Quick Reference, GC26-7709
v IBM TS2340 Tape Drive Models L43/S43 Setup, Operator, and Service Guide,
GC27-2103
v IBM TS2340 Tape Drive Models L43/S43 Quick Reference Card, GC27-2104
v IBM TS2350 Tape Drive Setup, Operator, and Service Guide, GC27-2277
Copyright IBM Corp. 2007, 2014

xiii

v
v
v
v
v

IBM
IBM
IBM
IBM
IBM

TS2350
TS2360
TS2360
TS3500
TS3500

Tape
Tape
Tape
Tape
Tape

Drive Installation Quick Reference, GC27-2278


Drive Setup, Operator, and Service Guide, GC27-2228
Drive Installation Quick Reference, GC27-2278
Library Planning and Operator Guide, GA32-0408
Library Maintenance Information, 19P2440

v IBM TS3500 Tape Library


v IBM TS3500 Tape Library
v IBM TS3500 Tape Library
GA32-0589
v IBM TS3310 Tape Library
v IBM TS3310 Tape Library
v IBM TS3310 Tape Library
v IBM TS3100 Tape Library
Guide, GA32-0545
v IBM TS3100 Tape Library
GA32-0548

with ALMS: Introduction and Planning Guide, GA32-0593


with ALMS: Operator's Guide, GA32-0594
with ALMS: Tape System Reporter User's Guide,
Setup and Operator Guide, GA32-0477
Maintenance Information, GA32-0478
SCSI Reference, GA32-0476
and TS3200 Tape Library Setup, Operator, and Service
and TS3200 Tape Library Installation Quick Reference,

v IBM TS3100 Tape Library and TS3200 Tape Library SCSI Reference, GA32-0547
To access the latest documentation for your product, go to the IBM Publications
Center at http://www-05.ibm.com/e-business/linkweb/publications/servlet/
pbi.wss. Select your country, then click Search for publications to find the desired
publication. Publications can be viewed and downloaded from the website.
.

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 relate to Linux distributions:
http://www.redhat.com
http://www.suse.com

Solaris
The following URL relates to Oracle Solaris systems:
http://www.oracle.com/us/sun/index.html

Microsoft Windows
The following URL relates to Microsoft Windows systems:
http://www.microsoft.com

xiv

IBM Tape Device Drivers Installation and Users Guide

Additional information
The following publication contains additional information related to the IBM tape
drive, medium changer, and library device drivers:
v American National Standards Institute Small Computer System Interface
X3T9.2/86-109 X3.180, X3B5/91-173C, X3B5/91-305, X3.131-199X Revision 10H,
and X3T9.9/91-11 Revision 1

Sending your comments


Your feedback is important in helping us provide the most accurate and best
quality information. If you have comments or suggestions for improving this
publication, you can send us comments electronically by using these addresses:
v E-mail
Submit your comments electronically to the following e-mail address:
starpubs@us.ibm.com

Be sure to include the name and order number of the book and, if applicable,
the specific location of the text you are commenting on, such as a page number
or table number.
v Mail
Fill out the Readers' Comments form (RCF) at the back of this book. Return it by
mail or give it to an IBM representative. If the RCF is removed, you can address
your comments to:
International Business Machines Corporation
RCF Processing Department GZW
9032 South Rita Road
Tucson, AZ 85775-4401

Preface

xv

Special printing instructions


This Tape Device Drivers Installation and User's Guide contains sections for each
type of operating system/platform; for example, AIX, HP-UX, Linux, Oracle
Solaris, Windows; and 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, note that
the print page range is based on the page controls for Adobe Acrobat, not
the page printed on the actual document. Enter the Adobe page numbers to
print.

Important printer note

This area indicates the


pages that will actually
print in your specified
range of pages.

Ignore the page number


appearing on the page itself
when entering page ranges
for your printer.

If you want to print one or more separate sections of the manual, follow these
steps:
1. Navigate to the beginning of the section and note the page number.
2. Navigate 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 entered prints.
4. Repeat these steps to print additional sections.
Attention: Only one Table of Contents and one Index exists for this entire book.
If you want to print those items, you must repeat the previous process, entering
the page range for the Table of Contents and the Index page range, respectively.

xvi

IBM Tape Device Drivers Installation and Users Guide

Introduction
This publication describes the IBM Tape and Medium Changer Device Drivers and
IBM Tape Diagnostic Tool (ITDT) for various operating systems. Not all devices are
supported by all operating systems, drivers, or ITDT. Refer to the Hardware
requirements section for details.

Purpose
The IBM tape and medium changer device drivers are designed specifically to take
advantage of the features that are provided by the IBM tape drives and medium
changer devices. The goal is to give applications access to the functions required
for basic tape functions (such as backup and restore) and medium changer
operations (such as cartridge mount and unmount), and to the advanced functions
needed by full tape management systems. Whenever possible, the driver is
designed to take advantage of the device features transparent to the application.
The most current information on hardware and software requirements for IBM
tape and medium changer device drivers can be found in the individual platform
readme files or with the subsequent links.

Hardware requirements
The tape drivers are developed to support various versions of different platforms.
For the latest support, refer to the Interoperation Center website http://www.ibm.com/systems/support/storage/config/ssic/.
Note: A single Fibre Channel host bus adapter (HBA) for concurrent tape and disk
operations is not recommended. Tape and disk devices require incompatible
HBA settings for reliable operation and optimal performance characteristics.
Under stress conditions (high I/O rates for either tape, disk, or both) where
disk and tape subsystems share a common HBA, stability problems are
observed. These issues are resolved by separating disk and tape I/O streams
onto separate HBAs and by using SAN zoning to minimize contention. IBM
is focused on assuring server/storage configuration interoperability. It is
strongly recommended that your overall implementation plan includes
provisions for separating disk and tape workloads.
For information about this issue, see the following Redbook, section 4.1.3 in
http://www.redbooks.ibm.com/abstracts/sg246502.html?Open.

Software requirements
If you use a third-party application, consult with your application provider about
the compatibility with IBM tape device drivers. http://www-03.ibm.com/systems/
resources/lto_isv_matrix1.pdf
For detailed driver requirements for each operating system, refer to the appropriate
chapter. To obtain the most current service and documentation for this software,
refer to Appendix A, Accessing documentation and software online, on page 321.

Copyright IBM Corp. 2007, 2014

xvii

IBM tape products


The IBM tape product family provides an excellent solution for customers with
small to large storage and performance requirements.
1. IBM Virtualization Engine TS7520
2. IBM Virtualization Engine TS7650
3. IBM TS2230/TS2240/TS2250/TS2260 tape drive
4. IBM TS2340/TS2350/TS2360 tape drive
5. IBM 3580 (Ultrium) tape drive (Model L33)
6.
7.
8.
9.

IBM TS1140/TS1150 tape drive (Enterprise)


IBM TS1120/TS1130 tape drive (Enterprise)
IBM TS3200 tape library
IBM TS3500 and TS4500 tape library (also known as IBM UltraScalable tape
library 3584)

10. IBM TS3310 tape library


11. IBM TS3100 tape library
The image illustrates the attachment of various current products to an open
systems server.

3
4
2
5
10
1

System
Storage

8
7

dd000005

SystemSto
rage

Figure 1. Current attachment array

xviii

IBM Tape Device Drivers Installation and Users Guide

1 Open Systems Server

6 IBM TS1120/TS1130/TS1140/TS1150 tape


drive [also known as Enterprise]

2 IBM Virtualization Engine


TS7520/TS7530

7 IBM TS3200 tape library

3 IBM Virtualization Engine TS7650

8 IBM TS3500 or TS4500 tape library

4 IBM TS2230/TS2240/TS2250/TS2260


Ultrium 3/4/5/6 Half-High tape drive

9 IBM TS3310 tape library

5 IBM TS2340/TS2350/TS2360 (or 3580)


Ultrium 3/4/5/6 Full-High tape drive

10 IBM TS3100 tape library

Introduction

xix

xx

IBM Tape Device Drivers Installation and Users Guide

Chapter 1. Common extended features


Purpose
This chapter provides general information about the IBM device drivers,
requirements, and advanced functionality.

Path failover and load balancing


Device driver path failover support configures multiple physical paths to the same
device within the device driver and provides two basic functions:
1. Automatic failover to an alternate physical path when a permanent error occurs
on one path.
2. Dynamic load balancing for tape devices by using multiple host bus adapters
(HBA).
Path failover is supported on certain tape products with the latest IBM device
drivers available on the following website - http://www.ibm.com/support/
fixcentral. Instructions for downloading drivers can be found in Appendix A,
Accessing documentation and software online, on page 321. Some devices
require a path failover feature code to be installed before path failover support is
enabled in the device driver. Refer to Supported devices and feature codes on
page 6 for a list of supported devices and what path failover feature code is
required for your machine type.
At startup or configuration, the system detects multiple logical devices of the tape
drive. Each logical device is a physical path to the same tape drive. A backup and
restore application can open and use only one logical device at a time because they
represent the same physical device.
Without path failover support, if a permanent path error occurs (because of an
HBA or cable failure, for example), the application fails. It is possible to initiate
manual failover by restarting the application on the alternate logical device, but the
application must be restarted from the beginning. A long backup or restore
operation might be in progress when the path error occurred. Sometimes manual
failover requires operator intervention to reset the drive because a SCSI
Reservation might still exist on the failing HBA path.
When path failover support is enabled on all logical devices, the device driver
configures them internally as a single device with multiple paths. The application
can still open and use only one logical device at a time. If an application opens the
primary device and a permanent path error occurs, the device driver initiates
failover error recovery automatically on an alternate path. If successful, the current
operation continues on an alternate path without interrupting the application. The
data path failover error recovery first restores the previous device state, SCSI
Reservation, and tape position. Then, it tries the failing operation again.

Automatic failover
The automatic failover support provides error recovery on an alternate path when
a permanent error occurs on the primary path. This support is transparent to the
running application. The two types of path failover are Data Path failover (DPF)
Copyright IBM Corp. 2007, 2014

and Control Path failover (CPF). They are closely related. However, the difference
is that DPF is an automatic failover support for the transfer of data, which
provides error recovery for systems that are connected to tape drives. CPF is an
automatic failover support for the transfer of commands to move tape cartridges.
Examples of different configurations that can be constructed follow.

Data path failover


The following flowcharts outline the different types of configurations for data path
failover (DPF). These configurations are presented in order of best practices as
recommended by IBM.

Dual Host Bus Adapters (HBAs) to a multi-port drive


Consider a multipath connection that consists of two Host Bus Adapters (HBAs)
connected through a fabric to a multi-port drive.
Mulit-Port Drive
Dual HBA
A

Drive
Multi-Port Drive
In Library
Fabric

Drive

Library
Controller

Virtual Tape Library

a2500255

Drive

Figure 2. Dual HBA and multi-port drives

As seen in Figure 2, four available paths are available between the drive and the
host system. These paths are
HBA
HBA
HBA
HBA

A
A
B
B

to
to
to
to

drive
drive
drive
drive

port
port
port
port

1
2
1
2

[A, p1]
[A, p2]
[B, p1]
[B, p2]

One path is the primary path and the other three are alternate paths. If [A, p1] is
the primary path and if HBA A fails, two valid paths ([B, p1] and [B, p2]) remain.
The DPF tries to switch to one of the available configured paths. Conversely, if the
cable to port 1 of the drive fails with [A, p1] as the primary path, two valid paths
to the drive [A, p2] and [B, p2] are still available. Without DPF support, if a
permanent path error occurs (because of HBA or cable failover, for example), the
application fails. With DPF, if the permanent failure occurs with this configuration,
two valid physical paths for the data are still available for transmitting data. The
running application is not affected.
If the path that failed is restored, the device driver claims the path as available and
uses it as a valid alternate path in most conditions. This action is dependent on

IBM Tape Device Drivers Installation and Users Guide

Operating System and HBA behavior, not the IBM tape device driver behavior.

Dual Host Bus Adapters (HBAs) to a single-port drive


Consider a multipath connection that consists of two HBAs connected through a
fabric to a single-port device.

Dual HBA
Single-Port Drive
A

Drive

Fabric

Single Port Drive


In Library

Drive

Library
Controller

Virtual Tape Library

a2500256

Drive

Figure 3. Dual HBA and single-port drive

This configuration supplies two physical paths to the same device. However, if the
port or cable from the device fails, the automatic failover does not work. That
connection is severed and a permanent path error occurs. If, however, the failure
was with one of the HBAs or their cables, the automatic data path failover selects
the other HBA. Then, the information continues through the alternate path. An
example here is with the connections [A, p1] and [B, p1]. If [A, p1] is the primary
path and a failure occurs with the HBA or HBA cable, then DPF automatically
moves the connection to [B, p1] without affecting the application.

Single Host Bus Adapters (HBA) to a multi-port drive


Consider a single path from the HBA through the fabric to a multi-port device.

Chapter 1. Common extended features

Single HBA
Mulit-Port Drive

Drive
Mulit-Port Drive
In Library
Fabric

Library
Controller

Drive

a2500257

Drive

Virtual Tape Library


Figure 4. Single HBA and multi-port drive

This configuration also provides a failover path unless the failure is with the HBA
or the HBAs cable. At which point, the connection is severed and a permanent
path error occurs. Whereas, if the failure occurs on the device side, an alternative
path is still available for the information to go through which DPF automatically
failovers to.

Control path failover


The following flowcharts outline the different types of configurations for control
path failover (CPF). These configurations are presented in order of best practices as
recommended by IBM.

Dual Host Bus Adapters (HBAs) to multi-port drives


Consider a multipath connection that consists of two Host Bus Adapters (HBAs)
connected through a fabric to the library by at least two drives.

Library
Dual HBA
Drive 1

Drive 2

Library
Controller

Fabric

Control Path Failover (CPF)


Dual HBA Multi Drives

Virtual Tape Library

a2500293

Figure 5. Dual HBA and multi-port drives

As seen in Figure 5, four available paths are available between the drive and the
host system. These paths are
HBA
HBA
HBA
HBA

A
A
B
B

to
to
to
to

drive
drive
drive
drive

1
2
1
2

[A, d1]
[A, d2]
[B, d1]
[B, d2]

IBM Tape Device Drivers Installation and Users Guide

As with DPF, one path is the primary path and the other three are alternate paths.
If [A, d1] is the primary path and if HBA A fails, two remaining valid paths ([B,
d1] and [B, d2]) are still available. The CPF attempts to switch to one of the
available configured paths. Conversely, if the cable to drive 1 or drive 1 fails with
[A, d1] as the primary path, two valid paths to the drive ([A, d2] and [B, d2]) are
available. Without CPF support, if a permanent path error occurs (because of HBA
or cable failover, for example), the application fails. With CPF, if a permanent
failure with this configuration occurs, two valid physical paths are available for the
data to be transmitted. Also, the running application is not affected.
If the failed path is restored, the device driver claims the path as available and
uses it as a valid alternate path in most conditions. This action is dependent on
Operating System and HBA behavior, not the IBM tape device driver behavior.
Note: In the operating systems logs, reservation conflict information might appear,
which is because of scsi2 reservations that are not cleared. However, the
device driver continues to try any paths that are available to make the
reservation conflict transparent to the operating system.

Single Host Bus Adapter (HBA) to multi-port drives


Consider a single path from the HBA through the fabric to two drives in a library.

Library
Control Path Failover (CPF)
Single HBA Multi Drives

Drive 1
Drive 2

Library
Controller

Fabric

Virtual Tape Library

a2500292

Single HBA

Figure 6. Single HBA and multi-port drives

This configuration also provides a failover path unless the failure is with the HBA
or the HBAs cable. At which point, the connection is severed and a permanent
path error occurs. Whereas, if the failure occurs with a drive or a drives cable, an
alternative path is still available for the information to go through which CPF
automatically failovers to.

Dynamic load balancing


The dynamic load balancing support optimizes resources for tape devices that have
physical connections to multiple host bus adapters (HBA) in the same machine.
When an application opens a device that has multiple configured HBA paths, the
device driver determines which path has the HBA with the lowest usage. Then, it
assigns that path to the application. When another application opens a different
device with multiple HBA paths, the device driver again determines the path with
the lowest HBA usage. Then, that path is assigned to the second application. The
device driver updates the usage on the HBA assigned to the application when the
device is closed. Dynamic load balancing uses all host bus adapters whenever
possible and balance the load between them to optimize the resources in the
machine.

Chapter 1. Common extended features

For example, consider a machine with two host bus adapters, HBA1 and HBA2,
with multiple tape drives attached. Each tape drive is connected to both HBA1 and
HBA2. Initially, there are no tape drives currently in use. When the first application
opens a tape drive for use, the device driver assigns the application to use HBA1.
When a second application opens a tape drive for use, the device driver assigns
the second application to use HBA2. A third application is assigned to HBA1 and a
fourth application is assigned to HBA2. Two applications are assigned to HBA1
and two applications are assigned to HBA2.
If the first application finishes and closes the device, there is now one application
with HBA1 and two applications with HBA2. When the next application opens a
tape drive, it is assigned to HBA1, so again there are two applications with HBA1
and two applications with HBA2. Likewise, if the second application finishes and
closes the device, HBA2 has one application that is assigned to it. The next
application that opens a tape drive is assigned to HBA2.
The dynamic load balancing support is independent from the automatic failover
support. Regardless of the path that is assigned initially for load balancing, if that
path fails, the automatic failover support attempts recovery on the next available
path.

Dynamic Runtime Attributes


There are frequently field issues where customers must know which Initiator is
holding a reservation in a drive or preventing the media from being unloaded.
Also, they must correlate which drive special file name is used for the drive (such
as rmt2). Sometimes this issue occurs over transport bridges and translators, losing
any transport identifiers to help in this effort. LTO5, 3592 E07 (Jag 4) and later
physical tape drives support attributes that are set to the drive dynamically by a
host. This function is called Dynamic Runtime Attributes (DRA).
This feature is enabled by default. The attributes are set in the drive by the host
during open, close, device reset, and data path change only. If there is a problem
with sending the attributes to the drive, the error is ignored and not returned to
the application.
There is no ioctl in the IBM tape drivers to retrieve the dynamic runtime attributes
but is an upcoming command on ITDT. The attributes can also be retrieved
through a pass through ioctl to issue Read Dynamic Runtime Attributes SCSI
command (see applicable IBM Tape Drive SCSI Reference). See the host platform
section for any special information that pertains to the driver that concerns DRA. If
there is a question whether your driver level supports DRA, see the fixlist that
comes with your driver to see whether it was added. Updates are also required
with the drive firmware.

Supported devices and feature codes


Path failover is supported only for the devices that are listed in Table 1 on page 7.
Path failover includes Control Path failover (CPF) for tape libraries and Data Path
failover (DPF) for tape drives. To use path failover support, some devices require
feature codes as listed in Table 1 on page 7.

IBM Tape Device Drivers Installation and Users Guide

Table 1. Supported devices and feature codes


Supported tape library/drive

Feature code (FC), if required

|
|

TS3500 and TS4500/3592

Standard, no FC required (DPF)


FC 1682 (CPF)

TS3500 and TS4500/LTO

FC 1682 (CPF and DPF)

|
|

TS3400/3592

Standard, no FC required (DPF)


FC 1682 (CPF)

TS3310/LTO

FC 1682 (CPF and DPF)

TS3200/LTO

FC 1682 (CPF and DPF)

TS3100/LTO

FC 1682 (CPF and DPF)

TS7520/All

FC 1682 (CPF and DPF)

TS7650/All

Standard, no FC required (CPF and DPF)

3583

FC 1680 (CPF), FC 1681 (DPF)

3582

FC 1680 (CPF), FC 1681 (DPF)

Note:
1. Path failover is not supported on parallel SCSI (except for some parallel
SCSI drives on AIX operating systems). Path failover is only supported
on SAS devices that are attached to Windows and Linux for Intel/AMD
processor-based servers. SAS is not supported on System p servers (AIX
and Linux).
2. Path failover is not supported on Virtual Tape Libraries (except for the
libraries that are listed in Table 1) that emulate IBM tape devices.
3. If your device does not support path failover, you must disable this
option in the device driver. See the specific platform section for driver
default behavior and enable/disable failover instructions.

Data encryption
Tape and library requirements
The LTO Ultrium 4, 5, and 6 tape drives support host Application Managed
Encryption (AME), Library Managed Encryption (LME), and System Managed
Encryption (SME), by using T10 encryption methods, for SAS and Fibre Channel
drives only. Data encryption is supported by LTO Ultrium 4, Ultrium 5, and
Ultrium 6 Data Cartridges only. Encryption is also supported by library firmware
version 4.0 or higher.
The encryption-enabled drive contains the necessary hardware and firmware to
encrypt and decrypt host tape application data. Encryption policy and encryption
keys are provided by the host application or host server. A drive digital certificate
is installed at manufacturing time. Each drive receives a unique serial number and
certificate. The T10 application can validate each drive instance by checking the
drive's digital certificate.
|
|
|
|
|

The IBM TS1120 (3592 Model E05) and newer tape drives can encrypt data as it is
written to their supporting IBM 3592 Enterprise Tape Cartridges, including WORM
cartridges. The IBM TS1040 LTO Ultrium 4 and newer Ultrium tape drives can also
encrypt data as it is written to any LTO 4 or newer data cartridge. Encryption is
completed at full line speed in the tape drive after compression. (Compression is
Chapter 1. Common extended features

more efficiently done before encryption.) This new capability adds a strong
measure of security to stored data without the processing overhead and
performance degradation that is associated with encryption done on the server or
the expense of a dedicated appliance.

|
|
|
|

The following three major elements comprise the tape drive encryption solution.
v The encryption-enabled tape drive
The 3592 Model E07 and newer model tape drives, and the LTO Ultrium 4 and
newer Ultrium drives are encryption capable. All TS1120 Model E05 tape drives
with Feature code 5592 or 9592 are encryption capable. They are functionally
capable of completing hardware encryption, but this capability is not yet
activated. To run hardware encryption, the tape drives must be
encryption-enabled. Encryption can be enabled on the encryption-capable tape
drives through the Tape Library Specialist Web interface. Refer to the
appropriate section in the documentation for your library for information about
how to enable encryption.

Note: FC 1604, Transparent LTO Encryption, is required to use system-managed


or library-managed encryption on LTO Ultrium 4 and newer tape drives.
It is not required for application-managed encryption. Refer to the
sections on each method of encryption for information.
v Encryption key management
Encryption involves the use of several kinds of keys, in successive layers. How
these keys are generated, maintained, controlled, and transmitted depends upon
the operating environment where the encrypting tape drive is installed. Some
data management applications, such as Tivoli Storage Manager, can run key
management. For environments without such applications or where
application-agnostic encryption is wanted, IBM provides a key manager (such as
the Tivoli Key Lifecycle Manager or the IBM Security Key Lifecycle Manager) to
complete all necessary key management tasks.
v Encryption policy
The method that is used to implement encryption. It includes the rules that
govern which volumes are encrypted and the mechanism for key selection. How
and where these rules are set up depends on the operating environment.

The LTO Ultrium 6 encryption environment is complex and requires knowledge


beyond that of product trained Service Support Representatives (SSRs). The
Encryption function on tape drives (desktop, stand-alone, and within libraries) is
configured and managed by the customer. In some instances, SSRs are required to
enable encryption at a hardware level when service access or service password
controlled access is required. Customer setup support is by Field Technical Sales
Support (FTSS), customer documentation, and software support for encryption
software problems. Customer 'how to' support is also provided with a support line
contract.
In the open system environment, there are three methods of encryption
management to choose from. These methods differ in where you choose to locate
your encryption key manager application. Your operating environment determines
which is the best for you, with the result that key management and the encryption
policy engine might be in any one of the three environmental layers: application
layer, system layer, and library layer.

IBM Tape Device Drivers Installation and Users Guide

Application-managed tape encryption


This method is best where operating environments run an application already
capable of generating and managing encryption policies and keys, such as Tivoli
Storage Manager (TSM). Policies specifying when encryption is to be used are
defined through the application interface. The policies and keys pass through the
data path between the application layer and the Encryption is the result of
interaction between the application and the encryption-enabled tape drive, and is
transparent to the system and library layers.
Refer toPlanning for application-managed tape encryption on page 10 for details
on the hardware and software requirements for application-managed encryption.
For details on setting up application-managed tape encryption refer to the Tivoli
Storage Manager documentation or for information, visit the following site http://publib.boulder.ibm.com/infocenter/tivihelp/v1r1/index.jsp
It is required to use the latest device drivers available. Refer to Appendix A,
Accessing documentation and software online, on page 321 for downloading
drivers.

System-managed tape encryption


In this method, key generation and management are completed by an encryption
key manager (EKM). Policy controls and keys pass through the data path between
the system layer (device drivers) and the encryption-capable tape drives.
Encryption is transparent to the applications.
Note: The abbreviation EKM for the driver configuration file is used generically to
refer to any encryption key manager.
It is required to use the latest device drivers available on the website. See
Appendix A, Accessing documentation and software online, on page 321 for
instructions.
Refer to Planning for system-managed tape encryption on page 10 for details on
the hardware and software requirements for system-managed encryption. For
details on setting up system-managed encryption in different operating system
environments, refer to the applicable chapter for each operating system.

Library-managed tape encryption


This method is best for encryption-capable tape drives in open attached IBM tape
libraries. Scratch encryption policies that specify when to use encryption are set up
through the IBM Tape Library Specialist Web interface. Policies are based on
cartridge volume serial numbers. Key generation and management are run by an
encryption key manager. Policy control and keys pass through the library-to-drive
interface, therefore encryption is transparent to the applications.
Refer toPlanning for library-managed tape encryption on page 13 for details on
the hardware and software requirements for library-managed encryption. For
details on setting up library-managed encryption on encryption-capable tape
drives, refer to the IBM Tape Library Operator's Guide for your library.

Chapter 1. Common extended features

Planning for application-managed tape encryption


Note: Contact your IBM representative for information about encryption on the
IBM encryption-capable tape drive.
To run encryption on the encryption-capable tape drive, the following is required.
v Encryption-capable tape drive
v Encryption configuration features:
Library code updates and Transparent LTO Encryption feature code for
encryption-capable libraries
Tape drive code updates

Application-managed tape encryption setup tasks


Any task that is not identified as an IBM service task is the responsibility of the
customer.
1. Install, cable, and configure the encryption-capable tape drive (refer your IBM
Tape Drive or Library Operator's Guide)
2. Install appropriate IBM tape device driver level (Atape, for example).
3. Set up encryption policies. Refer to the appropriate Tivoli Storage Manager
documentation.
4. Perform write/read operation to test encryption.
5. Verify encryption of the test volume by Autonomic Management Engine
(AME): issue QUERY VOLUME FORMAT=DETAILED
Verify that Drive Encryption Key Manager is set to Tivoli Storage Manager.

Planning for system-managed tape encryption


Note: Contact your IBM representative for information about encryption on the
IBM encryption-capable tape drive.
To run encryption on the encryption-capable tape drive, the following is required.
v Encryption-capable tape drive
v Keystore (Refer to documentation on Tivoli Key Lifecycle Manager (TKLM))
v Encryption configuration features:
Tivoli Key Lifecycle Manager (TKLM)
Tape drive code updates and Transparent LTO Encryption feature code for
encryption-capable libraries
Tape system library code updates

Setup tasks for system-managed tape encryption on Open


Systems operating system
Any task that is not identified as an IBM service task is the responsibility of the
customer.
1. Install, verify, and configure
a. Keystore
b. EKM (Refer to documentation on Tivoli Key Lifecycle Manager (TKLM))
Note: The SSL protocol in TKLM is not supported by SME.

10

IBM Tape Device Drivers Installation and Users Guide

2. Install, cable, and configure encryption-capable tape drive (refer to your IBM
Tape Drive or Library Operator's Guide).
3. Install and enable appropriate device driver level (refer to the appropriate
operating system chapter in this document for details).
4. Edit the /etc/ibmekm.conf file.
5. Use [38] Test Encryp. Path (Test Encryption Key Path/Setup) on page 252 or
Test Encryption Path on page 316 to verify.

System-managed encryption configuration


Note: The tape drive must be set to system-managed encryption from the drive
panel or library user interface before device driver system-managed
encryption is used.
After the device driver is installed, then an encryption key manager must be
configured. The servers are configured in a text file ibmekm.conf that is installed
in the /etc directory by the device driver if a current configuration file does not
exist.
Figure 7 on page 12 is an example of the sample configuration file installed.

Chapter 1. Common extended features

11

# IBM Encryption Key Manager Configuration File


#
# (C) COPYRIGHT International Business Machines Corp. 2006
# All Rights Reserved
# Licensed Materials - Property of IBM
#
# US Government Users Restricted Rights - Use, duplication or
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
#
# This file contains the TCP/IP address(s) and port(s) for the Encryption Key
# Server with a configuration entry in the following formats. The IPv4 address
# entered as x.x.x.x:port. The IPv6 address entered as x:x:x:x:x:x:x:x port.
# The server is for information only and is not used. The timeout value is
# specified in seconds.
#
# The format for IPv4 address:
# server timeout address:port
# for example,
# ekmtest 10 9.12.123.1234:8050
#
# The format for IPv6 address:
# server timeout address port
# for example,
# ekmtest 10 fe80::207:30ee:edcb:d05d 8050
#
# The Encryption Key Server address and port can be a local loop back
# address 127.0.0.1:port in IPv4 format or ::1 port in IPv6 format if the server
# is on the same host or a network address and port if external to the host.
# Up to 16 server address and port entries are supported if there are multiple
# TCP/IP connections to the same server and/or multiple servers.
#
# Interoperability between IPv4 and IPv6 versions running on dual-stack hosts:
#
IPv4 Client <--> IPv4/IPv6 Server
using IPv4 address for EKM server
#
IPv6 Client <--> IPv4 Server
using IPv4 address for EKM server
#
IPv6 Client <--> IPv6 Server
using IPv6 address for EKM server
#
# Sample entry for a local server with a 10 second timeout using port 8050
# in IPv4 format
# ekmtest 10 127.0.0.1:8050
#
# in IPv6 format
# ekmtest 10 ::1
8050
Figure 7. Sample configuration file

The following shows the different entry formats for IPv4 and IPv6 addresses in the
ibmekm.conf configuration file:
v IPv4 format: EKMserver timeout IPv4_address
Port_number
v IPv6 format: EKMserver

timeout

IPv6_address

Port_number

To set up an IP address for an encryption key manager server, use Table 2 to


choose an appropriate IP address type. Then, add the IP address in the entry of the
encryption configuration file.
Table 2. Interoperability between IPv4 and IPv6 clients and servers
IPv4 EKM
IPv6 EKM
IPv4 EKM
server IPv4-only server IPv6-only server
host
host
dual-stack host
IPv4
IPv4
Client/IPv4-only
host

12

IBM Tape Device Drivers Installation and Users Guide

(no)

IPv4

IPv6 EKM
server
dual-stack host
IPv4

Table 2. Interoperability between IPv4 and IPv6 clients and servers (continued)
IPv4 EKM
IPv6 EKM
IPv4 EKM
server IPv4-only server IPv6-only server
host
host
dual-stack host

IPv6 EKM
server
dual-stack host

IPv6
(no)
Client/IPv6-only
host

IPv6

(no)

IPv6

IPv4 Client
dual-stack host

IPv4

(no)

IPv4

IPv4

IPv6 Client
dual-stack host

IPv4

IPv6

(no)

IPv6

The timeout value in seconds is used when a request is sent to the server and the
time for the server to respond in case no response is received.
A maximum of 16 server connections are configured for failover. When a
connection cannot be made or is lost on the current server that is used, the
operation is tried again on the next configured server.
After servers are configured in the ibmekm.conf file, then specific tape drives
must be configured to the device driver for system-managed encryption. The
device driver default does not enable encryption. Refer to the following sections
for specific information, depending on the operating system.

Planning for library-managed tape encryption


Note: Contact your IBM representative for information about encryption on the
IBM encryption-capable tape drive.
To complete encryption on the encryption-capable tape drive, the following is
required.
v Encryption-capable tape drive
v Keystore (Refer to documentation on Tivoli Key Lifecycle Manager (TKLM))
v Encryption configuration features:
Tivoli Key Lifecycle Manager (TKLM)
Tape system library code updates and Transparent LTO Encryption feature
code for encryption-capable libraries
Tape drive code updates

Library-managed tape encryption tasks


Any task that is not identified as an IBM service task is the responsibility of the
customer.
1. Install, verify, and configure
a. Keystore
b. EKM (Refer to documentation on Tivoli Key Lifecycle Manager (TKLM)) for
information on both.
2. Install and cable the encryption-capable tape drive (IBM service task for TS1120
Tape Drive).
3. Use IBM tape library specialist to enable the tape drive for library-managed
tape encryption (refer to your IBM Tape Drive or Library Operator's Guide).
Chapter 1. Common extended features

13

4.

Use library diagnostic functions to verify.

Bulk rekey
For customers with Library-Managed Encryption with 3592 Enterprise tape drives
and IBM tape and changer drivers that are running on open systems operating
system (AIX, HP-UX, Linux, Solaris, Windows), sample code for completing bulk
rekey operations is available. The sample code packages are provided "as-is" with
limited testing, and are provided to give customers guidance on bulk rekey
operations.
For UNIX operating systems, a sample script (rekey_unix.sh) is provided and must
be used with the tapeutil version that is bundled in the same package. For
Windows operating systems, a sample c program (rekey_win.c) is provided. Both
of these sample programs must be used with both the IBM tape and changer
drivers. In addition, data cartridges must be in storage cells, not in I/O station
cells or tape drives.
For information and to download the sample code packages, see
http://www.ibm.com/support/fixcentral/.

Encryption feature codes


To use system-managed and library-managed encryption, the Transparent LTO
Encryption feature codes that are listed in Table 3 are required for the associated
IBM tape libraries with encryption-capable tape drives. If the drives in use are
TS1120 tape drives, this feature code is not required for system-managed or
library-managed encryption. If you are using application-managed encryption, no
feature code is required on any encryption-capable tape drives.
Table 3. Feature codes (encryption)
Tape library

14

Feature code

TS4500

FC 1604

TS3500

FC 1604

TS3400

Standard Feature

TS3310

FC 5900

TS3100/3200

FC 5900

IBM Tape Device Drivers Installation and Users Guide

Chapter 2. AIX Tape and Medium Changer device driver


This chapter describes the IBM AIX Enhanced Tape and Medium Changer Device
Driver (Atape) for IBM tape devices.

Purpose
The IBM AIX Enhanced Tape and Medium Changer device driver is designed to
take advantage of the features that are provided by the IBM tape drives and
medium changer devices. The goal is to give applications access to the functions
required for basic tape operations (such as backup and restore) and medium
changer operations (such as mount and unmount the cartridges), and to the
advanced functions needed by full tape management systems. Whenever possible,
the driver is designed to take advantage of the device features transparent to the
application.

Data flow
The software that is described in this chapter covers the AIX Enhanced Device
Driver (Atape device driver) and the interface between the application and the
tape device. For data flow, refer to Figure 8.

Figure 8. Data flow for AIX Device Driver (Atape)

Product requirements
Hardware requirements
Refer to Hardware requirements on page xvii the latest hardware that is
supported by the Atape device driver.

Software requirements
The AIX Enhanced device driver (Atape device driver) supports AIX 5L Version
5.3 and later releases on IBM POWER-based AIX servers.
For current software requirements, refer to the Software requirements on page
xvii.

Installation and configuration instructions


The recommended procedure for installing a new version of the device driver is to
uninstall the previous version.
Instructions for uninstalling the device driver are outlined in Uninstalling on
page 18.
Copyright IBM Corp. 2007, 2014

15

1. At the end of the installation procedure, the installp facility automatically runs
the AIX bosboot command to update the boot record with the newly installed
Atape files. When the bosboot command completes, the following messages are
displayed:
0503-292 This update does not fully take effect until after a system reboot.
installp: bosboot process completed.

This message refers to the updates to the boot record only. If the installation
summary shows that the Atape driver was installed successfully, it is not
necessary to reboot the machine currently.
If the installation summary shows that the installation failed, you must reboot
the machine and attempt to install the Atape driver a second time.
2. During the Atape install, the following entries are entered into the two system
files.
v /usr/lpp/bosinst/cdfs.optional.list to help the system image backup to
DVD/CD media
The entry list in /usr/lpp/bosinst/cdfs.optional.list:
/usr/lib/drivers/Atape
/usr/lib/methods/cfgAtape
/usr/lib/methods/ucfgAtape
/usr/lib/methods/defAtape
/usr/lib/methods/udefAtape
/usr/lib/methods/chgAtape

/usr/lib/drivers/Atape
/usr/lib/methods/cfgAtape
/usr/lib/methods/ucfgAtape
/usr/lib/methods/defAtape
/usr/lib/methods/udefAtape
/usr/lib/methods/chgAtape

Atape.driver
Atape.driver
Atape.driver
Atape.driver
Atape.driver
Atape.driver

v /usr/lpp/bosinst/tape/tapefiles1 to create a bootable tape


The entry list in /usr/lpp/bosinst/tape/tapefiles1:
/usr/lib/drivers/Atape
/usr/lib/methods/ucfgAtape
/usr/lib/methods/cfgAtape
/usr/lib/methods/udefAtape
/usr/lib/methods/defAtape
/usr/lib/methods/chgAtape

The entries are removed from the files when Atape is uninstalled.
Attention: The entries might be lost when a user upgrades the AIX file set of
bos.sysmgt.sysbr for System Backup and BOS Install Utilities after Atape
installation. It is recommended that the user check whether the entries still exist
and add the entries into the files if needed.

Installation procedure
For information on obtaining the latest version of device drivers and the latest
documentation, refer to Appendix A, Accessing documentation and software
online, on page 321.

Preinstallation considerations
Before the installation starts, verify the following items:
1. The tape device is properly functioning, properly attached to the server, and is
powered up.
2. You logged on to the server on an account that has root authority.
3. You have a command shell window open on the server to run the installation
procedure.

16

IBM Tape Device Drivers Installation and Users Guide

4. Make sure that the current path is defined in the command shell PATH
variable. This definition can be accomplished in the Korn shell by using the
following command:
EXPORT PATH=.:$PATH

5. If the tape device was configured previously by another device driver (not
Atape), remove any existing device definitions for it. The following command
is an example: rmdev -l ost1 -d

Installation procedure
Enter the following command to list the currently installed Atape.driver version:
lslpp -l Atape.driver

Enter the following command to install the Atape driver in the current directory.
For example
installp -acXd Atape.x.x.x.x Atape.driver

This command installs and commits the Atape driver on the system.

Configuring Tape and Medium Changer devices


After the driver software is installed and a tape device is connected to the adapter,
the device can be configured and made available for use. Access to the device is
not provided until the device is configured.
Note: If the tape device was configured previously by another SCSI device driver,
such as OST (Other SCSI Tape), issue the following command to remove the
device definition before the following steps are completed.
rmdev -l [device]

Configure a tape device by using one of the following procedures.


v Enter the following command with no parameters.
cfgmgr

The command configures all devices automatically (including any new tape or
medium changer devices).
v Power Off your subsystem and reboot the system to configure it automatically
and make available any new tape or medium changer devices on the system.

Configuring limitations
The subsequent limitations are applied for the Atape driver that runs on an AIX
host.
Maximum supported number of tape devices

1024

Maximum supported number of HBA ports

32

Maximum supported number of paths for a


device (DPF/ CPF)

16/16

Maximum LUN size per target for FC HBA*

4095

Note: *On AIX systems, the maximum LUN number is 4095. Since Atape supports up to
1024 devices, Atape configures a total of 1024 devices by using the range from LUN 0 4095. For instance, a device with LUN 4095 at a SCSI target address can be configured by
Atape if the total number of devices on the system is less than 1024.

Chapter 2. AIX Tape and Medium Changer device driver

17

Every opened tape device uses a certain amount of resources. The user must also
consider other resources such as physical memory and virtual space on the system
before you attempt to reach the limits.

Deconfiguring tape devices


Note: In the following examples, replace the letter n with the appropriate number
for the chosen device.
Deconfigure the tape device by using one of the following procedures:
1. The first method leaves the tape device that is defined in the configuration
database. It is similar to bringing the device offline (not in use).
Enter the following command to bring the /dev/rmtn tape device offline, but
leave it defined in the device database.
rmdev -l rmtn

2. The second method brings the tape device offline and removes its definition
from the device database.
Enter the following command.
rmdev -l rmtn -d

The device driver is not unloaded from the kernel until the last device is
deconfigured.

Deconfiguring Medium Changer devices


Note: In the following examples, replace the letter n with the appropriate number
for the chosen device.
Deconfigure the medium changer device by using one of the following procedures:
1. The first method leaves the device that is defined in the configuration database.
It is similar to bringing the device offline.
Enter the following command to bring the /dev/smcn medium changer device
offline, but leave it defined in the device database.
rmdev -l smcn

2. The second method brings the medium changer device offline and removes its
definition from the device database.
Enter the following command.
rmdev -l smcn -d

The device driver is not unloaded from the kernel until the last device is
deconfigured.

Uninstalling
Attention: All devices that use the Atape driver must be closed and cannot be in
use when Atape is uninstalled or the uninstall fails.
You can uninstall the Atape device driver by using the smit command menu to
uninstall software and selecting Atape.driver or by using the following installp
command
installp -u Atape.driver

18

IBM Tape Device Drivers Installation and Users Guide

Tape drive, media, and device driver parameters


This chapter describes the parameters that control the operating modes of the AIX
Enhanced Tape and Medium Changer Device Driver.

Configuration parameters
The operating parameters for the tape drive and device driver are set and changed
by configuration parameters. The installation defaults are provided for all
parameters initially. The AIX smit command is used to set these parameters when
a device is configured or to change these parameters. The AIX chdev command is
used to change the configuration parameters.
The configuration parameters are used to set the operating mode of the tape drive
and device driver when a device is opened. These parameters can be queried by an
application. Some parameters can be temporarily changed during the open
subroutine by an application. But, they are always restored to the configuration
values when a device is closed. The configuration parameters are
v Alternate Pathing
v Autoloading
v Emulate autoloader (359x devices only)
v Block size
v Buffered mode (359x devices only)
v Compression
v
v
v
v
v

Fail degraded media (359x devices only)


Logical write protect (359x devices only)
Logging
Maximum size of the log file
New logical name

v Read error recovery time (359x devices only)


v Record space mode
v Reservation key
v Reservation support
v Reservation type
v Retain reservation
v Rewind immediate
v System encryption
v System encryption for Write Commands
v Trailer labels
v SCSI status busy retry

Alternate pathing
This parameter enables or disables the path failover support when a device is
configured.Data Path failover and load balancing support for tape drives on
page 32 for a description of the path failover and failover support.
The installation default is no (path failover is not enabled).

Chapter 2. AIX Tape and Medium Changer device driver

19

Autoloading
This parameter enables the autoloading feature of the device driver. It is used with
the autoloading capability of the autoloader, ACF, ACL, or CSL installed on the
tape device.
Note: The autoloading feature is not supported on the IBM 3584 UltraScalable tape
library and the IBM 3583 Ultrium Scalable tape library with more than one
IBM 3580 Ultrium tape drive installed.
Note: The autoloading feature is supported only on the following device types and
configurations:
v IBM 3490E Models C11, C22, E01, E11, F01, and F11
v IBM Enterprise Tape System 3590, Models B11, E11, and H11
v IBM Magstar MP 3570 Models B01, C01, B11, and C11
v IBM Magstar MP 3570 Models B02, B12, C02, and C12 (configured in split
mode only)
v IBM 7332 (all models)
Do not enable autoloading if one of the following conditions is true.
v The device is used by an application that provides library medium changer
support for the IBM 3581 or IBM 3583.
v The device is installed in a 3494 Enterprise Tape Library.
v The device is used by an application with stack loader support.
v The application is MKSYSB.
v The tapes that are read were not written with the autoloading feature.
Tapes that are created with AUTOLOAD=YES are not readable in configurations
without Atape autoload enabled, or on other UNIX operating systems, or on device
types/models that are different from the backup device type/model.
If the parameter is set to On, then the tape stacker acts as one large virtual tape.
During a read, write, or forward space file operation, no end of tape is detected by
the application. When the end of tape is reached, the device driver automatically
rewinds and unloads the tape, then loads the next tape. Then, it continues reading
or writing the next tape. The following conditions are required to use this feature:
v The autoloading parameter must be set to On.
v The cartridge stacker must be loaded with one or more tapes.
v The ACF, ACL, or CSL must be set to Automatic, System, or Random mode.
This feature allows multivolume backups (with commands such as tar) without
prompting for a volume change.
The installation default is Off (no autoloading).

Emulate autoloader
This parameter controls how the device driver operates when the ACF on the IBM
Enterprise Tape System 3590, the IBM Magstar MP tape device, or the IBM 3490E
Model Fxx is set to Random mode. If this parameter is set to On and the ACF is in
Random mode, the device driver emulates an autoloading tape drive. When an
unload command is sent to the device driver to unload a tape, the tape is
unloaded, returned to the magazine, and the next tape in the magazine is loaded

20

IBM Tape Device Drivers Installation and Users Guide

automatically into the tape drive. If this parameter is set to Off, the normal unload
operation occurs, and the tape remains in the drive.
The emulate autoloader parameter can be used for legacy applications that are
written for the IBM 3490E Automated Cartridge Loader (ACL) when the IBM
Enterprise Tape System 3590, the IBM Magstar MP 3570, or the IBM 3490 Model F
autoloader is set to Random mode. This parameter eliminates the need to
reconfigure the autoloader of the device Random or Automatic operation.
The installation default is Off (do not emulate autoloader).
Note: On IBM Magstar MP 3570 Models B02, C02, and C12, this feature is
supported only when the two drives are configured in Split mode, or in
Base mode with one drive that is configured and available to AIX. This
feature does not work in Base mode if both drives are in the available state
to AIX.

Block size
This parameter specifies the block size that is used for read and write operations.
A value of zero is the variable block size. Any other value is a fixed block size.
The installation default is zero (use variable length) except for the IBM 7332 4-mm
Tape Cartridge Autoloader, for which the default is a fixed block size of 1024 bytes.

Buffered mode
When a write command is processed, the data is either stored directly on the
physical tape or buffered in the tape device. Buffering can increase the device
performance.
The installation default is On (use Buffered mode).

Compression
Hardware compression is implemented in the device hardware. This parameter
turns the compression feature On and Off. If compression is enabled, then the
effective performance can increase based on the compressibility of the data.
The installation default is On (use compression).

Fail degraded media


This parameter controls whether the device driver fails a tape operation when
degraded media is detected by the IBM Enterprise Tape System 3590. If a tape is
loaded and the IBM 3590 cannot read the positioning information from the tape,
the device driver is notified when the first command is sent to the tape drive. If
this parameter is set to On, the device fails the command and returns a media
error to the application. If this parameter is set to Off, the device driver does not
fail the command.
Degraded media is a correctable condition that prevents the IBM Enterprise Tape
System 3590 from running high speed Locate operations. A Locate command can
take over 20 minutes, depending on the wanted position and the amount of data
on the tape. This parameter is intended for use by real-time applications that
cannot tolerate long Locate commands.
Chapter 2. AIX Tape and Medium Changer device driver

21

The installation default is Off (do not fail the tape operation if degraded media is
detected).

Logging
This parameter turns the volume information logging on and off. If logging is set
to On, the statistical information about the device and media is saved in a log file
when a tape is unloaded. If logging is set to Off, the information is not saved. This
parameter has no effect on error logging because error logging is always enabled.
For information, refer to Device and volume information logging on page 36.
The installation default is Off (no logging).

Maximum size of the log file


This parameter specifies the number of entries that are made before the log file
starts to wrap. Each entry is approximately 2 KB (2048 bytes). After the log file
starts to wrap, the number of entries stays constant. Each time a new entry is
made, the oldest entry is overlaid. For information, refer to Device and volume
information logging on page 36.
The installation default is 500.

New logical name


Setting this parameter changes the logical name of the device to a new name as
specified. After the logical name is changed, the new logical name parameter is
cleared. For information, refer to Persistent Naming Support on page 28.
There is no installation default value for this parameter.

Read error recovery time


This parameter controls the read error recovery time for the IBM Enterprise Tape
System 3590. If this parameter is set to On, the recovery time for read errors is
limited to a maximum of 5 seconds. If this parameter is set to Off, full recovery is
used by the device and can take up to 10 minutes. This parameter is intended for
use by real-time applications that cannot tolerate long delays when data is read
from the tape.
The installation default is Off (do not limit the read error recovery time).

Record space mode


This parameter specifies how the device driver operates when a forward or
backward space record operation encounters a filemark. The two modes of
operation are SCSI and AIX.
The SCSI mode is the default mode of operation. When a forward or backward
space record operation is issued to the driver and a filemark is encountered, the
device driver returns -1 and the errno variable is set to input/output error (EIO).
The tape is left positioned after the filemark (the end-of-tape side of the filemark
on the forward space and the beginning-of-tape side of the filemark on the
backward space).

22

IBM Tape Device Drivers Installation and Users Guide

The AIX mode returns the same EIO errno value as the SCSI mode when a filemark
is encountered except that the tape is left positioned before the filemark (the
beginning-of-tape side of the filemark on the forward space and the end-of-tape
side of the filemark on the backward space).
The installation default is SCSI mode.

Reservation key
This parameter specifies the SCSI Persistent Reservation key that is used by the
device driver when either the Reservation Type parameter is SCSI Persistent
Reserve and the Alternate Pathing parameter is set to no or when the Alternate
Pathing parameter is set to Yes.
The default for this attribute is blank (NULL).
If the Reservation Key parameter is specified as blank (NULL), then the device
driver uses an internal unique key for all devices on the host they are configured
on. Another AIX host that shares devices also have an internal unique key for all
devices if the Reservation Key parameter was blank (NULL).
If the default is not used, then the Reservation Key value can be specified as either
a 1-8 character ASCII alphanumeric key or a 1-16 hexadecimal key that has the
format 0xkey. If fewer than 8 characters are used for an ASCII key (such as host1),
the remaining characters are set to 0x00 (NULL). If less than a 16 hexadecimal key
is used, the remaining bytes are set to 0x00.
Note: When a Reservation Key is specified on each host that shares a device, the
key must be unique to each host.

Reservation support
The parameter of reserve_support indicates that the Atape driver manages the
reservation for the tape device when it is enabled. Atape reserves the tape device
in open and releases it in close, and maintains the reservation in error recovery
procedure (ERP).
Note: For the medium changer, this parameter is not applied when the Alternate
Pathing (path failover) parameter is set to Yes. The device driver forces the
setup to be disabled and the medium changer is not reserved in open when
the Alternate Pathing parameter is set to Yes.
The installation default is Yes.

Reservation type
This parameter specifies the SCSI Reservation type that is used by the device
driver, either a SCSI Reserve 6 command or a SCSI Persistent Reserve command.
Note: This parameter is not used if the Alternate Pathing (path failover)
parameter is set to Yes. The device driver uses SCSI Persistent Reserve when
the Alternate Pathing parameter is set to Yes.
The installation default is SCSI Reserve 6.

Chapter 2. AIX Tape and Medium Changer device driver

23

Retain reservation
When this parameter is set to 1, the device driver does not release the device
reservation when the device is closed for the current open. Any subsequent opens
and closes until the STIOCSETP IOCTL is issued with retain_reservation parameter
set to 0. The device driver still reserves the device on open to make sure that the
previous reservation is still valid.
The installation default is Off (the reservation is released in close).

Rewind immediate
This parameter turns the immediate bit On and Off in rewind commands. If it is
set to On, the rewind tape operation runs faster. However, the next command takes
a long time to finish unless the rewind operation is physically complete. Setting
this parameter reduces the amount of time that it takes to close a device for a
Rewind on Close special file.
The installation default is Off (no rewind immediate) except for the IBM 7332
4-mm Tape Cartridge Autoloader, for which the default is On (rewind immediate).

System encryption
This parameter specifies whether System-Managed Encryption must be used. For
information, refer to System-managed encryption on page 34.
The installation default is No.

System encryption for Write commands


This parameter controls if System-Managed Encryption is used for Write
commands. For information, refer to System-managed encryption on page 34.
The installation default is Custom.

Trailer labels
If this parameter is set to On, then writing a record past the early warning mark
on the tape is allowed. The first write operation to detect EOM fails, and the errno
variable is set to ENOSPC. No data is written during the operation. All subsequent
write operations are allowed to continue until the physical end of the volume is
reached and EIO is returned.
This parameter can also be selected by using one of three device special files that
allow trailer-label processing. The special files are rmtx.40, rmtx.41, and rmtx.60,
where x is the name of the device (for example, rmt0.40).
The installation default is Off (no trailer labels).

SCSI status busy retry


Atape retries the SCSI command fail due to the SCSI status Busy when the
parameter of busy_retry is set to On. Otherwise, Atape fails the SCSI command if
it is set to Off.
The installation default is Off.

24

IBM Tape Device Drivers Installation and Users Guide

Media parameters
The ability to set or change media parameters is a tape diagnostic and utility
function, refer to Chapter 8, IBM Tape Diagnostic Tool (ITDT), on page 211.
The media parameters can be queried and set by ITDT or the tape diagnostic and
utility function by using the Query/Set Parameters option in the window.
These parameters cannot be set or changed by the configuration procedures. The
media parameters are
v Capacity scaling
v Logical write protect
v Volume ID for logging

Capacity scaling
This parameter sets the capacity or logical length of the current tape on IBM
Enterprise Tape System 3590, IBM Enterprise Tape System 3592, or Magstar MP
tape subsystems. By reducing the capacity of the tape, the tape drive can access
data faster at the expense of data capacity.
Capacity scaling can be set at 100% for the entire tape (which is the default) or set
at 75%, 50%, or 25% of the tape or any device-specific hexadecimal value. For
example, on IBM 3592, to change capacity scaling from a 300 GB format tape
(100%) to a 60 GB format tape, select the capacity scaling option, then select the
option to enter a hexadecimal value and enter 35. Capacity scaling remains with
the tape across mounts until it is changed.
Note:
1. The tape position must be at the start of the tape to change this
parameter from its current value.
2. Changing this parameter destroys any existing data on the tape.
3. Attempting to set capacity scaling that is not supported by a device or
the current media loaded always returns 100% and cannot be changed.
For example, 60 GB media for the IBM 3592 cannot be capacity scaled
and is always 100%.

Logical write protect


This parameter sets or resets the logical write protect of the current tape on IBM
Enterprise Tape System 3590, IBM Enterprise Tape System 3592, or Magstar MP
tape subsystems. The three types of logical write protect are associated protect,
persistent protect, and write-once read-many (WORM) protect.
Associated protect remains only while the current tape is mounted or associated
with the tape drive. It is reset when the tape is unloaded or the tape drive is reset.
Persistent protect remains or persists with the tape across mounts until it is reset.
WORM protect also remains with the tape across mounts, but (unlike persistent
protect) it cannot be reset on the tape. After a tape is WORM protected, it can
never be written on again.
Note:
Chapter 2. AIX Tape and Medium Changer device driver

25

1. The tape position must be at the start of the tape to change this
parameter from its current value.
2. Attempting to set logical write protect that is not supported by a device
or the current media loaded always returns "No" and cannot be changed.

Volume ID for logging


This parameter is the volume ID of the current loaded tape. It is used in the log
file entry (if volume logging is active) to identify the entry with a particular
volume. The device driver sets the volume ID to UNKNOWN initially and when
the tape is unloaded.

Special files
When the driver is installed and a tape device is configured and available for use,
access is provided through the special files. These special files, which consist of the
standard AIX special files for tape devices (with other files unique to the Atape
driver), are in the /dev directory.

Special files for tape devices


Each tape device has a set of special files that provides access to the same physical
drive but to different types of functions. As shown in Table 4, in addition to the
tape special files, a special file is provided for tape devices that allow access to the
medium changer as a separate device.
Note: The asterisk (*) represents a number that is assigned to a particular device
(such as rmt0).
For tape drives with attached SCSI medium changer devices, the rmt*.smc special
file provides a separate path for commands that are issued to the medium changer.
When this special file is opened, the application can view the medium changer as a
separate SCSI device.
Both this special file and the rmt* special file can be opened at the same time. The
file descriptor that results from opening the rmt*.smc special file does not support
the following operations.
v Read
v Write
v Open in Diagnostic mode
v Commands that are designed for a tape drive
If a tape drive has a SCSI medium changer device that is attached, then all
operations (including the medium changer operations) are supported through the
interface to the rmt* special file. For detailed information, refer to Table 4.
Table 4. Special files for tape devices
Rewind on
Close (Note
1)

Retension
on Open
(Note 2)

Bytes per
Inch (Note
3)

Trailer Label

Unload on
Close

/dev/rmt*

Yes

No

N/A

No

No

/dev/rmt*.1

No

No

N/A

No

No

/dev/rmt*.2

Yes

Yes

N/A

No

No

Special file name

26

IBM Tape Device Drivers Installation and Users Guide

Table 4. Special files for tape devices (continued)


Rewind on
Close (Note
1)

Retension
on Open
(Note 2)

Bytes per
Inch (Note
3)

Trailer Label

Unload on
Close

/dev/rmt*.3

No

Yes

N/A

No

No

/dev/rmt*.4

Yes

No

N/A

No

No

/dev/rmt*.5

No

No

N/A

No

No

/dev/rmt*.6

Yes

Yes

N/A

No

No

/dev/rmt*.7

No

Yes

N/A

No

No

/dev/rmt*.10
(Note 4)

No

No

N/A

No

No

/dev/rmt*.20

Yes

No

N/A

No

Yes

/dev/rmt*.40

Yes

No

N/A

Yes

No

/dev/rmt*.41

No

No

N/A

Yes

No

/dev/rmt*.60

Yes

No

N/A

Yes

Yes

/dev/rmt*.null
(Note 5)

Yes

No

N/A

No

No

/dev/rmt*.smc
(Note 6)

N/A

N/A

N/A

N/A

N/A

Special file name

Note:
1. The Rewind on Close special files write filemarks under certain conditions before
rewinding.
2. The Retensions on Open special files rewind the tape on open only. Retensioning is not
done because these tape products complete the retension operation automatically when
needed.
3. The Bytes per Inch options are ignored for the tape devices that are supported by this
driver. The density selection is automatic.
4. The rmt*.10 file bypasses normal close processing, and the tape is left at the current
position.
5. The rmt*.null file is a pseudo device similar to the /dev/null AIX special file. The
input/output control (ioctl) calls can be issued to this file without a real device that is
attached to it, and the device driver returns a successful completion. Read and write
system calls return the requested number of bytes. This file can be used for application
development or debugging problems.
6. The rmt*.smc file can be opened independently of the other tape special files.

Special files for Medium Changer devices


After the driver is installed and a medium changer device is configured and made
available for use, access to the robotic device is provided through the smc* special
file in the /dev directory.
Table 5 on page 28 shows the attributes of the special file. The asterisk (*)
represents a number that is assigned to a particular device (such as smc0). The
term smc is used for a SCSI medium changer device. The smc* special file
provides a path for issuing commands to control the medium changer robotic
device. For information, refer to Table 5 on page 28.

Chapter 2. AIX Tape and Medium Changer device driver

27

Table 5. Special files for Medium Changer devices


Special file name

Description

/dev/smc*

Access to the medium changer robotic device

/dev/smc*.null

Pseudo medium changer device

Note: The smc*.null file is a pseudo device similar to the /dev/null AIX special file. The
commands can be issued to this file without a real device that is attached to it, and the
device driver returns a successful completion. This file can be used for application
development or debugging problems.

The file descriptor that results from opening the smc special file does not support
the following operations:
v Read
v Write
v Commands that are designed for a tape device

Persistent Naming Support


Persistent naming support is used to ensure that attached devices are always
configured with the same logical name based on the SCSI ID, LUN ID, and host
bus adapter (HBA), even when the system is rebooted.
When the AIX operating system is booted, the HBA runs a device discovery and
assigns a default logical name to each device found in a sequential order. If there
are three tape drives attached to a parallel SCSI adapter, each with a LUN ID of 0
and a target address of 0, 1, and 2, the HBA initially configures them as Available
with the following logical names.
rmt0
rmt1
rmt2

target 0, lun 0
target 1, lun 0
target 2, lun 0

Available
Available
Available

Run the following commands before the machine is rebooted.


- rmdev -dl rmt1
- rmdev -dl rmt2

On the next reboot, if the existing rmt1 target 1 device is powered off or not
connected, the HBA initially configures two devices as Available with the following
logical names:
rmt0
rmt1

target 0, lun 0
target 2, lun 0

Available
Available

If the previous rmt1 target 1 device is powered on after reboot and the cfgmgr
command is run, the HBA configures the device as rmt2 instead of rmt1.
rmt2

target 1, lun 0

Available

This is one example, but there are other cases where the logical names of devices
could change when the system is rebooted. For applications that need a consistent
naming convention for all attached devices, it is accomplished with persistent
naming support by defining a unique logical name (other than the AIX default
names) that are associated with the specific SCSI ID, LUN ID, and HBA that the
device is connected to.

28

IBM Tape Device Drivers Installation and Users Guide

Changing the logical name after initial boot


The logical name of a device can be changed after an initial boot and configured.
This procedure can be done by using the SMIT menu or the chdev command from
a script or command line.
For example, a default rmt0 logical name for a tape drive can be changed to rmt-0,
tape0, or any descriptive name wanted. In this example, if the three tape drives are
changed to rmt-0, rmt-1, and rmt-2, and the system is then rebooted with rmt-1
powered off, the HBA detects that unique names are predefined for the attached
devices, and the HBA uses those names. In this case, the devices configure as
follows:
rmt-0
rmt-1
rmt-2

target 0, lun 0
target 1, lun 0
target 2, lun 0

Available
Defined
Available

Since rmt-1 is not detected by the HBA but is predefined at the SCSI ID and LUN
ID, it remains in the defined state and is not configured for use. But, the next rmt-2
tape drive configures as the same name at the same location after reboot.

Changing the logical name with SMIT


To change the logical name by using SMIT, complete the following steps:
1. Run SMIT from a command line and select Devices.
2.
3.
4.
5.
6.

Select Tape Drive.


Select Change/Show Characteristics of a Tape Drive.
Select the logical device to be changed from the list displayed.
In the New Logical Name field, enter a non-AIX default logical name.
Press Enter to process the change.

Changing the logical name with the chdev command


The logical name of a device can be changed by using the chdev command. For
example, to change the logical name of the device from rmt0 to rmt-0, run
chdev l rmt0 a new_name=rmt-0

The output of this command displays


rmt0 changed

Note:
v When path failover is enabled, if you change the logical name for either a
primary or alternate device, only the individual device name changes.
v Follow the naming convention whenever you run mksysb, bosboot:
The prefix name of "rmt" cannot be changed.
A sequence number must be a positive integer. The smallest sequence
number is 0.
The prefix name cannot contain non-numerical characters. For example,
rmt1_rescu is not an acceptable prefix name.
When a device instance logical name is generated, the SMIT tool
automatically assigns the next available sequence number (relative to a

Chapter 2. AIX Tape and Medium Changer device driver

29

specific prefix name). The next available sequence number is defined as


the smallest sequence number for a particular prefix name that is not
yet allocated.

Control Path failover support for tape libraries


Note: The library control path failover feature code must be installed before
enabling the path failover support in the Atape device driver. Refer to
Automatic failover on page 1 for what feature codes might be required for
your machine type.
The Atape device driver path failover support configures multiple physical control
paths to the same logical library within the device driver. It also provides
automatic failover to an alternate control path when a permanent error occurs on
one path. This support is transparent to the running application.

Configuring and unconfiguring path failover support


Path failover support is not enabled automatically when the device driver is
installed. It must be configured initially on each logical device after installation.
When path failover support is enabled for a logical device, it remains set until the
device is deleted or the support is unconfigured. The alternate path failover setting
is retained even if the system is rebooted.
To enable or disable the support on a single logical device, use the SMIT menu to
Change/Show Characteristics of a Tape Drive, select the logical device to change
such as smc0, smc1, then select Yes or No for Enable Path Failover Support. The
support can also be enabled or disabled by using the chdev command, for example,
chdev
chdev
chdev
chdev

-l
-l
-l
-l

smc0
smc1
smc0
smc1

-aalt_pathing=yes
-aalt_pathing=yes
-aalt_pathing=no
-aalt_pathing=no

Primary and alternative paths


When the device driver configures a logical device with path failover support
enabled, the first device that is configured always becomes the primary path. On
SCSI attached devices, -P is appended to the location field. On Fibre attached
devices, -PRI is appended to the location field of the device.
When a second logical device is configured with path failover support enabled for
the same physical device, it configures as an alternative path. On SCSI attached
devices, -A is appended to the location field. On Fibre attached devices, -ALT is
appended to the location field of the device.
A third logical device is also configured as an alternative path with either -A or
-ALT appended, and so on. The device driver supports up to 16 physical paths for
a single device.
The labeling of a logical device as either a primary or alternative path is for
information only, to
1. Be able to identify the actual number of physical devices that are configured on
the system and a specific logical device that is associated with them. Only one

30

IBM Tape Device Drivers Installation and Users Guide

logical device is labeled as the primary path for each physical device. However,
many (multiple) logical devices can be labeled as an alternative path for the
same devices.
2. Provide information about which logical devices configured on the system have
path failover support enabled.

Querying primary and alternative path configurations


You can see the primary and alternative path configuration for all devices with the
lsdev command. Two or more logical devices can be configured for a single
physical device, but the first device that is configured is labeled the primary
device. All other logical devices that are configured after the first device are
labeled as alternative devices. To see this information, run the lsdev -Cc tape
command and look at the location field in the data. Run the following command,
lsdev -Cc tape | grep P

For example, you can easily determine how many physical devices are configured
with path failover support.
Note: Show the primary and alternative path configuration for any device by
using tape diagnostic and utility functions. Refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Configuring and unconfiguring primary and alternative


devices
Logical devices that are configured as alternative paths can be unconfigured and
reconfigured at any time after the initial configuration is run. Unconfiguring an
alternative path device removes that device from the primary device path list,
removes the -A or -ALT appended to the location field, and changes the device to
the Defined state. The primary and any other alternative devices are still available.
Likewise, configuring a new alternative path device or reconfiguring an existing
one in the Defined state adds that device to the primary device path list, appends
-A or -ALT to the location field, and makes the device available.
Logical devices that are configured as primary paths can also be unconfigured and
reconfigured at any time after initial configuration is run. However, the operation
is different for a primary device. When a primary device is unconfigured, the
following events occur.
1. All alternative devices are unconfigured as described previously.
2. The primary device is unconfigured.
3. The -P or -PRI appended to the location field is removed.
4. The device is changed to the Defined state.
5. All alternative devices that were unconfigured are reconfigured. The first device
that is reconfigured becomes the new primary device. All remaining alternative
devices are reconfigured as alternative paths.
These methods can unconfigure and reconfigure physical devices on the system
when device connections or addressing changes are made.

Chapter 2. AIX Tape and Medium Changer device driver

31

Data Path failover and load balancing support for tape drives
Note:
1. Some devices require a path failover feature code that is installed before
the path failover support is enabled in the Atape device driver. Refer to
Automatic failover on page 1 for what feature code might be required
for your machine type.
2. DPF keys do not need to be added if you are running the latest drive
code on Ultrium 3 and Ultrium 4 drives.
3. This function is not supported for devices that are attached through an
IBM San Data Gateway or on the IBM Virtualization Engine TS7510.
4. The AIX operating system supports only a static configuration of devices,
which also applies to the Path Failover and Failover Support. When
devices are initially configured at a specific SCSI ID and physical
connection (drive port, host bus adapter, and switch number/port, if
applicable) and in the Available state, changing the physical device
address/connection without either rebooting or unconfiguring and
reconfiguring the devices has unpredictable results and is not supported.

Installing Data Path failover license key


Use the following command line script to query, add, or delete license keys for this
feature before the path failover feature is enabled as described below. The key is a
16-digit hexadecimal value, for example, 1234567890abcdef.
All key values A-F must be entered in lowercase letters as a-f.
v Query installed keys: dpf_keys
v Install a license key: dpf_keys -a key
v Delete a license key: dpf_keys -d key

Configuring and unconfiguring path failover support


Path failover support is not enabled automatically when the device driver is
installed. It must be configured initially on each logical device after installation.
When path failover support is enabled for a logical device, it remains set until the
device is deleted or the support is unconfigured. The path failover setting is
retained even if the system is rebooted.
Path failover support can be enabled on all configured devices at one time, or it
can be enabled or disabled selectively by logical device. It might be desirable at
times to configure some, but not all, logical paths to a device with the support
enabled.
To enable the support globally on all currently configured devices, run the
command
/usr/lpp/Atape/instAtape -a

This action unconfigures all devices that have path failover set to No, and
reconfigures all devices, setting path failover to Yes.

32

IBM Tape Device Drivers Installation and Users Guide

To enable or disable the support on a single logical device, use the SMIT menu to
Change/Show Characteristics of a Tape Drive, then select Yes or No for Enable
Path Failover Support. The support can also be enabled or disabled by using the
chdev command, for example:
chdev -l rmt0 -aalt_pathing=yes
chdev -l rmt0 -aalt_pathing=no

Primary and alternative paths


When the device driver configures a logical device with path failover support
enabled, the first device that is configured always becomes the primary path and
PRI is appended to the location field of the device. When a second logical device is
configured with path failover support enabled for the same physical device, it
configures as an alternative path and ALT is appended to the location field. A third
logical device is configured as the next alternative path with ALT appended, and
so on. The device driver supports up to 16 physical paths for a single device.
For example, if rmt0 is configured first, then rmt1, the lsdev -Cc tape command
output is similar to the following command.
rmt0 Available 20-60-01-PRI IBM 3590 Tape Drive and Medium Changer (FCP)
rmt1 Available 30-68-01-ALT IBM 3590 Tape Drive and Medium Changer (FCP)

If rmt1 is configured first, then rmt0, the command output is similar to the
following.
rmt0 Available 20-60-01-ALT IBM 3590 Tape Drive and Medium Changer (FCP)
rmt1 Available 30-68-01-PRI IBM 3590 Tape Drive and Medium Changer (FCP)

The labeling of a logical device as either a primary or alternative path is for


information only, to
1. Identify the actual number of physical devices that are configured on the
system and a specific logical device that is associated with them. Only one
logical device is labeled the primary path for each physical device. However,
many (multiple) logical devices can be labeled as an alternative path for the
same devices.
2. Provide information about which logical devices configured on the system have
path failover support enabled.

Querying primary and alternative path configuration


You can see the primary and alternative path configuration for all devices with the
lsdev command. Two or more logical devices might be configured for a single
physical device, but the first device that is configured is labeled the primary
device. All other logical devices that are configured after the first device are
labeled as alternative devices.
To see this information, run the lsdev -Cc tape command and look at the location
field in the data. By running lsdev -Cc tape | grep PRI, for example, you can
easily determine how many physical devices on the RS/6000 or System p (also
known as pSeries) server are configured with path failover support.

Chapter 2. AIX Tape and Medium Changer device driver

33

Configuring and unconfiguring primary and alternative


devices
Logical devices that are configured as alternative paths can be unconfigured and
reconfigured at any time after the initial configuration is run. Unconfiguring an
alternative path device removes that device from the primary device path list,
removes the ALT appended to the location field, and changes the device to the
Defined state. The primary and any other alternative devices are still available.
Likewise, configuring a new alternative path device or reconfiguring an existing
one in the Defined state adds that device to the primary device path list, appends
ALT to the location field, and makes the device available.
Logical devices that are configured as primary paths can also be unconfigured and
reconfigured at any time after initial configuration is run. However, the operation
is different for a primary device. When a primary device is unconfigured, the
following events occur.
1. All alternative devices are unconfigured as described previously.
2. The primary device is unconfigured.
3. The PRI appended to the location field is removed.
4. The device is changed to the Defined state.
5. All alternative devices that were unconfigured are reconfigured. The first device
that is reconfigured becomes the new primary device. All remaining alternative
devices are reconfigured as alternative paths.
These methods unconfigure and reconfigure physical devices on the system when
device connections or addressing changes are made.

System-managed encryption
Device driver configuration
System-managed encryption can be set on a specific tape drive by using the
standard SMIT panels to Change/Show Characteristics of a tape device or the
command line chdev command. There are two new attributes added for encryption.
sys_encryption yes/no
wrt_encryption off/on/custom

Use System Encryption FCP Proxy Manager


System Encryption for Write Commands at BOP

The sys_encryption attribute enables device driver system-managed encryption for


a tape drive by setting the value to yes.
The wrt_encryption attribute controls whether the device driver can set the tape
drive to encryption enabled for write commands. When set to off, the tape drive
uses encryption for read operations; write operations do not use encryption. When
set to on, the tape drive uses encryption for both read/write operations. When set
to custom, the device driver does not modify current tape drive setting. The
custom setting is intended for applications that use system-managed encryption to
control write encryption without device driver intervention.
Note: If wrt_encryption is set to on, an application cannot open a tape drive by
using the append mode.

34

IBM Tape Device Drivers Installation and Users Guide

Querying tape drive configuration


Querying the tape drive configuration is a tape diagnostic and utility function.
Refer to Chapter 8, IBM Tape Diagnostic Tool (ITDT), on page 211.

Testing data encryption configuration and connectivity


A data encryption test is available to validate the ibmekm.conf file server entries
and test tape drive to server connectivity operations.
This test is a tape diagnostic and utility function. Refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Error logging
Encryption errors are logged along with other tape operation errors by using the
standard TAPE_ERR1 Template Tape Operation Error with associated sense data
in the detail data.
An encryption failure is indicated when the asc/ascq in the sense data is EFxx or
EExx. Refer to the tape drive hardware reference for information on the asc/ascq
being reported. The asc/ascq can be found in the first column of the second row in
detail sense data. For example,
Detail Data
SENSE DATA
0A00 0000 5A08
EF11 FF02 D105
0000 0000 0000
2020 2000 0041
0000 0000 0000

25FF
0000
FFFF
4A00
0000

0000
0009
FF00
0000
0000

00FF
0191
0000
0000
0000

FF00
0002
FFF0
0000
0000

0000
0000
B7E3
0000
0000

0000
0000
0001
0000
0000

0000
0A00
2127
0000
0000

F000
0000
0000
0000
0000

0600
0000
0000
0000
0000

0000
0000
0000
0000
0000

1458
0000
0000
0000
0000

0000
0000
3930
0000

0000
0000
3220
0000

Field support information


When encryption failures require field support or development analysis, the
following data must be provided for a problem on a specific tape drive from the
machine (rmt1 for example) for the device driver. Tape drive dumps and EKM
server logs might be needed in addition to this information.
errpt a > errpt.rmt1
lsattr -El rmt1 > lsattr.rmtl
All Atape files in /var/adm/ras/Atape*

Problem determination
A set of tools is provided with the device driver to determine whether the device
driver and the tape device are functioning correctly. The standard AIX interface is
provided for problem determination.

Dump support
Dump support is provided through the dump entry point in the driver. Refer to
appropriate AIX manuals for a description of how to use the dump devices and
how to read the dump data.

Chapter 2. AIX Tape and Medium Changer device driver

35

Dump device commands


To list the current dump devices, enter the following command,
sysdumpdev -l

To establish the rmt1 tape device as a secondary dump device, enter the following
command,
sysdumpdev -s /dev/rmt1

To run a dump operation, use the sysdumpstart command. To send the dump data
to the secondary dump device, enter the following command:
sysdumpstart -s

Note: This command stops the system. Use the sync command to ensure that the
cache is flushed before the sysdumpstart -s command is issued.
To list the last dump data, enter the following command,
sysdumpdev -z

After the dump data is placed on the tape, copy it to a file on the disk before the
crash command is used to process it. For example,
dd if=/dev/rmt1 of=tapedump1 ibs=4096 obs=512
crash tapedump1

Note: The ibs value is the input block size.


If the block size of the tape device is larger than the block size sent during the
dump process, the dump operation fails. Set the block size to zero on the tape
device and experiment with the ibs value for the dd command.

Device and volume information logging


An optional logging utility is provided to log the information about the device and
the media. The information is extensive for some devices and limited for other
devices. If set to On, the logging facility gathers all available information through
the SCSI Log Sense command.
This process is a separate facility from error logging. Error logging is routed to the
system error log. Device information logging is sent to a separate file.
The following parameters control this utility,
v Logging
v Maximum size of the log file
v Volume ID for logging
Refer to Tape drive, media, and device driver parameters on page 19 for a
description of these parameters.
Each time the rewind and unload sequence occurs or the STIOC_LOG_SENSE ioctl
command is issued, an entry is added to the log. Each time a new cartridge is
loaded, the values in the device log buffers are reset with the Log Sense command.
The log data is gathered on a per-volume basis.

36

IBM Tape Device Drivers Installation and Users Guide

Log file
The data is logged in the /usr/adm/ras directory. The file name is dependent on
each device; therefore, each device has a separate log. An example of the rmt1
device file is
/usr/adm/ras/Atape.rmt1.log

The files are in binary format. Each entry has a header followed by the raw Log
Sense pages as defined for a particular device.
The first log page is always page 0x00. This page, as defined in the SCSI-2 ANSI
specification, contains all pages that the device supports. Page 0x00 is followed by
all pages that are specified in page 0x00. The format of each following page is
defined in the SCSI specification and the device manual.

Tape log utility


A tape log utility is installed with the tapelog device driver that displays the
contents of the log file in ASCII text. The log pages are shown as hexadecimal
values in dump format.
The syntax for the tape log utility is
tapelog -l Name [-d] or tapelog -f File [-d]

Note:
1. Name is the logical name of the device (such as rmt0).
2. File is the name of a log file (such as Atape.rmt0.log).
3. The -d parameter, if used, deletes the log file for the specified device.
The contents of the log file are displayed as standard output. To save the log in a
file, use the AIX redirection function. For example,
tapelog -l rmt0 > rmt0.log

Reservation conflict logging


When the device driver receives a reservation conflict during open or after the
device is opened, it logs a reservation conflict in the AIX error log. Before it logs
the error, the device driver issues a Persistent Reserve In command to determine
whether a SCSI Persistent Reservation is active on the reserving host to get the
reserving host initiator WWPN (worldwide port name) and reserve key. If
successful, the device driver logs this information as follows,
Reserving host key xxxxxxxx WWPN xxxxxxxx

Where the first xxxxxxxx is the actual reserve key, and the second xxxxxxxx is the
reserving host initiator WWPN.
After the reserving host WWPN is initially logged, subsequent reservation conflicts
from the same reserving host WWPN are not logged. This action prevents multiple
entries in the error log until either the reserving host WWPN is different from the
one initially logged or the device driver reserved the device and another
reservation conflict occurs.
If the Persistent Reserve In command fails, the detail data contains the following
entry with the errno from the failing Persistent Reserve In command.
Chapter 2. AIX Tape and Medium Changer device driver

37

Unable to obtain reserving host information, errno x

The possible errno values are


v ENOMEM - Device driver cannot obtain memory to run the command
v EINVAL - Device has a Persistent Reservation but does not support the
Persistent Reserve In service action
v EBUSY - Device failed the command with reservation conflict and has an SCSI-2
Reserve active
v EIO - Unknown I/O failure occurred

Error logging
The device driver provides logging to the AIX system error log for various errors.
The error log can be viewed for specific devices by using the Error Log Analysis
utility that is provided with the tape drive service aids. Refer to Error Log
Analysis on page 44. The error log can also be viewed by using the smit or the
errpt command.

Error log templates


The error log templates the device driver uses follow the same format as the
default AIX tape error log entries. Each error log entry is identified by an error
label and contains detail data that is associated with the type of error. The
following items describe the error labels and detail data for the templates that are
used for logging tape device, media, and SCSI adapter-related errors in the AIX
system error log.

Error labels
Errors are logged with an associated error label and error ID. The error label
indicates the basic type of error.
v TAPE_ERR1
Tape media error
v TAPE_ERR2
Tape hardware error
v TAPE_ERR4
SCSI Adapter detected error
v TAPE_ERR5
Unknown error
v RECOVERED_ERROR
Temporary tape hardware or media error
v SIM_MIM_RECORD_3590
3590 Service/Media Information Message (Log Page X '31')
v TAPE_SIM_MIM_RECORD
Tape drive Service/Media Information Message (Log Page X '31')
v DEV_DUMP RETRIEVED
Device dump retrieved
v TAPE_DRIVE_CLEANING
Tape drive needs cleaning
v RESERVE_CONFLICT

38

IBM Tape Device Drivers Installation and Users Guide

Reservation conflict

Detail data
Detail data is logged with the associated error that identifies the cause of the error.
Detail data for the SIM_MIM_RECORD_3590 or TAPE_SIM_MIM_RECORD entries
contain the raw data from Log Sense Page 31. Refer to the hardware reference
manual for the format of this entry. All other error log entries use the following
format for detail data:
Detail Data
SENSE DATA
aabb xxxx ccdd eeee eeee eeee eeee eeee ffgg hhxx ssss ssss ssss ssss ssss
ssss ssss ssss ssss ssss ....

aa

Length of the command descriptor block (CDB).

bb

SCSI target address.

xx

Unused or reserved.

cc

Start of CDB, cc is the operation code (byte 0).

dd

Logical unit (byte 1) in the CDB.

ee

Bytes 2 - 12 in the CDB.

ff

Status validity field. If this field is 01, then a SCSI error was reported, and
byte gg indicates the type of error. If this field is 02, then an adapter error
was reported, and byte hh indicates the type of error.

gg

This byte indicates the type of SCSI error that occurred.


v 02 CHECK CONDITION - Device reported a check condition.
v 08 BUSY STATUS - Target is busy.
v 18 RESERVATION CONFLICT - Target is reserved to another initiator.
v 22 COMMAND TERMINATED - Device terminated the command.
v 28 QUEUE FULL - Device command queue is full.

hh

This byte indicates the type of adapter error that occurred. For parallel
SCSI adapters, this byte is the general_card status code as defined in
/usr/include/sys/scsi.h
v 01 HOST IO BUS ERROR - Host I/O bus error during data transfer.
v 02 SCSI BUS FAULT - SCSI bus protocol or hardware error.
v 04 COMMAND TIMEOUT - Command timed out before completion.
v 08 NO DEVICE RESPONSE - Target did not respond to selection phase.
v 10 ADAPTER HARDWARE FAILURE - Adapter indicated a hardware
failure.
v 20 ADAPTER SOFTWARE FAILURE - Adapter indicated a microcode
failure.
v 40 FUSE OR TERMINAL PWR - Blown terminator fuse or bad
termination.
v 80 SCSI BUS RESET - Adapter indicated that SCSI bus was reset.
For FCP or SAS adapters, this byte is the adapter_status code as defined in
/usr/include/sys/scsi_buf.h
v 01 HOST IO BUS ERROR - Host I/O bus error during data transfer.
v 02 TRANSPORT FAULT - Failure in the transport layer.
v 03 COMMAND TIMEOUT - Command timed out before completion.
Chapter 2. AIX Tape and Medium Changer device driver

39

v 04 NO DEVICE RESPONSE - Target did not respond to attempts to


select it.
v 05 ADAPTER HARDWARE FAILURE - Adapter indicated a hardware
failure.
v 06 ADAPTER SOFTWARE FAILURE - Adapter indicated a microcode
failure.
v 07 WW NAME CHANGE - Adapter detected a new worldwide name for
the device.
v 08 FUSE OR TERMINAL PWR - Blown terminator fuse or bad
termination.
v 09 TRANSPORT RESET - Adapter detected an external SCSI bus reset.
v 0A TRANSPORT BUSY - The transport layer is busy.
v 0B TRANSPORT DEAD - The transport layer is inoperative.
ss

If byte gg indicates a check condition, the ss byte is the sense data from the
device. Refer to the appropriate device reference manual for the specific
format and content of these bytes.

Automatic dump facility


The device driver provides an automatic dump facility for devices that support
reading a dump and indicating when a dump is available in device sense data.
Whenever a check condition occurs and the sense data indicates that a dump is
available, the device driver reads the dump from the device and stores it in the
/var/adm/ras directory. A maximum of five dumps for each device are stored in
this directory as
Atape.rmtx.dump1
Atape.rmtx.dump2
Atape.rmtx.dump3

Note: X is the device number, for example, rmt0.


When the device is first configured, the dump name is set to dump1. If more than
three dumps occur, the driver starts over at dump1; therefore the last three dumps
are always kept.

Dynamic Runtime Attributes


Field issues can occur where customers must know which initiator on a host is
holding a reservation in a drive or preventing the media from being unloaded.
Also, they must correlate which special file name is used for the drive (such as
rmt2). Sometimes this issue occurs over transport bridges and translators, thus
losing any transport identifiers to help this effort. LTO5, 3592 E07, 3592 E08, and
later physical tape drives support attributes set to the drive dynamically by a host.
This function is called Dynamic Runtime Attributes (DRA). Atape supports the
feature, starting from 12.5.9.0.

The feature is enabled by default. The drive attributes on the host are set during
the open, close, device reset, and data path change only. So, it does not have
impact on the tape and system performance. The error is ignored and is not
returned to application, when the information failed to send. However, a device
attribute named as "host_attributes" is available to disable the DRA feature, when
Atape runs with the virtual tape library for which the feature is not supported.

40

IBM Tape Device Drivers Installation and Users Guide

Run the lsattr command to display the attribute of host_attributes setup.


On LTO tape drive:
# lsattr -El rmt1
host_attributes yes

Host Dynamic Runtime Attribute (LTO-5 and later only) True

On 3592 tape drive:


# lsattr -El rmt4
host_attributes yes

Host Dynamic Runtime Attribute for 3592-E07 and later True

To modify the attribute of "host_attribute", run the chdev command.


# chdev -lrmt1 -a host_attributes=no
rmt1 changed

Trace facility
The AIX trace facility is supported for the device driver. The trace event is
identified with a hookword. The hookword that is used by the device driver is 326.
The trace can be initiated at any time before an operation on a tape device.
Enter the following AIX command to start the trace.
trace -a -j 326

This command starts the trace in the background and collects only the trace events
with the 326 hookword (Atape device driver).
Enter the following AIX command to stop the trace.
trcstop

This command stops the trace after the tape operations are run.
Enter the following AIX command to view the trace.
trcrpt > trace.out

This command formats the trace output into a readable form and places it into a
file for viewing.

Atape System Trace (ATRC) utility


The atrc trace utility is also installed with the device driver to start, stop, and
format a device driver trace. To start the trace, enter the atrc command. To stop
and format the trace, enter the atrc command again. The trace is formatted to an
atrc.out AIX file in the current directory.

Component tracing
Later releases of AIX 5.3 and above support component tracing. Unlike system
tracing that must be started and stopped, component tracing by default is on all
the time and runs continually.
To determine whether component tracing is available, run the command ctctrl -q
to display a list of supported components with their default settings. You must
have root authority to run this command. Refer to the AIX ctctrl man page for a
complete description of the ctctrl command and parameters.
Chapter 2. AIX Tape and Medium Changer device driver

41

To dump and format the current component trace to a file (for example, actrc.out)
into the current directory, run the following commands.
ctctrl -D -c Atape
trcrpt -l Atape -o actrc.out

The Atape component trace can also be retrieved from a system dump. This action
eliminates the need to start the Atape system trace before a system dump or to
re-create an AIX system dump when a system trace is not running. The AIX system
dump is normally stored in the /var/adm/ras directory as a vmcore.x.BZ file, where
x is a dump number 1, 2, and so on.
To retrieve and format the Atape component trace from a dump file (for example,
vmcore.1.BZ) to a file (for example, actrc.dump) into the current directory, run the
following commands.
dmpuncompress /var/adm/ras/vmcore.1.BZ
trcdead -c /var/adm/ras/vmcore.1
trcrpt -l Atape -o actrc.dump

Atape Component Trace (ACTRC) utility


The actrc component trace utility is also installed with the device driver to dump
and format the current Atape component trace. To dump and format the
component trace, run the command actrc. The trace is formatted to an actrc.out
file in the current directory.

Tape drive service aids


The service aids described in the following sections are accessible through the AIX
diagnostic subsystem by using the AIX diag command and in the Task Selection
menu by selecting IBM Tape Drive Service Aids. Refer to Tape drive service aids
details.
Tape drive service aids are also available by using the Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Tape drive service aids details


The following service aid utilities are installed with the device driver:
v
v
v
v
v
v

Force Microcode Dump


Read Dump
Microcode Load
Error Log Analysis
Reset Drive
Create an FMR Tape

Force Microcode Dump


This utility forces a dump operation on the tape drive. After the dump operation is
completed, the dump data can be transferred from the tape drive by using the
Read Dump utility.
To access this utility 1. Open the Service Aids window.

42

IBM Tape Device Drivers Installation and Users Guide

2. Select Force Microcode Dump from the IBM Tape Drive Service Aids window,
then press Enter.
3. Select the device from the IBM Tape Drive Selection window, then press Enter.
The Force Microcode Dump operation starts, and a window opens when the
operation is completed.

Read Dump
This utility transfers the dump data from the device to a file, a diskette, or a tape
cartridge.
To access this utility 1. Open the Service Aids window.
2. Select Read Dump from the IBM Tape Drive Service Aids window, then press
Enter.
3. Select the device from the IBM Tape Drive Selection window, then press Enter.
4. Enter the destination file name or device in the Prompting for Destination
window. The default destination is the /dev/rfd0 diskette drive. To transfer the
dump data to a tape cartridge, enter the device name of the tape drive (for
example, /dev/rmt0). To transfer the dump data to a file, enter the file name.
Press F7 to commit.
Note: On certain terminal types, it might be necessary to press Esc and the
number 7 instead of F7.
The Read Dump operation starts, and a window opens when the operation is
completed.

Microcode Load
This utility downloads microcode to the device from a file or a diskette (AIX
format only).
Note: To download the microcode from a DOS diskette, you must first use the AIX
dosread command to transfer the file from the DOS diskette to the AIX file.
Then, you can use the Microcode Load utility to download the AIX file to
the tape drive.
To access this utility 1. Open the Service Aids window.
2. Select Microcode Load from the IBM Tape Drive Service Aids window, then
press Enter.
3. Select the device from the IBM IBMTape Drive Selection window, then press
Enter.
4. Enter the source file name or device on the Prompting for Source File window.
The default source is the /dev/rfd0 diskette drive. To load from a file, enter the
file name. Press F7 to commit.
Note: On certain terminal types, it might be necessary to press Esc and the
number 7 instead of F7.
5. If the current microcode on a tape drive is Federal Information Processing
Standard (FIPS) code, then a window opens and displays the following
message.

Chapter 2. AIX Tape and Medium Changer device driver

43

Warning: The drive is currently using FIPS code. Press Enter to


continue with downloading new drive code.

If you do not want to download the new code, press either F3 to cancel or F10
to exit without downloading new code. Otherwise, press Enter to continue with
the download code procedure.
The Microcode Load operation starts, and a window opens when the operation is
completed.

Error Log Analysis


This utility displays and analyzes the system error log entries for a specific tape
drive and can be used for problem determination. The type of error, the SCSI
command, and the sense data (if applicable) are displayed for each entry in the
error log (one screen at a time).
To access this utility 1. Open the Service Aids window.
2. Select Error Log Analysis from the IBM Tape Drive Service Aids window, then
press Enter.
3. Select the device from the IBM Tape Drive Selection window, then press Enter.
4. If entries are listed in the error log for the selected device, then the first entry is
displayed. Press Enter to display the next entry.
5. After all entries are displayed, a window opens, and the operation is
completed.

Reset Drive
This utility resets the tape drive.
To access this utility 1. Open the Service Aids window.
2. Select Reset Drive from the IBM Tape Drive Service Aids window, then press
Enter.
3. Select the device from the IBM IBMTape Drive Selection window, then press
Enter.
The Reset Drive operation starts, and a window opens when the operation is
completed.

Create an FMR Tape


This utility creates a field microcode replacement (FMR) cartridge tape by using
the loaded functional microcode in the tape drive.
To access this utility 1. Open the Service Aids window.
2. Select Create an FMR Tape from the IBM Tape Drive Service Aids window,
then press Enter.
3. Select the device from the IBMTape Drive Selection window, then press Enter.
The Create an FMR Tape operation starts, and a window opens when the
operation is completed.

44

IBM Tape Device Drivers Installation and Users Guide

Performance considerations
This chapter describes the parameters and issues that can affect the perceived
performance of the tape drive. In general, AIX applications that operate at a file
level to move data between disk storage devices and tape do not use the full
capabilities of a high end tape device. The goal of this discussion is to give an
overview of the data path components that are involved in moving data between
disk storage devices and tape. The following chapter describes basic techniques
and common utilities in a specific environment that can be used to understand
how a device is performing. Performance issues that are encountered by advanced
application developers are beyond the scope of this document.
v Refer to the hardware reference for the specific device for performance
specifications.
v Refer to the application documentation for information on device-specific
application configuration.
v Refer to the operating system documentation for information on disk storage
device striping and other techniques for improving file system performance.

Data path
The simplified model in Figure 9 shows the components that are involved in the
data path for moving data at a file level between disk storage devices and tape.
Performance analysis must be approached by determining which component of the
data path impacts performance. Typically, a performance problem can be isolated
by looking at one leg of the data path at a time. The goal of this analysis is to
confirm that the tape data path is not impacting the performance adversely.

Figure 9. Data path for AIX device driver (Atape)

Common AIX utilities


The most commonly reported cause for poor tape performance is the use of small
block sizes or the modification of the installation defaults for the tape device.
Note: The device parameters must not be changed from the defaults for most
applications.
The following guidelines typically result in good tape path performance for use
with AIX utilities:
1. Hardware compression must be enabled for maximum performance if the data
sent to the device is uncompressed.

Chapter 2. AIX Tape and Medium Changer device driver

45

2. The block_size parameter must be set to variable (block_size=0) and command


or application parameters that are specified to a block size appropriate for the
device.
3. Block sizes of 128 KB or greater must be used to improve performance.

AIX iostat utility for tape performance


In releases of AIX 5.3 and earlier, the AIX iostat utility supports tape performance
statistics in addition to other supported devices (such as disk). To determine
whether the iostat utility supports the configured tape drives, run the command
iostat -p. If the configured tape drives are supported, a list of configured tape
drives are displayed with the statistics listed for each drive. Refer to the AIX iostat
man page for a complete description of the iostat command and parameters.
When the Data Path Failover feature is used, only the primary path for the tape
drive is listed. The statistics apply to both the primary and alternative paths that
are used.

Before Support is called


System performance tuning is not a support responsibility. If tests indicate that raw
tape performance is below specifications, record the exact failing command. Then,
collect the output from the commands in Table 6 before support is contacted.
Table 6. Error description

46

Information

Command

Configuration

lscfg -v

Device parameters

lsattr -E -l rmtN

Error log. Call hardware support if errors


are found for TAPE_ERR* or SCSI* error
labels.

errpt -a

Driver version

lslpp -l Atape.driver

Trace of failing command

Refer to Trace facility on page 41

IBM Tape Device Drivers Installation and Users Guide

Chapter 3. HP-UX Tape and Medium Changer device driver


This chapter provides an overview of the IBM Tape and Medium Changer device
driver for HP-UX that provides support for IBM tape drives and medium changer
devices.
For tape diagnostic and utility functions refer to Chapter 8, IBM Tape Diagnostic
Tool (ITDT), on page 211.

Purpose
This device driver product provides SCSI-3 attachment for the IBM tape devices to
selected Hewlett-Packard Precision Bus and PCI-based operating systems that run
HP-UX 11i v2, and 11i v3.
The HP-UX installed name of this device driver is Advanced Tape Device Driver
(ATDD). ATDD is used throughout this chapter to identify this driver.
ATDD is designed specifically to take advantage of the features that are provided
by the IBM tape devices (refer to Hardware requirements on page xvii). The goal
is to give applications access to the functions required for basic operations (such as
backup and restore) and the advanced functions that are needed by full tape
management systems. Whenever possible, the device driver is designed to take
advantage of the IBM tape system features transparent to the application.

Data flow

Application
Program

ATDD
Device
Driver

SCSI or Fibre
Channel
Adapter
Device
Driver

IBM
Tape
Subsystem

a250104

Both data and commands flow between the application program and the tape
subsystem by way of the IBM Tape and Medium Changer device driver for HP-UX
(ATDD). Figure 10 shows the relationships between the IBM Tape and Medium
Changer device driver for HP-UX, the application program, the SCSI or Fibre
Channel adapter device driver, and the IBM tape subsystem.

Figure 10. Data flow for HP-UX device driver (ATDD)

Product requirements
ATDD implementation
ATDD is a set of device driver implementations for operation in the following
HP-UX operating system environments:
v HP PCI Bus - HP-UX 11i v1 (64 bit) - versions of this driver are identified by
levels ATDD 3.x.x.x.
Note: The 11i v1 driver is no longer currently supported. A stable version is
available on http://www.ibm.com/support/fixcentral.
Copyright IBM Corp. 2007, 2014

47

v HP PCI Bus - HP-UX 11i v2 (64-bit for Itanium 2) - versions of this driver are
identified by levels ATDD 5.5.x.x.
v HP PCI Bus - HP-UX 11i v2 (64-bit for PA-RISC) - versions of this driver are
identified by levels ATDD 5.6.x.x.
v HP PCI Bus - HP-UX 11i v3 (64-bit for Itanium 2) - versions of this driver are
identified by levels ATDD IA.6.x.x.x.
v HP PCI Bus - HP-UX 11i v3 (64-bit for PA-RISC) - versions of this driver are
identified by levels ATDD PA.6.x.x.x.

Hardware requirements
For current hardware requirements, refer to the Hardware requirements on page
xvii.
Note:
1. ATDD does not support tape devices that are attached to HSC/GSC bus
architectures.
2. For attachment of Enterprise Tape System 3590 and IBM Magstar MP
devices to HP rp8400 (formerly V-Class) platforms, a feedthrough SCSI
terminator, which attaches to the A4800A Host Bus Adapter, is required.
This feedthrough SCSI terminator is available as FC 9798 for Enterprise
Tape System 3590 and FC 5098 for the 3575 Tape Library Dataserver or
MP 3570 C model tape subsystem. Attach the male end of the
feedthrough SCSI terminator to the host adapter and connect the host
end of the standard FC 51xx SCSI cable to the feedthrough terminator.
Terminate the SCSI bus at the last device on the bus as usual.
3. The low-level FC-Tape protocol standard is not supported in the HP
A5158A HBA firmware and users must restrict their SAN configurations.
The jobs are aborted with HP-UX A5158A HBA configurations when
errors are detected in the SAN.
The HP A5158A host adapter is not compliant with the Fibre Channel
Protocol for SCSI, second version (FCP-2), dated 17 November 2000, a
draft that is proposed by the American National Standard of Accredited
Standards Committee (NCITS).
4. The HP A6826A HBAs need the QLogic firmware level B.11.11.02 or later.
If the adapter is directly connected to a 3592 without a switch, then the
topology on the drive port must be set to L-port.

Software requirements
For current software requirements, refer to the Software requirements on page
xvii.
Attention: To install ATDD in HP-UX 11i v3, some HP-UX patches must be
applied first on the system. For information, refer to the atdd.Readme file that is
downloaded with the driver.

Software interface to the device driver


The IBM Tape and Medium Changer device driver for HP-UX provides the
following standard HP-UX entry points for IBM tape systems:
Open

48

This entry point is driven by the open system function call.

IBM Tape Device Drivers Installation and Users Guide

Write

This entry point is driven by the write system function call.

Read

This entry point is driven by the read system function call.

Close

This entry point is driven explicitly by the close system function call and
implicitly by the operating system at program termination.

IOCTL
This entry point is driven by the input/output control (ioctl) system
function call. It provides a set of tape device, medium changer device, and
SCSI-specific operations. It allows HP-UX applications to access and
control the features and attributes of IBM SCSI tape subsystems
programmatically.
For programming information, refer to the IBM Tape Device Drivers Programming
Reference, GA32-0566.

Installation and configuration instructions


The following sections describe the installation and configuration for three types of
HP-UX devices.

Configuration limitations
Maximum supported number of tape devices

1000

Maximum supported number of HBA ports

128

Maximum supported number of paths for a


device (DPF/ CPF)

16/16

Maximum LUNs per system

32

Every attached tape or library device uses a certain amount of resources. The user
must consider resources such as physical memory and virtual space on the system,
which can further limit the number of devices that can be attached.

Installing and configuring PCI drivers


This chapter describes how to install, configure, and uninstall the IBM Tape and
Medium Changer device driver for HP-UX (ATDD) for PCI-based systems. By
default, ATDD automatically configures all supported IBM tape drives that are
attached and powered On when the system starts. ACDD, the changer part of
ATDD, does not configure IBM Medium Changer devices by default because many
applications use either their own changer drivers or the native schgr or sctl
drivers. In HP-UX 11i v1 and v2, the ATDD package includes with atdd tape
driver and acdd changer driver dynamic loadable kernel modules (DLKM). In
HP-UX 11i v3, the ATDD package consists of five modules in the kernel.
v atdd - static tape driver kernel module
v acdd - static changer driver kernel module
v atdd_leg - static legacy tape driver kernel module
v acdd_leg - static legacy changer driver kernel module
v atdd_core - DLKM core kernel module

Chapter 3. HP-UX Tape and Medium Changer device driver

49

Overview of the installation process


During and after the ATDD is installed, ACDD, the changer part of ATDD, can be
set to configure (CLAIM) all attached IBM Medium Changer devices. Additionally,
selected IBM Medium Changer devices can be configured by running the
swinstall command with the -x ask=true command option, or by running
/opt/atdd/bin/atdd_claim c c in 11i v2. The installation process depends on
whether all IBM tape drives are to be configured by ATDD or only selected ones.
Also, whether configured tape drives exhibit default behavior or require specific
configuration settings. Additionally, for IBM Medium Changers, installation
selection or post-installation configuration can determine whether all IBM Medium
Changers must be configured, selectively configured, or NOT configured at all.

Preinstallation considerations
Make sure that your system is ready to install ATDD before you begin. Follow
these steps to complete the installation.
1. Copy the software from the distribution medium to the depot.
2. Check the readme file and verify that your system is configured appropriately
for installing ATDD.
3. Ensure that the tape drives to be managed by ATDD are powered on.
4. Install and configure the software.
The following describes facts about the command sequences.
v In some of the examples, file names that are given on the command line must be
referenced with an absolute path. Using 'pwd'/filename to reference a file
instead of filename ensures this.
v All the software distributor commands (for example, swinstall or swcopy) can
be run first with the -p flag to preview the command. After the preview output
is observed, you can reissue the command without the -p flag to complete the
actual operation.
v The software distributor commands are moderately complex scripts that
frequently require several steps. The steps are typically Selection, Analysis, and
Execution. Each step can produce useful information and error messages. It is a
good idea to carefully observe the results of the installation process as it occurs.
If you encounter unexpected results during the installation, check the associated
log file.
While the software distributor commands are used, you might encounter the
following error about mounted file systems:
ERROR: "hostname/": One or more filesystems that appear in the
filesystem table are not mounted and cannot be mounted.

Many commands (for example, swinstall and swremove) attempt to mount all file
systems in the /etc/fstab file at the start of the analysis phase. This action ensures
that all listed file systems are mounted before proceeding. This action also helps
ensure that files are not loaded into a directory that might be below a future
mount point. But, it often causes an error with NFS mounted file systems.
This error can be overridden with '-x' to set the mount_all_filesystems option to
FALSE. When this option is used, the command finishes with a warning that
indicates no attempt is made to mount all file systems. For example,
# swinstall -x mount_all_filesystems=false -x ask=true -x autoreboot=true atdd

50

IBM Tape Device Drivers Installation and Users Guide

WARNING: "hostname:/": There will be no attempt to mount filesystems


that appear in the filesystem table.

Creating the Drive Configuration File (optional)


If you are not using the standard device driver defaults, you must create a
configuration file that directs the device driver on how to customize driver
behavior for particular IBM devices. If all configured devices are to use the device
driver configuration defaults, it is not necessary to create a configuration file before
the driver for ATDD is installed.
The Drive Configuration File is required if you do not use the device driver
configuration defaults.
If you do not need to create a Drive Configuration File, skip to the instructions in
Powering Off the tape drives on page 52.
If you do must create a Drive Configuration File, consult the following
instructions.
The configuration file is named sbin/init.d/atdd and has the following syntax:
ATDD_global_parameter=value
ATDD_device_parameter[index]=value

Note:
v Blank lines and lines that start with # are ignored.
v No spaces can appear within each entry.
v No trailing comments can appear on a variable definition line.

Determining the device hardware path for IBM tape drives


To determine the device hardware path for IBM tape drives with a SCSI
attachment, complete the following steps.
1. Run ioscan to determine the hardware path (the SCSI adapter) the tape drive is
connected to.
# ioscan -f -C ext_bus

2. Record the hardware path entry of the adapter:


For example: 0/10/0/0
3. Determine the SCSI target address of the tape drive.
HWPATH = adapterpath.drivetargetaddress.0 (tape drive)

For a tape drive at SCSI target address 3, the device hardware path is
0/10/0/0.3.0
To determine the device hardware path for IBM tape drives with the Fibre Channel
attachment, complete the following steps.
1. Run ioscan to determine the hardware path (the Fibre Channel) the tape drive
is connected to
# ioscan -f -C tape

2. Record the hardware path entry of the Fibre Channel. For example,
HWPATH = 0/5/0/0.8.0.255.7.9.0

Chapter 3. HP-UX Tape and Medium Changer device driver

51

Creating the hardware path entry


You must tell the driver which hardware path you want to attach to if you are not
using the installation defaults for driver behavior. Create an entry in the
/etc/rc.config.d/atdd configuration file for each device you want the driver to
attach. For example:
ATDD_HWPATH[0]=0/10/0/0.1.0
ATDD_HWPATH[1]=0/10/0/0.6.0
ATDD_HWPATH[2]=0/5/0/0.8.0.255.6.14.0

Creating the device-specific configuration entries (optional)


The ATDD is shipped with default settings for all configuration parameters. To
change these settings, an entry is made in the configuration file that assigns an
appropriate value to the wanted configuration variable. Each device can have a
different value for each configuration variable. The index number that is associated
with the configuration variable associates the parameter setting with the device at
the hardware path with the same index.
Example 1:
ATDD_IMMEDIATE[0]=1

This parameter allows application control to return from the device before the
rewind completes for the device at hardware path 0/10/0/0.1.0 (based on the
hardware path entry in Creating the hardware path entry).
Example 2:
ATDD_TRAILER[1]=1

This parameter allows write operations after an early end-of-tape warning for the
device at hardware path 0/10/0/0.6.0. Refer to Table 7 on page 58 and Table 8 on
page 59 for a description of all configuration parameters.
Note: If you experience difficulties with your tape device, check the /etc/rc.log for
errors and correct the problem.

Powering Off the tape drives


When the ATDD software is initially installed, it attaches itself to all tape drives
that are in the CLAIMED state as shown by entering the command
# ioscan -fk -C tape

Before you continue, make sure that all devices CLAIMED with the preceding
command are devices that you want this device driver to manage.
To list device file names in the /dev directory and its subdirectories, enter
# ioscan -funC tape

In HP-UX 11i v3, you can also enter


# ioscan -funNC tape

To remove a tape drive from the CLAIMED state so it is not configured by this
driver, power Off the tape drive and run ioscan without the -k argument as
follows.
# ioscan -f -C tape

52

IBM Tape Device Drivers Installation and Users Guide

Installing the driver with the ATDD installation script


An installation script (InstallAtdd) is provided to automate driver installation and
run some checking functions. It copies the latest version of the driver to the
software depot and installs the latest driver version.
To install ATDD with the script, download the installation script with the driver at
Fix Central, then run the installation script.
When the installation script runs, the customer is prompted with the question,
Would you like to activate the Medium Changer support by ATDD (Y/N)?. Enter
Y to allow the ATDD to configure all attached IBM Medium Changer devices. Or,
answer N to allow the HP native changer driver to configure these Medium
Changer devices.
Note:
1. If a previous version of ATDD is installed on your system, uninstall it
before you attempt to install the latest version. Refer to Uninstalling the
software on page 57.
2. The system reboot is required to install ATDD in HP-UX 11i v3.
To install ATDD manually, follow the steps in Installing drivers manually.

Installing drivers manually


Installing the drivers manually requires the steps that are detailed in the following
sections.
1. Copying the software to the Software Depot.
2. Installing the ATDD software.
3. If a previous version of ATDD is installed on your system, uninstall it before
you attempt to install the latest version. Refer to Uninstalling the software on
page 57.

Copying the software to the Software Depot


Attention: If you do not copy the ATDD software into a depot, you cannot
readily uninstall the product.
Copy the appropriate driver to the Software Depot. For example:
# swcopy -p -s /driver_location/atdd.x.x.x.x atdd (preview option)
# swcopy -s /driver_location/atdd.x.x.x.x atdd

Use swlist to verify that the ATDD software is in the depot:


# swlist -d atdd

Installing the ATDD software


When the software is in the depot and only the appropriate drives are powered on,
the ATDD software can be installed to the root file system with the HP-UX
swinstall command. If the target root file system is the primary, the ATDD
software is configured automatically upon installation.
If the target is an alternate root file system, then the ATDD software is not
configured automatically.

Chapter 3. HP-UX Tape and Medium Changer device driver

53

Note: If an earlier version of the product is already installed on the target root file
system, the existing version is replaced. This replacement is true even if the
version already installed is more recent than the version being installed.
The following commands install ATDD from the depot to the default root file
system by issuing the swinstall command with the ask options that are set as
follows:
# swinstall -p -x ask=true atdd (preview option)
# swinstall -x ask=true atdd in HP-UX 11i v1, and v2
# swinstall -x autoreboot=true -x ask=true atdd in HP-UX 11i v3

Running the swinstall command with the ask option set to TRUE prompts the
customer, Would you like to activate the Medium Changer support by ATDD
(Y/N)?. Enter Y to allow the ATDD to configure all attached IBM Medium Changer
devices, or answer N to allow the HP native changer driver to configure these
Medium Changer devices.
You can use swlist to list the software that is installed on the default root file
system as follows:
# swlist atdd

You can verify correct installation to the default root file system with the swverify
command as follows:
# swverify atdd
# ioscan -fknC tape
Class I H/W Path
Driver
S/W State
H/W Type
Description
============================================================================================
tape 0 0/3/0/0.5.0
atdd
CLAIMED
DEVICE
IBM 03590E11
/dev/rmt/0m /dev/rmt/0mn
/dev/rmt/c4t5d0BEST /dev/rmt/c4t5d0BESTn
/dev/rmt/0mb /dev/rmt/0mnb /dev/rmt/c4t5d0BESTb /dev/rmt/c4t5d0BESTnb
tape 1 0/3/0/0.6.0
atdd
CLAIMED
DEVICE
IBM 03590B11
/dev/rmt/1m /dev/rmt/1mn
/dev/rmt/c4t6d0BEST /dev/rmt/c4t6d0BESTn
/dev/rmt/1mb /dev/rmt/1mnb /dev/rmt/c4t6d0BESTb /dev/rmt/c4t6d0BESTnb
tape 4 0/5/0/0.1.23.232.0.0.2 atdd
CLAIMED
DEVICE
IBM ULT3580-TD1
/dev/rmt/4m /dev/rmt/4mn
/dev/rmt/c6t0d2BEST /dev/rmt/c6t0d2BESTn
/dev/rmt/4mb /dev/rmt/4mnb /dev/rmt/c6t0d2BESTb /dev/rmt/c6t0d2BES

If you enabled ACDD, run the following ioscan command to view the medium
changers found:
# ioscan -fnkC autoch
Class
I H/W Path
Driver S/W State H/W Type Description
=======================================================================
autoch 0 0/3/0/0.5.1
acdd CLAIMED
DEVICE
IBM 03590E11
/dev/rmt/0chng
autoch 2 0/6/0/0.1.17.255.5.10.1 acdd
CLAIMED
DEVICE
IBM 03590E11
/dev/rmt/2chng
autoch 4 0/5/0/0.1.23.232.0.0.1 acdd
CLAIMED
DEVICE
IBM ULT3583-TL
/dev/rmt/4chng

In HP-UX 11i v3, run # ioscan -funNC tape or autoch to display the tape devices
that are configured with ATDD and ACDD drivers. Run # ioscan -funNC tape or
autoch to show the tape devices that are bound with the legacy atdd_leg and
acdd_leg drivers.

54

IBM Tape Device Drivers Installation and Users Guide

Configuring all IBM tape drives/Media Changers with ATDD/ACDD


By default, ATDD automatically configures all supported IBM tape drives that are
attached and powered on when the ATDD package is installed. The ACDD driver
does not configure IBM Medium Changer devices by default. To configure all IBM
Medium Changer devices on the system during the installation of ATDD package,
run the swinstall command with the -x ask=true command option and answer
Yes to allow the ACDD to claim these devices.
v In HP-UX 11i v1 and v2, run the command:
# /opt/atdd/bin/atdd_claim -c

v In HP-UX 11i v3, do the following steps:


1. Bind each changer device with the ACDD driver:
# ioscan -b -M acdd -H hw_path

2. Reboot the system to configure the changer devices:


# shutdown -ry now

To remove the claim with ACDD after the next reboot:


v In HP-UX 11i v1 and v2, run the command:
# /opt/atdd/bin/atdd_claim -u

v In HP-UX 11i v3, do the following steps.


1. Bind each changer device with a changer driver. For example, to bind the
changer device with eschgr driver:
# ioscan -b -M eschgr -H hw_path

2. Reboot the system to unconfigure the changer devices:


# shutdown -ry now

Configuring selected IBM tape devices with ATDD/ACDD in HP-UX 11i


v1 and v2
Attaching selected IBM tape devices to ATDD/ACDD during auto booting
To claim a specific tape device with atdd/acdd during reboot, edit the "Claiming
Device" section in the /sbin/init.d/atdd file.
For example, to attach IBM 3590E11 medium changer with acdd driver:
1. To determine the HW path:
# ioscan -fnk|grep IBM
autoch
0 0/3/0/0.5.1

schgr

CLAIMED

DEVICE

IBM

03590E11

2. Comment out the command lines in the init script of /sbin/init.d/atdd:


v For tape drives:
/opt/atdd/bin/atdd_claim -t

v For medium changers:


/opt/atdd/bin/atdd_claim -c

3. Add a command line in the Configuring Device section in /sbin/init.d/atdd:


/opt/atdd/bin/atdd_claim -H 0/3/0/0.5.1

Attaching selected IBM tape devices to ATDD/ACDD dynamically


To dynamically attach selected IBM tape device after the ATDD installation, run
the following commands.
1. To determine the HW path of the device:
Chapter 3. HP-UX Tape and Medium Changer device driver

55

# ioscan -fnk|grep IBM


autoch
0 0/3/0/0.5.1

schgr

CLAIMED

DEVICE

IBM

03590E11

2. To claim the device with ATDD/ACDD:


# /opt/atdd/bin/atdd_claim -H 0/3/0/0.5.1

Note: The dynamic attachment might be lost after the system reboots.
Attaching selected IBM tape device with a particular driver
Use the system ioscan and rmsf commands to force a non-atdd/acdd driver to
bind an IBM tape device. For example, force bind the IBM 3590E media changer
with the HP native changer driver schgr with these steps:
1. Determine the HW path of the device:
# ioscan -fnk |grep IBM
tape
0 0/3/0/0.5.0
autoch
0 0/3/0/0.5.1

atdd
acdd

CLAIMED
CLAIMED

DEVICE
DEVICE

IBM
IBM

03590E11
03590E11

DEVICE
DEVICE

IBM
IBM

03590E11
03590E11

2. Remove the I/O configuration from the system:


# rmsf -H 0/3/0/0.5.1

3. Force binding:
# ioscan -M schgr -H 0/3/0/0.5.1

4. Create the device special files:


# insf -H 0/3/0/0.5.1

5. Verify the force binding:


# ioscan -fnk |grep IBM
tape
0 0/3/0/0.5.0
autoch
0 0/3/0/0.5.1

atdd
schgr

CLAIMED
CLAIMED

Note: The force binding is lost after the system reboots. To keep the binding to
a selected device with a particular driver after a reboot, add these
command-lines in steps 24 in Claiming Device section in
/sbin/init.d/atdd file. For example,
# Configuring Device Section:
# add specific device claim here, for example
# /opt/atdd/bin/atdd_claim -H 0/3/0/0.5.1
# /opt/atdd/bin/atdd_claim -H 0/6/0/0.1.30.255.0.0.1
rmsf -H 0/3/0/0.5.1
ioscan -M schgr -H 0/3/0/0.5.1
insf -H 0/3/0/0.5.1

Configuring selected IBM tape devices with ATDD/ACDD in HP-UX 11i


v3
By default, atdd driver automatically configures all supported IBM tape drives that
are attached and powered on when the ATDD package is installed. The acdd
driver does not configure IBM medium changer devices by default. All of IBM
medium changers are claimed if you use acdd and acdd_leg as the changer drivers
during ATDD are installed. To attach a selected IBM tape device with a particular
driver, run the system ioscan command to force a non-ATDD/ACDD driver to
bind an IBM tape device, and then reboot the system. For example, to force bind
the IBM 3592 E05 tape drive with the HP native tape driver estape, complete these
steps:
1. Determine the HW path of the device:
# ioscan -fNk | grep IBM
tape
1 64000/0xfa00/0x7

2. Force the binding:

56

IBM Tape Device Drivers Installation and Users Guide

atdd

CLAIMED

DEVICE

IBM 03592E05

# ioscan -b -M estape -H 64000/0xfa00/0x7

3. Reboot the system:


# shutdown -ry now

4.

Create the device special files if it does not exist after the system bootup:
# insf -H 64000/0xfa00/0x7

5. Verify the force binding:


# ioscan -fNk | grep IBM
tape
1 64000/0xfa00/0x7

estape

CLAIMED

DEVICE

IBM 03592E05

Uninstalling the software


Attention: Do not try to uninstall the ATDD software by deleting the files that
make up the ATDD file set. This action causes a number of inconsistencies on the
system. It is best to use the swremove command.
To uninstall ATDD (from the root file system):
# swremove atdd in HP-UX 11i v1 and v2
# swremove -x autoreboot=true atdd in HP-UX 11i v3

Other administrative tasks


To determine whether the current version of ATDD is installed or configured on
the default root file system:
# swlist -a state atdd

To determine the versions of ATDD stored in the default depot:


# swlist -d atdd

To remove ATDD from the depot:


# swremove -d atdd

If more than one level of ATDD exists in the depot, explicitly specify the level to
remove it. For example:
# swremove -d atdd,r=3.5.0.0

To view the file set of ATDD installed on the system:


# swlist -l file atdd

To display and manage ATDD kernel modules and kernel-tunable parameters, run
kmadmin, kmsystem, kmtute, and kmadmin commands in HP-UX 11i v1 and kcmodule,
kctune commands in HP-UX 11i v2 and v3, or go to the Kernel Configuration in
the sam utility. Refer to the system manual for detail.
For an example, print the ATDD driver module status, entering the command:
# kcmodule -d atdd
Module State
Cause
atdd
static explicit

Description
Advanced Tape Device Driver

Supported configuration parameters


This chapter describes the supported configuration values for multiple device types
that are configured on the same system. The configuration parameters are global.
Because the configuration parameters are global to all devices, it is necessary to
use configuration values that run reliably on all devices that are attached to your
Chapter 3. HP-UX Tape and Medium Changer device driver

57

system. If you are experiencing difficulties, ensure that your driver is configured
properly. To check your current configuration, use the atdd_cfg program that is in
/opt/OMImag/bin for the static PB driver and in /opt/atdd/bin for the PCI driver.
For program usage, run as follows:
For PB driver:
# /opt/OMImag/bin/atdd_cfg -h

For PCI driver:


# /opt/atdd/bin/atdd_cfg -h

Configuration parameter definitions


This section describes the configuration parameters and values. Modifying the
default settings is not recommended unless instructed to do so. The ATDD is
shipped with default values that allow the most reliable execution across various
device types.

Device-specific parameters
Some of the configuration parameters are device-specific, while others are
driver-specific. Table 7 shows the parameters that are device-specific, what they
mean, and their values.
Table 7. HP-UX: Device-specific parameter definitions
Parameter

Meaning

Values

DENSITY

Density to use when


writing/reading tape

In hexadecimal

SILI

Suppress Incorrect Length v 0=Off (do not suppress, by


Indicator
default)
v 1=On (suppress)

BLOCKSIZE

Block Size

Size in bytes, 0 by default.

COMPRESSION

Compression Mode

v 0=Off (do not use compression


at drive)
v 1=On (use compression at
drive, by default)

BUFFERING

Buffering Mode

v 0=Off (do not buffer data)


v 1=On (buffer data to hardware
buffers, by default)

IMMEDIATE

Immediate Mode

v 0=Off (wait for rewind


completion, by default)
v 1=On (return before rewind is
complete)

TRAILER

Trailer Label Processing

v 0=Off (do not allow writes past


early EOT warning, by default)
v 1=On (allow writes past early
EOT warning)

ERRNO_LEOT

58

IBM Tape Device Drivers Installation and Users Guide

Error Number return for


Logical End Of Tape)

Value that is returned for writes


past EOM, 28 by default.

Table 7. HP-UX: Device-specific parameter definitions (continued)


Parameter

Meaning

Values

RESERVE

Multiple open for the


device

v 1=On (reserve the device after


to open, by default)
v 0=Off (do not reserve the
device after to open) (multiple
open support)

RESERVE_KEY

WFM_IMMEDIATE

The user specifies the


Persistent Reservation
key that is used by the
device driver when the
Persistent Reservation is
used.

v 0 (the driver assigns the key by


default)

Immediate Mode for


Write File Mark

v 0=Off (wait for write file mark


completion, by default)

v A string of 1-8 character ASCII


alphanumeric key such as
"key12345". If fewer than 8
characters are used, the
remaining characters are set to
0x00(NULL)

v 1=On (return before write file


mark is complete)
PRE_V3_COMPAT

Use to share tapes with


blocksize > 256 kb with
HP-UX 11i v2 or earlier.
Supported in HP-UX 11i
v3 only.

v 0=Off (always write or read the


date with the blocksize defined
by user, by default)
v 1=On (split the blocksize less
than 256 kb during the read or
write)

Driver-specific parameters
Some of the configuration parameters are device-specific, while others are
driver-specific.Table 8 shows the parameters that are driver-specific, what they
mean, and their values.
Table 8. HP-UX: Driver-specific parameters (Global)
Parameter

Meaning

Values

INSTANCE

ATDD Device Number

(Read Only)

DEVICES

Number of Configured Devices

(Read Only)

Modifying configuration parameters


To change a configuration parameter, use the atdd_cfg program in
/opt/OMImag/bin for the PB driver and in /opt/atdd/bin for the PCI driver. You
can update the current value.
v In HP-UX 11i v1 and v2:
For example, if you want to change the COMPRESSION parameter to 0 for the
device at hardware path 0/4/0/0.1.0, do the following step:
# atdd_cfg -g INSTANCE 0/4/0/0.1.0
INSTANCE: 2

The ATDD instance number for this device is returned. You must use this
INSTANCE value (1) to set the COMPRESSION value for this device.
# atdd_cfg -s COMPRESSION 0 2

Or, to get or modify COMPRESSION by using the hardware path:


Chapter 3. HP-UX Tape and Medium Changer device driver

59

# atdd_cfg -g COMPRESSION 0/4/0/0.1.0


# atdd_cfg -s COMPRESSION 0 0/4/0/0.1.0

v In HP-UX 11i v3:


The usage of atdd_cfg command is:
atdd_cfg -d special_file [-o parameter [-w value]]

All configurable parameters for the specified device are displayed by entering
#atdd_cfg -d special_file only
For instance:
# /opt/atdd/bin/atdd_cfg -d /dev/rtape/tape14_BEST
DENSITY=0
SILI=1
BLOCKSIZE=0
COMPRESSION=1
BUFFERING=1
REWIND_IMMEDIATE=0
TRAILER=1
SCALING=0
WRITEPROTECT=0
ERRNO_LEOT=28
WFM_IMMEDIATE=0
RESERVE=1
PRE_V3_COMPAT=0

To display a specific parameter, run #atdd_cfg -d special_file -o parameter


For example,
#/opt/atdd/bin/atdd_cfg -d /dev/tape/tape14_BESTn -o COMPRESSION
COMPRESSION=1

To set a specific parameter, run #atdd_cfg -d special_file -o parameter -w


value
For example,
# atdd_cfg -d /dev/rtape/tape14_BESTn -o
Success

COMPRESSION -w 0

To set a new BOOT default value for the configuration parameter, you must
modify or add an entry in the atdd.cfg configuration file in /etc/rc.config.d for
the static driver or the atdd configuration file in /sbin/init.d.
For example, if you want the COMPRESSION default set to 0 for the device at
ATDD_HWPATH[0] or tape14_BESTn, add the following line to your configuration file:
v In HP-UX 11i v1 and v2:
ATDD_COMPRESSION[0]=0

v In HP-UX 11i v3:


/opt/atdd/bin/atdd_cfg -d /dev/rtape/tape14_BESTn -o COMPRESSION -w 0

Note: The configuration parameters are prefixed with ATDD_ in the configuration
file. For instructions about using the configuration program, use the -h
option as follows:
# atdd_cfg -h

Configurable kernel parameters (tunable)


ATDD provides the following variety of configurable kernel parameters that allow
the users to customize for specific setup:

60

IBM Tape Device Drivers Installation and Users Guide

atdd_log_trace
Log the sense data in syslog when a hardware or medium error is
occurred, see Sense data logging on page 68 for details. This parameter
is enabled by default on 11i v3 and later, but disabled by default in 11i v2
and earlier.
alternate_pathing/atdd_alternate_pathing
Enable or disable the alternate path support for CPF/DPF (see the specific
operating system section that covers CPF and DPF support for detail). This
parameter is enabled by default.
atdd_disable_reserve/atdd_disable_res
Allows the user to disable the reservation management from ATDD. This
parameter is Off by default.
atdd_loadbalance
Allows the user to disable automatic load balancing from ATDD. This
parameter is On (1) by default and supported on 11i v3 only.
atdd_reserve_type
The drive is reserved in the SCSI-2 Reserve command when Data Path
failover (DPF) is disabled by default. To reserve the drive with Persistent
Reserve In and Out commands, the user can set the value of
atdd_reserve_type to 3. The default values for the tunable:
v 1 - Reserve(6) command.
v 2 - Reserve(10) command (Unsupported).
v 3 - Persistent Reserve In/Out commands.
To change the value of tunable, run the command kctune/kmtune or the SAM
(System Administration Manager) tool.

Special files
For each drive configured by ATDD, 12 or 13 special files are created. 12 special
files are generated for a 3590 with ACF set to Manual, Automatic, System,
Accumulate, Random, or Library mode. A 13th special file is created for
independent operation of the ACF, if the 3590 mode is set to Random 2 LUN
operation (/dev/rmt/<instance#>chng).
ATDD creates the tape device special files in three forms v The standard or long file name.
v An alternative short file name that is based on the instance number.
v An alternative short file name that is not based on the instance number.
BEST represents the operational capabilities likely to be required, including the
highest density/format and data compression, if supported by the device. Each set
of special file names (long and short) contains four special files that have all
combinations of n and b options, as shown in Table 9 and Table 10 on page 62. For
information, refer to the mt(7) man pages.
Table 9. Special files
BSD
compatibility

Rewind on
close

/dev/rmt/<instance#>m

No

Yes

/dev/rmt/<instance#>mb

Yes

Yes

Special file name

Chapter 3. HP-UX Tape and Medium Changer device driver

61

Table 9. Special files (continued)


BSD
compatibility

Rewind on
close

/dev/rmt/<instance#>mn

No

No

/dev/rmt/<instance#>mnb

Yes

No

/dev/rmt/s<#>m

No

Yes

/dev/rmt/s<#>mb

Yes

Yes

/dev/rmt/s<#>mn

No

No

/dev/rmt/s<#>mnb

Yes

No

/dev/rmt/<instance#>t<target>d<LUN>BEST

No

Yes

/dev/rmt/<instance#>t<target>d<LUN>BESTb

Yes

Yes

/dev/rmt/<instance#>t<target>d<LUN>BESTn

No

No

/dev/rmt/<instance#>t<target>d<LUN>BESTnb

Yes

No

N/A

N/A

BSD
compatibility

Rewind on
close

/dev/rtape/tape#_BEST

No

Yes

/dev/rtape/tape#_BESTb

Yes

Yes

/dev/rtape/tape#_BESTn

No

No

/dev/rtape/tape#_BESTnb

Yes

No

N/A

N/A

Special file name

/dev/rmt/<instance#>chng
Table 10. New special files in HP-UX 11i v3
Special file name

/dev/rchgr/autoch#

v In HP-UX 11i v1 and v2:


atdd_lssf in /opt/OMImag/bin for the static driver and in /opt/atdd/bin for the
DLKM driver lists information about a special file. For example,
#atdd_lssf /dev/rmt/393mnb
atdd card instance 30 available at address Major = 79
settings = No Rewind, Berkeley, Best Format,
IBM 03590H1A /dev/rmt/393mnb

Minor = Ox1E90C0

v In HP-UX 11i v3:


ATDD supports the HP-UX lssf, insf, and rmsf commands. To display special
file information, enter the lssf command. For example,
# lssf /dev/rtape/tape14_BESTnb
atdd Berkeley No-Rewind best density available at address 64000/0xfa00/0x32
/dev/rtape/tape14_BESTnb
# lssf /dev/rchgr/autoch1
acdd section 0 at address 64000/0xfa00/0x21 /dev/rchgr/autoch1

If the device special files are not created on the system, use the # insf command
to generate them.

62

IBM Tape Device Drivers Installation and Users Guide

Persistent Naming Support


Persistent Naming Support is used to ensure that attached devices are always
configured with the same logical name across system reboots. For this purpose, the
HP-UX tape driver creates an extra set of device special files with a prefix of "s" for
the configured tape drives in HP-UX 11i v1 and v2, such as s55m in the following
example.
# ioscan -funC tape
Class I
H/W Path
Driver S/W State
H/W Type
Description
===================================================================================
tape
103 1/0/0/0.97.25.255.2.7.0
atdd
CLAIMED
DEVICE
IBM
03592E05
/dev/rmt/103m
/dev/rmt/c10t7d0BESTn
/dev/rmt/s55mb
/dev/rmt/103mb
/dev/rmt/c10t7d0BEST
/dev/rmt/s55mn
/dev/rmt/103mn
/dev/rmt/c10t7d0BESTb
/dev/rmt/s55m
/dev/rmt/103mnb
/dev/rmt/c10t7d0BESTnb
/dev/rmt/s55mnb

In HP-UX 11i v3, HP introduces the native multi-pathing and path-independent


persistent Device Special Files (DSFs) and the auto discovery of devices to enhance
overall manageability. The ATDD does not create the additional set of device
special files with a prefix of s.
The persistent DSF format for tape devices that are introduced with the Agile view
in HP-UX 11i v3 is
# ioscan -funNC tape
Class
I H/W Path Driver S/W State
H/W Type
Description
===================================================================
tape
1 64000/0xfa00/0x7
estape
CLAIMED
DEVICE IBM 03592E05
/dev/rtape/tape1_BEST
/dev/rtape/tape1_BESTn
/dev/rtape/tape1_BESTb
/dev/rtape/tape1_BESTnb
# ioscan -funNC autoch
Class
I H/W Path Driver S/W State
H/W Type
Description
=================================================================
autoch
8 64000/0xfa00/0xa
acdd
CLAIMED
DEVICE IBM 03584L22
/dev/rchgr/autoch8

To map a persistent DSF to its legacy DSF, enter the following # ioscan -m dsf /dev/rtape/tape1_BESTb
Persistent DSF
Legacy DSF(s)
========================================
/dev/rtape/tape1_BESTb
/dev/rmt/c3t15d0BESTb
/dev/rmt/c9t6d0BESTb

Control Path failover support for tape libraries


Note:
1. The library control path failover feature code must be installed before the
path failover support is enabled in the HP-UX ATDD device driver. Refer
toAutomatic failover on page 1 for what feature code might be
required for your machine type.
2. It is a requirement that applications must open the primary path for CPF.

Configuring and unconfiguring path failover support


Path failover support is enabled automatically when the device driver is installed.
However, the driver provides a kernel parameter that you can use to enable library

Chapter 3. HP-UX Tape and Medium Changer device driver

63

control path failover. To enable the failover support in the ATDD driver, complete
the following steps after the driver is installed.
v In HP-UX 11i v1 and v2:
1. Set the alternate_pathing parameter.
#

2.

/opt/atdd/bin/atdd_failover -a 1

Reconfigure CPF for the devices.


#

/opt/atdd/bin/atdd_claim

v In HP-UX 11i v3:


Run kctune to enable the kernel tunable of atdd_alternate_pathing. ATDD
handles the CPF in the next open.
# kctune atdd_alternate_pathing=1
* The automatic backup configuration has been updated.
* The requested changes have been applied to the currently
running configuration.
Tunable
Value
Expression
Changes
atdd_alternate_pathing (before)
0
0
Immed
(now)
1
1

You can check whether the driver recognized multiple control paths for your
library by running
#ioscan -funC autoch

If you see .altpath next to one of the special files in HP-UX 11i v1 and v2, then
you successfully enabled the control path failover feature for your library. In
HP-UX 11i v3, use the # ioscan -m dsf command and [11] Display All Paths on
page 249 or Display All Paths on page 310 in ITDT to verify that the multiple
path is configured by the system and ATDD.
After the path failover support is enabled, it remains set until atdd_claim is run
with the alternate_pathing driver parameter set to OFF. The path failover setting
is retained even if the system is rebooted. If you want to turn off the control path
failover feature in the ATDD driver, complete the following steps.
v In HP-UX 11i v1 and v2:
1. Clear the alternate_pathing parameter.
#

/opt/atdd/bin/atdd_failover -a 0

2. Reconfigure CPF for the devices.


#

/opt/atdd/bin/atdd_claim

v In HP-UX 11i v3:


Run kctune to disable the kernel tunable of atdd_alternate_pathing. ATDD
manages the CPF in the next open.
# kctune atdd_alternate_pathing=0
* The automatic backup configuration has been updated.
* The requested changes have been applied to the currently
running configuration.
Tunable
Value Expression
Changes
atdd_alternate_pathing (before)
1
1
Immed
(now)
0
0

Primary and alternative paths


When ATDD is loaded into the kernel, the first logical medium changer device that
it sees in the system is the primary path for that medium changer. The other
logical medium changers that ATDD attached for the same medium changer is
configured as alternative paths. The device driver supports up to 16 physical paths
for a single device.

64

IBM Tape Device Drivers Installation and Users Guide

On HP-UX 11i v3, the HP-UX system always selects the best path for ATDD to
open so the primary path is dynamically assigned from the system. ATDD does
not provide any .altpath special file.
The primary and alternative path information can be obtained by using the
following command on HP-UX 11i v1 and v2.
#

ioscan -funC autoch

The following is an example of what you might see:


autoch
autoch

0 0/1/0/0.101.22.255.1.1.1
1 0/1/0/0.101.22.255.1.2.1

acdd
acdd

CLAIMED
CLAIMED

DEVICE
DEVICE

IBM
IBM

ULT3582-TL /dev/rmt/0chng
ULT3582-TL /dev/rmt/1chng.altpath

Querying primary and alternative path configurations


You can display the primary and alternative path configuration for all devices by
running the ioscan command, as explained in Determining the device hardware
path for IBM tape drives on page 51.
Note: To display the primary and alternative path configuration for any device by
using tape diagnostic and utility functions, refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Disabling and enabling primary and alternative paths


When you load the ATDD device driver with the alternate_pathing parameter set
to ON, by default, all the available paths for a physical device are enabled.
If it is necessary to disable a path and not complete path failover (for example due
to maintenance), run commands to disable and then later enable the primary and
alternative paths.
The commands to enable and disable primary and alternative paths are tape
diagnostic and utility functions.
Note: See Chapter 8, IBM Tape Diagnostic Tool (ITDT), on page 211.

Data Path failover and load balancing support for tape drives
The HP-UX device driver path failover support configures multiple physical paths
to the same device within the device driver and provides two basic functions.
1. Automatic failover to an alternative physical path when a permanent error
occurs on one path.
2. Dynamic load balancing for devices with multiple Host Bus adapters (HBA).
On HP-UX 11i v3, HP-UX system always picks up a best path for ATDD to
open. ATDD does not run a dynamic load balancing in open.
Note:
1. Data Path failover is not supported when block sizes greater than 256 K
are used, except in HP-UX 11i v3.
2. It is required that applications must open the primary path for Data Path
failover (not in HP-UX 11i v3).
Chapter 3. HP-UX Tape and Medium Changer device driver

65

3. Data Path failover is supported for 3592 tape drives on HP-UX 11i v2
and v3, and for Ultrium 3, Ultrium 4, Ultrium 5, and Ultrium 6 drives on
HP-UX v2 and v3.

Configuring and unconfiguring path failover support


Path failover support is turned on automatically when the device driver is
installed. However, you must provide the data path failover feature key and
reclaim the devices by using the atdd_claim script. The feature key is a string with
16 characters and numbers.
1. Edit the following line in your /sbin/init.d/atdd file.
DPF_KEYS="1234567890123456; 0987654321123456 "

Note:
a. 1234567890123456 is an example of a data path failover feature key. If
you have multiple 3584 libraries and multiple data path failover
feature keys, input your keys as follows:
DPF_KEYS="key1; key2; ..."

b. A DPF key is required for Ultrium 3 tape drives only. No DPF key
must be added into the /sbin/init.d/atdd file if you are running the
most recent drive code.
2. Save the file, then run the following command in HP-UX 11i v1 and v2:
#

/opt/atdd/bin/atdd_claim

3. In HP-UX 11i v1 and v2, you can check whether the driver recognized multiple
data paths for your drives by running:
#ioscan -funC tape

If you see ".altpath" next to one of the special files, then you successfully
enabled control path failover feature for your library.
In HP-UX 11i v3, use the # ioscan -m dsf command to verify that the multiple path
is configured by the system and ATDD.
Note: See Chapter 8, IBM Tape Diagnostic Tool (ITDT), on page 211.
After path failover support is enabled, it remains set until atdd_claim or kctune is
run with the alternate_pathing driver parameter set to OFF. The path failover
setting is retained even if the system is rebooted. If you want to turn off the data
path failover feature in the ATDD driver, complete the following steps.
In HP-UX 11i v1 and v2:
1. Clear the alternate_pathing parameter. (You can ignore the message about
rebooting the system.)
#

/opt/atdd/bin/atdd_failover -a 0

2. Reconfigure DPF for the devices.


#

/opt/atdd/bin/atdd_claim

In HP-UX 11i v3:


Run kctune to disable the kernel tunable of atdd_alternate_pathing. ATDD handles
the DPF in the next open.

66

IBM Tape Device Drivers Installation and Users Guide

# kctune atdd_alternate_pathing=0
* The automatic backup configuration has been updated.
* The requested changes have been applied to the currently
running configuration.
Tunable
Value Expression Changes
atdd_alternate_pathing (before)
1
1
Immed
(now)
0
0

If you want to turn the data path failover feature back on in the ATDD driver,
complete the following steps.
In HP-UX 11i v1 and v2:
1. Set the alternate_pathing parameter. (You can ignore the message about
rebooting the system.)
#

2.

/opt/atdd/bin/atdd_failover -a 1

Reconfigure DPF for the devices.


#

/opt/atdd/bin/atdd_claim

In HP-UX 11i v3:


Run kctune to enable the kernel tunable of atdd_alternate_pathing. ATDD handles
the DPF in the next open.
# kctune atdd_alternate_pathing=1
* The automatic backup configuration has been updated.
* The requested changes have been applied to the currently
running configuration.
Tunable
Value Expression Changes
atdd_alternate_pathing (before)
0
0
Immed
(now)
1
1

Primary and alternative paths


When ATDD is loaded into the kernel, the first logical device that it sees in the
system is the primary path for that medium changer. The other logical paths that
ATDD attached for the same tape drive is configured as alternative paths. The
device driver supports up to 16 physical paths for a single device. In HP-UX 11i
v3, the HP-UX system always picks up the best path for ATDD to open so the
primary path is dynamically assigned from the system. ATDD does not provide
any .altpath special file.
The primary and alternative path information can be obtained by issuing the
following command except in HP-UX 11i v3.
#

ioscan -funC tape

The following is an example of the output for this command.


home/root# ioscan -funC tape
Class I H/W Path
Driver S/W State H/W Type
Description
===============================================================================
tape 0 0/1/0/0.101.22.255.1.1.1 atdd CLAIMED DEVICE IBM ULT3580-TD3 /dev/rmt/0m
tape 1 0/1/0/0.101.22.255.1.2.1 atdd CLAIMED DEVICE IBM ULT3580-TD3 /dev/rmt/1m.altpath

Querying primary and alternative path configuration


You can display the primary and alternative path configuration for all devices by
running ioscan, as explained in Primary and alternative paths.

Chapter 3. HP-UX Tape and Medium Changer device driver

67

Note: To display the primary and alternative path configuration for any device by
using tape diagnostic and utility functions, refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Disabling and enabling primary and alternative paths


If it is necessary to disable a path and not complete path failover (for example due
to maintenance), run commands to disable and then later enable the primary and
alternative paths.
The commands to enable and disable primary and alternative paths are tape
diagnostic and utility functions.
Note: See Chapter 8, IBM Tape Diagnostic Tool (ITDT), on page 211.

Problem determination
A set of tools is provided with the device driver to determine if the device driver
and the tape device are functioning correctly.

Error logging
Read the system log file (typically /var/adm/syslog/syslog.log) and the ATDD log
file (/var/adm/atdd/atdd_d.log) if you are having problems. The ATDD logs
messages to this file that provides information about the problem.

Sense data logging


When the tape drive responds with CHECK CONDITION status and associated
sense keys of 0x1 (Recovery Error), 0x3 (Medium Error), 0x4 (Hardware Error), and
0xB (Aborted Command) for a hardware or medium error, the sense data is logged
in to the system log file (typically /var/adm/syslog/syslog.log). The sense data
logging feature is disabled by default on 11i v1 and 11i v2 and enabled by default
on 11i v3. To enable the support dynamically, run /opt/atdd/bin/atdd_cfg with the
-c option.
# /opt/atdd/bin/atdd_cfg -c 1
* The requested changes have been applied to the currently running system.
Tunable
Value Expression Changes
atdd_log_trace (before)
0
Default
Immed
(now)
1
1

Support_info script
Run the support_info script, in the /opt/OMImag/bin directory for the static driver
and in /opt/atdd/bin for the DLKM driver. This script gathers important system
and configuration information. There are several sections with the keyword
VERIFY, indicating information that must be verified for correctness.
Log in as user ID "root" on the system that experienced a problem. Then, run the
script and redirect the output to an end of a file.
Static
/opt/OMImag/bin/support_info > support_info.out

68

IBM Tape Device Drivers Installation and Users Guide

DLKM
/opt/atdd/bin/support_info > support_info.out

Tracing facility
Running the ATDD_trace utility, in the /opt/OMImag/bin for the static driver and in
/opt/atdd/bin for the DLKM driver, displays debug information. The utility traces
can be started at any time before an operation on a tape device. The default debug
level is 0x00001003, which shows driver configuration and per instance drive
attribute configuration and errors. You can increase the amount of debug
information that is displayed by enabling more trace flags. Issuing atdd_trace -f
0x1fffffff turns on every trace.
1. Determine which items must be traced and set the trace flags by using the
atdd_trace command. For example, to trace everything For the Static driver:/opt/OMImag/bin/atdd_trace -f 0x1fffffff
For the DLKM driver:/opt/atdd/bin/atdd_trace -f 0x1fffffff
In HP-UX 11i v3, run the sam utility or # kctune atdd_trace_level=1
command to set the trace level to 1. The default set is 3. The different levels
of tracing for 11iv3 are
v Full trace = 1
v Messages = 2
v Warnings = 3
v Errors = 4
The set of trace flags is displayed in Table 11.
Table 11. Trace flags
COMMAND

VALUE

Configuration

0x00000001

General errors

0x00000002

Routine entry points

0x00000004

Returns

0x00000008

TRACE_DBG information

0x00000010

Open/Close routine

0x00000020

Trace motion commands

0x00000040

Read/Write

0x00000100

Strategy

0x00000200

Open/Close states

0x00000400

IOCTLs

0x00000800

Trace device config routines

0x00001000

Trace SCSI level stuff

0x00004000

Configuration

0x10000000

Entry point

0x01000000

General information

0x00400000

Memory

0x00200000

2. Clear the trace buffer.


For the Static driver:/opt/OMImag/bin/atdd_trace -c
Chapter 3. HP-UX Tape and Medium Changer device driver

69

For the DLKM driver:/opt/atdd/bin/atdd_trace -c


3. To have trace data that is displayed immediately in a readable format as it is
collected.
For the Static driver:/opt/OMImag/bin/atdd_trace -b
For the DLKM driver:/opt/atdd/bin/atdd_trace -b
4. Start the operations on a tape device.
5. To display collected trace data in a readable format at any time:
For the Static driver:/opt/OMImag/bin/atdd_trace -d
For the DLKM driver:/opt/atdd/bin/atdd_trace -d
6. The atdd_trace output can be redirected to place the trace data in a readable
format into a file, by entering
For the PB driver:/opt/OMImag/bin/atdd_trace >trace.txt
For the PCI driver:/opt/atdd/bin/atdd_trace >trace.txt
7. In HP-UX 11i v3, the ATDD trace is logged in to syslog of /var/adm/syslog/
syslog.log when the kernel tunable of atdd_direct_trace is enabled. To set a
value (0 or 1) to atdd_direct_trace, run # kctune atdd_direct_trace=value. To
turn on the trace #kctune atdd_direct_trace=1 and set to 0 to turn off.

Problems and solutions


Table 12 describes problems and possible solutions for errors you might encounter
with the DLKM driver.
Table 12. Problems, reasons, and solutions
Problem

Reason and solution

The system hangs when it runs rmsf -H on HP-UX 11i.

DLKM Infrastructure does not set the correct flag in the


device switch table entry for a DLKM driver that uses.
Install HP patch PHKL_29818.

ATDD DLKM modules are not loaded in the running


The current kernel is not matching the symbol table
kernel.A message in the file /var/adm/syslog/syslog.log (DLKM) in /stand/dlkm
"vmunix: WARNING: modpath: DLKM is not initialized"

Must rebuild the kernel by running the following


commands:
#cd /stand/build
#/usr/lbin/sysadm/system_prep -s /stand/build/system
#/usr/sbin/mk_kernel -s /stand/build/system
#mv /stand/system /stand/system.prev
#mv /stand/build/system /stand/system
#kmupdate /stand/build/vmunix_test
#shutdown -ry now

A message in the file /var/adm/syslog/syslog.log


"modld: Attempt to load unregistered module "

ATDD DLKM Module's component files are not copied


to certain subdirectories of /usr/conf and /stand.
Remove ATDD and try to install it again.

# kmtune | grep atdd


kmtune: Cannot open file -- /stand/.kmsystune_lock

The file .kmsystune_lock was removed manually.


Use the following command to create the
.kmsystune_lock file again:
# touch /stand/.kmsystune_lock

70

IBM Tape Device Drivers Installation and Users Guide

Table 12. Problems, reasons, and solutions (continued)


Problem

Reason and solution

IBM tape devices not claimed in ioscan -fnk display

As "root", verify the drivers that are loaded in the


running kernel by using `kmadmin -s`.
If status is "LOADED", run 'atdd_claim -b' to claim all
IBM devices, run 'atdd_claim -t' to claim the tape
drives, then run 'atdd_claim -c' to claim the changers.
If status is "UNLOADED", run 'kmadmin -L atdd' to
load the ATDD, run 'kmadmin -L acdd' to load the
ACDD, then run 'atdd_claim' to claim the tape devices.
If status is still "UNLOADED", check the entries of the
files 'atdd' or 'acdd' in /etc/loadmods. If no atdd or acdd
file entries exist, the driver might be statically bound to
the kernel, or the ATDD package might not be installed.
Check the installation by running the following
command:
# swlist atdd

No special files that are found in /dev/rmt

Run the atdd_mksf and acdd (if you have changers that
are managed by the acdd driver) scripts that are found
in /opt/atdd/bin
atdd_mksf and acdd_mksf
Note: The script prints the commands that are necessary
to create the special files. To create the files you must
"pipe" the output to shell (sh), with the following
commands:atdd_mksf | sh acdd_mksf | sh.

The special files for a device are duplicates.

Remove all of the special files for the device in /dev/rmt


Create the special files again by running the commands
atdd_mksf or acdd_mksf.

No special files are created by HP Stape and Schgr after


ATDD is installed

Create the special files by running the command: # insf


-e.

Cannot open Special File and the system log has the
following message:

Wrong DENSITY setting. Check the current value by


running the command:atdd_cfg -g DENSITY Try setting
value to 0 (zero) by running the command: atdd_cfg -s
DENSITY 0.

Invalid SCSI request in data at bit 7 of byte 4


An attempt to read data times out and returns an error
and the system log has the following messages:
A SCSI command timed out and was aborted.

Make sure that the SILI configuration parameter is "1".


This configuration can be checked by running the
command: atdd_cfg -g SILI
If the value of SILI = 0, try setting the value to 1, by
running the following command: atdd_cfg -s SILI 1.

Table 13 describes problems and possible solutions for errors you might encounter
with the static driver.
Table 13. Troubleshooting (problems and solutions)
Problem

Solution

No special files that are found in /dev/rmt

Issue the following commands: /opt/OMImag/bincd


/opt/OMImag/binatdd_mksf | sh.

Chapter 3. HP-UX Tape and Medium Changer device driver

71

Table 13. Troubleshooting (problems and solutions) (continued)


Problem

Solution

If you are using the PB drivers or are not using the


standard device driver defaults with PCI drivers:

Verify that the hardware path for the device is listed in


the configuration file/etc/rc.config.d/atdd.cfg
If the hardware path is missing or incorrect, the driver
was not installed properly.

Claimed by HP Stape driver

Run the command: # lsdev to check that the atdd is in


the current kernel.
1. If the atdd is not in the output, rebuild the kernel or
reinstall atdd.
2. If the atdd is in the output a. Rebuild the system I/O configuration.
1) Remove /stand/ioconfig and /etc/ioconfig
after to back up the files.
2) Reboot the system.
3) On System Console, enter the command #
/sbin/ioinit -c while the autobooting is
halted.
4) Run the command: # /sbin/insf -e.
5) Enter the command: # ^D to exit the I/O
configuration.
b. Reinstall the HP-UX operating system if the
system is new or is a new update.

Cannot open Special File. The system log has the


following message:

Wrong DENSITY setting. Check the current value by:


atdd_cfg -g DENSITY <atdd_inst>

Invalid SCSI request in data at bit 7 of byte 4


Try setting it to 0 (zero):
atdd_cfg -s DENSITY 0 <atdd_inst>
An attempt to read data times out and returns an error.
The system log has the following messages:

Check that the SILI configuration parameter is 1 by


running

A SCSI command timed out and was aborted.

atdd_cfg -g SILI <atdd_inst>

LLIO: Detected PowerFail


(probably caused by SCSI bus or device reset).

If the SILI parameter is zero, try setting it to 1:


atdd_cfg -s SILI 1 <atdd_inst>

An attempt to read data times out and returns an error.


The system log has the following messages:

Check that the FORCE_NARROW parameter is valid for


this device by running

A SCSI command timed out and was aborted.

atdd_cfg -g FORCE_NARROW <atdd_inst>

scsi3: ....date code...


scsi3: ....timestamp...

72

IBM Tape Device Drivers Installation and Users Guide

If FORCE_NARROW is 1, try setting it to 0:


atdd_cfg -s FORCE_NARROW 0 <atdd_inst>

Chapter 4. Linux Tape and Medium Changer device driver


This chapter describes the IBM Linux Tape and Medium Changer device driver
(lin_tape).
For tape diagnostic and utility functions, refer to Chapter 8, IBM Tape Diagnostic
Tool (ITDT), on page 211.

Purpose
The lin_tape and medium changer device driver is designed to take advantage of
the features that are provided by the IBM tape drives and medium changer
devices. The goal is to give applications access to the functions required for basic
tape operations (such as backup and restore) and medium changer operations
(such as mount and unmount the cartridges), and also the advanced functions that
are needed by full tape management systems. Whenever possible, the driver is
designed to take advantage of the device features transparent to the application.

Data flow

Application
Program

IBMtape
Device
Driver

Host Bus
Adapter
Driver

Tape
Device

a250181

The software that is described in this chapter covers the Linux device driver
(lin_tape device driver) and the interface between the application and the tape
device.

Figure 11. Data flow for Linux device driver (lin_tape)

Product requirements
Hardware requirements
For current hardware requirements, refer to the Hardware requirements on page
xvii.

Software requirements
For current software requirements, refer to the Software requirements on page
xvii.

Installation and Configuration instructions


The lin_tape device driver for Linux is provided in a source rpm package. The
utility tools for lin_tape are supplied in binary rpm packages. Refer to
Appendix A, Accessing documentation and software online, on page 321. They
are downloaded with the driver.

Copyright IBM Corp. 2007, 2014

73

The following sections describe installation, configuration, uninstallation, and


verification procedures for lin_tape and its utility tools. Refer to Linux
documentation for tar command information and any Linux distribution that
support rpm for rpm command information. You must have root authority to
proceed with the installation of the driver. See the README file that can be
downloaded with the driver at Fix Central. For information about downloading
drivers, see Appendix A, Accessing documentation and software online, on page
321.
This file contains the latest driver information and supersedes the information in
this publication.

Conventions used
In subsequent pages, you see file names with x.x.x in them. The x.x.x refers to the
version of the driver, which changes as IBM releases new driver levels. Use the
actual driver version numbers as you complete the instructions.
Commands that you are to type are indicated with a leading ">" character, which
indicates the shell prompt.
Note: This procedure is run with tape diagnostic and utility functions. See
Chapter 8, IBM Tape Diagnostic Tool (ITDT), on page 211.

Configuration limitations
Maximum supported number of
tape devices

1024

Maximum supported number of


HBA ports

16 (8 dual-port, 4 quad-port)

Maximum supported number of


paths for a device (DPF/CPF)

16/16

Maximum LUNs per system

256

Every attached tape or library device uses a certain amount of resources. The user
must consider resources such as physical memory and virtual space on the system,
which might further limit the number of devices that can be attached.

Components created during installation


The lin_tape package consists of the device driver and a number of associated files.
Components that are created during lin_tape installation (from the rpm package)
are listed in Table 14.
Table 14. Linux: Components created during lin_tape installation

74

Component

Description

/lib/modules/(Your system's kernel


name)/kernel/drivers/scsi/lin_tape.ko

Device driver module for current kernel


version

/usr/bin/lin_taped

lin_taped daemon

/etc/lin_taped.conf

lin_taped daemon configuration file

IBM Tape Device Drivers Installation and Users Guide

Table 14. Linux: Components created during lin_tape installation (continued)


Component

Description

/usr/share/doc/lin_tape-xxx/
lin_tape_359X.Readme (for Red Hat)

Readme file for lin_tape with IBM devices

/usr/share/doc/packages/lin_tape/
lin_tape_359X.Readme (for SUSE LINUX)
Readme file for lin_taped daemon

/usr/share/doc/lin_tape-xxx/
lin_taped.Readme (for Red Hat)
/usr/share/doc/packages/lin_tape/
lin_taped.Readme (for SUSE LINUX)

/usr/share/doc/lin_tape-xxx/copying (for Red License documentation for lin_tape


Hat)
/usr/share/doc/packages/lin_tape/copying
(for SUSE LINUX)

Installation procedure
If lin_tape is already installed on your system, refer to the Updating procedure
on page 76. This section assumes that you are installing the lin_tape device driver
onto a system where it is not currently installed.
If you are installing lin_tape on a system that is running Linux for S/390 or
Linux for zSeries, ensure that the OpenFCP adapter device driver zfcp is loaded in
the kernel. Refer to Configuring Tape and Medium Changer devices on IBM
System z models on page 77 for how to configure and install zfcp.
Make sure that the C/C++ development and kernel development packages are
installed on your system. To install the lin_tape driver with all the added value of
the lin_taped daemon, complete the following steps.
1. Download the appropriate level of the source RPM package to a directory of
your choice on the Linux kernel for which you want to install it.
2. Run rpmbuild --rebuild <filename>, where: <filename> is the name of the RPM
file. A binary RPM package is created for your kernel from the source RPM
package. For example,
>rpmbuild --rebuild lin_tape-1.x.x.x.0-1.src.rpm

3. Output from the build is printed to your screen. Near the end of the output, a
line indicates the file name and location of your binary RPM package. For
example, a line similar to the following is output to your screen.
Wrote: /usr/src/redhat/RPMS/i386/lin_tape-1.x.x.x.0-1.i386.rpm

4. To install the lin_tape driver from the binary package, run >rpm -ivh
<filename> For example,
>rpm -ivh /usr/src/redhat/RPMS/i386/lin_tape-1.x.x.x.0-1.i386.rpm

5. To install the lin_taped daemon, download it to your Linux file system and run
rpm -ivh on the daemon RPM file. For example,
>rpm -ivh /usr/src/redhat/RPMS/i386/lin_taped-1.x.x.x.0-rhel5.i386.rpm

Chapter 4. Linux Tape and Medium Changer device driver

75

Updating procedure
If your current lin_tape device driver was installed from a rpm package
previously, you can uninstall the driver first, then install the newer version. For
example,
>rpm -e lin_taped
>rpm -e lin_tape
>rpmbuild --rebuild lin_tape.x.x.x.i386.rpm
>rpm -i lin_tape.x.x.x.i386.rpm
Note: All tape devices that use the lin_tape device driver must be closed and
cannot be in use when lin_tape is uninstalled.

Querying the installed package


The query is supported for the lin_tape device driver rpm package only.
The installed rpm package can be queried by running the following commands to
show information that is associated with the package.
To show information about lin_tape >rpm -qi lin_tape
To show the file list, enter the command
>rpm -ql lin_tape
To show the states of files in the package, for example, normal, not installed, or
replaced >rpm -qs lin_tape

Configuring Tape and Medium Changer devices on


Intel-compatible systems
If you did not physically attach your tape and medium changer devices to your
Linux server, complete the following steps.
1. Halt the Linux server.
2. Power down the Linux server.
3. Physically attach the tape and medium changers to the host bus adapter cards.
Consult your hardware documentation for details.
4. Power on the tape and medium changer devices. Verify that they complete the
initialization process.
5. Power on and boot the Linux server.
Note: Hot plugging SCSI devices while the Linux server is running can cause
hardware damage.
After the driver software is installed and a tape device is connected to the adapter,
the device can be configured and made available for use. Access to the device is
not provided until the device is configured.

76

IBM Tape Device Drivers Installation and Users Guide

If your system is attached to an IBM 3583 tape library with the integrated router,
before the QLogic driver is installed, set the host type of the router to solaris and
make sure that the logical unit numbers of the control unit, medium changer, and
the connected tape drives are contiguous. Otherwise, the QLogic device driver
does not recognize all of the attached devices. To view the LUNs of attached
devices, log on to the router and use the fcShowDevs command. If the LUNs are
not contiguous, use the mapCompressDatabase command to delete the invalid LUNs
and make the valid LUNs contiguous.
When you run the lin_tape kernel module, it creates special files in the /dev
directory.

Configuring Tape and Medium Changer devices on IBM


System p models
Follow the same instructions as documented in the previous section. You must
configure the Emulex Linux device driver if you have Fibre Channel tape devices
that are attached to your System p (also known as pSeries) system.

Configuring Tape and Medium Changer devices on IBM


System z models
The Fibre Channel topology that is supported for System z is point-to-point and
fabric. Refer to the Linux on System z Fibre Channel documents for details on the
supported configurations for Fibre Channel device attachment. The Linux Fibre
Channel adapter device driver zfcp is available in the kernel that supports zSeries
Fibre Channel Protocol. The zfcp device configuration methods in 2.6 and 2.4
kernels are different. For 2.6 kernels, refer to appropriate chapter in the Linux on
System z document entitled Linux on System z: Device Drivers, Features, and
Commands.
For 2.4 kernels, there are three ways to load the zfcp device driver to see the
attached tape devices.
1. Create a /etc/zfcp.conf file and make a ramdisk to statically attach tape devices
into your system. You can use this method only if you have a persistent
mapping in a SAN environment. Every time that you reboot the system, the
zfcp is automatically loaded and the tape devices can be seen from the system.
You must add the device map into this file. The following is an example of
zfcp.conf.
0xf1c0 0x1:0x5005076300402733 0x0:0x0000000000000000;\
0xf1c1 0x1:0x5005076300402733 0x0:0x0001000000000000

The zfcp device driver uses the "map" module parameter to recognize a
physically attached tape device. map takes the following format,
map="<devno><port scsi-id>:<wwpn><unit-scsi-lun>:<fcp-lun>;...."

Where
devno The device number of the host bus adapter (16 bits, see
/proc/subchannels). It is 0xf1c0 or 0xf1c1 in the previous example.
port scsi-id
Linux internal SCSI ID assigned to the Fibre Channel port of the SCSI

Chapter 4. Linux Tape and Medium Changer device driver

77

target device (32-bit, must not be 0, must be a unique one-to-one


mapping for each worldwide port name. It is 0x1 in the previous
example.
wwpn Worldwide port name that identifies the Fibre Channel port of the SCSI
target device (64-bit). It is 0x5005076300402733 in the previous example.
unit scsi-lun
Linux internal SCSI Logical Unit Number (32-bit). It is 0x0 in the
previous example.
fcp-lun
Logical Unit Number that is associated with the SCSI target device
(64-bit). In the previous example, 0x0000000000000000 is the Logical
Unit Number 0, and 0x0001000000000000 is the Logical Unit Number 1.
For tape attachment, each logical unit number must be associated with a
unique devno. If you use the same devno numbers for several logical units,
you can ensure that each <unit-scsi-lun> is unique. After /etc/zfcp.conf is
created, run the following commands.
>mk_initrd>zipl

Then, reboot the system. After it is booted up, your tape device must be shown
in /proc/scsi/scsi file.
2. Modify the /etc/modules.conf file to add the zfcp module parameters; then run
the depmod A and modprobe zfcp command.
Note: Do not use this choice together with the first one, otherwise it causes
conflicts.
The zfcp map in /etc/modules.conf always takes higher priority than the map
in /etc/zfcp.conf.
The following example demonstrates the zfcp configuration in
/etc/modules.conf.
options zfcp map="\
0xf1c0 0x1:0x5005076300402733 0x0:0x0000000000000000;\
0xf1c1 0x1:0x5005076300402733 0x0:0x0001000000000000"

The map arguments are the same as the ones listed in for the /etc/zfcp.conf file.
After the /etc/modules.conf file is modified, save and close it. Then, run the
following command.
>depmod -A
>modprobe zfcp

This action installs the zfcp device driver and all of its prerequisite kernel
modules. Now you can check the file /proc/scsi/scsi to see if all of the attached
tape devices are shown in this file. If not, then check the Fibre Channel
connection, such as the fibre cables, or if the devices are powered on.
Then, run the following commands to install zfcp.
>rmmod zfcp
>modprobe zfcp

3. Run the modprobe zfcp command first, then dynamically add a tape device into
the system after you physically attach a Fibre Channel tape device to the
switch.
If you physically attach a tape device on the switch and zfcp is already loaded,
you do not need to reboot the Linux system to add this entry in the
/proc/scsi/scsi file. The zfcp device driver provides an "add_map" proc system
entry under the directory /proc/scsi/zfcp to dynamically add the device into the

78

IBM Tape Device Drivers Installation and Users Guide

system. For example, to add two logical units from the example in Step 2 into
the system, you can issue the following commands.
> echo "0xf1c0 0x1:0x5005076300402733 0x0:0x0000000000000000;\
0xf1c1 0x1:0x5005076300402733 0x0:0x0001000000000000"
> /proc/scsi/zfcp/add_map
> echo "scsi add-single-device 0 0 1 0" > /proc/scsi/scsi
> echo "scsi add-single-device 1 0 1 1" > /proc/scsi/scsi
The scsi add-single-device takes four parameters, corresponding to the four
parameters scsi, Channel, Id, and Lun in the /proc/scsi/scsi file. The value of
scsi is 0 for the first devno, 1 for the second devno (if it is different from the
first devno), and so on. The value of Channel can start from 0 for each different
scsi value. The value of Id is the one you use for <unit scsi-lun> in the
previous mapping. The value of Lun is the logical unit number of the target
device, for example, the last number in the previous mapping. Currently, the
zfcp device driver does not support dynamically removing the attached
devices. If you must remove the tape devices from the system, do rmmod zfcp.
Then, you can delete the entry in /etc/modules.conf and reload zfcp, or reload
zfcp first and dynamically add the devices that you want. After you finished
all the mapping, if you can see all of the attached tape devices in
/proc/scsi/scsi, you successfully attached those devices to your system. Next,
you can install the lin_tape device driver. Refer to the Installation procedure
on page 75 section for the instructions on how to install lin_tape.

Uninstallation procedure
Note: All tape devices that use the lin_tape driver must be closed and cannot be
in use when lin_tape is uninstalled or the uninstall fails.
Run the following command.
>rpm -e lin_tape

Tape drive, media, and device driver parameters


This chapter describes the parameters that control the operating modes of the IBM
Linux Tape and Medium Changer device driver.

Configuration parameters
The configuration parameters are used to set the operating mode of the tape drive
and device driver when a device is opened. The installation defaults are provided
for all parameters initially. These parameters are kept on reopen, but are always
restored back to the default values when the lin_tape device driver is reinstalled.
Note: This procedure is completed with tape diagnostic and utility functions. See
Chapter 8, IBM Tape Diagnostic Tool (ITDT), on page 211.
The nonchangeable configuration parameters are
v Autoloading
v Density code
v Emulate autoloader
v Hook word
Chapter 4. Linux Tape and Medium Changer device driver

79

v
v
v
v
v

Maximum block size


Minimum block size
Medium type
Read SILI bit
Record space mode

v Volume ID for logging


v Write protect
The changeable configuration parameters are
v Barcode length
v Block size
v Buffered mode
v Capacity scaling
v
v
v
v
v

Compression
Disable auto drive dump
Disable SIM logging
Dynamic attributes
Logging

v Logical write protect


v Maximum SCSI transfer length
v Read past filemark
v
v
v
v

Rewind immediate
Trace
Trailer labels
Busy Retry

Nonchangeable parameters
The configuration parameters are used to set the operating mode of the tape drive
and device driver when a device is opened. The nonchangeable parameters are
detailed as follows.

Autoloading
This parameter enables the autoloading feature of the device driver. It is disabled
by default and cannot be changed.

Capacity scaling
This parameter sets the capacity or logical length of the current tape. By reducing
the capacity of the tape, the tape drive can access data faster at the expense of data
capacity. Capacity scaling is not supported currently but might be supported in
future releases of lin_tape.

Density code
This parameter is the density setting for the currently loaded tape. Some tape
devices support multiple densities and report the current setting in this field. It
cannot be changed by the application.

80

IBM Tape Device Drivers Installation and Users Guide

Emulate autoloader
This parameter currently is not supported and is ignored.

Hook word
This parameter is not supported in the lin_tape device driver.

Logical write protect


This parameter sets or resets the logical write protect of the current tape. This
feature is not supported currently but might be supported in future releases of the
lin_tape.

Maximum block size


This parameter is the maximum block size for the device.

Minimum block size


This parameter is the minimum block size for the device.

Medium type
This parameter is the media type of the current loaded tape. Some tape devices
support multiple media types and different values are reported in this field.

Read SILI bit


SILI bit currently is not supported due to limitations associated with the Linux
environment. SILI bit support can be enabled in future releases of the lin_tape.

Record space mode


This parameter specifies how the device driver operates when a forward or
backward space record operation encounters a filemark. Only the SCSI mode is
supported by lin_tape. When a forward or backward space record operation is
issued to the driver and a filemark is encountered, the device driver returns -1 and
the errno variable is set to input/output error (EIO). On the forward space
operation, the tape is left-positioned after the filemark (the end of tape side of the
filemark). On the backward space operation, the tape is positioned before the
filemark (the beginning of tape side of the filemark).

Volume ID for logging


This parameter is the volume ID of the currently loaded tape. The lin_tape device
driver ignores this field.

Write protect
This parameter is set to TRUE if the currently mounted tape is logically or
physically write protected.

Chapter 4. Linux Tape and Medium Changer device driver

81

Changeable parameters
The configuration parameters are used to set the operating mode of the tape drive
and device driver when a device is opened. The changeable parameters are
detailed as follows.

Barcode length
This parameter can be set to change the barcode length for a cartridge. For LTO
cartridges the default is 8. It can be changed to 6 for LTO 1 and LTO 2 generation
cartridges only. For 3592 cartridges the default is set at 6. It can be changed to 8. In
the /etc/modprobe.conf.local file the following line must be added to reflect the
desired change.
options lin_tape ibm3592_barcode=8
options lin_tape lto_barcode=6

Stop and start the driver by running these commands.


>lin_taped stop
>rmmod lin_tape
>depmod
>modprobe lin_tape (reinstall back)
>lin_taped (restart the daemon)

Block size
This parameter specifies the block size that is used for read and write operations.
A value of zero means a variable block size. Any other value is a fixed block size.
The installation default is zero (variable length block size). Refer to Maximum
SCSI transfer length on page 84 for guidance.

Buffered mode
This parameter specifies whether read and write operations must be buffered by
the tape device. The default (recommended) value is TRUE.

Capacity scaling
This parameter sets the capacity or logical length of the current tape on Enterprise
Tape System 3590 or 3592 tape subsystems. By reducing the capacity of the tape,
the tape drive can access data faster at the expense of data capacity. Capacity
scaling can be set at 100% for the entire tape (which is the default), or set at 75%,
50%, or 25% of the 3590 tape cartridge and more available capacity scaling for the
3592 standard 300 GB rewritable data cartridge. Capacity scaling remains with the
tape across mounts until it is changed.
Note:
1. The tape position must be at the start of the tape to change this
parameter from its current value.
2. Changing this parameter destroys any existing data on the tape.
3. For 3592 media types, capacity scaling is supported only for the standard
300 GB rewritable data cartridge. Attempting to set capacity scaling that
is not supported by a device or the current loaded media always returns
100% and cannot be changed. For example, the 60 GB (Economy Data)
cartridge for the IBM 3592 cannot be capacity-scaled and is always 100%.

82

IBM Tape Device Drivers Installation and Users Guide

Compression
Hardware compression is implemented in the device hardware. This parameter
turns the hardware compression feature On and Off. If compression is enabled, the
effective performance can increase, based on the compressibility of the data.
The installation default is On (use compression).

Disable auto drive dump


This parameter is provided in the lin_tape version 1.2.2 or later. It is set to FALSE
by default. If it is FALSE and the lin_taped daemon is running and if an error
occurs in the drive that creates a drive dump, the lin_tape device driver
automatically retrieves the drive dump and saves it under the /var/log directory
by default. You can specify another directory in the /etc/lin_taped.conf file. The
dump is labeled with a .dmp extension on the file. Refer to Configuring and
running the lin_taped daemon on page 96 for details.

Disable SIM logging


This parameter is provided in the lin_tape version 1.2.2 or later. It is set to FALSE
by default. If it is FALSE and the lin_taped daemon is running and SIM/MIM data
is generated by the drive, the lin_tape device driver automatically retrieves the
data and saves it in a formatted text file under the /var/log directory by default.
You can specify another directory in the /etc/lin_taped.conf file. Refer to
Configuring and running the lin_taped daemon on page 96 for details.
This capacity is not applicable to IBM Ultrium tape drives.

Dynamic attributes
This parameter determines whether dynamic runtime attributes are attempted on
open for supported drives. Default is 1 (on) meaning that the driver automatically
attempts to set dynamic runtime attributes on open. This parameter can be
changed to 0 (off) in the configuration file before the lin_tape is loaded. It is
recommended to keep on dynamic attributes unless it produces an unexpected
problem in the environment.

Logging (volume logging)


This parameter turns the volume information logging On or Off. With the lin_tape
version 1.2.2 and later, the lin_tape device driver provides this support. It is set to
On by default. If logging is On and the lin_taped daemon is running, the lin_tape
device driver retrieves the full log sense data from the drive whenever a tape is
unloaded, or the drive reaches a log threshold. The log file is saved in binary
format under the directory /var/log by default. You can specify another directory
in /etc/lin_taped.conf file. Refer to Configuring and running the lin_taped
daemon on page 96 for details.
Note: This parameter is volume logging, which is different from error logging.
lin_tape provides error logging whenever the lin_taped daemon is running.
Refer to Configuring and running the lin_taped daemon on page 96 for
details on error logging.

Chapter 4. Linux Tape and Medium Changer device driver

83

Logical write protect


This parameter sets or resets the logical write protect of the current tape on
Enterprise Tape System 3590 tape subsystems. The three types of logical write
protect are associated protect, persistent protect, and write-once read-many
(WORM) protect.
1. Associated protect remains only while the current tape is mounted or
associated with the tape drive. It is reset when the tape is unloaded or the tape
drive is reset.
2. Persistent protect remains or persists with the tape across mounts until it is
reset.
3. WORM protect also remains with the tape across mounts, but unlike persistent
protect it cannot be reset on the tape. After a tape is WORM protected, it can
never be written on again.
Note: The tape position must be at the start of the tape to change this parameter
from its current value.

Maximum SCSI transfer length


In the lin_tape drivers with level lower than 3.0.3, the maximum transfer length
per device per SCSI command is 262144 bytes (256 KB) by default. Variable block
read/write requests with transfer length greater than the maximum transfer length
fails [errno: EINVAL]. When a fixed block size is defined, large write requests are
subject to both the granularity of the block size and the maximum transfer length.
For example, with a fixed block size of 80000 bytes and maximum transfer length
of 262144, a write request for 400000 bytes (5 blocks of 80000 each) is written to
tape in two transfers. The first transfer is 240000 bytes (3 blocks) and the second
transfer is 160000 (the remaining two blocks). You can increase the maximum
transfer length to enhance the data throughput. This procedure can be done with
ITDT with the Query/Set Parameters option, or a customized STIOCSETP
input/output control (ioctl) call. However, setting the transfer length greater than
the default 256 KB does not guarantee a noticeable increase in data throughput.
Maximum transfer length of 256 KB is highly recommended.
In lin_tape driver with level 3.0.5 or higher and the open source driver lin_tape,
the maximum transfer length is defined as the minimum length that the host bus
adapter and the tape drive can support. This number is greater than 256 KB. It
cannot be changed by the STIOCSETP ioctl call any more.

Read past filemark


If this parameter is set to true, when a fixed-length read operation encounters a
filemark, it returns the number of bytes read before the filemark is encountered
and positions the tape head after the filemark. If the read_past_filemark
parameter is set to false, when the fixed-length read operation encounters a
filemark, if data was read, the read function returns the number of bytes read, and
positions the tape head before the filemark. If no data was read, then the read
returns 0 bytes read and positions the tape head after the filemark.
This installation default is FALSE.

84

IBM Tape Device Drivers Installation and Users Guide

Rewind immediate
This parameter sets the immediate bit for rewind commands. If it is set to On, the
rewind tape operation runs faster, but the next command takes a long time to
finish unless the physical rewind operation is complete. Setting this parameter
reduces the amount of time it takes to close a device for a Rewind on Close special
file.
The installation default is Off (no rewind immediate).

Trace
This parameter turns the trace facility On or Off. With the lin_tape version 1.2.2
and later, the lin_tape device driver provides this support. It is set to On by
default. If trace is On and the lin_taped daemon is running, the lin_tape device
driver retrieves the trace from the driver if trace level is set to 1 or 2 in the
/etc/lin_taped.conf file. The trace file is saved under the directory /var/log by
default. You can specify another directory in /etc/lin_taped.conf file. Refer to
Configuring and running the lin_taped daemon on page 96 for details.

Trailer labels
If this parameter is set to On, then writing records past the early warning mark on
the tape is allowed. The first write operation after detecting the early warning
mark fails and the errno variable is set to ENOSPC. No data is written during the
operation. All subsequent write operations are allowed to continue until the
physical end of the volume is reached and errno EIO is returned.
If this parameter is set to Off, then writing records past the early warning mark is
not allowed. Errno variable is set to ENOSPC.
The installation default is On (with trailer labels).
|

Busy Retry

|
|
|

The parameter busy_retry determines how many times to retry a command when
the device is busy. Default is 0 (off), and can be set up to 480 in the configuration
file before the lin_tape is loaded.

Special files
After the driver is installed and a device is configured and made available for use,
access is provided through the special files. These special files, which consist of the
standard Linux special files for devices, are in the /dev directory.

Special files for the tape device


Each tape device has a set of special files providing access to the same physical
drive but providing different attributes. Table 15 on page 86 shows the attributes of
the special files.
Note: The asterisk (*) in IBMtape* represents a number assigned to a particular
device, such as IBMtape0.

Chapter 4. Linux Tape and Medium Changer device driver

85

For tape drives with attached medium changer devices, the IBMchanger* special
file provides a separate path for issuing commands to the medium changer. When
this special file is opened, the application can view the medium changer as a
separate device. Both the tape and changer special file can be opened at the same
time.
Table 15. Linux: Special files for IBM tape devices
Special file name

Rewind on Close

/dev/IBMTape*

YES

/dev/IBMTape*n

NO

Special files for the Medium Changer device


After the driver is installed and a medium changer device is configured and made
available for use, access to the robotic device is provided through the IBMchanger
special file in the/dev directory. The asterisk (*) represents a number that is
assigned to a particular device, such as IBMchanger0. The term IBMchanger is used
for a SCSI medium changer device. The IBMchanger* special file provides a path
for issuing commands to control the medium changer robotic device.
The file descriptor that results from opening the IBMchanger special file does not
support the following operations.
v
v
v
v

Read
Write
Open in Append mode
Commands that are designed for a tape device

Persistent Naming Support


Lin_tape Persistent Naming is implemented through the Linux udev utility. Udev
is a service that monitors changes in system hardware configuration and completes
actions that are based on what devices are attached to the Linux system. It can be
configured to create symbolic links (persistent names) to a device based on
attributes that a driver exports for that device. The persistent name can then be
used as the device name to open and complete IO to a tape drive or medium
changer. This action makes it possible to reference a static name, such as
/dev/lin_tape/by-id/lin_tape4801101

This name is always associated with the same physical device, rather than being
required to reference the device name /dev/IBMtape0, which can change names
and become /dev/IBMtape1 after the driver is reinstalled.
Lin_tape exports several attributes that can be used as the basis to create persistent
names. These attributes can be reported to the user through udevadm info on
recent Linux kernels, or udevinfo on older Linux kernels. The udevinfo and
udevadm are udev management tools. These tools can query the udev database for
device information and properties that are stored in the udev base for help
creating udev rules.
Note: Udev, udevinfo, and udevadm are not implemented or maintained by the
lin_tape driver. Refer to the man pages for udevadm or udevinfo for details
on usage. These man pages are system specific and supersede all

86

IBM Tape Device Drivers Installation and Users Guide

information in this document. For questions on these utilities, you must


contact your Linux support representative.
An example is provided on udev for implementing a persistent name. The example
must be customized to fit a users needs and environment.
Note: Variations exist between kernels.
If a tape device is attached to the Linux system with worldwide port name
0x123456789ABCDEF0 with a current device name of /dev/IBMtape0, a user can run
udevadm information to obtain information on exported attributes for this device.
This procedure can be done as follows,
>udevadm info --attribute-walk --name /dev/IBMtape0

The output of this command includes something similar to


ATTRS{serial_num}=="123456789"
ATTRS{ww_node_name}=="0x123456789ABCDEF1"
ATTRS{ww_port_name}=="0x123456789ABCDEF0"

If you are using udevinfo, enter the previous command as


>udevinfo -a -p `udevinfo -q path -n /dev/IBMtape0`
or
>udevinfo -a -p /sys/class/lin_tape/IBMtape0
(Both commands return the same information).
Also, on some kernels an attribute ATTRS{xxx} is replaced by SYSFS{xxx}.
Furthermore, some kernels use a '=' (single equal sign) to indicate an attribute
match and also an assignment. Whereas, other kernels use a '==' (double equal
sign) for a match and '=' for assignment. Place the attribute from the attribute list
into your rules file exactly as it appears in the attribute list, as described here.
The ww_port_name is in a rules file that assigns a symbolic link to a device that
has the listed worldwide port name. The file typically is placed in
/etc/udev/rules.d, but this location might be changed by the udev_rules directive
in the /etc/udev/rules.conf file. In this example, a file is created that is called
/etc/udev/rules.d/98-lin_tape.rules and write a single line to the file.
KERNEL=="IBMtape*", ATTRS{ww_port_name}=="0x123456789ABCDEF0",
SYMLINK="lin_tape/by-id/lin_tape4801101"

Assuming that the udev service is running and configured correctly, the user can
install or reinstall lin_tape with modprobe, and the symbolic link is created in the
/dev/lin_tape/by-id folder. One line must be added to the 98-lin_tape.rules file for
each wanted symbolic link.
With lin_tape version 2.2.0, a parameter, persistent_n_device, is added to support
persistent naming of no rewind devices. The default value is 0 (off). To enable this
support, complete the following steps.
1. Modify the 98-lin_tape.rules file to differentiate standard devices and no
rewind devices. For example,
KERNEL=="IBMtape*[0-9]", ATTR{serial_num}=="1013000306", SYMLINK="lin_tape/by-id/IBMtape0"
KERNEL=="IBMtape*n", ATTR{serial_num}=="1013000306", SYMLINK="lin_tape/by-id/IBMtape0n"

2. Stop the lin_taped daemon.


lin_taped stop

3. Unload the lin_tape driver from the memory.


Chapter 4. Linux Tape and Medium Changer device driver

87

modprobe -r lin_tape

4. Add the following line in your /etc/modprobe.conf or /etc/modprobe.conf.local


file (or, if you are running RHEL 6 or higher, in your /etc/modprobe.d/
lin_tape.conf file).
options lin_tape

persistent_n_device=1

5. Reload the lin_tape driver into memory.


modprobe lin_tape

Note: Wait at least 10 seconds between step 3 (modprobe -r lin_tape) and step
5 (modprobe lin_tape) in order for udev to correctly configure the
devices.
6. Check that the devices are all correctly listed with the following command.
ls -l /dev/lin_tape/by-id/

7. Restart the lin_taped daemon.


lin_taped

Control Path failover support for tape libraries


Note: The library control path failover feature code must be installed before
control path failover support is enabled in the Linux lin_tape device driver.
Refer toAutomatic failover on page 1 to determine which feature code is
required for your machine type.
The Linux lin_tape device driver control path failover support configures multiple
physical control paths to the same logical library within the device driver. It also
provides automatic failover to an alternative control path when a permanent error
occurs on one path. This support is transparent to the running application.

Configuring and unconfiguring path failover support


Control path failover support is not enabled automatically when the device driver
is installed. The Linux lin_tape device driver provides a driver parameter
alternate_pathing for you to enable the library control path failover. To enable the
failover support in the lin_tape device driver software, you must do the following
steps after the lin_tape rpm package is installed:
1. lin_taped stop (stop the lin_taped daemon)
2. rmmod lin_tape (unload the lin_tape driver from the memory)
3. Add the following line in your /etc/modprobe.conf or /etc/modprobe.conf.local
file (or, if you are running RHEL 6 or higher, in your /etc/modprobe.d/
lin_tape.conf file)
options lin_tape alternate_pathing=1

4. depmod
5. modprobe lin_tape (reload the lin_tape driver into memory)
6. lin_taped (restart lin_taped daemon)
You can ignore the Unresolved symbols in /lib/modules/<your kernel
name>/drivers/scsi/lin_tape.ko message after the depmod command. You can
check whether the lin_tape driver recognized multiple control paths for your
library by reading the /proc/scsi/IBMchanger file.
v cat/proc/scsi/IBMchanger

88

IBM Tape Device Drivers Installation and Users Guide

If your library lists "Primary" or "Alternate" under "FO Path", you successfully
enabled the control path failover feature for your library. If "NA" is listed under
"FO Path", then the control path failover is not enabled. After control path failover
support is enabled, it remains set until the lin_tape driver is reloaded with the
alternate_pathing driver parameter set to OFF. The path failover setting is
retained even if the system is rebooted. If you want to turn off the control path
failover feature in the lin_tape device driver, you can complete the following steps.
1. lin_taped stop
2. rmmod lin_tape
3. Delete the following line in your /etc/modprobe.conf file.
options lin_tape alternate_pathing=1

4. depmod
5. modprobe lin_tape
6. lin_taped

Primary and alternative paths


When lin_tape is loaded into kernel memory, the first logical medium changer
device that lin_tape sees in the system is the primary path for that medium
changer. The other logical medium changers that lin_tape attached for the same
medium changer are configured as alternative paths. The device driver supports
up to 16 physical paths for a single device. The primary and alternative path
information can be obtained by the following command.
v cat /proc/scsi/IBMchanger
The following is an example of a /proc/scsi/IBMchanger file.
v lin_tape version: 3.0.3
v lin_tape major number: 253
Table 16. Attached changer devices
Number
Model
0
03584L22
1
03584L22
2
03584L22

SN
IBM1234567
IBM1234567
IBM1234567

HBA
qla2xxx
qla2xxx
qla2xxx

FO Path
Primary
Alternate
Alternate

The labeling of a logical device as either a primary or alternative path is for


information only, to
v Identify the actual number of physical devices that are configured on the system
and a specific logical device that is associated with them. Only one logical
device is labeled as the primary path for each physical device. However,
multiple logical devices can be labeled as an alternative path for the same
devices.
v Provide information about which logical devices configured on the system have
path failover support enabled.

Querying primary and alternative path configuration


You can show the primary and alternative path configuration for all devices by
reading the /proc/scsi/ IBMchanger file, as explained in Primary and alternative
paths.

Chapter 4. Linux Tape and Medium Changer device driver

89

Note: Show the primary and alternative path configuration for any device with
tape diagnostic and utility functions. Refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Disabling and enabling primary and alternative paths


When you load the lin_tape device driver with the alternate_pathing parameter
to be ON, by default, all the available paths for a physical device are enabled.
If it is necessary to disable a path and not run path failover (for example, because
of maintenance), run commands to disable and then later enable the primary and
alternative paths.
The commands to enable and disable primary and alternative paths are tape
diagnostic and utility functions.
Note: See Chapter 8, IBM Tape Diagnostic Tool (ITDT), on page 211.

Data Path failover and load balancing support for tape drives
Data path failover support is not enabled automatically when the device driver is
installed. The Linux lin_tape device driver provides a driver parameter
alternate_pathing for you to enable the data path failover.
To enable the failover support in the lin_tape device driver software, you must
complete the following steps after the lin_tape rpm package is installed.
>lin_taped stop (stop the lin_taped daemon)
>rmmod lin_tape (unload the lin_tape driver from the memory

If you have IBM 3592 tape drives, add the following line in your
/etc/modprobe.conf or /etc/modprobe.conf.local file (or, if you are running RHEL 6
or higher, in your /etc/modprobe.d/lin_tape.conf file).
options lin_tape alternate_pathing=1

If you have IBM LTO tape drives, the library must have a path failover feature
code. The data path failover license keys are needed to enable the failover if you
are running LTO2 drives or if you are running LTO3 drives with old levels of drive
code. DPF keys do not need to be added if you are running the latest drive code
on LTO3 or higher drives.
Add the following line in your /etc/modprobe.conf or /etc/modprobe.conf.local file
(or, if you are running RHEL 6 or higher, in your /etc/modprobe.d/lin_tape.conf
file).
options lin_tape alternate_pathing=1 dpf_keys="abcdefghijklmnop"

abckdefghijklmnop is an example of a data path failover feature key. If you have


multiple libraries and multiple data path failover feature keys, input your keys as
follows.
dpf_keys="key1;key2;..."

Save the file, then run the following commands.


>depmod
>modprobe lin_tape (re-load the lin_tape driver into memory)
>lin_taped (re-start lin_taped daemon)

90

IBM Tape Device Drivers Installation and Users Guide

You can ignore the Unresolved symbols in /lib/modules/<your kernel


name>/drivers/scsi/lin_tape.ko message after the depmod command. You can
check if the lin_tape driver recognized multiple paths for your tape drive by
reading the /proc/scsi/IBMtape file.
>cat /proc/scsi/IBMtape

If your tape drive lists "Primary" or "Alternate" under "FO Path", you successfully
enabled data path failover feature for your tape drive. If it is "NA" listed under
"FO Path", then the data path failover is not enabled. After the path failover
support is enabled, it remains set until the lin_tape driver is reloaded with the
alternate_pathing driver parameter set to OFF. The path failover setting is
retained even if the system is rebooted. If you want to turn off the data path
failover feature in the lin_tape device driver, you can run the following steps.
>lin_taped stop
>rmmod lin_tape

Delete the following line in your /etc/modules.conf file: options lin_tape


alternate_pathing=1.
>depmod
>modprobe lin_tape
>lin_taped

Primary and alternative paths


When the lin_tape device driver is loaded into kernel memory with path failover
support enabled, the first logic device that lin_tape sees always becomes the
primary path. The other logical devices that lin_tape sees are configured as the
alternative paths. The device driver supports up to 16 physical paths for a single
device.
The primary and alternative path information can be obtained by the following
command.
>cat /proc/scsi/IBMtape

The following is an example of a /proc/scsi/IBMtape:


lin_tape version: 3.0.3
lin_tape major number: 253
Table 17. Attached tape devices
Number

Model

SN

HBA

FO Path

03592

IBM1234567

qla2xxx

Primary

03592

IBM1234567

qla2xxx

Alternate

The labeling of a logical device as either a primary or alternative path is for


information only to
v Identify the actual number of physical devices that are configured on the system
and a specific logical device that is associated with them. Only one logical
device is labeled the primary path for each physical device. However, many
(multiple) logical devices can be labeled as an alternative path for the same
devices.
v Provide information about which logical devices configured on the system have
path failover support enabled.

Chapter 4. Linux Tape and Medium Changer device driver

91

Querying primary and alternative path configuration


You can show the primary and alternative path configuration for all devices by
reading the /proc/scsi/IBMtape file, as explained in Primary and alternative
paths on page 91.
Note: Show the primary and alternative path configuration for any device with
tape diagnostic and utility functions. Refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Disabling and enabling primary and alternative paths


If it is necessary to disable a path and not run path failover (for example, because
of maintenance), run commands to disable and then enable the primary and
alternative paths.
The commands to enable and disable primary and alternative paths are tape
diagnostic and utility functions.
Note: See Chapter 8, IBM Tape Diagnostic Tool (ITDT), on page 211.

Tape Reserve Type


This parameter causes lin_tape to issue SCSI-3 persistent reserves to a tape drive
whenever a reservation is attempted. Persistent reserves are automatically issued if
data path failover is used, and therefore setting the parameter is unnecessary. This
parameter can be set only when lin_tape is installed. To set it, add the following
line to /etc/modprobe.conf or /etc/modprobe.conf.local (or, if you are running
RHEL 6 or higher, to /etc/modprobe.d/lin_tape.conf).
options lin_tape tape_reserve_type=persistent

Note: When a Linux TSM library manager is used with lin_tape, the special device
file /dev/TSMtape needs to have the same TSM user permissions as other
lin_tape devices. See Configuring Tape and Medium Changer devices on
Intel-compatible systems on page 76, Configuring Tape and Medium
Changer devices on IBM System p models on page 77, or Configuring
Tape and Medium Changer devices on IBM System z models on page 77
for guidance on how to configure lin_tape with different Linux versions.
Correct permissions to the lin_tape special file allows TSM to use the
RESETDRIVES option to clear a persistent reservation that is held by a library
client or storage agent. If the TSMtape special file is not created, enable
persistent reservation. If the file does not exist, you might need to create
modprobe.conf. With newer Linux distributions, create a file that is called
/etc/modprobe.d/lin_tape.conf.

Open source device driver - lin_tape


The lin_tape device driver is the new device driver for the Linux 2.6 kernels to
replace the closed-source driver IBMtape. In most respects, it behaves the same as
the closed-source IBMtape device driver. This section covers significant differences
between the IBMtape driver and the lin_tape driver.

92

IBM Tape Device Drivers Installation and Users Guide

Comparing IBMtape and lin_tape


Table 18 compares the names for various components of the IBMtape and lin_tape
device drivers.
Table 18. Comparing IBMtape and lin_tape
Component

IBMtape

Lin_tape

Driver name

IBMtape

lin_tape

Module name

IBMtape.ko

lin_tape.ko

Special files

/dev/IBMtape0

No change

/dev/IBMchanger0, etc.
proc entry

/proc/scsi/IBMtape

No change

/proc/scsi/IBMchanger
Daemon name

IBMtaped

lin_taped

Daemon configuration file

/etc/IBMtaped.conf

/etc/lin_taped.conf

Daemon trace files

/var/log/IBMtape.trace

/var/log/lin_tape.trace

/var/log/IBMtape.errorlog

/var/log/lin_tape.errorlog

Installation
Installation of the lin_tape driver is the same as for the IBMtape driver, except
that IBMtape must be replaced with lin_tape in the installation instructions. Refer
to Installation and Configuration instructions on page 73 for details.
The lin_tape driver cannot be installed if the IBMtape driver is already installed. If
the IBMtape driver is installed, first uninstall the IBMtape driver, and then install
the lin_tape driver. With RHEL4 and SLES10, driver removal also requires a reboot
of the server, since the IBMtape driver module is "permanent" in these
distributions.

Driver parameters and special device files


The driver parameters are not changed for the lin_tape driver. However, it is
important that the module parameters, such as alternate_pathingand dpf_keys,
must now be applied to the lin_tape module, instead of the IBMtape module. For
example, in the /etc/modprobe.conf or /etc/modprobe.conf.local file (or, if you are
running RHEL 6 or higher, the /etc/modprobe.d/lin_tape.conf file), add the
following line for LTO library's path failover:
options lin_tape alternate_pathing=1 dpf_keys="abcdefghijklmnop"

abckdefghijklmnop is an example of a data path failover feature key.


The special device files for the lin_tape driver are the same as for the IBMtape
driver. Refer to Special files for the tape device on page 85 and Special files for
the Medium Changer device on page 86 for details on special device files.

Chapter 4. Linux Tape and Medium Changer device driver

93

Taking devices offline and completing maintenance


Input and output must be quiesced and all driver handles must be closed before a
lin_tape device is taken offline. It is recommended to remove the lin_tape driver
module and the HBA driver module before maintenance is done or the physical
topology of the tape drive or library environment is changed. Lin_tape can be
removed by the following command at the shell prompt.
rmmod lin_tape

Likewise, the HBA module can be removed by the following command, where
"HBA_driver" is your specific HBA driver.
rmmod <HBA_driver>

After the maintenance is complete and the environment is ready to issue input and
output, the drivers must be reinstalled in reverse order. This procedure is typically
done by
modprobe <HBA_driver>
modprobe lin_tape

Path failover support


Path failover support in lin_tape is the same. However, with the lin_tape driver,
failover support is provided through the lin_taped daemon. If the lin_taped
daemon is not running, neither control path failover nor data path failover is
attempted. The lin_taped daemon is started automatically when the lin_tape driver
is loaded.
To check whether the lin_taped daemon is running, run the following command.
lin_taped status

This command indicates whether the lin_taped daemon is running. If the


/proc/scsi/IBMtape and /proc/scsi/IBMchanger files indicate "NA" for "FO Path",
this answer indicates that failover support for that device is not enabled. If all
other settings are correct, but "FO Path" is incorrectly indicating "NA", confirm that
the lin_taped daemon is running.
For details about path failover support, refer to Control Path failover support for
tape libraries on page 88 and Data Path failover and load balancing support for
tape drives on page 90.

lin_taped daemon
The lin_taped daemon uses the same command-line arguments as the IBMtaped
daemon. The lin_taped configuration file is the same as the IBMtaped
configuration file, but is renamed to lin_taped.conf. Refer toConfiguring and
running the lin_taped daemon on page 96 for information.

System-managed encryption
Configuring device drivers
Note: System-managed encryption (SME) on Linux requires that the lin_taped
daemon is running.

94

IBM Tape Device Drivers Installation and Users Guide

The device driver SME settings can be set for all drives at once with the
default_sys_encryption_proxy and default_sys_encryption_write module options.
If no options are specified in the registry, the driver uses the default values for the
parameters.
v The default value for default_sys_encryption_proxy is 1.
This value causes the device driver to handle encryption key requests, if the
drive is set up for system-managed encryption. This value does not need to be
changed. A value of 0 causes the device driver to ignore encryption key requests
for system-managed encryption drives, and is not desirable.
v The default value for default_sys_encryption_write is 2.
This value causes the device driver to leave the encryption write-from-BOP
settings alone. It does not turn on or turn off encryption writing, but instead
uses the settings that are already in the drive. If encryption is not set up
previously, then the drive writes unencrypted data. A value of 0 causes the
device driver to write unencrypted data. A value of 1 causes the device driver to
write encrypted data.
The module options can be specified in the /etc/modprobe.conf,
/etc/modprobe.conf.local, or /etc/modprobe.d/lin_tape.conf files, the same as other
lin_tape module parameters.
For example, to turn on SME to write/read encrypted data,
1. Add the following line:
options lin_tape default_sys_encryption_write=1

2. Then, run the following commands.


>lin_taped stop
>rmmod lin_tape
>depmod
>modprobe lin_tape (reinstall back)
>lin_taped (restart the daemon)

The default settings are used to initialize the settings for all connected drives.
To modify the settings for individual drives, the settings are sys_encryption_write
and sys_encryption_proxy. They have the same definitions and values as the
similarly named "default" parameters, except that the settings apply only to
individual drives.
These settings are available as part of the sysfs infrastructure. For each drive, there
are two files, named sys_encryption_write and sys_encryption_proxy, in the
/sys/class/lin_tape/{DEVICE}/ directory, where: {DEVICE} is the device name,
such as IBMtape0. The contents of these files indicate the current setting for the
parameter for that particular drive. The setting can be changed by writing a
different value for the parameter to the file.
For example, to change the sys_encryption_write setting for IBMtape0 to ON
(which has a value of 1), enter the following at a command line.
echo 1">/sys/class/lin_tape/IBMtape0/sys_encryption_write

Note: The driver encryption parameters for individual drives are not persistent
between loads of the lin_tape driver. If you remove the lin_tape driver, and
then reload it, the individual settings for all drives are the same as the
"default" settings in /etc/modprobe.conf, /etc/modprobe.conf.local, or
/etc/modprobe.d/lin_tape.conf.
Chapter 4. Linux Tape and Medium Changer device driver

95

The ibmekm.conf file, which contains the configuration that the EKM servers use,
is installed in the /etc/ directory when lin_tape is installed. Instructions for
modifying this file are found within the file itself.

Querying tape drive configuration


The following is an example of the output when the drive is configured for
system-managed encryption, with encryption turned on.
issuing query encryption status...
encryption capable......Yes
encryption method.......METHOD_SYSTEM
encryption state........ON

Problem determination
A set of tools is provided with the device driver to determine whether the device
driver and the tape device are functioning correctly.

Tracing driver modules


By default, the driver prints minimal kernel trace messages to the system log at
/var/log/messages. The minimal information includes notification that a device is
recognized or taken offline and also the most serious of error conditions. If a more
verbose trace is wanted, the variable /sys/bus/scsi/drivers/lin_tape/lin_tape_debug must
contain the value 1. This procedure can be accomplished in one of two ways v Add the following line to /etc/modprobe.conf, /etc/modprobe.conf.local, or
/etc/modprobe.d/lin_tape.conf.
options lin_tape lin_tape_debug=1

Then reinstall lin_tape. This action causes the lin_tape_debug variable to be set
every time lin_tape is loaded.
v Issue the following command from the shell.
echo 1 > /sys/bus/scsi/drivers/lin_tape/lin_tape_debug

This action causes the lin_tape_debug variable to be set only until lin_tape is
uninstalled or until the variable is set back to 0.

Configuring and running the lin_taped daemon


Starting with lin_tape version 1.2.5, the lin_tape device driver provides an error
diagnostic daemon (lin_taped) which provides the following capabilities:
1. Error logging and tracing
2. When drive dumps, log sense data, or SIM/MIM error information is created
by the tape drive, the daemon automatically retrieves that data and saves it to
the hard disk drive on your Linux system.
3. Failover and load balancing
4. Encryption
Because lin_taped requires a minimal amount of system resource and because it
provides these necessary diagnostic capabilities, IBM recommends that you leave
the daemon always enabled.

96

IBM Tape Device Drivers Installation and Users Guide

Installing lin_taped
lin_taped is automatically installed at/usr/bin/lin_taped when you install the
lin_tape device driver with the rpm or tar package. Refer toInstallation and
Configuration instructions on page 73 for instructions on installing the lin_tape
device driver.

Configuring lin_taped
You can customize the operation of lin_taped by modifying its configuration file,
which is at /etc/lin_taped.conf. The daemon reads only the configuration file when
it starts; so if you modify the configuration file, stop the daemon, and restart it so
that your modifications are recognized by the daemon.
Tracing:
Three levels of tracing are supported for the lin_taped daemon. lin_taped tracing is
a complement to, but is different from, tracing of the kernel module that is
described in Tracing driver modules on page 96. The lin_taped tracing levels are
defined as follows:
0

With tracing set to 0, lin_taped records minimal tracing.

With tracing set to 1, lin_taped records information that is associated with each ioctl
called. If a device error occurs and SCSI sense data is obtained from the device, a
subset of that sense data is also recorded. The default setting for tracing.

With tracing set to 2, lin_taped records tracing messages for each SCSI command. If
a device error occurs and SCSI sense data is obtained form the device, all sense data
is also recorded. This tracing level is used only when a specific problem is being
diagnosed due to the potential for huge amounts of data that is generated.

Set the lin_tapeTrace variable in the /etc/lin_taped.conf file to 0, 1, or 2, depending


on what level of tracing you want. If the lin_tapeTrace variable is set to an invalid
number, the lin_taped daemon does not start.
Tracing information is written to a file named /var/log/lin_tape.trace, by default.
Information is written into the file until it is 1 MB in size, by default. After 1 MB of
information is written, the file is archived (using the Linux ar command) into file
lin_tape.a in the same directory. In the archive, the file name is renamed to
lin_tape.trace.timestamp, where timestamp reflects the time that the file was
archived.
You can change the directory to which the tracing information is written or the
default maximum size of the trace file by modifying settings in the lin_taped.conf
file. Refer to the instructions in the lin_taped.conf file for details.
Error logging:
lin_taped records certain error messages from the lin_tape device driver in a file
named /var/log/lin_tape.errorlog, by default. Information is written into the file
until it is 1 MB in size, by default. After 1 MB of trace information is written, the
file is archived (with the Linux ar command) into file lin_tape.a in the same
directory. In the archive, the file name is renamed to lin_tape.errorlog.timestamp,
where timestamp reflects the time that the file was archived.

Chapter 4. Linux Tape and Medium Changer device driver

97

You can change the directory to which the error logging information is written or
the default maximum size of the error log file by modifying settings in the
lin_taped.conf file. Refer to the instructions in the lin_taped.conf file for details.
Whenever the lin_taped daemon is running, error logging is enabled if tracing is
enabled. Following is an example an error log record.
IBMtape0---E0001
Scsi Path
:
CDB Command :
Status Code :
Sense Data :

Tue Sep
03 00 00
01 00 00
08 00 00
70 00 04
C4 77 00
10 01 00
00 00 00
Description : Hardware

10 14:04:57
00
00 00 00
01
00 00 00 00
00 00 06 01
00 00 00 00
00 00 00 00
Error

2002

58
40
00
00

00
00
00
00

00
00
00
00

00
00
00
00

00
00
00
00

00
00
00
00

00
00
00
00

FF
01
00
00

0B
00
00
00

The first line indicates the tape device special file name and the device serial
number, and the timestamp when the error message was recorded. "Scsi Path" is
the SCSI path for this logical unit. It matches the order of the scsi/Channel/Id/Lun
information in the /proc/scsi/scsi file. "CDB Command" is the command data block
of the SCSI command. "Status Code" is the returned result from the Linux SCSI
middle layer device driver (scsi_mod.o). The 4 bytes represent driver_byte,
host_byte, msg_byte, and status_byte. "Sense Data" is the full SCSI sense data that
is returned from the target. "Description" is a person-readable text string that is
obtained by parsing the sense key field of the sense data.
The following circumstances are not logged in the lin_tape.errorlog file:
1. Sense key is 0, and the sense data indicates an overlength or an underlength
read, or encountering a file mark or the end of data
2. Sense key is 2, and the ASC/ASCQ indicates that the device is becoming ready
3. Sense key is 6, indicating a unit attention
4. Sense key is 8, and the ASC/ASCQ indicates the end of data
Volume logging:
The lin_tape device driver retrieves the full log sense data from the tape drive
whenever the drive reaches a log threshold, or a tape is unloaded from the drive,
or the drive is reset through an application. This data is stored in binary in a file
named lin_tape.timestamp.log, where: lin_tapen is the device special file (for
example, lin_tape1, lin_tape2) and timestamp reflects the time that the file was
created. Each time log sense data is obtained, it is written to a new file. Use the
appropriate tape drive hardware reference manual to decode the log sense data.
The volume logging data is stored in the /var/log directory by default. You can
specify another directory in the /etc/lin_taped.conf file.
There are two configuration parameters in the /etc/lin_taped.conf file that you can
tailor to affect the number of log sense files that are kept on your system.
v lin_tapeMaxLogSenseFiles, which has a value of 0 or a positive decimal number.
v lin_tapeAutoLogSenseFileOverWrite, which has a value of 0 or 1.
By default, lin_tapeMaxLogSenseFiles is 0 and
lin_tapeAutoLogSenseFileOverWrite is 1, which means that every time log sense
data is created, it is written to a new file.

98

IBM Tape Device Drivers Installation and Users Guide

If lin_tapeMaxLogSenseFiles is 0, lin_tapeAutoLogSenseFileOverWrite is ignored,


and each time log sense data is obtained, it is written to a new file.
If lin_tapeMaxLogSenseFiles is a positive number and
lin_tapeAutoLogSenseFileOverWrite is 0, each time log sense data is created,
lin_taped writes that data to a file until lin_tapeMaxLogSenseFiles is created.
Then, lin_taped stops creating new files, even if new log sense data is produced.
If lin_tapeMaxLogSenseFiles is a positive number and
lin_tapeAutoLogSenseFileOverWrite is 1, each time log sense data is created,
lin_taped writes that data to a file until lin_tapeMaxLogSenseFiles is created.
Then, when new log sense data is detected, lin_taped deletes the oldest log sense
file and creates a new file with the newest log sense data. Thus, only the newest
data is kept.
Automatically retrieving a drive dump:
If a condition occurs in the drive such that a drive dump is created, lin_taped
retrieves the drive dump and saves it in a file named lin_tapex.timestamp.dmp,
wherelin_tapen is the device special file (for example, lin_tape1, lin_tape2) and
timestamp reflects the time that the file was created. Each time a drive dump is
obtained, it is written to a new file. The IBM service organization might request
that you forward drive dumps to them for analysis.
The drive dumps are stored in the /var/log directory by default. You can specify
another directory in the /etc/lin_taped.conf file.
There are two configuration parameters in the /etc/lin_taped.conf file that you can
tailor to affect the number of drive dumps that are kept on your system.
v lin_tapeMaxDumpFiles, which can have a value of 0 or a positive decimal
number.
v lin_tapeAutoDriveDumpFileOverWrite, which can have a value of 0 or 1.
By default, lin_tapeMaxDumpFiles is 0 and
lin_tapeAutoDriveDumpFileOverWrite is 1, which means that every time a drive
dump is obtained, it is written to a new file.
If lin_tapeMaxDumpFiles is 0, lin_tapeAutoDriveDumpFileOverWrite is ignored,
and each time a drive dump is obtained, it is written to a new file.
If lin_tapeMaxDumpFiles is a positive number and
lin_tapeAutoDriveDumpFileOverWrite is 0, each time a dump is obtained,
lin_taped writes that data to a file until lin_tapeMaxDumpFiles is created. Then,
lin_taped stops creating new files, even if new drive dumps are produced.
If lin_tapeMaxDumpFiles is a positive number and
lin_tapeAutoDriveDumpFileOverWrite is 1, each time a dump is obtained,
lin_taped writes that data to a file until lin_tapeMaxDumpFiles is created. Then,
when a new drive dump is detected, lin_taped deletes the oldest drive dump file
and creates a new file with the newest drive dump data. Thus, only the newest
data is kept.
Automatically retrieving SIM/MIM data:

Chapter 4. Linux Tape and Medium Changer device driver

99

If a condition occurs in the drive such that a drive SIM/MIM data is created,
lin_taped retrieves the data and save it in a file named
lin_tapex.timestamp.simmim, where lin_tapen is the device special file (for
example, lin_tape1, lin_tape2) and timestamp reflects the time that the file was
created. Each time SIM/MIM data is obtained, it is written to a new file. The IBM
service organization might request that you forward SIM/MIM data to them for
analysis.
The SIM/MIM data is stored in the /var/log directory by default. You can specify
another directory in the /etc/lin_taped.conf file.
There are two configuration parameters in the /etc/lin_taped.conf file that you can
tailor to affect the number of SIM/MIM files that are kept on your system.
v lin_tapeMaxSimMimDataFiles, which can have a value of 0 or a positive decimal
number.
v lin_tapeAutoSimMimDataOverWrite, which can have a value of 0 or 1.
By default, lin_tapeMaxSimMimDataFiles is 0 and
lin_tapeAutoSimMimDataOverWrite is 1, which means that every time SIM/MIM
data is obtained, it is written to a new file.
If lin_tapeMaxSimMimDataFiles is 0, lin_tapeAutoSimMimDataOverWrite is
ignored, and each time SIM/MIM data is obtained, it is written to a new file.
If lin_tapeMaxSimMimDataFiles is a positive number and
lin_tapeAutoSimMimDataOverWrite is 0, each time SIM/MIM data is obtained,
lin_taped writes that data to a file until lin_tapeMaxSimMimDataFiles is created.
Then, lin_taped stops creating new files, even if new SIM/MIM data is created.
If lin_tapeMaxSimMimDataFiles is a positive number and
lin_tapeAutoSimMimDataOverWrite is 1, each time SIM/MIM data is obtained,
lin_taped writes that data to a file until lin_tapeMaxSimMimDataFiles is created.
Then, when new SIM/MIM data is detected, lin_taped deletes the oldest
SIM/MIM file and creates a new file with the newest SIM/MIM data. Thus, only
the newest data is kept.
Selective tracing:
Lin_tape provides facilities by which you can disable and enable tracing, error
logging, auto-retrieving drive dumps, and auto-retrieving SIM/MIM data. You can
selectively enable or disable them through an application program, which uses the
STIOC_SETP ioctl. These settings persist until the device driver is restarted, or the
host system is rebooted.
The parameters and their definitions are as follows trace

This parameter is set to On by default, which enables lin_tape tracing of


activities and error logging on a particular tape drive. Set this parameter to
off to stop tracing and error logging.

logging
This parameter is set to On by default and enables logging of log sense
data. Setting this flag to Off suppresses volume logging for this device.
disable_sim_logging
This parameter controls the logging of SIM/MIM data for a device. By

100

IBM Tape Device Drivers Installation and Users Guide

default it is set to Off, which causes SIM/MIM data to be logged. Set this
flag to On to suppress the logging of SIM/MIM records.
disable_auto_drive_dump
This parameter controls the saving of drive dumps for a device. By default
it is set to Off, which causes drive dumps to be saved. Set this flag to On
to suppress the saving of drive dumps.
Running lin_taped:
If you are running the lin_tape device driver, version 1.4.1 or higher, after
installing lin_tape lin_taped starts running even if your system does not have a
tape device attached. If you add a new tape device into your Linux system,
lin_taped automatically creates a special file under the /dev directory. If you are
running the lin_tape device driver, version 1.3.x or less, lin_taped does not
automatically start if there is no tape device attached. After you attach a new tape
device, you must start the lin_taped daemon.
You can start lin_taped from the command line. lin_taped takes zero or more of the
parameters as listed in the following command.
lin_taped [start stop restart status]

lin_taped or lin_taped start


Starts the daemon. If there is already a lin_taped running, the new one is
aborted. (Use lin_taped restart if lin_taped is already running.)
lin_taped stop
Terminates the daemon and frees all the resources that are associated with
the daemon. When the daemon is stopped, no information is saved.
lin_taped restart
Terminates the currently running daemon and starts a new one. The new
daemon reads the /etc/lin_taped.conf file. This command is used after the
/etc/lin_taped.conf file is modified while lin_taped is running.
lin_taped status
Prints a message on stdout to indicate whether the daemon is running or
not.
Note: If you run rmmod lin_tape command to remove the lin_tape device driver
from the running kernel, you must stop the lin_taped daemon first;
otherwise you get a Device or Resource Busy error.

Reservation conflict logging


When the device driver receives a reservation conflict on a tape drive command, it
logs the conflict to the kernel debug buffer (which is typically echoed to
/var/log/messages). Before the error is logged, the device driver determines
whether a SCSI Persistent Reservation is active on the target tape drive. If it is, it
gets the reserving host initiator WWPN (worldwide port name). If successful, the
device driver posts the message
lin_tape: reserve held by xxxxxxxx

to the debug buffer. To prevent multiple identical entries in the error log,
subsequent reservation conflicts from the same reserving host WWPN are not
logged.

Chapter 4. Linux Tape and Medium Changer device driver

101

102

IBM Tape Device Drivers Installation and Users Guide

Chapter 5. Solaris Tape and Medium Changer Device Driver


This chapter provides an overview of the IBM SCSI Tape and Medium Changer
Device Driver for Solaris, also known as IBMtape.

Purpose
This device driver product provides attachment for IBM Magnetic Tape and
Library System products to Oracle SPARC and x64 Servers running the Solaris
operating system.
It is designed specifically to take advantage of the features that are provided by
IBM tape and library systems. It also includes control of the random access
medium changer facility (move, element information, and inventory) present in
some devices. The goal is to give applications access to the functions required for
basic operations (such as backup and restore). The goal also includes the advanced
functions that are needed by full tape management systems. Whenever possible,
the device driver is designed to take advantage of the IBM tape system features
transparent to the application.

Data flow

Application
Program

IBMtape
Device
Driver

SCSI or
FC
Host Bus
Adapter
Driver

IBM
Tape
Subsystem

a2500266

Both data and commands flow between the application program and the tape
subsystem by way of IBMtape. Figure 12 shows the data flow between IBMtape,
the application program, the SCSI adapter device driver, and the IBM tape system.

Figure 12. Data flow for Solaris Device Driver (IBMtape)

Product requirements
Hardware requirements
Refer to the Hardware requirements on page xvii for the latest hardware that is
supported by the IBMtape device driver.
Note: For IBM Ultrium drives with the Fibre Channel attachment, the Oracle
Solaris operating system requires that the Fibre Channel addressing mode of
the drive be set to hard addressing.

Software requirements
For current software requirements, refer to the Software requirements on page
xvii.

Copyright IBM Corp. 2007, 2014

103

Installation and configuration instructions


IBM SCSI Tape Drive and Medium Changer Device Driver for Solaris is an
installable kernel module, which is supplied as a standard Solaris software
package. When installed, its package name is IBMtape. The following sections
describe installation, removal, configuration, and verification procedures for
IBMtape. Refer to the Solaris documentation for general information about
installable packages.
The IBMtape package consists of the device driver and a number of associated
files and utilities. For components that are created during IBMtape installation,
refer to Table 19.
Table 19. Solaris: IBMtape components
Component (Note)

Description

/etc/ibmekm.conf

SME configuration file, working version

/etc/tmd.conf

TMD configuration file, working version

/opt/IBMtape

Package subdirectory

/opt/IBMtape/diags_info

Diagnostic script

/opt/IBMtape/ibmekm.conf

SME configuration file, reference version

/opt/IBMtape/tapelist

Utility program

/opt/IBMtape/tmd

Tape Monitor Daemon (TMD) program

/opt/IBMtape/tmd.conf

TMD configuration file, reference version

/opt/IBMtape/IBMtape.conf

Configuration file, reference version

/opt/IBMtape/ztapelist

Shell script for Solaris zones use

/opt/IBMtape/tapedtrc

Dynamic tracing utility program

/usr/kernel/drv/IBMtape

Kernel module device driver

/usr/kernel/drv/IBMtape.conf

Configuration file, working version

/usr/include/sys/smc.h

Medium changer application programming


interface (API) header file

/usr/include/sys/st.h

Tape drive API header file

/usr/include/sys/svc.h

Service aid API header file

/usr/include/sys/oldtape.h

Compatibility API header file

Note: When IBMtape is updated, the working copies of IBMtape.conf, tmd.conf, and
ibmekm.conf are not overwritten by the package file contents. This action allows tape
drive configuration options to be preserved across IBMtape updates. The reference copies
of IBMtape.conf, tmd.conf, and ibmekm.conf are always installed in the /opt/IBMtape
directory.

Examples of installation commands and their results throughout this chapter use a
percent sign (%) to indicate the shell prompt.

Preventing conflicts with other device drivers


IBMtape attempts to claim and operate only the devices that are described in
Hardware requirements on page 103. However, the Solaris operating system
includes a SCSI tape device driver named st, which claims any SCSI-compliant
tape drive that it detects, including devices that IBMtape manages. To avoid
conflicts between IBMtape and st, you must prevent st from claiming and

104

IBM Tape Device Drivers Installation and Users Guide

attempting to operate IBMtape-owned devices. Likewise, other suppliers SCSI


tape device drivers that you installed must be prevented from claiming
IBMtape-owned devices.
Note: To prevent more than one device driver from claiming IBMtape-owned
devices, IBMtape must be also configured with the HBA correctly. Refer to
the section of Configuring IBM tape devices with Oracle FC and SAS
HBAs on page 113 for the details.
Attention: Failure to prevent more than one device driver from operating the
same tape drive might cause system panics or data loss on the tape drive.
The following installation and update steps describe how to prevent conflicts
between IBMtape and other SCSI tape device drivers.

Preinstallation considerations
Follow these steps to install or update IBMtape. Before the step-by-step procedure
is started, note the following general considerations.
v Differential SCSI-2 support must exist on the machine before IBMtape is
installed. Install and configure one of the supported differential SCSI adapters
first, then return to this section. Refer to the differential SCSI adapter
documentation for instructions on installing the adapter and adapter driver.
v You must have root authority to install or remove IBMtape.
v You can restart the system as part of the IBMtape installation. Take appropriate
precautions that this action does not adversely affect users or active processes on
the system.
v As a consequence of installing or reinstalling IBMtape, device special file
numbers under /dev/rmt might change. These numbers are assigned by Solaris
during the driver attachment process, and the sequencing cannot be specified by
the device driver or installer.

Installing and updating IBMtape


Several steps must be taken before IBMtape is installed or updated on your system
to ensure correct installation and system integrity.
1. Notify users that system maintenance and a restart is completed.
2. Select a time when all system activity can be stopped to run the installation.
3. Log in to the target system as root.
4. Ensure that all user and tape drive activity on the system is halted.
5. If tape drives that are not owned by IBMtape are installed on the system, list
the low-density device special files and find the SCSI addresses with which
they are currently associated.
% ls -l /dev/rmt/*l
lrwxrwxrwx
1 root
root
72 Aug 26 15:47 /dev/rmt/5l ->
../../devices/iommu@f,e0000000/sbus@f,e0001000/QLGC,isp@3,10000/st@2,0:l

In the preceding example, /dev/rmt/5l and the related 5m, 5h, are controlled
by the st device driver and are associated with the device at SCSI address 2,
LUN 0. Record the device type, /dev/rmt special file number, owning driver,
SCSI target address, and LUN. This information is required later in the
installation.
For example, suppose that an installation has two non-IBM devices that are
owned by st at SCSI addresses 2 and 8. The low-density devices are accessed
Chapter 5. Solaris Tape and Medium Changer Device Driver

105

as special files /dev/rmt/5l and /dev/rmt/6l. For the equipment listing after the
device information is recorded, refer to Table 20.
Table 20. Solaris: IBMtape install or update
Old special file

Old driver

SCSI address/LUN
(Old)

QIC

/dev/rmt/5l

st

2/0

QIC

/dev/rmt/6l

st

8/0

DEVICE

6. If IBMtape is updating, IBMtape-owned devices are already installed. In that


case, list the primary device special files and find the SCSI addresses with
which they are currently associated.
% ls -l /dev/rmt/*st /dev/rmt/*smc
lrwxrwxrwx
1 root
other
46 Aug 26 16:36 /dev/rmt/0st ->
../../devices/pci@6,4000/scsi@3/IBMtape@b,0:st
lrwxrwxrwx
1 root
other
47 Aug 26 16:36 /dev/rmt/1smc ->
../../devices/pci@6,4000/scsi@3/IBMtape@b,1:smc

Note: When the drive is configured with Oracle HBA driver, even though the
hardware path shows as st@w10000000c9848d68,0 the device special file
still indicates that the drive is configured with IBMtape driver.
lrwxrwxrwx
1 root
root
80 Feb 22 05:12 /dev/rmt/0st ->
../../devices/pci@400/pci@0/pci@d/SUNW,emlxs@0/fp@0,0/
st@w10000000c9848d68,0:st

The previous device special file is created by IBMtape. Refer to Special


files on page 127 for detail.
In this example, /dev/rmt/0st (a SCSI tape drive) is controlled by IBMtape and
is associated with the device at SCSI address b, LUN 0. The address is
reported in hexadecimal format: The file /dev/rmt/1smc (a SCSI medium
changer) is associated with the device at SCSI address b, LUN 1. Record the
device type, /dev/rmt special file number, owning driver, SCSI target address,
and LUN. This information is required later in the installation.
For example, suppose that an installation has only an IBMtape-owned device
that is installed at SCSI address 8. The device consists of both a tape drive and
SCSI medium changer. The tape drive is accessed as /dev/rmt/2st, and the
medium changer as /dev/rmt/3smc. For a similar equipment listing after the
device information is recorded, refer to Table 21.
Table 21. Solaris Device Driver - IBMtape - equipment listing example 1
DEVICE
3590-B11 drive
3590-B11 changer

Old special fle

Old driver

SCSI address/LUN
(Old)

/dev/rmt/2st

IBMtape

8/0

/dev/rmt/3smc

IBMtape

8/1

7. Select one of the following methods to prevent conflicts between IBMtape and
other SCSI tape device drivers, depending on the equipment that is attached
to your system.
Note: To prevent more than one device driver from claiming IBMtape-owned
devices, IBMtape must be also configured with HBA correctly. Refer to
the section of Configuring IBM tape devices with Oracle FC and SAS
HBAs on page 113 for the details.

106

IBM Tape Device Drivers Installation and Users Guide

Attention: Failure to prevent more than one device driver from operating the
same SCSI tape drive can cause system panics or data loss on the tape drive.
a. If the system has only IBMtape-owned devices that are attached, follow
these steps to prevent st and other non-IBM SCSI tape device drivers from
claiming the IBM devices.
1) Edit /kernel/drv/st.conf, and comment out all SCSI target entries by
placing a number sign (#) in the first column of each target entry. The
following example shows the entries for SCSI target addresses 0 and 1
commented out. Repeat this operation for all target entries.
#name="st" class="scsi"
#target=0 lun=0;
#name="st" class="scsi"
#target=1 lun=0;

2) For other non-IBM installed SCSI tape device drivers, remove the
drivers if they are not needed. If a driver is for SCSI tape devices only,
it is not needed. If a driver is for both tape and disk devices, follow the
suppliers instructions to disable its access to all SCSI tape devices.
b. If the system has a mixture of IBMtape-owned devices and other tape
drives, follow these steps to configure st and other non-IBM SCSI tape
device drivers so that they control a range of target addresses distinct from
the range that IBMtape uses. These steps leave target addresses 7 and 15
unclaimed by all target device drivers because SCSI adapters typically use
one of the two addresses.
1)

Edit /kernel/drv/st.conf, and comment out SCSI target entries for


addresses 7-15 by placing a number sign (#) in the first column of each
target entry. In the following example, the entries for SCSI address 7
and 8 are commented out. Repeat this operation for all entries in the
target address range 7-15.
#name="st" class="scsi"
#target=7 lun=0;
#name="st" class="scsi"
#target=8 lun=0;

2) For other non-IBM installed SCSI tape device drivers, follow the
suppliers instructions to disable their access to all SCSI tape devices in
the address range 7-15.
3) After the IBMtape package is installed, you must alter its configuration
file so it does not use SCSI target addresses in the range 0-7 or address
15.
Now st and other non-IBM SCSI tape device drivers are configured to
avoid a conflict with IBMtape.
8. Remove all special file entries under /dev/rmt. This action ensures that stale
entries do not exist after the system is restarted. New entries are created when
the system is restarted.
% rm /dev/rmt/*

9. Read the next section of Configuring IBM tape devices with Fibre Channel
and SAS HBAs on page 111, and follow the instruction requirements for the
selected HBA in the host machine before or after IBMtape is installed.
10. If you are updating the level of IBMtape, remove the currently installed
IBMtape package. If this procedure is a new installation of IBMtape, skip this
step.
a. Use pkgrm to remove the current level.
% /usr/sbin/pkgrm IBMtape
Chapter 5. Solaris Tape and Medium Changer Device Driver

107

Respond to the pkgrm prompts.


b. Examine the results from pkgrm. If you see these messages, one or more
IBMtape-owned tape drives or tape monitor daemon (TMD) were still in
use. Identify the drives and TMD process ID (pid), and end the processes
that are using them. If you cannot identify the processes, you must restart
the system to free the tape drive, then continue with the installation from
this point.
...
Device busy
Cannot unload module: IBMtape
Will be unloaded upon reboot.
...

11. Select one of the following methods to install the IBMtape package,
depending on the package distribution medium and the location of system
resources.
Note: If this procedure is a new installation of IBMtape, IBM devices are not
yet attached to the system, pkgadd error messages similar to the
following are output.
...
drvconfig: Driver (IBMtape) failed to attach
Warning: Driver (IBMtape) successfully added to system
but failed to attach
## The device driver was unable to detect any supported devices!
## Verify that the device(s) are properly connected and powered on.
## Ensure that the SCSI adapter device driver is installed/configured.
## Then try reinstalling the device driver as follows:
##
-enter the command: rem_drv IBMtape
##
-enter the command: add_drv -m * 0666 bin bin IBMtape
## If problems persist, contact your IBM service representative.
pkgadd: ERROR: postinstall script did not complete successfully
...

Later, after you cabled IBM drives to the system and restarted, the driver
attaches normally.
If the distribution medium is a package file in a UNIX file system, complete
the following steps. You might obtain a package file by downloading it from
the IBM Fix Central website: http://www.ibm.com/support/fixcentral. For
information, see Appendix A, Accessing documentation and software online,
on page 321. This example presumes a package file named IBMtape.4.0.2.7 in
the /tmp directory.
a. If necessary, FTP the package file to the target system. Use binary transfer
mode. Place the package file in the target systems /tmp directory.
b. Use pkgadd to install the driver.
% /usr/sbin/pkgadd -d /tmp/IBMtape.4.0.2.7

12. If your system environment includes a mixture of IBMtape-owned devices


and devices that are owned by st or another third-party SCSI tape device
driver, you must first modify the configuration files for the non-IBM device
drivers and restrict them to target addresses in the range 0-6.
Edit IBMtape.conf, in /usr/kernel/drv, and comment out entries for SCSI
target addresses 0-7 and 15. Place a number sign (#) in the first column of
each line that makes up the entries. In the following example, the entries for
address 0, LUN 0 and address 0, LUN 1 are commented out. Repeat the
operation for all stanzas in the address range 0-7 and address 15. Each SCSI
target address has a stanza for both LUN 0 and LUN 1.

108

IBM Tape Device Drivers Installation and Users Guide

#name="IBMtape" class="scsi"
#target=0 lun=0
#block_size=0
#buffering=1
#immediate=0
#trailer=0
#sili=0;
#name="IBMtape"
#target=0 lun=1
#block_size=0
#buffering=1
#immediate=0
#trailer=0
#sili=0;

class="scsi"

In SAN environment, the Fibre Channel HBA driver can map the SCSI target
address out of the range 15 and LUN over the number 1. You create a new
entry with the mapped SCSI target in IBMtape.conf. In the following
example, the IBM tape device is mapped to the SCSI target 32 and LUN 15.
name="IBMtape" class="scsi"
target=32 lun=15
block_size=0
buffering=1
immediate=0
trailer=0
sili=0;

Alternatively, you can modify the configuration file or use the utility that is
provided by the Fibre Channel HBA driver to persistently bind the tape
device to the expected SCSI target address.
13. Shut down the system. One common method to complete a shutdown is
shown here but use your installations normal procedures.
% /usr/sbin/shutdown -y -g0 -i0

14. Address or readdress devices as determined by your installation.


a. If the system has only IBMtape-owned devices that are attached, you can
select addresses in the range 0-6 or 8-14. Leave addresses 7 and 15 unused
because these addresses are used typically by the SCSI adapter.
1) For each device, refer to the appropriate IBM hardware reference for
any special instructions about addressing. Then, set the address and
record the device type, SCSI address, and LUN. For example, suppose
that an installation has only IBMtape-owned devices attached. An IBM
device with tape drive and medium changer is added. It is addressed
at target 4 and the information is recorded. For the results, refer to
Table 22
Table 22. Solaris Device Driver - IBMtape - equipment listing example 2

Old driver

SCSI
address/LUN
(Old)

SCSI
address/LUN
(New)

4/0

4/1

Old special
file

3590-B11 drive
3590-B11 changer

DEVICE

b. If you are using distinct address ranges to separate tape drives that are
IBMtape-owned from devices that are owned by st or another suppliers
driver, readdress the tape drives now.
1) For each device that is owned by st or another SCSI tape device driver,
refer to the manufacturers hardware reference for any special
Chapter 5. Solaris Tape and Medium Changer Device Driver

109

instructions about readdressing. Then, readdress each device to an


address in the range 0-6. For each tape drive that is readdressed, record
the new SCSI address next to the special file number and old SCSI
address that you recorded previously.
2) Readdress all tape drives that are owned by IBMtape to addresses in
the range 8-14. Refer to the appropriate IBM hardware references for
any special instructions about readdressing. For each tape drive that is
readdressed, record the new SCSI address next to the special file
number and old SCSI address, if any, that you previously recorded.
For example, suppose that an installation has two non-IBM devices that
are owned by st at SCSI addresses 9 and B (12 in decimal). An IBM
device with tape drive and medium changer is added. To prevent
conflicts between IBMtape and st, the non-IBM devices are all placed
at addresses in the range 0-6. The new IBM device is addressed in the
range 8-14, at address 10, or 0A. Depending on the addresses that are
chosen for the non-IBM devices after device information is readdressed
and recorded, refer to Table 23 for the possible equipment listing.
Table 23. Solaris Device Driver - IBMtape - equipment listing example 3

Old driver

SCSI
address/LUN
(Old)

SCSI
address/LUN
(New)

/dev/rmt/2l

st

9/0

3/0

/dev/rmt/3l

st

b/0

5/0

3590-B11 drive

a/0

3590-B11 changer

a/1

Old special
file

QIC
QIC

DEVICE

Note: The SCSI target address of Fibre Channel tape device might be over 15.

15. Cable the tape drives to the system, if not yet done. Refer to the
manufacturers hardware references for any special instructions about cabling.
Ensure that each SCSI bus is terminated properly.
16. Start the system according to your installations normal procedures.
17. Log on as root and list the device special files in /dev/rmt as you did earlier
during the installation.
% ls -l /dev/rmt/*l
% ls -l /dev/rmt/*st /dev/rmt/*smc

Compare the SCSI addresses obtained from ls with the readdressed SCSI
targets you recorded. Write the new device special file numbers and owning
driver next to the matching new SCSI addresses.
For example, suppose that an installation previously had two non-IBM devices
that are owned by st at SCSI addresses 2-8. An IBM device with tape drive
and medium changer is added. To prevent conflicts between IBMtape and st,
the non-IBM devices are all placed at addresses in the range 0-6. The new IBM
device is addressed in the range 8-14. Depending on the addresses that are
chosen after installation is completed and device information is recorded, refer
to Table 24 for the possible equipment listing entries.
Table 24. Solaris Device Driver - IBMtape - equipment listing example 4

DEVICE
QIC

110

Old special
file
/dev/rmt/5l

SCSI
SCSI
Old address/LUN address/LUN
driver
(Old)
(New)
st

IBM Tape Device Drivers Installation and Users Guide

2/0

2/0

New
driver

New special file


(Note)

st

/dev/rmt/0l

Table 24. Solaris Device Driver - IBMtape - equipment listing example 4 (continued)

DEVICE
QIC

Old special
file

SCSI
SCSI
Old address/LUN address/LUN
driver
(Old)
(New)

New
driver

New special file


(Note)

/dev/rmt/6l

st

8/0

0/0

st

/dev/rmt/1l

3590-B11
drive

8/0

IBMtape

/dev/rmt/2st

3590-B11
changer

8/1

IBMtape

/dev/rmt /3smc

Note: Based on the listing, you can see that the tape drive accessed previously as
/dev/rmt/5 is now accessed as /dev/rmt/0, the new medium changer is accessible as
/dev/rmt/3smc.

18. Complete validation of "configuration conflict" to avoid the device that is


configured with more than one device driver.
a. List the device special files in /dev/rmt and check if any unexpected device
special file is created by non-IBMtape driver.
b. Verify whether same SCSI address or WWNN is pointed to different
device special files owned by the different device driver. For example, a
same tape drive is configured by st driver with the special file of
/dev/rmt/0 and by IBMtape driver with /dev/rmt/15st at the same SCSI
address (target 0 and LUN 0).
lrwxrwxrwx
1 root
root
49 Jul 28 2009 /dev/rmt/0 ->
../../devices/pci@81,2000/fibre-channel@1/st@0,0:
lrwxrwxrwx
1 root
sys
56 Jul 28 2009 /dev/rmt/15st ->
../../devices/pci@80,2000/fibre-channel@1/IBMtape@0,0:st

c. Run the system command or other utility to verify whether the device can
be opened by using both device special file names.
With the device special files in above example, load the cartridge in the
drive and run # mt -f /dev/rmt/* stat command
(1) IBMtape opens the drive.
# mt -f /dev/rmt/15stn stat
IBM_ULT3580-TD5 tape drive:
sense key(0x0)= No Additional Sense
file no= 0
block no= 0
(2) st opens the drive.
# mt -f /dev/rmt/0n stat
IBM_ULT3580-TD5 tape drive:
sense key(0x0)= No Additional Sense
file no= 0
block no= 0

residual= 0

retries= 0

residual= 0

retries= 0

(3) st fails to open the drive.


# mt -f /dev/rmt/0n stat
/dev/rmt/0n: No such file or directory

19. Verify operation of the newly installed or readdressed equipment.


20. Notify users of any changed device special files numbers.

Configuring IBM tape devices with Fibre Channel and SAS


HBAs
Users might experience difficulty when an IBM tape device is attached to an IBM
tape driver on a fibre network. The following sections describe how to configure
IBM tape devices with QLogic, Emulex, Oracle, Brocade, and AMCC Fibre Channel
HBAs.
v Configuring IBM tape devices with QLogic FC HBAs on page 112
Chapter 5. Solaris Tape and Medium Changer Device Driver

111

v
v
v
v

Configuring
Configuring
Configuring
Configuring

IBM
IBM
IBM
IBM

tape
tape
tape
tape

devices
devices
devices
devices

with Emulex FC HBAs


with Oracle FC and SAS HBAs on page 113
with AMCC FC HBAs on page 114
with Brocade FC HBAs on page 115

Configuring IBM tape devices with QLogic FC HBAs


To configure an IBM tape device with a QLogic FC HBA, complete the following
steps.
1. Run the QLogic SANSurfer Control FX utility to find and record the mapped
target and LUN of the tape device.
2. Remove the comment at the beginning of the entry for the QLogic HBA in the
/usr/kernel/drv/IBMtape.conf file.
For example, the following command opens the entry for QLogic QLA2462
running QLogic HBA driver qla2300.
name="IBMtape" parent="qla2300" target=0;

# for qla2300 only

3. Update the entry for the device in the IBMtape.conf file, if necessary. The
current entry in the IBMtape.conf file is added to target 255 with LUN 0 and 1.
For instance, the following command adds an entry for a mapped device with
target 200 and LUN 3.
name="IBMtape" class="scsi" target=200 LUN=3;

4. Unload and reload the IBMtape driver.


#
#
#
#

/opt/IBMtape/tmd -s
rem_drv IBMtape
add_drv -m * 0666 bin bin IBMtape
/opt/IBMtape/tmd

5. Display information on the configured devices by running


/opt/IBMtape/tapelist -l.
To configure an IBM tape device with a QLogic FC HBA running with Oracle
branded QLogic FC HBA driver (qlc), refer to the section Configuring IBM tape
devices with Oracle FC and SAS HBAs on page 113.

Configuring IBM tape devices with Emulex FC HBAs


To configure an IBM tape device with an Emulex FC HBA, complete the following
steps.
1. Run the Emulex HBAnyware utility to find and record the mapped target and
LUN of the tape device.
2. For lpfc.6.30g or later, update the parameters setting in /kernel/drv/lpfc.conf
and reboot the system.
If IBMtape driver is used as a tape driver, change the parameter for IBMtape.
target-tape="IBMtape

If IBMtape driver is used as a changer driver, modify the setting for IBMtape.
target-tapechanger="IBMtape"

3. Remove the comment at the beginning of the entry for the Emulex HBA in
/usr/kernel/drv/IBMtape.conf:
name="IBMtape" parent="lpfc" target=0;

If this action fails to configure the changer, you might need to add the entries
for LUN 0 and 1.

112

IBM Tape Device Drivers Installation and Users Guide

name="IBMtape" parent="lpfc" target=X lun=0;


name="IBMtape" parent="lpfc" target=X lun=1;

4. Update the entry for the device in the IBMtape.conf file, if necessary. The
current entry in IBMtape.conf adds target 255 with LUN 0 and 1.
For instance, the following command adds an entry for a mapped device with
target 200 and LUN 3.
name="IBMtape" class="scsi" target=200 lun=3;

5. Unload and reload the IBMtape driver:


#
#
#
#

/opt/IBMtape/tmd -s
rem_drv IBMtape
add_drv -m * 0666 bin bin IBMtape
/opt/IBMtape/tmd

6. Display information on the configured devices by running


/opt/IBMtape/tapelist -l.
To configure an IBM tape device with an Emulex FC HBA running with Oracle
branded Emulex FC HBA (emlxs) driver, refer to the section Configuring IBM
tape devices with Oracle FC and SAS HBAs.

Configuring IBM tape devices with Oracle FC and SAS HBAs


To configure an IBM tape device with an Oracle FC HBA, complete the following
steps.
1. Attach the IBM tape devices on the host.
2. Install the appropriate patch for the Oracle HBA driver.
3. Run # cfgadm -al to display the configuration between the HBA and the tape
device.
Run # cfgadm -al -o show_FCP_dev Ap_Id to show the medium changer
configuration with the FC HBA.
Run # cfgadm -c configure device to configure the tape device with the HBA if
needed.
4. Install the IBMtape tape driver by running the # pkgadd -d IBMtape command.
5. Enter the following appropriate lines in /etc/driver_aliases:
IBMtape "scsiclass,01.vIBM.pXXX" for tape drive.
IBMtape "scsiclass,08.vIBM.pXXX" for medium changer.

Where: 01 and 08 stand for the type of tape drive and medium changer and
XXX is the product ID string in the standard inquiry data. For example,
ULT3580-TD2 is the product ID of the IBM LTO2 drive. The following entry is
added in the file for the IBM LTO2 drive.
IBMtape "scsiclass,01.vIBM.pULT3580-TD2"

The following is a list of the entries for the supported IBM tape devices.
For the tape drives
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape

"scsiclass,01.vIBM.pULT3580-TD1"
"scsiclass,01.vIBM.pULTRIUM-TD1"
"scsiclass,01.vIBM.pULT3580-TD2"
"scsiclass,01.vIBM.pULTRIUM-TD2"
"scsiclass,01.vIBM.pULT3580-TD3"
"scsiclass,01.vIBM.pULTRIUM-TD3"
"scsiclass,01.vIBM.pULT3580-TD4"
"scsiclass,01.vIBM.pULTRIUM-TD4"
"scsiclass,01.vIBM.pULT3580-TD5"
"scsiclass,01.vIBM.pULTRIUM-TD5"
"scsiclass,01.vIBM.pULT3580-HH2"
"scsiclass,01.vIBM.pULTRIUM-HH2"
"scsiclass,01.vIBM.pULT3580-HH3"
Chapter 5. Solaris Tape and Medium Changer Device Driver

113

IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape

"scsiclass,01.vIBM.pULTRIUM-HH3"
"scsiclass,01.vIBM.p03590B1A"
"scsiclass,01.vIBM.p03590E1A"
"scsiclass,01.vIBM.p03590H1A"
"scsiclass,01.vIBM.p03592J1A"
"scsiclass,01.vIBM.p03592E05"
"scsiclass,01.vIBM.p03592E06"
"scsiclass,01.vIBM.p03592E07"
"scsiclass,01.vIBM.p03592E08"

For the medium changers


IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape

"scsiclass,08.vIBM.p03584L32"
"scsiclass,08.vIBM.p03584L22"
"scsiclass,08.vIBM.pULT3582-TL"
"scsiclass,08.vIBM.pULT3583-TL"
"scsiclass,08.vIBM.pULT3581-TA"
"scsiclass,08.vIBM.pULT3581-TA2"
"scsiclass,08.vIBM.p03590B11"
"scsiclass,08.vIBM.p03590E11"
"scsiclass,08.vIBM.p03590H11"
"scsiclass,08.vIBM.p3576-MTL"
"scsiclass,08.vIBM.p3573-TL"
"scsiclass,08.vIBM.p3572-L1U"
"scsiclass,08.vIBM.p3572-TL"
"scsiclass,08.vIBM.p3577-TL"

Note: The entry is also added running the # update_drv command on Solaris 8
(patch 111804-03 is required), Solaris 9, and later versions of the
operating system. For example,
# update_drv -av -i "scsiclass,01.vIBM.pULT3580-TD2" IBMtape

6. Reboot the system by running # reboot -- -r.


7. Run # /opt/IBMtape/tapelist -l to display the configured tape device
information.
Note: All of the added entries are removed by the operating system
automatically after IBMtape is unloaded from the kernel by running the
# pkgrm, rem_drv, or modunload commands. It is recommended that you
back up these entries in a file. Then, reenter the entries when you
upgrade the IBMtape driver before the #pkgadd command is run.

Configuring IBM tape devices with AMCC FC HBAs


To configure an IBM tape device with an AMMC FC HBA, complete the following
steps:
1. Modify and add the following parameters in /kernel/drv/jnic146x.conf.
CmdTaskAttr=1;
lun_throttle=1;
tape-device="IBMtape";
tape-changer="IBMtape";

2. Update the change in jnic146x.conf.


3. Run the EZ Fibre utility to find and record the mapped target and LUN of the
tape device.
4. Remove the comment from the beginning entry for AMCC HBA in
/usr/kernel/drv/IBMtape.conf.
name="IBMtape" parent="jnic146x" target=0;

114

IBM Tape Device Drivers Installation and Users Guide

5. Update the entry for the device in IBMtape.conf if necessary. The current entry
in IBMtape.conf adds target 255 with LUN 0 and 1. For instance, use the
following command to add an entry for a mapped device with a target 200 and
LUN 3.
name="IBMtape" class="scsi" target=200 lun=3;

6. Unload and reload the IBMtape driver.


# /opt/IBMtape/tmd -s
# rem_drv IBMtape
# add_drv -m * 0666 bin bin IBMtape
# /opt/IBMtape/tmd

7. Display information on the configured devices by running


/opt/IBMtape/tapelist -l.

Configuring IBM tape devices with Brocade FC HBAs


To configure an IBM tape device with a Brocade FC HBA, complete the following
steps.
1. Attach IBM tape devices on the host.
2. Install the appropriate version of Brocade HBA driver and its utilities.
3. Run Brocade HCM (Host Connectivity Manager) to display the configuration.
4. Install the IBMtape tape driver by running # pkgadd command.
5. Enter the following appropriate lines in /etc/driver_aliases:
IBMtape "scsiclass,01.vIBM.pXXX" for tape drive.
IBMtape "scsiclass,08.vIBM.pXXX" for medium changer.

Where: 01 and 08 stand for the type of tape drive and medium changer and
XXX is the product ID string in the standard inquiry data. For example,
ULT3580-TD2 is the product ID of the IBM LTO2 drive. The following entry is
added in the file for the IBM LTO2 drive,
IBMtape "scsiclass,01.vIBM.pULT3580-TD2"

The following is a list of the entries for the supported IBM tape devices.
For the tape drives

IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape

"scsiclass,01.vIBM.pULT3580-TD3"
"scsiclass,01.vIBM.pULTRIUM-TD3"
"scsiclass,01.vIBM.pULT3580-HH3"
"scsiclass,01.vIBM.pULTRIUM-HH3"
"scsiclass,01.vIBM.pULT3580-TD4"
"scsiclass,01.vIBM.pULTRIUM-TD4"
"scsiclass,01.vIBM.pULT3580-HH4"
"scsiclass,01.vIBM.pULTRIUM-HH4"
"scsiclass,01.vIBM.pULT3580-TD5"
"scsiclass,01.vIBM.pULTRIUM-TD5"
"scsiclass,01.vIBM.pULT3580-HH5"
"scsiclass,01.vIBM.pULTRIUM-HH5"
"scsiclass,01.vIBM.p03592E05"
"scsiclass,01.vIBM.p03592E06"
"scsiclass,01.vIBM.p03592E07"
"scsiclass,01.vIBM.p03592E08"

For the medium changers


IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape
IBMtape

"scsiclass,08.vIBM.p03584L32"
"scsiclass,08.vIBM.p03584L22"
"scsiclass,08.vIBM.p3576-MTL"
"scsiclass,08.vIBM.p3573-TL"
"scsiclass,08.vIBM.p3572-L1U"
"scsiclass,08.vIBM.p3572-TL"
"scsiclass,08.vIBM.p3577-TL"

Chapter 5. Solaris Tape and Medium Changer Device Driver

115

Note: The entry is also added running the # update_drv command on Solaris 8
(patch 111804-03 is required), Solaris 9, and later versions of the
operating system. For example,
# update_drv -av -i "scsiclass,01.vIBM.pULT3580-TD2" IBMtape

6. Reboot the system by running # reboot -- -r.


7. Run # /opt/IBMtape/tapelist -l to display the configured tape device
information.

Configuring limitations
The subsequent limitations are applied for the IBMtape driver that runs on a
Solaris host.
Maximum supported number of tape devices 1024
Maximum supported number of HBA ports

56

Maximum supported number of paths for a


device (DPF/ CPF)

16/16

Maximum LUN size per target for FC HBA

256 (Oracle, QLogic, Brocade FC HBAs)


128 (Emulex FC HBA running with lpfc HBA
driver)

Every opened tape device uses a certain amount of resources. The user must also
consider other resources such as physical memory and virtual space on the system
before you attempt to reach the limits.

Solaris Zones support


The Solaris Zones partitioning technology on Solaris 10 is used to virtualize
operating system services and provide an isolated and secure environment for
running applications. Every Solaris system contains a global zone with ID 0, where
the IBMtape driver is installed. Zones that are hosted by a global zone are known
as non-global zones, which have their own node name, virtual network interface,
and storage assignment.
The IBMtape driver supports the Solaris Zones environment. To install IBMtape
on the system with the virtualized zones, run the pkgadd system command from
the global zone.
#pkgadd -G -d IBMtape.x.x.x.x

The IBMtape installation script installs the driver in the global zone and installs
some of IBMtape utilities that run a non-root user in all zones.
Since the tape devices in non-global zones are configured from the global zone, a
script program that is called ztapelist was developed to help the user display the
IBM tape devices. And, it dynamically assigns or removes IBM tape devices in
non-global zones without the non-global zone reboot requirement. The utility
(available in IBMtape 4.1.5.2 or later) is installed on Solaris 10 and runs in the
global zone only.
Use the ztapelist utility on the command line as follows.
Synopsis
/opt/IBMtape/ztapelist [-l] [-c] [-z zonename] [-a] [-d] [-h]

116

IBM Tape Device Drivers Installation and Users Guide

Options and usage


ztapelist recognizes the following options.
-l
-c
-z zonename
-a

Displays IBM tape device information with the column headers


for all zones
Displays IBM tape device information without the column
headers for all zones
Shows IBM tape devices in a zone
Dynamically adds IBM tape devices to each non-global zone
without additional arguments
zonename inst#_1 inst#_2 inst#_3 ...
Dynamically sets IBM tape devices not greater than 7 in
a non-global zone.

-d
-h

zonename all
Dynamically sets all IBM tape devices on the system in a
non-global zone.
Removes the IBM tape device from a non-global zone
Displays help information

The ztapelist command displays all of the IBM tape devices in the global zone
and the tape devices in the non-global zones as shown in the following example.
An option of ztapelist -z zonename is also provided to show all of the assigned
tape devices in a particular zone.
# /opt/IBMtape/ztapelist -l
Running in global zone ...
Inst#
Special File
Device
Serial No
TGT/LUN
Ucode
World Wide NN
World Wide PN
------- -------------- ---------- ----------------- ------------ ---------- ----------------- ----------------193
/dev/rmt/27st
03592E05(e/e)
000001365066
2/0
1A38 500507630019F016 500507630059F016
194
/dev/rmt/28smc 03584L22
0000000T003904E5 2/1
805r
N/A
N/A
200
/dev/rmt/29st
ULT3580-TD4(e)
1300000044
4/0
82F0 500507630019F009 500507630059F009
201
/dev/rmt/30smc 03584L32
0000000T00390401 4/1
805r
N/A
N/A
206
/dev/rmt/31st
ULT3580-TD3
1210003557
7/0
73P5
500507630019F007 500507630059F007
38
/dev/rmt/32smc 03584L32
0000000T00390401 7/1
805r
N/A
N/A

Running in non-global
Inst#
Special File
------- ------------200
/dev/rmt/29st
201
/dev/rmt/30smc

zone camshaft ...


Device
Serial No
----------------- -----------------ULT3580-TD4(e) 1300000044
03584L32
0000000T00390401

Running in non-global zone softail ...


Inst#
Special File
Device
------- ------------- ------------193
/dev/rmt/27st
03592E05(e/e)
194
/dev/rmt/28smc
03584L22

TGT/LUN
Ucode
World Wide NN World Wide PN
-------- ---------- ------------------------4/0
82F0 500507630019F009 500507630059F009
4/1
805r
N/A
N/A

Serial No
TGT/LUN Ucode
World Wide NN
--------------------- -------- --------------000001365066
2/0
1A38 500507630019F016
0000000T003904E5
2/1
805r
N/A

World Wide PN
-----------------500507630059F016
N/A

To add the tape devices in non-global zones, run # /opt/IBMtape/ztapelist -a, as


shown in the following example.
|
|

Note: Due to operating system limitations, this option is supported on Solaris 10,
11.0, and 11.2, and not on 11.1.

Chapter 5. Solaris Tape and Medium Changer Device Driver

117

# ztapelist -a
Issuing this function will assign the tape devices in non-global zone
Do you wish to continue? [y/n]: y
Inst#
Special File
Device
Serial No
TGT/LUN
Ucode
World Wide NN
World Wide PN
------- ---------------- ------------------------------------ ---------- ---------------- -------------193
/dev/rmt/27st
03592E05(e/e)
000001365066
2/0
1A38
500507630019F016 500507630059F016
194
/dev/rmt/28smc
03584L22
0000000T003904E5
2/1
805r
N/A
N/A
200
/dev/rmt/29st
ULT3580-TD4(e) 1300000044
4/0
82F0
500507630019F009 500507630059F009
201
/dev/rmt/30smc
03584L32
0000000T00390401
4/1
805r
N/A
N/A
206
/dev/rmt/31st
ULT3580-TD3
1210003557
7/0
73P5
500507630019F007 500507630059F007
38
/dev/rmt/32smc
03584L32
0000000T00390401
7/1
805r
N/A
N/A
Enter Instance Number (Inst #) of a device to be added: 200
ID NAME
STATUS
PATH
0 global
running
/
1 camshaft
running
/zones/zone1
2 softail
running
/zones/zone2
Enter the zonename where the device will be added: camshaft
Inst#
Special File
Device
Serial No
TGT/LUN Ucode
World Wide NN World Wide PN
------- --------------- ---------------- ----------------- --------- ------- --------------- --------------200
/dev/rmt/29st
ULT3580-TD4(e)
1300000044
4/0
82F0
500507630019F009 500507630059F009
Do you wish to continue to add the devices? [y/n]: y
Enter Instance Number (Inst #) of a device to be added: 193
Enter the zonename where the device will be added: softail
Inst#
Special File
Device
Serial No
TGT/LUN Ucode
World Wide NN World Wide PN
------- --------------- ---------------- ----------------- --------- ------- --------------- --------------193
/dev/rmt/27st
03592E05(e/e)
000001365066
2/0
1A38
500507630019F016 500507630059F016
Do you wish to continue to add the devices? [y/n]: n
#

The ztapelist command also allows the user to remove all or some assigned tape
devices from the non-global zone, as shown in the following example.

118

IBM Tape Device Drivers Installation and Users Guide

# /opt/IBMtape/ztapelist -d
Issuing this function will remove the tape devices from non-global zone
Do you wish to continue? [y/n]: y
Do you want to remove the tape devices from all of non-global zones? [y/n]: n
ID NAME
STATUS
PATH
0 global
running
/
1 camshaft
running
/zones/zone1
2 softail
running
/zones/zone2
Enter the zonename where the devices will be removed: camshaft
Do you want to remove all of the tape devices from this zone? [y/n]: n
Inst#
Special File
Device
Serial No
TGT/LUN
Ucode
World Wide NN
World Wide PN
------- ---------------- ------------- ----------------- ----------- -------- ------------------ ----------------200
/dev/rmt/29st
ULT3580-TD4(e)
1300000044
4/0
82F0 500507630019F009
500507630059F009
201
/dev/rmt/30smc
03584L32
0000000T00390401 4/1
805r
N/A
N/A
Enter Instance Number (Inst #) of a device to be removed: 201
Removing this tape device /dev/rmt/30smc for this zone camshaft ...
Inst#
Special File
Device
Serial No
TGT/LUN Ucode
World Wide NN
World Wide PN
------- -------------- ------------------ ---------------- ---------- -------- ------------------- -----------------200
/dev/rmt/29st
ULT3580-TD4(e)
1300000044
4/0
82F0
500507630019F009 500507630059F009
Do you wish to continue to remove the devices from this zone? [y/n]: n
Do you wish to continue to remove the devices from other zone? [y/n]: y
ID NAME
STATUS
PATH
0 global
running
/
1 camshaft
running
/zones/zone1
2 softail
running
/zones/zone2
Enter the zonename where the devices will be removed: softail
Do you want to remove all of the tape devices from this zone? [y/n]: y
Removing all of tape devices for this zone softail ...
Inst#
Special File
Device
Serial No
TGT/LUN Ucode World Wide NN
World Wide PN
------- ------------------- --------------- ------------------ --------- -------- -------------- ------------------Do you wish to continue to remove the devices from other zone? [y/n]: n

Configuration parameters
When devices controlled by IBMtape are used, certain device characteristics, such
as the default block size, can be controlled through the device driver configuration
file. The IBMtape configuration file is named IBMtape.conf. The working copy of
this file is in the /usr/kernel/drv directory.
During installation of IBMtape, the working copy of IBMtape.conf is preserved, if
it exists. During removal of IBMtape, the working copy of IBMtape.conf is not
deleted. These conventions allow configuration settings to remain across updates of
IBMtape. A reference copy of IBMtape.conf with factory default settings is always
installed in the /opt/IBMtape directory.
Note: IBM requires that the Solaris native SCSI tape device driver `st is configured
so that it does not attempt to support SCSI targets that are controlled by
IBMtape. Refer to Preventing conflicts with other device drivers on page
104 for information about multiple driver access to a device.
Attention: Failure to prevent more than one device driver from operating the
same tape drive can cause system panics or data loss on the tape drive.
Configuration settings are applied only at start time, or when IBMtape is unloaded
manually from, then reloaded into, memory. If you change configuration settings in

Chapter 5. Solaris Tape and Medium Changer Device Driver

119

IBMtape.conf, you can make the changes effective by restarting the system. As an
alternative to restarting, ensure that no IBMtape-owned devices are in use, then
issue the following command.
%
%
%
%

/opt/IBMtape/tmd -s
for IBMtape.4.0.9.2 and later
/usr/sbin/rem_drv IBMtape
/usr/sbin/add_drv -m * 0666 bin bin IBMtape
/opt/IBMtape/tmd
for IBMtape.4.0.9.2 and later

Default settings in IBMtape.conf can be overridden for a particular device (and


only while the device is kept open) with the ioctl application programming
interface (API) of the device driver. The parameter settings that are made through
the API revert to the default values in IBMtape.conf the next time the device is
opened. Refer to the IBM Tape Device Drivers: Programming Reference for information
about changing configuration parameters under program control.
IBMtape.conf contains one stanza for each SCSI target address/LUN pair that is
owned by IBMtape. The reference IBMtape.conf file that is supplied with the
package contains a stanza for every possible SCSI target and LUN combination
that is supported by IBM tape systems.
The following example shows the stanza for target 0, LUN 0, with IBMtape's
default configuration parameter values. The parameter immediate is disabled,
which means that SCSI commands Write FM, Locate, Load-Unload, Erase, and
Rewind complete before status is returned.
name="IBMtape" class="scsi"
target=0 lun=0
block_size=0
buffering=1
immediate=0
trailer=0
sili=0;

The following example shows the stanza for target 0, LUN 0, with IBMtape's
default configuration parameter values and the rewind immediate mode set On.
This action causes the SCSI rewind command to return control to the application
program before the command completes on the tape drive.
name="IBMtape" class="scsi"
target=0 lun=0
block_size=0
buffering=1
rew_immediate=1
trailer=0
sili=0;

If immediate is set to 1 and rew_immediate is set to 0, the setting of rew_immediate


is ignored.
The name variable identifies IBMtape as the device driver, and class identifies the
type of device that is supported as SCSI.
The target and the lun variables determine the target address and LUN of IBM
devices that are controlled by that stanza. On systems with multiple SCSI adapters,
a single target/LUN stanza controls the configuration settings for all devices that
are addressed with that target address and LUN. Thus, two or more supported
IBM devices on the system that have the same target and LUN settings but are
attached to different SCSI buses are all affected by the configuration parameters of
the single stanza with that target address and LUN.

120

IBM Tape Device Drivers Installation and Users Guide

After installation of the IBMtape package is complete, you can eliminate


unnecessary probing for devices by commenting out unused target/LUN pairs. In
this example, the stanzas for target 0, LUN 0 and target 0, LUN 1 are commented
out. Those address/LUN combinations are not probed. This action saves time
during a restart or manual reload of IBMtape. However, if an IBM device is
addressed at target 0, LUN 0 or target 0, LUN 1, it is not detected.
#name="IBMtape" class="scsi"
#target=0 lun=0
#block_size=0
#buffering=1
#immediate=0
#trailer=0
#sili=0;
#name="IBMtape"
#target=0 lun=1
#block_size=0
#buffering=1
#immediate=0
#trailer=0
#sili=0;

class="scsi"

The remaining five configuration parameters specifically affect the behavior of the
IBM device or devices that are associated with that stanza (target and LUN). All of
these parameters are specific to tape drive device operation only and have no
effect on medium changer device behavior. The default configuration parameters
are adequate for most purposes. However, the values in the configuration file can
be modified to suit the specific requirements of the application or the user.
Modifying a value in the configuration file determines the value of the parameter
at device open time. When the device is open, the value of a parameter can be
altered with an ioctl function call. But the change is effective only while the device
remains open. Working configuration parameters revert to the default values
(established by the configuration file) when the device is closed and reopened.
Refer to the IBM Tape Device Drivers: Programming Reference for information about
changing configuration parameters through program control.
Table 25 on page 122 lists and describes the set of configuration parameters that are
recognized by the IBMtape device driver.

Chapter 5. Solaris Tape and Medium Changer Device Driver

121

Table 25. Solaris: configuration parameters recognized by IBMtape


Parameter

Values

Description

block_size

(0=variable
length)

This option specifies the device block size that is


established with the SCSI Mode Select command
during an open function call. Until this value is
changed, it is the working block size. Variable block
size is established with a value of zero. Any other
positive value represents a fixed block size. The
maximum supported block size varies for each tape
device. Refer to the appropriate hardware reference
manual for information.
Note: IBMtape does not allow odd-byte-count fixed
block reads or writes. For instance, a fixed block size
of 4096 or 4098 is allowed, but 4097 is not. If you
attempt to read or write with an odd-byte-count fixed
block size, the read or write returns -1, with errno set
to 22, invalid argument. If you must read or write
odd-byte-count blocks, set block size to 0 (variable
block size), then transfer one blocks worth of data per
read or write.

buffering

(0=Off, 1=On)

When a Write command is processed, the data is either


directly stored on the physical tape or buffered in
device hardware. Buffering can be turned On and Off
with this option. If buffering is disabled, the effective
performance of the device can be degraded seriously.
The tape devices cannot take advantage of their
buffering optimization. Buffer flushing (or committing
data to the tape) can be controlled by the application
through the STIOC_SYNC_BUFFER ioctl function.

immediate

(0=Off, 1=On)

If immediate is set to 0, the SCSI commands Write FM,


Locate, Load-Unload, Erase, and Rewind return with
status when the command actually completes on the
tape drive. If immediate is set to 1, these commands
returns with status before the command actually
completes.

reserve_key

(A string of 1-8
character ASCII
alphanumeric
key such as
"key12345". If
fewer than 8
characters are
used, the
remaining
characters are set
to 0x00(NULL).

The user specifies the Persistent Reservation key that is


used by the device driver when the Persistent
Reservation is used.

reserve_type

The reserve key is assigned by the driver by default.

(1=reserve(6),
This parameter specifies the SCSI Reservation type that
is used by the device driver, either a SCSI Reserve(6)
2=reserve(10),
3=persist_reserve) command or a SCSI Persistent Reserve command.
The SCSI Reserve(10) command is unsupported
recently.
The reserve type 1 is set by default.
Note: This parameter is not used if the Data Path
Failover is supported.

122

IBM Tape Device Drivers Installation and Users Guide

Table 25. Solaris: configuration parameters recognized by IBMtape (continued)


Parameter

Values

Description

rew_immediate (0=Off, 1=On)

If rew_immediate is set to 0, the SCSI Rewind


command returns with status when the command
actually completes on the tape drive. If it is set to 1,
the Rewind command returns with status before the
command actually completes. If immediate is set to 1,
the setting of rew_immediate is ignored.

trailer

(0=Off, 1=On)

If a tape drive encounters logical end-of-tape (EOT)


during a write operation, it returns a check condition
status. The driver returns 0 bytes written to notify the
application of this EOT situation. A check condition is
also returned by the tape drive for every subsequent
write operation when past EOT. If trailer is enabled,
writing records past EOT is allowed by the device
driver. Following the first time the write operation
notifies the application of EOT. All subsequent EOT
notifications are suppressed by the driver, and the
actual number of bytes written is returned. When
physical end of media is reached, all write operations
fail with a return code of -1, regardless of the trailer
setting. When trailer is enabled, managing the media
past EOT is the applications responsibility.

sili

(0=Off, 1=On)

Normally, during a read operation, if a larger block of


data is requested than is read from the tape, the tape
device raises a check condition. The IBMtape device
driver must complete error handling procedures,
which add overhead to the read operation. The
IBMtape driver does not surface this issue as an error
condition to the application and ultimately returns the
actual number of bytes read. However, this driver
error processing results in less than optimum read
performance in some scenarios. When SILI mode is
enabled, the tape device is forced to Suppress Illegal
Length Indication during read operations. This action
eliminates the error processing that is run by the
driver and results in improved read performance for
some scenarios. The actual number of bytes read is still
returned to the application in SILI mode.

max_busy_retry a positive
integer

When a SCSI command is returned as a BUSY status,


IBMtape retries this SCSI command up to 3002 or this
user-defined time in each interval of 1/10 second.

Dynamic Runtime Attributes


This parameter determines whether dynamic runtime attributes are attempted on
open for supported drives. Default is 1 (On) meaning that the driver automatically
attempts to set dynamic runtime attributes on open. This action can be changed to
0 (Off) in the configuration file before the IBMtape is loaded. It is recommended to
keep dynamic runtime attributes On unless it produces an unexpected problem in
the environment.
The dynamic runtime attributes setting is retained even if the system is rebooted.
Follow the steps to enable or disable the Dynamic Runtime Attributes parameter.
1. To enable the support on all currently configured devices, add the entry
Dynamic_Runtime_Attribute =1 at the beginning of the IBMtape.conf file.
Chapter 5. Solaris Tape and Medium Changer Device Driver

123

2. Stop the TMD (tape monitor daemon) running on the system and unload the
IBMtape driver module from the current kernel.
# /opt/IBMtape/tmd -s
# /usr/sbin/rem_drv IBMtape

3. Reload the IBMtape driver module in the kernel and start the daemon.
# /usr/sbin/add_drv -m ' 0666 bin bin' IBMtape
# /opt/IBMtape/tmd

1. To disable the support on all currently configured devices, add the entry
Dynamic_Runtime_Attribute = 0 at the beginning of the IBMtape.conf file.
2. Stop the TMD (tape monitor daemon) running on the system and unload the
IBMtape driver module from the current kernel.
# /opt/IBMtape/tmd -s
# /usr/sbin/rem_drv IBMtape

3. Reload the IBMtape driver module in the kernel and start the daemon.
# /usr/sbin/add_drv -m ' 0666 bin bin' IBMtape
# /opt/IBMtape/tmd

Removing IBMtape
All active processes that use IBM devices that are supported by the IBM SCSI Tape
and Medium Changer Device Driver for Solaris must be stopped for the removal
procedure to complete successfully.
Use the pkgrm command to remove the IBMtape package from the system.
% /usr/sbin/pkgrm IBMtape

Adding or removing devices


To add support for a new IBM tape system or to remove support for a previously
attached IBM tape system, complete the following steps.
1. Edit the IBMtape.conf file in the /usr/kernel/drv directory to reflect the
change in IBM device support. Either add a stanza to provide support for a
device that is to be added, or remove (comment out) a stanza for a device that
is no longer supported.
2. When support for a new device is added, ensure that the target and LUN
values in the configuration file stanza match the target and LUN settings of the
IBM device. Refer to Configuration parameters on page 119 for information
about the IBMtape.conf configuration file.
3. Shut down and power Off the host system.
4. Plug the new device into the SCSI bus or unplug the existing device from the
bus. Pay particular attention to correct SCSI cabling and termination.
5. Power On and start the host system.
Note:
a. It is possible to reinitialize the IBMtape device driver without
restarting the system. This procedure is done by first unloading the
device driver, then reloading the device driver into kernel memory.
b. For the version of IBMtape.4.0.9.2 and later, the TMD daemon must
be stopped. Run the /opt/IBMtape/tmd -s command to unload the
IBMtape driver from the kernel. Running the /opt/IBMtape/tmd
command restarts the daemon afterward to reload the device driver.
The commands to unload the device driver are

124

IBM Tape Device Drivers Installation and Users Guide

% /opt/IBMtape/tmd -s
% /usr/sbin/rem_drv IBMtape

for IBMtape.4.0.9.2 and later

The commands to reload the device driver are


% /usr/sbin/add_drv -m * 0666 bin bin IBMtape
% /opt/IBMtape/tmd
for IBMtape.4.0.9.2 and later

When the IBMtape device driver is reloaded, it reads the IBMtape.conf file
and acknowledge changes that are made in the file. This method can be used to
modify configuration parameters.
Note: It is suggested that the host system and all devices that are attached to
the SCSI bus be powered Off before devices are added or removed from
the SCSI bus. Hot plugging SCSI devices can cause hardware damage
and disruption of reliable system operation

Unconfiguring tape devices


In some special situations, the user cannot modify IBMtape.conf to unconfigure
some tape devices with IBMtape driver. This issue occurs when more than one
device is configured with the same target address, or the tape devices are attached
on the FC or SAS HBA running with Oracle HBA driver.
In IBMtape.4.1.9.2 and later, a configuration parameter defined exclude_dev_list
is introduced to allow users to exclude some devices from the configuration with
IBMtape.
Unconfigure the tape device with the following steps.
1. Add the entry of exclude_dev_list in IBMtape.conf in /usr/kernel/drv.
exclude_dev_list=sn1,sn2,sn3,... ;

Where: sn is the serial number of the excluded device, 10-characters long for
LTO drive, 12-characters long for 359x drive and 16-characters long for changer.
The serial number can be found by running the following command.
/opt/IBMtape/tapelist -l

2. Reinstall IBMtape driver or reboot the system to allow IBMtape to update the
configuration.

Tapelist Utility Program


A Tapelist Utility Program that is called tapelist is installed in the /opt/IBMtape
directory as part of the IBMtape package. The tapelist utility provides the user a
listing of tape, medium changer, and SAN data gateway devices that are
configured with the IBMtape driver. It also displays the information of HBA with
IBM tape drive attachment and the status of load balancing. The following is an
example of a Tapelist Utility Program output.

Chapter 5. Solaris Tape and Medium Changer Device Driver

125

# tapelist
Instance : 697
Special File : /dev/rmt/6st
Device : 03592E05(e/e)
Serial Number : 000001300168
TGT/LUN : 7/0
Ucode : 04C4
World Wide NN : 5005076302000127
World Wide PN : 5005076302400127
Dev Phy Path : /devices/pci@1f,2000/QLGC,qla@1/IBMtape@7,0:st
Path Type : N/A
# tapelist -t
hba_index hba_inst hba_driver reg_count usage_count
HBA Path
--------- -------- ----------- ----------- ----------- --------------------------
0
0
qla2300
4
1
/devices/pci@4,2000/fibre-channel@1
1
2
lpfc
4
2
/devices/pci@6,2000/pci@1/fibre-channel@4
2
3
lpfc
1
0
/devices/pci@6,2000/pci@1/fibre-channel@5

A new feature is added in tapelist to display the drive information in the library
that is running /opt/IBMtape/tapelist -L.
# tapelist -L
Addr Inst# Special File Device
----- ----- ------------- ------------Library (/dev/rmt/5smc) Info:
2894 /dev/rmt/5smc 03584L22
274
2893 /dev/rmt/13st 03592E05(e/e)
276
2914 /dev/rmt/14st 03592E06(e/e)

Serial No
TGT/LUN Ucode World Wide NN
---------------- ------- ----- -------------0000000T003904E5
000001365066
000001326803

World Wide PN
--------------

3/1
3/0
14/0

806c
1D10
2444

N/A
N/A
500507630019F016 500507630059F016
500507630019F019 500507630059F019

Library (/dev/rmt/7smc) Info:


2899 /dev/rmt/7smc 03584L32
0000000T00390401
265
2898 /dev/rmt/6st ULT3580-TD4(e) 1300000044

6/1
6/0

806c
82F0

N/A
N/A
500507630019F009 500507630059F009

Library 3494 Info:


322
/dev/rmt/10st 03592J1A

1/0

0464

5005076300000000 5005076300400000

000001300147

The following is a definition of the fields and headers that appear in the previous
screens.
Inst #
Special File
Device
TGT/LUN
Ucode level
World Wide NN
World Wide PN
Dev Phy Path
Path Type
hba_index
hba_inst
hba_driver
reg_count
usage_count
HBA Path
Addr
e/e

The instance number of the particular device.


The device special file used to access this device.
A string indicating the device model and encryption information
(e/e: encryption capable/encryption enable).
Serial No: The serial number of the device.
The SCSI target and LUN of the device.
The current microcode (firmware) loaded on the device.
A number indicating Fibre Channel World Wide Node Name of the device.
A number indicating Fibre Channel World Wide Port Name of the device.
A string indicating the device path in the device tree.
A primary or alternate path used for failover.
The index number of the particular HBA in the HBA list.
The instance number of the particular HBA assigned by the
Solaris system.
The HBA driver name with IBM tape drive attachment.
The number of IBM tape drives attached on the HBA.
The number of IBM tape drives currently using the HBA.
A string indicating the HBA device path in the device tree.
The element address where the drive is located in the library.
The first and second instances of "e" stand for encryption
capable and encryption enable.

The usage of the tapelist program is as follows.

126

IBM Tape Device Drivers Installation and Users Guide

-l
-L
-c
-t
-f
-A
-a
-h

Print for all of the configured devices with the column headers in long list
Display the tape drives information in the tape library
(IBMtape supported Libraries ONLY)
Dont print column headers in long list for all of the configured devices
Display HBA information and current load balancing status
Print the list for a particular file only
List the tape devices by HBA
Print out the info of all of FC HBAs
Help menu

Running tapelist without any options displays the device information line by line
for all of the configured devices.

Special files
After the IBMtape driver is installed, a set of special files is available for
completing input/output (I/O) operations to each supported device. The device
special file names that are created by the IBMtape device driver are similar to the
SCSI tape special files used on Solaris systems.
Each tape instance has a set of minor numbers that provides access to the same
physical device. But, each minor number provides a different function or behavior
for the tape subsystem. These minor numbers are accessed through variations of
the special file name for that device. The special files are created in the /dev/rmt
directory. These special files are symbolic links to files created within the /devices
subdirectory hierarchy.
Issuing the ls -la /dev/rmt command gives useful information about these device
special files. The following example shows entries that are returned by this
command for a single IBM tape subsystem. This listing is system-dependent, so
entries vary slightly in format, depending on the operating system and SCSI
adapter support. Entries might be included for other devices that are not
supported by the IBMtape device driver.
lrwxrwxrwx root other 79 Aug 26 18:54 0smc
->
/devices/iommu@f,e0000000/sbus@f,e0001000/QLGC,isp@3,
10000/IBMtape@2,0:smc
lrwxrwxrwx root other 78 Aug 26 18:54 0st
->
/devices/iommu@f,e0000000/sbus@f,e0001000/QLGC,isp@3,
10000/IBMtape@2,0:st
lrwxrwxrwx root other 79 Aug 26 18:54 0stb
->
/devices/iommu@f,e0000000/sbus@f,e0001000/QLGC,isp@3,
10000/IBMtape@2,0:stb
lrwxrwxrwx root other 80 Aug 26 18:54 0stbn ->
/devices/iommu@f,e0000000/sbus@f,e0001000/QLGC,isp@3,
10000/IBMtape@2,0:stbn
lrwxrwxrwx root other 79 Aug 26 18:54 0stc
->
/devices/iommu@f,e0000000/sbus@f,e0001000/QLGC,isp@3,
10000/IBMtape@2,0:stc
lrwxrwxrwx root other 80 Aug 26 18:54 0stcb ->
/devices/iommu@f,e0000000/sbus@f,e0001000/QLGC,isp@3,
10000/IBMtape@2,0:stcb
lrwxrwxrwx root other 81 Aug 26 18:54 0stcbn ->
/devices/iommu@f,e0000000/sbus@f,e0001000/QLGC,isp@3,
10000/IBMtape@2,0:stcbn
lrwxrwxrwx root other 80 Aug 26 18:54 0stcn ->
/devices/iommu@f,e0000000/sbus@f,e0001000/QLGC,isp@3,
10000/IBMtape@2,0:stcn
lrwxrwxrwx root other 79 Aug 26 18:54 0stn
->
/devices/iommu@f,e0000000/sbus@f,e0001000/QLGC,isp@3,
10000/IBMtape@2,0:stn

Chapter 5. Solaris Tape and Medium Changer Device Driver

127

These entries show the device hierarchy that is established to support I/O for an
IBM SCSI tape system. The attachment path of the device special files spans from
the system board, through the S-bus, to the Oracle F/W SCSI adapter (supported
by the QLGC, isp SCSI adapter device driver), to the IBM device at SCSI target 2
and LUN 0 (supported by the IBMtape device driver). All nine of these special
files are associated with the same IBM device (device number 0).

Device behaviors
Certain device behaviors are determined by which special file in the set is opened
for device access. The smc special file controls only the medium changer portion of
the device and accepts only medium changer operations by way of the ioctl entry
point. The smc special file does not support the read and write entry points. Only
one st type special file for a particular device can be opened at any one time. The
smc special file can be opened concurrently with any one of the st special files.
The IBMtape device driver decides which types of special files to create during
installation, which is based on the IBM device type that is configured. For the IBM
3490E Magnetic Tape Subsystem, only the eight st type special files are created. For
other IBM tape drives, all nine special files that are shown previously are created.
For IBM tape libraries and autoloaders, only a single smc special file is created.
With the information from the previous command, issuing the ls -la
/devices/iommu@f,e0000000/sbus@f,e0001000/QLGC,isp@3,10000 command
presents further information about the same special files, as shown in the following
example. Again, the actual path information that is specified in the command
varies from system to system.
crw-rw-rwcrw-rw-rwcrw-rw-rwcrw-rw-rwcrw-rw-rwcrw-rw-rwcrw-rw-rwcrw-rw-rwcrw-rw-rw-

1
1
1
1
1
1
1
1
1

bin
bin
bin
bin
bin
bin
bin
bin
bin

bin
bin
bin
bin
bin
bin
bin
bin
bin

109,1696
109,1664
109,1728
109,1732
109,1688
109,1752
109,1756
109,1692
109,1668

Aug
Aug
Aug
Aug
Aug
Aug
Aug
Aug
Aug

26
26
26
26
26
26
26
26
26

18:54
18:56
18:54
18:54
18:54
18:54
18:54
18:54
18:54

IBMtape@2,0:smc
IBMtape@2,0:st
IBMtape@2,0:stb
IBMtape@2,0:stbn
IBMtape@2,0:stc
IBMtape@2,0:stcb
IBMtape@2,0:stcbn
IBMtape@2,0:stcn
IBMtape@2,0:stn

These entries show the major and minor numbers that are associated with each
special file. Here, the major number is 109 and identifies to the system that the
IBMtape device driver is in support of these special files. Major numbers are
assigned by the system at the time the driver is installed and vary from system to
system. The nine different minor numbers are specific to the special file names.
They are used by the device driver to determine which special file was used to
access the device and control the device behavior accordingly. For example, the
minor number 1696 indicates to the driver that the device was opened by way of
the smc special file. For information on device special files and major and minor
numbers, consult the Solaris mtio man pages.

File naming conventions


Table 26 on page 129 shows the special file naming convention and the associated
device attributes recognized by the IBMtape device driver.

128

IBM Tape Device Drivers Installation and Users Guide

Table 26. IBM SCSI Tape/Medium Changer special files for Solaris
BSD compatibility (Note
1)

Rewind on Close (Note 2)

Compression (Note 3)

/dev/rmt/[0255]smc (Note 4)

N/A

N/A

N/A

/dev/rmt/[0255]stn (Note 5)

No

No

No

/dev/rmt/[0255]stcn (Note 5)

No

No

Yes

/dev/rmt/[0255]st (Note 5)

No

Yes

No

/dev/rmt/[0255]stc (Note 5)

No

Yes

Yes

/dev/rmt/[0255]stbn (Note 5)

Yes

No

No

/dev/rmt/[0255]stcbn (Note 5)

Yes

No

Yes

/dev/rmt/[0255]stb (Note 5)

Yes

Yes

No

/dev/rmt/[0255]stcb (Note 5)

Yes

Yes

Yes

Special file name

Note:
1. The BSD (b) device special file modifies close behavior for non-rewind devices. If the device is opened for no
rewind on close in non-BSD mode, and if the last command before the device was closed was a read, then the
tape is positioned after the filemark immediately following the last block read. If the device is opened for no
rewind on close in BSD mode, and if the last command before the device was closed was a read, the tape is left
positioned exactly where it was following the last block read. If the device is opened for rewind on close the
BSD mode is not relevant.
2. The no rewind on close (n) device special file does not rewind the tape during a close operation. Otherwise, the
tape is rewound when the device is closed. If the last operation before the device was closed was a write or
write filemark, then enough filemarks is written so that two filemarks follow the data.
For the non-rewind special files, the tapes are positioned between the trailing filemarks before closing. If the
device is then reopened and more data is written, it is separated by a single filemark from the previous data.
3. The compression (c) device special file determines whether the tape device uses built-in hardware compression
while data is stored on the tape. The compression mode of the device can also be set to the wanted state
programmatically through the STIOC_SET_PARM ioctl, regardless of the default compression mode that is
established by the special file that is originally used to open the device.
4. The smc special file is created only for IBM tape systems that provide medium changer capability. For IBM tape
libraries and autoloaders, the smc special file is the only file that is created because the IBMtape device driver
supports only the medium changer portion. It does not support the tape drive portion of these devices. For the
IBM 3490E Magnetic Tape System, there is no smc special file created.
5. Only one st special file can be opened at one time. The smc special file can be opened by itself or with one of
the st type files. The smc special file accepts only medium changer commands. Tape drive commands that are
issued to the medium changer fail, with errno set to 22, invalid argument.
Aside from the normal configuration with the medium changer that answers as a distinct target/LUN pair, some
supported devices can be configured with a nonstandard integrated medium changer that reports at the same
target and LUN as the tape drive. In such a case, both st and smc special files accept a limited subset of medium
changer commands. If you want to use this nonstandard mode, consult the appropriate hardware reference to
determine whether the drive supports such a configuration.

Persistent Naming Support


The device special file names are created by the IBMtape driver in the order that
the tape devices are presented by the Solaris system. Each device special file name
is maintained with the same logical name across reboots, even when an existing
device is powered off or not connected.
However, the logical names of devices can be changed because of the swapping of
connecting cables, HBA mapping changes, tape device driver updates, or other
reasons.
Chapter 5. Solaris Tape and Medium Changer Device Driver

129

The user can rename the logical name by editing the /etc/devlink.tab system file
for the persistent name binding and reloading the IBMtape driver as follows.
1. Before the persistent name binding, make sure that the IBM tape devices are
configured at the different target and LUN addresses if the devices are attached
on more than one HBA.
The Ultrium 3 tape drive is connected to two Emulex HBAs with the same
address of target 3 and LUN 0 through a switch in the following example. You
must use the HBA utility, follow HBA vendor instructions, or both to
persistently bind the tape devices at the different mapped target and LUN.
# tapelist -l
Inst# Special File
Device
Serial No
TGT/LUN
Device Physical Path
------ -------------- ------------- ------------ -------- ------------------------------------454
/dev/rmt/2st
ULT3580-TD3
1210003557
3/0
/devices/pci@6,2000/pci@1/fibre-channel@5/IBMtape@3,0
582
/dev/rmt/8st
ULT3580-TD3
1210003557
3/0
/devices/pci@1f,2000/pci@1/fibre-channel@5/IBMtape@3,0

The tape drive is mapped at target 3, LUN 0 on HBA 1 and target 24, LUN 0
on HBA 2 after device persistent binding.
# tapelist -l
Inst# Special File
Device
Serial No
TGT/LUN
------ --------------- ----------- --------- ---------454
/dev/rmt/4st
ULT3580-TD3
1210003557
3/0
1136 /dev/rmt/7st
ULT3580-TD3
1210003557
24/0

Device Physical Path


---------------------------------------/devices/pci@6,2000/pci@1/fibre-channel@5/IBMtape@3,0
/devices/pci@1f,2000/pci@1/fibre-channel@5/IBMtape@18,0

Note: Device persistent binding is not provided on Oracle HBAs, so this


persistent name approach cannot be used with the same physical drive
that is attached to multiple Oracle HBA ports.
2. Start persistent name binding. In this example, the user renames 4st and 7st to
10st and 11st.
a. Create the entry for persistent naming. Determine the target address from
the Device Physical Path in the output of tapelist -l and add the planned
device special file name in the entry. Here, 4st and 7st drives are at 3,0
(target 3, LUN 0) and 18,0 (target 24 (0x18), LUN 0) at the device physical
paths of /devices/pci@6,2000/pci@1/fibre-channel@5/IBMtape@3,0 and
/devices/pci@1f,2000/pci@1/fibre-channel@5/IBMtape@18,0. Add the
address and device file name into the entries:
type=ddi_byte:tape;addr=3,0;
type=ddi_byte:tape;addr=18,0;

rmt/10\M0
rmt/11\M0

Note:
1) A tab is entered between addr=3,0; and rmt/10\M0.
2) The 0 in the entry is the zero in M0.
3) To avoid conflicts with the current device special files assigned by
the system automatically, be sure to assign a higher number for
the persistent name.
4) The address is w500507630059f007,0 for the tape drive on the
Oracle HBA with the path of /devices/pci@1,0/pci1022,7450@1/
pci1077,141@1/fp@0,0/tape@w500507630059f007,0.
.
b. Add the entry into the /etc/devlink.tab system file.

130

IBM Tape Device Drivers Installation and Users Guide

c. Remove existing links that are created by the IBMtape driver from /dev/rmt
by running the # rm command.
d. Run the # devfsadm command without any options to enable IBMtape to
create the new device special file name as defined in the entries in
/etc/devlink.tab. A system reboot is also required if the tape device is
attached on Oracle HBA.
e. Run tapelist to list the device special files.
# tapelist -l
Inst# Special File
Device
Serial No
TGT/LUN
Device Physical Path
------ ------------- ------------ ------------- ---------- ------------------------454
/dev/rmt/10st ULT3580-TD3 1210003557
3/0
/devices/pci@6,2000/pci@1/fibre-channel@5/IBMtape@3,0
1136 /dev/rmt/11st ULT3580-TD3 1210003557
24/0
/devices/pci@1f,2000/pci@1/fibre-channel@5/IBMtape@18,0

Control Path failover support for libraries


Configuring and deconfiguring Path Failover support
Control path failover (CPF) support is enabled automatically by default when the
IBMtape device driver is installed on Solaris system. The Solaris IBMtape device
driver provides a driver configuration parameter failover for you to enable or
disable the library control path failover support. To enable the CPF support for all
of the paths, no action is required. To disable the CPF support for all of the paths
or a particular path, use the following steps.
1. To disable CPF support for all the paths, add and set the failover parameter to
off at the beginning of IBMtape.conf file in the directory of /usr/kernel/drv.
2. To disable a particular path, add and set the failover parameter to Off in the
path entry in IBMtape.conf file. For example, name="IBMtape" class="scsi"
target=3 lun=1 failover=0;
3. Stop the TMD (tape monitor daemon) from running on the system and unload
the IBMtape driver module from the current kernel.
# /opt/IBMtape/tmd -s
# /usr/sbin/rem_drv IBMtape

4. Reload the IBMtape driver module in the kernel and start the daemon.
# /usr/sbin/add_drv -m ' 0666 bin bin' IBMtape
# /opt/IBMtape/tmd

Primary and alternative paths


When the device driver configures a logical device with path failover support
enabled, the first device that is configured always becomes the primary path.
When a second or more logical device is configured with path failover support
enabled for the same physical device, it configures as an alternative path. The
device driver supports up to 16 physical paths for single a device.
The primary and alternative path information can be obtained in the field of "Path
Type" running the /opt/IBMtape/tapelist command output and is similar to the
example in Table 27 on page 132.

Chapter 5. Solaris Tape and Medium Changer Device Driver

131

Table 27. Solaris: Example of Control Path failover support command output
#tapelist -1
Inst# Special File Device Serial No TGT/LUN Ucode WWNN WWPN Device Physical Path
Path Type
------------------------------------------------------------------------------------------------------------686 /dev/rmt/12smc 03584L32 0000000T0039 1/1 402j N/A N/A /devices/pci@If,2000/QLGC,qla@1/IBMtape@1,1 Primary
688 /dev/rmt/14smc 03584L32 0000000T0039 2/1 402j N/A N/A /devices/pci@If,2000/QLGC,qla@1/IBMtape@2,1 Alt_path_1
694 /dev/rmt/26smc 03584L32 0000000T0039 5/1 402j N/A N/A /devices/pci@If,2000/QLGC,qla@1/IBMtape@5,1 Alt_path_2

The labeling of a logical device as either a primary or alternative path is for


information only; it is used to
1. Identify the actual number of physical devices that are configured on the
system and a specific logical device that is associated with them. Only one
logical device is labeled the primary path for each physical device. However,
multiple logical devices can be labeled as an alternative path for the same
devices.
2. Provide information about which logical devices that are configured on the
system have path failover enabled.

Querying primary and alternative path configuration


You can display the primary and alternative path configuration for all devices with
the tapelist utility.
Note: Display the primary and alternative path configuration for any device by
using tape diagnostic and utility functions. Refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Disabling and enabling primary and alternative paths


When you install the IBMtape device driver, by default all the available paths for a
physical device are enabled.
Note: Display the primary and alternative path configuration for any device by
using tape diagnostic and utility functions. Refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Data Path failover and load balancing support for tape drives
Note: The tape drive failover feature code must be installed before the DPF for
IBM Ultrium tape drive is enabled in the Solaris IBMtape device driver.
Refer to Automatic failover on page 1 to determine which feature code is
required for your machine type.

Configuring and deconfiguring Path Failover support


Path failover support for tape drives is enabled automatically when the device
driver with the version of IBMtape.4.2.1.0 or later is installed. It is disabled by
default at the previous version. When path failover support is enabled for a logical
device, it remains set until the device is deleted or the support is deconfigured.
The path failover setting is retained even if the system is rebooted. Path failover
support can be enabled on all configured devices at one time, or it can be enabled

132

IBM Tape Device Drivers Installation and Users Guide

or disabled selectively by logical device. It might be desirable at times to configure


some, but not all, logical paths to a device with the support enabled. Follow the
steps to enable the DPF support:
1. To enable the support globally on all currently configured devices, add an entry
of dpf_support=1 at the beginning of the IBMtape.conf file, such as
dpf_support=1;

2. Or, to enable a particular path, add the parameter dpf_support and turn it on
in the path entry in the IBMtape.conf file. For example,
name="IBMtape" class="scsi" target=3 lun=0 dpf_support=1;

3. For the IBM Ultrium tape drive, you must enter the DPF feature keys in the
parameter dpf_keys at the beginning of the IBMtape.conf file in the directory
/usr/kernel/drv. For example,
dpf_keys="A729E60F7B119411, C7A0B9ef2c1a4360, a729e60f7b118460";

Note:
a. The parameter dpf_keys is in the format key1, key2, key3, ...... .
Each key is 16 characters long with a comma "," and a space " ". The
IBMtape driver supports up to 36 dpf keys.
b. DPF keys do not need to be added in IBMtape.conf if you are
running the latest drive code on Ultrium 3 and Ultrium 4 drives.
4. Stop the TMD (tape monitor daemon) running on the system and unload the
IBMtape driver module from the current kernel.
# /opt/IBMtape/tmd -s
# /usr/sbin/rem_drv IBMtape

5. Reload the IBMtape driver module in the kernel and start the daemon.
# /usr/sbin/add_drv -m 0666 bin bin IBMtape
# /opt/IBMtape/tmd

This action deconfigures all devices to add the parameter dpf_support=0 in the
IBMtape.conf file, and reboot the system or deconfigure and reconfigure all
devices. For example,
1. To disable the support globally on all currently configured devices, add the
entry dpf_support=1 at the beginning of the IBMtape.conf file.
# dpf_support=0;

2. Stop the TMD (tape monitor daemon) from running on the system and unload
the IBMtape driver module from the current kernel.
# /opt/IBMtape/tmd -s
# /usr/sbin/rem_drv IBMtape

3. Reload the IBMtape driver module in the kernel and start the daemon.
# /usr/sbin/add_drv -m 0666 bin bin IBMtape
# /opt/IBMtape/tmd

To disable the support on a single logical device, follow these steps.


1. To enable the support globally on all currently configured devices, add an entry
dpf_support=1 at the beginning of the IBMtape.conf file, such as
dpf_support=1;

2. To disable a particular path, add the parameter dpf_support and turn it off in
the path entry in the IBMtape.conf file. For example,
name="IBMtape" class="scsi" target=3 lun=0 dpf_support=0;

3. Stop the TMD (tape monitor daemon) running on the system and unload the
IBMtape driver module from the current kernel.
Chapter 5. Solaris Tape and Medium Changer Device Driver

133

# /opt/IBMtape/tmd -s
# /usr/sbin/rem_drv IBMtape

4. Reload the IBMtape driver module in the kernel and start the daemon.
# /usr/sbin/add_drv -m 0666 bin bin IBMtape
# /opt/IBMtape/tmd

Primary and alternative paths


When the device driver configures a logical device with path failover support
enabled, the first device that is configured always becomes the primary path.
When a second logical device is configured with path failover support enabled for
the same physical device, it configures as an alternative path. A third logical device
is configured as the next alternative path, and so on. The device driver supports
up to 16 physical paths for a single device.
For example, if 0st (port 0 of 3592) is configured first, then 5st (port 1), 18st (port
1), and 21st (port 0) to the two HBAs through a switch (here, WWPN
5005076302400127 from port 0 and 5005076302800127 from port 1), the
/opt/IBMtape/tapelist command output is similar to the example in Table 28.
Table 28. Example of Data Path failover support command output
#tapelist -1
Inst# Special File
Device Serial No
TGT/LUN Ucode
WWNN
WWPN
Device Physical Path
Path Type
-------------------------------------------------------------------------------------------------685
/dev/rmt/0st 03592J1A 000001300168
1/0 04CE 5005076302000127 5005076302400127
/devices/pci@1f,2000/QLGC,qla@1/IBMtape@1,0
Primary
697
/dev/rmt/5st 03592J1A 000001300168
7/0 04CE 5005076302000127 5005076302800127
/devices/pci@1f,2000/QLGC,qla@1/IBMtape@7,0
Alt_path_1
666
/dev/rmt/18st 03592J1A 000001300168 1/0 04CE 5005076302000127 5005076302800127
/devices/pci@1f,4000/JNI,FCR@2/IBMtape@1,0
Alt_path_2
670
/dev/rmt/21st 03592J1A 000001300168 3/0 04CE 5005076302000127 5005076302400127
/devices/pci@1f,4000/JNI,FCR@2/IBMtape@3,0
Alt_path_3

The labeling of a logical device as either a primary or alternative path is for


information only, to
1. Be able to identify the actual number of physical devices that are configured on
the system and a specific logical device that is associated with them. Only one
logical device is labeled the primary path for each physical device. However,
many (multiple) logical devices might be labeled as an alternative path for the
same devices.
2. Provide information about which logical devices configured on the system have
path failover support enabled.

Querying primary and alternative path configuration


You can display the primary and alternative path configuration for all devices with
the tapelist utility.
Note: Display the primary and alternative path configuration for any device by
using tape diagnostic and utility functions. Refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

134

IBM Tape Device Drivers Installation and Users Guide

Disabling and enabling primary and alternative paths


When you enter the parameter dpf_support in the IBMtape.conf file and install the
IBMtape device driver, all the available paths for a physical device are enabled.
1. Add the parameter of dpf_support and turn it off in the path entry in
IBMtape.conf file. For example,
name="IBMtape" class="scsi" target=3 lun=0 dpf_support=0

2. Stop the TMD (tape monitor daemon) from running on the system and unload
the IBMtape driver module from the current kernel.
# /opt/IBMtape/tmd -s # /usr/sbin/rem_drv IBMtape

3. Reload the IBMtape driver module in the kernel and start the daemon.
# /usr/sbin/add_drv -m ' 0666 bin bin' IBMtape
# /opt/IBMtape/tmd

To enable a path from a disabled state, you can run the following steps.
1. Add the parameter of dpf_support and turn it off in the path entry in
IBMtape.conf file. For example,
name="IBMtape" class="scsi" target=3 lun=0;

2. Stop the TMD (tape monitor daemon) from running on the system and unload
the IBMtape driver module from the current kernel.
# /opt/IBMtape/tmd -s
# /usr/sbin/rem_drv IBMtape

3. Reload the IBMtape driver module in the kernel and start the daemon.
# /usr/sbin/add_drv -m ' 0666 bin bin' IBMtape
# /opt/IBMtape/tmd

System-managed encryption
Device driver configuration
System-Managed Encryption can be set on global or a specific tape drive in
IBMtape.conf in /usr/kernel/drv. There are two new configuration parameters
added for encryption.
v sys_encryption_proxy ON/OFF Use System Encryption FCP Proxy Manager
v sys_encryption_write OFF/ON/CUSTOM System Encryption for Write
Commands at BOP
The sys_encryption_proxy parameter enables device driver system-managed
encryption for a tape drive by setting the value to ON (default set).
The sys_encryption_write parameter controls if the device driver can set the tape
drive to encryption enabled for write commands. When set to OFF, the tape drive
uses encryption for read operations; write operations do not use encryption. When
set to ON, the tape drive uses encryption for both read/write operations. When set
to CUSTOM, the device driver does not modify current tape drive setting. The
custom setting is intended for applications by using system-managed encryption to
control write encryption without device driver intervention. The parameter is set to
CUSTOM by default.
Note: If sys_encryption_write is set to ON, an application cannot open a tape
drive by using the append mode.

Chapter 5. Solaris Tape and Medium Changer Device Driver

135

To make a global setting to enable SME in IBMtape.conf:


sys_encryption_write=1;

# System Encryption for Write Commands at BOP

To enable SME for a particular target


v name="IBMtape"
v class="scsi"
v target=0
v
v
v
v
v
v
v

lun=0
block_size=0
buffering=1
immediate=0
trailer=0
sili=0
sys_encryption_write=1;

To disable SME in a particular target


v
v
v
v
v

name="IBMtape"
class="scsi"
target=0
lun=0
block_size=0

v buffering=1
v immediate=0
v trailer=0
v sili=0
v sys_encryption_proxy=0;

Querying tape drive configuration


Querying tape drive configuration is a tape diagnostic and utility function. Refer to
Chapter 8, IBM Tape Diagnostic Tool (ITDT), on page 211.

Testing data encryption configuration and connectivity


A data encryption test is available to validate the ibmekm.conf file server entries
and test tape drive to server connectivity operations.
This test is a tape diagnostic and utility function. Refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Field support information


When encryption failures require field support or development analysis, run the
/opt/IBMtape/diags_info script to generate a file of diags.out. Tape drive dumps
and EKM server logs might be needed in addition to this information.

136

IBM Tape Device Drivers Installation and Users Guide

Problem determination
The following sections describe the service and diagnostic aids that are part of the
IBM SCSI Tape and Medium Changer Device Driver for Solaris package.
Procedures for verifying correct installation of the device, basic problem
determination guidelines, and outlines of the utility program included with the
IBMtape package are included.

Functional verification
If you wish to verify that the installation of the IBM SCSI Tape and Medium
Changer Device Driver for Solaris package was successful, follow these steps.
1. Enter this command to verify that installation was successful.
/usr/bin/pkginfo IBMtape

The following information must be displayed.


system IBMtape IBM SCSI Tape & Medium Changer Device Driver x.x.x.x
where x.x.x.x is the version of the device driver.
2. To verify that device driver support for a specific IBM tape system that is
attached to the system is functioning correctly, enter the following command.
/opt/IBMtape/tapelist -f /dev/rmt/nst

substituting for n the number that is associated with the device special file
assigned to the IBM tape system that you want to check. Listing the contents of
the /dev/rmt directory (by using the ls command) can be helpful in
determining the correct special file name. For medium changer devices, the
special file name /dev/rmt/nsmc must be used.
The following information is displayed.
IBM Tape Device
Instance
Special File
Device
Serial Number
TGT/LUN
Ucode
World Wide NN
World Wide PN
Dev Phy Path
Path Type
Path Type

Information :
: 202
: /dev/rmt/13st
: ULT3580-TD5(fh)
: 1013000306
: 5/0
: z1B8
: 500507630019F00B
: 500507630059F00B
: /devices/pci@6,2000/fibre-channel@1/IBMtape@5,0
: N/A
: N/A

3. To verify that the IBMtape device driver is loaded in kernel memory, enter the
following command.
/usr/sbin/modinfo | /usr/bin/grep IBMtape

The following information is displayed.


165 f5f10000

15c0s 109

IBMtape (IBM SCSI Tape/Medium Changer DD)

The first five fields that are shown probably do not match your specific output.
The fields indicate the ID, load address, size, major number, and revision for the
IBMtape device driver and vary from machine to machine

Sense data logging


When the tape drive responds with a CHECK CONDITION status and associated
sense keys of 0x1 (Recovery Error), 0x3 (Medium Error), 0x4 (Hardware Error), and

Chapter 5. Solaris Tape and Medium Changer Device Driver

137

0xB (Aborted Command) for a hardware or medium error, the sense data is logged
in to the system log file (typically /var/adm/messages).

Installation problems
If you are experiencing problems with installation of the IBM SCSI Tape and
Medium Changer Device Driver for Solaris package, the following information
might help. If you cannot solve the problems after the following is checked, contact
the appropriate IBM service representative.
v If you receive the following message during installation,
drvconfig: System call modctl_modconfig failed:
No such device or address.
Warning: Driver (IBMtape) configuration failed.
System could not install driver.

it indicates that the IBMtape device driver was not loaded because it did not
detect the presence of any supported IBM devices on the SCSI bus. Verify that
SCSI adapter device driver support is installed and configured correctly. Verify
that the IBM tape subsystem is connected properly to the SCSI bus, which is
powered On, and online. It is not necessary for the tape drive to have a
cartridge that is loaded to be recognized by the IBMtape device driver.
v If you cannot open an IBM device, verify that you are using the correct special
file. The IBM tape special files are of the form *st* in the /dev/rmt directory. The
IBM medium changer special files are of the form *smc in the /dev/rmt
directory. Ensure that the Solaris native tape device driver (st) is not contending
for the same IBM device. Consult the st.conf file in the /kernel/drv directory
and comment out conflicting stanzas.

Tape monitor daemon (tmd)


The Tape Monitor Daemon is introduced in the version of IBMtape.4.0.9.2 or later.
It is designed to run concurrently with the IBMtape driver. It automatically
retrieves and stores the IBM tape drive diagnostic information (drive dump) into
the /var/opt/IBMtape directory. The daemon is automatically started when the
driver is installed, even when no tape device is attached on the system. An entry
name="IBMtape" parent="pseudo" instance=16383; is also entered into the
configuration file of /usr/kernel/drv/IBMtape.conf automatically for the daemon
during the IBMtape driver installation.
The following options can be used to configure the tape monitor daemon, running
it on the command line. Most options can also be specified in the /etc/tmd.conf
configuration file. However, the command line options override any configuration
file options.
-s
-r
-d
-D
-p
-l
-y
-z

138

Stop any currently running instance of the tape monitor daemon.


Restart the tape monitor daemon and reload all configuration settings.
Turn on drive error diagnostic retrieval and storage.
This option is enabled by default.
Turn off drive error diagnostic retrieval and storage.
<directory> Specify an alternate directory for the storage of
drive diagnostic information. Default directory is /var/opt/IBMtape
<filename> Specify a file for writing daemon related log messages.
By default, the tmd only writes status information to the syslog file of
/var/adm/messages.
Turns off writing log messages to syslog.
Turn off compression. By default, the tmd will use a form of file compression
to reduce the size of stored diagnostic information.

IBM Tape Device Drivers Installation and Users Guide

The file name of dump presents some useful information. An example of the dump
file is
IBMtape.000001300148.2004-04-09-14:54:14.dump.gz

Here, 000001300148 represents the serial number of the tape device,


2004-04-09-14:54:14 is the time stamp for the dump retrieval.
A message is also logged in the syslog file of /var/adm/messages after a drive
dump is retrieved by tmd. For example,
Apr

9 14:54:21 Java tmd[3279]: Drive dump saved to /var/opt/IBMtape


IBMtape.000001300148.2004-04-09-14:54:14.dump.

Tracing facility
IBMtape incorporates a tracing facility that is useful for completing problem
determination. The tracing facility logs diagnostic information to
/var/adm/messages based on the control variable IBM_trace. Refer to Setting the
IBM_trace level for static tracing on page 141 for instructions on how to set the
trace value.
IBM_trace values range from 0-13 and result in posted messages as shown in
Table 29. Postings are cumulative, so trace level 3 also posts items for levels 2, 1,
and 0. A trace value of 2 or 3 is suitable for most normal production environments,
with little or no degradation of throughput. IBM_trace values of 4 and higher
increasingly degrade performance and generally is used only when directed by
IBM support personnel.
Table 29. Solaris: tracing facility
Trace level

Items traced

Severe error conditions only. For installations with small /var file systems,
this setting can prevent filling the file system unexpectedly. However, this
setting might be at the cost of not recording messages that are related to
serious device or system environment errors.

Device sense data. Sense data can help in diagnosing the source of
unexpected error conditions.

Device opens and closes,


Decoded SCSI command, sense key, ASC and ASCQ for sense data.

413

Increasingly verbose tracing information. These tracing levels are useful only
to IBMtape developers.

Note: IBMtape earlier than Version 4.0.2.7 had only IBM_trace values 04. Message content
and selection differed significantly from current IBMtape versions.

By default, system error messages, including IBMtape trace messages, are placed
in /var/adm/messages. If your installation modified /etc/syslog.conf to redirect
system error messages, IBMtape tracing is handled as other kernel messages. Refer
to the syslog.conf man page and the comments in syslog.conf for information
about the system logging operation. Changes made to syslog.conf take effect after
the next system restart.
The following shows trace level 2 output, with system date and time stamps
removed. Device instance 390 is opened on the first line. The device minor number
12450 is decoded and shows that the SCSI medium changer (smc) special file was
opened.
Chapter 5. Solaris Tape and Medium Changer Device Driver

139

The second line decodes selected fields from the sense data that follows it. The
decoded information shows that sense data was generated during a Move Medium
command. Looking up the decoded Sense Key/ASC/ASCQ combination in the
3590 hardware reference, we find that the command failed because the move from
location was empty. The actual sense data follows the decoded fields.
Note: Solaris, rather than printing multiple 16-byte lines of hexadecimal zeros,
prints only the first such line, followed by a repeat count.
IBMtape(390) _open: 374 Inst 390, Minor 12450 (smc), Flags 0x5,
TL 2/0/0, 4.0.2.8
IBMtape(390) check_sense: cmd 0xa5(move_medium), key/asc/ascq 0x5/3b/e,
defer 0, retry 0, rc 22
IBMtape(390) 03590B11 SENSE DATA:
IBMtape(390) 70 0 5 0 0 0 0 58 0 0 0 0 3b e ff 2
IBMtape(390)
0 20 1 40 a 9 1 0 0 0 0 0 0 0 a5 0
IBMtape(390) 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
last message repeated 1 time
IBMtape(390) 0 0 0 0 0 0 0 0 36 33 39 20 20 20 20 0
IBMtape(390) 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
IBMtape(390) _close: Inst 390, Minor 12450 (smc), Flags 0x5, exit(0)

In the next example, the device open line shows that a tape drive (drv) device
special file was opened. The sense data for device instance 292 was generated
during a space operation. The Sense Key/ASC/ASCQ shows that a filemark was
encountered during the space.
IBMtape(292) _open: 554 Inst 292, Minor 9412 (drv), Flags 0x5,
TL 2/0/0, 4.0.2.8
IBMtape(292) check_sense: cmd 0x11(space), key/asc/ascq 0x0/0/1,
defer 0, retry 0, rc 5
IBMtape(292) 03570B02 SENSE DATA:
IBMtape(292) f0 0 80 0 0 0 1 48 0 0 0 0 0 1 ff a
IBMtape(292) c4 b1 0 20 0 5 1 91 0 34 0 0 0 0 11 0
IBMtape(292) 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 6
IBMtape(292) 6f 28 0 ad 73 32 0 0 0 0 0 0 0 0 0 0
IBMtape(292) 0 0 0 0 0 0 20 0 31 42 41 20 20 20 20 0
IBMtape(292) _close: Inst 292, Minor 9412 (drv), Flags 0x5, exit(0)

Finally, the sense data for device instance 230, a tape drive, occurred during a test
unit ready and indicates that no tape is loaded in the drive.
IBMtape(230) _open: 728 Inst 230, Minor 7366 (drv), Flags 0x5,
TL 2/0/0, 4.0.2.8
IBMtape(230) check_sense: cmd 0x0(test_unit_ready),
key/asc/ascq 0x2/3a/0, defer 0, retry 0, rc 5
IBMtape(230) 03570B02 SENSE DATA:
IBMtape(230) 70 0 2 0 0 0 0 48 0 0 0 0 3a 0 ff 2
IBMtape(230) c4 8 0 30 0 6 1 40 0 0 0 0 0 0 0 0
IBMtape(230) 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
last message repeated 1 time
IBMtape(230) 0 0 0 0 0 0 0 0 31 42 41 20 20 20 20 0
IBMtape(230) _close: Inst 230, Minor 7366 (drv), Flags 0x5, exit(0)

You can match an instance number with its corresponding device special file in
two steps.
1. Find the instance number in /etc/path_to_inst.
$ grep 292 /etc/path_to_inst
"/pci@6,4000/scsi@2,1/IBMtape@2,0" 292 "IBMtape"

2. List long the contents of /dev/rmt and search for the path name you found in
the previous step.

140

IBM Tape Device Drivers Installation and Users Guide

$ ls -l /dev/rmt | grep "/pci@6,4000/scsi@2,1/IBMtape@2,0"


lrwxrwxrwx
1 root
other
48 Aug 26 11:49 8st ->
../../devices/pci@6,4000/scsi@2,1/IBMtape@2,0:st
lrwxrwxrwx
1 root
other
49 Aug 26 11:49 8stb ->
../../devices/pci@6,4000/scsi@2,1/IBMtape@2,0:stb

In this example, /dev/rmt/8st, /dev/rmt/8stb, and so on, are symbolic links to the
device special files that are associated with device instance 292.

Dynamic tracing utility


A dynamic tracing utility named tapedtrc is introduced in the IBMtape.4.1.6.0 or
later driver. It is used to dynamically set, reset, start, stop, and query IBMtape
tracing at any time for debugging use. The program is in the/opt/IBMtape
directory, with the tracing level set to 0 by default.
Use the tapedtrc program from the command line as follows.
/opt/IBMtape/tapedtrc [option]
options:
[set]
- Set IBMtape trace level and/or start the tracing
[set] level
- Set trace to a particular trace level
[get]
- Query the current IBMtape trace level
[start]
- Start IBMtape tracing
[stop]
- Stop IBMtape tracing without the trace level reset
[clean]
- Stop the IBMtape tracing and reset IBMtape trace
level to 0
[help]
- IBM tapedtrc help menu

Setting the IBM_trace level for static tracing


The user can still enable or disable static IBMtape tracing and set the IBM trace
level in /etc/system or run the adb system command. The host is required to reboot
to enable or disable the tracing when the trace level is set in /etc/system. The
IBMtape driver must be loaded in the kernel. If the tracing is enabled or disabled
by using the adb command, the tracing starts or stops at the next device open.
The default value for IBM_trace is zero (0). You can define another IBM_trace value
by placing an entry in /etc/system so that IBM_trace is set at each restart. For
example, this entry in /etc/system sets IBM_trace to 2 at each restart.
set IBMtape:IBM_trace = 2

When IBM_trace is set in /etc/system, it affects tracing during driver loading,


initialization, and operation.
You can also set or modify the IBM_trace value manually in an adb session.
Because the driver must already be loaded and initialized before this method is
used, the trace value that is set is active only during driver operation.
In this sample session, ksh> is a shell prompt, and adb> is the adb session prompt.
Commands that you enter are in boldface. Explanatory comments follow number
signs (#) or exclamation and number sign pairs (!#). Text lines without a prefix are
adb session responses to commands.
#
# Start adb session and set session prompt.
ksh> adb -P "adb> " -k -w /dev/ksyms /dev/mem
physmem 7c5e
!#
Chapter 5. Solaris Tape and Medium Changer Device Driver

141

!# Set default for input values to base 10.


adb> a$d
radix=10 base ten
!#
!# Display current IBM_tape value as unsigned decimal integer.
adb> IBM_trace/u
IBM_trace:
IBM_trace:
0
!#
!# Set new IBM_trace value.
!# adb will confirm the old and new values.
adb> IBM_trace/w 2
IBM_trace:
0
=
2
!#
!# Quit session.
adb> $q
#
# Back to the shell.
ksh>

Running the diags_info script


Run the diags_info script in the /opt/IBMtape directory. This script detects the
problems on the configuration files, gathers important system HBAs, and
configuration information. The script must be run as root. If not run as root, the
information must be labeled as such, but the value of the information is degraded
when run as a non-root user.
To facilitate capture of data, the script places information in a file that is called
diags.out in the directory where the script is. Send the output file to the location
identified by your IBM service representative.

iostat command
IBMtape driver supports the iostat system command, which reports I/O statistics
for the supported tape drives in IBMtape.4.1.2.7 and later versions. Refer to man
(1M) iostat for the command usage.

Reservation conflict logging


When the device driver receives a reservation conflict during open or after the
device is opened, it logs a reservation conflict in the Solaris system log of
/var/adm/messages. Before the error is logged, the device driver issues a
Persistent Reserve In command to determine whether a SCSI Persistent
Reservation is active on the reserving host. It gets the reserving host initiator
WWPN (worldwide port name) and reserve key. If successful, the device driver
logs this information in the detail data. After the reserving host WWPN is logged,
subsequent reservation conflicts from the same reserving host WWPN and
reservation key are not logged. This action prevents multiple entries in the system
log until either the reserving host WWPN or reservation key is different from the
one initially logged. Or, the device driver reserved the device and then another
reservation conflict occurs.
The log examples
1. The information is logged when the drive is reserved with a Persistent
Reservation.
log_reserve: Reserving host key 46E48C49413E6EB1

142

IBM Tape Device Drivers Installation and Users Guide

WWPN 210000E08B118BB1

2. The information is logged when the drive is reserved with an SCSI-2 Reserve.
log_reserve: Reservation Conflict: read full status failure (rc 16)

3. The information is logged when the drive is reserved but the host reservation
information is not available.
log_reserve: Reservation Conflict: No reserving host information is available.

Chapter 5. Solaris Tape and Medium Changer Device Driver

143

144

IBM Tape Device Drivers Installation and Users Guide

Chapter 6. Windows Tape and Medium Changer device driver


This chapter describes the hardware requirements, software requirements, and
installation notes for the Microsoft Windows device drivers for IBM tape devices.

Purpose
The Windows tape and medium changer device driver is designed to take
advantage of the features that are provided by the IBM tape drives and medium
changer devices. The goal is to give applications access to the functions required
for basic tape operations (such as backup and restore) and medium changer
operations (such as mount and unmount the cartridges), and to the advanced
functions needed by full tape management systems. Whenever possible, the driver
is designed to take advantage of the device features transparent to the application

Data flow
The software that is described here covers the Windows device driver and the
interface between the application and the tape device.
Figure 13 illustrates a typical data flow process.

Windows Tape
and Medium
Changer Device
Driver

Host Bus
Adapter
Driver

Tape
Device
a2500268

Application
Program

Figure 13. Data flow for Windows device driver (IBMmag)

Product requirements
Hardware requirements
Refer to the Hardware requirements on page xvii for the latest hardware that is
supported by the IBM tape device driver.

Software requirements
For current software requirements, refer to the Software requirements on page
xvii.
Note: Limited support for customers who have Microsoft Windows Server 2003
extended support from Microsoft only.

Installation and configuration instructions


This section includes instructions for installing and configuring the Windows tape
and medium changer device driver on Windows Server 2003/Windows Server
2008/Windows Server 2012.

Copyright IBM Corp. 2007, 2014

145

The recommended procedure for installing a new version of the device driver is to
uninstall the previous version (see Uninstalling the device drivers on page 150).

Windows Server 2003, Windows Server 2008, and Windows


Server 2012 instructions
This section describes how to install, remove, and uninstall the Windows tape and
medium changer device drivers on Windows Server 2003, Windows Server 2008,
and Windows Server 2012.

Installation overview
The installation process consists of the following steps:
1. Verify that the hardware and software requirements are met.
2. Install the host bus adapters and drivers.
3. Shut down the system.
4. Connect the tape and medium changer devices to the host bus adapters.
5. Power on the tape and medium changer devices.
6. Reboot the system.
7. Log on as Administrator.
8. Install and configure the devices and device drivers with the installation
application.

Installation procedures
These procedures make the following assumptions:
v No other driver is installed that claims the tape and medium changer devices.
v If you are updating the device driver from a Microsoft certified version to an
uncertified version, you must first uninstall the certified driver. Refer to
Uninstalling the device drivers on page 150.
v The host bus adapter is installed, configured properly, and is running supported
microcode and driver levels.
v Drivers are identified by the following conventions, where nnnn refers to a
version of the driver. If there is more than one version, use the latest.
Windows Server 2003,
32-bitIBMTape.x86_nnnn.zip

Windows Server 2008,


32-bitIBMTape.x86_w08_nnnn.zip

Windows Server 2003 for extended 64-bit architectures (Intel EM64T and
AMD64),
IBMTape.x64_nnnn.zip

Windows Server 2008 for extended 64-bit architectures (Intel EM64T and
AMD64),
IBMTape.x64_w08_nnnn.zip

Windows Server 2012 for extended 64-bit architectures (Intel EM64T and
AMD64),
IBMTape.x64_w12_nnnn.zip

To install the device drivers, follow this procedure.


1. Log on as Administrator.

146

IBM Tape Device Drivers Installation and Users Guide

v install_nonexclusive.exe The driver permits open handles from the host to a


drive to exist at the same time, as is required by applications such as
Microsoft Removable Storage Manager (RSM) or Microsoft Data Protection
Manager (DPM).
Note: Review with your software application vendor the supported or required
driver installation and configuration.
The necessary .sys files for correct driver operation are installed, and all IBM
devices are associated with the driver. Refer to Figure 14.

a2500267

|
|

2. Download and install the appropriate driver. Refer toAppendix A, Accessing


documentation and software online, on page 321 for installation instructions.
3. Extract the driver package to a hard disk drive directory of your choice, other
than the root directory.
4. Ensure that the tape and medium changer devices are connected to your host
bus adapter and configured properly by locating the devices in Device
Manager.
5. For driver packages before v6.1.8.9, double-click install.exe in the driver
package.
For all subsequent levels, double-click either install_exclusive.exe or
install_nonexclusive.exe.
v install_exclusive.exe The driver issues automatic reserves on open. It also
prevents multiple open handles from the host to a drive from existing at the
same time, as is required by applications such as Tivoli Storage Manager.
This driver is also required for the failover feature to work as it uses
persistent reservation (by default).

Figure 14. Installation application in Windows Explorer

Note:
a. More installation features are available through the command-line
interface (CLI), which include

Chapter 6. Windows Tape and Medium Changer device driver

147

v Installing only the tape or medium changer device drivers (-t or


-c)
v Running in debug mode, which creates the file debug.txt in the
driver package directory (-d)
v Running in silent mode, which suppresses messages that require
user intervention, but only with Microsoft-certified IBM drivers
(-s)
v Disabling the Microsoft RSM service (-r), available in driver
packages v6.1.8.6 and later
v Disabling DPF from installation (-f), available in driver packages
v6.2.0.1 and later
v Enabling Persistent Reserve from installation if DPF is disabled
(-p), available in driver packages v6.2.0.6 and later.
v Disable Media Polling (-m).
v Disable Dynamic Runtime Attributes (-a).
To install the device drivers with any of these features, instead of
double-clicking the install executable file, open a command-line
window and cd to the driver package directory. For the usage
information, type install_exclusive.exe -h or
install_nonexclusive.exe -h at the prompt.
b. If the Windows "Found New Hardware" Wizard begins during
installation, cancel the wizard. The installation application completes
the necessary steps.
6. If you are installing a driver that is not certified by the Microsoft Windows
Hardware Quality Laboratories (WHQL), a warning screen opens. Refer to
Figure 15 on page 149. If you want to continue to install the driver, select
Continue Anyway.
Note: All drivers that are released by IBM went through a complete test to
ensure that they are stable and conform to specified requirements.

148

IBM Tape Device Drivers Installation and Users Guide

a250215

Figure 15. Windows logo testing screen

7. If you are installing a Windows Server 2008 or Windows Server 2012 driver
that is not certified by the Microsoft Windows Hardware Quality Laboratories
(WHQL), it likely has a VeriSign digital signature. During installation, you
might be presented with a prompt to install the software. Mark the "Always
trust software from IBM Corporation" check box and click Install. You see this
screen only the first time that you install the drivers, provided you click the
Always trust software box.
8. To verify that the tape and medium changer devices and drivers are installed
correctly, follow the instructions in Appendix B, Verifying correct attachment
of your devices, on page 325.

Device removal or disable procedure


If you must remove a device, or if you are altering the hardware configuration,
you must uninstall or disable the device first.
1. Right-click My Computer, select Manage to open the Computer Management
Console, and click Device Manager.
2. Right-click the device you want to uninstall and select Uninstall .... If you want
to disable the device without uninstalling it, you can select Disable.
3. You are prompted to confirm the uninstallation. Click OK.
4. In Device Manager, under System devices, right-click Changer Bus
Enumerator and select Uninstall.
5. In Device Manager, under System devices, right-click Tape Bus Enumerator
and select Uninstall.
Note: This removal procedure removes the device from the device tree, but it does
not uninstall the device driver files from your hard disk.

Chapter 6. Windows Tape and Medium Changer device driver

149

Uninstalling the device drivers


To uninstall the device drivers from the system, which includes deleting the system
files and deallocating other system resources, complete the following steps.
1. Complete the steps under Device removal or disable procedure on page 149
to remove the tape and medium changer devices.
2. Double-click uninst.exe in the driver package.
Note: This action removes all the files in the system directories that were
created during the installation of the device driver. It does not delete the
.zip file or the files that were extracted from the .zip file. If you want to
remove these files, you must delete them manually.
3. Reboot the system.

Configuring limitations
The driver limitation for the supported number of tape devices is 1024. Every
installed device uses a certain amount of resources. The user must also consider
other resources, such as physical memory and virtual space on the system before
you attempt to reach the limits. Also, be aware of Microsoft limitations. One
known article is http://support.microsoft.com/kb/310072 (ID: 310072). Be aware of
any Windows specific version limitations.

Persistent Naming Support on Windows Server 2003, Windows Server


2008, and Windows Server 2012
The Windows tape driver has an option for enabling device object names that
persist across reboots of the operating system. For example, if your tape drive has
the name \.\tape4801101 and the persistent naming option is used, then
\\.\tape4801101 is reserved for use by that device after an operating system
reboot.
Complete the following steps to enable this feature.
1. Add a DWORD value to the registry called PersistentNaming and assign it a
value 1 at HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ibmtp2kx
where x is replaced by 8 for Windows 2008 or by 12 for Windows 2012.
2. Reboot your system. Then, the system writes information to the registry to
associate the Worldwide Node Name from Inquiry p. 0x83 with the persistent
name used by the operating system.
v If the Worldwide Node Name is unavailable, or the drive is a virtual (that is,
emulated) drive, then the device serial number is used rather than the
Worldwide Node Name.
v If the PersistentNaming option is not specified in the registry, then your
devices might not be able to claim the same device name after reboot or
driver initialization.
You can find registry subkeys with persistent naming information at
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ibmtpbs2kx
where x is replaced by 8 for Windows 2008 or by 12 for Windows 2012.
Alternately, you can use the Windows Device Manager to examine the device
number to determine that persistent naming is enabled on your host. Persistent

150

IBM Tape Device Drivers Installation and Users Guide

names contain tape device numbers that are based at 4801101 (which is the decimal
equivalent of hexadecimal 0x49424D and ASCII "IBM").
If two physical paths exist to a drive and different Windows device names are
required (which happens, for example, when two different HBAs are connected to
the drive and Data Path failover is disabled), the first discovered path claims the
persistent device name. Any subsequent paths that connect to the same device
receive names according to the order in which they are discovered by the Windows
Device Manager.
Note: Persistent naming is not set by default. For disabling it, set the
PersistentNaming value to 0 and reboot the system.

Control Path failover support for tape libraries


To take advantage of Windows Control Path failover (CPF) support, the
appropriate feature code must be installed. Refer toAutomatic failover on page 1
for what feature code might be required for your machine type.

Configuring and unconfiguring Control Path failover support


Control Path failover is enabled automatically when the device driver is installed
by default (install_exclusive.exe). It can be disabled from installation with the -f
CLI option. Or, it can be disabled or reenabled for the entire set of attached
medium changers by modifying the registry.
1. Open the reg folder of the driver package.
2. Double-click DisableCPF.reg or EnableCPF.reg.
3. Reboot the system. This action is necessary for any registry modification to take
effect.

Querying primary and alternative path configuration


To check whether the control path failover is enabled in the device driver and
show the primary and alternative paths, use the tape diagnostic and utility tool.
Note: Show the primary and alternative path configuration for any device with
tape diagnostic and utility functions. Refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Checking disablement of Control Path failover setting


If you disabled the control path failover in the device drivers setting by
double-clicking the DisableCPF.reg file and rebooting your system, you can go
into the registry by issuing the Windows regedit command to confirm that CPF is
disabled. Look for a line like the following if your system is Windows Server 2012
or Windows Server 2008.
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ibmcg2kx]
"FailoverDisabled"=dword:00000001
where x is replaced by 8 for Windows 2008 or by 12 for Windows 2012.
This line indicates that CPF is disabled in the driver. This setting takes effect only
after your system is rebooted.
Chapter 6. Windows Tape and Medium Changer device driver

151

Data Path failover support for tape drives


To take advantage of Windows Data Path failover (DPF) support, the appropriate
feature code must be installed. Refer toAutomatic failover on page 1 for what
feature code might be required for your machine type.

Configuring and unconfiguring Data Path failover support


Data Path failover is enabled automatically when the device driver is installed by
default (install_exclusive.exe). It can be disabled from installation with the -f
CLI option. Or, it can be disabled or reenabled for the entire set of attached drives
or medium changers by modifying the registry.
1. Open the reg folder of the driver package.
2. Double-click DisableDPF.reg or EnableDPF.reg.
3. Reboot the system. This action is necessary for any registry modification to take
effect.
|
|

For latest LTO generation 3 code and later LTO generation tape drives, a license
key feature for the library hardware is required.

|
|
|
|
|
|
|
|
|

Note: For LTO generation 3 or lower, or for tape drives that require a data path
license key on the host side to enable DPF, the device driver looks for a file
that is called %system_root%:\IBM_DPF.txt for the key. %system_root% is the
drive letter where Windows is installed, typically C (for example,
C:\IBM_DPF.txt). The file contains the key on a single line, with no spaces
and no other text on the line. If multiple keys are required, place each key in
the file on its own line. The driver looks for this file at initialization. If the
file contains a valid DPF license key, the DPF feature is enabled and any
eligible devices have multi-path support.

Reserve Type if DPF is disabled


If DPF is disabled, SCSI-2 reserve is used by default to handle the reservation on
tape drives. If Persistent Reserve is wanted rather than SCSI-2 reserve,
ReserveTypePersistent.reg enables it (ReserveTypeRegular.reg disables it and then
SCSI-2 reserve is used). Or,-p CLI option installation (only if -f was used to
disable DPF) enables Persistent Reserve from installation.
Note: If DPF is not disabled, Persistent Reserve is used.

Querying primary and alternative path configuration


To check whether the data path failover is enabled in the device driver and show
the primary and alternative paths, you can use the tape diagnostic and utility tool.
Note: Show the primary and alternative path configuration for any device with the
tape diagnostic and utility functions. Refer to Chapter 8, IBM Tape
Diagnostic Tool (ITDT), on page 211.

Checking disablement of Data Path failover setting


If you disabled the data path failover in device drivers setting by double-clicking
the DisableDPF.reg file and rebooting your system, you can go into the registry by

152

IBM Tape Device Drivers Installation and Users Guide

issuing the Windows regedit command to confirm that DPF is disabled. Look for
a line like the following if your system isWindows Server 2012 or Windows Server
2008.
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ibmtp2kx]
"FailoverDisabled"=dword:00000001
where x is replaced by 8 for Windows 2008 or by 12 for Windows 2012.
This line indicates that DPF is disabled in the driver. This setting takes effect only
after your system is rebooted.
If you enabled Persistent Reserve on DPF disabled, look for a line like
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ibmtp2kx]
"ReserveType"=dword:00000001
where x is replaced by 8 for Windows 2008 or by 12 for Windows 2012.
If you use ReserveTypeRegular.reg, then the ReserveType value is set to 0.

System-managed encryption
Device driver configuration
System-managed encryption parameters on Windows are placed in the registry
under the key for the device driver. The parameters are populated in user-created
subkey that contains the serial number of the device. The registry keys
(sys_encryption_proxy and sys_encryption_write) are used to determine SME
enablement and invocation of the EKM proxy on write.
Note: Leading zeros in the serial number must be excluded. For example, if the
serial number of the encryption-capable tape drive were 0123456789, the
user creates the following registry key:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ibmtp2kx\123456789
where x is replaced by 8 for Windows 2008 or by 12 for Windows 2012.
Under this key, the user creates DWORD values that are called
sys_encryption_proxy or sys_encryption_write, and assigns them values that
correspond with the wanted behavior.
The device driver SME settings can be set for all drives at once by placing the
sys_encryption_proxy and sys_encryption_write registry options under the device
driver key, found at
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ibmtp2kx
where x is replaced by 8 for Windows 2008 or by 12 for Windows 2012.
When this option is chosen, the settings that are established for all drives are
overridden by the serial-number specific settings described the previous
paragraph.
If no options are specified in the registry, the driver uses the default values for the
parameters.
v The default value for sys_encryption_proxy is 1.
Chapter 6. Windows Tape and Medium Changer device driver

153

This value causes the device driver to handle encryption key requests, if the
drive is set up for system-managed encryption. This value does not need to be
changed. A value of 0 causes the device driver to ignore encryption key requests
for system-managed encryption drives, and is not desirable.
v The default value for sys_encryption_write is 2.
This value causes the device driver to leave the encryption write-from-BOP
settings alone. It does not turn on or turn off encryption writing, but instead
uses the settings that are already in the drive. If encryption is not set up
previously, then the drive writes unencrypted data. A value of 0 causes the
device driver to write unencrypted data. A value of 1 causes the device driver to
write encrypted data.
Changes to the registry require a reboot before the settings are able to be viewed.
However, during new installations of the driver, if the old driver is not uninstalled,
the old settings remain in place and no reboot is required.

Configuration file
The file %system_root%:\IBMEKM.conf is used to store the IP address of the
EKM server and other network-related parameters. The phrase %system_root%
refers to the drive letter where the Windows installation is located, typically C (for
example C:\IBMEKM.conf).
The format for the EKM server parameters is
Server<tab>Timeout<tab>IPAddress:Port

For example, if the Windows installation is installed at c:\, the EKM server is
named ekmtest, the wanted timeout is 10 seconds, and the IP address is 127.0.0.1
at port 4242. Then, create a line in C:\IBMEKM.conf as follows.
ekmtest<tab>10<tab>127.0.0.1:4242

Querying tape drive configuration settings


An ITDT command is used to query the encryption settings of a tape drive. In
ITDT-SE this procedure can be done by using either theStandard Edition - Scan
menu commands on page 226 section or the Tapeutil menu commands with
command [35] Query Encryption Status on page 251.
In ITDT-GE, it can be accomplished by using the Diagnostic/Maintenance tab (see
Encryption on page 296) or by Query Encryption Status on page 315 on the
Tapeutil tab.

Problem determination
There is a debug version of the device driver that can be used if you encounter
problems. The debug version of the driver issues DbgPrint messages at various
places during device driver execution. To capture these messages, you must start a
debugger or use a tool like Debug View from Sysinternals Suite, available from
http://technet.microsoft.com/sysinternals/.

154

IBM Tape Device Drivers Installation and Users Guide

Windows Server 2003 instructions


Installing the Debug version
To install and use the debug version of the device driver, complete the following
steps after the driver is initially installed.
1. Quiesce all activity on the tape and medium changer.
2. Exit all applications that are using the tape and medium changer devices.
3. Locate the \checked folder for the device driver level that you are running.
This folder is in the highest level directory of the driver package. It contains
checked versions of the tape and medium changer device drivers,
ibmtpxxyyy.sys, and ibmcgxxyyy.sys, where
v xx = ft for the filter driver, bs for the bus driver, or blank for the base driver,
and
v yyy = 2k3 for Windows Server 2003, 2k8 for Windows Server 2008, or 2k12
for Windows Server 2012. Refer to Figure 16

dd000002

Note: The last driver level to include support for Windows 2000 is V6.1.4.8.
The last driver level to include support for Windows 2003 is V6.2.1.7.
Subsequent levels include support for Windows Server 2012 and
Windows Server 2008 only, and therefore contains only 2k12 and 2k8
files.

Figure 16. Checked folder

4. Copy the checked version of ibmtpxxyyy.sys or ibmcgxxyyy.sys to


\winnt\system32\drivers, overwriting the version of the file already there.
5. Reboot the system.
6. Start the debugger to capture the DbgPrint messages.

Chapter 6. Windows Tape and Medium Changer device driver

155

7. Issue the commands to the driver. You can see debug statements that are
printed to the debugger window from IBMTpBus, IBMCgBus, tape, or mcd. For
example, you might see IBMTpBus: ENT: tag output. If you do not see
something similar, then something went wrong on the checked driver
installation or there is no driver activity.

Windows 2008 and Windows 2012 instructions


1. Quiesce all activity on the tape and medium changer.
2. Exit all applications that are using the tape and medium changer devices.
3. If the driver is installed, complete the Uninstall the devices procedure that is
described in a previous section.
4. Locate the \checked folder that is described at Step 3 of the Windows Server
2003 instructions. With the .sys files, you find .inf and .cat files because
Windows 2008 and Windows 2012 drivers are digitally signed.
5. Copy the files from the \checked folder to the highest level directory of the
driver package, overwriting the files in there. A previous backup of the files or
having a copy of the original driver package is recommended.
6. Complete the Installation procedure.
7. Follow Steps 6 and 7 from the Windows Server 2003.

Restoring the non-Debug version


To restore the non-debug version of the driver, complete the following steps.
1. Quiesce all activity on the tape and medium changer devices.
2. Exit all applications that are using the tape and medium changer devices.
3. In the highest level directory of the driver package, are non-debug versions of
the tape and medium changer device drivers, ibmtpxxyyy.sys and
ibmcgxxyyy.sys, where
v xx = ft for the filter driver, bs for the bus driver, or blank for the base driver,
and
v yyy = 2k for Windows 2000, or 2k3 for Windows Server 2003, or 2k8 for
Windows Server 2008. Refer to Figure 16 on page 155.
Note: The last driver level to include support for Windows 2000 is V6.1.4.8.
The last driver level to include support for Windows 2003 is V6.2.1.7.
Subsequent levels include support for Windows Server 2012 and
Windows Server 2008 only, and therefore contains only 2k12 and 2k8
files.
4. Copy the non-debug version of ibmtpxxyyy.sys or ibmcgxxyyy.sys to
\winnt\system32\drivers, overwriting the version of the file already there.
5. Reboot the system. When the driver starts and commands are issued to it, the
driver no longer produces debug output.
Note: For Windows Server 2008 and Windows Server 2012, it is necessary to
uninstall the devices and then install the non-debug version of the driver.

Reservation conflict logging


When the device driver receives a reservation conflict during open or after the
device is opened, it logs a reservation conflict in the Windows eventlog. Before the
error is logged, the device driver issues a Persistent Reserve In command. This
action determines whether a SCSI Persistent Reservation is active on the reserving

156

IBM Tape Device Drivers Installation and Users Guide

host to get the reserving host initiator WWPN (worldwide port name). If
successful, the device driver logs this information as follows.
Reserving host key: kkkkkkkk WWPN: xxxxxxxx

Where kkkkkkkk is the actual reserve key and xxxxxxxx is the reserving host initiator
WWPN.
After initially logging the reserving host WWPN, subsequent reservation conflicts
from the same reserving host WWPN are not logged. This action prevents multiple
entries in the error log until the reserving host WWPN is different from the one
initially logged. Or, the device driver reserved the device and then another
reservation conflict occurs.
|
|
|
|
|
|
|
|

Max retry busy


Complete the following steps to enable this feature.
1. Add a DWORD value to the registry called MAXBusyRetry and assign it a
value between 1 and 480 at HKEY_LOCAL_MACHINE\System\CurrentControlSet\
Services\ibmtp2kx where x is replaced by 8 for Windows 2008 or by 12 for
Windows 2012.
2. Reboot your system. Then, when a device gets the device busy error, the
command is retried up to MAXBusyRetry times.

Chapter 6. Windows Tape and Medium Changer device driver

157

158

IBM Tape Device Drivers Installation and Users Guide

Chapter 7. 3494 Enterprise Tape Library support


Purpose
The IBM 3494 Library device driver is a device driver providing attachment for the
IBM 3494 Enterprise Automated Tape Library and IBM Virtual Tape Server (VTS)
to a server. The programs that are described in this chapter support the 3494
Enterprise Automated Tape Library on the following operating systems:
v AIX on IBM POWER-based servers
v HP-UX
v Linux
v Solaris
v Microsoft Windows
Note: Check the versions of operating system that is supported by the IBM tape
driver on each platform.

MTLIB program
The mtlib program is a command-line interface used to control the 3494 Enterprise
tape library and is installed, by default, for execution by all users on the system.
This program provides the full interface (except for the MTIOCLEW library system
call) as specified in the IBM Tape Device Drivers: Programming Reference, GA32-0566.
Refer to MTEVENT program on page 169.
The mtlib program provides an interface to the physical tape drives and volumes
within a 3494 tape library and also to the virtual tape drives and volumes within
an attached IBM Virtual Tape Server (VTS).
To issue commands to the physical tape drives and volumes, specify a device
special file name, such as /dev/lmcp0 or the logical name of the library, such as
libmgrc7.
To issue commands to the virtual tape drives and volumes in an attached VTS
library, specify a device special file name or the logical name of the library with
the name of the logical VTS library that is appended with a slashv(/). For example,
to issue commands to the first attached VTS library, use /dev/lmcp0/vts1 or
libmgrc7/vts1. The attached VTS libraries are named logically vts1, vts2, and so on.
They correspond to the order in which they were configured in the tape library.
The -D flag, with the -E flags, can be used to display the attached VTS devices and
the number of the VTS library.

Syntax and examples


Figure 17 on page 160 shows the syntax for the mtlib program.

Copyright IBM Corp. 2007, 2014

159

Figure 17. Syntax diagram for mtlib program

The mtlib program has the following flags:


-f[filename]
Device special file for the drive, for example, /dev/rmt0 (AIX),
/dev/rmt/0st (Solaris), /dev/rmt/0m (HP), /dev/IBMtape0 (Linux),
\\.\tape0 (Windows).
-x[number]
Device number of the drive, for example, 518350.
-l[filename]
On AIX, library special file name, for example, /dev/lmcp0,
/dev/lmcp0/vts1. For non-AIX, the logical name of the library, for example,
libmgrc7.
-q[type]
Query the library information option:

160

Volume data.

Library data.

Statistical data.

Inventory data.

Category inventory data.

Device data.

Expanded volume data.

Inventory volume count data.

Reserved category list.

IBM Tape Device Drivers Installation and Users Guide

Category attribute list.

All mounted volumes.

-D

Return an array of devices that are configured in the specified library.

-E

Return (if used with the -D option) an array of expanded information for
all devices that are configured in the specified library, including the control
unit ID, device, and VTS library number.

-m

Mount option.

-d

Demount option.

-c[requestid]
Cancel the pending request option.
-n

No wait mode.

-i[requestid]
Query the request ID status option.
-C

Change the category of a volume.

-a

Audit the specified volume.

-k[flags]
Assign a category (with one of the following flags) to a device in the
library:
O

Enable the category order.

Clear the cartridge loader.

Generate the first mount.

Enable the auto mount.

Remove the device category assignment.

Note: Valid combinations are OG, OA, GA, and OGA.


-r

Reserve the category.

-R

Release the category.

-S

Set the category attribute.

Note: The categories must be reserved before this option is used.


-s[category]
Source or starting category.
-t[category]
Target category.
-V[volser]
Volume serial number.
-L[list]
Filename containing a list of the volume serial numbers. Each Volume
Serial must be entered as one per line in the file.
-N[name]
Category name to assign to the category (valid characters are uppercase
A-Z, 0-9, -, *, or blank).

Chapter 7. 3494 Enterprise Tape Library support

161

-h[hostid]
Host ID for the reserve or release category or the R/A option for the query
command.
-u

Include usage date in the expanded volume data (used with the-qE
option). The default is the ISO format with a period separator. The format
can be specified with the -F option.

-F[flags]
Format or separator for volume usage and date with the -u option:
I

ISO/Japan yyyy.mm.dd.

Europe dd.mm.yyyy.

US mm.dd.yyyy.

Period separator mm.dd.yyyy.

Dash separator mm-dd-yyyy.

Slash separator mm/dd/yyyy.

-v

Verbose.

-#[num_categories]
Number of categories to reserve.
-A

Query library addresses and status.

-?

Help text.

Note: Thev-l argument is required.


The report in Table 30 was produced by
mtlib
mtlib
mtlib
mtlib
mtlib
mtlib

-l
-l
-1
-1
-1
-l

/dev/lmcp0 -f /dev/rmt5 -qD (for AIX physical library)


/dev/lmcp0/vts1 -f /dev/rmt5 -qD (for AIX VTS library 1)
libmgrc7 -f /dev/rmt/5st -qD (for Solaris)
libmgrc7 -f /dev/rmt/5m -qD (for HP)
libmgrc7 -f /dev/IBMtape5 -qD (for Linux)
libmgrc7 -f \\.\tape0 -qD (for Windows)

Table 30. Device query


Device Data:
mounted volser............TAF500
mounted category..........FF00
device category...........0000
device state..............Device installed in Library.
Device available to Library.
Volume is loaded.
ACL is installed.
device class..............3590-B1A
extended device status....00

The report in Table 31 on page 163 was produced by


mtlib -l /dev/lmcp0 -qV -VCS2000 (for AIX physical library)
mtlib -l /dev/lmcp0/vts1 -qV -VCS2000 (for AIX VTS library 1)
mtlib -l libmgrc7 -qV -VCS2000 (for Solaris, HP, Linux, SGI, Tru64, and Windows)

162

IBM Tape Device Drivers Installation and Users Guide

Table 31. Volume query


Volume Data:
volume state.........00
logical volume.......No
volume class.........3590 1/2 inch cartridge tape
volume type..........HPCT 320m nominal length
volser...............CS2000
category.............FE00
subsystem affinity...04 03 05 06 01 02 00 00
00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00

The report in Table 32 was produced by


mtlib -l /dev/lmcp0 -qE -VCS2000 (for AIX physical library)
mtlib -l /dev/lmcp0/vts1 -qE -VCS2000 (for AIX VTS library 1)
mtlib -l libmgrc7 -qE -VCS2000 (for Solaris, HP, Linux, SGI, Tru64, and Windows)
Table 32. Expanded volume query
Expanded Volume Data:
volume status........00
logical volume.......No
volume class.........3590 1/2 inch cartridge tape
volume type..........HPCT 320m nominal length
volser...............CS2000
device category......FF00

The report in Table 33 was produced by


mtlib -l /dev/lmcp0 -qE -u -VCS2000 (for AIX physical library)
mtlib -1 libmgrc7 -qE -u -VCS2000 (for Solaris, HP, Linux, SGI, Tru64, and Windows)
Table 33. Expanded volume data with usage
Expanded Volume Data with Usage:
volume status............00
logical volume...........No
volume class.............3590 1/2 inch cartridge tape
volume type..............HPCT 320m nominal length
volser...................CS2000
device category..........FF00
last used (yyyy.mm.dd)...2001.08.26

The report in Table 34 was produced by


mtlib -l /dev/lmcp0 -qK -v (for AIX physical library)
mtlib -l /dev/lmcp0/vts1 -qK -v (for AIX VTS library 1)
mtlib -l libmgrc7 -qK -v (for Solaris, HP, Linux, SGI, Tru64, and Windows)
Table 34. Inventory count data
Performing Query Inventory Volume Count Data using /dev/lmcp0
Inventory Volume Count Data:
sequence number......12345
number of volumes....207
category.............0000

The report in Table 35 on page 164 was produced by


mtlib -l /dev/lmcp0 -D (for AIX physical library)
mtlib -l /dev/lmcp0/vts1 -D (for AIX VTS library 1)
mtlib -l libmgrc7 -D (for Solaris, HP, Linux, SGI, Tru64, and Windows)
Chapter 7. 3494 Enterprise Tape Library support

163

Refer also to the tapeutil subcommand mtdevice.


Table 35. Tape library device number
0, 00515820 003490C2A00
1, 00515821 003490C2A01

The report in Table 36 was produced by


mtlib -l /dev/lmcp0 -DE (for AIX physical library)
mtlib -l /dev/lmcp0/vts1 -DE (for AIX VTS library 1)
mtlib -1 libmgrc7 -DE (for Solaris, HP, Linux, SGI, Tru64, and Windows))

Refer also to the tapeutil subcommand mtdevice.


Table 36. Expanded tape library device list
Type
003590
003590
003590
003590
003590
003590
003490
003490
003490
003490
003490
003490
003490
003490

Mod Serial # Devnum


Cuid
B1A 13-10800 00108000
1
B1A 13-10800 00108001
1
B18 13-01817 00018170
2
B18 13-01817 00018171
2
B18 13-01817 00018172
2
B18 13-01817 00018175
2
C2A 13-01817 00FF0100
3
C2A 13-01817 00FF0101
3
C2A 13-01817 00FF0110
3
C2A 13-01817 00FF0111
3
C2A 13-01817 00FF0120
3
C2A 13-01817 00FF0121
3
C2A 13-01817 00FF0130
3
C2A 13-01817 00FF0131
3

Device
0
1
0
1
2
3
0
1
2
3
4
5
6
7

VTS Library
1
1
1
1
1
1
1
1
1
1
1
1

The report in Table 37 on page 165 was produced by


mtlib -l /dev/lmcp0 -qL (for AIX physical library)
mtlib -l /dev/lmcp0/vts1 -qL (for AIX VTS library 1)
mtlib -l libmgrc7 -qL (for Solaris, HP, Linux, SGI, Tru64, and Windows)

164

IBM Tape Device Drivers Installation and Users Guide

Table 37. Library data


Library Data:
Operational state..........Paused Operational State
Intervention Required
functional state...........00
input stations.............1
output stations............1
input/output status........All input stations empty
All output stations empty
machine type...............3494
sequence number............10491
number of cells............1056
available cells............1014
subsystems.................6
convenience capacity.......30
accessor config............01
accessor status............Accessor available
Gripper 1 available
Gripper 2 installed
Vision system operational
comp avail status..........Primary library manager installed.
Primary library manager available.
Secondary library manager installed.
Secondary library manager available.
Primary hard drive installed.
Primary hard drive available.
Secondary hard drive installed.
Secondary hard drive available.
Convenience input station installed.
Convenience input station available.
Convenience output station installed.
Convenience output station available.
library facilities.........00
bulk input capacity........0
bulk input empty cells.....0
bulk output capacity.......0
bulk output empty cells....0
avail 3490 cleaner cycles..0
avail 3590 cleaner cycles..91

The report in Table 38 on page 166was produced by


mtlib -l /dev/lmcp0 -qS (for AIX physical library)
mtlib -l /dev/lmcp0/vts1 -qS (for AIX VTS library 1)
mtlib -l libmgrc7 -qS (for Solaris, HP, Linux, SGI, Tru64, and Windows)

Chapter 7. 3494 Enterprise Tape Library support

165

Table 38. Statistical data


Statistical Data:
hour index...........10
machine type.........003494
model number.........L10
manufacturer.........IBM
plant................13
sequence number......000000010491
drives...............6
mounted drives.......1
max mounted drives...2
min mounted drives...1
avg mounted drives...1
max mounted time.....22
min mounted time.....16
avg mounted time.....19
pending mounts.......0
max pending mounts...2
min pending mounts...0
avg pending mounts...0
mounts/hour..........18
index mounts/hour....0
pre-mounts/hour......0
max mount time.......27
min mount time.......16
avg mount time.......19
pending demounts.....0
max pending demounts.2
min pending demounts.0
avg pending demounts.0
demounts/hour........16
index demounts/hour..0
post-demounts/hour...0
max demount time.....28
min demount time.....19
avg demount time.....24
pending ejects.......0
max pending ejects...0
min pending ejects...0
avg pending ejects...0
ejects/hour..........0
max eject time.......0
min eject time.......0
avg eject time.......0
pending audits.......0
max pending audits...0
min pending audits...0
avg pending audits...0
audits/hour..........0
max audit time.......0
min audit time.......0
avg audit time.......0
input stores/hour....0

The report in Table 39 on page 167 was produced by


mtlib -l /dev/lmcp0 -qI-v (for AIX physical library)
mtlib -l /dev/lmcp0/vts1 -qI -v (for AIX VTS library 1)
mtlib -l libmgrc7 -qI -v (for Solaris, HP, Linux, SGI, Tru64, and Windows)

166

IBM Tape Device Drivers Installation and Users Guide

Table 39. Inventory query


Performing Query Inventory Data using /dev/lmcp0
Inventory Data:
sequence number......10491
number of volumes....44
inventory records
record
1......category............012C
volser..............008273
volume state........00
logical volume......No
volume class........3590 1/2 inch cartridge tape
volume type.........HPCT 320m nominal length
record
2......category value......FF00
volser..............064435
volume state........00
logical volume......No
volume class........3590 1/2 inch cartridge tape
volume type.........HPCT 320m nominal length
record
3......category value......FF00
volser..............ALTML1
volume state........00
logical volume......No
volume class........3590 1/2 inch cartridge tape
volume type.........HPCT 320m nominal length

record 42......category............FF00
volser..............TST039
volume state........00
logical volume......No
volume class........3590 1/2 inch cartridge tape
volume type.........HPCT 320m nominal length
record 43......category............FF00
volser..............TST182
volume state........Volume present in Library,
but Inaccessible
record 44......category value......FF00
volser..............XYZ464
volume state........00
logical volume......No
volume class........3590 1/2 inch cartridge tape
volume type.........HPCT 320m nominal length
Note:

All available records are produced as output per request.


Fewer records are shown here for the sake of brevity.

The report in Table 40 on page 168 was produced by


mtlib -l /dev/lmcp0 -qC -sFF00 -v (for AIX physical library)
mtlib -l /dev/lmcp0/vts1 -qC -sFF00 -v (for AIX VTS library 1)
mtlib -l libmgrc7 -qC -sFF00 -v (for Solaris, HP, Linux, SGI, Tru64, and Windows)

Chapter 7. 3494 Enterprise Tape Library support

167

Table 40. Category inventory query


Performing Query Category Inventory Data using /dev/lmcp0
Inventory by Category Data:
sequence number......10491
number of volumes....30
category.............FF00
inventory records
record
1......category ...........FF00
volser..............CS2017
volume state........00
logical volume......No
volume class........3590 1/2 inch cartridge tape
volume type.........HPCT 320m nominal length
record
2......category ...........FF00
volser..............FVT896
volume state........00
logical volume......No
volume class........3590 1/2 inch cartridge tape
volume type.........HPCT 320m nominal length
record
3......category ...........FF00
volser..............IHG319
volume state........00
logical volume......No
volume class........3590 1/2 inch cartridge tape
volume type.........HPCT 320m nominal length

record 28......category ...........FF00


volser..............SLT500
volume state........00
logical volume......No
volume class........3590 1/2 inch cartridge tape
volume type.........HPCT 320m nominal length
record 29......category ...........FF00
volser..............TAF195
volume state........00
logical volume......No
volume class........3590 1/2 inch cartridge tape
volume type.........HPCT 320m nominal length
record 30......category ...........FF00
volser..............MOO801
volume state........00
logical volume......No
volume class........3590 1/2 inch cartridge tape
volume type.........HPCT 320m nominal length
Note:

All available records are produced as output per request.


Fewer records are shown here for the sake of brevity.

The report in Table 41 was produced by


mtlib -l /dev/lmcp0 -r -#2 -h roadster (for AIX physical library)
mtlib -l /dev/lmcp0/vts1 -r -#2 -h roadster (for AIX VTS library 1)
mtlib -l libmgrc7 -r -#2 -h roadster (for Solaris, HP, Linux, SGI, Tru64, and Windows)
Table 41. Reserve category command
Reserved Category List:
sequence number............10491
system token...............roadster
total number reserved......0002
category......0101
category......0102

168

IBM Tape Device Drivers Installation and Users Guide

The report in Table 42 was produced by


mmtlib -l /dev/lmcp0 -qR -h roadster (for AIX physical library)
mtlib -l /dev/lmcp0/vts1 -qR -h roadster (for AIX VTS library 1)
mtlib -l libmgrc7 -qR -h roadster (for Solaris, HP, Linux, SGI, Tru64, and Windows)
Table 42. Reserve category list
Reserved Category List:
sequence number............10491
system token...............roadster
total number reserved......0002
category......0101
category......0102

The report in Table 43 was produced by


mtlib
mtlib
mtlib
mtlib
mtlib
mtlib
mtlib
mtlib
mtlib

-l
-l
-l
-l
-l
-l
-l
-l
-l

/dev/lmcp0 -S -S101 -NSCRATCH (for AIX physical library)


/dev/lmcp0 -S -S102 -NWORKING (for AIX physical library)
/dev/lmcp0 -qA -h roadster (for AIX physical library)
/dev/lmcp0/vts1 -S -S101 -NSCRATCH (for AIX VTS library 1)
/dev/lmcp0/vts1 -S -S102 -NWORKING (for AIX VTS library 1)
/dev/lmcp0/vts1 -qA -h roadster (for AIX VTS library 1)
libmgrc7 -S -S101 -NSCRATCH (for Solaris, HP, Linux, SGI, Tru64, and Windows)
libmgrc7 -S -S102 -NWORKING (for Solaris, HP, Linux, SGI, Tru64, and Windows)
libmgrc7 -qA -h roadster (for Solaris, HP, Linux, SGI, Tru64, and Windows)

Table 43. Category attribute list


Category Attribute List:
sequence number............10491
system token...............roadster
category 0101 name: SCRATCH
category 0102 name: WORKING

The report in Table 44 was produced by


mtlib -l /dev/lmcp0 -A (for AIX physical library)
mtlib -l tire -A (for Solaris, HP, Linux, SGI, Tru64, and Windows)
Table 44. Library address information
Library Address Information:
library name...............tire
host identification........roadster
primary address............9.115.45.52
primary status.............Online
alternate address..........9.115.45.51
alternate status...........Offline

MTEVENT program
The mtevent program is a command-line interface to the MTIOCLEW command.
The mtevent program has the following flags:
-l[filename]
Library special file name or logical name of the library, for example,
/dev/lmcp0, /dev/lmcp0/vts1, or libmgrc7.
-t[timeout]
Number of seconds to wait for the event to occur.

Chapter 7. 3494 Enterprise Tape Library support

169

(0=no timeout).
Note:
1. The -l flag is required.
2. If the -t flag is not supplied, then no timeout is completed.

Library driver information


The lmcpd communicates to the tape library through symbolic names that are
defined in the /etc/ibmatl.conf file. One or more symbolic names can be configured
for each tape library online to the system. A symbolic name is used to run the
various library functions (such as mounting and unmounting volumes).

Software interface
The Cvobject module provides three subroutines for communicating with the IBM
3494 Enterprise tape library. These subroutines are open_ibmatl, close_ibmatl, and
ioctl_ibmatl. The open_ibmatl and close_ibmatl routines are used to open and
close communication with the library. Similarly, the open and close system calls
are used to open and close communication with a file. The ioctl_ibmatl subroutine
is used to send commands to the Library Manager on the 3494 tape library.
To send commands to the 3494 tape library, one symbolic name must be defined
for use on the library.

Library Manager event notification


In addition to completing library operations, the lmcpd is responsible for receiving
the various Library Manager notifications. The daemon monitors several types of
events. When the daemon receives an event, it checks a list of processes that are
waiting for an event to determine where to deliver it. If no process is waiting for
the event that arrived, then the event is discarded. The applications can use the
Library Event Wait call to request notification of all Library Manager events. Refer
to the IBM Tape Device Drivers: Programming Reference for information.

Synchronous and asynchronous operations


Two types of library operations are supported: synchronous and asynchronous.
The Library Manager responds to the synchronous operation immediately. These
operations are completed when the library responds to the request. An example of
a synchronous operation is the Library Query call. An asynchronous operation
(such as a mount operation) takes longer to complete. In an asynchronous
operation, the library returns an initial response when the command is accepted
for execution. When the command is completed, it returns a delayed response
message that indicates the status of the operation.

Operation Complete notification


When the Mount, Demount, Audit, or Set Volume category operation is sent to
the library, a message identifier is assigned to the operation. This identifier is
returned to lmcpd. When the operation is completed, an operation complete
notification is sent to the daemon. The daemon makes a determination (based on
the initial message identifier) as to which user process to notify that the operation

170

IBM Tape Device Drivers Installation and Users Guide

is complete. The Mount, Demount, Audit, or Set Volume category operations have
an option that allows the user process to wait or not wait for the operation
complete message. If the user process does not wait for the final complete, the
initial message identifier is returned to the caller. It can be used in subsequent
Library Query Message ID operations to solicit the status of the asynchronous
operation.

Unsolicited notification
There are situations when the Library Manager has a condition to report that is not
related to any I/O operation. In this case, an unsolicited notification is sent to the
device daemon. If a notification is received, then any process that is waiting with
the Library Event Wait call is notified. An example of an unsolicited notification is
the operational state change of the library (from the Auto mode to the Pause
mode). Refer to the IBM Tape Device Drivers: Programming Reference for a list of
unsolicited notifications that are received by the lmcpd.

Driver message queue


The driver maintains a message queue for any process that has an open LMCP file
descriptor. This queue, which has a depth of four entries, is implemented on a
first-in, first-out basis. The purpose of this message is to reduce the possibility of
missing a message when several messages occur in a short time. All queue entries
are discarded when the LMCP file descriptor is closed. When an application issues
the MTIOCLEW input/output control (ioctl) call, the driver returns the oldest
entry from the message queue and deletes it. If no entries are in the queue, then
the calling process is put to sleep until a message is received.

Volume categories
To facilitate the management of the tape volumes within the 3494 tape library, the
capability to associate the tape volumes into logical groupings is provided. Each
logical grouping is known as a category. For example, an installation can have one
or more scratch categories that are assigned by media type or class of user.
Another potential use is managing volumes for daily, weekly, and monthly
backups or volumes that are owned by a specific user. The lmcpd also allows a
user process to assign a particular category to a tape device in the library. This
process allows all the volumes that are associated with the category to be mounted
as determined by the flags of the command on the specified device.
A category is a four digit hexadecimal number in the X'0000'-X'FFFF' range. The
assigned categories are
X'0000'
NULL category (not usable or not assigned).
X'0001'-X'FEFF'
General programming use.
X'FFFF'
VOLSER specific.
The X'FF00'-X'FFFE' categories are reserved for hardware functions.
X'FF00'
Insert.

Chapter 7. 3494 Enterprise Tape Library support

171

X'FF01'-X'FF0F'
Reserved.
X'FF10'
Eject.
X'FF11'
Bulk eject.
X'FF12'-X'FFF8'
Reserved.
X'FFF9'
Service volume.
X'FFFA'
Manually ejected.
X'FFFB'
Purge volume.
X'FFFE'
Cleaner volume.
The following three categories are available for programming use.
Insert When a tape volume is received in the input station, the volume label is
read and assigned to this category. This category cannot be assigned by a
user process.
Eject

The volumes that are assigned to this category are moved from their cell
into the output station. After the volume is delivered, it is removed from
the inventory. The Library Set Volume Category command is the only
command that can change the category of a volume to the eject category.

Bulk eject
The volumes that are assigned to this category are moved from their
current cell to the bulk output area in the 3494 tape library. Refer to the
IBM Enterprise Automated Tape Library Operator Guide for information about
the bulk output area. The Library Set Volume Category command is the
only command that can change the category of a volume to the bulk eject
category.
The X'FFFF' category is available for general programming use. However, any
mount request to this category must apply to a specific volume that is assigned to
the category (and not based on the category alone).

IBM Virtual Tape Server subsystem attachment


The device driver supports the IBM Virtual Tape Server (VTS) subsystem
attachment with a 3494 Enterprise tape library on AIX, HP-UX, Windows, and
Oracle Solaris systems. An attached VTS subsystem provides virtual tape drives
that are accessible with the VTS SCSI attachment feature. Volumes within the VTS
subsystem are logical tape volumes. A logical tape volume appears to the host as a
normal physical tape volume. However, the VTS logical volumes are unique to the
VTS subsystem and are accessible only by virtual tape drives within the VTS
subsystem.
Access to a VTS subsystem is specified to the device driver as a logical library
within the attached tape library as vts1, vts2, and so on. For example, issuing a
Query Inventory command to the 3494 lib returns the physical volumes in the 3494

172

IBM Tape Device Drivers Installation and Users Guide

tape library, where 3494 lib is a library that is configured in the /etc/ibmat1.conf
file. Issuing a Query Inventory command to 3494 lib/vts1 returns the logical
volumes in the first VTS subsystem that is attached to the 3494 Enterprise tape
library.

3494 Library emulation


With 3494 Library emulation support, you can use applications that were written
for the 3494 API on host attached SCSI Medium Changer libraries. Specifically, you
can use migration to the 3584 Ultra Scalable library with 3592 drives.

Overview
Existing customer scripts that use the mtlib program and customer or ISV
applications require no or minor changes to use, depending on the 3494 functions
that are used. Customer and ISV applications must be recompiled only with the
new libibm.o object module to use the emulation support. The mtlib 3494 user
command line interface program has the same syntax and output on every
operating system. It also provides a common utility for SCSI Medium Changer
libraries. Current operating system device driver utilities vary by syntax or output.
They require a knowledge of SCSI Medium Changers to use, and require multiple
commands to run a single mtlib command.

3494 Emulation design


The 3494 Emulation support adds a libsmc extension to the current libibm.o object
module that applications compile with for existing 3494 support. The libsmc
extension contains the 3494 API Emulation support. The extension issues SCSI
Medium changer commands to the library by using the operating system SCSI
Medium Changer device driver.
Figure 18 and Figure 19 on page 174 show the 3494/SMC data flow between existing
applications and components and the new libsmc extension.
3494/ SMC Library Data Flow
Tape Device
Driver

Adapter
Device Driver

Library
Tape Drive

LMCPD

TCP/IP

3494
Library Manager

SMC Device
Driver

Adapter
Device Driver

SCSI Medium
Changer

LIBIBM.O
Object
Module

LIBSMC

a28t1001

Application

Figure 18. 3494/SMC library data flow

Chapter 7. 3494 Enterprise Tape Library support

173

libsmc_aix.c

AIX
Atape Device
Driver

libsmc_sun.c

Solaris
IBMtape Device
Driver

libsmc_hp.c

HPUX
atdd Device
Driver

libsmc_linux.c

Linux
IBMtape Device
Driver

libsmc_win.c

Windows
IBMtape Device
Driver

libsmc.c
3494 API
Emulation

SCSI Medium
Changer
Commands

a28t1002

LIBSMC and O/S Components

Figure 19. LIBSMC and OS components

3494 API Emulation and MTLIB program


Refer to the IBM Tape Device Drivers Installation and User's Guide and theIBM Tape
Device Drivers Programmer's Reference for the complete description of 3494 library
support and the mtlib program and syntax.

SMC library names


The library name on the open_ibmatl ("libname") or mtlib -l libname parameter
determines whether a 3494 library or an SMC library is being used. If the library
name is a logical operating system SMC library name, then the libsmc support is
used. Otherwise, the lmcpd support is used.
For example, SMC libraries on AIX are named smc0, smc1, and so on. To issue an
mtlib query library command on AIX to a 3584 library named smc0,
mtlib -l smc0 -qL

To issue an mtlib command on Linux to a 3584 library named IBMchanger0,


mtlib -l IBMchanger0 -qL

Volume categories
The 3494 library supports the grouping of one or more volumes into categories
that can be assigned by an application and operations that can specify a category
only rather than a specific volume. SCSI Medium Changers do not provide a
similar function. All volumes in an SMC library are category 0000, the NULL
category.

174

IBM Tape Device Drivers Installation and Users Guide

Because volume categories are not supported, the following API and mtlib
command options cannot be used. Applications and mtlib scripts that use these
functions might require changes.
v
v
v
v
v
v

Reserve category mtlib -r option


Release category mtlib -R option
Change a volume category mtlib -C option
Set category attribute mtlib -S option
Assign a category mtlib -k option
Mount from a category mtlib -m -s option

Asynchronous library operations


The 3494 library runs all mount, demount, audit, and eject operations
asynchronously and initially returns a request id to the host for the operation. The
request id can then be queried at any time to determine whether the operation is
still pending, completed, or is unknown. SMC libraries run these operations
synchronously and do not support a request id.
An application can select to wait for an asynchronous operation to complete by
setting the API wait_flg to one or by using mtlib without the -n option. The
operation is synchronous on both a 3494 and SMC library and no request id is
returned to the application. These applications and mtlib scripts do not require
any changes.
If an application selects to not wait for an asynchronous operation to complete by
setting the API wait_flg to zero or by using mtlib with the -n option, the
operation on an SMC library is still synchronous. A request id 0 is returned to the
application.
Most applications and scripts do not use the return request id to determine when
the operation completes and uses the no wait option for performance only. For
example, by using the no wait option on a demount operation so the application
can continue while the library is demounting the volume. These applications and
mtlib scripts do not require any changes but do take the same amount of time as
the wait option.
Applications that use the Query Message ID or mtlib -i option to determine when
the return request id operation completes might require changes. One change is
polling for a mount that is issued with the no wait option since any request id is
always unknown on an SMC library because the operation is already complete.

Performance considerations
The performance time of mtlib commands that are issued to a SCSI 3584 library
versus a 3494 vary and some performance times might be higher. The mtlib
commands, such as -qV and -qI that require reading all the slot information from
the library also vary in the amount of time it takes for the command to complete.
The fewer the number of slots that are in the library, the shorter time it takes to
complete the mtlib command and a larger number of slots in the library takes
longer.

Chapter 7. 3494 Enterprise Tape Library support

175

AIX
The software consists of an Automated Tape Library Device Driver (atldd), an
application daemon (lmcpd) that communicates with the 3494 Library Manager
(LM), and a utility program (mtlib), which provides a command-line interface to
the library. Either an ethernet, token-ring LAN, or an RS-232 serial connection can
be used for the physical connection between the host and the 3494 LM.
The daemon, which is known to AIX specifically as the IBM Library Manager
Control Point Daemon (lmcpd), communicates with tape libraries that are defined
in a configuration file. This file, ibmatl.conf, is placed in the /etc directory when
the software package is installed. Customization of this file is described in
Defining tape libraries to the daemon on page 178. A typical environment for the
AIX 3494 Enterprise Library Driver is an RS/6000 or System p (also known as
pSeries) server on a local area network (LAN) with SCSI- or fibre-attached tape
drives that provide backup and restore functions.

Data flow
The software described in this chapter covers the library device driver and the
interface between the application and the library device driver. For information,
refer to Figure 20.

Figure 20. Data flow for AIX 3494 Enterprise Tape Library Driver

176

IBM Tape Device Drivers Installation and Users Guide

Product requirements
The following hardware and software components are supported by IBM.

Hardware requirements
The library driver supports the following hardware.
v One of the following options, depending on the connection (RS-232 or LAN)
required for the Library Manager,
RS-232
- One standard 25 pin null modem D-shell RS-232 cable
- (maximum of 15.24 meters [50 feet])
LAN
- Token Ring or Ethernet Adapter support in an RS/6000 or pSeries
workstation that is attached to the Library Manager
- LAN cabling (as required)
v IBM TS1120 Tape Drive Model EO5
v IBM TS1130 Tape Drive Model E06
v 3592 Tape Drive Model J1A

Software requirements
The following software is required for the library driver:
v AIX 5L, Version 5.3, and later releases on IBM POWER-based servers.
v AIX Tape and Medium Changer Device Driver (Atape)
To obtain the most current service and documentation for this software, refer to
Appendix A, Accessing documentation and software online, on page 321

Installation instructions
Use the standard set of AIX methods to install and configure the LMCP devices.
You must have root authority to complete these operations.

Installation procedure
Refer to Appendix A, Accessing documentation and software online, on page 321
for information on obtaining the latest versions of the device driver and the latest
documentation.
Enter the following command to list the currently installed version of the 3494
Enterprise Library Driver:
lslpp -l atldd.driver

Connecting the IBM Enterprise tape library


If a tty connection is needed, use a standard 25 pin null modem D-shell RS-232
cable to connect the workstation to the 3494 Enterprise tape library. Place the cable
on the native serial port or on the 8 port or 16 port asynchronous adapter.
If a LAN connection is needed, connect the LAN cable from the Token Ring or
Ethernet adapter card in the workstation to the 3494 tape library.
Chapter 7. 3494 Enterprise Tape Library support

177

Note: The cable (RS-232 or LAN) must be in place before the software is installed
to ensure correct initialization of the driver.

Configuring the serial port


After the 3494 tape library is connected to the workstation, you must configure the
serial port to which it is connected. Use smit to configure the serial port. Enter the
following command:
smit tty

Select the following options.


1. TTY menu: Add a tty device.
2. Selection menu: Select the appropriate parent serial adapter.
3. Add TTY menu: Enter the port number.
4.
5.
6.
7.

Press F4 to generate a list of possible values.


Add TTY menu: Set baud rate to 9600.
Add TTY menu: eight data bits, one stop bit, no parity.
Add TTY menu: Set Enable program to Off.
Press F4 to generate a list of possible values.
Add TTY menu: Set Enable LOGIN to disable.
Use Tab to toggle the value.

8. Press Return to configure the tty device.


Repeat steps 1 - 8 for each tape library that is connected to the workstation.

Configuring the IBM 3490E or 3590 tape drive


To operate the 3494 Enterprise tape library successfully through the configured
LMCPs, you must configure all 3490E or 3590 tape drives in the 3494 tape library.
Refer to Configuring the Library Manager Control Point on page 179 for
instructions.

Defining tape libraries to the daemon


After the software is installed and the tape libraries are connected to the system,
the /etc/ibmatl.conf file must be edited to define the tape libraries to the lmcpd.
The format of the file is
Symbolic name

Connection type

Identifier

Alternate LAN Connection

Symbolic name is used to identify each library. The symbolic names must be unique
across all libraries that are defined in the /etc/ibmatl.conf file.
Connection type is used to define the type of connection to the library (either
RS-232 or TCP/IP). For RS-232 connections, this type is the device special file name
of the tty device (for example, /dev/tty0 or /dev/tty1). For TCP/IP connections, this
type is the IP address of the Library Manager. If the library has a dual LAN card
that is installed, the second IP address of the dual LAN card must be entered after
the first IP address.
Note: Ensure that duplicate IP addresses are not used in this file or unpredictable
results can occur.
Identifier is used to specify a name by which the Library Manager identifies the
host machine. This identifier has a maximum of 8 characters. The host name of the

178

IBM Tape Device Drivers Installation and Users Guide

workstation is usually the best name to use (although it is not necessary). This
parameter is used only to identify a particular host to the 3494 Enterprise Library
Manager.
Alternate LAN Connection is used to specify an alternate IP address for a 3494
High Availability LAN attached configuration. If the High Availability Library has
a dual LAN card that is installed, the second IP address of the dual LAN card
must be entered after the first alternate LAN connection IP address.
Note: For RS-232 attachments, the alternate LAN connection is not applicable.
Failover for RS-232 connections proceeds over the single serial line.
The following examples show how to define the library name.
libmgrc7

/dev/tty0

mercury

This stanza defines the libmgrc7 library that is connected by /dev/tty0 to the
workstation. The library uses the mercury identifier for the host.
libmgrc8

9.115.32.21

jupiter

This stanza defines the libmgrc8 library that is connected through TCP/IP to the
workstation. The address of the Library Manager on the 3494 Tape Library is
9.115.32.21. The library uses the jupiter identifier for the host.
libmgrc9

9.115.46.15

telos

9.115.46.17

This stanza defines the libmgrc9 High Availability library that is connected
through TCP/IP to the workstation. The IP addresses of the dual Library Managers
are 9.115.46.15 and 9.115.46.17.
libmgrc7

9.115.32.21

9.115.32.22

mercury

This stanza defines libmgrc7 with a dual LAN card connected through TCP/IP to
the workstation. The first address of the Library Manager on the 3494 Tape Library
is 9.115.32.21 and the second address is 9.115.32.22. The library uses the mercury
identifier for the host.
The following stanza defines the libmgrc7 High Availability library with dual LAN
cards connected through TCP/IP to the workstation. The IP addresses of the first
Library Manager are 9.115.32.21 and 9.115.32.22. The IP addresses of the second
Library Manager are 9.115.26.13 and 9.115.26.14. The library uses the mercury
identifier for the host.
libmgrc7

9.115.32.21

9.115.32.22

mercury

9.115.26.13

9.115.26.14

Configuring the Library Manager Control Point


After the driver is installed, a tape library is connected to the workstation, and the
serial port is configured, you can configure the instances of the LMCP. Complete
the following procedure to define and configure the LMCP:
1. Enter the following command:
smit

The system management interface tool (smit) main menu is displayed (refer to
Table 45 on page 180).

Chapter 7. 3494 Enterprise Tape Library support

179

Table 45. SMIT main menu


System Management
Move cursor to desired item and press Enter.
Software Installation and Maintenance
Devices
Physical & Logical Storage
Security & Users
Diskless Workstation Management & Installation
Communications Applications and Services
Spooler (Print Jobs)
Problem Determination
Performance & Resource Scheduling
System Environments
Processes & Subsystems
Applications
Using SMIT (information only)

F1=Help
F9=Shell

F2=Refresh
F10=Exit

F3=Cancel
Enter=Do

F8=Image

2. Select Devices (item 2) from the smit main menu.


Use the up () arrow and down () arrow keys to move the cursor to the
wanted item on the menu.
Press Enter or click Do if you are processing smit in a windowed
environment.
3. Select Tape Drive from the Devices menu (refer to Table 46).
Table 46. SMIT devices menu
Devices
Move cursor to desired item and press Enter.
Configure Devices Added after IPL
Printer/Plotter
TTY
Asynchronous Adapters
PTY
Console
Fixed Disk
CD ROM Drive
Optical Disk Drive
Diskette Drive
Tape Drive

The Tape Drive menu is displayed (refer to Table 47 on page 181).

180

IBM Tape Device Drivers Installation and Users Guide

Table 47. SMIT tape drive menu


Tape Drive
Move cursor to desired item and press Enter.
List All Defined Tape Drives
List All Supported Tape Drives
Add a Tape Drive
Change / Show Characteristics of a Tape Drive
Remove a Tape Drive
Configure a Defined Tape Drive
Generate Error Report
Trace a Tape Drive

4. Select Add a Tape Drive from the Tape Drive menu (Table 47). The Tape
Drive Type menu is displayed (refer to Table 48).
5. Select the Library Manager control point from the Tape Drive Type menu
(refer to Table 48).
Table 48. SMIT tape drive type menu
Tape Drive Type
Move cursor to desired item and press Enter.
8mm
9trk
150mb
ost
drive
drive
drive
atl

scsi
scsi
scsi
scsi
3420
3480
3490
library

2.3 GB 8 mm Tape Drive


1/2 Inch 9 Track Tape Drive
150 MB 1/4 Inch Tape Drive
Other SCSI Tape Drive
3420 Tape Drive
3480 Tape Drive
3490 Tape Drive
LAN/TTY Library Manager Control Point

The Add an LMCP Logical Device menu is displayed (refer to Table 49).
The Logical Name field for the Library Manager control point is optional. If
the field remains blank, a unique name is assigned automatically. The
assigned name is lmcpn, where: n is a number that indicates the LMCP entry
and starts with zero for the first LMCP defined.
The Library Name field must be one of the library names that are defined in
the /etc/ibmatl.conf file. Refer to Defining tape libraries to the daemon on
page 178 for a description of this file.
The Command Timeout in Minutes field is optional and is used to specify
the maximum amount of time an application waits for commands to complete,
including mount and demount commands. The default is to wait forever until
the command completes.
Table 49. Add an LMCP Logical Device menu
Add an LMCP Logical Device
Type or select values in entry fields.
Press Enter AFTER making all desired changes.

Logical Name of LMCP (optional)


Library Name (F4 to list library names)
Command Timeout in Minutes

[Entry Fields]
[]
[libmgrc7]
[]

Chapter 7. 3494 Enterprise Tape Library support

181

6. The COMMAND STATUS window opens with the Command: OK status.


The logical name of the Library Manager control point is displayed as
Defined (refer to Table 50).
Table 50. LMCP COMMAND STATUS window
COMMAND STATUS
Command: OK

stdout: yes

stderr: no

Before command completion, additional instructions may appear below.


lmcp0

Defined

7. Repeat steps 4 - 6 to define any additional Library Manager control points.


8. Return to the smit Tape Drive menu (refer to Table 47 on page 181).
9. Select Configure a Defined Tape Drive from the smit Tape Drive menu. A
list of LMCP devices is displayed (refer to Table 51).
Table 51. Configure an LMCP selection list
Tape Drive
Move cursor to desired item and press Enter.
rmt0
rmt1
lmcp0

Available 00-00-0S-50 2.3 GB 8 mm Tape Drive


Defined
00-01-01-20 IBM SSD 3490E Tape Drive
Defined
LAN/TTY Library Manager Control Point

F1=Help
F8=Image

F2=Refresh
F10=Exit

F3=Cancel
Enter=Do

10. Select a defined Library Manager control point to configure from the LMCP
Selection list.
The COMMAND STATUS window opens with the Command: OK status,
and the Library Manager control point is shown as Available (refer to
Table 52).
Table 52. Configure a Defined LMCP COMMAND STATUS window
COMMAND STATUS
Command: OK

stdout: yes

stderr: no

Before command completion, additional instructions may appear below.


lmcp0

Available

11. Cancel the COMMAND STATUS window by pressing F3. The LMCP
Selection window opens again.
12. Continue selecting the Library Manager control points for configuration until
all the devices are configured.
13. Exit from the smit menu.
You completed the configuration of Library Manager control points to the
system.

182

IBM Tape Device Drivers Installation and Users Guide

Loading the daemon


The lmcpd is loaded during the system initialization. During the initial installation
of the driver, you must load the daemon manually by using the following
command,
cfgmgr

You can access the 3494 Enterprise Tape Library after the command is completed.
To verify that the daemon is loaded correctly, enter the following command,
ps -efa | grep lmcpd

You can see multiple instances of the daemon running (which is typical), but only
one instance has a parent process ID of 1.

Deconfiguring the Library Manager Control Point


In the following examples, replace the letter n with the appropriate number for the
chosen device.
Deconfigure the LMCP device by using one of the following procedures:
1. The first method deconfigures the device but leaves the device that is defined
in the configuration database. It is similar to taking the device offline.
Enter the following command to deconfigure the /dev/lmcpn device but leave it
defined in the device database.
rmdev -l lmcpn

2. The second method takes the device offline and removes the device definition
from the device database.
Enter the following command,
rmdev -l lmcpn -d

The device driver modules are not unloaded from the kernel until the last tape
device is deconfigured.

Uninstall procedure
All devices that use the atldd driver must be closed and not in use when atldd is
uninstalled or the uninstall fails.
You can uninstall the atldd by using the smit command menu to uninstall software
and selecting atldd.driver or use the following installp command,
installp -u atldd.driver

Special files
After the driver is installed and a Library Manager control point is configured and
made available for use, access is provided through the special files. These special
files are in the /dev directory. Each instance of an LMCP has exactly one special file
(for example, /dev/lmcp0) associated with it.

3494 Enterprise tape library attachment test


The following procedure tests the attachment of a 3494 Enterprise Tape Library to
an AIX system. The procedure assumes that your device is defined as /dev/lmcp0.
Chapter 7. 3494 Enterprise Tape Library support

183

1. Open an AIX window.


2. Enter mtlib -l /dev/lmcp0-qI
3. Enter mtlib -l /dev/lmcp0 -qL

Problem determination
A set of tools is provided with the device driver to determine whether it is
functioning correctly. The standard AIX interface is provided for problem
determination.

Error logging
The driver provides logging to the system error log for various errors. View the
error log by using the smit or the errpt command. The error templates follow the
same form as the default AIX error log entries.

AIX device driver trace facility


The AIX trace facility is supported for the device driver. The trace event is
identified with a hookword. The hookword that is used by the device driver is 426.
The trace can be initiated at any time before an operation on a tape device.
Enter the following command to start the trace.
trace -a -j 426

This command starts the trace in the background and collects only the trace events
with the 426 hookword.
Enter the following command to stop the trace.
trcstop

This command stops the trace after the tape operations are completed.
Enter the following command to view the trace.
trcrpt > lmcp.trace.out

This command formats the trace output into a readable form and places it in a file
for viewing. The /etc/lmcp.trcfmt file is installed into /etc during installation. It
provides the formatting statements that are needed by trcrpt.

Daemon trace facility


The following trace facility is available for the lmcp daemon and device driver:
trcatl -[ald]

Arguments:
-a
-l <name>
-d

(trace all libraries defined in /etc/ibmatl.conf)


(name of library)
(delete all log files; requires root authority)

Examples:
trcatl -a >/tmp/trace-out
trcatl -l libmgrc7

Note: The -a argument takes precedence over the -l argument.

184

IBM Tape Device Drivers Installation and Users Guide

HP-UX
The software consists of a daemon that communicates directly with the Library
Manager of the 3494 Enterprise tape library through Ethernet or Token Ring LAN,
a utility program that provides a command line interface to the daemon, and a C
object module that can be linked with user applications to provide a
communication interface with the daemon.
Note: In the HP-UX operating system, this daemon is a program that runs
unattended in the background to run a standard service. Some daemons are
triggered automatically to complete their task, others operate periodically.
This software is known as a driver throughout this document because it provides
the software and interface necessary to drive the 3494 tape library. However, the
product does not consist of a device driver in the true sense of the term. That is, it is
not an extension of the operating system kernel, such as a SCSI tape device driver.
A typical environment for the HP-UX Automated Tape Library Driver is an HP
workstation that acts as a data server on a network with SCSI tape devices that
provides backup or restore and data server functions.
The Library Manager control point daemon (lmcpd) is provided in the package.
The lmcpd is a process that is always running on the system. It provides direct
communication with the 3494 Enterprise Library Manager. An application links
with the supplied C object module by using the interface that is described in the
IBM Tape Device Drivers: Programming Reference. The subroutines in this module
communicate with the lmcpd to run the various library operations by using
standard UNIX namespace sockets.
The lmcpd communicates with the Library Manager through TCP/IP. The
/etc/ibmatl.conf configuration file is used to define the attachment for each library.
Refer to Defining the library device to LMCPD on page 189 for information.

Data flow
The software described in this chapter covers the library driver. The interface
between the application and the library driver is described in the IBM Tape Device
Drivers: Programming Reference. Figure 21 on page 186 illustrates the data flow.

Chapter 7. 3494 Enterprise Tape Library support

185

Tape Device
Driver

Adapter
Device Driver

Physical
Tape Drive

LMCPD

TCP/IP

Library
Manager

Application

a250106

C
Object
Module

Figure 21. Data flow for HP-UX 3494 Enterprise tape library driver

Product requirements
The following software and hardware are required to use this product.

Hardware requirements
The following hardware is required for the library driver.
v 3494 Enterprise Tape Library with 3590 and 3592 drives.
v IBM Virtualization Engine TS7510 and TS7520
v Enterprise Model B10, B18, and B20 Virtual Tape Server (direct attached only)
v One of the following options, depending on which LAN connection is used for
the Enterprise Library Manager
Token-Ring Attach - Enterprise FC 5219 (Token-Ring Adapter)
- Token-Ring adapter card for HP workstation
- Token-Ring cables (as required)
Ethernet Attach - Enterprise FC 5220 (Ethernet Adapter)
- Ethernet port or adapter for HP workstation
- Ethernet cables (as required)

Software requirements
The following software is required for the library driver.
v HP-UX operating system

186

IBM Tape Device Drivers Installation and Users Guide

Note: For information, refer to Chapter 3, HP-UX Tape and Medium Changer
device driver, on page 47.
v IBM Tape and Medium Changer Device Driver for HP-UX
To obtain the most current service and documentation for this software, refer to
Appendix A, Accessing documentation and software online, on page 321.

Software compatibility
The following optional software is supported by the library driver:
IBM Tivoli Distributed Storage Manager for HP-UX

Installation instructions
This chapter describes how to install, configure, and uninstall the HP-UX
Automated Tape Library Support for the 3494 Enterprise tape library. The IBM tape
library driver for HP-UX is installed by using the standard swinstall process. The
IBM tape library driver for HP-UX is the lmcpd package.

Installation overview
LAN support must exist on the machine before the IBM tape library driver for
HP-UX is installed. Install and configure the LAN support before you proceed with
the installation of the lmcpd package. For information, refer to the HP-UX
documentation appropriate for the LAN support that you are using.
1. Copy the software from the distribution medium to the depot.
2. Check the readme file and verify that your system is configured appropriately
for installing the lmcpd software.
3. Install and configure the software.
You must have root authority to run this installation procedure.
The distribution diskette contains a swinstall process that includes the lmcpd
daemon with other associated files and utilities.

Command sequence information


Take note of the following facts about the command sequences described in this
section:
v In some of the examples, file names that are given on the command line must be
referenced with an absolute path. Using 'pwd'/filename to reference a file
instead of filename ensures the absolute path.
v All the SD commands (for example, swinstall, swcopy) can be run initially with
the '-p' flag to preview the command. After the preview output is observed,
you can reissue the command without the '-p' flag to run the actual operation.
v The SD commands are moderately complex scripts that usually proceed in
several steps. The steps are typically Selection, Analysis, and Execution. Each
step might produce useful information and error messages. It is a good idea to
observe carefully the results of the installation process as it occurs.
If you run into unexpected results during the installation, check the associated log
file.

Chapter 7. 3494 Enterprise Tape Library support

187

Note: If an earlier version of the product is installed on the machine, run the
uninstallation procedure before you enter the following commands. Refer to
Uninstallation procedure on page 190 for information.
The following files are installed on the system:
v /etc/lmcpd (Library Manager control point daemon)
v /etc/ibmatl.conf (configuration file)
v /usr/lib/libibm.o (32-bit application interface object module)
v /usr/lib/libibm64.o (64-bit application interface object module)
v /usr/lib/libibmz.0 (32-bit application interface object module with +z option)
v /usr/lib/libibm64z.0 (64-bit application interface object module with +Z option)
v /usr/lib/libibm_ia64.0 (64-bit application interface object module with +z option
for Itanium system)
v /usr/lib/libibm_ia64z.0 (64-bit application interface object module with +Z
option for Itanium system)
v /usr/include/sys/mtlibio.h (application interface header file)
v /usr/bin/mtlib (tape library driver utility program)
v
v
v
v
v

/usr/bin/intlib64 (64-bit tape library driver utility program)


/usr/bin/mtevent (tape library driver utility program)
/usr/bin/trcatl (tape library driver diagnostic program)
/opt/lmcpd (subdirectory)
/opt/lmcpd/ibmatl.conf (backup configuration file)

Note: If you are updating the lmcpd package, the existing /etc/ibmatl.conf file is
preserved. It is not overwritten. A copy of ibmatl.conf is also installed in the
/opt/lmcpd directory.

Installing the product manually


Installing the product manually requires two steps, detailed in the following
sections.
1. Copying the software to the Software Depot
2. Installing the product

Copying the software to the Software Depot


If you do not copy the lmcpd software into a depot, you cannot easily uninstall the
software.
Copy the appropriate driver to the Software Depot. For example,
# swcopy -p -s /driver_location/lmcpd.hpux.x.x.x.x lmcpd (preview option)
# swcopy -s /driver_location/lmcpd.hpux.x.x.x.x lmcpd

Use swlist to verify that the lmcpd software is in the depot.


# swlist -d lmcpd

Installing the product


When the software is in the depot, the lmcpd software can be installed to the root
file system by using the HP-UX swinstall command.

188

IBM Tape Device Drivers Installation and Users Guide

The following commands install lmcpd from the depot to the default root file
system.
# swinstall -p lmcpd (preview option)
# swinstall lmcpd

Use swlist to list the software that is installed on the default root file system as
follows,
# swlist lmcpd

Verify correct installation to the default root file system with the swverify
command,
# swverify lmcpd

Connecting the IBM 3494 Enterprise automated tape library


You can use a LAN connection (either Ethernet or Token Ring) through a TCP/IP
connection. The connection must be in place before the software is installed to
ensure correct initialization of the daemon. For each 3494 Enterprise tape library
that is connected through TCP/IP, ensure that your machine has access to the
Library Manager on the 3494 Enterprise tape library. Use the ping utility to verify
that you have network connectivity to the Library Manager. Consult your network
administrator if you need help with this task.

Defining the library device to LMCPD


After the software is installed and all tape libraries are connected to the system,
the /etc/ibmatl.conf file must be edited to define the library devices to the lmcp
daemon. The format of the file is
Symbolic name

Connection type

Identifier

Alternate LAN Connection

Symbolic name is used to identify each tape library. The symbolic names must be
unique across all libraries that are defined in the ibmatl.conf file.
Connection type defines the type of connection to the library. For TCP/IP
connections, this type is the IP address of the 3494 Enterprise Library Manager. If
the Library has a dual LAN card that is installed, the second IP address of the dual
LAN card must be entered after the first IP address.
Identifier is used to specify a name by which the Library Manager identifies the
host machine. This identifier has a maximum length of 8 characters. The symbolic
network name of the host is usually the best name to use, although any name is
acceptable. This parameter is used only to identify a particular host to the 3494
Library Manager.
Alternate LAN Connection is used to specify an alternate IP address for an
Enterprise High Availability LAN configuration. If the High Availability Library
has a dual LAN card that is installed, the second IP address of the dual LAN card
must be entered after the first alternate LAN connection IP address.
The following examples show how to define the library name.
3494a

9.115.32.21

jupiter

This stanza defines the 3494a library that is connected to the host. The address of
the Enterprise Library Manager is 9.115.32.21. The tape library uses jupiter as the
identifier for the host.
Chapter 7. 3494 Enterprise Tape Library support

189

libmgrc9

9.115.46.15

telos

9.115.46.17

This stanza defines the libmgrc9 High Availability library that is connected
through TCP/IP to the workstation. The IP addresses of the dual Library Managers
are 9.115.46.15 and 9.115.46.17.
libmgrc7

9.115.32.21

9.115.32.22

mercury

This stanza defines libmgrc7 with a dual LAN card connected through TCP/IP to
the workstation. The first address of the Library Manager on the 3494 Tape Library
is 9.115.32.21 and the second address is 9.115.32.22. The library uses the mercury
identifier for the host.
The following stanza defines the libmgrc7 High Availability library with dual LAN
cards connected through TCP/IP to the workstation. The IP addresses of the first
Library Manager are 9.115.32.21 and 9.115.32.22. The IP addresses of the second
Library Manager are 9.115.26.13 and 9.115.26.14. The library uses the mercury
identifier for the host.
libmgrc7

9.115.32.21

9.115.32.22

mercury

9.115.26.13

9.115.26.14

Adding or deleting entries in the library device


You can add or delete entries in /etc/ibmatl.conf at any time. However, changes do
not take effect until the daemon is started again. Use the UNIX kill command
(kill -kill <pid>) to stop the lmcpd process, then enter the /etc/lmcpd command
to start the daemon again.
Ensure that the library activity on all of the libraries is completed before lmcpd is
started again.

Uninstallation procedure
Do not try to uninstall the lmcpd software by deleting the files that make up the
lmcpd file set. It is best to use the swremove command.
Halt all library activity before the uninstallation procedure is started. Kill the
lmcpd daemon if it is running.
To remove the lmcpd software from the root file system, enter
# swremove -p lmcpd
# swremove lmcpd

Other administrative tasks


To determine what versions of the lmcpd software are currently installed on the
default root file system,
# swlist -a state lmcpd

To determine what versions of the lmcpd software are stored in the default depot,
# swlist -d state lmcpd

To view the set of files that are installed with the lmcpd software,
# swlist -l file lmcpd

To remove the lmcpd software from the depot,


# swremove -d lmcpd

190

IBM Tape Device Drivers Installation and Users Guide

If more than one level of lmcpd exists in the depot, explicitly specify the level to
remove it. For example,
# swremove -d lmcpd,r=4.1.8.0

3494 Enterprise tape library attachment test


The following procedure tests the attachment of a 3494 Enterprise tape library to
an HP-UX system. The procedure assumes that your device is defined in
/etc/ibmatl.conf as L3494.
1. Enter a shell prompt.
2. Enter mtlib -l L3494 -qI.
3. Enter mtlib -l L3494 -qL.

Problem determination
A set of tools is provided with the software to determine whether the lmcpd is
functioning correctly.

Error logging
The lmcpd uses the syslog facility to log the errors. Errors are logged according to
the /etc/syslog.conf file. The lmcpd uses the daemon facility for logging errors.
Only errors are logged with this facility. For information about using syslog, refer
to your system administration manuals.

Daemon trace facility


The following trace facility is available for the lmcpd daemon.
trcatl -[ald]

Arguments:
-a
-l <name>
-d

(trace all libraries defined in /etc/ibmatl.conf)


(name of library)
(delete all log files; requires root authority)

Examples:
trcatl -a >/tmp/trace-out
trcatl -l libmgrc7

Note: The -a argument takes precedence over the -l argument.

Linux
The software consists of a daemon that communicates directly with the Library
Manager of the 3494 Enterprise Tape Library through Ethernet or Token Ring LAN.
It also provides a utility program that provides a command line interface to the
daemon, and a C object module that can be linked with user applications to
provide a communication interface with the daemon.
Note: In the Linux operating system, this program runs unattended, in the
background, to complete a standard service. Some daemons are triggered
automatically to complete their task; others operate periodically.

Chapter 7. 3494 Enterprise Tape Library support

191

This software is known as a driver throughout this document because it provides


the software and interface necessary to drive the 3494 tape library. However, the
product does not include a device driver in the true sense of the term. That is, it is
not an extension of the operating system kernel, such as a tape device driver.
A typical environment for the Linux Automated Tape Library Driver is a Linux
workstation that acts as a data server on a network. Tape devices provide backup
or restore and data server functions.
The Library Manager control point daemon (lmcpd) is provided in the package.
The lmcpd is a process that is always running on the system. It provides direct
communication with the Library Manager. An application links with the supplied
C object module by using the interface that is described in the IBM Tape Device
Drivers: Programming Reference. The subroutines in this module communicate with
the lmcpd to run the various library operations with standard UNIX namespace
sockets.
The lmcpd communicates with the Library Manager through TCP/IP. The
/etc/ibmatl.conf configuration file is used to define the attachment for each library.
Refer to Defining the library device to the lmcpd on page 194 for information.

Data flow
The software described in this chapter covers the library driver. The interface
between the application and the library driver is described in the IBM Tape Device
Drivers: Programming Reference.Figure 22 illustrates the data flow.

Tape Device
Driver

Adapter
Device Driver

Physical
Tape Drive

LMCPD

TCP/IP

Library
Manager

Application

a250106

C
Object
Module

Figure 22. Data flow for Linux 3494 Enterprise tape library driver

Product requirements
The following hardware and software components are required and supported by
IBM.

192

IBM Tape Device Drivers Installation and Users Guide

Hardware requirements
The following hardware is required for the library driver:
v IBM 3494 Enterprise Tape Library with IBM 3590 and 3592 drives with the Fibre
Channel Attachment
v IBM TS1120 Tape Drive
v IBM Virtualization Engine TS7510
v One of the following options, depending on which LAN connection is used for
the Enterprise Library Manager:
Token-Ring Attach:
- Enterprise FC 5219 (Token-Ring Adapter)
- Token-Ring adapter card for Linux workstation
- Token-Ring cables (as required)
Ethernet Attach:
- Enterprise FC 5220 (Ethernet Adapter)
- Ethernet port or adapter for Linux workstation
- Ethernet cables (as required)

Software requirements
The following software is supported by the library driver:
v For Linux distribution support, refer to Product requirements on page 73.
v IBM Tape and Medium Changer Device Driver (IBMtape) for Linux
To obtain the most current service and documentation for this software, refer to
Appendix A, Accessing documentation and software online, on page 321.

Installation instructions
The IBM tape library driver for Linux (ibmatl), is supplied in an rpm package. The
following sections describe installation, removal, configuration, and verification
procedures for ibmatl. Refer to any Linux distribution that supports rpm for rpm
command information. You must have root authority to proceed with the
installation of the driver.
In the subsequent pages, you can see file names with xxxx or x.x.x.x in them. The
xxxx or x.x.x.x refers to the version of the driver, which changes as IBM releases
new driver levels. Use the actual driver version numbers as you complete the
procedures.
Install and configure the LAN support before you proceed with the installation of
the ibmatl package. For information, refer to the Linux documentation appropriate
to the LAN support you are using.
The following files are installed on your system:
/etc/lmcpd (library manager control point daemon)
/etc/ibmatl.conf (configuration file)
/usr/lib/libibm.o (application interface object module)
/usr/lib/libibm64.o (64-bit application interface object module for 64-bit
IBM zSeries system only)
/usr/include/sys/mtlibio.h (application interface header file)
/usr/bin/mtlib (tape library driver utility program)
/usr/bin/mtlib64 (64-bit tape library driver utility program for 64-bit IBM
Chapter 7. 3494 Enterprise Tape Library support

193

zSeries system only)


/usr/bin/mtevent (tape library driver utility program)
/usr/bin/trcatl (tape library driver diagnostic program)

On the IBM Linux for IBM S/390 and zSeries systems, documentation files are
installed at
/usr/share/doc/packages/ibmatl/README (readme file)
/usr/share/doc/packages/ibmatl/license (license file)

On Red Hat Linux for Intel PC-based systems, documentation files are installed at
/usr/share/doc/ibmatl-x.x.x.x/README (readme file, where x.x.x.x is the version)
/usr/share/doc/ibmatl-x.x.x.x/license (license file, where .x.x.x.x is the version)

Note: If you are updating the ibmatl package, the existing /etc/ibmatl.conf file is
preserved (it is not overwritten).

Installation procedure
If ibmatl is already installed on your system, refer to Updating procedure on
page 195. This section assumes that you are installing ibmatl on a system where it
is not installed.
Run the following command to install ibmatl rpm package,
>rpm -ivv ibmatl.x.x.x.x.os.rpm

Connecting the Enterprise 3494 tape library


Use a LAN connection (either Ethernet or Token Ring) through TCP/IP. The
connection must be in place before the software is installed to ensure correct
initialization of the daemon. For each 3494 tape library that is connected through
TCP/IP, ensure that your machine has access to the Library Manager on the 3494
tape library. Use the ping utility to verify that you have network connectivity to
the Library Manager. Consult your network administrator if you need help with
this task.

Defining the library device to the lmcpd


After the software is installed and tape libraries are connected, the /etc/ibmatl.conf
file must be edited to define the library devices to the lmcpd. The format of the
file is
Symbolic name

Connection type

Identifier

Alternate LAN Connection

Symbolic name is used to identify each tape library. The symbolic names must be
unique across all libraries that are defined in the ibmatl.conf file.
Connection type is used to define the type of connection to the library. For TCP/IP
connections, this type is the IP address of the 3494 Library Manager. If the Library
has a dual LAN card that is installed, the second IP address of the dual LAN card
must be entered after the first IP address.
Identifier parameter is used to specify a name by which the Library Manager
identifies the host machine. This identifier has a maximum length of 8 characters.
The symbolic network name of the host is usually the best name to use, although
any name is acceptable. This parameter is used only to identify a particular host to
the 3494 Library Manager.

194

IBM Tape Device Drivers Installation and Users Guide

Alternate LAN Connection is used to specify an alternate IP address for a 3494


High Availability LAN configuration. If the High Availability Library has a dual
LAN card, the second IP address of the dual LAN card must be entered after the
first alternate LAN connection IP address.
The following examples show how to define the library name.
3494a

9.115.32.21

jupiter

This stanza defines the 3494a library that is connected to the host. The address of
the 3494 Library Manager is 9.115.32.21. The tape library uses jupiter as the
identifier for the host.
libmgrc9

9.115.46.15

telos

9.115.46.17

This stanza defines the libmgrc9 High Availability library that is connected
through TCP/IP to the workstation. The IP addresses of the dual Library Managers
are 9.115.46.15 and 9.115.46.17.
libmgrc7

9.115.32.21

9.115.32.22

mercury

This stanza defines libmgrc7 with a dual LAN card connected through TCP/IP to
the workstation. The first address of the Library Manager on the 3494 Tape Library
is 9.115.32.21 and the second address is 9.115.32.22. The library uses the mercury
identifier for the host.
libmgrc7

9.115.32.21

9.115.32.22

mercury

9.115.26.13

9.115.26.14

This stanza defines the libmgrc7 High Availability library with dual LAN cards
connected through TCP/IP to the workstation. The IP addresses of the first Library
Manager are 9.115.32.21 and 9.115.32.22. The IP addresses of the second Library
Manager are 9.115.26.13 and 9.115.26.14. The library uses the mercury identifier for
the host.

Adding or deleting entries in the library device


You can add or delete entries in /etc/ibmatl.conf at any time. However, changes do
not take effect until the daemon is started again. Use the UNIX kill command
(kill -kill <pid>) to stop the lmcpd process, and enter the /etc/lmcpd command
to start the daemon again.
Ensure that activity on all libraries is completed before the lmcpd is restarted.

Updating procedure
If your current ibmatl was installed from an rpm package previously, issue the
following command.
rpm -Uvv
rpm -Uvv

ibmatl.x.x.x.x.s390.rpm
ibmatl.x.x.x.x.i386.rpm

--for IBM Linux on S/390 systems


--for Red Hat Intel PC based systems

Querying the installed package


The query function is supported for the ibmatl rpm package only.
The installed rpm package can be queried by running the following commands to
display information that is associated with the package.
To display information about ibmatl,
>rpm -qi ibmatl
Chapter 7. 3494 Enterprise Tape Library support

195

To display the package's file list, enter the command


>rpm -ql ibmatl

To display the states of files in the package, for example, normal, not installed, or
replaced.
>rpm -qs ibmatl

Verifying the install/update


If the IBMtape device driver is installed from the rpm package, issue the following
command,
>rpm -V ibmatl

Starting ibmatl
Start the daemon by using the following command,
/etc/lmcpd

Uninstallation procedure
Attention: Do not try to uninstall the ibmatl software by removing the files that
make up the ibmatl file set. It is best to use the rpm -e command or the uninstall
script.
Note: Halt all library activity before the uninstall procedure is started.
For the rpm package, run the command rpm -e.
rpm -evv

ibmatl

If more than one level of ibmatl exists on the system, explicitly specify the level to
remove it.
rpm -evv

ibmatl-5.0.7.0

3494 Enterprise tape library attachment test


The following procedure tests the attachment of a 3494 Enterprise tape library to a
Linux system. The procedure assumes that your device is defined in
/etc/ibmatl.conf as L3494.
1. Enter a shell prompt.
2. Enter mtlib -l L3494 -ql
3. Enter mtlib -l L3494 -qL

Problem determination
A set of tools is provided with the software to determine whether the ibmatl is
functioning correctly.

Error logging
The ibmatl uses the syslog facility to log the errors. Errors are logged according to
the /etc/syslog.conf file. The ibmatl uses the daemon facility for logging errors.
Only errors are logged with this facility. For information about using syslog, refer
to your system administration manuals.

196

IBM Tape Device Drivers Installation and Users Guide

Daemon trace facility


The following trace facility is available for the lmcpd.
daemon:trcatl -[ald]

Arguments:
-a
-l <name>
-d

(trace all libraries defined in /etc/ibmatl.conf)


(name of library)
(delete all log files; requires root authority)

Examples:
trcatl -a >/tmp/trace-out
trcatl -l libmgrc7

Note: The -a argument takes precedence over the -l argument.

Solaris
The software consists of a daemon that communicates directly with the Library
Manager of the 3494 tape library through RS-232 or LAN. It also has a utility
program that provides a command line interface to the daemon, and a C object
module that can be linked with user applications to provide a communication
interface with the daemon.
This software is known as a driver throughout this document because it provides
the software and interface necessary to drive the tape library. However, the product
does not consist of a device driver in the true sense of the term. That is, it is not an
extension of the operating system kernel, such as a SCSI tape device driver.
A typical environment for the IBM Oracle Automated Tape Library Driver is an
Oracle workstation that acts as a data server on a network with SCSI tape devices
that provide backup or restore and data server functions.
The Library Manager control point daemon (lmcpd) is provided in the package.
The lmcpd is a process that is always running on the system. It provides direct
communication with the 3494 Library Manager. An application links with the
supplied C object module by using the interface that is described in theIBM Tape
Device Drivers: Programming Reference. The subroutines in this module communicate
with the lmcpd to run the various library operations with standard UNIX
namespace sockets.
The lmcpd communicates with the Library Manager either through a standard 25
pin null modem D-shell RS-232 cable or through TCP/IP. The /etc/ibmatl.conf
configuration file is used to define the type of attachment for each library. Refer to
Defining the symbolic name to the lmcpd on page 201 for information.

Data flow
The software described in this chapter covers the library driver. The interface
between the application and the library driver is described in the IBM Tape Device
Drivers: Programming Reference. Figure 23 on page 198 illustrates the data flow.

Chapter 7. 3494 Enterprise Tape Library support

197

Tape Device
Driver

Adapter
Device Driver

Physical
Tape Drive

Application

C
Object
Module

TCP/IP

Native
TTY
Device
Driver

a250093

Library
Manager

LMCPD

Figure 23. Data flow for Solaris 3494 Enterprise tape library driver

Product requirements
The following software and hardware are supported by this product.

Hardware requirements
The following hardware is supported by the library driver:
v 3494 Enterprise Tape Library with SCSI-attached 3490E (Model C1A or C2A),
3590 and 3592 drives
v IBM TS1120 Tape Drive
v IBM Virtualization Engine TS7510
v IBM Virtual Tape Server (Models B10, B18, and B20)
v One of the following options, depending on which connection (RS-232 or LAN)
is required for the Enterprise Library Manager.
RS-232:
One standard 25 pin null modem D-shell RS-232 cable
(maximum of 15.24 meters [50 feet])
LAN:
- Token-Ring or Ethernet adapter card in a Solaris workstation that is
attached to the 3494 Enterprise Library Manager
- LAN cable

198

IBM Tape Device Drivers Installation and Users Guide

Software requirements
The following software is required for the library driver:
v Solaris Operating System
Note: For information, refer to Chapter 5, Solaris Tape and Medium Changer
Device Driver, on page 103.
v IBM Tape and Medium Changer Device Driver for Solaris
To obtain the most current service and documentation for this software, refer to
Appendix A, Accessing documentation and software online, on page 321.

Software compatibility
The following optional software is supported by the library driver:
IBM Tivoli Distributed Storage Manager for Solaris

Installation instructions
The IBM tape library driver for Solaris is installed by using the standard Solaris
package facility. The IBM Tape Library Driver for Solaris is the lmcpd package.

Preinstallation considerations
The LAN or tty support must exist on the machine before the IBM Tape Library
daemon for SunOS is installed. Install and configure the LAN or tty adapter and
the associated LAN or tty adapter device driver before you proceed with the
installation of the lmcpd package. For information, refer to the documentation
appropriate for the LAN or tty adapter and the LAN or tty adapter device driver
that you are using.
You must have root authority to complete this installation procedure.
Note: If an earlier version of the product is installed on the machine, run the
uninstallation procedure before you enter the following commands. Refer to
Uninstallation procedure on page 202 for information.
The following files are installed on the system:
v /etc/lmcpd (Library Manager control point daemon)
v
v
v
v
v
v
v

/etc/ibmatl.conf (configuration file)


/usr/lib/libibm.o (application interface object module)
/usr/lib/libibm64.o (64-bit application interface object module)
/usr/include/sys/mtlibio.h (application interface header file)
/usr/bin/mtlib (tape library driver utility program)
/usr/bin/mtevent (tape library driver utility program)
/usr/bin/trcatl (tape library driver diagnostic program)

v /opt/lmcpd (subdirectory)
v /opt/lmcpd/ibmatl.conf (backup configuration file)
Note: If you are updating the lmcpd package, the existing /etc/ibmatl.conf file is
preserved. It is not overwritten. A copy of ibmatl.conf is also installed in the
/opt/lmcpd directory.
Chapter 7. 3494 Enterprise Tape Library support

199

Installation procedure
Use the following commands to install the lmcpd package. Substitute the device
special file name for the installation source device that is appropriate for your
system.
If a previous version is installed on the system, uninstall the previous version first,
then enter the following command,
/usr/sbin/pkgrm

lmcpd

To install the package from the directory where the driver is located, enter the
following command,
/usr/sbin/pkgadd -d lmcpd.x.x.x.x

To verify that the installation was successful, enter the following command,
/usr/bin/pkginfo lmcpd

Connecting the 3494 Enterprise tape library


Use one of the following methods to connect the workstation to the 3494 tape
library.
v Use a standard 25 pin null modem D-shell RS-232 cable. Place the cable on the
native serial port or on the eight-port or 16 port asynchronous adapter.
v Use a LAN connection (either Ethernet or Token-Ring) through TCP/IP.
In either case, the connection must be in place before the software is installed to
ensure correct initialization of the daemon.
For each 3494 tape library that is connected with an RS-232 cable, follow the
directions in Configuring the serial port. For each 3494 tape library that is
connected through TCP/IP, ensure that your machine has access to the Library
Manager on the Enterprise device. Use the ping utility to verify that you have
network connectivity to the Library Manager. Consult your network administrator
if you need help with this task.
Identify the host name of your workstation to the Enterprise Library Manager.
Follow the instructions in the IBM Enterprise Automated Tape Library Operator Guide,
in the Add LAN Host section.

Configuring the serial port


After the 3494 tape library is connected to the workstation, you must configure the
serial port to which it is connected.
Set the following tty port attributes.
Baud rate
9600.
Data bits
8.
Stop bits
1.
Parity None.

200

IBM Tape Device Drivers Installation and Users Guide

Defining the symbolic name to the lmcpd


After the software is installed and all tape libraries are connected to the system,
the /etc/ibmatl.conf file must be edited to define the tape libraries to the lmcpd.
The format of the file is
Symbolic name

Connection type

Identifier

Alternate LAN Connection

Symbolic name is used to identify each tape library. The symbolic names must be
unique across all libraries that are defined in the/etc/ibmatl.conf file.
Connection type is used to define the type of connection to the library (either
RS-232 or TCP/IP). For RS-232 connections, this type is the device special file name
of the tty device (for example, /dev/ttya or /dev/tty1). For TCP/IP connections, this
type is the IP address of the Library Manager. If the Library has a dual LAN card
that is installed, the second IP address of the dual LAN card must be entered after
the first IP address.
Identifier is used to specify a name by which the Library Manager identifies the
host machine. This identifier has a maximum length of 8 characters. The host name
of the workstation is usually the best name to use (although it is not necessary).
This parameter is used only to identify a particular host to the 3494 Enterprise
Library Manager.
Alternate LAN Connection is used to specify an alternate IP address for an
Enterprise High Availability LAN-attached configuration. If the High Availability
Library has a dual LAN card that is installed, the second IP address of the dual
LAN card must be entered after the first alternate LAN connection IP address.
Note: For RS-232 attachments, the alternate LAN connection is not applicable.
Failover for RS-232 connections proceeds over the single serial line.
The following examples show how to define the library name.
3494a

/dev/ttya

mercury

This stanza defines the 3494a library that is connected by /dev/ttya to the
workstation. The library uses the mercury identifier for the host.
3494b

9.115.32.21

jupiter

This stanza defines the 3494b library that is connected through TCP/IP to the
workstation. The address of the Library Manager on the Enterprise Tape Library is
9.115.32.21. The library uses the jupiter identifier for the host.
libmgrc9

9.115.46.15

telos

9.115.46.17

This stanza defines the libmgrc9 High Availability library that is connected
through TCP/IP to the workstation. The IP addresses of the dual Library Managers
are 9.115.46.15 and 9.115.46.17.
libmgrc7

9.115.32.21

9.115.32.22

mercury

This stanza defines libmgrc7 with a dual LAN card connected through TCP/IP to
the workstation. The first address of the Library Manager on the 3494 tape library
is 9.115.32.21 and the second address is 9.115.32.22. The library uses the mercury
identifier for the host.
The following stanza defines the libmgrc7 High Availability library with dual LAN
cards connected through TCP/IP to the workstation. The IP addresses of the first
Chapter 7. 3494 Enterprise Tape Library support

201

Library Manager are 9.115.32.21 and 9.115.32.22. The IP addresses of the second
Library Manager are 9.115.26.13 and 9.115.26.14. The library uses the mercury
identifier for the host.
libmgrc7

9.115.32.21

9.115.32.22

mercury

9.115.26.13

9.115.26.14

Adding or deleting entries in the library


You can add or delete entries in /etc/ibmatl.conf at any time. However, changes do
not take effect until the daemon is started again. Use the UNIX kill command
(kill -kill <pid>) to stop the lmcpd process, then enter the /etc/lmcpd command
to start the daemon again.
Ensure that the library activity on all of the libraries is completed before the lmcpd
is restarted.

Uninstallation procedure
Halt all library activity before the uninstallation procedure is started. Stop the
lmcpd daemon if it is running. Enter the following command to uninstall the
library support from your workstation.
/usr/sbin/pkgrm lmcpd

3494 Enterprise tape library attachment test


The following procedure tests the attachment of a 3494 Enterprise tape library to a
Solaris system. The procedure assumes that your device is defined in
/etc/ibmatl.conf as L3494.
1. Enter a shell prompt.
2. Enter mtlib -l L3494 -qI
3. Enter mtlib -l L3494 -qL

Problem determination
A set of tools is provided with the software to determine whether the lmcpd is
functioning correctly.

Error logging
The lmcpd uses the syslog facility to log the errors. Errors are logged according to
the /etc/syslog.conf file. The lmcpd uses the daemon facility for logging errors.
Only errors are logged with this facility. For information about using syslog, refer
to your system administration manuals.

Daemon trace facility


The following trace facility is available for the lmcpd.
daemon:trcatl -[ald]

Arguments:
-a
-l <name>
-d

(trace all libraries defined in /etc/ibmatl.conf)


(name of library)
(delete all log files; requires root authority)

Examples:

202

IBM Tape Device Drivers Installation and Users Guide

trcatl -a >/tmp/trace-out
trcatl -l libmgrc7

Note: The -a argument takes precedence over the -l argument.

Windows
The software consists of a tape library service that communicates directly with the
Library Manager of the 3494 Enterprise Tape Library through LAN. A utility
program also provides a command prompt interface to the service, and a static
library and DLL that can be used to provide a communication interface with the
service.
A typical environment for the Windows Automated Tape Library Service is a
workstation that runs the Microsoft Windows operating system. It acts as a data
server on a network with SCSI tape devices that provide backup or restore and
data server functions.
The IBM Automated Tape Library service is provided in the installation package.
This service is installed with STARTUP=AUTOMATIC, which means that it is
started when the Microsoft Windows operating system is started. An application
program might access those functions through API calls. The interface is described
in the IBM Tape Device Drivers: Programming Reference. The subroutines in this
module communicate with the Enterprise Library Manager to run the various
library operations.
The service communicates with the Library Manager through TCP/IP. The
c:\winnt\ibmatl.conf configuration file is used to define the type of attachment
for each library. Refer to Defining the symbolic name to the service on page 207
for information.

Data flow
The software described in this chapter covers the library driver. The interface
between the application and the library driver is described in the IBM Tape Device
Drivers: Programming Reference.Figure 24 on page 204 illustrates the data flow.

Chapter 7. 3494 Enterprise Tape Library support

203

Figure 24. Data flow for Windows 3494 Enterprise tape library driver

Product requirements
The following hardware and software components are required and supported by
IBM.

Hardware requirements
The following hardware is required for the library driver:
v 3494 Enterprise Tape Library with Enterprise Tape System 3590 and 3592 drives
v IBM TS1120 Tape Drive
v IBM Virtualization Engine TS7510
v IBM Virtual Tape Server (Models B10, B18, and B20)
The following options are required for operation of the Enterprise Library
Manager:
v Token-Ring or Ethernet adapter card in an Intel-compatible workstation that
runs Microsoft Windows and attached to the 3494 Enterprise Tape Library
v LAN cable

Software requirements
Microsoft Windows is required for the library driver: For information, refer to
Chapter 6, Windows Tape and Medium Changer device driver, on page 145.

204

IBM Tape Device Drivers Installation and Users Guide

To obtain the most current service and documentation for this software, refer to
Appendix A, Accessing documentation and software online, on page 321.

Installation instructions
The IBM tape library service for Microsoft Windows is installed by starting the
installation binary. This binary has the format ibmatl.x.x.x.x.x86.exe for 32-bit
Windows 200x that runs on x86, ibmatl.x.x.x.x.i64.exe for 64-bit Windows 2003 that
runs on IA64, and ibmatl.x.x.x.x.x64.exe for 64-bit Windows Server 2003 and
Windows Server 2008 that runs on AMD64 and EM64T.

Installation procedure
Use the following procedure to install the IBM Automated Tape Library Service or
to upgrade the software level of your service on your workstation.
Follow these steps to run the installation of the service and its associated software:
1. Verify that the prerequisites are satisfied. Refer to Product requirements on
page 204.
2. Ensure that the workstation is on the LAN.
3. Log on as Administrator.
4. If the IBM Automated Tape Library Service is installed, ensure that all
programs and services that use the service are stopped. Then, remove it from
the system.
5. Ensure that the IBM Automated Tape Library Service is not running.
v On Windows NT
a. Click Start.
b. Move to Settings, then click Control Panel.
c. Double-click the Services icon.
v On Windows 2000 and 2003
a. Click Start.
b. Move to Settings, then click Control Panel.
c. Double-click the Services icon.
v On Windows 2008
a. Click Start.
b. Double-click the Administrative Tools icon.
c. Double-click the Services icon.
The Services window opens. Scroll through the entries until you find IBM
Automated Tape Library. If you do not find the entry for IBM Automated
Tape Library, the service is not installed; click Close. If there is an entry and
the status is blank, the service is not running; click Close. If the status is
Started, click IBM Automated Tape Library, then click Stop.
v Wait for the service to stop and the Status to be set to blank, then click
Close.
v On 32-bit Windows 200x, wait for the service to stop and the Service status
to be set to Stopped, then close both windows.
v On 64-bit Windows, the service is stopped and removed automatically
during the uninstallation.
6. Obtain ibmatl driver from the IBM storage FTP server in binary.
7. Locate and start ibmatl driver.
Chapter 7. 3494 Enterprise Tape Library support

205

8. You see some windows displayed that indicates the image is unpacked and
read and the installation program is setting up. After these messages are
displayed, the screen stops on a window called Welcome to the IBM
Automated Tape Library Setup Program. Follow the instructions on the
window, then select Next.
9. The Software License Agreement window opens. Read the contents, then
click Yes if you accept the terms. If you do not accept the terms, the
installation script exits.
10. The Choose Destination Location window opens. You can accept the default
destination folder by selecting Next >, or you can select Browse... and select
another destination folder by following the prompts in the subsequent dialog.
If you do not select the default destination folder, you must record your
destination folder for future reference. After you select the folder, click Next >.
11. The Setup Complete window opens. You can check the Yes, I want to view
the Read Me file prompt to read the file, then click Finish, or click Finish.
The Read Me file is stored in the destination file that you indicated in step 10.
12. After you click Finish, if you did not select to view the Read Me file, the
installation dialog exits. If you chose to view the Read Me, it is displayed.
After you read it, exit the Notepad application. An informational message is
displayed, indicating that the setup is complete. Click OK to exit the
installation dialog.
13. Verify that you can use the ping utility successfully for any tape library you
want to access from your workstation.
14. Update the c:\winnt\ibmatl.conf file, if necessary, with entries for each tape
library you want to access from your workstation. Refer to Defining the
symbolic name to the service on page 207 for details.
15. Start the service in one of the following ways:
v For Windows NT, start the service by restarting the system or by using the
Services option in the Control Panel window.
v On Windows 2000 and 2003, start the service by using the Services icon,
which is on the Administrative Tools icon in the Control Panel window.
v On Windows 2008, start the service by using the Services icon, which is on
the Administrative Tools icon.
Note: When a firewall is enabled on Windows, you must allow the lmcpd
program to access the network. Do not block the network IP port of
3494, which is used for communication between the 3494 library and
lmcpd.
For example, to allow lmcpd.exe access to the network on Windows
2008 servers, click the Windows Firewall icon in the Control Panel
window. Next, click the button to allow a program or an exception, and
then click Add Program. Select your browser and then select lmcpd.exe
in /Windows/system32 for an x86 system or /Windows/SysWOW64 for
i64 or x64 systems.

Connecting the 3494 Enterprise tape library


Use a LAN connection (either Ethernet or Token-Ring) through TCP/IP to connect
the workstation to the 3494 Enterprise tape library. The connection must be in
place before the service is started to ensure correct initialization of the service.

206

IBM Tape Device Drivers Installation and Users Guide

Ensure that your machine has access to the Library Manager on the Tape Library.
Use the ping utility to verify that you have network connectivity to the Library
Manager. Consult your network administrator if you need help with this task.
Identify the host name of your workstation to the Enterprise Library Manager.
Follow the instructions in the IBM Enterprise Automated Tape Library Operator Guide,
in the Add LAN Host section.

Defining the symbolic name to the service


After the software is installed and the tape libraries are connected to the system,
the c:\winnt\ibmatl.conf file must be edited to define the tape libraries to the
service. The format of the file is
Symbolic name

Connection type

Identifier

Alternate LAN Connection

Symbolic name identifies each tape library. The symbolic names must be unique
across all libraries that are defined in the c:\winnt\ibmatl.conf file.
Connection type is the IP address of the Library Manager. If the Library has a dual
LAN card that is installed, the second IP address of the dual LAN card must be
entered after the first IP address.
Identifier specifies a name by which the Library Manager identifies the host
machine. This identifier has a maximum length of 8 characters. The host name of
the workstation is usually the best name to use (although it is not necessary). This
parameter identifies only a particular host to the Enterprise Library Manager.
The following stanza defines the 3494b library that is connected through TCP/IP to
the workstation. The address of the Library Manager on the 3494 tape library is
9.115.32.21. The library uses the jupiter identifier for the host.
3494b

9.115.32.21

jupiter

The Alternate LAN Connection parameter specifies an alternate IP address for an


Enterprise High Availability LAN configuration. If the High Availability Library
has a dual LAN card that is installed, the second IP address of the dual LAN card
must be entered after the first alternate LAN connection IP address.
The following stanza defines the libmgrc9 High Availability library that is
connected through TCP/IP to the workstation. The IP addresses of the dual
Library Managers are 9.115.46.15 and 9.115.46.17.
libmgrc9

9.115.46.15

telos

9.115.46.17

The following stanza defines libmgrc7 with a dual LAN card connected through
TCP/IP to the workstation. The first address of the Library Manager on the 3494
tape library is 9.115.32.21 and the second address is 9.115.32.22. The library uses
the mercury identifier for the host.
libmgrc7

9.115.32.21

9.115.32.22

mercury

The following stanza defines the libmgrc7 High Availability library with dual LAN
cards connected through TCP/IP to the workstation. The IP addresses of the first
Library Manager are 9.115.32.21 and 9.115.32.22. The IP addresses of the second
Library Manager are 9.115.26.13 and 9.115.26.14. The library uses the mercury
identifier for the host.
libmgrc7

9.115.32.21

9.115.32.22

mercury

9.115.26.13

9.115.26.14

Chapter 7. 3494 Enterprise Tape Library support

207

Adding or deleting libraries to the service


You can add or delete entries in c:\winnt\ibmatl.conf at any time. However,
changes do not take effect until the tape service starts again.
On Windows NT, stop and start the service by using the Services option in the
Control Panel window.
On Windows 200x, stop and start the service by using the Services icon, which is
on the Administrative Tools icon in the Control Panel window.
Ensure that the library activity on all of the libraries is completed before the
service is started again.

Uninstallation procedure
Use the following procedure to remove the IBM Automated Tape Library Service
permanently from your workstation.
Note: If you are upgrading the software level of your service, follow the steps in
Installation procedure on page 205.
Follow these steps to uninstall the service and its associated software:
1. Log on as Administrator.
2. Back up the c:\winnt\ibmatl.conf file if you want to keep a copy of this file
because the uninstall procedure erases the file.
3. Ensure that all programs and services that use the IBM Automated Tape
Library Service are stopped.
4. Ensure that the IBM Automated Tape Library Service is not running. Click
Start > Settings > Control Panel.
v Double-click the Services icon.
v On Windows 200x, double-click the Administrative Tools icon, then
double-click the Services icon.
The Services window opens. Scroll through the entries until you find IBM
Automated Tape Library. If the status is blank, the service is not running;
click Close. If the status is Started, click IBM Automated Tape Library, then
click Stop.
v Wait for the service to stop and the Status to be set to blank, then click
Close.
v On 32-bit Windows 200x, wait for the service to stop and the Service status
to be set to Stopped, then close both windows.
v On 64-bit Windows, the service is stopped and removed automatically
during the uninstallation.
5. Open a Command Prompt window, enter lmcpd -remove, press Enter, then
wait for the command to complete.
Note: If you forget this step, the next time that the system is started,
Microsoft Windows NT tries (unsuccessfully) to start the service again.
To resolve this situation, you must reinstall the service, then uninstall it.
6. Double-click Add/Remove Programs in Windows NT/200x or Programs and
Features on Windows 2008 in the Control Panel window.
7. Scroll to and select IBM Automated Tape Library.

208

IBM Tape Device Drivers Installation and Users Guide

8. For Windows 200x, click Change/Remove.


9. A Confirm File Deletion window opens. Click Yes.
10. After various dialogs run, a Remove Programs from Your Computer window
opens, which indicates the components that were removed successfully. Click
OK to exit the dialog.
11. For Windows 2000 and 2003, close the Add/Remove Programs Properties
window.
For Windows 2008, close the Programs and Features window.

3494 Enterprise tape library attachment test


The following procedure tests the attachment of a 3494 Enterprise tape library to a
Windows system. The procedure assumes that your device is defined in
c:\winnt\ibmatl.conf as L3494.
1. Open a Windows command shell window.
2. Enter mtlib -l L3494 -qI
3. Enter mtlib -l L3494 -qL

Problem determination
A tracing tool is provided with the software to determine whether ibmatl is
functioning correctly.

Daemon trace facility


The following trace facility is available for the ibmatl service.
trcatl -h
usage: trcatl [-ald]
[-l <name>]
[-a]
[-d]

name of library
all libraries defined in c:\WINNT\ibmatl.conf
delete all logfiles in c:\WINNT\

Note:
1. Run trcatl in the Command Prompt window.
2. The -a parameter takes precedence over the -l parameter.
3. The trace.out is located under the directory where the trcatl runs.
Examples:
trcatl -l libmgrc7
trcatl -a > trace.out

Chapter 7. 3494 Enterprise Tape Library support

209

210

IBM Tape Device Drivers Installation and Users Guide

Chapter 8. IBM Tape Diagnostic Tool (ITDT)


This chapter describes the IBM Tape Diagnostic Tool.

Purpose
The IBM Tape Diagnostic Tool (ITDT) is available in two versions:
v Standard Edition (ITDT-SE) - The command line version.
v Graphical Edition (ITDT-GE) - The GUI version for the following platforms:
Microsoft Windows operating systems
Linux operating systems
Both versions provides the user with a single diagnostic program for tapeutil
applications. Both SE and GE contains tapeutil function with SE also providing
scripting capability.
Note: The term tapeutil is a synonym for the tool that is delivered with the device
driver. For example, this tool is named tapeutil on UNIX operating systems;
it is named ntutil on Microsoft Windows operating systems.
The available advanced operations that are provided by the IBM Tape Diagnostic
Tool is completed on tape drives and tape libraries. By using this function, the
customer completes maintenance tasks and runs diagnostic tasks to determine tape
drive issues. This action reduces product downtime and increases productivity.
The IBM Tape Diagnostic Tool is designed to
v
v
v
v
v

Run quick or extended diagnostic tests on tape drives


Start tape library self-test operations
Retrieve dumps from tape drives and libraries
Run a firmware update on tape drives or libraries
Online Check for Firmware updates for tape drives or libraries (ITDT-GE)

v Test the performance of the environment by completely writing a cartridge and


measuring performance
v Verify tape drive compression
v Measure system performance
v Retrieve and display cartridge usage information
v Verify the encryption environment
This test is used to verify whether data on the cartridge was written encrypted.
v Scan the system to discover all supported tape and library devices.
v Run a connection test (scan)
This test is used to verify that all devices are attached properly
v Run a standard test to check whether the tape device is defective and output a
pass/fail result
Note: When this test is completed, all data on the cartridge is overwritten.
v Run a full write function

Copyright IBM Corp. 2007, 2014

211

This function writes the entire cartridge, overwriting all previous data with a
selectable block size that contains either compressible or incompressible data and
then outputs performance data.
Note: When this test is completed, all data on the cartridge is overwritten.
v Run a system test
Write different block sizes with compressible and incompressible data and then
outputs performance data.
Note: When this test is completed, all data on the cartridge is overwritten.
v Run a tape usage function to retrieve statistical data and error counters
v Run a manual inspect function for devices not recognized.
v Run HD-P functions like discovery.
v Physical Copy/Data migration and Verification of Cartridges.
v Log and Dump File analysis.
The ITDT-SE provides the most important functions of the previous tapeutil tools.
As an extension of the current tapeutil variants, the set of operations and functions
available with ITDT-SE is identical across all supported operating systems (unless a
particular function is not available on a particular system).
Dedicated device drivers for tapes and libraries can be installed on the target
system and an application is installed that uses the tape/library devices. When this
configuration exists, ITDT-SE can coexist with the application so that when the
application disables the device internally, ITDT-SE can run the diagnostic tests on
that device.

Accessing ITDT
IBM maintains the latest levels of the ITDT tool chain and documentation on the
Internet at http://www.ibm.com/support/fixcentral.
One option to access ITDT is through Appendix A, Accessing documentation and
software online, on page 321. When an IBM driver is downloaded, there is a
corequisite to download ITDT.
This portal gives access to the download area where the following procedure
guides you to the correct download:
1. In the Product Group menu select Storage Systems.
2. In the Product Family menu select Tape Systems.
3. In the Product Type menu select Tape device drivers and software.
4. In the Product menu select Tape Diagnostic Tool (ITDT).
5. Select your platform and press Continue.

Supported systems
ITDT is supported on the following systems.

212

IBM Tape Device Drivers Installation and Users Guide

Standard Edition (ITDT-SE)


The Standard Edition (ITDT-SE) is supported on the following operating systems.
v AIX operating systems (64-bit pSeries/System p)
AIX 5L 5.3
AIX 6.1
AIX 7.1
v HP-UX operating systems
HP-UX Version 11i v1, v2 and v3 (64-bit PA-Risc and Itanium)
v Linux operating systems
Linux systems with Kernel 2.6, glibc 2.2.5 and later (32-bit x86)
Linux systems with Kernel 2.6, glibc 2.3.2 and later (64-bit x64)
Linux systems with Kernel 2.6, glibc 2.2.5 and later (64-bit pSeries/System p)
Linux systems with Kernel 2.6, glibc 2.3.3 and later (64-bit zSeries/System z)
v Macintosh OS X
Mac OS X 10.5.6 and later (Leopard) (Intel, 32-bit)
Mac OS X Server 10.5.6 and later (Intel, 32-bit)
Mac OS X 10.6 (Snow Leopard) and later (Intel, 32 and 64-bit)
Mac OS X Server 10.6 and later (Intel, 32 and 64-bit)
v Solaris operating systems
Solaris Version 9 and 10 (64-bit SPARC and 64-bit x64)
Solaris Version 11.1 (64-bit SPARC)
v Windows operating systems

Microsoft Windows Server 2008 (32-bit x86 and 64-bit x64)


Microsoft Windows Server 2012 (32-bit x86 and 64-bit x64)
Microsoft Windows 7 (32-bit x86 and 64-bit x64)
Microsoft Windows 8 (32-bit x86 and 64-bit x64)
v i5/OS V5R4, IBM i 6.1 and IBM i 7.1 (iSeries/System i)

Graphical Edition (ITDT-GE)


The Graphical Edition (ITDT-GE) is supported on the following operating systems.
v Windows operating systems
Microsoft Windows Server 2008 (32-bit x86 and 64-bit x64)
Microsoft Windows Server 2012 (32-bit x86 and 64-bit x64)
Microsoft Windows 7 (32-bit x86 and 64-bit x64)
Microsoft Windows 8 (32-bit x86 and 64-bit x64)
v Linux operating systems
Linux Distributions with Kernel 2.6, glibc 2.2.5 and later (32-bit x86 and 64-bit
x64).

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

213

Supported equipment
The following equipment is supported for both the Standard Edition (ITDT-SE) and
the Graphical Edition (ITDT-GE):
v IBM Ultrium 3580 Tape Drive (Generation 3, 4 and 5)
v IBM Ultrium Tape Drives T800/F, T800V, T1600/F, T3000V/P
v IBM 588/TS1030 model F3A and F3B Tape Drive
v IBM 3588/TS1060 model F6A Tape Drive
v IBM 3580 Half Height/TS2230 and TS2240 Tape Drive Express
v IBM TS2250 Tape Drive
v
v
v
v
v
v
v

IBM
IBM
IBM
IBM
IBM
IBM
IBM

TS2260 Tape Drive


TS2340 Tape Drive Express
TS2350 Tape Drive
TS2360 Tape Drive
3592/TS1120/TS1130/TS1140/TS1150 Enterprise Tape System
3572/TS2900 Tape Library Express
3573/TS3100 and TS3200 Tape Library Express

v IBM 3576/TS3310 Tape Library


v IBM 3577/TS3400 Tape Library
v IBM 3584/TS3500 and TS4500 Tape Library

The following equipment is supported System x LTO tape drives. These drives are
not tested by the IBM Test Lab. They are also not supported by IBM support. All
queries are to be addressed to IBM System x support.
v IBM Full High LTO Gen 1, p/n 00N8016, replacement p/n 37L5799
v IBM Full High LTO Gen 2, p/n 59P6744, replacement p/n 71P9141
v IBM Full High LTO Gen 3, p/n 25R0012 and 39M5657, replacement p/n 25R0003
and 23R4808
v IBM Half High LTO Gen 3, p/n 43W8478, replacement p/n 23R7036
v IBM Half High LTO Gen 4, p/n 44E8895, replacement p/n 45E1125
v IBM Half High LTO Gen 5
v 3600-XXX Library and Autoloader IBM Full High LTO Gen 1, p/n 09N4048*
v 4560-SLX IBM Full
v 3623-2LX IBM Full
v 3361-4LX IBM Full
(p/n 40K2575)*
v 3362-2LX IBM Full
42D8769)*

High LTO Gen 2, p/n 71P9146*


High LTO Gen 2
High LTO Gen 3 SCSI (p/n 42C3942 and 40K2573) and Fibre
High LTO Gen 3 SCSI (p/n 40K2596) and Fibre (p/n

Note: *Refer to Retain tip H195744. External document link: http://www947.ibm.com/systems/support/supportsite.wss/docdisplay?lndocid=MIGR5081290&brandind=5000008.


All other System x LTO tape drives are not supported by ITDT.
Note: Replacement part numbers are only given for the stand-alone IBM LTO tape
drives.

214

IBM Tape Device Drivers Installation and Users Guide

For i5/OS operating systems, see i5/OS operating systems on page 224 for
product support limitations.

IBM Tape Diagnostic Tool - Standard Edition


Installing ITDT - Standard Edition
This section describes the installation procedures for the Standard Edition of ITDT
in various operating systems.
Before the IBM Tape Diagnostic Tool Standard Edition (ITDT-SE) is used with the
IBM Tape Device Driver, we recommend upgrading to the latest available IBM
Tape Device Driver level.
In a System Managed Encryption setup, the [E] Encryption test always exits with
NO DRIVER SPECIAL FILE when ITDT-SE is started with -force-generic-dd.

Installing ITDT-SE on Windows operating systems


To install ITDT-SE on Windows operating systems, complete the following steps.
Note: ITDT-SE can be used only by a user with Administrator rights.
1. Download itdtinst <version> windows<arch>.exe where <arch> can be
v AMD64 (64-bit Intel EM64T or AMD servers)
v X86 (32-bit Intel-compatible servers)
to a directory of your choice.
2. Run the following command:
itdtinst<version>windows<arch>.exe

Installing ITDT-SE on i5/OS operating systems


ITDT-SE for i5/OS or IBM i is installed with a graphical installer based on the
InstallAnywhere installation software. This software must be run on a Microsoft
Windows system and installs the software onto the remote i5/OS system. The
installer generates installation information on the local Microsoft Windows system.
So, the program can be removed from the remote i5/OS system by running the
uninstaller on the local Microsoft Windows system.
To install ITDT-SE on i5/OS operating systems, complete the following steps.
Note: ITDT-SE on i5/OS requires a Microsoft Windows PC with a Java run time
1.4.2 or higher.
1. Start the installer itdtinst<version>I5OS.exe.
2. Read through the welcome and license screens.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

215

a2500246

Figure 25. Welcome/Startup screen

a2500247

3. Accept the License Agreement, then click Next.

Figure 26. License screen

4. Enter your i5/OS system host name or IP address and administrator


credentials. Start the installation by pressing Install. Click Done when the
installation is complete.

216

IBM Tape Device Drivers Installation and Users Guide

a2500248

Note: The user name must be QSECOFR.

a2500249

Figure 27. Machine credentials screen

Figure 28. Installation progress screen

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

217

a2500250

Figure 29. Installation complete screen

Installing ITDT-SE on other supported operating systems


To install ITDT-SE on other supported operating systems, complete the following
steps.
Note: ITDT-SE can be used only by a user with root access rights, except for the
Mac OS, which requires the user to have the minimum of read/write access
to the device file.
1. Download itdtinst <version><OS> to a directory of your choice.
v itdtinst<version> Aix is for AIX operating systems
v itdtinst <version> LinuxX86 is for Linux operating systems on X86 hardware
v itdtinst <version> LinuxX86_64 is for Linux operating systems on X86_64
hardware
v itdtinstn<version> LinuxPPC is for Linux operating systems on pSeries
v itdtinst <version> LinuxS390X is for Linux operating systems on zSeries
v itdtinst <version> Hpux is for HP-UX operating systems.
v itdtinst <version> MacOS is for Mac OS operating systems.
v itdtinst <version> SolarisX86_64 is for Solaris X86_64 operating systems.
v itdtinst <version> Solaris is for Solaris SPARC operating systems.
2. Run the following command to make itdtinst<version><OS> executable.
chmod 700 itdtinst<version><OS>

3. Run the following command


itdtinst<version><OS>

or
./itdtinst<version><OS>

218

IBM Tape Device Drivers Installation and Users Guide

depending on your operating system.

Starting ITDT - Standard Edition


This section describes the startup procedures for the Standard Edition of ITDT in
various operating systems.

Starting ITDT-SE on Solaris operating systems


1. If the IBM Tape Device Driver is not used, if it is not installed, or you want to
be able to run -force-generic-dd, configure the sgen driver.
A script sgen_solaris_conf.sh is included in the ITDT-SE package. This script
allows the user to configure the sgen generic SCSI driver that is shipped with
Solaris.
ITDT-SE requires that the sgen device driver is configured so that the devices
you want to work with can be found.
Note: For system security reasons, always reset the sgen device driver settings
after you finish working with ITDT-SE, by using the
sgen_solaris_conf.sh script.
To configure the sgen driver, start the sgen_solaris_conf.sh script with root
access.
The following command line options are available on the SGEN driver
configuration screen:
v 1. Check driver: This option checks if the driver /kernel/drv/sgen is available.
v 2. List driver settings: This option shows the current activated devices.
v 3. New driver configuration: This option shows the screen that is used to
create a new driver configuration (see Step 2).
v 4. Stop sgen driver: This option stops the driver (that is, rem_drv sgen).
v 5. Start sgen driver: This option stops and starts the sgen driver.
v 6. Exit program: This option closes the shell script.
2. Enter option 3 to create a new driver configuration.
The following command line options are available on the New Configuration
screen. Use these options to configure the sgen driver:
v 1. List targets: This option shows the targets in current configuration.
v 2. Define device types: This option defines drive and changer types.
v 3. or 5. Add targets: This option adds targets to the list.
Note: Option 3 allows for the addition of individual devices one at a time.
Option 5 allows for the addition of a range of devices, eliminating the
need to add many devices one by one.
v 4. or 6. Remove targets: This option removes targets from the list.
Note: Option 4 allows for the removal of individual devices one at a time.
Option 6 allows for the removal of a range of devices, eliminating the
need to remove many devices one by one.
v 7. Save configuration: This option saves the modifications.
v 8. Back to Main Menu: This option returns to the main menu.
3. After the sgen driver is configured, enter command line option 8 to go back to
the main menu.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

219

4. On the SGEN driver configuration screen enter command line option 5. This
option starts the sgen driver. New devices are found by using the definitions
that are completed in Step 2.
5. After the new devices are found, enter option 6 to exit the sgen_solaris_conf.sh
script.
Note: For Fibre Channel Host Bus Adapters (HBAs), special handling is required.
Attached devices must be configured with their WWPN in the sgen.conf file.
This task must be done manually. It is not completed by using the
sgen_solaris_conf.sh script.
The following is an example how to add those devices:
Run the command "cfgadm -al" to get the WWPN number(s).
......
c4
fc-private
connected
configured
c4::5005076302401924
tape
connected
configured
.....
Add the WW-PN number(s) into the sgen.conf file.
name="sgen" parent="fp" target=0 lun=0 fc-port-wwn="5005076302401924";
name="sgen" parent="fp" target=0 lun=1 fc-port-wwn="5005076302401924";
If you have finished the editing, the sgen driver has to be restarted.
Please enter "update_drv sgen".

The Read Attribute command is 16-byte CDB. On Solaris 10, IBMtape can
detect what maximum CDB length is supported from HBA attributes and set
the supported CDB. For Solaris 9, CDB16 must be enabled for ITDT-SE to
work correctly. This procedure can be done by adding the entry of
cdb16_support=1

at the first line in


/usr/kernel/drv/IBMtape.conf

and reload the IBMtape driver again.


To start ITDT-SE, run the following command:
./itdt

At first start, read the User License Agreement.


v Press Enter to scroll the license screens forward or b followed by Enter to
go back.
v Type i if you agree to the terms of license or q followed by Enter to quit
the application.
During the initial program startup, the input and output directories are
created.
v Input directory: default directory for firmware files during Firmware
Update
v Output directory: directory that contains the result files, dump files, and
log files after tests are run
ITDT-SE does not make changes outside the installation directory.

220

IBM Tape Device Drivers Installation and Users Guide

Starting ITDT-SE on Windows operating systems


Start ITDT by running the following command:
itdt.exe

At first start, read the User License Agreement.


v Press Enter to scroll the license screens forward or b followed by Enter to go
back.
v Type i if you agree to the terms of license or q followed by Enter to quit the
application.
At first program startup, the license text is displayed and the input and output
directories are created. ITDT-SE does not create any registry entries or make
changes outside the installation directory.
v Input directory: default directory for firmware files during Firmware Update
v Output directory: directory that contains the result files, dump files, and log files
after tests are run

Starting ITDT-SE on i5/OS operating systems


To use ITDT-SE to update firmware or pull dumps from a tape drive inside a tape
library, make sure that the drives are varied online in STANDALONE MODE by
completing the following steps.
1. Issue the command WRKMLBSTS. Identify the library and drives you want to
work with. Note their names (for example, TAPMLB01, TAP01, TAP02).
2. Deallocate the corresponding drives by using option 6.
3. Vary OFF the TAPMLB by using option 2.
4. Enter the following command:
WRKCFGSTS *DEV TAP*

Identify the drives that were noted in Step 1 (for example, TAPMLB01, TAP01,
TAP02) and vary them ON by using option 1.
5. Start the iSeries Qshell environment with the following command:
QSH

6. Change to the folder /home/itdt with the following command:


cd /home/itdt

7. Start ITDT with the following command.


/itdt

8. Update Firmware and pull dumps. See Firmware Update on page 233 and
Dump on page 232.
9. When firmware updates and dumps are complete, enter the following
command:
WRKCFGSTS *DEV TAP*

10. Vary off the TAPs that you worked with by using option 2.
11. Issue the command WRKMLBSTS. Identify the library and drives you worked
with.
12. Vary on the TAPMLB by using option 1.
13. Press F5 to refresh the screen. The TAPs belonging to the TAPMLB shows up.
14. Allocate the TAPs back to the TAPMLB by using option 4 or 5.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

221

Starting ITDT-SE on other supported operating systems


To start ITDT-SE, run the following command
./itdt

At first start, read the User License Agreement:


v Press Enter to scroll the license screens forward or b followed by Enter to go
back.
v Type i if you agree to the terms of license or q followed by Enter to quit the
application.
During the initial program startup, the input and output directories are created.
v Input directory: default directory for firmware files during Firmware Update
v Output directory: directory that contains the result files, dump files, and log files
after tests are run
ITDT-SE does not make changes outside the installation directory.

Standard Edition - known issues and limitations


This section describes the known issues and limitations of the ITDT-SE program.

AIX operating systems


The following are the known scan limitations:
v Only devices that have the device state "available".
For FC and SAS devices, ID and LUN greater than 999 are not displayed; they are
masked by ###.
When logged in through telnet, backspace might not work - an escape sequence is
inserted and the input is ignored after Enter is pressed.

HP-UX operating systems


Verify that the following patches are installed before ITDT-SE is started.
v PA-Risc: At least these patches:
ld and linker tools cumulative patch
libc cumulative patch
v Itanium/IA-64: All regular patches and the following patches:

VxVM 3.5~IA.014 Command Patch


VxVM 3.5~IA.014 Kernel Cumulative Patch
Aries cumulative patch
linker + fdp cumulative patch

Note: ITDT-SE is emulated by Aries (a binary emulator that transparently emulates


32-bit and 64-bit HP-UX PA-RISC applications on HP-UX IA-64 machines).
On HP-UX11.iV3 systems, tape libraries that are operated through the drive's
control path (no control path failover) might disappear from the Device List after a
[F] Firmware Update on the controlling drive. It is recommended to complete
repeated [S] Scan operations to make the library reappear in the device list.

222

IBM Tape Device Drivers Installation and Users Guide

Linux operating systems


ITDT-SE on Linux requires glibc 2.2.5 or later.
Note: On an SLES9 s390x (64 bit) configuration, you might experience a SCSI
CMD TIMEOUT when the [T] option is run with the IBM Tape Device
Driver.
For SUSE SLES9 on zSeries, ensure that the kernel update SUSE-SA:2007:035 is
installed.

Solaris operating systems


Rescan might take 6-8 minutes, depending on the numbers of host adapters and
devices attached.
The known scan limitations: SCSI ID 0-255, LUN 0-10.
If the IBM Tape Device Driver is not installed on Solaris 10, tape devices might not
be found during scan although they are configured in sgen.conf. When this event
occurs, complete the following steps to configure the devices:
1. Check the current driver bindings for IBM tape drives and changers by
entering the following commands:
# egrep "scsiclass,01" /etc/driver_aliases
# egrep "scsiclass,08" /etc/driver_aliases

(for drives)
(for changers)

2. Modify the /etc/driver_alias file to comment all lines not starting with sgen
and containing identification of your drives and changers. Examples:
#st
#st
#st
#st

"scsiclass,01"
"scsiclass,01.vIBM.pULT3580-TD4"
"scsiclass,08"
"scsiclass,08.vIBM.p3573-TL"

(all
(IBM
(all
(IBM

tape drives)
tape drive model ULT3580-TD4)
changers)
changer model 3573-TL)

3. Check that the configured drives are not configured for st driver by entering
the following command:
# cfgadm -al

If the tape drive is claimed by st device driver, an entry with cxx:rmt/y, is


displayed, for example:
c11::rmt/0

tape

connected

configured

unknown

4. Add sgen driver aliases with one of the following commands:


# update_drv -a -i "scsiclass,01.vIBM.pULT3580-HH4" sgen
(adds sgen alias for IBM drive, model ULT3580-HH4)
# update_drv -a -i "scsiclass,01" sgen
(adds sgen alias for all drives attached to the system)
# update_drv -a -i "scsiclass,08.vIBM.pULT3581-TA2" sgen
(adds sgen alias for IBM changer, model ULT3581-TA2)
# update_drv -a -i "scsiclass,08" sgen
(adds sgen alias for all changers attached to the system)

5. Check that the drives and changers are now configured with the following
command:
# cfgadm -al

6. If the drives or changers are not listed in the output of cfgadm -al, reboot
the system and verify the list of configured devices with the command:
# cfgadm -al

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

223

Windows operating systems


After a firmware update, devices might disappear. This issue is a known Windows
problem.
See the Article ID: 812024 at http://support.microsoft.com/kb/812024/en-us.
Repeated Scan operations can help to rediscover the device.
When applications are turned on Windows while ITDT-SE is running, an extra ESC
character might appear on the input line. When this issue occurs, the input is
ignored after Enter is pressed.
If you are using Adaptec SCSI Host Bus adapters, ensure that you are using the
latest Adaptec Host Bus Adapter Drivers instead of the drivers that are shipped
with the Windows operating system.
On Microsoft Windows systems where the maximum transfer size is limited to less
than 64 kB, the Dump and Firmware Update operations do not work.

i5/OS operating systems


The Tape Drive must be varied online. If the tape drive is operated through a tape
library, the library must be varied offline. See Starting ITDT-SE on i5/OS
operating systems on page 221 for details.
As the library is varied offline, the Encryption Test does not deliver decrypted data
in a Library Managed Encryption environment.
IO adapters without a dedicated IOP do not support commands with 16 bytes.
These adapters are called IOP-less and can be identified with the command;
WRKHDWRSC *STG. Adapters where the CMBxxx and DCxxx resource names are the
same (like both 5774) are IOP-less. If it is IOP, then the CMBxxx is a different type
from the DCxxx.
Therefore, the following ITDT commands and test sequences can fail on IOP-less
adapters attached devices.
v Encryption Verification Test
v Physical Copy with more than one partition
v Erase command
v Change Partition command
v Read/write -attribute command
ITDT-SE on i5/OS V5R4 requires the following PTF installed.
v PTF: SI25023 Release: 540 Abstract: OSP-MEDIA-TAPE-THREADS-MSGCEE0200T/QTAHRMGR QTARDCAP FAILS
The [U] Tapeutil option is not available for i5/OS with this release as all the
underlying operations require the IBM Tape Device Driver to be installed.
FC 5912 SAS HBA support is only for POWER6 and V6R1 configurations that are
attached to LTO Gen 4 HH tape drives (No support for LTO 3 HH SAS).

224

IBM Tape Device Drivers Installation and Users Guide

All supported operating systems


This section describes the known issues and limitations of the ITDT-SE program on
all other supported operating systems.
Prevent/Allow Medium Removal is missing as a Tape Drive option. But, it can still
be completed by using the [56] Prevent/Allow Medium Removal option for tape
libraries while the tape device is opened.

User Interface issues


If you press the arrow keys on most UNIX operating system consoles, the input is
ignored after Enter is pressed.
When the Tab key is pressed as an input string for field data, the user interface is
corrupted.
Make sure that field input does not start with a number followed by space and
extra text. This input is interpreted as an entry to a specific row in the field. To
avoid this issue, use an underscore character ( _ ) instead of the space character.

Command timeout
There is no instant operation termination upon SCSI command timeout; for
example, when the SCSI cable is unplugged after POST A is started.
When a command timeout condition occurs, ITDT might still continue to complete
more operations (like unmounting the cartridge) instead of instantly terminating
with a timeout condition.

3576/TS3310 tape library


Library Firmware Update with ITDT-SE and ITDT-GE is not supported by the
3576/TS3310 library. Update the Firmware by using the 3576/TS3310 Web User
Interface.

3494 tape library


Drives in a 3494 tape library or an STK silo library are supported, only the [T]
Test option does not work because of device-specific restrictions for handling
cartridges.

Standard Edition - Start menu commands


After program startup, ITDT-SE displays the start screen menu.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

225

a2500231

Figure 30. Start screen menu

The following commands are available on the start screen menu:


v S - Scan for tape drives
Opens the screen for the Scan function (refer to Standard Edition - Scan menu
commands).
v U - Tapeutil
Opens the screen for the Tapeutil operation commands. These commands are the
standardized tapeutil functions with most of the options available that were
available with the previous tapeutil functions (refer to Standard Edition Tapeutil menu commands on page 245).
v A - Add Device Manually
Opens the screen for specifying a device manually instead of using the Scan
function.
v H - Help
Help starts and displays the available online help.
v Q - Quit
Quits the function.

Standard Edition - Scan menu commands


When ITDT-SE is used after S is entered on the Start screen, the Scan function
starts and displays the first device list screen. This screen contains the S, T, D, F,
E, W, U, O, V, and M commands. Entering the O command displays the second
device list screen. Entering the M command returns to the Start Screen menu.
Entering the V command toggles between displaying the physical device address
and the driver name.

226

IBM Tape Device Drivers Installation and Users Guide

a2500271

Figure 31. Scan menu

The following commands are described:


v S - Scan on page 228
v
v
v
v
v

T - Test on page 229


D - Dump on page 232
F - Firmware Update on page 233
E - Encryption on page 236
W - Full Write on page 238

a2500270

v U - Tape Usage on page 239


v O - Other on page 240

Figure 32. More scan options

v Y - System Test on page 240


Chapter 8. IBM Tape Diagnostic Tool (ITDT)

227

v
v
v
v
v

L - Library Test on page 242


I - Manual Inspect on page 242
R - Return on page 243
C - Config. TCP/IP on page 243
M - Automated Library Media Screening on page 244

v K - LTFS Readiness Check on page 245

Scan
The Scan function [S] is used to discover all supported tape and library devices
that are attached to the computer system so that they can be selected for the
subsequent ITDT-SE operations. The scan function also serves as a connection test
that can be used to verify correct attachment of the devices.
Make sure that no other program is accessing the devices that are used by
ITDT-SE. For example, stop the backup jobs that are accessing the devices when
ITDT-SE is used, or if not sure, stop the entire backup application.
After ITDT-SE is started, type S followed by Enter to activate the scan function.
Depending on the operating system and the number of attached drives, the scan
can take several minutes. See Standard Edition - known issues and limitations on
page 222 for details.
During the scan operation, a bar in the lower left edge of the screen shows that the
scan operation is still in progress.
When the scan is finished, the first device list screen is displayed.

Name of
current screen
If marked
with an
X, the
device is
selected

Device
number

Command
Prompt

a2500280

Command

Figure 33. Device List screen

The first device list screen shows all detected devices and the connection
information (host adapter number, bus number, SCSI/FCP ID, and LUN or driver
name) along with product data (Model name, Unit Serial number, Microcode
revision). For drives that are attached to a library, the Changer column shows the
serial number of the changer the drive is attached to.

228

IBM Tape Device Drivers Installation and Users Guide

Scrollable data is indicated by "VVVVVVVVV" at the bottom of the screen. To


scroll down to access non-displayed entries, type + and press the Enter key.
Note: For fast down scrolling, type + followed by a space and the number of lines
to scroll down then press Enter, or type N and press Enter to scroll down
one page.
To scroll back, use - instead of +.
Note: For fast up (backward) scrolling, type - followed by a space and the number
of lines to scroll up. Then, press Enter, or type P and press Enter to scroll up
one page.
If no devices appear or if devices are missing in the list, make sure that
v ITDT-SE is running with administrator/root rights.
v The devices are properly attached and powered on.
v Linux: The devices must be attached at boot time.
v i5/OS: Only tape drives are detected.
v Solaris, when no IBM tape device driver is in use:
Ensure that sgen is correctly configured.
file /kernel/drv/sgen.conf

is correctly configured (see Starting ITDT-SE on Solaris operating systems


on page 219).
Solaris 10, see (see Standard Edition - known issues and limitations on page
222)
v More than 12 devices displayed - scroll down the Device List.
ITDT-SE uses the IBM Tape Device Driver for its operations. If no IBM Tape Device
Driver is installed, the generic device driver for the operating system is used
instead. On Microsoft Windows, any Tape Device Driver that is installed is used.
If you must bypass the IBM Tape Device Driver for diagnostic purposes, start
ITDT-SE with the following command.
itdt -force-generic-dd

Note: For operating system-specific information on how to use this command, see
the corresponding Initial Startup sections.
When the wanted device is displayed, select the device for test. Only one device
can be selected.

Test
The Test function [T] checks if the tape device is defective and outputs a pass/fail
result.
Attention: The test function erases user data on the cartridge that is used for the
test.
For the library or autoloader test, the [L] library test must be selected.
Note:
1. The test can take from 15 minutes up to 2 hours.
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

229

2. The test runs only on tape drives, not on autoloaders or libraries.


To complete the test function, it is recommended that a new or rarely used
cartridge is used. Scaled (capacity-reduced) cartridges must not be used to test the
device.
To test tape drives within a library, the library must be in online mode.
1. Start ITDT-SE, then type S and press Enter to scan for the devices. Select the
device that you want to test by entering its number and press Enter.
2. Type T followed by Enter to activate the test.
If no cartridge is inserted, ITDT-SE prompts to insert a cartridge. Either insert a
cartridge and press Enter or stop the test by entering C followed by Enter.

a2500234

Note: If ITDT-SE detects data on the cartridge, the Device Test screen displays a
message (as shown in Figure 34.

Figure 34. Data Delete question

Type Y followed by Enter to continue the test if you are sure that data on the
cartridge can be overwritten. If you are unsure, type N followed by Enter to stop
the test.
During the test, the program shows a progress indicator in the form of a bar of
number signs (#) (1) that shows the progress of a single subtest and also a
description of that subtest. The user might stop the test by selecting the [A]Abort
option (exceptions: POST A, POST B).
During the test, a progress indicator (1) is shown on the test screen. Messages
from the test steps are shown in the Status field (2).

230

IBM Tape Device Drivers Installation and Users Guide

a2500235

Figure 35. Test running

The test sequence contains the following steps.


1. Initialize Device
2. Read Thermal Sensor (might get skipped)
3. Mount Medium
4. [Medium Qualification] - only if the previous step indicated this requirement
5. Load/Write/Unload/Read/Verify
6.
7.
8.
9.
10.

POST A
Performance Test (run 2 times if first run failed with performance failure)
Unmount Medium
Read Thermal Sensor (might get skipped)
Get FSC

11. Get Logs


The test can be stopped by typing A followed by Enter at any time except during
the POST tests, which are not interruptible.
Note: It might take some time until the test stops.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

231

a2500236

Figure 36. Test results

When all subtests are finished, ITDT-SE shows a screen that displays the
attachment and device information as in the first device list screen, together with
the test result and failure information in the code field. The screen also shows the
output files that were generated during the test run. The files might be requested
by the IBM Support Center.
If you want to use other ITDT-SE functions, type R followed by Enter to return to
the first device list screen. Otherwise, type Q followed by Enter to exit the
program.

Dump
Complete the following steps to start the Dump [D] process.
1. Start ITDT-SE, then type S and press Enter to scan for the devices.
2. Select the device that you want to retrieve a dump from by entering its number
and pressing Enter.
3. Type D and press Enter to start the dump retrieval for the selected device. The
ongoing dump process is completed (it takes less than 1 minute).

232

IBM Tape Device Drivers Installation and Users Guide

Log Filenames

a2500237

Dump Filenames

Figure 37. Dump

|
|

When the dump process is completed on a tape library or autoloader other than
the 3584/TS3500/TS4500, the Dump function stores 1 log file in the output folder
of the program (*.blz). For the 3584/TS3500/TS4500, a dump file (*.a) is stored in
the output folder.

|
|

Note: When the Dump function is completed for tape libraries or autoloaders
other than the 3584/TS3500/TS4500, the log file contains only Log Sense
and Mode Sense pages, while a Drive or 3584/TS3500/TS4500 dump
contains much more diagnostic information.
Retrieve the files from the ITDT-SE output subdirectory that was created during
the installation. The following are examples of the directory:
v Example output directory (Windows): c:\itdt\output
v Example output directory (UNIX): /home/user/itdt/output
v Example output directory (i5/OS): /home/itdt/output
(On the IFS) use FTP or the System i Navigator to transfer the file
If you want to use other ITDT-SE functions, type R followed by Enter to return to
the device list; otherwise, type Q followed by Enter to exit the program.

Firmware Update
The Firmware Update [U] upgrades the firmware of tape drives and tape libraries.
See Supported equipment on page 214 for a list of supported products.
Note: See 3576/TS3310 tape library on page 225 for information on how to
update the firmware on a 3576/TS3310 tape library.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

233

a2500251

Figure 38. Firmware Update screen

The following site is available for the latest firmware files: http://www.ibm.com/
systems/support/storage/tape
Download the files to the ITDT-SE input subdirectory that was created during the
installation. The following are examples of the directory:
Example input directory (Windows): c:\itdt\input
Example input directory (Unix): /home/user/itdt/input
Example input directory (i5/OS): /home/itdt/input
(on the IFS) use FTP or the i-Series Navigator to transfer the file

To do a Firmware Update, complete the following steps:


1. Start ITDT-SE, then type S and press Enter to scan for the devices.
2. Select the device that you want to update by typing the number of the device
and pressing Enter.
3. Type F and press Enter to display the Firmware Update screen.
4. To select the needed firmware update, complete one of the following steps:
v If the firmware file you downloaded is listed in the Content field of the
Firmware Update screen, type the corresponding line number and press
Enter.
v If the firmware file is stored in a directory other than the one in FW Dir,
type F followed by a space and the fully qualified path to the directory that
contains the firmware file, then press Enter.
For example, enter the following to change the firmware directory (UNIX):
f /home/user/firmware

v If no files are displayed in the Content field, check the Dir OK field on the
right side of the screen. It indicates true if the directory exists, false
otherwise.
v If the content of the displayed FW Dir changed, type D and press Enter to
refresh the directory content.

234

IBM Tape Device Drivers Installation and Users Guide

VVVVV = More data

a2500253

Note: The selected file name is reset to the first item (#0) after the Refresh
function is used.
v If the displayed directory contains more files than the files shown, type + and
press Enter to scroll down the list. For fast down scrolling type + followed
by a space and the number of lines to scroll down then press Enter. To scroll
back, use - instead of +.
Scrollable data is indicated by "VVVVVVVVVVVVVVVVV".

Figure 39. Scrollable Data screen

5. After the firmware file is selected, type C and press Enter to continue.
6. Before the firmware update is started, make sure the file that is displayed in
the FW File field is the correct file.
v If the correct file is displayed, proceed to the next step.
v If the correct file is not displayed, type C and press Enter to change the
selected firmware file. Go to Step 4.
Note: The selected file name is reset to the first item in the list when you
return to that dialog from the Start Update dialog.
7. If you decide to run the firmware update, type S and press Enter to start the
firmware update.
During the firmware update, a firmware update progress screen is displayed.
Attention: Once started, do not interrupt the firmware update.
The firmware update usually takes 3-5 minutes, but it can take up to 45
minutes for libraries. If you decide not to run the firmware update, type R and
press Enter to return to the Device List.
Note: If ITDT-SE detects a FIPS-certified drive firmware, it displays a warning
dialog. Before you continue, ensure that you use a FIPS-certified
firmware to update the drive.
8. After completion, the Status field on the lower right side indicates PASSED if
the firmware was updated successfully and FAILED otherwise.
Type R and press Enter to return to the Device List.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

235

Encryption
The Encryption [E] function is used to verify whether data on the cartridge was
written encrypted. It reads both decrypted and raw data from the cartridge into
two separate files on disk. The user can then verify that the data differs to ensure
that encryption worked.
The Encryption function does not provide a Write - Read test.
The Encryption function is supported only on encryption enabled drives. It
requires that an encryption infrastructure, including the Encryption Key Manager
(EKM), is properly set up. An encrypted data cartridge must be used.
The Encryption function is supported for the following encryption environments:
v System Managed: IBM tape device driver must be installed and in use by ITDT
to read decrypted data
v Library Managed
v Application Managed: Only raw encrypted data is read (result file *.ENC)
Note: On i5/OS, media changers and media changer operations are not supported
by this release of ITDT-SE. To test a tape drive inside a library, the tape
drive must be varied online and the tape library must be varied offline (see
Starting ITDT-SE on i5/OS operating systems on page 221 for details). As
the library is varied offline, the Encryption function does not deliver
decrypted data in a Library Managed Encryption environment.
1. After ITDT-SE is started, type S followed by Enter to activate the device scan.
2. Select the device that you want to test by entering its number and press Enter.
Type E and press Enter to start the encryption test.
3. ITDT-SE then switches to the Encryption Verification screen. On this screen,
the system requires the entry of the number of the start record and the amount
of data (in KB) to be read.
4. Type S followed by a space and the start record number, then press Enter to
enter the start record number. Type L followed by a blank and the data length,
then press Enter to enter the data length, maximum 100000 KB.

236

IBM Tape Device Drivers Installation and Users Guide

a2500245

Figure 40. Encryption Start screen

5. If you entered the values correctly, press Enter to start the encryption.
During the encryption, the program shows a progress indicator in form of a bar
of number signs (#) that shows the progress of a single subtest and information
about that subtest.
The Encryption function can be stopped by typing A followed by Enter at any
time.
Note: It can take some time before the Encryption function stops.
If all encryption operations are finished, ITDT-SE shows a screen that displays the
Status field on the lower left side that indicates PASSED if the encrypted test
completed successfully and ABORTED otherwise.
The screen also shows the output files that were generated during the Encryption
function:
v file serial# .n.ENC contains the raw encrypted data
v file serial# .n.DEC contains the decrypted data
Table 53 defines the abort codes.
Table 53. Abort code definitions
ABORT CODE

ROOT CAUSE

LOCATE FAILED

Start position as requested by the user was not reached

MEDIUM NOT ENCRYPTED

ITDT detected medium as non-encrypted

NO DRIVER SPECIAL FILE

System-Managed environment, but generic device file


is used instead of IBM device driver special file

DRIVE ENCRYPTION DISABLED Mode Sense detected disabled drive encryption


UNEXPECTED DATA

v Set Raw read mode failed


v One of the commands failed

END OF MEDIUM

End of medium that is encountered before the


specified amount of data was read

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

237

Table 53. Abort code definitions (continued)


ABORT CODE
END OF DATA

ROOT CAUSE
End of data that is encountered before the specified
amount of data was read

READ FAILED
ENCRYPTION ERROR
INVALID PARAMETER

User entered data length of 0 kB

If you want to use other ITDT-SE functions, type R followed by Enter to return to
the device list. Otherwise, type Q followed by Enter to exit the program.

Full Write
The Full Write [F] function writes the entire cartridge with a specified block size
either with compressible or incompressible data and output performance data.
Attention: The Full Write function erases data on the cartridge that is used for
the test.
Note:
1. The Full Write function takes approximately 2 hours when
incompressible data is written, less time for compressible data.
2. The Full Write function runs only on tape drives, not on autoloaders or
libraries.
The Full Write test can be used to
v Demonstrate that the drive can write the full amount of data on a cartridge.
v Identify system issues with compression.
Drive data compression is always turned on during the full write. When run
with compressible data, the output shows the compression rate. If the
compression rate is higher than 1.0 but the system does not appear to be able to
compress data on the cartridge, check the device driver and software settings to
see whether they disable compression.
1. After ITDT-SE is started, type S followed by Enter to activate the device scan.
2. Select the device that you want to write to by entering its number and press
Enter. Type W and press Enter to start the full write.
ITDT-SE then switches to the Full Write screen. If no cartridge is inserted,
ITDT-SE prompts to insert a cartridge. Either insert a cartridge and press Enter
or stop the test by typing C followed by Enter.
Note: If ITDT-SE detects data on the cartridge, it shows the Full Write screen,
and displays the following message:
Cartridge not empty!
Overwrite data?

Type Y followed by Enter to continue the test if you are sure that data on
the cartridge can be overwritten. If you are unsure, type N followed by
Enter to stop the test.
3. The system prompts for entry of a transfer size between 16 KB and the
maximum block size that is supported by the system (maximum value is 512

238

IBM Tape Device Drivers Installation and Users Guide

KB). This action is a check for the type of supported block size that is
completed. Enter the appropriate values for your system.
4. Select the type of data to write, either [C] Compressible or [I] Incompressible.
During the full write, the program shows a progress indicator in form of a bar
of number signs (#) that shows the progress of the full write.
The full write can be stopped by typing A followed by Enter at any time.
Note: It can take some time until the full write stops.
If all write operations are finished, ITDT-SE shows a screen that displays the
compression ratio (1) and the write performance (shown in 2 as the Data
Rate) for the selected block size. If an error occurred during the full write, data
is only written partially.
"Compressible = Yes" means that the data written was just zeros so that the
data is compressed by the drive with a maximum compression ratio.
"Compressible = No" means that a data pattern was written that the drive
almost cannot compress at all. If the compression ratio is 1, the drive was not
able to compress the data (equivalent to 1:1 compression ratio). If the
compression ratio is 94.0, the drive was able to do 94:1 compression, meaning
that 94 bytes in the original data is compressed to 1 byte on the medium. 100.0
means 100 bytes is compressed down to 1 byte on the medium.
If you want to use other ITDT-SE functions, type R followed by Enter to return
to option 4 the device list. Otherwise, type Q followed by Enter to exit the
program.
2

a2500243

Figure 41. Full Write results

Tape Usage
The Tape Usage [U] function retrieves statistical data and error counters from a
cartridge.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

239

a2500244

Figure 42. Tape Usage screen

1. After ITDT-SE is started, type S followed by Enter to activate the device scan.
2. Select the device that you want to test by entering its number and press Enter.
3. Type U followed by Enter to start the tape usage log retrieval. ITDT-SE then
switches to the tape usage screen. If no cartridge is inserted, ITDT-SE prompts
to insert a cartridge. Either insert a cartridge and press Enter or stop the test by
entering C followed by Enter.
During the get logs operation, the program shows a progress indicator in form of a
bar of number signs (#) that shows the progress of a single suboperation and a
description of that operation.
If all suboperations are finished, ITDT-SE shows a Tape Usage completion screen.
The Status field on the lower right side indicates PASSED if the log retrieval
completed successfully and ABORTED otherwise.

Other
Other [O] - type O followed by Enter to display a screen with the following
commands:
v Y - System Test
v L - Library Test on page 242
v
v
v
v
v

I - Manual Inspect on page 242


R - Return on page 243
C - Config. TCP/IP on page 243
M - Automated Library Media Screening on page 244
K - LTFS Readiness Check on page 245

System Test
The System Test [Y] is a short test that completes the following steps:
v Reveals system performance bottlenecks. Compressible data throughput values
can reveal bandwidth limitations that are caused by the system, cabling, or HBA.
v Measures performance variations across the different block sizes to find the ideal
block size for the system configuration.

240

IBM Tape Device Drivers Installation and Users Guide

The System Test runs only on tape drives, not on autoloaders or libraries. To
complete a System Test on tape drives within a library, the library must be in
online mode.
1. Start ITDT-SE, type S, and press Enter to scan for the devices.
2. Type O and press Enter to display the second device list screen.
3. On the second device list screen, type Y and press Enter to start the System
Test.
ITDT-SE then switches to the System Test screen. If no cartridge is inserted,
ITDT-SE prompts to insert a cartridge. Either insert a cartridge and press Enter
or stop the test by typing C followed by Enter.
Note: If ITDT-SE detects data on the cartridge, it shows the System Test screen,
and displays the following message.
Cartridge not empty!
Overwrite data?

Type Y followed by Enter to continue the test if you are sure that data on
the cartridge can be overwritten. If you are unsure, type N followed by
Enter to stop the test.
The System Test is completed as follows:
a. System Test determines the amount of data to write for each supported
blocksize (a percentage of the cartridge is written for each blocksize).
b. The test determines the maximum supported blocksize of the system.

a2500245

c. System Test writes the amount of data with all supported block sizes in
powers of two down to 16 KB. It begins with the maximum supported
blocksize that was detected before, first with incompressible, next with
compressible data, and then performance data and a progress screen.
d. At the end of the test, a summary screen is displayed.

Figure 43. System Test results

Compressible = Yes" means that the data written was just zeros so that the data
is compressed by the drive with a maximum compression ratio. "Compressible
= No" means that a data pattern was written that the drive almost cannot
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

241

compress at all. If the compression ratio is 1, the drive was not able to
compress the data (equivalent to 1:1 compression ratio). If the compression
ratio is 94.0, the drive was able to do 94:1 compression, meaning that 94 bytes
in the original data is compressed to 1 byte on the medium. 100.0 means 100
bytes is compressed down to 1 byte on the medium.The System Test can be
stopped by typing A followed by Enter at any time.
Note: It can take some time until the System Test stops.
If you want to use other ITDT-SE functions, type R followed by Enter to return to
the device list. Otherwise, press Q followed by Enter to exit the program.

Library Test
The Library Test [L] starts and monitors the library-internal self-test. This test runs
only on libraries and autoloaders, not on tape drives.
1. Start ITDT-SE, type S, and press Enter to scan for the devices.
2. Type O and press Enter to display the second device list screen.
3. On the second device list screen, type L and press Enter to start the Library
Test.
A Device Test screen is displayed and a functionality test on the tape library is
completed.
At the end of the test, a results screen is displayed.
The Library Test can be stopped by typing A followed by Enter at any time.
Note: It can take some time until the Library Test stops.
If you want to use other ITDT-SE functions, type R followed by Enter to return to
the device list; otherwise press Q followed by Enter to exit the program.

Manual Inspect
Manual Inspect [I] creates a manual inspection record if a device does not appear
in the device list. This test is intended for devices that are not recognized or have a
technical problem that cannot be determined by ITDT-SE.
If a tape drive cannot be identified by using a device scan, the user can manually
create a test record for the drive. The system prompts for the user to run the
SCSI/FC Wrap test for the drive (see the service manual for the drive). The results
of the wrap test can be entered along with extra inspection information. The results
are saved into binary and text output files that have the same format as the output
files generated by the test.
1. Start ITDT-SE, type S, and press Enter to scan for the devices.
2. Type O and press the Enter key to display the second device list screen.
3. On the second device list screen, type I and press Enter to open the Manual
Inspection screen.
4. On the next screen, type M followed by a space and the model name and press
Enter. For example: M ULT3580-TD1
5. Enter the required information to complete the items in the screen:
a. Type N followed by a space and the serial number and press Enter.
b. Type T followed by a space and the content of the Message Display and
press Enter.

242

IBM Tape Device Drivers Installation and Users Guide

c. Optionally, type A followed by a space and extra information text and press
Enter.
6. After all information is entered, type S and press Enter to save the data.
The information is stored in a binary file (which can be used for further
analysis), and in a human-readable text file. Both files are stored in the ITDT-SE
output folder.
If you want to use other ITDT-SE functions, type R followed by Enter to return to
the first device list screen. Otherwise, press Q followed by Enter to exit the
program.

Return
Return [R] - type R followed by Enter to go back to the first device list screen.

Config. TCP/IP
|

|
|

Configure TCP/IP [C] configures the ethernet port settings of LTO 5, LTO 6,,
TS1140, and TS1150 drives. For those drives, the current settings are read and
displayed and can be changed.
Note: LTO 5 and LTO 6 drives have one port and TS1140 and TS1150 drives have
two ports that can be configured. Configuring the ethernet ports must not
be done in a TS3500/TS4500. Although the ports can be configured, it is
ineffective.
1. Start ITDT-SE, type S, and press Enter to scan for the devices.
2. Select a device from the list (just the ones that are listed are supported) by
entering the number, then press Enter.
3. Type O and press Enter to display the second device list screen.
4. On the second device list screen, type C and press Enter to open the Configure
TCP/IP screen.
ITDT-SE switches to the Configure TCP/IP screen and reads the data configuration
of port 1. To toggle between port 1 and 2, type P and press Enter.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

243

a2500281

Figure 44. TCP/IP screen: Read data

but
Each parameter can be set by entering the number (1 - 5) and a following value. If
you want to enable DHCP, enter '1 1' and press Enter. The value of the DHCP
field is refreshed with the value entered.
The values for both ports are applied to the drive by entering A and pressing
Enter. ITDT-SE configures the drive and the current active addresses are shown in
the field: Active IP Addresses. Regular field values:
[1]
[2]
[3]
[4]
[5]

DHCP enabled:
Address IPV4
Subnet Mask Length V4:
Address IPV6:
Subnet Mask Length V4:

0/1 (false/true)
Regular IPv4 address
0...23
Regular IPv6 address
0...127

If you want to use other ITDT-SE functions, type R, then press Enter to return to
the device list. Or, press Q and Enter to exit the program.

Automated Library Media Screening


The Automated Library Media Screening test generates dumps for each drive and
cartridge within a library. It runs only on libraries (except TS3500/TS4500) and
auto-loaders, not on tape drives.

First, the test tries to read dump files from each drive that is installed from the
library. After that, the customer must select one drive for loading the cartridges.
All cartridges of the I/O and storage slots are moved - one after the other - from
their source to the selected drive. A dump is taken and moved back to the source
address.
In the result screen, the dumps taken and the count of dumps is displayed.

244

IBM Tape Device Drivers Installation and Users Guide

LTFS Readiness Check


The LTFS Readiness Check analyzes the operating system and tape drive
environment to ensure that the IBM linear tape file system can be installed. This
test checks the operating system version, the tape device driver version, the tape
drive firmware, and the LTFS HBA requirements.

Note: The tape drive firmware must be at least version: C7RC (for LTO 5), C974
(for LTO 6), and 36A5 (for Jaguar E07 and E08). The LTFS Readiness Check
requires an empty data cartridge.
The LTFS Readiness Check can return with result FAILED and one of the following
error codes.
Table 54. Codes and root causes
Code

Root causes

LOCATE FAILED

Start position as requested by the user could


not be reached

MEDIUM NOT ENCRYPTED

Mode Sense detected medium as


non-encrypted

NO DRIVER SPECIAL FILE

System-managed AIX environment, but


/dev/rmt device not found

DRIVE ENCRYPTION DISABLED

Mode Sense detected disabled drive


encryption

UNEXPECTED DATA

v Set Raw read mode failed


v System-managed but not AIX

END OF MEDIUM

End of medium that is encountered before


the specified amount of data could be read

END OF DATA

End of data that is encountered before the


specified amount of data could be read

DRIVE NOT ENCRYPTION CAPABLE

Drive is not encryption capable

Standard Edition - Tapeutil menu commands


When the user runs the U command on the ITDT-SE start screen, the Tapeutil
operation screen is displayed.
Note: On any screen, to start a command, press the shortkey displayed in brackets
[ ], followed by Enter.
The following commands are described in this section:
v [1] Open a Device on page 246
v [2] Close a Device on page 248
v [3] Inquiry on page 248
v [4] Test Unit Ready on page 248
v [5] Reserve Device on page 248
v [6] Release Device on page 248
v [7] Request Sense on page 248
v [8] Log Sense on page 248
v [9] Mode Sense on page 248
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

245

v
v
v
v
v

[10] Query Driver Ver. (Version) on page 249


[11] Display All Paths on page 249
[12] Query Runtime Info on page 249
[20] Rewind on page 249
[21] Forward Space File Marks on page 249

v
v
v
v
v
v
v

[22]
[23]
[24]
[25]
[26]
[27]
[28]

Backward Space File Marks on page 249


Forward Space Records on page 249
Backward Space Records on page 249
Space to End of Data on page 249
Read and Write Tests on page 250
Read or Write Files on page 250
Erase on page 250

v
v
v
v
v
v

[29]
[30]
[31]
[32]
[33]
[34]

Load Tape on page 250


Unload Tape on page 251
Write File Marks on page 251
Synchronize Buffers on page 251
Query/Set Parameter on page 251
Query/Set Tape Position on page 251

v [35] Query Encryption Status on page 251


v [36] Display Message on page 251
v [37] Report Density Supp (Support) on page 252
v
v
v
v

[38]
[39]
[50]
[51]

Test Encryp. Path (Test Encryption Key Path/Setup) on page 252


Configure TCP/IP Port on page 252
Element Information on page 253
Position to Element on page 254

v
v
v
v

[52]
[53]
[54]
[55]

Element Inventory on page 254


Exchange Medium on page 254
Move Medium on page 254
Initialize Element Status on page 254

v
v
v
v

[56]
[57]
[58]
[59]

Prevent/Allow Medium Removal on page 254


Initialize Element Status Range on page 255
Read Device IDs on page 255
Read Cartridge Location on page 255

v [70] Dump/Force Dump/Dump on page 255


v [71] Firmware Update on page 255
v [101] HDP Discover on page 256
v [102] HDP Initiate Call Home on page 256
v [103] HDP Show Import Export Elements on page 256

[1] Open a Device


When you select the Open a Device command [1]:
1. ITDT checks if a device is already opened.
2. You are prompted for a device special file name.
3. You are prompted for an open mode (rw, ro, wo, append).
4. ITDT opens the device that you selected.

246

IBM Tape Device Drivers Installation and Users Guide

Note: Always use the Read Only mode when you are working with
write-protected media.
The combination of open cmd with parameter -force-generic-dd is not supported.

Device file names - device addressing


ITDT supports generic and Device Driver claimed devices. This section shows
examples for device names (addressing) of all supported platforms. The used
abbreviations stand for:
host

Number of the host adapter (SCSI, FC, SAS)

bus

Number of the bus from the host adapter

target

Target Number of the device

lun

Logical Unit Number of the device that is separated with blanks.

Note: The correct IDs are reported in the ITDT Control Center after a scan or with
the scripting function "scan".
Table 55. Device addressing
IBM Tape
Device Driver
IBM AIX

Generic IDs separated with


blanks

Generic (alternative, as a
result from ".itdt scan")

<host><bus><target><lun>

H<host>-B<bus>T<target>-L<lun>

/dev/rmtX.Y
/dev/smcX

Linux

/dev/IBMtapeX
/dev/
IBMchangerX

Microsoft
Windows

\\.\tape0
\\.\changer0

Oracle Solaris /dev/rmtXsmc


/dev/smc/
Xchng
HP-UX

/dev/rmt/
Xmnb
/dev/rmt/
Xchng

Apple Mac

H<host>-B<bus>T<target>-L<lun>
<host><bus><target><lun>

tapeX
changerX

IBM 'i'

Device Name; for


example, TAP01

Example for Windows:

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

247

C:\tmp\itdt.exe scan
Scanning SCSI Bus ...
#0 \\.\Tape4 - [03592E06]-[2471] S/N:000012345678 H2-B0-T3-L0
Exit with code:0
C.\tmp

For a device that uses the IBM device driver, the call might look like \\.\Tape4,
and for a generic device on Windows 2 0 3 0.

[2] Close a Device


When you select the Close a Device command [2]:
1. ITDT checks if the device is already closed.
2. ITDT closes the device.

[3] Inquiry
When you select the Inquiry command [3]:
1. You are prompted for page code.
2. ITDT then displays a decoded format of a hexadecimal dump and prints a
hexadecimal dump of the inquiry data.

[4] Test Unit Ready


When you select the Test Unit Ready (TUR) command [4], ITDT issues the Test
Unit Ready ioctl command.

[5] Reserve Device


When you select the Reserve Device command [5], ITDT issues a reserve
command for the device.

[6] Release Device


When you select the Release Device command [6], ITDT issues a release command
for the device.

[7] Request Sense


When you select the Request Sense command [7]:
1. ITDT issues a Request Sense command.
2. ITDT then displays a decoded format of hexadecimal dump sense data and
prints hexadecimal dump sense data.

[8] Log Sense


When you select the Log Sense command [8]:
1. You are prompted for Log Sense Page.
2. ITDT issues a mode sense command.
3. ITDT completes a hexadecimal dump page.

[9] Mode Sense


When you select the Mode Sense command [9]:
1. You are prompted for Mode Sense Page.
2. ITDT issues mode sense command.

248

IBM Tape Device Drivers Installation and Users Guide

3. ITDT completes a hexadecimal dump page.

[10] Query Driver Ver. (Version)


When you select the Query Driver Version command [10]:
1. ITDT issues the required command to get the driver version.
2. ITDT prints the driver version.

[11] Display All Paths


When you select the Display All Paths command [11]:
1. ITDT issues an ioctl command.
2. ITDT outputs decoded path information for all paths.

[12] Query Runtime Info


When you select the Query Runtime Info command [12]:
1. ITDT issues the required command to get the runtime info.
2. ITDT prints out the Dynamic Runtime Attribute Values.

[20] Rewind
When you select the Rewind command [20], ITDT issues the ioctl rewind command
for the device.

[21] Forward Space File Marks


When you select the Forward Space File Marks command [21]:
1. You are prompted for the number of file marks to space forward.
2. ITDT issues (extrinsic) ioctl command.

[22] Backward Space File Marks


When you select the Backward Space File Marks command [22]:
1. You are prompted for the number of file marks.
2. ITDT issues (extrinsic) ioctl command.

[23] Forward Space Records


When you select the Forward Space Records command [23]:
1. You are prompted for the number of records to space forward.
2. ITDT issues (extrinsic) ioctl command.

[24] Backward Space Records


When you select the Backward Space Records command [24]:
1. You are prompted for the number of records to space backward.
2. ITDT issues (extrinsic) ioctl command.

[25] Space to End of Data


When you select the Space to End of Data (EOD) command [25], ITDT issues the
(extrinsic) ioctl command.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

249

[26] Read and Write Tests


When you select the Read and Write Tests command [26]:
v You are prompted for block size (If you press Enter, the default block size is
10240 bytes).
Note: If the block size is zero, variable mode is used. With a fixed block size, a
data amount of (block size * blocks) is transferred with a single operation.
This process can get rejected if the total amount exceeds the transfer size
the system can handle.
v You are prompted for the number of blocks per read/write (If you press Enter,
the default number of blocks is 20).
v You are prompted for the number of repetitions (If you press Enter, the default
number of repetitions is 1).
You can then select one of the following options:
v Read data from tape (to run Read only test)
v Write data to tape (to run Write-only test)
v Write/Read/Verify (to run Read and Write test)
ITDT runs the selected test. Then, it displays the transfer size and block size that is
used for this test, the number of records read/written, and the total bytes
transferred.

[27] Read or Write Files


When you select the Read or Write Files command [27]:
v You are prompted to specify the file name of the source file (for Write test) or
the destination file (for Read test).
v You are prompted for the number of records to be read.
You can then select one of the following options:
v Read File from Tape: ITDT reads a file from tape and stores data into a file with
the specified file name.
v Write File to Tape: ITDT reads data from file with the specified file name and
writes data to tape.
ITDT displays the number of records read/written, the transfer size, and the total
bytes transferred.

[28] Erase
When you select the Erase command [28], ITDT issues the (extrinsic) ioctl
command to erase the cartridge.
For more information, refer to the Tapeutil Scripting Command at .

[29] Load Tape


When you select the Load Tape command [29], ITDT issues the load tape
command.

250

IBM Tape Device Drivers Installation and Users Guide

[30] Unload Tape


When you select the Unload Tape command [30], ITDT issues the unload tape
command.

[31] Write File Marks


When you select the Write File Marks command [31]:
1. You are prompted for the number of file marks to write.
2. ITDT issues the (extrinsic) ioctl command.

[32] Synchronize Buffers


When you select the Synchronize Buffers command [32], ITDT issues the ioctl
command.

[33] Query/Set Parameter


When you select the Query/Set Parameter command [33]:
1. ITDT displays non-changeable parameters.
Note: The list of non-changeable parameters is operating system specific.
2. ITDT displays changeable parameters.

3.
4.
5.
6.

Note: The list of changeable parameters is operating system specific. For a list
of changeable parameters, refer to .
You are prompted for parameter to change.
ITDT requests prompt for parameter value (if required).
ITDT requests safety prompt (if required).
ITDT issues the ioctl command.

[34] Query/Set Tape Position


When you select the Query/Set Tape Position command [34]:
1. ITDT displays the current position
2. You are prompted for a new position to set.
3. ITDT issues the Set Position ioctl command.

[35] Query Encryption Status


When you select the Query Encryption Status command [35]:
1. ITDT issues Get Encryption State ioctl command.
2. ITDT displays encryption settings (Encryption capability, Encryption method,
Encryption state).

[36] Display Message


When you select the Display Message command [36]:
1. You are prompted for the text of message 0 (8 characters or less).
2. You are prompted for the text of message 1 (8 characters or less).
3. You are prompted for message type (msg0, msg1, flash0, flash1, alt).
4. ITDT issues the Display Message ioctl command.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

251

Not all drives have a display. The 3592 drive is the only one that has display
message capability. It is the only one with a display that is more than one character
long. Eight is the limit of the characters on a display screen.

[37] Report Density Supp (Support)


When you select the Report Density Support command [37]:
1. ITDT prints report status text for all supported media.
2. ITDT issues Report Density Support ioctl command to retrieve all supported
media.
3. ITDT prints all requested reports. Data is printed in a decoded way. Scroll the
screen to print each one of the following information:
v Density name
v Assigning organization
v Description
v Primary density code
v Secondary density code
v Write OK
v Duplicate
v
v
v
v
v

Default
Bits per MM
Media Width
Tracks
Capacity (megabytes).

4. ITDT prints report status text for current media


5. ITDT issues Report Density Support ioctl command to retrieve current media
6. ITDT prints report data in a decoded way.

[38] Test Encryp. Path (Test Encryption Key Path/Setup)


When you select the Test Encryption Key Path/Setup command [38]:
Note: Not supported for the HP-UX operating system.
1. ITDT prints status message that server configuration and connections are tested
2. ITDT issues the Encryption Diagnostics ioctl command, Ping Diag
3. ITDT prints number of servers available or error message
4. ITDT issues the Encryption Diagnostics ioctl command, Basic Encryption
Diag
5. ITDT prints completion code or error message
6. ITDT issues the Encryption Diagnostics ioctl command, Full Encryption Diag
7. ITDT prints completion code or error message.

[39] Configure TCP/IP Port


For LTO 5, LTO 6, TS1140, and TS1150 drives, the ethernet port settings can be
configured with the Configure TCP/IP Port command. The Configure TCP/IP Port
command displays the current settings:

252

IBM Tape Device Drivers Installation and Users Guide

dd000009

Figure 45. TCP/IP Port command

dd000010

You can change any of the settings by stepping through each parameter - press
Enter. To change a parameter, enter the new value, then press Enter. All data is
sent to the drive and the following screen display is shown:

Figure 46. TCP/IP Port command results

Note: Because earlier drive generations do not have an ethernet port, the
Configure TCP/IP Port command is rejected for these devices with the
following message:
TCP/IP configuration is not supported on this product.

[50] Element Information


When you select the Element Information command [50]:
1. ITDT issues the ioctl command
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

253

2. ITDT displays the


v Number of robots
v First robot address
v Number of slots
v First slot address
v
v
v
v

Number of I/E elements


First element address
Number of drives
First drive address

[51] Position to Element


When you select the Position to Element command [51]:
1. You are prompted for destination address
2. ITDT issues the ioctl command.

[52] Element Inventory


When you select the Element Inventory command [52]:
1. ITDT issues the Element Info ioctl command.
2. ITDT issues the Element Inventory ioctl command.
3. ITDT displays decoded element inventory information. Type n followed by
Return to show the next page of information.

[53] Exchange Medium


When you select the Exchange Medium command [53]:
1. You are prompted for source address.
2. You are prompted for first destination address.
3. You are prompted for second destination address.
4. ITDT issues the ioctl command.

[54] Move Medium


When you select the Move Medium command [54]:
1. You are prompted for source address.
2. You are prompted for destination address.
3. ITDT issues the ioctl command.

[55] Initialize Element Status


When you select the Initialize Element Status command [55]:
1. ITDT prints the command summary.
2. ITDT issues the ioctl command.

[56] Prevent/Allow Medium Removal


When you select the Prevent/Allow Medium Removal command [56]:
1. You are prompted to select (1) for Prevent Removal, or (0) for Allow Removal.

254

IBM Tape Device Drivers Installation and Users Guide

[57] Initialize Element Status Range


When you select the Initialize Element Status Range command [57]:
1. You are prompted for the first slot address.
2. You are prompted for the number of slots.
3. ITDT issues the ioctl command.

[58] Read Device IDs


When you select the Read Device IDs command [58], ITDT retrieves the device ID
information for all available drives and displays the information. Type n followed
by Enter to show the next page.

[59] Read Cartridge Location


When you select the Read Cartridge Location command [59]:
1. You are prompted for the address of the first slot.
2. You are prompted for number of elements.
3. ITDT verifies that the specified address range is valid, otherwise prints error
message and exit.
4. ITDT issues the Read Cartridge Location ioctl command.
5. ITDT issues the Element Info ioctl command.
6. ITDT verifies that the address range is valid; otherwise, print the error message
and exit.
7. If no slots are found in Element Info data, print the error message and exit.
8. ITDT issues the Read Cartridge Location ioctl command.
9.

ITDT prints decoded storage element information, Type n followed by Enter to


show next page.

[70] Dump/Force Dump/Dump


When you select the Dump/Force Dump/Dump command [70]:
v ITDT retrieves the dump.
v ITDT issues the Force Dump command.
v ITDT retrieves second dump.
v ITDT displays the name of stored dump files and the output directory where
they are stored. The dump file names start with the serial number of the device.

[71] Firmware Update


When you select the Firmware Update command [71]:
1. ITDT displays the default input directory where the firmware files must be
stored. The following are examples of the directory:
v Example input directory (Windows): c:\itdt\input
v Example input directory (UNIX): /home/user/itdt/input
2. You are prompted to specify a different input directory if required, or to press
Enter to keep the standard ITDT directory.
3. You are prompted to specify the firmware file name and press Enter to start.
4. ITDT runs firmware update and displays progress status and result.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

255

Note: See 3576/TS3310 tape library on page 225 for information on how to
update the firmware on a 3576/TS3310 tape library.
The following site is available for the latest firmware files:
http://www.ibm.com/storage/lto.

[101] HDP Discover


Discover the configuration of the HD-P system of all attached libraries - just
TS3500/TS4500. The function scans the host for attached TS3500/TS4500 devices
and uses their data to discover the HD-P system.

If it is successful, it delivers two maps that represents the logical and physical
HD-P environment.
The logical map is a representation of the libraries, where a 1 is the indicator for
a connection and a -1 of no connection.
Command Result
+-----------------------------------------------------------------------------+
| Shuttle Call System discover.....
|
| Scanning devices.....
|
| .....DeviceFileName:/dev/smc1
SN:0000013AAA160404
|
|
|
| Discovering Libraries......
|
| .....Passed
|
|
|
| Connection Map:
|
| LL01: /dev/smc1
|
|
|
|
LL01
|
| LL01 -1
|
|
|
| Physical Map:
|
|
|
|
|
| SCS Discover passed
|
|
|
|
|
|
|
+-----------------------------------------------------------------------------+
< [Q] Quit | [N] Next| [P] Previous | + | - | [Enter] Return >

Supported platforms: AIX, Linux on P, and X64


Note: Mixed Media environments (3592 and LTO) are not supported.

[102] HDP Initiate Call Home


Issuing a Test Call Home function.
Supported platforms: AIX, Linux on P, and X64

[103] HDP Show Import Export Elements


Shows the extended HD-P Import Export Elements.
Supported platforms: AIX, Linux on P, and X64

256

IBM Tape Device Drivers Installation and Users Guide

Standard Edition - Program options


For problem determination and customization, ITDT is providing the following
command line options.
-h help
Prints help information
-version
Displays the version of ITDT,
used configuration files and creation dates.
-force-generic-dd
the usage of the generic Operating System driver
(not using the IBM Tape Device driver)will be forced.
-LP logpath
Use logpath as logging path (default: output)
-L logfile
Use logfile for log messages (default: metro.log)
-LL Errors|Warnings|Information|Debug
Set log level (default: Error)
-R resultdir
Use resultdir as result file path (default: output)

Standard Edition - Tapeutil scripting commands


Scripting is enabled with the 4.0 release of ITDT SE. ITDT-SE provides
compatibility with earlier versions for existing tapeutil scripts. While some legacy
commands exist, they are not documented in their entirety as they are phased out
over time. New scripts must always use the scripts that are listed in this guide, the
Common Command set (CS). Also, existing scripts must be modified for forward
compatibility with ITDT.
You can find a list of commands, on each command you find the command, a
description, parameter list, and which platforms are supported. Some commands
have numbers after them. The numbers mean that a corresponding menu
command is in Standard Edition - Tapeutil menu commands on page 245.
The calling convention for the Common Command set is
itdt -f filename [Open Mode] Subcommand [Subcommand ...]

Note: "filename" is a device special file for the drive/changer or the device
address (host bus target lun). For a complete list of the file name or address
syntax, refer the section "Special Files" on each platform or go to Device file
names - device addressing on page 247.
The Open Mode flag is supported on all platforms. If the flag is not set, the device
is opened in read/write mode. More parameters that might be required for
opening the device are automatically detected and set.
-w mode
Open mode, by default Read/Write.
Valid modes are:
1 = Read/Write
2 = Read Only
3 = Write Only
4 = Append

Note: Always use the Read Only mode when you are working with
write-protected media.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

257

The new command set enables legacy commands on every platform, even if that is
not previously supported by Tapeutil. The output follows current Tapeutil
conventions. But, if different output displays for a single command on various
platforms, the output is implemented according to the AIX output as the primary
scripting platform.
Tapeutil allows undocumented abbreviations for some of the commands. For
example, it was possible to shorten inquiry to inq or inqu or inqui. The
following command abbreviations are supported by ITDT-SE too: inq(uiry),
req(sense), pos(ition), ele(mentinfo), inv(entory), devid(s), cartridge(location).
Deprecated commands are listed at Deprecated commands on page 281. Also,
there is a list of unsupported commands and known exceptions at Standard
Edition scripting commands: known limitations and deviations on page 283.
The following commands are described.
General commands
v
v
v
v

allow on page 260


devinfo on page 260
inquiry on page 260
logpage on page 260

v
v
v
v
v
v

loop on page 261


modepage on page 261
prevent on page 261
print on page 261
qrypath on page 261
qryversion on page 262

v
v
v
v

release on page 262


reqsense on page 262
reserve on page 262
scan on page 262

v sleep on page 263


v tur on page 264
v vpd on page 264
Tape commands
v append on page 264
v bsf on page 264
v bsr on page 264
v chgpart on page 265
v
v
v
v
v
v
v

density on page 265


display on page 265
erase on page 265
fdp on page 266
fdpl on page 266
fsf on page 266
fsr on page 266

v getparms on page 266

258

IBM Tape Device Drivers Installation and Users Guide

v
v
v
v
v

idp on page 267


idpl on page 267
list on page 268
load on page 268
logsense on page 268

v
v
v
v
v
v
v

qrypar/qrypart on page 268


qrylbp on page 268
qrypos on page 269
qrytcpip on page 269
read on page 269
resetdrive on page 269
rmp on page 270

v
v
v
v
v
v

runtimeinfo/qryruntimeinfo on page 270


rewind on page 270
rtest on page 270
rwtest on page 270
sdp [0|1|2|3] on page 271
sdpl [0|1] on page 271

v seod on page 271


v setparm on page 271
v setpos on page 272
v
v
v
v

settcpip on page 273


sync on page 274
unload on page 274
verlbp on page 274

v weof on page 274


v write on page 274
v wtest on page 275
Medium Changer Subcommands
v audit on page 275
v cartridgelocation on page 275
v elementinfo on page 275
v exchange on page 276
v inventory on page 276
v move on page 276
v position on page 276
Service Aid commands
v dump on page 276
v ekmtest on page 277
v encryption on page 277
v
v
v
v

ucode on page 277


tapephcp on page 277
ltfsphcp on page 278
verify on page 278
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

259

v
v
v
v
v

checkltfsreadiness on page 278


ltfsdefragmentation on page 279
standardtest on page 279
fullwrite on page 280
systemtest on page 280

v tapeusage on page 280


HD-P commands
v hdp discover on page 280
v hdp senderror on page 281
v hdp show on page 281

allow
(Deprecated: unlock, -o rem) Allow medium removal for tape or changer devices
(unlock door). The counter command for this is prevent.
Parameters:
None

Supported platforms: All

devinfo
(Deprecated: -o gdi) Show device information (device type, sub type and block
size)
Parameters:
None

Supported platforms: AIX, Solaris, HP-UX

inquiry
(Deprecated: -o inq) Issue an Inquiry command and dump the bytes in Hex.
Parameters:
inquiry [Page code in Hex, 00-FF without leading x]

Note: ITDT prints a hex dump of the inquiry data on all platforms.
Supported platforms: All

logpage
(Deprecated: -o log) This subcommand issues the SCSI Log Sense command to the
device for the specified page and displays the log sense data.
Parameters:
Page (page in hex without the leading x)
[Subpage] (in hex without leading x)

Supported platforms: All

260

IBM Tape Device Drivers Installation and Users Guide

loop
This subcommand loops all subsequent subcommands continuously or a number
of times if the Count parameter is specified. Also refer to the sleep subcommand.
Parameters:
loop [Count]

Supported platforms: All

modepage
(Deprecated: -o mod) This subcommand issues the SCSI Mode Sense command to
the device for the specified page and displays the mode sense data.
Parameters:
modepage Page (page in hex without leading x)

Supported platforms: All

prevent
(Deprecated: -o lck, lock) Prevent medium removal for tape or changer devices
(lock door). The counter command for this command is allow.
Parameters:
None

Supported platforms: All

print
This subcommand prints the associated text to standard output. It can be used at
any time to display the progress of the subcommands.
Parameters:
print Text

Supported platforms: All

qrypath
(Deprecated: -o phs, path, checkpath) This subcommand displays information
about the device and SCSI paths, such as logical parent, SCSI IDs, and the status of
the SCSI paths for the primary path and all alternate paths that are configured.
Parameters:
None

Note: ITDT shows the entire path information for all the commands.
Supported platforms: All

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

261

qryversion
(Deprecated: -o drv) This subcommand prints out the current version of the IBM
device driver.
Parameters:
None

Supported platforms: All

release
(Deprecated: -o rel) This subcommand explicitly releases a device and makes it
available for other hosts by issuing the SCSI Release command.
Parameters:
None

Supported platforms: All

reqsense
(Deprecated: -o req) This subcommand issues the SCSI Request Sense command to
the device and displays the sense data in hex format.
Parameters:
None

Supported platforms: All

reserve
(Deprecated: -o res) This subcommand explicitly reserves a device by issuing the
SCSI Reserve command.
Parameters:
None

Supported platforms: All

scan
Displays the list of connected devices. For each detected device special file name,
vendor id, firmware version, serial-number, SCSI bus address, associated changer,
and device driver name is shown.
Parameters:
[-force-generic-dd] [-o formatstring]

Supported platforms: All


Example scan:
./itdt scan
Scanning SCSI Bus ...
#0 /dev/IBMtape3 - [ULT3580-TD5]-[ACDF] S/N:1168001104 H3-B0-T3-L0
#1 /dev/IBMchanger1 - [3573-TL]-[9.20] S/N:00L4U78D6118_LL0 H3-B0-T5-L1
#2 /dev/IBMtape7 - [ULTRIUM-TD4]-[A232] S/N:1310000593 H1-B0-T0-L0

262

IBM Tape Device Drivers Installation and Users Guide

By using the optional parameter -force-generic-dd, the usage of the generic


Operating System driver (not with the IBM Tape Device Driver) is forced.
The formatstring controls the output and specifies how the connected devices must
be reported. It can include any alphanumeric character. The default formatstring is
"#%# %D - [%P]-[%F] S/N:%S H%H-B%B-T%T-L%L".
Interpreted identifiers are
%D
%V
%P
%F
%S
%H
%B
%T
%L
%h
%b
%t
%l
%I
%#
%C

device name
vendor name
product name
firmware version
serial number
host adapter
bus number
target id
logical unit
host adapter as hexadecimal value
bus number as hexadecimal value
target id as hexadecimal value
logical unit as hexadecimal value
interface type
enumeration number
serial number of associated changer device

Minimum field width:


An integer that is placed between a % sign and the format command acts as a
minimum field width specifier, a negative value uses right text alignment.
Example scan with format string:
./itdt scan -o "%-2#. %-18S %-12P %F %I"
Scanning SCSI Bus ...
0.
1310115166 ULT3580-TD4 97F2
1.
1310034311 ULT3580-TD4 A232
2.
1168001104 ULT3580-TD5 B170
3.
00L4U78D6118_LL0
3573-TL 9.20
4.
00L2U78G8705_LL0
3573-TL 9.20
5.
000001327208
03592E06 26CA
6.
cigen22164 ULT3580-TD2 73V1
7.
000001365271
03592E05 1DD1

Fibre
Fibre
Fibre
N/A
N/A
Fibre
Fibre
Fibre

Exit with code: 0

Any combination of the identifiers that are listed here are supported.
Known problem: On Solaris for IBM device driver managed device: the
information about the host, bus, target, and lun for generic devices is incorrect.

sleep
Sleep for the specified number of seconds before running the next subcommand.
Parameters:
sleep [Seconds]

Supported platforms: All

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

263

tur
(Deprecated: -o tur) This subcommand issues the SCSI Test Unit Ready command
to the device.
Parameters:
None

Supported platforms: All

vpd
This subcommand displays Vital Product Data (VPD) that are part of the Inquiry
command data and outputs Manufacturer, Product Identification and Revision
Level.
Parameters:
None

Supported platforms: All

append
Opens the device in append mode. The file access permission is Write Only.
Parameters:
None

Supported platforms: All, but on Windows this open mode is not supported by the
IBM Tape Device Driver. On HP-UX this open mode is remapped to r/w by the
IBM Tape Device Driver.

bsf
(Deprecated: -o bsf) This subcommand backward spaces Count filemarks. The
tape is positioned on the beginning of the last block of the previous file. An
optional Count can be specified. The default is 1.
Parameters:
bsf [Count]

Supported platforms: All

bsr
(Deprecated: -o bsr) This subcommand backward spaces Count records. An
optional count can be specified. The default is 1.
Parameters:
bsr [Count]

Supported platforms: All

264

IBM Tape Device Drivers Installation and Users Guide

chgpart
This subcommand changes the current active tape partition to a new partition
specified by Number. Optionally, a Blockid can also be specified. If Blockid is
omitted, the tape is positioned at the start of the new partition. Otherwise, the tape
is positioned at the Blockid specified.
Parameters:
Number [Blockid]

Supported platforms: All

density
(Deprecated: -o gdn / -o rds) This subcommand issues the SCSI Report Density
Support command for all supported media and for the current media loaded in the
drive, and displays the results. If the drive is not loaded, the current media density
is not reported.
Parameters:
None

Note: ITDT-SE outputs detailed information on all platforms.


Supported platforms: All

display
(Deprecated: -o msg) This subcommand displays a message on the display panel of
the tape device. Up to 16 characters can be used for the message. If the message is
longer than eight characters, the display alternates between the first eight
characters and the remainder of the message.
Parameters:
display message1 message2

Supported platforms: All

erase
(Deprecated: -o era) This subcommand writes EOD at the current position and
erases the tape from EOD to the end of current partition.
Parameters:
None

Supported platforms: All except i5/OS operating system


Note: The erase command triggers a long erase of the cartridge that sets EOD to
the current position. Then, it writes the Data Set Separator (DSS) pattern
from the new EOD to the end of the current partition. This process
overwrites any data that is on the cartridge after the current logical position.
To remove the entire cartridge, the user must remove all partitions (use the
rmp command for LTO 5, TS1140, and newer drives). Then, issue the rewind
command before the erase command.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

265

Examples:
For LTO 5 / TS1140 and later
itdt -f <device name> load rmp rewind erase

For all earlier LTO and Enterprise drive generations


itdt -f <device name> load rewind erase

fdp
This subcommand creates fdp (fixed data partitions) wrap wise. The default size
for LTO 5 of partition 0 in this case is 1425 GB and the size of partition 1 is 37.5
GB. It also works for Jaguar 4 but the size depends on the used cartridge.
Supported by LTO 5, Jaguar 4, and later.
Parameters:
None

Supported platforms: All

fdpl
This subcommand creates fdp (fixed data partitions) longitudinal. The command is
valid only for Jaguar drives (Jaguar 4 and later) and creates partitions 0 and 1 on
the cartridge. The size depends on the used cartridge.
Parameters:
None

Supported platforms: All

fsf
(Deprecated: -o fsf) This subcommand forward spaces count filemarks. The tape
is positioned on the first block of the next file. An optional count can be specified.
The default is 1.
Parameters:
fsf [Count]

Supported platforms: All

fsr
(Deprecated: -o fsr) This subcommand forward spaces count records. An optional
count can be specified. The default is 1.
Parameters:
fsr [Count]

Supported platforms: All

getparms
(Deprecated: -o parms / status / -o gpa) Get and show drive, media and driver
parameters.

266

IBM Tape Device Drivers Installation and Users Guide

Parameters:
None

Supported platforms: All

idp
This subcommand creates initiator defined partitions (IDP) wrap wise on tape. The
parameter pSize0 is used to specify the size of partition 0 and the parameter pSize1
is used to specify the size of partition 1. One of pSize0 or pSize1 must have a
value that is entered in hex matching 37.5 * n with (1 <= n <= 38) to specify the
wanted size of that partition. The other parameter of pSize0 or pSize1 must have
the value 0xFFFF to specify that the remaining capacity is used for that partition. If
0xFFFF is not used for one of the parameters, pSize0 or pSize1, the drive might
reject the command | unless pSize0 and pSize1 exactly match predefined allowable
values.
For Jaguar 4 (not for LTO 5) the parameters pSize2 and pSize3 are valid and they
follow the same rules as described earlier.
For example: If you want a 37.5 GB partition (the minimum size partition) in
partition 0 and the remainder in partition 1, then set pSize 0 to 0x26 and pSize1 to
0xFFFF. This action results in a volume with a 37.5 GB sized partition 0 and a 1425
GB sized partition 1.
Parameters:
idp pSize0 pSize1
pSize0: size of partition 0
pSize1: size of partition 1

Example Call:
idp 0x26 0xffff

Supported platforms: All

idpl
This subcommand creates initiator defined partitions (IDP) longitudinal wise on
tape. The parameter pSize0 is used to specify the size of partition 0 and the
parameter pSize1 is used to specify the size of partition 1. One of pSize0 or pSize1
must have a value that is entered in hex matching 37.5 * n with (1 <= n <= 38) to
specify the wanted size of that partition. The other parameter of pSize0 or pSize1
must have the value 0xFFFF to specify that the remaining capacity is used for that
partition. If 0xFFFF is not used for one of the parameters, pSize0 or pSize1, the
drive might reject the command | unless pSize0 and pSize1 exactly match
predefined allowable values.
For Jaguar 4 (not for LTO 5) the parameters pSize2 and pSize3 are valid and they
follow the same rules as described earlier.
For example: If you want a 37.5 GB partition (the minimum size partition) in
partition 0 and the remainder in partition 1, then set pSize 0 to 0x26 and pSize1 to
0xFFFF. This action results in a volume with a 37.5 GB sized partition 0 and a 1425
GB sized partition 1.
Parameters:
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

267

idp pSize0 pSize1


pSize0: size of partition 0
pSize1: size of partition 1

Example Call:
idp 0x26 0xffff

Supported platforms: All

list
This subcommand displays the content of a tape. The output lists filemarks and
the size of each record found on the tape until the end of data is reached. The
output that is generated from this subcommand can be large depending on the
amount of data on the tape and must usually be redirected to a file.
Parameters:
None

Supported platforms: All

load
(Deprecated: -o lod) This subcommand issues a SCSI Load command to load a
tape. The subcommand loops all subsequent subcommands continuously or a
number of times if the Count parameter is specified. Also refer to the sleep
subcommand.
Parameters:
None

Supported platforms: All

logsense
Retrieves all Log Sense pages and outputs them as hex.
Parameters:
None

Supported platforms: All

qrypar/qrypart
Queries and displays tape partitioning information.
Parameters:
None

Supported platforms: All

qrylbp
Queries and displays logical block protection information.
Parameters:
None

268

IBM Tape Device Drivers Installation and Users Guide

Supported platforms: All

qrypos
(Deprecated: -o gpo) This subcommand displays the current tape position.
Parameters:
None

Supported platforms: All

qrytcpip
|

This subcommand outputs the current drive TCP/IP configuration. Only supported
with LTO 5, LTO 6, TS1140, and TS1150. Outputs adapter and TCP/IP address
information for IPv4 and IPv6 with address, port and subnet mask. For example:
./itdt -f /dev/IBMtape3 qrytcpip
Reading current TCP/TP Configuration...
Number of Port Descriptors 1
Port Descriptor for Port 1
Number of Socket Descriptors 2
Adapter:1 IPV4 9.11.22.111/23 DHCP:0
Adapter:2 IPV6[0002:0000:0000:0000:0007:0008:0000:0000]/24
Active IP Addresses:
IPv4: 169.254.0.3
Exit with code: 0

Parameters:
None

Supported platforms: All

read
This subcommand reads a file, or a specified number of records, from the tape to
the destination file name specified with the -d flag. If the optional count parameter
is used, only the number of records that are specified with the -c flag are read
unless a filemark is encountered before the number of specified records. If the
count parameter is not used, all records up to the next filemark on tape are read.
Parameters:
read -d Dest [-c Count]

Supported platforms: All

resetdrive
This subcommand issues a Send Diagnostic command (Reset Drive subcommand)
to reset the device.
Parameters:
None

Supported platforms: All

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

269

rmp
Remove partitioning.
Parameters:
None

Supported platforms: All

runtimeinfo/qryruntimeinfo
This subcommand is used to query the dynamic runtime information. Dynamic
runtime information allows an initiator to set dynamic runtime attributes (DRA)
about itself into a device server. The device server then associates those attributes
to the I_T_L nexus and uses the information and associations for enhanced data
collection and debugging.
Parameters:
None

Supported platforms: All (supported since LTO 5 and 3592 E07)

rewind
(Deprecated: -o rew) Rewinds the tape.
Parameters:
None

Supported platforms: All

rtest
(Deprecated: -o rea) This subcommand runs a read test by reading a random data
pattern from the tape and verifying that it matches the written data. The rtest
subcommand can be used after the wtest subcommand to verify the data. An
optional block size, count, and repetition can be specified with the -b, -c, and -r
flags, respectively. If the block size is fixed, then the count specifies the number of
blocks to read on each repetition. If the block size is zero (variable), then the count
specifies the number of bytes to read on each repetition. The default is a block size
of 10240, a count of 20 blocks, and a repetition of 1.
Parameters:
read [-b Blocksize] [-c Count] [-r Repetition]

Supported platforms: All

rwtest
This subcommand runs a read and write test by writing a random data pattern on
the tape, reading it, and verifying that it matches the written data. An optional
block size, count, and repetition can be specified with the -b, -c, and -r flags,
respectively. If the block size is fixed, then the count specifies the number of blocks
to write on each repetition. A single transfer transmits (block size * count) bytes.
The operation is rejected if the total amount exceeds the transfer size the system is

270

IBM Tape Device Drivers Installation and Users Guide

capable of. If the block size is zero (variable), then the count specifies the number
of bytes to write on each repetition. The default is a block size of 10240 bytes, a
count of 20 blocks, and a repetition of 1.
Parameters:
rwtest [-b Blocksize] [-c Count] [-r Repetition]

Supported platforms: All

sdp [0|1|2|3]
Creates SDP (Select Data Partitions) wrap wise on tape.
Parameters:
Type number
For LTO (5 and higher) only the values 0 and 1 are valid.
Using value 0 as parameter leads to partition 0 with 1.5TB
and partition 1 does not exist.
Using value 1 as parameter leads to partition 0 with 750 GB
and partition 1 with 712.5 GB.
For Jaguar (4 and higher) values 0, 1, 2 and 3 are valid.
Using value 0 as parameter will create only one partition,
value 1 creates two and so on.
The sizes of the partitions are depending on the cartridge used in drive.

Supported platforms: All

sdpl [0|1]
Creates SDP (Select Data Partitions) longitudinal on tape.
Parameters:
Type number
For Jaguar (4 and higher) values 0 and 1 are valid.
Using the value 0 as the parameter creates partition 0 only
and the value 1 as the parameter creates partitions 0 and 1.
The sizes of the partitions depends on the cartridge
used in drive.

Supported platforms: All

seod
(Deprecated: -o eod) Spaces to end of data on the tape.
Parameters:
None

Supported platforms: All

setparm
(Deprecated: -o spa / volid / compress / nocompress / sili / nosili /
autoload / noautoload / retain / noretain)
ITDT-SE uses the new setparm option that corresponds to the current interactive
mode options.
Parameters: The Value is
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

271

v
v
v
v
v

0-65535 for the blocksize parameter


0-100 for the capacity parameter (=percentage)
1 (SCSI) and 2 (AIX) for recordspacemode
The Volume Id string for the volid parameter
NONE|ASSO|PERS|WORM for the writeprotect parameter

v 0 for off/no and 1 for on/yes for setparm autoload, autodump, buffering,
compression, immediate, readpastfilemark, sili, simmim, trace, trailer,
volumelogging
Supported platforms: All, but only a subset of the parameters is supported by the
platform's device drivers.
Table 56. Supported platforms
Linux

Windows

setparm autoload

AIX

Solaris

HP-UX

setparm autodump

setparm blocksize

setparm buffering

X
3

setparm capacity

setparm compression

setparm datasafemode

setparm immediate

setparm readpastfilemark

setparm recordspacemode

setparm sili

setparm simmim

setparm skipsync

setparm sleepmode

setparm trace

setparm trailer

setparm volid
setparm volumelogging
setparm writeprotect

X
X
X

X
X

Note:
1. The datasafemode can be set to YES or NO when no cartridge is loaded.
When a cartridge is loaded, the datasafemode can be set only to YES.
2. Depending on the support of the device.
3. Only supported by 3592.

setpos
(Deprecated: -o spo / asf) This subcommand issues the SCSI Locate command to
the device to set the tape position. If the optional Blockid parameter is specified,
the tape position is set to the Blockid. Otherwise, if the Blockid parameter is
omitted, the tape position is set to the last position saved by using the qrypos
subcommand.

272

IBM Tape Device Drivers Installation and Users Guide

Parameters:
setpos [Blockid]

Supported platforms: All

settcpip
|
|

This subcommand sets the drive ethernet port TCP/IP settings for LTO 5, LTO 6,
TS1140, and TS1150 drives. Either a static IPv4 or IPv6 address can be set or DHCP
enabled.
Example DHCP:
./itdt -f /dev/IBMtape3 settcpip DHCP
Initializing device...
Setting TCP/TP Configuration...
Reading current TCP/TP Configuration...
Number of Port Descriptors 1
Port Descriptor for Port 1
Number of Socket Descriptors 2
Adapter:1 IPV4 9.11.22.111/23 DHCP:1
Adapter:2 IPV6 [0002:0000:0000:0000:0007:0008:0000:0000]/24
Active IP Addresses:
Exit with code: 0

IPv4 or IPv6 addresses are entered in the syntax a.b.c.d:/subnet_mask_length


where a, b, c, and d are values with 1 to 3 digits. If the optional parameter
subnet_mask_length is not specified, the current setting is kept.
Example static IPv4:
./itdt -f /dev/IBMtape3 settcpip 9.155.27.14/23
Initializing device...
Setting TCP/TP Configuration...
Reading current TCP/TP Configuration...
Number of Port Descriptors 1
Port Descriptor for Port 1
Number of Socket Descriptors 2
Adapter:1 IPV4 9.155.27.14/23 DHCP:0
Adapter:2 IPV6 [0002:0000:0000:0000:0007:0008:0000:0000]/24
Active IP Addresses: IPv4:
169.254.0.3 IPv4:
9.155.27.46 IPv4:
9.155.27.14
Exit with code: 0

Parameters:
dhcp, address[/subnet_mask_length]

Supported platforms: All


Note: With the current firmware level, the device can be reached (ping, FTP) only
within the same subnet. For example, the sample is configured with a static
IP address (9.155.27.14) and DHCP enabled. The drive can be pinged only
within the same subnet (9.155.27.xxx). Both IP addresses (9.155.27.14 and the
DCP address 9.155.27.46) are active and can be used.
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

273

sync
(Deprecated: -o syn) This subcommand synchronizes buffers/flushes the tape
buffers to tape.
Parameters:
None

Supported platforms: All

unload
(Deprecated: -o off / offline / rewoffl) This subcommand rewinds and unloads
the tape.
Parameters:
None

Supported platforms: All

verlbp
This subcommand verifies logical block protection written blocks. The verification
length can be set with parameter value filemarks count or with EOD.
Parameters:
filemarks (numeric value) | eod

Supported platforms: All

weof
(Deprecated: -o eof / eof) These subcommands write count filemarks. An
optional count can be specified. The default is 1.
Parameters:
weof [Count]

Note: The weof parameter [count] is optional, if it is not supplied, one filemark is
written.
Supported platforms: All

write
This subcommand writes the source file specified with the -s flag on the tape. In
case the parameter 'raw' is specified, the blocksize specified in setparm (setparm
blocksize) is used instead of the default blocksize of 64 kB.
Parameters:
[-raw] -s Source

Supported platforms: All

274

IBM Tape Device Drivers Installation and Users Guide

wtest
(Deprecated: -o wri) This subcommand runs a write test by writing a random data
pattern on the tape. The rtest subcommand can be used after the wtest
subcommand to verify the data that was written. An optional block size, count,
and repetition can be specified with the -b, -c, and -r flags, respectively. If the
block size is fixed, the count specifies the number of blocks to write on each
repetition. If the block size is zero (variable), the count specifies the number of
bytes to write on each repetition. The default is a block size of 10240, a count of 20
blocks, and a repetition of 1.
Parameters:
wtest [-b Blocksize] [-c Count] [-r Repetition]

Supported platforms: All

audit
(Deprecated: -o aud / -o ier) This subcommand with no parameters issues the
SCSI Initialize Element Status command to the device. Using the optional
parameters Address and Count issues the SCSI Initialize Element Status With
Range command to the device. The Address parameter specifies the starting
element address and the Count parameter, if used, specifies the number of
elements to initialize. If Count is omitted, it defaults to 1.
Parameters:
audit [[Address] [Count]]

Supported platforms: All

cartridgelocation
This subcommand with no parameters issues the SCSI Read Element Status
command to the device to report all slots with the cartridge location information.
Using the optional parameters Slot and Count issues the SCSI Read Element Status
to the device for a specific starting Slot address and optionally the Count specifies
the number of slots to return. If Count is omitted, it defaults to 1.
Parameters:
cartridgelocation [Slot [Count]]

Supported platforms: All

elementinfo
(Deprecated: -o ele) This subcommand displays element information (number and
address) of each element type.
Parameters:
None

Supported platforms: All

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

275

exchange
(Deprecated: -o exh) This subcommand issues the SCSI Exchange Medium
command to the device by using the Source, Dest1, and Dest2 addresses specified.
This command runs the equivalent function of two Move Medium commands. The
first moves the cartridge from the element address that is specified by the Dest1
parameter to the element address specified by the Dest2 parameter. The second
moves the cartridge from the element address that is specified by the Source
parameter to the element address specified by the Dest1 parameter.
Parameters:
exchange Source Dest1 Dest2

Supported platforms: All

inventory
(Deprecated: -o inv) This subcommand with no parameters issues the SCSI Read
Element Status command for each element type and displays the element status
information. If the optional -i parameter is used, then only the import/export
element status information is returned. If the optional -v parameter is used, then
only the element status information for the specified Volid if found is returned.
Parameters:
inventory [-i | -v Volid]

Note: ITDT supports the optional parameters on all platforms.


Supported platforms: All

move
(Deprecated: -o mov) This subcommand issues the SCSI Move Medium command
by using the source and destination addresses specified. The element addresses can
be obtained with the elementinfo subcommand.
Parameters:
move Source Dest

Supported platforms: All

position
(Deprecated: -o pos) This subcommand issues the SCSI Position to Element
command by using the destination specified.
Parameters:
position Dest

Supported platforms: All

dump
(Deprecated: -o sdp) This subcommand forces a dump of the tape drive and stores
the dumps before and after the force dump in the ITDT-SE output folder with the
ITDT-SE naming convention (serialnumber.a.gz and serialnumber.b.gz).

276

IBM Tape Device Drivers Installation and Users Guide

Parameters:
None

Supported platforms: All

ekmtest
Test encryption key path/setup.
Parameters:
None

Supported platforms: AIX, Linux, Solaris, Windows

encryption
Query tape drive encryption settings and display the encryption state.
Parameters:
None

Supported platforms: All

ucode
(Deprecated: -o dmc) This subcommand downloads microcode to the device. The
Filename is a file that contains the ucode.
Parameters:
ucode Filename

Supported platforms: All

tapephcp
Creates a physical copy of a tape cartridge. The created cartridge has the same
physical layout and contents as the origin cartridge. The amount of transferred
data and the current data transfer rate is displayed every 3-5 minutes. Tapephcp is
supported for LTO and 3592 tape drives and can therefore be used for data
migration. A tapephcp command that is issued to copy data from a 3592 drive to
an LTO drive or from an LTO Gen 4 to an LTO Gen 3 works, if the amount of used
data from the source device is equal or less than the capacity of the destination
device.
Parameters:
source destination

Source and destination can either a special device file name, or a tape image file
name. The special device file format is identical to the format specified in chapter
3.19 parameter -f device.
Examples: Tape to Tape copy with the IBM tape driver
./itdt tapephcp /dev/IBMtape0 /dev/IBMtape1
Tape to Image File using generic interface
./itdt tapephcp 3 2 1 0 /tmp/MyTapeImage.img
Image File to Tape using IBM Tape driver
./itdt tapephcp /tmp/MyTapeImage.img /dev/IBMtape1
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

277

Supported copy operations are from tape to tape, from image file to tape, and from
tape to image file.

ltfsphcp
Creates a physical copy of a LTFS formatted cartridge. Ltfsphcp is based on
tapephcp. The LTFS specified parameters volumeuuid and VCI are adjusted during
this copy operation. The created cartridge has exactly the same physical layout as
the origin cartridge. Expect the volumeuuid to be identical to the contents of the
two cartridges. The amount of transferred data and the current data transfer rate is
displayed every 3-5 minutes. When ltfsphcp is used with a non-LTFS formatted
cartridge, the behavior of ltfsphcp is identical to tapephcp.
Parameters:
source destination

Source and destination can either a special device file name, or a tape image file
name. The special device file format is identical to the format specified in chapter
3.19 parameter -f device.
Examples:
Tape to Tape copy using IBM tape driver
./itdt ltfsphcp /dev/IBMtape0 /dev/IBMtape1
Tape to Image File using generic interface
./itdt ltfsphcp 3 2 1 0 /tmp/MyTapeImage.img
Image File to Tape using IBM Tape driver
./itdt ltfsphcp /tmp/MyTapeImage.img /dev/IBMtape1

Supported copy operations are from tape to tape, from image file to tape, and from
tape to image file.

verify
Verifies the physical contents of two cartridges. The physical data layout and the
binary data are compared.
Parameters:
source destination

Source and destination can either a special device file name, or a tape image file
name. The special device file format is identical to the format specified in chapter
3.19 parameter -f.
Examples:
./itdt verify /dev/IBMtape0 /dev/IBMtape1

checkltfsreadiness
This subcommand issues the LTFS Readiness Check test.
The LTFS Readiness Check analyzes the Operating System and tape drive
environment to ensure that the IBM Linear Tape file system can be installed. This
test checks the Operating System version, the tape device driver version, the tape
drive firmware, and the LTFS HBA requirements. LTFS Readiness Check requires
an empty data cartridge.

278

IBM Tape Device Drivers Installation and Users Guide

ltfsdefragmentation
On an LTFS formatted cartridge, the physical data records for a single file can be
fragmented across the entire media. When such a file is accessed, a long response
time might result. The tape drive must locate to different cartridge positions to
retrieve the entire contents the file. If the first data records of a file are stored at
the end of the tape and the other records are stored at the beginning of the media,
the tape drive must run several times intensive seek operations to fulfill the
complete file retrieval. This subcommand creates a copy of the cartridge with
unfragmented content.
As an initial step, ITDT stores the complete content of the source tape media in a
Tape Image file that is on an HDD. Using this Tape Image file and the ITDT image
file backend driver for LTFS, LTFS is able to mount the previously created Tape
Image file as a read-only volume. As the final step, the data is defragmented by
copying the files from the mounted Tape Image file to the mounted destination
cartridge. This algorithm avoids any seek operations on the physical tape device.
The seek operations are completed on the temporary ITDT image file that is on a
hard disk. The source and destination tape device are accessed at maximum media
speed. The defragmentation of a cartridge can take up to 6 hours.
Parameters:
source tempdirectory destination [options]
source
tempdirectory
destination
Options:
-LTFSCOMMAND=<value>
-MKLTFSCOMMAND=<value>
-LTFSCPCOMMAND=<value>
-LTFS_SRC_OPTION=<value>
-LTFS_DEST_OPTION=<value>
-MKLTFSOPTION=<value>
-LTFSCPOPTION=<value>
-verbose
-debug

Source Tape Device with fragmented data on cartridge


Directory where the ITDT Tape image file is stored
Destination Tape Device where defragmented data should be stored.
Command used to perform the LTFS mount operation (default:ltfs)
Command used to format the destination media (default:mkltfs)
Command used to perform the LTFS Copy (default:cp)
For mounting of ITDT Image File, additional Mount options
For mounting of destination cartridge, additional Mount options
Additional options for mkltfs
Options for LTFS file copy program (default:-r --preserve=mode,
ownership,timestamps,xattr)
Displays executed LTFS (ltfs,mkltfs, ltfscp) commands and
associated return code
Displays detailed output of executed commands commands

Supported platforms: Linux x86_64 only


Prerequirements: IBM LTFS SDE Version 2.2 (Build 4700 or later) and sufficient free
hard disk space for temporary Tape Image file
Example:
./itdt ltfsdegragmentation /dev/IBMtape0 /tmp/tapeimages
/dev/IBMtape1 -verbose -mkltfsoption=--force

standardtest
The Test function (Scan Menu Command [T]) checks if the tape device is defective
and outputs a pass/fail result. This test requires a loaded cartridge.
Parameters:
[-forcedataoverwrite]

Supported platforms: All


Chapter 8. IBM Tape Diagnostic Tool (ITDT)

279

fullwrite
Runs the ITDT Full Write Test (Scan Menu Command [F]).
The Full Write function writes the entire cartridge with a given block size either
with compressible or incompressible data and output performance data. This test
requires a loaded cartridge.
Parameters:
[-b Blocksize]
[-compressible|-incompressible]
[-forcedataoverwrite]

Supported platforms: All

systemtest
Runs the ITDT Systemtest (Scan Menu Command [Y]).
The System Test is a short test that runs the following actions.
v Reveals system performance bottlenecks. Compressible data throughput values
can reveal bandwidth limitations that are caused by the system or cabling or
HBA.
v Measures performance variations across the different block sizes to find the ideal
block size for the system configuration.
This test requires a loaded cartridge.
Parameters:
[-forcedataoverwrite]

Supported platforms: All

tapeusage
Displays the tapeusage information (Scan Menu Command [U]).
This test requires a loaded cartridge.
Parameters:
None

Supported platforms: All

hdp discover
Discovers the HD-P system and presents the logical and physical HD-P
environment. The logical map is an n x n representation of the libraries, where a
1 is the indicator for a connection and a -1 of no connection. In case the
command is called without any device files, all attached TS3500/TS4500 are used.

Parameters:
[-d device-file1 -d device-file2 ....]

Supported platforms: AIX, Linux on P, and X64

280

IBM Tape Device Drivers Installation and Users Guide

A mixed environment (LTO and 3592 devices) is not supported.

hdp senderror
|

Issues a Test Call Home function. In case the command is called without any
device file, all attached TS3500/TS4500 are used.
Parameters:
[-d device-file]

Supported platforms: AIX, Linux on P, and X64

hdp show
|

Shows the extended HD-P Import Export Elements. In case the command is called
without any device file, all attached TS3500/TS4500 are used.
Parameters:
[-d device-file]

Supported platforms: AIX, Linux on P, and X64

Deprecated commands
The following is a list of commands that are currently available in this version of
ITDT. However, in a future release the following commands and some alternate
calls of the Common Command Scripting set are no longer available and the
scripts that contain these commands must be changed. The scripts that use the
deprecated commands must be changed for future editions.
General commands
v
v
v
v
v

-o dis / disablepath
-o ena / enablepath
fuser
kill
passthru

v resetpath
Tape commands
v bsfm
v -o chk
v fsfm
v -o grs
v -o gmi
v qryinquiry
v qrysense
v -o ret
v setblk
v -o gds
v getrecsize
v setrecsize

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

281

Medium Changer subcommands


v -o dvc
v mount
v demount
Service Aid commands
v fmrtape
v -o fdp
v reset
v -o qmc

Alternative mount/demount script - sample for Windows


The script (load.drive.cmd) issues a mount/umount command to the specified
library. If the drive is empty, a cartridge is moved from the first available storage
slot to the drive. If the drive contains a cartridge, the cartridge is moved to the
previous storage location.
Requirements:
v Windows operating system
v IBM tape library with one or more tape drives
v IBM tape device driver or Generic SCSI driver
v Path variable must include ITDT executable
Usage: load-drive.cmd drivername|hbtl [drivenumber]
drivername is the device driver name assigned by the IBM device driver
hbtl is the associated SCSI address h=host, b=bus, T=target id and l=lun
drivenumber, logical drive number, default is 1

Example for using the IBM device driver: load-drive.cmd \\.\Changer0


Example for using the SCSI Generic driver: load-drive.cmd "2 0 3 1"
load-drive.cmd:
@ECHO OFF
IF [%1]==[] (
echo.
echo Usage load-drive.cmd drivername^|hbtl [drivenumber]
echo.
echo drivername is the drivername assigned by the IBM device driver
echo example:load-drive.cmd \\.\Changer0
echo.
echo hbtl is the associated SCSI address h=host, b=bus, T=target id and l=lun
echo example: load-drive.cmd "3 0 2 1"
echo.
goto :EOF
)
set driveNumber=1
IF not [%2]==[] set driveNumber=%2
echo Loading/Unload Cartridge Drive:%driveNumber%
itdt -f %~1 inventory >inventory.txt
set /a count=0
set action=load
set sourceAddress=
set destination=
set driveAddress=
set slotAddress=
FOR /F "tokens=1,2,3,4,5" %%G IN (inventory.txt) DO (

282

IBM Tape Device Drivers Installation and Users Guide

call :checkline %%G %%H %%I %%J %%K


)
GOTO :moveMedium
:checkline
set name=%1 %2
if "%name%"=="Drive Address" (
set /a count+=1
set currentTag=%name%
set driveAddress=%3
)
if "%name%"=="Media Present" (
rem echo full drive addr:%driveAddress% slot addr:%slotAddress%
action:%action% source:%sourceAddress% Tag:%currentTag%
if "%count%"=="%driveNumber%" if "%currentTag%"=="Drive Address" if "%4"=="Yes" (
set action=unload
set sourceAddress=%driveAddress%
)
if "%count%"=="%driveNumber%" if "%currentTag%"=="Drive Address"
if not "%4"=="Yes" (
set action=load
set destination=%driveAddress%
)
if "%sourceAddress%"=="" if "%currentTag%"=="Slot Address"
if "%action%"=="load" if "%4"=="Yes" (
set sourceAddress=%slotAddress%
)
)
if "%name%"=="Source Element" (
if "%count%"=="%driveNumber%" if "%currentTag%"=="Drive Address"
if "%action%"=="unload" (
set destination=%5
)
)
if "%name%"=="Slot Address" (
set currentTag=%name%
set slotAddress=%4
)
GOTO:EOF
:moveMedium
echo %action% move media from %sourceAddress% to destination %destination%
itdt -f %~1 move %sourceAddress% %destination%
del inventory.txt
GOTO:EOF

Standard Edition scripting commands: known limitations and


deviations
|

The scripting commands idp, sdp, fdp, and qrypart are currently only supported
by LTO 5, LTO 6, TS1140, and TS1150 drives.
When scripting, one must be aware of the following general deviations to the
legacy tapeutil scripting command set.
The Verbose Mode parameter is ignored for the ITDT-SE implementation; instead
always the full information is printed.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

283

For some operations, the sense data length is limited to 32 bytes - this length is
required by the ITDT test sequences.
The list command does not work on Linux variants where the reported maximum
SCSI transfer size is larger than the size the system can actually transfer.
Because ITDT-SE opens the device read/write by default in scripting mode, the
WORM mode cannot be deactivated in scripting mode. Use the Tapeutil interactive
mode instead to deactivate the WORM mode.
Scripting mode command deviations to legacy tapeutil (tapeutil is not changed):
1. The erg (Erase Gap) command is not supported.
2. The mtdevice command is not supported.
3. The tell command is not supported.
The seek command is not supported.
The format command is not supported.
The -o qsn command is not supported.
path/querypath/path / qrypath / checkpath / - o phs - output: always
show all paths.
The command is valid only in combination with an IBM device driver.
8. devinfo - different output (decoded on all platforms)
9. inquiry - different output on Linux (like AIX in hex)
10. vpd - different behavior on Solaris (like AIX)
4.
5.
6.
7.

11. modepage - HP-UX and Solaris output deviations (like AIX)


12. inventory - additional parameters on AIX available on all platforms
13. cartridgelocation - AIX parameter deviation available on all platforms
14. mediainfo - different output --> decode on all platforms
The command is valid only in combination with an IBM device driver.
15. setpos - logical versus physical position, only set logical position as on AIX
16. HPUX: -o gpo -t 1|2 --> parameter -t1|2 (logical, physical) is not
supported.
17. density - output all information on all platforms
18. setparm (new) - work around the inability to set all parameters on all
platforms except the undocumented HP-UX release
19. getparms (new) - retrieve all parameters on all platforms, independent of flag
set
20. qryinquiry - output the same as on AIX
21. logsense - does not output header with device/serial/volid, example:
05/12/09 15:10:44 Device: ULT3580- S/N: 1300000206 Volid: UNKNOWN

22. erase - does not work on i5/OS because of operating system limitation.
23. Using -w x parameter without the necessary open leads to a core at least on
Solaris.

284

IBM Tape Device Drivers Installation and Users Guide

IBM Tape Diagnostic Tool - Graphical Edition


Installing ITDT - Graphical Edition
Installing ITDT-GE on Windows operating systems
To install ITDT-GE on Windows, download the executable file
install_ITDT_GE_<version>.exe on a directory of your choice.
Double-click the downloaded file to start the installer application.
ITDT-GE installer automatically uninstalls any previous version before the current
one is installed.
For the graphical user interface (GUI), a minimum screen resolution of 1024*768
pixels is required.
The supported Windows operating systems for ITDT-GE are
v Microsoft Windows Server 2008 (32-bit x86 and 64-bit x64)
v Microsoft Windows Server 2012 (32-bit x86 and 64-bit x64)
v Microsoft Windows 7 (32-bit x86 and 64-bit x64)
v Microsoft Windows 8 (32-bit x86 and 64-bit x64)

Installing ITDT-GE on Linux operating systems


To install ITDT-GE on Linux, download the executable file
install_ITDT_GE_<version>.bin to a directory of your choice.
install_ITDT_GE_<version>.bin must be run by a user with root access rights.
The ITDT-GE installer automatically uninstalls any previous version before the
current one is installed.
For the graphical user interface (GUI) a minimum screen resolution of 1024*768
pixels is required. The supported Linux operating systems for ITDT-GE are
v Linux Distributions with glibc 2.2.5 and higher.

Graphical Edition - known issues and limitations


This section describes the known issues and limitations of ITDT-GE.

Linux operating systems


It is recommended to not operate Security Enhanced Linux (SELinux) in enforcing
mode while ITDT-GE is running.
On RedHat Enterprise Linux 4 and 5 and SuSE Enterprise Linux 10, starting the
online help might cause an error message Problems opening link / Unable to
open web browser on {0}. Workarounds are to issue the commands
a) ln -s /usr/bin/firefox /usr/local/bin/mozilla
or
b) export MOZILLA_FIVE_HOME=/usr/lib/firefox<version>

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

285

Replace with the appropriate path to your installed Firefox version before ITDT-GE
is started.

Gnome desktop
If you are using the Gnome desktop, be sure to log in to the desktop session as
root to use ITDT-GE to prevent device access issues.

Windows operating systems


On Microsoft Windows systems where the maximum transfer size is limited to less
than 64 kB, the Dump and Firmware update operations does not work.

Performance issues
If you are using Adaptec SCSI Host Bus Adapters, ensure that you are using the
latest Adaptec Host Bus Adapter Drivers instead of the drivers that are shipped
with the Windows operating system.

Devices disappear after firmware update


After a firmware update, devices might disappear. This issue is a known Windows
problem.
See the Article ID: 812024 at http://support.microsoft.com/kb/812024/en-us
Repeated Scan operations might help to rediscover the device.

All supported operating systems


Command timeout
There is no instant operation termination upon SCSI command timeout. For
example, when the SCSI cable is unplugged after POST A is started.
When a command timeout condition occurs, ITDT might still continue to run more
operations (like unmounting the cartridge) instead of instantly terminating with a
timeout condition.

3576/TS3310 tape library


Library Firmware Update with ITDT-GE is not supported by the 3576/TS3310 tape
library. Update the firmware by using the 3576/TS3310 Web User Interface.

3494 tape library


Drives in a 3494 tape library or an STK silo library are supported. Only the Test
option does not work because of device-specific restrictions for handling cartridges.

286

IBM Tape Device Drivers Installation and Users Guide

a2500238

ITDT-GE user interface description

Figure 47. Graphical Edition user interface

To start ITDT-GE on Windows, click the shortcut that is created by the installation
process. On Linux, no start menu entry is generated. Start ITDT-GE by opening a
Terminal window, then switch to root user.
$ su -

Finally, start ITDT-GE with


$ /opt/ibm/itdt-ge/itdt-ge

The User Settings dialog box displays the first time that the program is run,
allowing the entry of user specifications: User name, company name, output path,
and log level.
The Output Path defines the location where the test reports and dumps are saved.
The Windows default output path is
C:\Documents and Settings\<username>\.itdt-ge\output

or
C:\Users\<username>\.itdt-ge\output

where <username> is the Windows user login name. The Linux default output
path is
/root/.itdt-ge/output

The Log Level must not be changed unless requested to do so by the IBM Support
Center. It is recommended that this information be provided to allow for further
analysis of test results.
The interface of the GE edition is as follows:
v The main menu in the upper left
v The graphical buttons to select either the Diagnostic or the Tapeutil perspective
v The Control Center with the toolbar that contains the main actions and
advanced actions that can be reached by drop-down arrows
v The test tab area on the right that contains all output of the running and
previously finished tests
v The Status Information area on the bottom that summarizes the results of
previously run tests or notifies when a test tab requires user input

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

287

a2500279

Figure 48. Graphical Edition preferences

It is recommended that this information be provided to allow for further analysis


of test results. Click OK to save the settings and close the dialog box.
The ITDT-GE interface contains the following sections:

288

IBM Tape Device Drivers Installation and Users Guide

a2500239

Figure 49. Graphical Edition interface

v Main menu (1 on Figure 49)- Located in upper left (File, Window, Help).
v Control Center (2 on Figure 49) - On left side (Device operations - Scan, Test,
Dump, and Update)
Extra device operations are available by using drop-down arrows.
v Test Lab (3 on Figure 49) - Located from center to right side (Contains running
and previously run tests)
v Status Information (4 on Figure 49) - Located below the Test Lab (Contains
summary results of tests)
The Control Center is the primary section the ITDT-GE operations.
v Click the Scan menu item in the Control Center to display the list of tape
devices found. When the scan is complete, select one device in the Test Lab by
clicking the corresponding check box. Click the arrow next to the Scan menu
item to add a device manually.
v Test
Click the arrow next to the Test menu item to select an extended test.
v Dump
Click the arrow next to the Dump menu item to select more log options.
v Update
Click the Update menu item to start the firmware update. Click the arrow next
to the Update menu item to select Online update options.
v Config
Click the TCP/IP Port menu item to configure the TCP/IP port.
For each device on which the operation is started, a tab displays on the right panel
(Test Lab area). The tab contains the operation information and status. Only one
operation can be run at a time with ITDT-GE. The benefit in using tabs even for
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

289

the single operation mode is that you get a history of operations as for each
consecutive operation, a separate tab is opened.

Graphical Edition - Scan menu commands


The following commands are described in this section:
v Scan
v Test on page 291
v Configure TCP/IP Ports on page 292
v
v
v
v
v
v
v

Dump on page 293


Firmware Update on page 294
Firmware Update - check for updates on page 295
Encryption on page 296
Full Write on page 296
Tape Usage on page 299
System Test on page 299

v Library Diagnostic Self-Test on page 300


v Library Media Screening on page 301
v LTFS Readiness Check on page 301
v Manual Inspection Record Entry on page 301
v Copy Services on page 301

a2500240

Scan

Figure 50. Scan

290

IBM Tape Device Drivers Installation and Users Guide

The scan function is used to discover all supported tape and library devices that
are attached to the computer system. Then, they can be selected for the subsequent
ITDT-GE operations. The scan function also serves as a connection test that can be
used to verify correct attachment of the devices.
Note: When Scan is pressed for the first time, a dialog box is displayed that warns
the user to stop all backup jobs.
When the scan is finished, the device list is displayed in the Control Center area.
A scroll bar is available to show all the devices. When the device you want is
displayed, select the device for test. Only one device can be selected.

a2500241

Test

Figure 51. Test

The test function checks if the tape device is defective and outputs a pass/fail
result.
Attention:
1. The test functionality erases user data on the cartridge that is used for the test.
2. The test can take from 15 minutes up to 2 hours.
3. The test runs only on tape drives, not on autoloaders or libraries.
To start the Test function, it is recommended that a new or rarely used cartridge is
used. Scaled (capacity-reduced) cartridges must not be used to test the device.
To test tape drives within a library, the library must be in online mode.
After the device you want to test is selected, start the Test function by selecting the
Test menu item.
The Test function can be stopped by clicking Abort.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

291

Note: It can take some time until the Test function stops.

Figure 52. Test results

Note: Information can be found in the .txt/.blz files. See the log file section (1).
The test sequence contains the following steps:
1. Initialize Drive
2. Read Thermal Sensor
3.
4.
5.
6.
7.

Mount Medium
[Medium Qualification] only if previous step indicated requirement
Load/Write/Unload/Read/Verify
POST A
Performance Test (run 2 times if first run failed with performance failure)

8. Unmount Medium
9. Read Thermal Sensor
10. Get FSC
11. Get Logs

Configure TCP/IP Ports


For LTO 5, LTO 6, TS1140, and TS1150 drives, the ethernet port settings can be
configured with the Configure TCP/IP Port command. The Configure TCP/IP Port
command displays the current settings:

292

IBM Tape Device Drivers Installation and Users Guide

a2500274

Figure 53. Configure TCP/IP Ports

After you click Apply, the new values are set and the updated values display.
Note: Because earlier drive generations do not have an ethernet port, the
Configure TCP/IP Ports command is rejected for these devices with the
following message:
TCP/IP configuration is not supported on this product.

Dump
After the device you want to dump is selected, start the Dump function by
selecting Dump > Dump from the actions toolbar.

|
|

When the dump process is run on a tape library or autoloader other than the
3584/TS3500/TS4500, the Dump function stores 1 log file in the output folder of
the program (*.blz). For the 3584/TS3500/TS4500, a dump file (*.a) is stored in the
output folder. Both files start with the serial number of the device (1).

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

293

Figure 54. Dump results

Note: When the Dump function is run for tape libraries or autoloaders other than
the 3584/TS3500/TS4500, the log file contains Log Sense and Mode Sense
pages only. A Drive or 3584/TS3500/TS4500 dump contains more diagnostic
information. (2)

|
|

Firmware Update
The Firmware Update upgrades the firmware of tape drives and tape libraries. See
Supported equipment on page 214 for a list of supported products.
Note: See 3576/TS3310 tape library on page 225 for information on how to
update the firmware on a 3576/TS3310 tape library.
The following site is available for the latest firmware files: http://www.ibm.com/
storage/lto
To do a Firmware Update, run the following steps:
1. Select the device that you want to update.
2. Select the Update menu item.
3. A standard file dialog opens to select the path of where the firmware update is
located. The path is either the default input path or the location of the last
successfully opened firmware file.
4. Press OK on this file dialog to start the update on the selected device.
5. During the firmware update, a firmware update progress screen is displayed,
indicating the progress of the update.
Attention: Once started, do not interrupt the firmware update.
The firmware update usually takes 3-5 minutes, but it can take up to 45 minutes
for libraries.

294

IBM Tape Device Drivers Installation and Users Guide

Note: If ITDT-GE detects a FIPS-certified drive firmware, it shows a warning


dialog message. Before you continue, ensure that you use a FIPS-certified
firmware to update the drive.

Firmware Update - check for updates


ITDT-GE can Check for Device Updates for IBM tape drives and IBM tape
libraries. The customer can choose to select either one device or all devices by
selecting the box next to Update in the ITDT Control Center.

a2500289

The program tries to connect to IBM FixCentral and identify updates for the
devices. If the connection cannot be established or another problem occurred, the
problem description is shown at the bottom of "FixCentral" Test Tab.

Figure 55. Check for Device Updates - FixCentral components

In the sample above, the drive has two FixCentral components. Each component
has several items; such as code files and textual meta information.
The code files (binary files) have "+" in the icon to distinguish and can be
downloaded either by double-clicking or by using the right mouse button. The text
files (for example, readme files) can be viewed in the same way. A separate Test
Tab is opened and the information shown.
For tape drives an available code is colored:
v GREEN: the code level is newer than the one of the drive.
v RED: the code level is older than the one of the drive.
v BLUE: the code level is the same as the one of the drive.
For automation drives (drives in a library), both devices are used. A code level for
an automation drive is directly linked to a code level of a library.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

295

a2500290

Figure 56. Check for Device Updates - code level

Encryption
The Encryption function is used to verify whether data on the cartridge is written
encrypted. It reads both decrypted and raw data from the cartridge into two
separate files on disk. The user can then verify that the data differs to ensure that
encryption worked.
The Encryption function is only supported on encryption enabled drives and
requires an encryption infrastructure, including the Encryption Key Manager
(EKM) to be properly set up.
1. After the device you want to test is selected, start the encryption function by
selecting Test > Encryption Verification from the actions toolbar.
2. ITDT-GE then shows the Encryption Verification screen. On this screen, the
system requires the entry of the number of the start record and the amount of
data (in KB) to be read.
3. Enter the required values and click OK to start the encryption.
The Encryption function can be stopped by clicking Abort.
Note: It can take some time until the Encryption function stops.
Table 53 on page 237 defines the abort codes.

Full Write
The Full Write function writes the entire cartridge with a specified block size either
with compressible or incompressible data and output performance data.

296

IBM Tape Device Drivers Installation and Users Guide

Attention:
1. The Full Write
2. The Full Write
is written, less
3. The Full Write
libraries.

function erases data on the cartridge that is used for the test.
function takes approximately 2 hours when incompressible data
time for compressible data.
function runs only on tape drives, not on autoloaders or

The Full Write test can be used to


v Demonstrate that the drive can write the full amount of data on a cartridge.
v Reveal system performance bottlenecks.
Full Write firsts runs the test with incompressible data first, then runs the test
with compressible data. If no difference in overall performance is observed, a
bandwidth limitation might be caused by the system or cabling or HBA.
v Identify system issues with compression.
Compression is always turned on during the full write. When run with
compressible data, the output shows the compression rate. If it is higher than 1.0
but your system is not able to compress data on the cartridge, check your device
driver and software settings to see whether they disable compression.
To run a full write on tape drives within a library, the library must be in online
mode.
1. After the device you want to write to is selected, start the Full Write function
by selecting Test > Full Write from the actions toolbar.
2. Click OK to start the full write.
3. ITDT-GE then shows the Full Write screen. If no cartridge is inserted, ITDT-GE
prompts you to insert a cartridge. Either insert a cartridge and click OK or stop
by clicking Abort.

a2500227

Note: If ITDT-GE detects data on the cartridge, it shows the following message.

Figure 57. Overwrite data?

Click Yes to continue the test if you are sure that data on the cartridge
can be overwritten. If you are unsure, click No to stop the test.
4. The system prompts for entry of a transfer size between 16 KB and the
maximum block size that is supported by the system. Maximum value is 512
KB. Select the appropriate value for your system.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

297

Figure 58. Transfer size

5. Select the type of data to write, either [C] Compressible or [I] Incompressible.
The full write can be stopped by clicking Abort.
Note: It can take some time until the full write actually stops.
"Compressible = Yes" means that the data written was just zeros so that the
data can be compressed by the drive with a maximum compression ratio.
"Compressible = No" means that a data pattern was written that the drive
almost cannot compress at all. If the compression ratio is 1, the drive was not
able to compress the data (equivalent to 1:1 compression ratio). If the
compression ratio is 94.0, the drive was able to do 94:1 compression. It means
that 94 bytes in the original data was compressed to 1 byte on the medium.
100.0 means 100 bytes is compressed down to 1 byte on the medium.
If all write operations are finished, ITDT-GE shows the performance statistics
for the selected block size that is written on the cartridge, in the Status
Information area. If an error occurred during the full write, data is only
partially written.

298

IBM Tape Device Drivers Installation and Users Guide

Tape Usage

Figure 59. Tape Usage

The Tape Usage function retrieves statistical data and error counters from a
cartridge.
1. After the device you want to test is selected, start the Tape Usage function by
selecting Dump > Tape Usage Log from the actions toolbar.
2. ITDT-GE then shows the tape usage screen. If no cartridge is inserted, ITDT-GE
prompts you to insert a cartridge. Either insert a cartridge and click OK or stop
by clicking Abort.

System Test
The System Test is a short test that runs the following tests:
v Reveals system performance bottlenecks. Compressible data throughput values
can reveal bandwidth limitations that are caused by the system or cabling or
HBA.
v Measures performance variations across the different block sizes to find the ideal
block size for the system configuration.
The System Test runs only on tape drives, not on autoloaders or libraries. To run a
System Test on tape drives within a library, the library must be in online mode.
After the device you want to test is selected, start the System Test function by
selecting Test > System Test from the actions toolbar.
ITDT-GE then shows the System Test screen. If no cartridge is inserted, ITDT-GE
prompts you to insert a cartridge. Either insert a cartridge and click OK or stop by
clicking Abort.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

299

Note: If ITDT-GE detects data on the cartridge, it shows the following message Cartridge not empty!
Overwrite data?

Click Yes to continue the test if you are sure that data on the cartridge can
be overwritten. If you are unsure, click No to stop the test.

Figure 60. System Test

The System Test is run as follows:


1. System Test determines the amount of data to write for each supported
blocksize (a percentage of the cartridge is written for each blocksize).
2. The test determines the maximum supported blocksize of the system.
3. System Test writes the amount of data with all supported block sizes in powers
of two down to 16 KB. It begins with the maximum supported blocksize that is
detected before, first with incompressible, next with compressible data. Then, it
shows performance data and a progress screen.
4. At the end of the test, a summary information is shown.

Library Diagnostic Self-Test


The Library Self-Test starts and monitors the library-internal self-test. This test runs
only on libraries and autoloaders, not on tape drives.
After the device you want to test is selected, start the Library Self-Test function by
selecting Test > Library Diagnostic Self-Test from the actions toolbar.
At the end of the test, the results are shown in the Status Information area.

300

IBM Tape Device Drivers Installation and Users Guide

Library Media Screening


|

The Automated Library Media Screening test generates dumps for each drive and
cartridge within a library. It runs only on libraries (except TS3500/TS4500) and
auto-loaders, not on tape drives.
First, the test tries to read dump files from each drive that is installed from the
library. After that, the customer must select one drive for loading the cartridges.
All cartridges of the I/O and storage slots are moved - one after the other from
their source to the selected drive. A dump is taken and moved back to the source
address. In the result screen, the dumps taken and the count of dumps are shown.

LTFS Readiness Check


The LTFS Readiness Check analyzes the Operating System and tape drive
environment to ensure that the IBM Linear Tape File system can be installed. For
extended information, refer to LTFS Readiness Check on page 245.

Manual Inspection Record Entry


A manual inspection record can be generated if the device does not show in the
device list. This test is intended for devices that are not recognized or have a
technical problem that cannot be determined by ITDT-GE.
If a tape drive cannot be identified by using a device scan, the user can manually
create a test record for the drive. The system prompts the user to run the SCSI/FC
Wrap test for the drive (see the service manual for the drive). The results of the
wrap test can be entered along with extra inspection information. The results are
saved into binary and text output files that have the same format as the output
files generated by the test.
1. From the Main Program menu, select File > Manual Record.
2. Enter the required information to complete the items in the screen.
a. Enter the device serial number.
b. Enter the content of the Message Display.
c. Optionally, enter any information text.
3. After all information is entered, click OK.
The information is stored in a binary file (which can be used for further
analysis), and in a human-readable text file. Both files are stored in the
ITDT-GE output folder.

Copy Services
With the Copy and Migration Services tape content can either be copied or moved
v From a cartridge to another cartridge
v From a cartridge to an image file, or
v From an image file to a cartridge.
The tool offers different use cases like copying data or migrating data from one
generation to another. That is, data can be copied from a Gen4 cartridge to a Gen5
cartridge. Even migration from an LTO to IBM Enterprise Tape Systems is
supported. For an LTFS environment, the data can be copied or moved with the
LTFS Physical copy that adjusts the LTFS parameter on the target to be unique.
Such a copy can be used in the same LTFS environment as the source.
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

301

Tape Physical Copy


Creates a physical copy of a tape cartridge either to another cartridge or to an
image file. The created cartridge has the same physical layout and contents as the
origin cartridge. 'Tape Physical Copy' supports LTO and 3592 tape drives and can
therefore be used for data migration. A copy from previous generation to a newer
generation cartridge and from an LTO to a 3592 works. However, the amount of
used data from the source device must be equal or less than the capacity of the
destination device. If the source cartridge is partitioned, the target must support
the same partitioning sizes and amount. The amount of transferred data and the
current data transfer rate is displayed every 3-5 minutes

LTFS Physical Copy


Creates a physical copy of an LTFS formatted cartridge. The LTFS specified
parameters volumeuuid and VCI are adjusted during this copy operation. The
created cartridge has the same physical layout as the origin cartridge. Expect the
volumeuuid to be identical to the contents of the two cartridges. The amount of
transferred data and the current data transfer rate is displayed every 3-5 minutes.
When 'LTFS Physical Copy' is used with a non-LTFS formatted cartridge, the
behavior is identical to 'Tape Physical Copy'.

Verify
Verifies the physical contents of two cartridges. The physical data layout and the
binary data are compared.

Usage
By opening the "Copy Services" perspective, the user can run a 'Scan...' to discover
attached devices.

302

IBM Tape Device Drivers Installation and Users Guide

a2500294

Figure 61. Copy Services

A cartridge can be loaded or unloaded by double-clicking or pressing the right


mouse button on the drive that is used for the copy tasks. When a cartridge is
loaded, the cartridge Serial Number or the VOLSER in a library environment is
shown. If a cartridge or an image file is selected on the left, it can be used as
"Source" by pushing Select Source. After the 'Source" is selected, the target can be
chosen. To select the target, either a different cartridge in a different drive or the
image file folder can be selected. By pressing Select Target, the target is set on the
right.
If the source and the target are selected, the Copy Services or a verification can be
started regarding the used Mode: Tape Physical Copy on page 302, LTFS
Physical Copy on page 302, or Verify on page 302.

Graphical Edition - visualizing log files


ITDT-GE offers the opportunity to visualize the content of DUMP and ITDT log
files (BLOB files).
v Dump files can be retrieved with ITDT or any other tool that supports this
function.
v Dump files that are generated by ITDT have the suffix ".a" or ".b".
v BLOB files are generated during the run of an ITDT test sequence, such as
"Standard Test".
v BLOB files have the suffix ".blz".
v Both file types can be opened and visualized with ITDT-GE.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

303

a2500286

Figure 62. Graphic Edition: log view

Opening a Dump or Blob file


A Dump or a Blob file can be opened either with the menu command File/Open
Log File or by switching to the Log Files perspective and pressing Open Log File
.... In both cases, a File Selection dialog opens where the user can select files for
display. After the successful open of a file, the data is shown.
Two views are available for presenting the data - each at a separate panel.
v The Event List shows the events of this file on the left side. An event is a group
of information and consists of 1 to n Elements shown on the right. By selecting
one event list entry on the left, the corresponding data (event elements) is shown
on the right.
v The Report panel offers the opportunity to generate a sublist of the available
'Event List' entries.

Graphical Edition - Tapeutil menu commands


After the initial startup, ITDT-GE shows three figures under the top menu. After
the Tapeutil option is selected, the following page opens.

304

IBM Tape Device Drivers Installation and Users Guide

Figure 63. Tapeutil Control Center

On the left, the Tapeutil Control Center tree contains all Tapeutil commands for
tape drives and tape libraries.
The commands from the General Commands and Service Aid Commands
categories are duplicated into the two sections (to make the GUI navigation easier).
After one category is expanded, the related commands open that allows users to
select the command.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

305

a2500261

Figure 64. Tapeutil scan results

The Open command has a Scan ... button in the Parameter view. Pressing the
button runs a scan on the host and displays the attached devices in the Result
View at the bottom. This information is helpful to identify the right Device Name
for the open function. If the device is not claimed by the IBM Device Driver, the
device can be opened by the HOST BUS TARGET LUN values, e.g. the Scan
command delivers the values for Host.

306

IBM Tape Device Drivers Installation and Users Guide

a2500287

Figure 65. Generic tapeutil scan

This screen layout stays within the Tapeutil perspective until the program is
closed. Outputs of subsequent operations are added to the Results field.
Commands that fail are indicated with a red cross in the Status area. Commands
that succeed are indicated with a green check mark. The status area can be cleared
by pressing Clear.
General commands
v
v
v
v
v

Open on page 308


Close on page 309
Inquiry on page 309
Test Unit Ready on page 309
Reserve Device on page 309

v Release Device on page 309


v Request Sense on page 309
v
v
v
v

Log Sense on page 309


Mode Sense on page 309
Query Driver Version on page 310
Display All Paths on page 310

Tape drive specific commands


v Rewind on page 310
v Forward Space Filemarks on page 310
v Backward Space Filemarks on page 310
v Forward Space Records on page 310
v Backward Space Records on page 310
v Space to End of Data on page 310
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

307

v
v
v
v
v

Read and Write Tests on page 310


Read or Write Files on page 312
Erase on page 313
Load Tape on page 313
Unload Tape on page 313

v
v
v
v
v
v
v

Write Filemarks on page 313


Synchronize Buffers on page 313
Query/Set Parameter on page 313
Query/Set Position on page 314
Query Logical Block Protection on page 314
Verify Logical Block Protection on page 314
Query Partitioning Information on page 314

v
v
v
v
v
v

Create Partition on page 314


Change Partition on page 314
Remove Partition on page 314
Query Dynamic Runtime Information on page 315
List Tape Contents on page 315
Query Encryption Status on page 315

v Display Message on page 315


v Display All Paths on page 310
v Report Density Support on page 315
v Test Encryption Path on page 316
Tape library-specific commands
v Element Information on page 316
v Position to Element on page 316
v Element Inventory on page 317
v Exchange Medium on page 317
v
v
v
v
v

Move Medium on page 317


Initialize Element Status on page 317
Prevent/Allow Medium Removal on page 317
Initialize Element Status Range on page 317
Read Device IDs on page 317

v Read Cartridge Location on page 318


Service aid commands
v Configure TCP/IP Ports on page 318
v Dump/Force Dump/Dump on page 319
v Firmware Update on page 319
Note: When a command is issued in Tapeutil mode for ITDT GE, Execute must be
pressed before the action takes place.

Open
When you select the Open command:
1. ITDT checks if a device is already opened.
2. Under Device Name:, enter the name of the device in the box.

308

IBM Tape Device Drivers Installation and Users Guide

3. In the Open Mode menu, select how to open the device (rw, ro, wo, append).
4. ITDT opens the device that you selected.
Note: Always use the Read Only mode when you are working with
write-protected media.

Close
When you select the Close command
1. ITDT checks if the device is already closed.
2. ITDT closes the device.

Inquiry
When you select the Inquiry command
1. You are prompted for page code.
2. ITDT then displays a decoded format of a hexadecimal dump and prints a
hexadecimal dump of the inquiry data.

Test Unit Ready


When you select the Test Unit Ready (TUR) command, ITDT issues the Test Unit
Ready ioctl command.

Reserve Device
When you select the Reserve Device command, ITDT issues a reserve command
for the device.

Release Device
When you select the Release Device command, ITDT issues a release command for
the device.

Request Sense
When you select the Request Sense command
1. ITDT issues a Request Sense command.
2. ITDT then displays a decoded format of hexadecimal dump sense data and
prints hexadecimal dump sense data.

Log Sense
When you select the Log Sense command
1. Enter the page number, in hexadecimal, in the Page-Code field.
2. ITDT issues a Log Sense command and outputs a hexadecimal dump of that
page.

Mode Sense
When you select the Mode Sense command
1. Enter the page number, in hexadecimal, in the Page-Code field.
2. ITDT issues a Mode Sense command and outputs a hexadecimal dump of that
page.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

309

Query Driver Version


When you select the Query Driver Version command
1. ITDT issues the required command to get the driver version.
2. ITDT prints the driver version.

Display All Paths


When you select the Display All Paths command
1. ITDT issues an ioctl command.
2. ITDT outputs decoded path information for all paths.

Rewind
When you select the Rewind command, ITDT issues the ioctl rewind command for
the device.

Forward Space Filemarks


When you select the Forward Space Filemarks command
1. Enter the amount of filemarks to forward space, in the Filemark-Count box.
2. ITDT issues (extrinsic) ioctl command.
3. The tape is positioned on the first block of the next file.

Backward Space Filemarks


When you select the Backward Space Filemarks command
1. Enter the amount of filemarks to backward space, in the Filemark-Count box.
2. ITDT issues (extrinsic) ioctl command.
3. The tape is positioned on the last block of the previous file.

Forward Space Records


When you select the Forward Space Records command
1. Enter the amount of records to forward space, in the Record-Count box.
2. ITDT issues (extrinsic) ioctl command.

Backward Space Records


When you select the Backward Space Records command
1. Enter the amount of records to backward space, in the Record-Count box.
2. ITDT issues (extrinsic) ioctl command.

Space to End of Data


When you select the Space to End of Data (EOD) command, ITDT issues the
(extrinsic) ioctl command.

Read and Write Tests


When you select the Read and Write Tests command, ITDT runs the following
functions (Read and Write Test, Read Only Test, and Write Only Test). Three

310

IBM Tape Device Drivers Installation and Users Guide

parameter fields have default values already in them. Next, a Test menu that gives
you the option of Read Data from Tape, Write Data to Tape, and
Read/Write/Verify.
Note: The default is a block size of 10240 bytes, a count of 20 blocks, and a
repetition of 1. If the block size is zero, variable mode is used. With a fixed
block size, a data amount of (block size * blocks) is transferred with a single
operation. This operation might get rejected if the total amount exceeds the
transfer size of the system.
The following steps are run, depending on which test is selected.
v The Read/Write steps:
Issues a Read Position.
Sets block size.
Generates special pattern.
Puts block id in bytes 0-3 of each block.
Prints current block number, number of bytes and blocks.
Issues write command.
Prints updated statistics.
If number of bytes written is different from requested bytes to write, stop
(go to Step 19).
9. Writes two filemarks.
10. Backward spaces two filemarks.
1.
2.
3.
4.
5.
6.
7.
8.

11. Backward spaces number of records written.


12. Prints amount of data to read.
13. Issues read command.
14. If read error occurred or number of bytes read is different from requested
number of bytes to read, go to Step 19.
15. Compares data that is read with data written, show miscompares and if
miscompares exist, stop (go to Step 19).
16. If compare is OK, print OK message.
17. Forward space one file mark.
18. Repeat Steps 10 - 24 until all blocks are written, or go to Step 4 until all
blocks are written.
19. Prints current block id and total number of bytes written.
v The Read Only steps:
1.
2.
3.
4.
5.

Issues a Read Position.


Sets block size.
Generates special pattern.
Print amount of data to read.
Issues read command.

6. If read error occurred or number of bytes read is different from requested


number of bytes to read, stop (go to Step 19).
7. Compares data that is read with buffer data, show miscompares and if
miscompares exist, stop (go to Step 19).
8. If compare is OK, print OK message.
9. Repeat Steps 10 - 15 until all blocks are written, or go to Step 4 until all
blocks are written.
10. Prints current block id and total number of bytes read.
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

311

11.
12.
13.
14.
15.
16.
17.
18.
19.

Backward spaces number of records written.


Prints amount of data to read.
Issues read command.
If read error occurred or number of bytes read is different from requested
number of bytes to read, go to Step 19.
Compares data that is read with data written, show miscompares and if
miscompares exist, stop (go to Step 19).
If compare is Ok, print OK message.
Forward space one file mark.
Repeat Steps 10 - 24 until all blocks are written, or go to Step 4 until all
blocks are written.
Prints current block id and total number of bytes written.

v The Write Only steps:


1. Issues a Read Position.
2.
3.
4.
5.
6.

Sets block size.


Generates special pattern.
Put block id in bytes 0-3 of each block.
Prints current block number, number of bytes and blocks.
Issues write command.

7. Prints updated statistics.


8. If number of bytes written is different from requested bytes to write, stop
(go to Step 10).
9. Repeat Steps 5 - 9 until all blocks are written, or to Step 4 until all blocks
are written.
10. Print current block id and total number of bytes written.

Read or Write Files


When Read or Write Files is selected, a box under File Name: is where the path
and name of the file is entered. Under that is a box named Number of records to
read (0 for entire file). The default amount in the box is 100. Next, a menu bar
under Test: gives you the choice of Read File from Tape or Write File to Tape.
Once the Test is selected, Browse appears next to the File Name box to allow
browsing for the needed file. When you select the Read or Write Files command,
ITDT runs the following functions:
v Read steps:
1. Prompts if to read a file from tape
2. You are prompted for destination file name
3. You are prompted for number of records to read (If you press Enter, the
entire file is read.)
4. Prints the file name to be opened
5. Opens the file (r/w with large file support, 666 umask)
6. Issues Query Parameters ioctl command, if it fails, quit
7. Sets blocksize to maximum, variable blocksize mode
8.
9.
10.
11.

312

Calculates the number of blocks to read.


Prints number of records to read.
ITDT read from tape.
Writes to file, stop if data count is not equal to data count requested.

IBM Tape Device Drivers Installation and Users Guide

12. If more data to read, go to Step 10.


13. Prints statistics.
v Write steps:
1. Prompts if to write a file to tape.
2. You are prompted for the source file name.
Prints the file name to be opened.
Opens the file (r/o with large file support).
Issues Query Parameters ioctl command, if it fails, quits.
Sets blocksize to maximum, variable blocksize mode
Prints write statement.
Reads from file.
Writes to tape, stop if data counts written is not equal to data count
requested.
10. Prints statistics.
3.
4.
5.
6.
7.
8.
9.

Erase
When you select the Erase command, ITDT issues the (extrinsic) ioctl command.

Load Tape
ITDT issues a SCSI Load command to load a tape.

Unload Tape
When you select the Unload Tape command
1. ITDT issues the (extrinsic) ioctl command.
2. The tape rewinds and then unloads.

Write Filemarks
When you select the Write Filemarks command
1. In the Filemark-Count box, enter the number of filemarks to write.
2. ITDT issues the (extrinsic) ioctl command.

Synchronize Buffers
When you select the Synchronize Buffers command, ITDT issues the ioctl
command.

Query/Set Parameter
When you select the Query/Set Parameter command
1. ITDT shows the changeable parameters.
Note: The list of changeable parameters are operating system specific. For a list
of changeable parameters, refer to Table 56 on page 272.
2.
3.
4.
5.

Select from the list of parameters that can be changed by clicking the choice.
ITDT requests prompt for parameter value (if required).
ITDT requests safety prompt (if required).
ITDT issues the ioctl command.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

313

Query/Set Position
When you select the Query/Set Position command
1. ITDT prints the current position and requests the new position.

2.

3.
4.
5.
6.
7.
8.
9.

Note: ITDT does not distinguish between logical and physical position. It
shows the current position and queries for the one to set, then sets the
new position.
Enter the block id for where the tape must go. This block id must be entered
in decimal. When the tape is set, the block id is printed in decimal with
hexadecimal in parentheses.
ITDT issues the Set Position ioctl and returns the pass or fail results.
ITDT prints decoded logical position details.
ITDT issues Query Physical Position ioctl command.
ITDT prints decoded physical position details.
You are prompted for position to set (logical or physical) or to stop.
You are prompted for the block id in decimal or hexadecimal.
ITDT prints a summary.

10. ITDT issues the Set Position ioctl command.


11. Repeat steps 2 - 5.

Query Logical Block Protection


When you select the Query Logical Block Protection command, ITDT displays
the logical block protection status.

Verify Logical Block Protection


When you select the Verify Logical Block Protection command, ITDT runs the
verification of logical block protection written blocks from current tape position to
End of Data.

Query Partitioning Information


When you select the Query Partitioning Information command, ITDT displays
the cartridge partitioning information.

Create Partition
When you select the Create Partition command
1. ITDT creates a partitioned cartridge.
2. Number of partitions, partition type, and partition size can be specified.

Change Partition
When you select the Change Partition command, ITDT changes the current tape
position to a new specified Partition Number and Block ID.

Remove Partition
When you select the Remove Partition command, ITDT removes all data and the
cartridge partitioning information.

314

IBM Tape Device Drivers Installation and Users Guide

Query Dynamic Runtime Information


When you select the Query Dynamic Runtime Information command
1. ITDT queries the dynamic runtime information.
2. Dynamic runtime information allows an initiator to set dynamic runtime
attributes (DRA) about itself into a device server.
3. The device server then associates those attributes to the I_T_L nexus and uses
the information and associations for enhanced data collection and debugging.

List Tape Contents


When you select the List Tape Contents command
1. ITDT displays the content of a tape.
2. The output lists filemarks and the size of each record found on the tape until
the end of data is reached.

Query Encryption Status


When you select the Query Encryption Status command
1. ITDT issues Get Encryption State ioctl command.
2. ITDT displays encryption settings (Drive EC, Encryption Method, Encryption
state).

Display Message
When you select the Display Message command
1. ITDT provides Parameter boxes in which you can enter 1 or 2 messages up to
8 characters.
Note: Display Message works only on drives that have a display pane, the 3590
and 3592 drives.
2. In the Type: menu, select which message (0 or 1) you want shown and if you
want it to flash. There is also an alternate (alt) selection that alternates between
messages.
3. ITDT issues the ioctl command.
4. ITDT prints the displayed message.

Display All Paths


When you select the Display All Paths command
1. ITDT issues an ioctl command.
2. ITDT outputs decoded path information for all paths.

Report Density Support


When you select the Report Density Support command
1. ITDT prints report status text for all supported media.
2. ITDT issues Report Density Support ioctl command to retrieve all supported
media.
3. ITDT prints all requested reports. Data is printed in a decoded way. Scroll the
screen to print each one of the following status texts:
v Density name
v Assigning organization
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

315

v
v
v
v
v

Description
Primary density code
Secondary density code
Write OK
Duplicate

v Default
v Bits per MM
v Media Width
v Tracks
v Capacity (megabytes).
4. ITDT prints report status text for current media.
5. ITDT issues Report Density Support ioctl command to retrieve current media.
6. ITDT prints report data in a decoded way.

Test Encryption Path


When you select the Test Encryption Path command
Note: Not supported for the HP-UX operating system.
1. ITDT prints status message that server configuration and connections are
tested.
2. ITDT issues the Encryption Diagnostics ioctl command, Ping Diag.
3. ITDT prints number of servers available or error message.
4. ITDT issues the Encryption Diagnostics ioctl command, Basic Encryption
Diag.
5. ITDT prints completion code or error message.
6. ITDT issues the Encryption Diagnostics ioctl command, Full Encryption Diag.
7. ITDT prints completion code or error message.

Element Information
When you select the Element Information command:
1. ITDT issues the ioctl command.
2. ITDT shows
v Number of robots
v First robot address
v Number of slots
v First slot address
v Number of I/E elements
v First element address
v Number of drives
v First drive address

Position to Element
When you select the Position to Element command:
1. In the Parameter boxes, the Transport element address must be entered, in
decimal (picker).
2. Insert the Destination element address in decimal.

316

IBM Tape Device Drivers Installation and Users Guide

3. ITDT issues the ioctl command.

Element Inventory
When you select the Element Inventory command:
1. ITDT issues the Element Info ioctl command.
2. ITDT issues the Element Inventory ioctl command.
3. ITDT displays decoded element inventory information.

Exchange Medium
When you select the Exchange Medium command:
1. Insert source address into the Source address box in Decimal.
2. Insert the first destination address in decimal in the First destination address
box.
3. Insert the second destination address in decimal in the Second destination
address box.
4. ITDT issues the ioctl command.

Move Medium
When you select the Move Medium command:
1. Insert source element address into the Source element address box in Decimal.
2. Insert the first destination element address in decimal in the First destination
element address box.
3. Insert the second destination element address in decimal in the Second
destination element address box.
4. ITDT issues the ioctl command.

Initialize Element Status


When you select the Initialize Element Status command:
1. ITDT issues the ioctl command.
2. ITDT prints the command summary.

Prevent/Allow Medium Removal


When you select the Prevent/Allow Medium Removal command:
1. Use the menu to either prevent or allow.
2. ITDT issues the ioctl command.

Initialize Element Status Range


When you select the Initialize Element Status Range command:
1. Insert the first slot address in decimal in the provided box.
2. Insert the number of slots in the provided box.
3. ITDT issues the ioctl command.

Read Device IDs


When you select the Read Device IDs command:
1. ITDT issues the Element Info ioctl command.
2. If no drive is present, ITDT prints NO DRIVE PRESENT and exits.
Chapter 8. IBM Tape Diagnostic Tool (ITDT)

317

3. ITDT prints information for all drives.

Read Cartridge Location


When you select the Read Cartridge Location command:
1. You are prompted for address of the first element.
2. If address is zero, print the error message and exit.
3. You are prompted for the number of elements.
4. If the number of elements is zero, print the error message and exit.
5. ITDT issues the Element Info ioctl command.
6. ITDT verifies that the address range is valid. Otherwise, print the error
message and exit.
7. If no slots are found in Element Info data; print the error message and exit.
8. ITDT issues the READ_CARTRIDGE_LOCATION ioctl command.
9. ITDT prints decoded storage element information.

Configure TCP/IP Ports


For LTO 5, LTO 6, TS1140, and TS1150 drives, the ethernet port settings can be
configured with the Configure TCP/IP Port command. The Configure TCP/IP Port
command displays the current settings:

a2500272

Figure 66. Configure TCP/IP Ports command in the Graphical Edition

After you click Apply, the new values are set and the updated values display.
Note: Because earlier drive generations do not have an ethernet port, the
Configure TCP/IP Ports command is rejected for these devices with the
following message:
TCP/IP configuration is not supported on this product.

318

IBM Tape Device Drivers Installation and Users Guide

Dump/Force Dump/Dump
When you select the Dump/Force Dump/Dump command:
1. ITDT retrieves the dump.
2. ITDT issues the Force Dump command.
3. ITDT retrieves the second dump.
4. ITDT displays the name of stored dump files and the output directory where
they are stored. The dump filenames start with the serial number of the device.

Firmware Update
When you select the Firmware Update command, browse to the microcode file to be
used. ITDT runs the firmware update and displays progress status and result.
Note: See 3576/TS3310 tape library on page 286 for information on how to
update the firmware on a 3576/TS3310 tape library.
The following site is available for the latest firmware files: http://www.ibm.com/
support/fixcentral/. Select System Storage > Tape Systems > Tape autoloaders
and libraries or Tape drives.

Chapter 8. IBM Tape Diagnostic Tool (ITDT)

319

320

IBM Tape Device Drivers Installation and Users Guide

Appendix A. Accessing documentation and software online


IBM maintains the latest levels of tape drive and library device drivers and
documentation on the Internet. Fix Central is a portal where you can download the
latest version of drivers for most of the IBM tape products. In this download area,
you find menus that can guide you to find what you need.
To access to tape Device Drivers or software downloads, click
http://www-933.ibm.com/support/fixcentral/?productGroup0=System%20Storage
&productGroup1=ibm/Storage_Tape&productGroup2=Tape%20drivers%20and
%20software&productGroup3=ibm/Storage_Tape/Tape%20device%20drivers.
Choose your platform, then click Continue. Alternately, you can follow these steps.
1. Access the Fix Central URL at http://www.ibm.com/support/fixcentral.
2. In the Product Group menu, select System Storage.
3. From the System Storage menu, select Tape systems.
4. In the Tape systems menu, select Tape drivers and software.
5. In the Select from Tape drivers and software menu, select Tape device
drivers. You are also able to get tools such as ITDT.
6. The Platform menu displays. Select the platform that you are looking for, then
click Continue to view what is available for the selected platform.
7. In the next screen, there is a list of the latest Tape device drivers or Tape
Diagnostic tools versions. Select the package that you need, then click
Continue.
Note:
v The latest driver has the highest number extension. Numeric
sequence numbers are in each level of the device and library driver.
So, for example, for AIX the number is Atape.11.7.5.0.bin. As newer
levels of a driver are released, a higher numeric sequence is assigned.
When a driver is downloaded, ITDT also appears as a recommended
download if you selected the option of co-requisites and prerequisite.
v As of January 31, 2012, each IBM client that accesses Fix Central
(whether through their employees or other authorized
representatives) is required to have an individual IBM ID to
download fixes (some exemptions might apply). The registration is
quick and simple and provides users with a customized experience
to better serve their needs.
8. After you click Continue, you can choose the way that you want to download
the fix or fixes. You can either use your browser (HTTP), the Download
Director (http://www6.software.ibm.com/dldirector/doc/
DDfaq_en.html#Q_A1), or bulk FTP option. The bulk FTP option is a web
service where you can download a package with the FTP command or other
download commands like WGET.
Note:
v To use the Download Director, ensure that the Java Runtime
Environment is installed on your computer. For information, see
http://www6.software.ibm.com/dldirector/doc/DDfaq_en.html.
Leave the check box for prerequisites and co-requisites selected. Click
Continue.
Copyright IBM Corp. 2007, 2014

321

v When you select the download option before Continue is pressed,


you can change the way that you want to download the fix or fixes
from the Change download options link at the top of the page.
9. Sign in, then click Submit.
10. Click I agree on the Terms and Conditions screen to continue.
11. A list of files and downloadable files displays, including links to
Documentation, Programming guides, User guides, and readme files.
Note: Some plain text files might require you to right-click, then select Save
Link As... to download the file.
Table 57 documents each driver by name and description.
Table 57. Driver descriptions
Driver

Description

Atape.n.n.n.n.bin

AIX Device Driver


(Atape)

.../atdd.n.n.n.n.bin

HP-UX Device Driver

/lin_tape_source-lin_taped/lin_tape-x.x.x.x-x.src.rpm.bin

Linux Device Driver


(lin_tape) source code

/lin_tape_source-lin_taped/lin_taped-x.x.x-dist.arch.rpm.bin

Linux lin_taped
daemon program

/IBMtape.n.n.n.n.bin

Solaris Device Driver


(IBMtape)

/IBMTape.arch_wXX_nnnn.zip

Windows Server 20XX


Driver on arch (x86,
x64) where XX
denotes the version
(such as, 2008, 2012)

Note:
1. Valid for Windows 2008 and Windows 2008 r2
2. dist indicates a Linux distribution. arch indicates a machine architecture (for example,
i386, ia64, s390).
3. The n.n.n. or n.n.n.n strings are replaced with digits to reflect the version of each driver.

v For details on supported tape attachment, refer to the System Storage


Interoperation Center website - http://www.ibm.com/systems/support/
storage/config/ssic/.
v Information concerning supported Fibre Channel host bus adapters (HBAs) and
associated HBA device drivers, firmware, and BIOS levels can be obtained from
the System Storage Interoperation Center website - http://www.ibm.com/
systems/support/storage/config/ssic/.
v The IBM_Tape_Driver_IUG.pdf file contains the current version of the IBM Tape
Device Drivers: Installation and User's Guide, which can be found here:
http://www-01.ibm.com/support/docview.wss?rs=577&iud=ssglS7002972. You
can also use the links that are located under Related Information to get quick
access to the download section for the tape device drivers.
v The IBM_Tape_Driver_PROGREF.pdf file contains the current version of the
IBM Tape Device Drivers: Programming Reference, which can be found here:
http://www-01.ibm.com/support/docview.wss?uid=ssg1S7003032.
v For the current information for the device driver you are using, consult the
readme file (not files) included in the download of your device driver.

322

IBM Tape Device Drivers Installation and Users Guide

Use the links listed below for quick access to the download section for every
tape Device Driver platform.
v AIX. Path: Storage Systems > Tape Systems > Tape device drivers and software
> Tape device drivers > AIX, or http://www-933.ibm.com/support/fixcentral/
swg/selectFixes?parent=ibm~ST~Tapedevicedriversandsoftware&product=ibm/
Storage_Tape/Tape+device+drivers&release=1.0&platform=AIX&function=all.
v HPUX. Path: Storage Systems > Tape Systems > Tape device drivers and
software > Tape device drivers > HPUX, or http://www-933.ibm.com/support/
fixcentral/swg/selectFixes?parent=ibm~ST~Tapedevicedriversandsoftware
&product=ibm/Storage_Tape/Tape+device+drivers&release=1.0
&platform=HPUX&function=all.
v Linux. Path: Storage Systems > Tape Systems > Tape device drivers and
software > Tape device drivers > Linux, or http://www-933.ibm.com/support/
fixcentral/swg/selectFixes?parent=ibm~ST~Tapedevicedriversandsoftware
&product=ibm/Storage_Tape/Tape+device+drivers&release=1.0&platform=Linux
&function=all.
v Solaris. Path: Storage Systems > Tape Systems > Tape device drivers and
software > Tape device drivers > Solaris, or http://www-933.ibm.com/
support/fixcentral/swg/
selectFixes?parent=ibm~ST~Tapedevicedriversandsoftware&product=ibm/
Storage_Tape/Tape+device+drivers&release=1.0&platform=Solaris&function=all.
v Windows. Path: Storage Systems > Tape Systems > Tape device drivers and
software > Tape device drivers > Windows, or http://www-933.ibm.com/
support/fixcentral/swg/
selectFixes?parent=ibm~ST~Tapedevicedriversandsoftware&product=ibm/
Storage_Tape/Tape+device+drivers&release=1.0&platform=Windows
&function=all.
v Windows WHQL. Path: Storage Systems > Tape Systems > Tape device drivers
and software > Tape device drivers > Windows WHQL, or
http://www-933.ibm.com/support/fixcentral/swg/
selectFixes?parent=ibm~ST~Tapedevicedriversandsoftware&product=ibm/
Storage_Tape/Tape+device+drivers&release=1.0&platform=Windows+WHQL
&function=all.

Appendix A. Accessing documentation and software online

323

324

IBM Tape Device Drivers Installation and Users Guide

Appendix B. Verifying correct attachment of your devices


Before you start to use your devices for production work with your applications,
or if you encounter difficulties with your devices, you might want to verify that
the hardware, connections, and device drivers are working together properly.
Before you can do this verification, you must do the following procedure 1. Install your hardware as indicated in the appropriate hardware manuals.
2. Power On your hardware and verify that the hardware is functioning properly
by running commands according to the product documentation. See "IBM Tape
Product Publications on page xiii.
3. Attach your hardware to the host system as indicated in the appropriate
hardware manuals and as indicated in the appropriate chapters from this
manual.
4. Start your operating system as indicated in the appropriate chapters from this
manual.
5. Log in to the operating system as Administrator.
6. If device drivers are used by your device other than the ones documented in
this manual, disable the other device drivers, and install or enable the drivers
that are documented in this manual.
7. Start ITDT (for instructions see Starting ITDT - Standard Edition on page
219).
8. Scan for devices. Any devices that show up are properly attached.

Platform-specific help
There is a problem determination section for each platform.
v AIX: Problem determination on page 35
v HP-UX: Problem determination on page 68
v Linux: Problem determination on page 96
v Solaris: Problem determination on page 137
v Windows: Problem determination on page 154

IBM technical support


If the problem persists after these procedures are followed, it is possible that an
unexpected condition occurred in the drivers environment. In this case, contact
your IBM service representative (1-800-IBM-SERV) and provide the following
information to help IBM re-create and resolve the problem:
1. Machine type and model of your IBM tape product
2.
3.
4.
5.

Specific driver version


Description of the problem
System configuration
Operation that was running at the time the problem was encountered

Copyright IBM Corp. 2007, 2014

325

326

IBM Tape Device Drivers Installation and Users Guide

Appendix C. Managing the microcode on the IBM tape drive


Microcode is computer software that is stored in nonvolatile storage on your tape
device or library hardware. It controls the operation of your hardware. When your
tape device or library hardware was manufactured, a microcode load was installed
and shipped with your device.
If you are having trouble with your hardware, IBM service personnel ask what
level of microcode you have on your hardware. If they believe that you need a
new level of microcode, they might instruct you to install a newer level of
microcode on your hardware. They can provide you with updated microcode.
You can query the current level of microcode by issuing commands on the front
panel of your hardware. Consult the appropriate hardware reference manual for
specific instructions on querying your microcode level.
If your device is connected to a host system that has device or library support, you
can also query the last 4 digits of the current level of microcode with software.
Refer to Chapter 8, IBM Tape Diagnostic Tool (ITDT), on page 211. The unit must
be powered On, configured properly, and ready. For information, refer to the
appropriate chapter in this document (based on the operating system/platform) for
details on how to have the device ready.
The following instructions are a guide to install another version of microcode on a
tape drive.
1. Ensure that the tape drive is connected to a host system and that the tape
device driver is powered-On and configured properly with no tape cartridge in
the drive. Follow the instructions in Appendix B, Verifying correct attachment
of your devices, on page 325 to ensure that the drive is configured properly
and ready.
2. Open ITDT and follow the instructions for downloading microcode. These
instructions are in both the SE and the GE versions. In SE, it is available in all
sections; scan menu under Firmware update, the tape utility (71) section, and
the scripting (ucode) command.

Copyright IBM Corp. 2007, 2014

327

328

IBM Tape Device Drivers Installation and Users Guide

Notices
References in this publication to IBM products, programs, or services do not imply
that IBM intends to make these available in all countries (or regions) in which IBM
operates.
Any references to an IBM program or other IBM product in this publication is not
intended to state or imply that only IBMs program or other product may be used.
Any functionally equivalent program that does not infringe any of IBMs
intellectual property rights may be used instead of the IBM product. Evaluation
and verification of operation in conjunction with other products, except those
expressly designed by IBM, is the users responsibility.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You may send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte character set (DBCS) information,
contact the IBM Intellectual Property Department in your country or send
inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other
country (or region) where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS
FOR A PARTICULAR PURPOSE. Some states (or regions) do not allow disclaimer
of express or implied warranties in certain transactions, therefore, this statement
cannot apply to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes are
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the products and/or programs described in this publication at
any time without notice.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

Copyright IBM Corp. 2007, 2014

329

The ITDT-SE and ITDT-GE software uses Henry Spencer's regular expression
library that is subject to the following copyright notice:
"Copyright 1992, 1993, 1994, 1997 Henry Spencer. All rights reserved. This software
is not subject to any license of the American Telephone and Telegraph Company or
of the Regents of the University of California.
Permission is granted to anyone to use this software for any purpose on any
computer system, and to alter it and redistribute it, subject to the following
restrictions:
1. The author is not responsible for the consequences of use of this software, no
matter how awful, even if they arise from flaws in it.
2. The origin of this software must not be misrepresented, either by explicit claim
or by omission. Since few users ever read sources, credits must appear in the
documentation.
3. Altered versions must be plainly marked as such, and must not be
misrepresented as being the original software. Since few users ever read
sources, credits must appear in the documentation.
4. This notice cannot be removed or altered.

Trademarks
The following terms are trademarks of International Business Machines
Corporation in the United States, other countries (or regions), or both:
AIX
AIX 5L
FICON
HyperFactor
i5/OS
iSeries
IBM

IBMLink
Magstar
Micro Channel
Netfinity
POWER5
ProtecTIER
pSeries

RS/6000
S/390
StorageSmart
System i
System p
System Storage
System x

System z
Tivoli
TotalStorage
Virtualization Engine
xSeries
z9
zSeries

Adobe and Acrobat are either registered trademarks or trademarks of Adobe


Systems Incorporated in the United States, and/or other countries.
Intel, Itanium, and Pentium are trademarks of Intel Corporation in the United
States, other countries (or regions), or both.
Java and all Java-based trademarks are trademarks of Oracle, Inc. in the United
States, other countries, or both.
Linux is a registered trademark of Linus Torvalds in the United States, other
countries, or both.
Microsoft, Windows, Windows NT, and Windows 2000 are trademarks of Microsoft
Corporation in the United States, other countries (or regions), or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries (or regions).
Other company, product, and service names may be trademarks or service marks
of others.

330

IBM Tape Device Drivers Installation and Users Guide

Index
Numerics
3494 Enterprise tape library attachment
test 183, 191, 196, 202, 209
3494 Enterprise Tape Library driver 170,
171, 172
3494 Enterprise Tape Library
support 159, 169, 173, 174, 175, 176

A
about data encryption 7
Accessing 212
ACTRC utility 42
adding or deleting entries in the
library 199
adding or deleting entries in the library
device 187, 193
adding or deleting libraries to the
service 205
adding or removing devices 124
Adding or removing devices 145
AIX (Atape) 1, 15, 16, 17, 18, 19, 25, 26,
27, 28, 30, 32, 33, 34, 35, 36, 37, 38, 40,
41, 42, 45, 46
AIX 3494 Enterprise Tape Library 176,
177, 183, 184
AIX device parameters 45
Alternate pathing 19
asynchronous library operations 175
ATDD implementation 47
ATDD installation script 53
ATRC utility 41
autoloading 19
automatic dump facility for 3590 and
Magstar MP tape drives 40
Automatic failover 1

B
block size 19
buffered mode 19
bulk rekey 13

C
capacity scaling 25
changeable parameters 82
Checklist 10
command sequence information 50, 187
Comments xv
common utilities 45
compatibility 186
component tracing 41
components created during
installation 74
compression 19
configuration 10, 35
Configuration parameter definitions 58,
59
Copyright IBM Corp. 2007, 2014

configuration parameters 79, 80, 82, 119


Configuration parameters 19
configuring and unconfiguring path
failover support 32
configuring and unconfiguring primary
and alternative devices 34
configuring Library Manager Control
Point 177
configuring tape and medium changer
devices 17
Configuring Tape and Medium Changer
devices 76, 77
configuring the 3490E or Enterprise Tape
System 3590 tape drive 177
configuring the serial port 177, 199
connecting Enterprise 3494 tape
library 193
connecting the 3494 Enterprise tape
library 199
Connecting the 3494 Enterprise tape
library 205
connecting the Enterprise tape
library 187
Connecting the Enterprise Tape
Library 177
connectivity 35
Control path failover 30
conventions used 74
copying software to software depot 53
create an FMR tape 42
creating device-specific configuration
entries (optional) 51
creating drive configuration file, if
required 51
creating hardware path entry 51

Detail data 38
detailed description 42
determining device hardware path for
IBM tape drives 51
Device and volume information
logging 36, 37
device behaviors 128
Device driver configuration 34
Device driver management 146
device driver trace facility 184
device-specific parameters 58
disable procedure 146
drive dump 35
driver message queue 171
driver-specific parameters 59
Dump device commands 35
Dump support 35
Dynamic Runtime Attributes 40, 123

E
EKM server logs 35
emulate autoloader 19
emulation and MTLIB 174
emulation design 173
encryption 1
encryption key manage configuration
file 10
error labels 38
error log analysis 42
error log templates 38
error logging 35, 38, 184, 191, 196, 202
Error logging 68

F
D
daemon trace facility 184, 191, 196, 202,
209
data flow 176, 185, 192, 197, 203
Data flow 15, 47, 73, 103
data path 45
data path failover 1
Data path failover 32
Deconfiguring the 3490E, 3590, Magstar
MP, or 7332 tape device 18
Deconfiguring the 3575, 7331, 7334, 7336,
or 7337 medium changer device 18
deconfiguring the Library Manager
Control Point 177
defining tape libraries to the
daemon 177
Defining the library device to
LMCPD 187
defining the library device to the
lmcpd 193
defining the symbolic name to the
lmcpd 199
Defining the symbolic name to the
service 205

fail degraded media 19


failover 10
field support 35
file naming conventions 128
force microcode dump 42
functional verification 137

G
general information 7

H
hardware requirements 48, 103, 145, 177,
186, 192, 198, 204
Hardware requirements 15, 73
HP-UX 49
HP-UX (ATDD) 47, 48, 49, 50, 51, 52, 53,
57, 58, 59, 61, 63, 68, 69, 70
HP-UX 3494 Enterprise Tape
Library 185, 186, 187, 191
HP-UX System testing 191

331

Installation and configuration


instructions 15, 16, 17, 18, 49, 73, 74,
75, 76, 77, 79, 104, 105, 124, 125, 145
installation instructions 177, 193, 199,
205
Installation instructions 187
installation overview 146, 187
installation problems 138
installation procedure 75, 177, 193, 205
Installation procedure 16
installation procedures 146
Installation, removal, and
configuration 105, 119, 123
Installing and configuring DLKM PCI
drivers 49, 50, 51, 52, 53
installing and updating IBMtape 105
installing driver manually 53
installing manually 187
installing the ATDD software 53
Introduction and product
requirements 1, 73, 145, 211
Introduction and Product
Requirements 103
iostat utility 46
ITDT 211, 212

new logical name 19


nonchangeable parameters

L
library control path failover 63
library driver information 176
Library driver information 170, 171, 172
library emulation 173, 174, 175
Library Manager event notification 170
library requirements 7
library-managed encryption
planning 13
libsmc extension 173
Linux (lin_tape) 73, 74, 75, 76, 77, 79, 80,
82, 85, 86
Linux 3494 Enterprise Tape Library 192,
193, 196
Linux system-managed encryption 94
Linux verification testing 196
Load balancing 1
loading the daemon 177
log file 37
logging 19
logical write protect 25

M
managing encryption 7
Managing microcode on the tape
drive 327
maximum size of the log file 19
media parameters 25
microcode load 42
Microsoft Windows system testing 209
modifying configuration parameters 59
MTEVENT program 169
mtlib command 159
MTLIB program 159

332

80

O
operation complete notification 170
other administrative tasks 187
overview 173
Overview of the installation process 50

P
path failover 1
Path failover 1
Path failover support 32, 33, 34
performance considerations 175
Performance considerations 45, 46
Persistent naming support 28
Persistent Naming Support 63, 129
powering off tape drives 52
preinstallation considerations 16, 105,
199
Preinstallation considerations 50
preventing conflicts with other device
drivers 104
primary and alternative paths 33
problem determination 138, 184, 191,
196, 202, 209
Problem determination 35, 38, 40, 41, 42
Problems and solutions 70
product requirements 176, 177, 185, 186,
192, 197, 198, 203, 204
Product requirements 15, 47, 48, 73
Product requirements and
compatibility 103, 145
programs 169
Purpose 1, 15, 211

Q
querying drive configuration 35
querying installed package 76
querying primary and alternate path
configuration 33
querying the installed package 193

R
read dump 42
read error recovery time 19
record space mode 19
Related information
Additional information xv
AIX xiv
HP-UX xiv
Linux xiv
Microsoft Windows xiv
Solaris xiv
Related Information xiii
removal procedure 146
removing IBMtape 124
requirements
library 7
tape 7

IBM Tape Device Drivers Installation and Users Guide

Reservation conflict logging 37


reservation key 19
reservation type 19
reset drive 42
retain reservation 19
rewind immediate 19

S
sample configuration file 10
SCSI status busy retry 19
sense data 35
Sense data logging 68
server logs 35
Service and diagnostic aids 137, 138,
139, 141
setting the IBM_trace level 141
SMC library names 174
SMIT panels 34
software compatibility 198, 199, 204
software interface 170
software interface to device driver 48
software requirements 48, 103, 145, 177,
186, 192, 198, 199, 204
Software requirements 15, 73
Solaris (IBMtape) 103, 104, 105, 119, 123,
124, 125, 127, 128, 129, 135, 137, 138,
139, 141
Solaris 3494 Enterprise Tape
Library 197, 198, 199, 202
Solaris verification testing 202
special files 127, 128, 183
Special files 26, 27, 61, 85, 86
Special files for 3490E, 3590, Magstar MP,
or 7332 tape devices 26
Special files for 3575, 7331, 7334, 7336, or
7337 medium changer devices 27
Special files for medium changer
device 86
Special files for tape device 85
starting ibmatl 193
Support_info script 68
Supported configurations 57
supported hardware 1
synchronous and asynchronous
operations 170
system encryption 19
system encryption for Write
commands 19
System p 77
System z 77
system-managed encryption 94, 135
System-managed encryption 34, 153
system-managed encryption
configuration 10

T
Tape drive service aids 42
Tape drive, media, and device driver
parameters 19, 25, 79, 80, 82
Tape library support programs 159
tape log utility 37
Tapelist Utility Program 125
testing data encryption configuration 35
timeout value 10

trace facility 41
tracing facility 139
Tracing facility 69
trailer labels 19
Troubleshooting 68, 69, 70

U
unconfiguring tape devices 125
uninstall procedure 18, 79, 177
uninstallation procedure 187, 193, 199,
205
uninstalling the device drivers 146
unsolicited notification 171
updating procedure 76, 193

V
Verifying device attachment 325
verifying the install/update 193
Virtual Tape Server subsystem
attachment 172
Virtual Tape Server Subsystem
Attachment 176
volume categories 171, 174
volume ID for logging 25

W
Windows (IBMtape) 145
Windows 3494 Enterprise Tape
Library 203, 204, 205, 209
Windows device driver 145, 146
Windows NT 145
Windows system-managed
encryption 153

Index

333

334

IBM Tape Device Drivers Installation and Users Guide

Readers Comments We'd Like to Hear from You


IBM Tape Device Drivers
Installation and Users Guide
Publication No. GC27-2130-20
We appreciate your comments about this publication. Please comment on specific errors or omissions, accuracy,
organization, subject matter, or completeness of this book. The comments you send should pertain to only the
information in this manual or product and the way in which the information is presented.
For technical questions and information about products and prices, please contact your IBM branch office, your
IBM business partner, or your authorized remarketer.
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any
way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use
the personal information that you supply to contact you about the issues that you state on this form.
Comments:

Thank you for your support.


Send your comments to the address on the reverse side of this form.
If you would like a response from IBM, please fill in the following information:

Name

Address

Company or Organization
Phone No.

Email address

GC27-2130-20



___________________________________________________________________________________________________

Readers Comments We'd Like to Hear from You

Cut or Fold
Along Line

_ _ _ _ _ _ _Fold
_ _ _and
_ _ _Tape
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please
_ _ _ _ _do
_ _not
_ _ staple
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Fold
_ _ _and
_ _ Tape
______
NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES

BUSINESS REPLY MAIL


FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK
POSTAGE WILL BE PAID BY ADDRESSEE

International Business Machines Corporation


Information Development
Department GZW
9000 South Rita Road
Tucson, Arizona 85775-4401

_________________________________________________________________________________________
Fold and Tape
Please do not staple
Fold and Tape

GC27-2130-20

Cut or Fold
Along Line



Printed in USA

GC27-2130-20



Spine information:

IBM Tape Device Drivers

IBM Tape Device Drivers Installation and Users Guide