virtuent user guide rel 7
TRANSCRIPT
26 Crosby Driv
P
ve, Suite 100
UserPart Number
0 · B
r’s Guidr 40-03377-E
Bedford, MA
de
E0-001
A 01730 · (781)2772-8200
Bus-Tech Virtuent User’s Guide Part Number 40-03377-E0-001 October 2010
© Copyright 2010 by BUS-TECH, INC. 26 Crosby Drive, Suite 100 Bedford, MA. 01730 Voice: (781) 272-8200 Fax: (781) 272-0342 All Rights Reserved.
The information contained in this document is proprietary.
Duplication of this document or any part thereof should be undertaken only with the written permission of Bus-Tech, Inc.
Acknowledgments: Bus-Tech, Mainframe Data Library, and Virtuent are trademarks of Bus-Tech, Inc.
Ethernet is a registered trademark of Digital Equipment Corporation, Intel® Corporation and Xerox Corporation.
IBM, System/390, and OS/390 are registered trademarks of International Business Machines, Inc.
Other names are used herein for identification purposes only and may be trademarks of their respective owners.
Table of Contents i
Table of Contents About This Publication ....................................v Who Should Use This Publication .....................v
How to Use This Publication .............................v
What is Included in This Publication ............... vi
New in Revision C0 ......................................... vi
New in Revision D0 ......................................... vi
New in Revision E0 ........................................ vii
Chapter 1 . Introduction.................................1
MDL Installation and Configuration .................3
Working with Configuration Files .....................3
Chapter 2 . Defining the Virtual Tape Library ..............................................................7 Overview ............................................................7
Storage Classes ..............................................8 Supporting Multiple Libraries .....................10 Lock Filesystem ...........................................10 Defining a Virtual Tape Library ..................11
Defining Filesystems .......................................11
Defining the Library to be Used by a Node .....15
Defining the Lock Directory ............................16
Backward Compatibility ..................................17
Chapter 3 . Configuring Virtual Devices .....19 Global Options .............................................19 Adding Devices ............................................21
Scratch Synonyms ............................................26
Saving your Configuration ...............................29
Activating (Installing) a Configuration ............29
Chapter 4 . Using Virtuent with z/OS, OS/390, or MVS .............................................31
Mainframe Utilities ..........................................31
Configuring the Devices ..................................32 Real 3480/3490/3590 ...................................32
Manual Tape Libraries .................................33 MTL-Related IBM maintenance ..................35
Bus-Tech’s Unit Information Module .............35
Virtuent Scratch Utility Program .....................37 VTSCR Parameters ......................................38 RMM Considerations ...................................41 TMS (CA-1) Considerations ........................41 TLMS Considerations ..................................42 TSM Considerations ....................................42
VTCMD Utility Program .................................42
DFSMShsm Considerations .............................44
Specifying Tape Compaction ...........................45
Missing Interrupt Timer ...................................45
Dynamic Device Reconfiguration (DDR) Considerations..................................................46
DR Logging .....................................................46 Enabling DR Logging ..................................47 Retrieving the Still In Use Report ................48
GENSTATS Reports ........................................48 Sample Reports ............................................52
Chapter 5 . Using Virtuent with VSE..........55 Overview ..........................................................55
Configuration Parameters Unique to VSE .......55 Global ...........................................................55 Device Specific ............................................56
VSE Programs ..................................................56
VSE Sample Jobs .............................................57
Tape Drives ......................................................57
VIRMOUNT Utility.........................................58
VIRMAINT Utility ..........................................59
Dynam/T Support.............................................59
VIRSSD Utility for Dynam/T Operation .........60
Dynam/T Message Exit ....................................61
ii Virtuent User’s Guide
Using Dynam/T ................................................62 Create New Tape Data Sets .........................62 Prepare a Scratch Pool .................................62 Volume Scratching and Erasing with Dynam/T ......................................................63
BIM-EPIC ACL Support .................................64
VIRSSE Utility for EPIC Operation ................65
Using CA-EPIC or BIM-EPIC .........................66 Creating New Tape Data Sets ......................68 Volume Scratching and Erasing with EPIC .68
All Environments .............................................69 Multiple VSE Images ...................................69 Specifying Tape Compaction .......................69 Sending Console Commands and Running Scripts from VSE .........................................69
Chapter 6 . Using Virtuent with VM ........73 Installing VTSCR and VTCMD ......................73
VTSCR .............................................................74
VTCMD ...........................................................77 Using VTCMD to Mount a VOLSER .........78
Chapter 7 . Using Virtuent with Unisys ......79
Unique Virtuent Operations for Unisys Mainframes ......................................................79
Autodetection ...............................................79 Load Displays ..............................................79 Mount “Ready” Interrupt .............................79 Query Config command ...............................79 Ring-Out Mount Request .............................79 Scratch Request ............................................80
Configuring for Unisys ....................................80
Device Type .....................................................80 Labels ...........................................................80 Scratch Tapes ...............................................80
Initializing Tapes for Unisys ............................81
Configuring the Mainframe for Virtuent .........81
Chapter 8 . System Operation......................83 VT Console ......................................................83
Starting / Stopping Tape Devices ....................85
Initializing Scratch Volumes............................86
Virtual Tape Operator Commands ...................87 Command Syntax .........................................88 EXPORT Command ....................................88 FIND Command ..........................................88 HELP Command ..........................................88 IMPORT Command .....................................89 INITIALIZE Command ...............................89 LOAD Command .........................................90 QUERY Command ......................................91 QUIESCE Command ...................................92 READY Command ......................................92 RESET CHANNEL ADAPTER Command 93 REWIND Command ....................................93 SAVE TRACE Command ...........................93 SET Command .............................................94 SHOW Command ........................................96 STOPVT Command .....................................96 STARTVT Command ..................................97 STOP CHANNEL ADAPTER Command ..97 UNLOAD Command ...................................97 UNQUIESCE Command .............................98 UNREADY Command ................................98
Reboot a Controller ..........................................98
Set Date and Time ............................................99
Virtuent Messages ..........................................100 Configuring SNMP Message Notification .100 Sending E-mail ..........................................101 Sending Vendor E-Mail (Phone Home) .....102 Configuring Messages to be Sent ..............102 Viewing Message (Log) Files ....................104
User Administration .......................................105 LDAP .........................................................106
Chapter 9 . z/OS Console Operation ..........109 VTHHOST .....................................................109
Installing VTHHOST .................................110 Running VTHHOST ..................................110 VTHHOST Configuration File ..................111
Table of Contents iii
Using z/OS Console Support .........................112 VTHHOST Commands ..............................113 WTOR Command Examples .....................114
Chapter 10 . Using Data Encryption .........117 Connecting to the RSA Key Manager ...........120
Chapter 11 . Back-End Tape Support.......121 Direct Tape .....................................................121
Compression and Encryption .....................123
Tape Export / Import Utilities ........................124 Export .........................................................125 Import .........................................................126
Chapter 12 . Data Exchange ......................127 Configuration .................................................128
Virtuent Controller .....................................128 z/OS, OS/390 .............................................130 VSE ............................................................130 VM .............................................................130
Writing Flat Files ...........................................131
Reading Flat Files ..........................................131 z/OS and OS/390 .......................................131 VSE ............................................................132
Appendix A. Volume Handling ...................133 Volume Serial Numbers .................................133
Scratching Volumes .......................................134 Deleting ("Erasing") a Scratch Volume's Data ............................................................135
Mounting Volumes ........................................135 Mounting A Specific Volume by VOLSER135 Mounting a "SCRTCH" or "PRIVAT" Volume .......................................................136
End of Volume Conditions ............................137 Logical End of Volume ..............................137 Physical End of Volume ............................138 End of Data ................................................138
Error Conditions .............................................138 Mount Loops ..............................................138 Out of Disk .................................................139
Appendix B. AWSTAPE Information .......141
Appendix C. Load Display Command – CCW Opcode x’9F’ ......................................143 Load Display Data .........................................144
Format Control Byte (FCB) ...........................144
Help and Service Information.....................147 Step 1: Problem Solving ................................147
Step 2: Preparing for the Call .........................147
Step 3: Placing the Call ..................................148 Additional Technical Support Resources ..148
Index ..............................................................149
Customer Response ......................................151
About This Publication v
About This Publication This Guide provides the information necessary to Bus-Tech Mainframe Data Library controllers running the Virtuent tape-on-disk software..
The following terms may be used as synonyms for the PCI ESCON Adapter in this publication and in some software installation screens:
Bus-Tech PCI to ESCON Adapter
ESCON adapter
channel adapter
The following terms may be used as synonyms for the PCI FICON Adapter in this publication and in some software installation screens:
Bus-Tech PCI Bus to FICON Adapter
FICON Adapter
channel adapter
The following term is used as a synonym for the Mainframe Data Library throughout this publication:
MDL
Who Should Use This Publication
This publication is intended for the system administrator responsible for configuring a Mainframe Data Library running Virtuent tape-on-disk software to connect with a z/OS, OS/390, MVS, VM, or DOS/VSE mainframe.
How to Use This Publication
This publication is specific to the Virtuent tape-on-disk application and its use. Bus-Tech’s Mainframe Data Library (MDL) is a family of controller products for the IBM mainframe which are all built using Virtuent tape-on-disk technology. Documentation for MDL controllers consists of both an MDL Installation and Configuration Guide specific to an MDL model and this User’s Guide covering general configuration and use of Virtuent. The two manuals are used together to install, operate, and manage the MDL controller.
This publication is organized into distinct chapters. Refer to those chapters specific to completing the task(s) you are performing.
vi Virtuent User’s Guide
What is Included in This Publication
This User's Guide contains information on how to complete the following tasks:
Connect, define, and configure an NFS storage subsystem
Configure virtual tape devices
Configure the System/390 mainframe
Operate a Mainframe Data Library running the Virtuent tape-on-disk software
New in Revision C0
In addition to fixing minor typing errors, this revision includes the following changes:
1. A new device specific configuration parameter, VOL=, has been added. See page 25.
2. Sample JCL for installing GENSTATS has been added. See page 48.
3. A new GENSTATS parameter, SYNCTIME, has been added. Pages 49 and 51.
4. Additional DD statements needed when running GENSTATS with the STILLINUSE parameter have been defined. See page 50.
5. Sample GENSTATS reports have been added beginning on page 52.
6. Chapter 9 has been updated documenting the new NOWTOR parameter on the z/OS Started Task (VTHHOST) beginning on page 109.
7. Information was added explaining the use of read-only on library filesystems on page 13.
8. The TMS Considerations on page 41 were updated to correctly indicate the use of the DSN17 field in the TMS scratch reports.
New in Revision D0
Updated GENSTATS Reports section beginning on Page 48.
Updated VT Console section beginning on Page 83.
About This Publication vii
New in Revision E0
Updated page 6 with additional information on installing a configuration.
Updated page 7 to correct description of how Virtuent allocates a new VOLSER to a filesystem in the library.
Updated Storage Classes overview beginning on page 8.
Updated description on how to define a lock directory on page 16.
Enhance section on activating a configuration beginning on page 29.
Updated section on mainframe utilities beginning on page 31.
Update to CA-1 Considerations beginning on page 41.
Updated the SHOW command on page 96.
Updated Appendix A to accurately explain scratch volume allocation within a tape library.
Numerous minor edits throughout the manual.
Chapt
ter 1. InBus-Tor IBMusing softwaconneon mo3490, mainf(See F
The taa singcorrelacquirtape v
The da modbeing origin
Optionthe orapplic
VirtueTheseinterfa
ntroductTech’s MainfM-compatibla common tare runs on a
ections or onodel, Virtuenor 3590 tap
frame is storeFigure 1-1).
Figu
ape data is stgle file holdinlated to a volred from the
volume to be
default file fodified AWST
written so thnally written.
nally, data criginal data rcation can re
ent starts a ve virtual tapeace’s firmwa
tion frame Data Lle mainframtape-on-diska base hardw
ne, two, or thnt controllerse drives. Daed and retrie
ure 1-1. MDL
tored in diskng the data flume by the
e Load Disple mounted fo
ormat for virTAPE formahat variable .
can also be wrecord lengthead the data a
virtual tape tae tasks run coare, emulate
Library is a fmes and for Uk software paware controllhree ESCONs can emulatata written toeved from a d
Controller / N
k files that cofor one tape tape Volumay command
or reading or
rtual tape datat. This formlength recor
written as a phs, labels, anas a sequenti
ask on the coontinuously 3xxx-type t
family of tapUnisys OS22ackage knowler which pro
N connectionte 32 to two o or read frodisk subsyst
Node Stores T
orrespond tovolume. Th
me Serial Numd sent from tr writing.
ta written to mat keeps trards can be re
plain, sequennd tapemarksial dataset.
ontroller forand, in conj
tape drives in
Chapte
pe-on-disk c200. All MDwn as Virtuenovides one os to the mainhundred fift
om these tapetem attached
Tape Volumes
o physical vohe files are idmber (VOLSthe host whe
Virtuent conack of recordead exactly a
ntial (“flat”) s are lost, bu
each active unction withn every way
VOLSER 1
VOLSER n
er 1. Introdu
controllers foDL models arnt. The Virtor two FICOnframe. Depty six (256) 3e drives by td to the contr
on Disk
olumes of tapdentified andSER), whichenever it wan
ntrollers is wd lengths as tas they were
file. In this ut any open-s
virtual tape h the channe
y possible, by
Tape Volumeon Disk
uction 1
or IBM re built tuent
ON pending 3480, the roller
pe, with d h is nts a
written in the file is
format, system
drive. el y:
es k
2 Virtuent User’s Guide
• Receiving and interpreting channel commands (CCWs) from the host;
• Sending and receiving tape data records, and reading and writing corresponding disk data in response to the CCWs;
• Presenting initial, intermediate, and final status to the host commands, and asynchronous status as required;
• Sending and receiving control information (such as sense and load display data) to and from the host in response to the CCWs.
A virtual tape drive is in one of two basic states at any given time: Ready or Not Ready.
In the Not Ready state, the virtual tape drive appears to the host to be online but in an unmounted state. Most channel commands are not accepted in this state and will receive a Unit Check status with Intervention Required sense. While in the Not Ready state, no disk file is opened on the disk subsystem. The Not Ready state is the initial state of all virtual tape drives when Virtuent is activated, and is entered whenever an Unload command is received from the mainframe.
The Ready state is entered when the virtual tape drive receives a load request from the host. For z/OS the Ready state is entered when a mount message is received on the virtual tape drive. For VSE systems Bus-Tech supplies a VSE-based application to detect mount messages on the VSE operator console and forward them to a Virtuent controller.
When the Mount message is received, the disk file associated with the volume specified in the Mount message is opened, and the virtual tape drive comes Ready to the host. The virtual tape drive remains in the Ready state, with the associated disk file open, until an Unload command is received from the host, at which time the disk file is closed and the virtual tape drive enters the Not Ready state.
While in the Ready state, the virtual tape drive will accept all data movement, read, and write commands from the host exactly as would an actual 3xxx tape drive. As the host reads and writes and otherwise positions the virtual tape, the application will maintain synchronization of the associated disk file to exactly match the content and positioning of the virtual tape volume.
Chapter 1. Introduction 3
MDL Installation and Configuration
Installing a Mainframe Data Library tape-on-disk controller involves several steps including:
1. Unpacking and installing the MDL hardware.
2. Connecting the MDL to mainframe channels and a disk subsystem.
3. Defining the disk subsystem to the Virtuent controller(s).
4. Configuring the virtual tape drives.
5. Configuring the tape drives in the System/390 operating system.
6. Configuring VSE interface applications (VSE only).
7. Activating the Virtuent tape drives.
8. Initializing the virtual tape volumes.
9. Verifying the installation and configuration.
Steps 1 and 2 of this process are specific to the MDL model being installed. These steps are discussed in the model specific manual that accompanied your MDL. Steps 3 through 8 focus on configuring the individual Virtuent controller and are the topics of this manual. Step 9 is completed by running test jobs on your mainframe writing and reading from your MDL.
Please refer to the MDL installation guide to complete steps 1 and 2 of the installation process. Then once you have the MDL to the point where you are ready to configure the virtual tape library and tape devices you can continue through the remainder of this manual.
Working with Configuration Files
An HTML-based configuration application is used to configure Virtuent. To access this application you will need a PC / laptop with a Java capable web browser such as Microsoft Internet Explorer or Mozilla Firefox.
To access the configuration application you simply open your web browser and enter the IP address of your Virtuent controller. Refer to the hardware installation guide that accompanied your controller to determine the default IP address.
Once connected, you will be prompted for a User id and Password for the system. The default Userid is “admin”. The default password is “password”.
The default configuration file used by the configuration program is “config”. If you simply access the Virtuent configuration application and begin modifying the configuration you will be working with this default configuration file. Optionally,
44 Virtuent U
User’s Guide
you can cas many cbe the act
To select Virtuent C
By defaulconfigura(Figure 1-
You will napplicatio
e
reate and usconfigurationtive configur
a configuratConfiguratio
lt the configuation file type-3).
now be edition will displa
e your own n files as youration at any
tion file to won (Figure 1-
Figure
uration file ue in a name
Figure 1-3
ing the new ay the config
configuratiou want. How
y point in tim
work with go-2).
e 1-2. Configu
used will be in the config
. Creating a N
configuratioguration file
on files. Virtwever, only
me.
o to the Conf
uration Panel
‘config’. Tguration na
New Configur
on file. The name in the
tuent will alone configu
figurations
ls
To create youamed field an
ration
Virtuent Coe heading are
low you to suration file w
panel on
ur own nd click New
onfiguration ea (Figure 1-
store will
w
-4).
Refer configmust s
After button1-5).
Savinthe acInstal
To inswill o
WARrunni
to subsequeguration optisave the cha
making youn should nowClick the Sa
g the configuctive (last insll button is c
stall the selepen showing
RNING! Ining when th
Figure 1
ent chapters iions. Once y
anges and ins
ur changes rew be active; iave changes
Fig
uration will stalled) confclicked.
cted configug the status a
multiple nohe install but
1-4. Editing a
in this manuyou have finstall it before
eturn to the Cindicating thbutton to sa
gure 1-5. Savi
not automatfiguration, th
uration click and results o
ode configutton is click
a New Configu
ual for informnished creatine it will be u
Configuratiohe configuraave your con
ing a Configu
tically instalhe new chang
k the Install bof installing y
rations all nked.
Chapte
uration File
mation aboutng your new
used by the V
ons panel. Tation has beenfiguration.
uration
l it. Even if ges will not
button. An your configu
nodes must
er 1. Introdu
t the variousw configuratiVirtuent cont
The Save chen modified (
f you have mtake place u
Apply log wuration.
be powered
uction 5
s ion you troller.
hanges (Figure
modified until the
window
d on and
66 Virtuent U
User’s Guide
WARNINonline, wMainframdevices emconfigura
Once a coInstallati(Figure 1-used by th
e
NG! Clickinwill cause theme devices amulated by ation file.
onfiguration ion” field sh-6). The lashe system.
ng Install we controllerare likely tothe entire M
has been insowing the nast configurat
Figure 1-6.
while a Virtu(or control
o be boxed. MDL are va
stalled the Came of the ction file insta
Showing Inst
uent Controllers) to tem It is strong
aried offline
Configurationconfigurationalled is the a
talled Configu
oller is activmporarily gogly recomme prior to in
n panel with n file that waactive config
uration
ve, with devio down. On
mended that nstalling a n
display a “Las installed lguration bein
ices nline
all ew
Last last ng
Chapter 2. Defining the Virtual Tape Library 7
Chapter 2. Defining the Virtual Tape Library This chapter discusses how to define and manage the disk storage used as the virtual tape library behind a Virtuent-based controller.
Overview
The Virtuent tape-on-disk software supports a variety of different types of open-systems storage. Depending on the Mainframe Data Library (MDL) model, your MDL controller may support one or more of the following types of storage within the virtual library:
– IP attached Network File System (NFS) version 3 – Fibre Channel attached Storage Area Network (SAN) storage – Fibre Channel attached Virtual Tape Library (VTL) – IP attached compliant storage
This manual discusses how to define and configure virtual libraries which are disk based; either Network Filesystem (NFS) or fibre channel SAN disk storage. Configuration of fibre channel attached VTL storage or IP attached compliant storage is covered in separate Virtuent documents specific to the storage option your MDL system supports.
A Virtuent Tape Library is normally defined using more than one filesystem. Logically, an open-systems filesystem can be thought of as a single disk. If you are using a Network Attached Storage (NAS) device, for example, than each filesystem is a single NFS export defined on the NAS device for use by Virtuent. If you are using fibre channel storage, then each filesystem is a logical unit (LUN) defined on the fibre channel storage for use by Virtuent.
To provide the best overall performance, especially in FICON environments, multiple filesystems in each library are desirable. And, while there is no strict limitation, a minimum of four (4) filesystems is recommended. When multiple tape volumes are being written from the mainframe to the library, Virtuent will randomly allocate each tape to one of the filesystems in the library in order to balance output across all filesystems in the library.
A virtual tape library is controlled by a top level directory stored on the Virtuent controller’s system disks. Each filesystem to be used as part of the tape library must be defined and mounted as a subdirectory within that top level directory. Virtuent will automatically use all filesystems mounted under the top level directory to store tape volumes. The sample library shown in Figure 2-1 is made up of four filesystems (disks). The virtual tape library is identified by the top level directory named “tapelib”. The four sub-directories defined within tapelib, ‘DISK1’, ‘DISK2’, DISK3’, and ‘DISK4’, each point to a filesystem to be included in the virtual tape library.
8 Virtuent User’s Guide
The top level tape library name can be made up of any combination of alpha numeric characters. Sub-directories within the tape library must be named using uppercase Alpha characters (A-Z) and numbers only. For example: A0, BB, 00, 01, AA1, and DISK1 would all be valid sub-directory names within tapelib. However, a0, 0b, ab, and disk1 would all be invalid.
Hundreds of thousands of serial numbers can be stored in a Virtuent library. Virtuent will continue to store VOLSERs into each filesytem within the library until space within the filesystem is depleted. Additional filesystems can be added to the library at any time without disrupting the operation of the library. Once a new filesystem is available Virtuent will automatically begin making use of it when creating new tape volumes.
Figure 2-1. Virtual Library Architecture
Individual tape volumes do not span filesystems. Each tape volume (VOLSER) is stored as a single file on one filesystem. Should a filesystem run out of space while writing a VOLSER, the mainframe will receive an end of tape indication on the tape volume. However, since multi-volume datasets are written to more than one tape volume (VOLSER), datasets that span multiple volumes are very likely to spread across more than one filesystem in the library.
Individual VOLSERs can move from one filesystem to another within the virtual library. Like real tape volumes, virtual volumes are written, read, and scratched. Once a VOLSER has been scratched within the library, it can be re-used during a future tape allocation process. When a previously scratched VOLSER is reallocated, it may be moved by Virtuent to a different filesystem within the library.
Storage Classes
Virtuent libraries allow for multiple storage classes to be defined. Each filesystem defined to a virtual library is assigned to one and only one storage class. By default, if you do not configure a different class, any filesystem you define will be assigned to the default storage class 0. During allocation of a new tape volume (VOLSER) the user may use scratch synonyms to specify which storage class a VOLSER should be
/tapelib /DISK1 /DISK2 /DISK3 /DISK4
Each Logical Disk represents a single NFS Export or a single Fibre Channel LUN
Chapter 2. Defining the Virtual Tape Library 9
stored in. Only filesystems assigned to the requested storage class will be candidates to receive the volume.
Returning to the library pictured in Figure 2-1, if the four filesystems are all defined with the default storage class 0, then the library will treat all four filesystems equally; randomly allocating new VOLSERs to any of the four filesystems with enough space to hold the cartridge as defined by the SIZE= parameter on the device writing the file.
Figure 2-2. Storage Classes
In Figure 2-2, DISK1 and DISK2 are assigned to the default storage class 0. But DISK3 and DISK4 are assigned to storage class 1.
All Virtuent controllers recognize the names ‘SCRTCH’ and ‘PRIVAT’ as a request for a scratch tape. When the controller receives a load CCW with either of these names it will, by default, randomly allocate a new tape volume to one of the filesystems defined to class 0. In the example shown in Figure 2-2, any request for SCRTCH or PRIVAT would result in the tape being placed on DISK1 or DISK2.
To allow tapes to be allocated to storage class 1 (DISK3 and DISK4 above) a scratch synonym (name) needs to be associated with that storage class. For example, to new tapes to be allocated to storage class 1, the default configuration for the synonym ‘PRIVAT’ could be modified to assign it to Class 1 (i.e. PRIVAT=CLASS=CLASS1).
Once PRIVAT has been associated the storage class 1, any job requesting a new tape by coding JCL specifying VOL=SER=SCRTCH will be allocated a VOLSER that will be stored on either DISK1 or DISK2. JCL specifying VOL=SER=PRIVAT will be allocated to a VOLSER that will be stored on DISK3 or DISK4.
Storage classes provide a convenient way to isolate or group tape volumes together within the library. For example, storage classes provide an easy way to isolate DR tapes that you want to replicate to a remote location from work tapes that only need to be kept locally. Continuing with the storage class definitions given above, DISK1
/tapelib /DISK1 /DISK2 /DISK3 /DISK4
Storage Class 0
Storage Class 1
10 Virtuent User’s Guide
and DISK2 may be local filesytems that are never replicated. DISK3 and DISK4 may be defined as part of a group of disks that get asynchronously replicated over an IP network to a remote disaster recovery site. Any tape volume allocated as ‘PRIVAT’ will be replicated to the DR site. Any tape volume allocated as ‘SCRTCH’ will not be replicated.
Virtuent randomly allocates new tape volumes to any filesystem within the desired storage class; checking to make sure there is enough space in the filesystem to hold the volume. This tends to spread new VOLSERs across all the filesystems within a storage class. If you expect to have many tapes being processed against the same storage class concurrently, you should define multiple filesystems to that class in order to spread the I/O across multiple filesystems and/or disks.
Scratch tapes are class specific. If you define multiple storage classes you will need to initialize scratch tapes (see page 86) into each storage class. Virtuent will move scratch volumes between filesystems within storage class by will not move scratch volumes from one storage class to another.
Supporting Multiple Libraries
Virtuent tape-on-disk software allows definition of more than one virtual tape library within an MDL controller. Creating multiple top level directories on an MDL controller defines multiple independent virtual tape libraries. For example, if you wanted two separate libraries, you might define top level directories /tapelib and /tapelib2.
Each virtual tape library must have its own filesystems (disks) mounted underneath the top level directory as shown in the previous examples. Virtuent software will not allow tape volumes (VOLSERs) to be written to the tope level directory which resides on the MDL system disks.
Each tape drive configured on an MDL controller is permanently connected to one and only one tape library. Suppose, for example, you have defined 2 libraries, /tapelib and /tapelib2. You then configure 32 tape drives. Each of these 32 drives may be individually connected to one of the two libraries. So, for example, you may connect drives 1 – 16 to /tapelib and drives 17 – 32 to /tapelib2.
On the mainframe, if you configure all 32 drives within the same LPAR, you must take care to isolate them into two libraries in order to prevent a mount request on a drive that cannot access the correct virtual tape library.
Lock Filesystem
In addition to defining filesystems (space) to the virtual tape library (or libraries), Virtuent also requires a small filesystem to use as a lock directory. This filesystem must be separate from the filesystems making up your virtual tape library (libraries). When multiple Virtuent controllers (nodes) are sharing a virtual library the lock filesystem must be resident on shared (NFS or fibre channel) storage that all controllers (nodes) can access.
Defining
Definin
Only omay b
The lofor ou10 MB
g a Virtual T
Thereor fibr
1. 2. 3. 4.
Steps once Vdiscus
ng Filesyst
As a mto useintendone fi
To dethe wethe St
The Snumb
one lock filebe defining to
ock filesytemutput. ThereB filesystem
Tape Librar
are four stere channel st
Define the
Define the
Identify th
Initialize s
1 - 3 will beVirtuent is russed in detai
tems
minimum, yoe as a lock did to define. Alesystem to
fine a new feb browser otorage panel
Storage paneler of nodes (
esystem is reo the Virtuen
m is only usefore, the size
m is generally
ry
ps required ttorage and b
e filesystems
e library or li
he lock direc
scratch tapes
e discussed iunning in at l in Chapter
ou will needirectory and As previouseach library
filesystem toon your PC /(Figure 2-3)
l has two or (controllers)
Chap
equired regarnt controller
ed during thee of the locky all that is re
to successfubegin using it
s (disks).
ibraries to be
tory to Virtu
s (VOLSERs
n this chapteleast one co8 beginning
d to define onat least one ly discussedin order to m
Virtuent ac/ laptop. On).
Figure 2-3. S
more tabs; d) within the c
pter 2. Defin
rdless of howr(s).
e process of k filesystem equired.
ully define a t. The steps
e used by ea
uent.
s) into the lib
er. Step 4, inontroller (nodg on page 86
ne small (10filesystem f
d, Bus-Tech rmaximize pe
cess the Virtnce connecte
Storage Definit
depending onconfiguration
ning the Virt
w many virtu
allocating a (directory) c
Virtuent taps are:
ach MDL no
brary.
nitializing tade). Tape in
6.
MByte) filefor each virturecommenderformance.
tuent configed, click on S
tion
n the MDL mn. For singl
tual Tape Li
ual tape libra
new scratchcan be very s
pe library usi
de (controlle
apes, must bnitialization i
esystem for Vual tape libras defining m
guration paneStorage to d
model and thle controllers
ibrary 11
aries you
h volume small. A
ing NFS
er).
e done is
Virtuent ary you
more than
els using display
he s there
12 Virtuent User’s Guide
will be two tabs, as shown. The Available tab is used to define the storage available to Virtuent to build one or more virtual libraries.
The “localhost” tab is the controller tab and is used to connect the virtual tape library (or libraries) to the individual controller (node). “localhost” is the name assigned to the controller (node) in the Network panel for single controller MDL models.
For MDL systems with multiple nodes (MDL-4000 and MDL-6000) there will be multiple controller tabs, one for each node in the configuration, labeled with the name of the node (controller).
Before defining the virtual tape library you need to have previously configured the storage itself. For NFS, this means you should have defined the exports for MDL to use.
The fields that need to be defined are:
Mount Point – the name where the storage is to be attached to the Virtuent controller. The format of this field is “/libraryname/diskname”. Where “libraryname” is the top-level directory associated with an individual library and “diskname” is the sub-directory connecting the individual disk (filesystem) (See Overview beginning on page 7). The library name can be any combination of characters. If the library name does not yet exist then a new directory will be created for you; defining a new library. The disk name must be capital alphanumeric letters only. If the disk name already exists, the definition will be modified based on the other parameters entered. If the disk name does not exist then a new sub-directory will be created, adding a new disk to the library. For example, if you define the following mount points:
/tapelib/DISK1
/tapelib/DISK2
/tapelib2/DISK01
/tapelib2/DISK02
You will have defined two separate tape libraries, each with two filesystems (disks).
For the Lock filesystem (directory), the format of the mount point field is /lockdir/diskname, where “/lockdir” is a fixed top level directory name that must be entered exactly as shown and diskname can be any combination of meaningful characters; preferably something easily recognizable. Examples of valid lock filesystem mount point names are: “/lockdir/nfs1” or “/lockdir/disk1”.
Storage Location – this field identifies the specific filesystem (NFS export or fibre channel LUN) to be connected to the mount point.
For Virtuent to work properly, the NFS server must export the filesystem allowing read/write capabilities for user id number (UID) 88 and group id number (GID) 88. Make sure your NFS server administrator is aware of
Chapter 2. Defining the Virtual Tape Library 13
this requirement when establishing exported filesystems to be used with Virtuent.
Following is a valid Storage Location definition of an NFS filesystem:
192.168.200.20:/disk1
Where 192.168.200.20 is the IP address of the NFS Server exporting the filesystem and “disk1” is the export name as configured in the NFS server.
The preferred method for defining a fibre channel disk is assign a volume label the disk at the time your format the filesystem and then use that label to identify the storage location. The format for the Storage Location definition for a fiber channel disk with a volume label is:
LABEL=VOLID
where VOLID is the volume label assigned to the disk. For example:
LABEL=LUN4
The Storage location for a filesystem being defined as a lock filesystem is no different than a filesystem being defined as a storage filesystem.
Storage Class – storage class identifies the specific storage class this storage is to be assigned to (see page 8). This is a numeric value. The default is 0, implying the storage is general storage not assigned to a class. Storage class does not apply to a filesystem being defined for use as a lock filesystem. Let the lock directory filesystem default to class 0.
Options – the options field allows you to assign mount options to the filesystem. The following options are recommended for NFS filesystems being used for storage:
rsize=32768,wsize=32768,hard,intr,tcp,nfsvers=3
For the lock directory filesystem the recommended NFS options are:
hard,intr,tcp,nfsvers=3
For OCFS/2 fibre channel storage the recommended option is:
_netdev
To mount a filesystem as read-only include the option:
ro
For example:
rsize=32768,wsize=32768,hard,intr,tcp,nfsvers=3,ro
Normally, the only time you would configure a filesystem as read-only would be if you were performing DR testing and wanted to make sure you did not modify or erase any production data during your DR tests. Be aware that if you mount a
114 Virtuent
User’s Guid
filesysto dire
Filesythis stwhereShare
Figureconfig“/tapeidentiaddresNFS smeans
Figure 2-5filesystem
You may next butto
de
stem read-onect new tape
ystem – this torage (disk)e the library d SAN Stora
e 2-4 shows guration. Aselib/DISK1” fied by “/tapss 192.168.1server is “diss it is genera
5 shows an em.
add any numon.
nly you muse volumes to
field allows). For fibre is not sharedage configur
an example s shown, the implying th
pelib”. The a1.20. The exsk1”. This fal storage no
Figure 2
example of a
Figure 2-5. A
mber of files
t make sure filesystems
s you to selecchannel stor
d, Bus-Tech rations you m
adding an Nnew filesys
his filesystemactual storag
xport name bfilesystem is t assigned to
-4. Adding an
adding a fibr
Adding a Fibr
systems to th
to use scratcnot configu
ct the type orage on a sinrecommend
must select O
NFS filesystetem will be
m is part of thge is locatedbeing used to
defaulting to a specific c
n NFS Filesyst
re channel L
re Channel Fil
he available
ch synonymured as read-o
of filesystem ngle Virtuentds selecting eOCFS/2.
em to the stomounted at the virtual tap
d on the NFSo export the to storage claclass.
tem
LUN using th
lesystem
storage by c
s (see page 2only.
to be used ot controller ext3. For M
orage the mount ppe library
S server at IPstorage on thass 0, which
he OCFS/2
clicking the A
26)
on
MDL
oint
P he
h
Add
Definin
ng the Libr
Becauoperattape li
On thesingleconfig(contrit defi
Once to the storagmanua
Simplshowsdefine
You maccessall fou
If muldiffere
If youconnesure to
Warnsure tinclud
rary to be
use some Mating nodes, tibraries are t
e storage pane MDL contrguration panroller) there wines.
you have senode will be
ge on the “aval to define s
ly click the cs a sample coed with 4 file
must always sing a libraryur filesystem
ltiple librarieent libraries.
u are definingected to one lo include bo
ing: If you that all nodedes 4 filesyst
Used by a
ainframe Datthe second stto be used by
nel, select throllers there els in this uswill be mult
lected a node displayed.
vailable” tabstorage to V
check boxes onfigurationesystems alo
connect the y, then it sho
ms have been
es are define.
Figur
g multiple lilibrary and o
oth library’s
are defininges / controlletems and an
Chap
a Node
ta Library mtep of storagy devices on
he tab for thewill only beser’s guide. tiple tabs wit
de (controller If nothing . Follow insirtuent.
for the storan where a sinong with the
lock fileysteould always n selected for
ed, then you
re 2-6. Definin
braries and wother tape drstorage in th
g a library aers include another only h
pter 2. Defin
models includge configuratn each Virtue
e controller ye one tab; lab
For MDL mth each tab i
r) to configuis displayed
structions in
age you wanngle virtual t
lock filesyst
em to all nodaccess all dir use by the
may configu
ng Storage to
want the conrives to be cohe node (con
across more all the same has the first
ning the Virt
de multiple, tion is to defent controlle
you wish to beled “localhmodels with indicating th
ure a list of ad, then you hn the previou
nt this node ttape library (tem.
des. Additiisks in that lMDL contro
ure different
the Node
ntroller to haonnected to
ntroller) conf
than one nofilesystems.
t 3, then the
tual Tape Li
independentfine which ver.
configure. Fhost” in the smore than o
he name of th
all storage avhave yet to dus section of
to use. Figur(tapelib) has
ionally, if a nibrary. As soller.
t nodes to co
ave some tapa second libfiguration.
ode / control. If one consecond cont
ibrary 15
tly virtual
For sample one node he node
vailable define
the
re 2-6 been
node is shown,
onnect to
pe drives rary, be
ller be ntroller troller
1
D
16 Virtuent
Defining th
User’s Guid
will be unthe fourth
Repeat th
he Lock D
The final filesystemtape volumshould be
The samelibrary. T
The lock VOLSERGlobal op
To defineparametescreen. Th
VOLS
Where “/ldirectory chapter).
de
nable to acceh filesystem.
e storage sel
Directory
step to confm (disk) to usmes. Theref
e plenty rega
e lock directoThe same loc
directory is RLOCKDIR.ptions on the
e the lock dirers”. Then ehe format of
SERLOCKD
lockdir/disknon the Avail
ess tape volu.
lection proce
figuring a Vise as the locfore, the file
ardless of how
ory MUST bck directory
identified to This param
e node Devic
Figure 2-7. G
rectory clickenter the lockf the lock dir
DIR /lockdir/
name” is thelable storage
umes (VOLS
ess for each
irtuent librark directory. system can bw big a libra
be defined tocan be used
o Virtuent wimeter is definces panel (Fi
Global Option
k on the hypek directory prectory param
/diskname
e mount poine panel (see
SERs) writte
node (contro
ry storage is This filesysbe small in sary you are d
o each node afor more tha
ith a global pned as an addigure 2-7).
ns on the Devic
erlink “clickparameter intmeter is:
nt you previo“Defining F
en by the firs
oller) in you
to tell Virtustem will nosize. 10 MBdefining.
accessing a van one virtua
parameter caditional para
ce Panel
k to add free-to the free-fo
ously definedFilesystems”
rst controller
ur configurat
uent which ot be used to Bytes of stora
virtual tape al tape librar
alled ameter under
-form orm area on
d for the loc” earlier in th
r into
tion.
store age
ry.
r the
the
k his
Backwa
Figurefilesys
ard Comp
Custocontrocontro
To opdefineVOLScontrowith V
Keep compaforce.the firFilesyfilesyscan be
If youthat yofull ad
e 2-8 shows stem located
patibility
mers installioller environoller in comp
perate in come a lock direcSERLOCKDoller (node) wVirtuent soft
in mind thatatibility mod Specificallrst 2 characteystems are gestems addede used.
u are definingou define a ldvantage of t
an example d at mount po
Fig
ing a Virtuennment with apatibility mo
mpatibility mctory filesys
DIR parametewill assume tware older t
t if the Virtude then the ry, each filesers of the VOenerally rest
d to the librar
g a new MDlock directorthe Virtuent
Chap
where the looint ‘/lockdi
gure 2-8. Free
nt 7 (or highan earlier verode.
mode using anstem in the cer has not bethat the virt
than release
uent controlleestrictions o
system must OLSERs thatricted to 10,ry must have
DL virtual tapry filesystem7 enhanced
pter 2. Defin
ock directoryir/lock’.
e-Form Param
her) based corsion of softw
n existing vionfigurationeen defined tual tape libr7.0.
er (node) is rof the previou
be defined (at will be sto,000 VOLSEe VOLSERs
pe library Bum as described filesystem a
ning the Virt
y has been d
meters
ontroller intoware can op
irtual libraryn. When theon a control
rary is an exi
running in bus library ar(mounted) in
ored in that fiERs per filess initialized i
us-Tech stroed in this maarchitecture.
tual Tape Li
defined as th
o an existingerate their n
y, you simplye ler (node), thisting library
backward rchitecture arn the library filesystem. system and ninto them be
ongly recommanual in orde.
ibrary 17
he
g multiple ew
y do not
he y created
re all in using
new efore they
mends er to take
18 Virtuent User’s Guide
If you must run in compatibility mode because of existing controllers, please refer to the Virtuent User’s Guide, part number 40-03208-xx-001 for documentation on the earlier generation library architecture.
Chapter 3. Configuring Virtual Devices 19
Chapter 3. Configuring Virtual Devices Once the tape library has been defined you are ready to begin configuring your virtual tape devices. Depending on your controller model, you will be able to define up to some number of virtual 3480/3490/3590 tape drives on each Virtuent controller (node). MDL model 100 controllers, for example, allow a maximum of 32 devices to be configured. MDL 1000, 2000, 4000, and 6000 all allow up to 256 devices to be configured per controller (node).
For z/OS systems you should plan for one virtual device that will be offline all the time that can be used by Bus-Tech supplied z/OS utilities to communicate with the MDL. Additionally, if you plan to run the Virtuent z/OS started task, you should plan for one virtual device per node (controller) that will remain offline and be used by the started task to communicate with the node / controller.
For VSE/ESA systems with tape management software installed you should define one virtual tape drive for control. This drive will be used to receive Load Display Mount messages and will not be available for use by applications. So, for example, if you define sixteen (16) tape drives only fifteen (15) will be useable by your applications. For BIM-EPIC environments, read the “BUSTECH MAS Support” section of the “BIM-EPIC Installation and System Guide” before configuring any virtual tape drives.
Virtuent device configuration is done using the Devices panel of the Virtuent configuration utility (See Figure 3-1).
Global Options
At the top of the Devices panel are Global options that can be set for the entire Virtuent Controller. These parameters include:
Warn at – Sets the percentage of disk space usage at which Virtuent will begin to warn about usage. Each time the contents of a filesystem changes Virtuent will check the space used against this value. If the used space in the filesystem is above this value a warning will be issued. The valid range is 0 to 100. The default is 75%.
Start space recovery at – Sets the percentage of disk space usage at which Virtuent automatically starts to recover disk space by deleting the data from scratch volumes (see page 135, “Deleting ("Erasing") a Scratch Volume's Data”). Valid values are from 0 to 100. The default is 95%. If the recovery percentage is set to 100, Virtuent will never automatically delete scratch volume data to recover disk space.
220 Virtuent
User’s Guid
Recovspace space erasedto 100filesys
Tape exportIBM 3Virtuecopy (TS112volumcontroetc). check
Writecontrocontrobackwa newvolumcontroinstall“Allow
de
ver amount it will contihas been rec
d. Valid valu0 will cause Vstem once th
export enabt / import uti3592 or TS1ent controlle(export) a ta20 cartridge
me (VOLSERoller and are By default t
kbox will ena
e compatibiloller needs bollers. By deward compat
w Virtuent comes with oldeoller can be rlations, wherw new featu
(1-100) – Wnue erasingcovered or uues are 1 to Virtuent to e
he start space
Figure 3-
bled – indicailities. Virt120 tape dri
er, export / imape volume (
or copy (imR) in the Vir
outside of athese utilitieable the Exp
lity – the wrbackward comefault, Virtutible with preontroller can er Virtuent cread by othere no existinures but lose
When Virtuendata from sc
until there ar100. The deerase the date recovery v
-1. Device Con
ates whethertuent controlive. When amport utilitieVOLSER) f
mport) a physrtuent libraryany mainframs are disableort / Import
rite compatibmpatibility went is configevious versiobe installed
controllers. er, older Virtng Virtuent ce backward
nt starts to aucratch volume no more scefault is 1%.ta from all scvalue has bee
nfiguration Pa
r or not this llers allow pha real IBM dres are availabfrom the librsical 3592 / Ty. These utilme security ped. Checkinutilities.
bility field inwith previougured so thatons of Virtuinto an exisSpecificallytuent based ccontrollers exd compatibil
automaticallymes until thiscratch volum. Setting reccratch volumen reached.
anel
controller ishysical attac
drive is attachable on the corary to a phyTS1120 cartrlities are exeprograms (R
ng this config
ndicates wheus generationt it will write
uent. This desting library y, volumes wcontrollers. xist, this optlity”. This w
y recover diss amount of mes that can covery amou
mes on this
s to provide chment of anhed to the ontroller tha
ysical 3592 / ridge to a tapecuted on the
RACF, ACF/guration
ether or not tn Virtuent e data that isefault insuresand share ta
written by thi For new
tion can be swill allow th
sk free be unt
n
at will
pe e /2,
this
s s that
ape is
set to he
Adding D
coco
Adpathcliin
See palibrari
Devices
Belowunits syou bemainf
The ficonfigvalid cthe cocontro
ontroller to taontroller.
dditional paarameters deat can be maick on click clude:
VOLSERfilesystempreviouslypage 11) a
age 16 for a ies.
w the global section and tegin the proc
frame by this
irst step to dguration. Ascontrol unit
ontroller. Fool unit value
ake full adva
arameters –scribed abovanually enterto add free-f
RLOCKDIRm to be used by defined to Vas well as bei
full descript
options sectthe Scratch scess of defins node / cont
efining devis shown in Fnumber and
or ESCON vas are 00-FF.
Fi
antage of all
– In addition ve there are gred into the c-form param
R /mountpoinby the controVirtuent on ting selected
tion on defin
ion of the desynonyms sening virtual ttroller.
ces is to addFigure 3-2, a d selecting a alid control Click the “
gure 3-2. Add
Chapter 3.
l features of
to the pre-dglobal free-fconfiguratio
meters. Curr
nt – defines oller. The mthe Availablon the node
ning a lock d
evices panel ection. The tape devices
d one or mornew controldevice type unit values a
“+” button to
ding a Contro
Configuring
the current g
defined globaform configu
on. To add arent free-form
the location mount point mle tab of the e storage pan
directory for
are two sectControl unit
s (drives) to b
re controllersl unit is addefor the deviare 00-0F. Fo complete th
ol Unit
g Virtual De
generation V
al configuraturation parama free-form pm parameter
of the lock must have bestorage pane
nel.
each of you
tions; the Cots section is be emulated
s to the ed by enterinces to be defFor FICON vhe add.
evices 21
Virtuent
tion meters
parameter rs
een el (see
ur virtual
ontrol where
d to the
ng a fined on valid
222 Virtuent
User’s Guid
The contrdefined th
The param
Contrdevice
Add ayou w
Initiadevicemainfrange device0F andE900,long.
Tape the lisStoragStorag
de
rol unit will bhe Add devic
meters you c
rol Unit - Thes on.
address ranwish to add to
al device name. Bus-Techframe operatof devices b
e. For examd you enter E, E901, E902
Library – Ist of availablge panel (seege panel (see
be added to ces configur
Figure
can configure
he control un
nge – The stao the control
me - A uniquh recommendting system. being created
mple, if you aE900 in this 2, ... E90F. T
Identifies thele libraries, se page 14) ane page 15).
the list. Oncation section
3-3. Add devi
e for each de
nit from the
arting and enller.
ue device nads using the The name yd and will beare defining
field, the coThe name yo
e library thisstorage mustnd be conne
ce at least onn will displa
ices Paramete
evice are:
list above th
nding hexade
ame must be same device
you enter wie incremente16 devices wonfigurator wou enter may
s device is cot be defined cted to the n
ne control unay (Figure 3-
ers
hat you wish
ecimal devic
created for e name as dell be the inited for each swith an addrwill name thy be from 1 t
onnected to. on the Avai
node on the n
ntil has been-3).
h to configur
ce unit addre
each Virtuenefined on thetial device insubsequent ess range of e 16 devicesto 8 characte
To appear ilable tab of node tab of t
n
e
esses
nt e n the
f 00 – s ers
in the the
Chapter 3. Configuring Virtual Devices 23
IDRC – Yes/No/Force turns on or off write compression of the data that Virtuent writes to disk. The default value is IDRC=Yes.
When IDRC is Yes, Virtuent will compress the data it writes to a virtual tape disk file as directed by the IDRC compression indicator passed with the data from the mainframe. Compression is controlled differently by various host operating systems, but is generally configurable in the JCL.
When IDRC is configured to No, Virtuent will not compress the data it writes to a virtual tape disk file, even if told to do so by the mainframe. Virtuent will report to the host that it supports compression; but it will not actually perform any compression as it writes data to disk. This is because some host operating systems or tape managers will not use a drive that does not support compression.
IDRC=No only affects writing of data. If IDRC is set to No, Virtuent will still decompress virtual tape volumes that were written with compression on.
IDRC=Force causes Virtuent to compress all data even when the mainframe does not tell the device to do so.
Compression of data can result in a considerable savings in disk storage required to store virtual tape files, but comes at a price in performance. It is most useful when writing to slow disk storage such as to NAS over slower connections, or when disk storage space is limited.
Note: Storage that performs global data de-duplication on all data it receives often performs better with data that has not been previously compressed. If your storage is performing data de-duplication you may wish to set IDRC=No. However, be aware that this may decrease throughput through the Virtuent controller as more data will need to be written to the back-end storage.
Encryption key class – Enter a valid RSA key class to enable the drives to do encryption. When this field is configured the tape drive will make a call to the RSA Key Manager using this key class each time the drive opens a tape volume for output.
Additional parameters - The Additional parameters field allows you to code a number of optional keyword parameters which will be assigned to the devices being created.
GROUP=nn nn is any decimal number. GROUP should be coded whenever Virtuent is to be used with the VSE VIRMOUNT utility on multiple VSE systems running under VM or on multiple LPARs. All virtual tape drives attached to the same VSE guest machine should have the same GROUP. When VIRMOUNT requests a mount, only virtual drives in the same GROUP are considered for the mount. When not coded all drives default to GROUP=0.
24 Virtuent User’s Guide
LABELS=S/N/A
Most operating system mount requests will specify a label type, but for those that do not the LABELS parameter sets the default label type for this drive. The default label type is S for IBM standard (EBCDIC) labels. Optional values are N for unlabeled, and A for ANSI (ASCII) labels.
The Virtuent label type only affects how new tapes are initialized by Virtuent and what type of scratch tape to select when the host does not specify a label in its mount request. The label type setting has no effect on existing tape volumes. It has no effect when the Host requests a specific VOLSER or label type in its mount request.
OSADDR=xxxx
xxxx is a 3-digit or 4-digit hexadecimal number. OSADDR should be coded with the address by which the virtual drive is known to VSE whenever Virtuent is used with the VIRMOUNT utility. When VIRMOUNT requests a volume to be mounted on a specific drive, it passes the device address as it's known to VSE. Virtuent then searches for the virtual drive configured with that OSADDR. In addition, when Virtuent satisfies a VIRMOUNT mount request it returns the OSADDR of the drive selected to the VIRMOUNT application.
SIZE=maxvolumesize
This parameter limits the maximum size an individual tape volume can be. The maximum volume size can be specified in bytes (SIZE=nnnnnn), kilobytes (SIZE=nnnK), megabytes (SIZE=nnnM), gigabytes (SIZE=nnnG), or terabytes (SIZE=nT). When specifying kilobytes, megabytes, gigabytes, or terabytes the value can contain a decimal point (i.e. SIZE=n.nT).
Size can range from 2M (2 megabytes) to 32T (32 terabytes). If omitted, the maximum volume size defaults to 2G (2 gigabytes) for 3480 or 3490 devices and 40G (40 gigabytes) for 3590.
TRACE=n
Trace allows you to set the trace option for this specific device. Available trace levels are:
0 – No Tracing (default) 1 – Trace Errors Only 2 – Trace Errors and Status 3 – Trace Errors, Status, and Headers 4 – Trace Errors, Status, Headers, and Data 5 – Perform a full packet trace (for customer support use only)
Chapter 3. Configuring Virtual Devices 25
VOL=(xx(,yy,…))
VOL allows scratch volume allocations to be restricted to a specific range of tape volumes beginning with the prefix(es) defined by VOL.
xx can be from 1 to 6 characters in length. For example, 00, 001, 0011, 00111, and 001111 are all valid examples of a VOLSER prefix.
VOLSER prefix(es) set with VOL are honored during scratch mounts ONLY. The VOL prefix(es) filter is applied after all other class, space, age, label-type, penalty, and synonym filters have been applied. VOL prefixes do not affect the determination of which directories are picked or in which sequence directories are picked. VOL prefixes do not affect the sequence that VOLSERs are evaluated; prefixes are simply a filter that is applied to the VOLSER candidates being considered.
The sequences of the prefixes does not change the evaluation process in any way. If any one prefix matches a candidate VOLSER the VOLSER passes the test and is selected for the scratch allocation.
For example, if
VOL=(01,02)
were specified for a range of devices then those devices would only allocate new scratch volumes to VOLSERs beginning with ‘01’ or ‘02’. If no scratch volumes beginning with ‘01’ or ‘02’ are available in the storage class being allocated to then the allocation will be ignored and the device will remain in a “not ready” state.
Once the parameters are set to your satisfaction click the Add range button to create the new devices. A Current devices section will display at the bottom of your browser showing the devices that have been created (Figure 3-4).
2
S
26 Virtuent
Scratch Sy
User’s Guid
Note: If yon the marather thatwo contr
ynonyms
When theload displto be mou“VOL=SEdevice indthe drive. and then r
z/OS usesrequest forecognizerequest tocommandthe contromount it o
Most comallowing tscratch ta
Customercharacter request fotape poolssynonyms
de
you are confainframe bean defining rol units with
e mainframe lay commanunted. For exER=000001”dicating the After sendi
reads the VO
s the default or a scratch te these 2 chao mount an ed containing oller will locon the reque
mmercial tapethe customer
ape.
rs using tapestrings that
or a scratch ts, Virtuent as” to the Vir
Fig
figuring thee aware that
32 devices oh 16 devices
wants a taped is sent ovexample, in z”, then z/OStape volumeing the load
OL1 label to
character strtape to be moaracter stringexisting VOLeither SCRT
cate an availasted device t
e managemer to define th
e pools with tthe compute
tape from a sallows the curtuent contro
gure 3-4. Curr
e tape deviceMTLs only
on a single cs each.
e volume (Ver the channez/OS if a use will send a
e with VOLSdisplay, z/Overify the se
rings “SCRTounted for o
gs as a requesLSER. WheTCH or PRIVable scratch to be used fo
ent systems (heir own scr
their TMS wer operators aspecific poolustomer to deoller. The sy
rent devices
es into a Maallow 16 de
control unit,
VOLSER) moel to the dev
er codes JCLload display
SER ‘00000OS waits for erial number
TCH” and “Poutput. By dst for a new en Virtuent rVAT insteadtape in the v
or output.
(TMS) suppratch pools fo
will have defand/or tape ll of scratch tefine their owynonyms, alo
anual Tape Levices per co, you would
ounted on a vice identifyiL for a tape vy command t01’ needs to the device tor.
PRIVAT” todefault Virtue
scratch tapereceives a lod of a volumvirtual tape l
ort the concfor use when
fined their owlibrary musttapes. In supwn unique “ong with SC
Library (MTontroller. So
want to defi
tape device ing the VOLvolume that rto the tape be mounted o become re
o indicate a ent controllee, rather thanoad display
me serial numlibrary and
ept of tape pn mounting a
wn special t recognize apport of TM“scratch CRTCH and
TL) o fine
a LSER reads
on ady
ers n a
mber,
pools; a new
as a MS
Chapter 3. Configuring Virtual Devices 27
PRIVAT, will be recognized by the Virtuent controller as a request for a new scratch volume when they are received in a load display command.
On the Device panel, next to the control units section is a section for adding your own scratch synonyms (tape pool names). See Figure 3-1.
The format for defining a scratch synonym is:
synonym=(prefix1,prefix2,…CLASS=(CLASSn,CLASSn,…))
where:
synonym – is the character string to be used as the synonym. Synonyms may be 1 – 10 characters in length and must contain only letters A-Z and numbers 0-9. Synonyms are not case sensitive and may be entered in either upper or lower case.
prefixn – a scratch synonym may be associated with a specific set of VOLSERs. prefixn defines the prefix characters of the VOLSERs that can be assigned in response to a scratch request made with this synonym. For example, SCRTCH=(00,01) would imply that any load request received for SCRTCH must be satisfied with a VOLSER that startes with either “00” or “01”. Valid VOLSERs that could be mounted by Virtuent would include any VOLSER in the range 000000 – 019999; assuming only numeric VOLSERs are in use. If there are no scratch tapes with VOLSERs beginning with “00” or “01” then Virtuent will not mount a tape and the mount will remain pending.
Each prefix can be from 1 to 6 characters in length.
If a VOLSER prefix is not defined for a specific scratch synonym then any available scratch tape will be used.
CLASSn – defines the storage class or classes associated with this scratch synonym. For example, PRIVAT=(CLASS=CLASS1) would indicate that any load request received for PRIVAT must be satisfied by allocating a scratch VOLSER in storage class 1. Virtuent will randomly allocate each new tape volume to any filesystem in the storage class with enough space for the cartridge (volume) being written as defined by the SIZE= parameter for the device.
If a class is not specified for a synonm, then the synonym will allocate new volumes to the default storage class 0.
228 Virtuent
User’s Guid
Figure 3-5
In this exaavailable
A requestassigned awith thesepending.
PRIVAT tape withithe mount
Syntax is
DR
defines twnumbers bserial num
Whereas d
DR
correctly beginning
Finally, kBy defaultape avail
de
5 show a sam
ample any mscratch tape
t for SCRTCa volume wie prefixes ar
tapes will goin that class t will remain
important w
RTAPE=(00
wo synonymbeginning w
mbers CLAS
defining:
RTAPE=((0
establishes tg with 00 or
keep in mind lt, Virtuent wlable on the d
Figure 3-
mple scratch
mount requese in the defau
CH will also ith a serial nure available t
o to storage will be used
n pending.
when coding
0,01),CLASS
s, DRTAPE with 00 or 01SS1 and CLA
00,01),CLAS
the single sc01 located in
that it is notwill allocate default (clas
-5. Defining S
h synonym co
sted with theult storage cl
go to defaulumber beginthe mount w
assigned to d. If there a
scratch syno
S=(CLASS1
and CLASSin Class 0 s
ASS2.
SS=(CLASS
ratch synonyn either stora
t necessary tany request
ss 0) storage
cratch Synony
onfiguration
e synonym Wlass 0.
lt storage (clnning with 0
will not be sat
storage clasare no availab
onyms. For
1,CLASS2)
S. DRTAPEstorage. CLA
1,CLASS2))
ym DRTAPEage class 1 o
to define anyfor SCRTCclass.
yms
n.
WORK will b
ass 0), but w0 or 01. If ntisfied and w
s 1. Any avble scratch t
example, de
E will use voASS will use
)
E using VOLor storage cl
y scratch synH or PRIVA
be assigned
will only be no scratch tawill remain
vailable scrattapes in class
efining:
olume serial e only volum
LSERs ass 2.
nonyms at alAT to any scr
any
apes
tch s 1,
me
ll. ratch
Saving
Activat
g your Con
Once the Co(Figur
ting (Insta
In ordinstallwill nyour c
WARrestarthe mmainfinstal
Be awdetectHoweinstallnot toexistinwill coconfignode)
nfiguration
you have deonfigurationre 3-6).
alling) a Co
der for any coled. Even wot become aconfiguration
RNING! Whrted. Any e
mainframe oframe you slling a new c
ware that if yting a chang
ever, if you al the configu modify anyng nodes do ontinue to ruguration, savwithout disr
n
efined the con panel click
onfigurati
onfigurationwhen you moactive until yn click the In
hen you clicemulated, onperating sys
should idle aconfiguratio
your systemge to its curare adding a uration whiley of the exist
not detect aun without reve the updatrupting the o
onfiguration k Save Chan
Figure 3-6.
ion
n to be used bodify the curryou re-installnstall button
ck the Instalnline tape dstem. If youall tape drivon (i.e. befo
m has multiprrent configunew control
e the existinging controlle
any changes estarting. Tted configuraoperation of
Chapter 3.
the way younges to save
Saving Chang
by the Virturently installl the configun on the Con
ll button thedrive will go ur controlleves and varyre clicking t
ple controlleuration willller (node) tog nodes are aers (nodes) ceffecting the
This allows yation, and inthe library.
Configuring
u want it, youe your config
ges
uent controlleled configur
uration. To infiguration
e Virtuent c offline ander is currenty them offlithe Install b
ers (nodes) l automatico an existingactive as lonconfigurationeir current coyou to add thnstall it (to ac
g Virtual De
u need to savguration to d
er(s) in mustration the chainstall (and apanel (Figur
controller(s)d may be boxtly online wine prior to button).
every contrally restart.
g system young as you takns. As longonfigurationhe new nodectivate the n
evices 29
ve it. On disk
t be anges activate) re 3-6).
) will be xed by
with the
roller .
u can ke care g as the n they e to the ew
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 31
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS
Mainframe Utilities
Bus-Tech provides several small utilities as well as a Unit Information Module (UIM) for the z/OS, OS/390 and MVS environments. The utilities provided include:
VTSCR – A scratch utility which sends volser scratch requests to Virtuent
VTCMD – A utility allowing Virtuent commands to be sent from the mainframe console
VTLIB – A utility allowing you to define scratch volumes to an MTL
VTHHOST – A program that runs as a started task in z/OS to allow message and command exchange between the z/OS operator console and the Virtuent controller(s).
GENSTATS – A utility that provides statistics reports on the usage of the Virtuent controller(s).
To use any of these utilities or the UIM you will need to upload a file from the MDL Host Utilities CD to your mainframe. The file you will need is called /UTIL/MVS/VT7ZOS.XMI. This file should be FTP’d to the mainframe as follows:
ftp target_system_name
(satisfy login requirements of the mainframe)
quote site recfm=fb lrecl=80
bin
put vt7zos.xmi (the file will be placed on the host as ’uid.vtzos.xmi’, where uid is the login user id used for the ftp. Alternatively, you may use put vtzos.xmi ‘filename’ to force a specific filename of your choice.)
quit
Once the file is on the mainframe use ISPF function 6 (Command Shell), and issue the command :
receive indataset(‘uid.vtzos.xmi’)
When prompted with ‘Enter restore parameters or delete or end’ enter:
da(‘BTI.MODULE’)
A ‘BTI.MODULE’ will be created with members:
CBDEC255 - The Unit Data Table for the UIM
CBDUC255 - The UIM for the Bus-Tech virtual devices
32 Virtuent User’s Guide
VTLIB - A utility to add volumes to an MTL
VTSCR - The Virtuent scratch utility
VTCMD - The Virtuent command utility
VTHHOST - The Virtuent z/OS console utility
GENSTATS – Virtuent reports utility
Configuring the Devices
z/OS, OS/390, and MVS use the Hardware Configuration Definition (HCD) utility to define devices to the system. HCD provides an interactive interface that allows you to define the system’s hardware configuration to both the channel subsystem and the operating system.
There are three alternatives for configuring Mainframe Appliance for Storage devices to the mainframe. They are:
1. Configure the devices as real 3480, 3490. or 3590 tape drives.
2. Configure the devices as a Manual Tape Library (MTL).
3. Configure the devices with a unique device type using Bus-Tech’s Unit Information Module (UIM).
Each of these alternatives will be discussed.
If you are planning on using MDL with IBM’s Object Access Method (OAM) then you should configure the Virtuent devices using alternative 2, a Manual Tape Library. OAM requires tape drives to be SMS managed. Bus-Tech’s UIM cannot be used with OAM because OAM does not recognize UIM devices as a supported drive model. The IBM document SC35-0426, “DFSMS Object Access Method Planning, Installation, and Storage Administration Guide for Object Support”, describes how to use a library for OAM object use.
Bus-Tech’s support web site contains sample I/O device gens (IOCDS) in the HCD guides found under the title “Knowledge Base” at the following link:
http://www.bustech.com/support/vtechtips.asp
Real 3480/3490/3590
Virtuent can emulate 3480, 3490, or 3590 tape drives. If your mainframe installation does not have one of these device types installed you can elect to install the Virtuent devices using that type. The advantage of using 3480/3490/3590 device types is that some applications or access methods examine device type to make sure they are writing/reading to a known tape device and these applications won’t necessarily work with Bus-Tech’s Unit Information Module (UIM).
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 33
However if you have real 3480, 3490, or 3590 tape drives configured in your system do not attempt to define Virtuent devices in this manner. Configuring Virtuent devices as a device type that is already present can result in mis-allocation where OS/390 will request a real 3480/3490/3590 cartridge on a Virtuent device or request a Virtuent tape-on-disk volume on a real 3480/3490/3590 drive.
If you do plan to use one of these device types to define Virtuent devices make sure that the esoterics configured for tape in your installation do not include this device type. More specifically, if your JCL is using the esoteric TAPE (UNIT=TAPE) then make sure that TAPE does not include the device type (3480, 3490, or 3590) you are using to define Virtuent devices.
Manual Tape Libraries
If you have 3480, 3490, and 3590 tape drives all installed in your installation then you should not define Virtuent devices as real tape drives. Doing so can result in allocation errors as described in the previous sub-section. But if you plan to use Virtuent devices with OAM or any application that checks device type then you also cannot use Bus-Tech’s Unit Information Module (UIM). In this case you must define your Virtuent devices as 3490 or 3590 tape drives and then include them in a Manual Tape Library (MTL) so that they will be isolated from your other 3490s or 3590s.
IBM introduced the concept of a Manual Tape Library (MTL) with APAR OW45271. This APAR allows standalone tape drives and their associated volumes to be SMS managed by treating a group of such drives as a logical tape library. Allocations to such a logical library are managed by SMS just as any automated tape library dataserver (ATLDS) would be with the exception that mount messages will be routed to a tape operator console rather than the ATLDS robotics. IBM document SC35-0427, “PISA Guide for Tape Libraries”, describes the issues regarding MTL support.
Begin by configuring the Virtuent devices as either 3490 or 3590 tape devices using HCD. The standard HCD 3490 / 3590 definitions should be used. On the Device/Parameter Feature definition screen for each drive, you must select MTL as YES and supply an artificial LIBRARY-ID and LIBPORT-ID. The control unit should also be defined as a 3490 / 3590 with 16 tape drives available.
All the devices in the same logical library should have the same LIBRARY-ID, with each group of 16 devices having a unique LIBPORT-ID. IBM’s requirement that there can be only 16 tape drives to a LIBPORT-ID will require you to configure multiple control units on the same channel using different logical control unit addresses when you want to configure more than 16 drives. Each control unit’s devices would have the same LIBRARY-ID, but have a unique LIBPORT-ID per control unit. For example:
34 Virtuent User’s Guide
Dev Add CU Log CU Library-ID Libport-ID E800 CU800 00 12345 01 E801 CU800 00 12345 01 E80F CU800 00 12345 01 E810 CU810 01 12345 02 E811 CU810 01 12345 02 E81F CU810 01 12345 02
Once the MTL has been defined to HCD it must be defined to SMS using the library management function. Then your ACS routines should be updated to allow jobs to select the new library with appropriate user defined ACS management, data, and storage classes and groups. For example, if you define a new esoteric called “VTAPE”, your ACS routines could allocate the dataset to the SMS storage group using the MTL whenever UNIT=VTAPE is specified in JCL.
The characteristics of Virtuent virtual tape cartridges match the SMS Media Type; “MEDIA2” for 3490 or “MEDIA4” for 3590. Be sure to specify the appropriate media type (MEDIA2 or MEDIA4) on the Library Definition screen. In addition, since SMS will request scratch tapes using the media type, you must add MEDIA2 or MEDIA4 to the list of Virtuent scratch name synonyms (see page 28).
Note that once the MTL is configured, it is treated much the same as a real library. That is, cartridges must be ‘entered’ into the library before they can be used. Therefore, you will need to define any VOLSERs to be used in your Virtuent library to the mainframe. To simplify this, the VTLIB utility may be used to enter cartridges into the MTL.
VTLIB must be executed out of an authorized library. An example of the JCL required to link VTLIB follows:
//L EXEC PGM=HEWL,PARM=’MAP,LET,LIST,NCAL,AC=1’ //SYSLMOD DD DSN=USER.LIBRARY,DISP=SHR //SYSUT1 DD DSN=&&SYSUT1,SPACE=(1024,(120,120),,,ROUND), // UNIT=SYSALLDA,DCB=BUFNO=1 //SYSPRINT DD SYSOUT=* //DDIN DD DSN=BTI.MODULE,DISP=SHR //SYSLIN DD * INCLUDE DDIN(VTLIB) NAME VTLIB® /*
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 35
The following is an example of JCL to run VTLIB:
//S2 EXEC PGM=VTLIB //SYSUDUMP DD SYSOUT=* //OUTDD DD DSN=VTLIB.LOG,DISP=SHR (recfm=fb,lrecl=80,blksize=4000) //INDD DD * * TO ENTER VOLUMES INTO THE MTL, THE SYNTAX IS AS FOLLOWS: * 1ST CHAR MUST BE AN 'M' * 4-9 IS THE STARTING VOLSER * 11-18 IS THE LIBRARY NAME ASSIGNED DURING SMS LIBRARY ADD * 20 IS THE MEDIA TYPE (DEFAULT=2). SPECIFY 4 FOR 3590 LIBRARY * 21-25 COUNT OF VOLSERS TO BE ADDED (DEFAULTS TO 1 IF BLANK * MAX COUNT=10000) * VOLSER LIB COUNT M BT0000 MTL1 5000 M AA0000 MTL2 10000 /*
The log file will list the result of each cartridge entry request, including any error codes. The VTLIB utility uses IBM's CBRXLCS macro, and the return codes and reason codes can be found in:
DFSMSdfp Diagnosis Reference (GY27-7618) section 11.4.1.
MTL-Related IBM maintenance
The PTFs for the following APARs should be applied before using Virtuent in an MTL environment:
APAR OA03749 MTL more than 1 device fails to vary on-line
APAR OA06698 Replacement tape drives get MSG IEA437I in an MTL environment
APAR OA07945 Mount hangs / timeouts using MTL with OEM Automated Library
APAR OA08963
Tape volume capacity incorrect for OAM object support users
APAR OA10482 MTL scratch volume mount error
Bus-Tech’s Unit Information Module
As an alternative to defining real 3480s, 3490s, or 3590s or using a MTL, Bus-Tech provides a user Unit Information Module (UIM) that allows Virtuent tape devices to be configured to HCD using a unique device type. Using the Bus-Tech UIM prevents the operating system from allocating Virtuent tape drives to jobs requesting a mount
36 Virtuent User’s Guide
of a real tape cartridge and vice-versa. If you are not using OAM or an application that checks device types the Bus-Tech UIM is the easiest way to configure Virtuent devices so that there will not be any allocation errors with real tape drives. Information regarding user UIMs can be found in IBM’s MVS/ESA Device Validation Support (GC28-1447) manual.
Bus-Tech’s UIM and associated UDT (Unit Data Table) must be installed into SYS1.NUCLEUS, prior to configuring the Virtuent devices in HCD. Prior to installing the UIM, it is important to back up the SYSRES volume containing the SYS1.NUCLEUS dataset in order to provide a recovery mechanism should anything fail to operate properly.
Use ISPF function 3.3 (Utilities; Move/Copy) and copy CBDEC255 and CBDUC255 from ‘BTI.MODULE’ (see page 31) into ‘SYS1.NUCLEUS’.
If CBDEC255 or CBDUC255 already exist in SYS1.NUCLEUS, then some other vendor has already supplied a user UIM using the same user device number of 255. Contact Bus-Tech support and we will arrange for a different module name to be used.
Once the UIM is installed, you can now configure the Virtuent devices in HCD. The UIM provides for four (4) control unit types of V3480, V3481, V3482 and V3483; supporting device types of V3480, V3481, V3482, and V3483 respectively. The generic names for these devices are also V3480, V3481, V3482, and V3483. If you have already defined a generic name of V348x, please contact Bus-Tech for support. Multiple virtual device types are defined to support multiple Virtuent systems or a single Virtuent with multiple virtual tape libraries configured.
You need to define a V348x tape drive to the hardware configuration for each virtual tape device you have configured in the MDL. All virtual tape drives assigned to the same virtual tape library need to be defined with the same generic name (V3480, for example). If you plan to have some drives assigned to a different virtual tape library (see page 28), then you should define that drive to a separate generic name (V3481, for example).
Once the Virtuent device definitions are active, you must either specify UNIT=V348x or hard code the unit address to allocate to a Virtuent device. In this way, regular jobs that call for real tape drives or use tapes previously catalogued on real 3480s will not allocate to Virtuent devices. Once a tape is catalogued as having been created on a Virtuent V348x device, it will only allocate to that same device type when it is called for again. Conversely, a tape catalogued as created on a real tape drive will not be allocated to a Virtuent V348x device.
Note: Bus-Tech’s UIM does not support auto-switching. If you need to auto-switch tape devices between LPARs in a sysplex, do not configure your devices with the UIM.
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 37
Virtuent Scratch Utility Program
Virtuent provides the VTSCR utility which can be used with any of the major tape management systems to keep your tape management system scratch status in sync with the Virtuent scratch status.
The VTSCR utility must be linked as an authorized program into an authorized library under the name VTSCR. It is highly recommended that RACF be used to restrict the use of VTSCR to authorized users only.
An example of the JCL required to link VTSCR follows:
//L EXEC PGM=HEWL,PARM='MAP,LET,LIST,NCAL,AC=1' //SYSLMOD DD DSN=USER.LIBRARY,DISP=SHR //SYSUT1 DD DSN=&&SYSUT1,SPACE=(1024,(120,120),,,ROUND), // UNIT=SYSALLDA,DCB=BUFNO=1 //SYSPRINT DD SYSOUT=* //DDIN DD DSN=BTI.MODULE,DISP=SHR //SYSLIN DD * INCLUDE DDIN(VTSCR) NAME VTSCR(R) /*
VTSCR runs on the mainframe and sends volume scratch requests to Virtuent. Since the tape management system (TMS) may dynamically release tapes back to scratch status, VTSCR should be periodically run to maintain synchronization between the TMS catalog and the MDL. To use VTSCR the user must run a TMS scratch report and then input that scratch report into VTSCR. VTSCR scans the scratch report for Virtuent owned volumes and sends the appropriate scratch requests to the MDL.
There are 2 methods of running VTSCR. Method 1 uses an offline tape device which points to the Virtuent controller (node). This is the preferred approach and should be used whenever you are not planning to use all the tape drives in your library.
For example, let’s assume you plan to use (32) drives on the controller (node). In the controller’s configuration, configure 33 active drives.
On your IBM mainframe define all 33 devices to z/OS. But configure the 33rd drive to remain offline at IPL. If you are defining the devices into an MTL, leave the offline drive out of the MTL. To prevent accidental allocation to this device if it were to be varied online you may wish to define it into its own unused MTL. When using this method the commands are sent to the control device without having to mount a tape volume (VOLSER) on the device.
The following JCL will run the VTSCR using the offline device:
<JCL to Generate Scratch Report Here> //LOG EXEC PGM=VTSCR,PARM=’DEV=xxxx,parms’ //VTSLOG DD DSN=VT.LOGFILE,DISP=OLD //VTSSCR DD DSN=SCRATCH.REPORT,DISP=OLD
38 Virtuent User’s Guide
where xxxx is the device address of the offline device and parms may include any of the parameters described below.
The second method for running VTSCR is to use a dedicated control tape. When using a control tape (VOLSER) rather than an offline device, VTSCR uses a control file called VTSCTRL. A DD statement for this file must be added to the JCL. The first time you run VTSCR use the following JCL:
<JCL to Generate Scratch Report Here> //LOG EXEC PGM=VTSCR,PARM='parms' //VTSLOG DD DSN=VT.LOGFILE,DISP=OLD //VTSSCR DD DSN=SCRATCH.REPORT,DISP=OLD //VTSCTRL DD DSN=VT.CTRL,UNIT=VTAPE,VOL=SER=, // DISP=(,CATLG)
Do not code the DEV=xxxx parm when using the VTSCTRL DD statement. Then, following the initial execution of VTSCR update the VTSCTRL DD statement to use the same control tape on subsequent executions of VTSCR:
<JCL to Generate Scratch Report Here> //LOG EXEC PGM=VTSCR,PARM='parms' //VTSLOG DD DSN=VT.LOGFILE,DISP=OLD //VTSSCR DD DSN=SCRATCH.REPORT,DISP=OLD //VTSCTRL DD DSN=VT.CTRL,DISP=(,KEEP)
Using VTSCR in this fashion creates a permanent control tape in the MDL library.
VTSCR Parameters
In addition to the DEV parmameter described above, any of the following parameters may be substituted as needed for parms in the sample JCL:
TYPE=x where x is used to select the tape management system. Valid types include RMM, TMS, TLMS, ZARA, CTLM, or CTLT. This is the only required parameter.
PREFIX=y where y is a string of prefix characters that will limit processing to volumes whose volume serial numbers (VOLSER) begin with the character(s) specified. Unless otherwise specified by the PREFIXLN parameter, the default prefix length is 2. ‘PREFIX=AAABAC’ would cause VTSCR to process only volumes whose serial numbers begin with AA, AB, or AC. Coding this parameter prevents VTSCR from trying to unnecessarily scratch volumes that are not stored on the MDL. If no PREFIX is specified VTSCR will process the entire scratch list.
PREFIXLN=n where n can be a single digit between 1 and 5. This value replaces the default prefix length of 2 for the ‘PREFIX=’ parameter. PARM=’PREFIX=ABCD,PREFIXLN=1’ will
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 39
cause VTSCR to process only volumes whose serial numbers begin with A, B, C, or D.
NODSNCHK Virtuent will normally validate Data Set Names if found in the scratch report as part of the scratch process. A scratch will not successfully complete if the data set name in the scratch report does not match the data set name in the HDR1 label on the volume being scratched. NODSNCHK prevents the dataset name check from being performed and is not recommended for normal use.
FREESPACE The default of VTSCR is simply to reclassify volumes being scratched as eligible for scratch allocation requests, without freeing up the space occupied by that volume. The FREESPACE parameter may be used to request that the space be freed. Note that FREESPACE requires the volumes to already be in scratch status. Therefore to immediately free the space, VTSCR will need to be run twice. The first execution should be run without the FREESPACE parameter to scratch the volumes and the second execution should be run with the FREESPACE parameter to release the space.
Keep in mind that Virtuent will automatically free the space of scratched volumes when it needs space so it is generally not necessary to run VTSCR with the FREESPACE parameter.
FREEAFTERSCR While the FREESPACE option requires a volume to already be in a scratched state, FREEAFTERSCR will immediately free space from a volume as soon as VTSCR scratches it. While FREEAFTERSCR allows you to scratch a volume and free the space associated in a single execution of VTSCR, it should be recognized that once the space has been freed the volume cannot be recovered if it was scratched by mistake.
NODATECHK Virtuent will normally check the creation date of a tape volume and will not allow any volume to be created and scratched in the same 24 hour period. Setting this parameter will allow volumes to be created and scratched on the same day. This parameter ignores the default date check in VTSCR.
IGNLCSERR This parameter will ignore any errors reported by Library Call Subsystem used by OAM with MTL volumes. Normally VTSCR will log any error returned by LCS and will stop processing scratch tapes when these errors occur. If this parameter is set, VTSCR scratch processing will continue even when LCS errors are encountered.
40 Virtuent User’s Guide
ALLVOLS This parameter will allow scratch of volumes with data set names of all zeros.
IGNLCSRC4 This will allow VTSCR processing to continue after a return code 4 from LCS processing, but terminate if the return code from LCS processing is greater than 4.
NOTCDB This will prevent VTSCR from attempting any TCDB updates. This should only be used if the TMS already performs this function.
NOTIFSCR This will prevent VTSCR from attempting to change the TCDB use attribute to scratch if Virtuent reports that the volser was already a scratch.
The output VTSLOG file will maintain a history of the results of each scratch request. The file should have a logical record length (LRECL) of 133. If an error occurs during a scratch request (such as scratching a non-existent volume) the failure will be recorded in the log file, the program will continue with the next scratch request, and a non-zero return code from the program execution will result.
The output VTSCTRL file is used to allocate a Virtuent tape device for use as a control path to pass the scratch request(s). If there are multiple tape libraries being used to contain the virtual volumes, the user must select a tape device address associated with the library containing the volumes to be scratched. Do not specify a VTSCTRL file if the DEV= parameter is used.
The VTSSCR file must point to the scratch report that the user has created using the appropriate TMS utility. The scratch report must be generated with a logical record length (LRECL) of 133. To avoid any possibility of confusion, it is strongly recommended that a single job be used that generates a current scratch list file and then runs the VTSCR utility against that file. In this way there is no possibility of accidentally running the VTSCR program against an old scratch report and causing the TMS and the MDL to become out of sync. In addition, since there is a slight time interval between the creation of the extract file and the processing of the report, Virtuent will not scratch a volume that has been created today. Additionally, the utility will not execute against a scratch report that was not created the same day.
The Scratch utility will use the data set name (dsname) information from the scratch report to verify volumes being scratched. If the data set name written in the volume header does not match the data set name on the scratch report for that volume the scratch request will be rejected.
It must be emphasized that once the VTSCR utility has completed, tapes that were successfully scratched by the utility can be re-used or erased at anytime. See page 134 for a complete description of the scratch process.
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 41
RMM Considerations
The following rules must be observed when using Virtuent with RMM:
1. Virtuent scratch volumes must be pre-defined to RMM. If Virtuent volume serial numbers have not been pre-defined as scratch to RMM then new volumes will be rejected by RMM. This will result in an unsatisfied mount request on the mainframe. To resolve the unsatisfied mount, Virtuent scratches would need to be defined to RMM, and a Virtuent LOAD command would have to be issued at the Virtuent console in order to satisfy a stalled request.
2. When defining new Virtuent scratch tapes to RMM, the ‘initialize’ option must be set to ‘no’. If ‘yes’ is accidentally used and RMM detects that the volume must be initialized (or EDGINERS is run), RMM will send a request for a ‘blank’ volume serial number to be mounted on Virtuent. Virtuent will not automatically come ready since it has no idea which volume to mount. Consequently, a manual mount requiring a Virtuent LOAD command at the Virtuent console would be needed for each volume being initialized.
3. VTSCR will process two types of RMM scratch reports; the scratch report created by EGDRPTD, or that created by EDGJRPT using the EDGRRPTE exec (EDGRPT01). Use the parameter DATEFORM(I) when running EDGRPTD to create scratch reports in order to ensure the expected date format. When the REXX exec form is used, VTSCR may not accept user tailored version of EDGRRPTE.
TMS (CA-1) Considerations
Although there are various reports supported by TMS (CA-1), VTSCR expects Report-05 or Report-06 to be used. The report generation parameters should request the field DSN17 instead of the default DSN. Otherwise, the report for multi-volume multi-file tapes will have the incorrect DSN for all but the first VOLSER and those volumes with incorrect DSN will fail the DSN validity check performed by VTSCR before scratching a tape.
Unique to CA-1 TMS environments only, VTSCR supports the following 2 additional run time parameters:
USETMC - When this parameter is specified VTSCR will directly read the CA-1 Tape Management Catalog (TMC) to find Virtuent resident VOLSERs which have been scratched. A separate execution of CA-1 scratch report utility is not required. Use of the USETMC option requires that the VTSSCR DD JCL statement point directly at the TMC (or a copy of the TMC). VTSCR will scan the TMC and send the appropriate scratch requests to the MDL for processing.
Note that when using the USETMC option VTSCR will send a scratch request for any scratch volume it finds in the TMC. This may result in a large number of VIR500I messages followed by VIR524W messages being issued to the Virtuent
42 Virtuent User’s Guide
message log whenever VTSCR is run. This is normal. The VIR500I message indicates Virtuent has received a request to scratch a VOLSER. The VIR524W message indicates the VOLSER was already scratched.
SYNC – only valid if specified along with USETMC, the SYNC option will cause VTSCR to synchronize both the Tape Control Data Base (TCDB) and the Virtuent library with the CA-1 TMC. Status of the VOLSERs in the TCDB and in the MDL will be changed from active to scratch or from scratch to active as required to match the status of the CA-1 Tape Management Catalog (TMC).
Note that when using the SYNC option VTSCR will send an unscratch request for any active volume it finds in the TMC. This may result in a large number of VIR500I messages followed by VIR524W messages being issued to the Virtuent message log whenever VTSCR is run. This is normal. The VIR500I message indicates Virtuent has received a request to unscratch a VOLSER. The VIR524W message indicates the VOLSER was already unscratched.
TMS users who use Scratch Pool Management and need to limit the eligible scratch volumes to a limited range of volsers must install the TMS usermod CL05219 (CTSMSGEX exit). When this exit is linked into IGX00030, an IPL with CLPA will be required to activate it. The exit will cause the first 8 characters of the scratch poolname to be placed into the Load_Display mount message that is sent to the tape drive. This poolname can be defined as a scratch synonym so that the Virtuent software will restrict the eligible scratch volumes to a specific prefix group.
TLMS Considerations
VTSCR expects either the TLMS003 or the TLMS043 report to be used as input.
TSM Considerations
VTSCR expects a Tivoli Storage Manager (TSM) Volume History Report to be used as input to the VTSCR DD.
VTCMD Utility Program
The VTCMD utility is provided to allow the user to issue Virtuent commands from the mainframe. This utility must be linked as an authorized program into an authorized library under the name VTCMD. It is highly recommended that RACF be used to restrict the use of VTCMD to authorized users only.
An example of the JCL to link VTCMD follows:
//L EXEC PGM=HEWL,PARM='MAP,LET,LIST,NCAL,AC=1' //SYSLMOD DD DSN=USER.LIBRARY,DISP=SHR //SYSUT1 DD DSN=&&SYSUT1,SPACE=(1024,(120,120),,,ROUND), // UNIT=SYSALLDA,DCB=BUFNO=1 //SYSPRINT DD SYSOUT=* //DDIN DD DSN=BTI.MODULE,DISP=SHR
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 43
//SYSLIN DD * INCLUDE DDIN(VTCMD) NAME VTCMD(R) /*
Like VTSCR (see page 37), VTCMD can be run using a dedicated control device or a dedicated control tape (VOLSER).
To run VTCMD using a control device use the following JCL:
//LOG EXEC PGM=VTCMD,PARM=DEV=xxxx //VTCLOG DD DSN=VT.LOGFILE,DISP=OLD //VTCCMD DD DSN=COMMANDS,DISP=OLD
Where xxxx is the device address of the control device. Typically this device would be offline as described in the previous section on VTSCR.
Alternatively, to run VTCMD using a control tape, use the following JCL:
//LOG EXEC PGM=VTCMD //VTCLOG DD DSN=VT.LOGFILE,DISP=OLD //VTCCTRL DD DSN=VT.CTRL,UNIT=VTAPE,VOL=SER=, DISP=(,CATLG) //VTCCMD DD DSN=COMMANDS,DISP=OLD
You may use the same control tape as you used with VTSCR.
The VTCMD program will read one or more Virtuent commands from the VTCCMD input file, and send each command to Virtuent for execution. A success or failure indication will be logged to the file pointed to by the VTCLOG DD statement. Note that any messages and other textual results of the command that display on the Virtuent console are not returned to the host.
The VTCCTRL file is used to allocate a Virtuent device for use as a control path to pass the Virtuent command(s). Any available virtual tape device can be used for the VTCCTRL device. Do not specify a VTCCTRL file if the DEV= parameter is used.
The VTCCMD DD statement should point to a list of Virtuent commands to be sent. The LRECL of VTCCMD cannot exceed 256. When possible, it should be created using the NONUM ISPF edit option to avoid sequence numbers at the end of the command line. This can optionally be an in-stream input file (VTCCMD DD *) of commands.
The VTCLOG DD statement points to a sequential file for logging the VTCMD results. This file should have a logical record length (LRECL) of 133. If an error occurs during command processing, the failure will be recorded in the log file, and a non-zero return code from VTCMD will result. The possible error codes are as follows:
44 Virtuent User’s Guide
0x01 Invalid data length (must be between 1 and 256 bytes)
0x02 Virtuent is configured to not accept Host-initiated console commands
0xFF(-1) A general syntax error occurred. (The Virtuent console error message “VIR891E: Invalid command syntax” was displayed.)
0xFC (-4) An “E” level error other than general syntax error occurred. (A Virtuent console error message other than VIR891E was displayed.)
A sample VTLOG output might be as follows:
VTCMD VER 1.0 VTCTRL = EA82 2004/09/10 12:47:49 CMD ERR=FF: this is an invalid command 2004/09/10 12:47:49 CMD ISSUED: q all 2004/09/10 12:47:49 CMD ERR=FC: q xxxxxxxx 2004/09/10 12:47:49 CMD ISSUED: set size=2g dev=EA80
There are two additional methods of passing the commands to VTCMD. They are:
1. Use of PARM=’WTOR’. This will result in message VIR070I ENTER Virtuent COMMAND being issued to the operator, who can then reply with the Virtuent command. The VIR070I message will be re-issued after each Virtuent command is accepted until END is entered as the reply. The VTCMD input file is not used if this method is employed. e.g.:
//LOG EXEC PGM=VTCMD,PARM=’WTOR’ //VTCLOG DD DSN=VT.LOGFILE,DISP=OLD //VTCCTRL DD DSN=VT.CTRL,UNIT=VTAPE,VOL=SER=, DISP=(,KEEP)
2. Use of PARM=’CMD=’. This allows the user to pass a single Virtuent command on the EXEC card rather than using the VTCMD input file. This also allows a user to call VTCMD from another program, and pass the command as an entry parameter. e.g.:
//LOG EXEC PGM=VTCMD,PARM=’CMD=Q SPACE’ //VTCLOG DD DSN=VT.LOGFILE,DISP=OLD //VTCCTRL DD DSN=VT.CTRL,UNIT=VTAPE,VOL=SER=, DISP=(,KEEP)
DFSMShsm Considerations
For those who plan to use Virtuent with HSM, the various SETSYS tape parameters will not accept V348x generic names as valid. For these environments, it is necessary to define Esoteric names that are unique to the various V348x devices.
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 45
To identify esoteric tape unit names to DFSMShsm, you must first define these esoteric tape unit names to MVS during system I/O generation (HCD). Then, you must include the esoteric tape unit names in a DFSMShsm SETSYS USERUNITTABLE command. Only after they have been successfully specified with the SETSYS USERUNITTABLE command can they be recognized and used as valid unit names with subsequent DFSMShsm commands.
Specifying Tape Compaction
Compaction of the virtual tape data under z/OS or OS/390 is initiated the same way as for a real compression-capable (IDRC) 3480/3490/3590. That is, the user may specify the use of compaction in the JCL by using the DCB=TRTCH=COMP parameter on the appropriate DD cards for output tapes. No JCL parameter is required for input compressed tapes.
Alternatively, the system programmer may specify the COMPACT=YES parameter in the DEVSUPxx PARMLIB member. This would result in compaction being the default option for all of the virtual drives.
It should be noted that while the compaction option should significantly reduce the amount of storage required on the Virtuent’s target file systems, there will be some impact on the data transfer performance compared to uncompressed data. The efficiency of the compaction as well as the performance impact will vary depending upon the data.
If you are writing to storage that performs data de-duplication and you want to make sure the Virtuent controller is not performing data compression you may set compression off by setting the IDRC parameter to “No” on the device configuration. IDRC=No causes the drive to ignore the compression flag received from the mainframe and write the data to the store without compressing it.
The file-size values reported by the Virtuent “QUERY” command as well as the awsdir and awsprint utilities reflect the compressed data size, not the original uncompressed size.
Missing Interrupt Timer
The MVS, OS/390, or z/OS Missing Interrupt Handler (MIH) timer value is often set at a value that is too low for the sometimes lengthy operations that can occur on a large tape cartridge. If an operation takes longer than the MIH value, the operating system will report I/O errors and possibly "box" the device, taking it out of service. For this reason, IBM recommends a MIH timer value of 20 minutes or more for tape drives, including virtual tape drives such as those on Virtuent.
46 Virtuent User’s Guide
Starting in release 3.10, Virtuent reports a preferred MIH timer value of 3000 seconds (50:00 minutes) to the Host when it is varied online, and the Host should take this value as the Virtuent devices' MIH time.
To determine the current MIH timer value, you can use the following MVS operator command:
D IOS,MIH,DEV=xxxx
where xxxx is any Virtuent tape drive address.
You can temporarily change the MIH value for Virtuent devices by entering the following MVS operator command:
SETIOS MIH,DEV=(xxxx-xxxx),TIME=mm:ss
where (xxxx-xxxx) is the range of Virtuent tape drive addresses.
For more information about the MIH timer and tape drives, refer to the IBM manual 3490 Magnetic Tape Subsystem Introduction and Planning Guide, number GA32-0297.
Dynamic Device Reconfiguration (DDR) Considerations
Since Virtuent is a virtual tape control unit, it cannot benefit from an operator or system-initiated 'swap' function. Accordingly, following any message 'IGF500I SWAP xxxx TO xxxx - I/O ERROR' for any Virtuent device, the operator must reply NO to the subsequent “## IGF500D REPLY 'YES', DEVICE, OR 'NO' ".
If the user has configured the Virtuent devices as V348x devices using the UIM, DDR swap is automatically disabled for those devices, and a swap cannot occur.
DR Logging
In z/OS environments, Virtuent controllers provide a service referred to as “DR Logging” which will log tape volume mounts and unmounts to a log file on the virtual tape library. When DR Logging is enabled, each Virtuent controller (node) defined as part of the virtual tape library will create a log file on each of the filesystems writing a single log record to the file showing each tape volume (VOLSER) it mounts and unmounts from the filesystem (Figure 13-1).
Enabling
These(VOL
If a cogeneravirtuaunmou
The pincom
By placontrorecovecomplbe usetime o
g DR Loggi
By detape lipresen
The .vonly u
N
N
e log files areLSER) files.
ontroller (noated using th
al tape libraryunted.
urpose of thmplete follow
acing the DRoller’s internery site alonlete loss of ted to help idof the failure
ng
efault, Virtueibrary. To ent in each fil
vstats file mauses the pres
Node N1
Node N2
Ch
Fi
e hidden from
de) outage she GENSTAy and report
is report is twing a contro
R log files innal storage, tng with the tathe primary pentify all tap
e.
ent controlleenable DR lolesystem wh
ay be emptysence of the f
hapter 4. Usi
igure 4-1. DR
m view so th
should occurATS utility. T
those tape v
o help determoller failure.
n the virtual the log files cape volumesprocessing fape volumes t
rs will not auogging, a hidere logging
. Virtuent dfile to determ
ing Virtuent
Logging Over
hat they cann
r, a Virtuent This report wvolumes whi
mine which
tape library can be replic
s. Then, in thfacility, the Vthat were in
automaticallydden control is to be perf
does not lookmine whethe
N1 Lo
N2 Lo
N1 Lo
N2 Lo
t with z/OS,
rview
not be mista
“Still in Usewill read all ich were mo
tape volume
rather than wcated to a sehe unlikely e
Virtuent Stilluse at the pr
y create DR filed named
formed.
k at the conteer or not to p
og
og
og
og
OS/390, or
aken for tape
e” report canthe log filesunted and ne
es may be
writing themcondary disaevent there il in Use reporimary site a
logs on the vd “.vstats”, m
ents of the fiperform DR
VOLSERs
Filesystem 1
Filesystem 2
MVS 47
e volume
n be s in the ever
m on the aster is a ort can at the
virtual must be
ile. It logging.
s
48 Virtuent User’s Guide
The procedure to create the .vstats file in a filesystem varies by Virtuent controller model. Please refer to the hardware installation guide that accompanied your system for information on how to create this control file.
Retrieving the Still In Use Report
The Still In Use report is part of the standard Virtuent general statistics report program, GENSTATS.
Please refer to the next section in this manual for instructions on how to use GENSTATS.
Running GENSTATS with the STILLINUSE parameter will produce the Still In Use report from available DR Logs.
GENSTATS Reports
In z/OS environments Virtuent controllers include a general reporting utility named GENSTATS. GENSTATS provides any or all of the following reports:
Throughput – Showing input / output by hour for the reported period
Maxtapes – Showing maximum tapes in use by hour for the reported period
Slowest Mounts – Showing the slowest tape mounts during the reported period
Still In Use – Showing tapes mounted and never unmounted
As indicated at the beginning of this chapter the GENSTATS utility is included in the VTZOS.XMI file along with other z/OS utilities. If you wish to use GENSTATS reporting you will need to first install the GENSTATS utility. The following sample JCL can be modified to suit your installation’s needs:
//L EXEC PGM=HEWL,PARM=’MAP,LET,LIST,NCAL,AC=1’ //SYSLMOD DD DSN=USER.LIBRARY,DISP=SHR //SYSUT1 DD DSN=&&SYSUT1,SPACFE=(1024,(120,120),,,ROUND), UNIT=SYSALLDA,DCB=BUFNO=1 //SYSPRINT DD SYSOUT=* //DDIN DD DSN=BTI.MODULE,DISP=SHR //SYSLIN DD * INCLUDE DDIN(GENSTATS) NAME GENSTATS(R) /*
Running GENSTATS reports is a two step process:
1. Run a collection routine on the Virtuent Controller to collect statistics into a tape volume on the virtual tape library.
2. Run the GENSTATS Utility to produce the desired report or reports.
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 49
The following JCL can be used to prepare GENSTATS reports for a single Virtuent controller (node).
//* PASS A COMMAND TO RUN THE STATFMT SCRIPT //STEP1 EXEC PGM=VTCMD,PARM=’CMD=RUNWAIT 99,DEV=xxxx’
//VTCLOG DD DSN=VT.LOGFILE,DISP=SHR
//* NOW PROCESS THE TAPE CREATED IN STEP1
//STEP2 EXEC PGM=GENSTATS,PARM=’see input parameter description below’ //GENIN DD DSN=BFLLCL,UNIT=VTAPE,LABEL=(,NL),VOL=SER=BFLLCL
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
Parameters may be entered here in place of on the EXEC statement
/*
Where:
xxxx is the control device configured for this Virtuent controller
In this example, VTAPE is an esoteric that directs allocation to a Virtuent tape device.
The parameters that can be specified are:
DATESTART - Optional. Will exclude statistics information for records preceeding the date specified.
DATEEND - Optional. Will exclude statistics information for records dated later than the date specified.
DAYCNT=xxxx - By default GENSTATS will process up to 128 days of data. DAYCNT can be used to increase the number of days to be included in the report.
DEV=xxxx - Optionally this parameter can be used in place of the GENIN DD card to target a specific device address. This can be useful when using cross-controller (node) MTL definitions and a specific controller (node) must be targeted. This parameter requires the use of the VOL= parameter to identify the tape volume (VOLSER) to be mounted. If using z/OS 1.11 or higher, it is recommended to use the SMSHONOR JCL parameter instead of DEV=, to target a specific address within an MTL.
DEVCNT=xxxx - By default GENSTATS will process up to 2000 devices. DEVCNT can be used to increase the number of devices to be processed.
MAXTAPES - This will produce a report detailing the highest number of concurrent tapes in use by hour for each of the days
50 Virtuent User’s Guide
processed. If no tapes were active during any particular hour, that cell will show a ‘***’.
When MAXTAPES is specified GENSTATS will invoke an internal sort. The following DD cards must be included in the GENSTATS JCL when MAXTAPES is specified:
//SORTIN DD (temporary work file) //SORTOUT DD (temporary work file) //SYSOUT DD SYSOUT=*
NODENAME - Since many MDL nodes may have statistics on the input file, this allows the input to be filtered to select a particular nodename. This parameter is ignored if the input file does not contain DR Logging records.
PATHCNT=xxxx - By default GENSTATS will process up to 512 paths. PATHCNT can be used to increase the number of paths processed.
PATHNAME - This allows the input data to be filtered for a particular pathname or group of pathnames. This parameter will be ignored if the input file does not contain DR Logging records. The characters specified will be used to match against the pathnames of the input records. Only the characters specified need match to accept a record. For example, if PATHNAME=/tapelib/DISK were specified, and the node paths included /tapelib/DISK1, /tapelib/DISK2, etc., all of the /tapelib/DISKx records would be processed.
STILLINUSE - This will list any tape that was mounted but has no matching unmount record.
When STILLINUSE is specified GENSTATS will invoke an internal sort. The following DD cards must be included in the GENSTATS JCL when STILLINUSE is specified:
//SORTIN DD (temporary work file) //SORTOUT DD (temporary work file) //SYSOUT DD SYSOUT=*
SLOWMOUNTS - This report will first show the average mount times for the entire day range covered. It will then list the slowest ‘n’ mount times along with the related Volser, Nodename, Pathname, Date and Time. This report can be used to identify any peak slow periods, and can provide the information required to investigate such periods, if any.
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 51
SYNCTIME - This parameter can only be used along with the DATEEND and STILLINUSE parameters. When SYNCTIME is specified, the combination of DATEEND and SYNCTIME will be used to determine the point at which time the STILLINUSE check will be applied. In addition, tapes mounted after SYNCTIME will be listed for user evaluation purposes.
THROUGHPUT - This will produce a report detailing the daily and hourly throughput numbers in GB/sec for the records that meet the NODENAME, PATHNAME, and DATE filtering parameters, if specified. At the end of the daily detail summary, the report will list some overall maximums for the range of days covered.
VOL=volser - The VOL parameter is required when using the DEV parameter to identify the tape volume (VOLSER) to be mounted.
By default, using the JCL shown above, GENSTATS will report statistics from a single Virtuent controller. However, if used in conjunction with DR Logging (see page 46) GENSTATS can produce reports including statistics from all Virtuent controllers (nodes) in a single virtual tape library.
To use GENSTATS with DR Logging you must replace the volser “BFLLCL” with volser “BFLDRL” and replace “CMD=RUNWAIT 99” with “CMD=RUNWAIT 98” in the parameter list (PARM=) on the EXEC statement for VTCMD.
Assuming that device 384 is a control device on a Virtuent controller in the library, the following JCL would produce a Still In Use report using the DR Logging log files in the virtual tape library.
//* PASS A COMMAND TO RUN THE STATFMT SCRIPT //STEP1 EXEC PGM=VTCMD,PARM=’CMD=RUNWAIT 98,DEV=384’
//VTCLOG DD DSN=VT.LOGFILE,DISP=SHR
//* NOW PROCESS THE TAPE CREATED IN STEP1
//STEP2 EXEC PGM=GENSTATS,PARM=’STILLINUSE’ //GENIN DD DSN=BFLLCL,UNIT=VTAPE,LABEL=(,NL),VOL=SER=BFLLCL //SORTIN DD SPACE=(CYL,(50)),UNIT=SYSDA //SORTOUT DD SPACE=(CYL,(50)),UNIT=SYSDA //SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
/*
52 Virtuent User’s Guide
Sample Reports
Throughput Report
The Throughput report shows the Gigabytes written (OUT) or read (IN) by the mainframe during each hour of the day.
THROUGHPUT IN GB/HR : +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ |YY/MM/DD|OUT 00|OUT 01|OUT 02|OUT 03|OUT 04|OUT 05|OUT 06|OUT 07|OUT 08|OUT 09|OUT 10|OUT 11| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | |OUT 12|OUT 13|OUT 14|OUT 15|OUT 16|OUT 17|OUT 18|OUT 19|OUT 20|OUT 21|OUT 22|OUT 23| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | |IN 00|IN 01|IN 02|IN 03|IN 04|IN 05|IN 06|IN 07|IN 08|IN 09|IN 10|IN 11| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | |IN 12|IN 13|IN 14|IN 15|IN 16|IN 17|IN 18|IN 19|IN 20|IN 21|IN 22|IN 23| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ |08/11/07|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | |0000.00|0000.00|0000.00|0000.00|0018.42|0029.31|0031.24|0015.28|0000.00|0000.00|0000.00|0000.00| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | |0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | |0000.00|0000.00|0000.00|0000.00|0087.56|0129.60|0132.00|0063.20|0000.00|0000.00|0000.00|0000.00| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ MAXI+O/HR=00163G TOT/DAY=00506G OUT/DY=00094G IN/DY=00412G MAXO/HR=00031G MAXI/HR=00132G MOUNTS/DY=06656 MAXMNT/HR=02112 +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ |08/11/10|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0007.73|0000.00| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | |0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | |0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0021.05|0000.00| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | |0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00|0000.00| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ MAXI+O/HR=00028G TOT/DAY=00028G OUT/DY=00007G IN/DY=00021G MAXO/HR=00007G MAXI/HR=00021G MOUNTS/DY=00418 MAXMNT/HR=00421 COUNT OF UNLOAD RECORDS :0007057 COUNT OF UNLOADS W/OUTPUT STATS:0007057 COUNT OF UNLOADS W/INPUT STATS :0007057 MAXIMUM OUTPUT/HR :000031.00G MAXIMUM OUTPUT/DAY :000094.26G MAXIMUM INPUT/HR :000132.00G MAXIMUM INPUT/DAY :000412.00G MAXIMUM THROUGHPUT/HR :000163.25G MAXIMUM THROUGHPUT/DAY :000506.65G MAXIMUM MOUNTS/HR :02112 MAXIMUM MOUNTS/DAY :06656 EFFECTIVE COMPRESSION RATIO : 5.5 TO 1
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 53
Max Tapes Report
The Max Tapes report shows the maximum number of tapes mounted at anytime during each hour of the day.
MAX TAPES IN USE PER HR : +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ |YY/MM/DD| 00| 01| 02| 03| 04| 05| 06| 07| 08| 09| 10| 11| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | | 12| 13| 14| 15| 16| 17| 18| 19| 20| 21| 22| 23| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ |08/11/07| ***| ***| ***| ***| ***| ***| ***| ***| ***| ***| ***| ***| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | | ***| ***| ***| ***| 020| 021| 020| 020| ***| ***| ***| ***| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ |08/11/10| ***| ***| ***| ***| ***| ***| ***| ***| ***| ***| 017| ***| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+ | | ***| ***| ***| ***| ***| ***| ***| ***| ***| ***| ***| ***| +--------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+
Slow Mounts Report
The Slow Mounts report shows the longest times Virtuent took to respond to a request to mount a VOLSER.
AVERAGE MOUNT RESPONSE (SECS.) :000.008 TOP 25 SLOWEST MOUNTS (SECS.): NODENAME TIME VOLSER DATE TIME PATH bti 000.058 H00090 2008/11/07 17:27:12 tapelib2/H0 bti 000.059 GF0491 2008/11/07 18:06:57 tapelib/GF bti 000.059 G00541 2008/11/07 18:58:34 tapelib2/G0 bti 000.059 H00143 2008/11/07 18:09:31 tapelib2/H0 bti 000.060 GB0147 2008/11/07 17:27:12 tapelib/GB bti 000.060 G00592 2008/11/07 18:05:39 tapelib/G0 bti 000.061 GB0337 2008/11/07 18:06:57 tapelib/GB bti 000.061 H00300 2008/11/07 18:54:26 tapelib2/H0 bti 000.061 GC0574 2008/11/07 18:54:26 tapelib/GC bti 000.061 G00562 2008/11/07 19:06:16 tapelib2/G0 bti 000.061 GC0575 2008/11/07 18:54:26 tapelib/GC bti 000.061 G00319 2008/11/07 17:39:40 tapelib2/G0 bti 000.061 G10018 2008/11/07 17:14:22 tapelib/G1 bti 000.062 G40051 2008/11/07 17:14:22 tapelib/G4 bti 000.063 G40169 2008/11/07 18:54:26 tapelib/G4 bti 000.063 G30567 2008/11/07 18:13:17 tapelib/G3 bti 000.064 G10019 2008/11/07 17:19:14 tapelib/G1 bti 000.064 G10058 2008/11/07 18:39:58 tapelib/G1 bti 000.064 G50379 2008/11/07 17:23:39 tapelib/G5 bti 000.064 G00312 2008/11/07 17:36:26 tapelib2/G0 bti 000.064 H00111 2008/11/07 17:43:25 tapelib2/H0 bti 000.064 GB0318 2008/11/07 17:58:40 tapelib/GB bti 000.065 G00110 2008/11/07 17:01:29 tapelib2/G0 bti 000.065 GA0560 2008/11/07 17:54:14 tapelib/GA bti 000.065 G70006 2008/11/07 18:39:58 tapelib/G7
54 Virtuent User’s Guide
Still in Use Report
The Still in Use report processes the Virtuent DR Logs (see the section title “DR Logging” on page 46) and produces a list of tapes that have been mounted and never unmounted.
VOLSERS STILL MOUNTED : NODENAME DEVICE VOLSER LAST MOUNTED PATH bti A405 GF0825 2008/11/10 10:23:18 tapelib/GF bti A404 GF0826 2008/11/10 10:23:18 tapelib/GF bti A419 G09009 2008/11/07 19:26:43 tapelib/G0 bti A415 G09005 2008/11/07 19:26:43 tapelib/G0 bti A414 G09004 2008/11/07 19:26:43 tapelib/G0 bti A413 G09003 2008/11/07 19:26:43 tapelib/G0 bti A40F H00365 2008/11/10 10:23:18 tapelib2/H0
Chapt
Overvie
Configu
Global
ter 5. U
ew
In z/Othe oprequesdrive.volumInsteaLoad Virtueused twheth
uration Pa
Whenbe spepage (
Using Vir
OS and OS/3perating systst for a volum Virtuent use
mes. Howevead, VSE showDisplay coment using justo send a Loaher you are u
arameters
n configuringecified as an(See Figure
ALLOWV
rtuent wi
90 environmem. Originame on a speces the Load er, VSE doews either the
mmand, so mst the operatiad Display c
using Epic, D
Unique to
g Virtuent fon additional p5.1 ) in orde
VSEUTILITI
Figure
C
ith VSE
ments, Virtuelly, these cocific tape driDisplay com
es not send Le job name o
mount requesing system fucommand to Dynam/T or
o VSE
or use with Vparameter iner to allow th
IES YES
5-1. Global O
Chapter 5. U
E
ent receives ommands infive by lighti
mmands to mLoad Displayor the mountsts cannot befunctions. In
Virtuent. Tno TMS.
VSE systemsn the Global ohe VSE utilit
Options for VS
Using Virtuen
Load Displaformed an oping the LCDmount scratchy commandsted volume se fulfilled aunstead, a utilThe program
s the followinoptions sectities to work
SE Systems
nt with VSE/
ay commandperator of a m on the top oh tapes or in
s the way z/Oserial numbeutomatically lity program used depend
ng parameteion on the Dproperly:
/ESA 55
ds from mount of the nput OS does. er in the by must be
ds upon
er should Device
56 Virtuent User’s Guide
Device Specific
When configuring virtual devices for VSE use, there are two device specific parameters used to help direct mount requests and send replies to the VSE console.
OSADDR – This parameter is required to specify a 4 digit address (0180) for each drive to use when replying to a mount request from a TMS or VIRMOUNT. Note: There may be a difference between the real channel address and the VSE address when running VSE under VM.
GROUP – Used to define several devices for use by one VSE system. When more than one VSE LPAR, CPU, or guest share a Virtuent controller, you must set up a separate group for each VSE. This allows the screen scraper or the VIRMOUNT program to ensure that when a mount request is received, the volume is mounted on a virtual address belonging to that VSE.
See the section ‘Adding Devices’ in the chapter Configuring Virtual Devices for more detailed information.
VSE Programs
The following VSE programs are supplied with all Virtuent-based controllers:
VIRMOUNT– Utility for mounting volumes in a non tape manager environment or for some specialized situations such as mounting an unlabeled tape.
VIRSSE and VIRSSD – REXX scripts for the EPIC or Dynam/T environments that are run continuously, usually in a dynamic partition.
VIRLDSPL – An assembler subprogram that is invoked by the REXX scripts.
VIREPSCR and VIRDTSCR – Programs are used to scratch volumes used by Epic and Dynam/T respectively. Uses a module supplied by the TMS vender to access the catalog and search for volumes in scratch status. The volume is placed in scratch status and will eventually be overwritten as space is used up, but it is not erased during this execution.
VIREPERA and VIRDTERA - Programs are used to erase the contents of volumes used by Epic and Dynam/T respectively. Uses a module supplied by the TMS vender to access the catalog and search for volumes in scratch status. If the volume has already been scratched by the VIRxxSCR program, then it will be erased to free up space. Use of these programs is optional.
VIRMAINT – Program reads commands on SYSIPT and can be used in a non tape manager environment to scratch, erase, or unscratch volumes. It can also be used in TMS environments. Note: Use of the erase function can result in lost data if used improperly. Make sure of your SYSIPT data when running this program.
Chapter 5. Using Virtuent with VSE/ESA 57
VIRCMD – Program reads SYSIPT and sends console commands or script execution commands to the unit.
VIRDTEXT – Dynam/T message exit program that may be used instead of VIRSSD screen scraper. Invoked by DTOPTIONS MSGHOOK(VIRDTEXT).
VSE Sample Jobs
Please note: These are samples of JCL and may need to be modified to fit you environment and library requirements.
JMOUNT – Execute the VIRMOUNT program
JVIRSSE and JVIRSSD – Executes the Epic or Dynam/T screen scraper REXX script (VIRSSE or VIRSSD).
JEPSCR and JDTSCR – Executes the Epic or Dynam/T scratch utility (VIREPSCR or VIRDTSCR).
JEPERA and JDTERA – Executes the Epic or Dynam/T erase utility (VIREPERA or VIRDTERA).
JVIRMNT – Executes the VIRMAINT utility.
JVIRCMD – Executes the VIRCMD utility.
Tape Drives
A tape drive address must be configured in VSE for each active virtual tape drive defined to Virtuent. In addition, when a tape management system like Dynam/T, CA-EPIC, or BIM-EPIC is in use one tape drive address will be reserved for use as a control device and will not be available for use by VSE applications. It is not recommended that you mix device types on one unit, but if you do so, make sure you allocate device types on a control unit boundary (usually 16 devices per CU).
VSE
You may use the following device types:
3490E Mode EML
3590B (TPA) Mode EML
EPIC ERD 3490E - ADD UCB=CUU,DEV=3490,FEAT=EI
3590B - ADD UCB=CUU,DEV=TPA,FEAT=TI
58 Virtuent User’s Guide
VIRMOUNT Utility
If your VSE system uses Dynam/T, CA-EPIC, or BIM-EPIC tape management skip this section and follow the instructions in the next section for setting up the VIRSSD or VIRSSE procedure to capture tape mount requests.
The VIRMOUNT utility is provided for VSE systems not running tape management software. VIRMOUNT is a batch program that issues a request to Virtuent to mount a volume on a virtual tape address. Job control for VIRMOUNT can be added to any batch job needing to mount a virtual tape volume.
VIRMOUNT is provided on the MDL Utilities CD in the file /UTIL/VSE/VIRMOUNT.
To run VIRMOUNT, you must assign SYS004 to a virtual address as a control device.
Then set the following parms separated by commas:
1. A 6 digit volser (or SCRTCH or a synonym, if used)
2. S N or A for standard labeled, nonlabeled, or ASCII labeled
3. CUU device address to be used. May be ANY to mount a volume on any free virtual address Or *** to cause the volume to be mounted on the control device NOTE - *** FUNCTIONS LIKE AN MVS MOUNT AND NO ERROR INFO IS RETURNED IF THE MOUNT FAILS FOR ANY REASON. MOUNT REQUESTS FOR OTHER ADDRESSES WILL RETURN ERRORS IF THE MOUNT FAILS.
Examples:
// ASSGN SYS004,280 // EXEC VIRMOUNT,SIZE=AUTO,PARM='FTAPES,S,***’ This will mount a standard labeled scratch tape using the synonym FTAPES on the control drive address (0280). // ASSGN SYS004,280 // EXEC VIRMOUNT,SIZE=AUTO,PARM='V00030,S,281’ This will mount standard labeled volume V00030 on address 281. // ASSGN SYS004,280 // EXEC VIRMOUNT,SIZE=AUTO,PARM='SCRTCH,S,ANY’ This will mount a standard labeled scratch tape using no synonym on any available address in same GROUP as 280.
It is important to unload the virtual volume when it is no longer needed, either in your program or via JCL (MTC, etc.) Otherwise the volume will remain mounted and the address will not be free for mounts.
Chapter 5. Using Virtuent with VSE/ESA 59
VIRMAINT Utility
Primarily intended for non-tape manager environments, but can be used in special cases with Dynam/T and EPIC as well. This program can perform three separate functions on individual volumes.
1. The S option is used to scratch volumes and make them available for reuse, but the volume contents still exist.
2. The U option is used to unscratch a volume already in scratch status. 3. The E option is used to erase the contents of an already scratched volume.
Assign SYS005 to an available virtual tape address. The program accepts input from SYSIPT and each input line can contain a single command. Terminate the input with a /*.
You would rarely have a use for the unscratch U option. The scratch S function would be the most commonly used of the three. Normally the automatic reclamation of space would be sufficient, but you might find it useful to free up space manually on occasion with the E option.
Examples:
// JOB VIRMAINT PERFORM MAINTENANCE ON VTAPE // ASSGN SYS005,181 ASSIGN TO AN AVAILABLE VTAPE ADDRESS // EXEC VIRMAINT,SIZE=AUTO S B00000 (Scratch) U B00000 (Unscratch) S D00000 (Scratch) E D00000 (Erase the previously scratched volume)) /* /&
Dynam/T Support
You may choose to use either the VIRSSD screen scraper or the Dynam/T message exit, but not both. The advantage of the message exit is that you do not have the overhead of a REXX script (fairly low) and continuous use of a dynamic partition. If you already are using a message exit, you may choose to use the screen scraper instead. No support is provided for integrating message exits. For more information about the message exit, see the Dynam/T documentation.
You should set your DTOPTIONS to include the following: ACCEPT(YES) PROTECT(YES) CATCHK(NO) OWNCHK(YES) STOP(NO) (recommended for performance)
60 Virtuent User’s Guide
VIRSSD Utility for Dynam/T Operation
Installation of VIRSSD is only required if your system is running Dynam/T and not using the message exit . Note: Virtuent volume serial numbers must begin with a user selectable one character prefix when Dynam/T is used.
The REXX procedure VIRSSD captures mount requests issued by Dynam/T and sends them to Virtuent. VIRSSD runs continuously under VSE. VIRSSD uses an assembler program named VIRLDSPL to send load display messages to Virtuent.
Three installation steps must be completed to successfully install VIRSSD:
1. You must catalog the VIRLDSPL phase into a VSE Library.
2. You must catalog the VIRSSD procedure into a VSE library.
3. You must tailor the JCL and set the correct parms for the REXX script
VIRLDSPL is provided on the Virtuent Utilities CD in /UTIL/VSE. The file includes the assembler source code along with sample JCL statements for cataloging VIRLDSPL.
VIRSSD is provided on the Virtuent Utilities CD in /UTIL/VSE.
Once VIRLDSPL and VIRSSD are cataloged you can tailor the JCL to send mount requests to Virtuent.
The parameters separated by spaces are as follows:
Single digit indicating the number of units or nodes supported (1 – 6)
One character OWNER ID used for the first volume prefix and library
Synonym used for scratch requests for the first library. If no synonym is specified on the unit, use SCRTCH.
Optional parms if more than one prefix/library is used:
One character OWNER ID used for the second volume prefix and library
Synonym used for scratch requests for the second library. If no synonym is specified on the unit, use SCRTCH.
One character OWNER ID used for the third volume prefix and library
Synonym used for scratch requests for the third library. If no synonym is specified on the unit, use SCRTCH.
Sample execute statement for Dynam/T environment: // EXEC REXX=VIRSSD,PARM='3 A SCRTCH B BTAPES D DTAPES'
This sample statement specifies 3 nodes are used. Scratch mount requests for volumes with OWNER=A or input volumes with A as the first character will be processed and the scratch volume mount requests will use no synonym. Scratch
Chapter 5. Using Virtuent with VSE/ESA 61
mount requests for volumes with OWNER=B or input volumes with a B prefix will be processed and the scratch volume mount requests will use synonym BTAPES. Scratch mount requests for volumes with OWNER=D or input volumes with a D prefix will be processed and the scratch volume mount requests will use synonym DTAPES.
Once VIRSSD is executing you may terminate it by typing:
MSG xx, DATA=HI
Where xx is the partition ID of the partition where VIRSSD is executing.
You may also manually mount volumes using VIRSSD. This is be useful when you want to mount a non-labeled volume or mount a volume for VM to use. The command format to manually mount a volume is:
MSG xx,DATA=vvvvvv dev l
vvvvvv = volume serial number (VOLSER) of the tape to be mounted or SCRTCH (or an alias for SCRTCH)
dev is either the device name on the VIR controller to be used or ‘ANY’ to allow any device to be used. Note: the device name is not necessarily the same as the VSE CUU, particularly in a VM environment.
l is the label type. S=STANDARD, A=ASCII, or N=UNLABELED.
Dynam/T Message Exit
The supplied exit program , VIRDTEXT, requires that user parameters be specified just as the REXX script does and should produce the same results. Look for the user parms section near the start of the assembler source code:
* ******************************************************************** * START OF USER PARAMETERS * * ******************************************************************** VTPPARMS , NODES=1, NODE1=0000, NODE2=0000, NODE3=0000, NODE4=0000, NODE5=0000, NODE6=0000, OWNID1=*, SYN1=SCRTCH, OWNID2=*, SYN2=SCRTCH, OWNID3=*, SYN3=SCRTCH * ******************************************************************** * END of USER PARAMETERS * * ********************************************************************
62 Virtuent User’s Guide
Change only the parms that apply to your environment. You must have at least one node, a node1 address, and an ownid1 specified. Be careful of continuation columns, etc. The node addresses refer to the control drive address on each node for this VSE. If you have, for instance two nodes with one prefix (A) and volume range (A00000-A99999), it might look like this:
Nodes=2 Node1=0180 Node2=0390 Ownid1=A
To invoke the exit program after it is catalogued, set
DTOPTIONS MSGHOOK(VIRDTEXT)
And restart Dynam/T.
Using Dynam/T
The VIRSSD REXX script or Dynam/T message exit look for CADT008D and CADT004D mount messages issued by Dynam/T. CADT008D messages (mount a scratch volume) are checked for the required owner id and are ignored if it does not match. The CADT004D messages (mount an input volume) are checked for a volume label starting with the same character(s) as the owner ID and are ignored if the there is not a match.
When the Dynam/T mount message indicates that the input or scratch volume belongs to Virtuent, the volume will be mounted on an available virtual tape address, and the CADTxxxx message will receive a reply with the drive address.
Create New Tape Data Sets
JCL statements that define new tape data sets to the Dynam/T catalog which will reside on a Virtuent volume must include the OWNER=c, and CLOSE=UNL parameters. The CLOSE=UNL parameter is important to ensure that the virtual volume is not left mounted after the job completes.
Example – Define a Dataset for the VTC
// JOB DEFINE // EXEC DYNCAT DEFINE 'VIR.TEST.1' TAPE OWNER=B CLOSE=UNL /* /&
Prepare a Scratch Pool
Virtuent has a console command (INIT) used to initialize scratch tape volumes in groups by specifying a starting volume number and the number of volumes to create. You should use the following example to create a scratch pool in the DYNAM
Chapter 5. Using Virtuent with VSE/ESA 63
catalog and specify the same volume numbers as you created on the Virtuent controller. Note that the first character of the volume numbers must match the Owner ID used for VIRSSD or VIRSSE and the dataset definitions.
NOTE: You must specify PROTECT=YES in your Dynam/T option macro to allow volumes defined with SCRPOOL to be opened by Virtuent without physically initializing them.
It is extremely important that Virtuent volumes have been predefined with SCRPOOL.
If Virtuent mounts a scratch volume which has not been defined with SCRPOOL, Dynam/T will reissue the mount message. Conversely, if you have plenty of volumes defined in the scratch pool, but you have not created them on the virtual library with using the Virtuent INIT function, the mounts will not be satisfied and you will get messages on the Virtuent console that there are no volumes available.
EXAMPLE – Prepare a Scratch Pool for the VTC
// JOB DYNAM SCRPOOL // EXEC DYNCAT SCRPOOL FIRSTVOL=A00000 LASTVOL=A99999 DEN=NO OWNER=A /* /&
Volume Scratching and Erasing with Dynam/T
When tapes are changed to scratch status in the Dynam/T catalog, it is necessary to inform Virtuent to scratch the virtual tape files associated with those volumes; making the volumes available again as scratch tapes. The VIRDTSCR program is provided for that purpose.
VIRDTSCR is provided on the Virtuent Utilities CD in the file /UTIL/VSE/VIRDTSCR. The file includes the assembler source code along with sample JCL statements for cataloging VIRDTSCR. Access to the vendor supplied DYNACC object module is required. Modify the JCL to meet your installation’s needs and catalog the VIRDTSCR phase into a VSE library.
The sample JCL below runs the VIRDTSCR utility to scratch volumes on the tape library. You must specify a parm with the owner ID. If you have more than one library prefix, you need to execute the program again with that owner ID.
// JOB JSCRTCH SCRATCH VIRTUAL TAPE VOLUMES // ASSGN SYS005,421 ASSIGN TO AN AVAILABLE DEVICE ADDRESS // EXEC VIRDTSCR,SIZE=AUTO,PARM=’B’ // EXEC VIRDTSCR,SIZE=AUTO,PARM=’C’ /&
Once volumes are scratched on the tape library, they are eligible to be overwritten in the future should the storage capacity reach a predefined threshold. If you wish to
64 Virtuent User’s Guide
free up space before that, VIRDTERA can be used. This will look in the Dynam/T catalog for scratch volumes that match the volume prefix in the user supplied parm and, if the volume is scratched on the virtual tape library, it will be erased down to the VOL1 and HDR1 labels.
VIRDTERA is provided on the Virtuent Utilities CD in the file /UTIL/VSE/VIRDTERA. The file includes the assembler source code along with sample JCL statements for cataloging VIRDTERA. Access to the vendor supplied DYNACC object module is required. Modify the JCL to meet your installation’s needs and catalog the VIRDTERA phase into a VSE library.
The sample JCL below runs the VIRDTERA utility to erase scratch volumes on the library. You must specify a parm with the owner ID. If you have more than one library prefix, you need to execute the program again with that owner ID.
// JOB JERASE ERASE VIRTUAL TAPE VOLUMES // ASSGN SYS005,421 ASSIGN TO AN AVAILABLE DEVICE ADDRESS // EXEC VIRDTERA,SIZE=AUTO,PARM=’B‘ // EXEC VIRDTERA,SIZE=AUTO,PARM=’C‘ /&
BIM-EPIC ACL Support
The support described in this section is provided by BIM-EPIC Release 6.4B and above. BIM-EPIC users with a single Virtuent controller or multiple Virtuent controllers that do not share volumes, are encouraged to use this option. Synchronization between the BIM-EPIC catalog and the Virtuent controller is done automatically.
BIM-EPIC supports the Virtuent controller as an Automatic Cartridge Loader (ACL) device in the same manner it supports ACL’s from other vendors.
BIM-EPIC uses an application program interface (API) to communicate directly with Virtuent in order to mount, scratch, or unscratch Virtuent-resident tape volumes. None of the Virtuent supplied VSE utilities described elsewhere in this manual are used in these activities.
The “BIM-EPIC Installation and System Guide” describes how Virtuent is defined to BIM-EPIC.
BIM-EPIC tape pools must be used for Virtuent-resident tape volumes. Their definition must correspond to the Virtuent volser prefix used. The “ MAS Support” section of the “BIM-EPIC Installation and System Guide” describes how this is done. (Note: Mainframe Appliance for Storage or MAS was the original product name for Virtuent-based controllers). All references to tape volume serial numbers required are now user definable as a one character prefix. IE: B or A, etc. followed by 5 digits. Make sure the tape pool consists of the same volume serial numbers as you define with the Virtuent INIT function.
Chapter 5. Using Virtuent with VSE/ESA 65
For each VSE BIM-EPIC system (VM Guest, LPAR, or physical CPU) that will use the same Virtuent controller, a "control drive" must be reserved to communicate with Virtuent. This drive is not usable for tape I/O purposes, but is required for BIM-EPIC's internal use.
VIRSSE Utility for EPIC Operation
Installation of VIRSSE is only required if your system is running EPIC and you are not using the BIM ACL support.
The REXX procedure VIRSSE captures mount requests issued by EPIC and sends them to Virtuent. VIRSSE runs continuously under VSE. VIRSSE uses an assembler program named VIRLDSPL to send load display messages to Virtuent.
Three installation steps must be completed to successfully install VIRSSE:
1. You must catalog the VIRLDSPL phase into a VSE Library.
2. You must catalog the VIRSSE procedure into a VSE library.
3. You must tailor the JCL and set the correct parms for the REXX script.
VIRLDSPL is provided on the Virtuent Utilities CD in /UTIL/VSE. The file includes the assembler source code along with sample JCL statements for cataloging VIRLDSPL.
VIRSSE is provided on the Virtuent Utilities CD in /UTIL/VSE.
Once VIRLDSPL and VIRSSE are cataloged you can tailor the JCL to send mount requests to Virtuent.
The parameters separated by spaces are as follows:
Single digit indicating the number of units or nodes supported (1 – 6).
One character Pool ID used for the first volume pool and library.
Synonym used for scratch requests for the first library. If no synonym is specified on the unit, use SCRTCH.
Optional parms if more than one prefix/library is used:
One character Pool ID used for the second volume pool and library.
Synonym used for scratch requests for the second library. If no synonym is specified on the unit, use SCRTCH.
One character Pool ID used for the third volume pool and library.
Synonym used for scratch requests for the third library. If no synonym is specified on the unit, use SCRTCH.
Sample execute statement for EPIC environment:
66 Virtuent User’s Guide
// EXEC REXX=VIRSSE,PARM='3 A SCRTCH B BTAPES DTAPES'
This sample specifies 3 nodes are being used. Scratch mount requests for volumes with POOL=A or input volumes with A as the first character will be processed and the scratch volume mount requests will use no synonym. Scratch mount requests for volumes with POOL=B or input volumes with a B prefix will be processed and the scratch volume mount requests will use synonym BTAPES. Scratch mount requests for volumes with OWNER=D or input volumes with a D prefix will be processed and the scratch volume mount requests will use synonym DTAPES.
Once VIRSSE is executing you may terminate it by typing:
MSG xx, DATA=HI
Where xx is the partition ID of the partition where VIRSSE is executing.
You may also manually mount volumes using VIRSSE. This is be useful when you want to mount a non-labeled volume or mount a volume for VM to use. The command format to manually mount a volume is:
MSG xx,DATA=vvvvvv dev l
vvvvvv = volume serial number (VOLSER) of the tape to be mounted or SCRTCH (or an alias for SCRTCH)
dev is either the device name on the VIR controller to be used or ‘ANY’ to allow any device to be used. Note: the device name is not necessarily the same as the VSE CUU, particularly in a VM environment.
l is the label type. S=STANDARD, A=ASCII, or N=UNLABELED.
Using CA-EPIC or BIM-EPIC
The VIRSSE REXX script looks for mount messages issued by EPIC. VIRSSE will only process EP001 and EP002 messages for normal operation. The EP002 messages (mount a scratch volume) are checked for the Pool ID field and ignored if it is not in the message. For VIRSSE to work properly you must specify TPL=c when defining data sets to the EPIC catalog. The EP001 messages (mount an input volume) are checked for a volume label starting with the Pool ID character and are ignored if the volume label is anything else. Note that EP164 mount messages are also processed for the sequential initialization function only.
When the message indicates that the input or scratch volume belongs to a Virtuent controller, a volume will be mounted on an available virtual tape address, and the EP001 or EP002 message will receive a reply with the drive address.
Chapter 5. Using Virtuent with VSE/ESA 67
The following options should be used EPIC. EPS102=YES EPS028=YES EPS033=YES UNLOAD=YES EPS095=YES AUTOSTP=NO (recommended for performance)
Virtuent has a console command (INIT) used to initialize scratch tape volumes in groups by specifying a starting volume number and the number of volumes to create.
You should use the following example to create a scratch pool in the EPIC catalog and specify the same volume numbers as you created on the Virtuent library. When the dummy dataset is deleted in the last statement, all of the added volumes will be put in scratch status. The INIT command should specify EPIC=YES or the volumes will not be recognized as owned by EPIC.
NOTE: You must also set the special option EPS033=YES at EPIC startup in order to use the tape defined in the scratch pool without physically initializing them.
It is extremely important that Virtuent volumes have been predefined to EPIC in this way. If Virtuent mounts a scratch volume which has not been defined, EPIC will reissue the mount message. Conversely, if you have plenty of volumes defined in the scratch pool, but you have not created them on the Virtuent library using the Virtuent INIT function, the mounts will not be satisfied and you will get messages on the Virtuent console that there are no volumes available.
EXAMPLE - Prepare scratch pools
// JOB DEFINE A DUMMY DN AND ADD VERSIONS // EXEC TSIDMNT // JOB TSIDPOL // LIBDEF PHASE,CATALOG=EPICLIB.EPIC BIM-EPIC INSTALL LIBRARY // LIBDEF *,SEARCH=EPICLIB.EPIC BIM-EPIC INSTALL LIBRARY // OPTION CATAL // EXEC ASSEMBLY POOL01 TSIDPOL (E,E00000,E00100),(F,F00000,F00100), X (G,G00000,G00100),TAPE=YES TSIDMAP END=YES END /* // EXEC LNKEDT /* SET SDL TSIDPOL,SVA /* /& /* /&
68 Virtuent User’s Guide
Creating New Tape Data Sets
When you define tape data sets to the CA-EPIC catalog that are to reside on the Virtuent library, include either the OWN=cc parameter (one or two characters) or the TPL=c parameter. Do not mix them. All Virtuent owned datasets used for a single EPIC catalog must use the same one or two character ID.
EXAMPLE – Define a Tape Dataset for Virtuent Using a Pool ID
// JOB DEFINE A DATASET // EXEC TSIDMNT CAT 'VIR.TEST.1' MOD=00 CYC=2 TPL=B /&
Volume Scratching and Erasing with EPIC
When tapes are changed to scratch status in the EPIC catalog, it is necessary to inform Virtuent to scratch the virtual tape files associated with those volumes in order to make the volumes available again as scratch tapes. The VIREPSCR program is provided for that purpose.
VIREPSCR is provided on the Virtuent Utilities CD in the file /UTIL/VSE/VIREPSCR. The file includes the assembler source code along with sample JCL statements for cataloging VIREPSCR. Access to the vendor supplied TSIDAC2 object module is required. Modify the JCL to meet your installation’s needs and catalog the VIREPSCR phase into a VSE library.
The sample JCL below runs the VIREPSCR utility to remove scratch volumes from the Virtuent library. You must specify a parm with the Pool ID. If you have more than one Pool prefix, you need to execute the program again with that Pool ID.
// JOB JSCRTCH SCRATCH VIRTUAL TAPE VOLUMES // ASSGN SYS005,421 ASSIGN TO AN AVAILABLE DEVICE ADDRESS // EXEC VIREPSCR,SIZE=AUTO,PARM=’B’ // EXEC VIREPSCR,SIZE=AUTO,PARM=’C’ /&
Once volumes are scratched on the Virtuent library, they are eligible to be overwritten in the future should the storage capacity reach a predefined threshold. If you wish to free up space before that, VIREPERA can be used. This will look in the EPIC catalog for scratched volumes matched the Pool ID in the user supplied parm and, if the volume is scratched on Virtuent, it will be erased down to the VOL1 and HDR1 labels.
VIREPERA is provided on the Virtuent Utilities CD in the file /UTIL/VSE/VIREPERA. The file includes the assembler source code along with sample JCL statements for cataloging VIREPERA. Access to the vendor supplied DYNACC object module is required. Modify the JCL to meet your installation’s needs and catalog the VIREPERA phase into a VSE library.
Chapter 5. Using Virtuent with VSE/ESA 69
The sample JCL below runs the VIREPERA utility to erase scratch volumes on the Virtuent library. You must specify a parm with the Pool ID. If you have more than one Pool ID, you need to execute the program again with that Pool ID.
// JOB JERASE ERASE VIRTUAL TAPE VOLUMES // ASSGN SYS005,421 ASSIGN TO AN AVAILABLE DEVICE ADDRESS // EXEC VIREPERA,SIZE=AUTO,PARM=’B‘ // EXEC VIREPERA,SIZE=AUTO,PARM=’C‘ /&
All Environments
Multiple VSE Images
If you are using Dynam/T, CA-EPIC, or BIM-EPIC and you are running multiple VSE guest machines under VM or multiple VSE LPARs you need to group virtual tape drives together by VSE system on the Virtuent controller. To do this code the GROUP parameter when configuring virtual tape drives All tape drives attached to the same VSE guest, including the control drive used by VIRSSD and VIRSSE , must be assigned the same group number. Virtuent uses the group number assigned to the VIRSSD and VIRSSE control drive to determine which other drives are available for responding to a mount request received from a specific VSE machine (guest).
Specifying Tape Compaction
Virtuent supports write compression. In VSE, write compression is activated by specifying a mode for the tape drive. The default value can be set on the ADD statement(s) at IPL time.
Alternatively, the compression option can be changed on individual assign statements or by TMS data set definitions.
No mode set parameter is required to read compressed data.
It should be noted that while the compaction option should significantly reduce the amount of storage required on the virtual tape library, there will be some impact on the data transfer performance compared to uncompressed data. The efficiency of the compaction as well as the performance impact will vary depending upon the data.
The file-size values reported by Virtuent “QUERY” command as well as the awsdir and awsprint utilities reflect the compressed data size, not the original uncompressed size.
Sending Console Commands and Running Scripts from VSE
The VIRCMD program may be used to send one or more commands or run script requests to a Virtuent controller. This command requires special settings in the Virtuent configuration in order to function. The command is read from SYSIPT, one
70 Virtuent User’s Guide
command per line. For valid commands, see the section Virtual Tape Operator Commands. Scripts are invoked by the RUN command as follows:
RUN[WAIT[(seconds)]] nnn [optional parameters ...]
The RUN command is only honored when sent from the Host (e.g. with the VSE VIRCMD program); it cannot be entered directly at the Virtuent console, or from the Virtuent vtcmd program.
seconds is an optional number of seconds to wait for the command completion if the WAIT option is specified. This value must be specified within parenthesis. (See RUNWAIT below for more information.)
nnn is a number that identifies the script to be run. The full script name that will be invoked is /etc/bti/userscripts/scriptnnn. Leading zeros are stripped from the nnn value specified, so specifying either 007 or 7 would invoke script7.
The optional parameters will be passed as command line arguments to scriptnnn.
Scripts invoked by the RUN command will run under the Virtuent application's user ID, vtape. If a script or the program(s) invoked by it need to run under any other user ID, it is the user’s responsibility to put the necessary command(s) inside the script to make it do so.
Scripts invoked by the RUN command will not be able to read from standard input (the keyboard). stdin will be closed before starting the script process, so any program attempting to read from stdin will get an error (end of file). This doesn't prevent redirection of input to programs from within the scripts.
All output from the scripts will by default be discarded. If a script's output needs to be retained (in a file, for example), it is the user’s responsibility to put the necessary redirection command(s) inside the script to make it do so. The feedback returned to the Host from Virtuent says whether or not the Virtuent command itself (in this case, RUN) was successfully executed. This says nothing about whether the invoked script itself, or anything run in the script, successfully accomplished anything.
If the RUN command without the WAIT option is used, Virtuent will return status to the Host as soon as the RUN command is executed; the invoked script will continue to run asynchronously for however long it takes. There will be no notification to the Host when (or if) the script ends. Additional commands could be sent to Virtuent while the script is executing in the background.
If the RUNWAIT variation is used and the RUNWAIT command execution is successful, Virtuent will wait for some time for the script to complete before returning status to the Host. You can specify the optional maximum wait period in seconds. Syntax requires the wait period to be specified in parenthesis to distinguish it from the script number. If omitted, the default is 110 seconds. If the script completes within the time limit specified, Virtuent will return a successful status code to the Host. If the script does not complete within the time limit specified, Virtuent will cancel the script at the expiration of the time limit and return a failure status code to the Host.
Chapter 5. Using Virtuent with VSE/ESA 71
With the WAIT option, the drive will be "busy" executing a Load Display (x'0F') CCW throughout the wait period. If the wait for completion exceeds the Host's missing interrupt time limit, the Host application will abend because of a missing interrupt.
Example:
// JOB JCMD SEND COMMANDS TO VIRTUENT // ASSGN SYS005,421 ASSIGN TO AN AVAILABLE DEVICE ADDRESS // EXEC VIRCMD,SIZE=AUTO Q SPACE (display storage usage) UNREADY 425 (make a virtual drive not ready) UNLOAD 425 (unload a virtual drive) RUN 2 (run script #2) RUN 21 (run script 21) RUNWAIT (300) 32 p1 s2 (run script 32 with a time limit of 300 seconds and pass 2 arguments, p1 and s2) /* /&
Chapter 6. Using Virtuent with VM 73
Chapter 6. Using Virtuent with VM Virtuent tape devices can be used by VM just as any other 3480, 3490, or 3590 tape drive would be used. Bus-Tech provides two small utilities for VM / CMS. VTSCR is a scratch utility that can be used to scratch VOLSERs on the MDL that are no longer needed. VTCMD is a command utility that will send MDL commands to a Virtuent controller.
Like VSE, VM does not send any Load Display CCWs over the channel when a tape volume needs to be mounted. There are 3 methods that can be used to send mount requests to MDL:
1. Use DMSG utility for CMS. This utility, available as part of a VM download package from IBM, is specifically intended to send a LOAD DISPLAY CCW to a tape device. The CMS user simply issues the DMSG command with a tape device address and VOLSER. MDL recognizes the Load Display CCW and mounts the VOLSER on the drive.
2. Use VTCMD and send an MDL Mount command to the MDL. This is equivalent to using DMSG except that the MDL MOUNT command allows you to mount the VOLSER on a different device than the device the VTCMD uses for sending the command.
3. You can create (or modify) your own program to send a standard Load Display CCW to the MDL.
Installing VTSCR and VTCMD
To install VTSCR and VTCMD in VM you will need to upload files from the MDL Utilities CD to your mainframe. The files you will need are located in the directory /UTIL/VM and are named VTSCR.MODULE and VTCMD.MODULE. You will need to FTP them to the system in binary, and set FIX 1024 before the put of VTSCR MODULE and VTCMD MODULE as in:
ftp> bin ftp> quote site fix 1024 ftp> put vtscr.module ftp> put vtcmd.module
Once they are transferred, they must then be unpacked:
copyfile vtscr module a (unpack copyfile vtcmd module a (unpack
The modules are now ready to be executed.
74 Virtuent User’s Guide
VTSCR
The VM version of the VTSCR utility can be used to keep your tape management system scratch status in sync with the MDL scratch status.
VTSCR runs under CMS on the mainframe and sends volume scratch requests to the MDL. Since a tape management system (TMS) may dynamically release tapes back to scratch status, VTSCR should be periodically run to maintain synchronization between the TMS catalog and the MDL. To use VTSCR the user must create a TMS scratch report and then input that scratch report into VTSCR.
VTSCR scans the scratch report for MDL owned volumes and sends the appropriate scratch requests to the MDL.
VTSCR can be executed using the following syntax:
VTSCR device report_type parameters
where:
device is the attached unit address of an MDL tape drive to be used as the control device. If there are multiple tape libraries being used to contain the MDL virtual volumes, the user must select a tape device address associated with the library containing the volumes to be scratched.
report_type is:
VMTAPE – indicating VTSCR will process a VM:Tape Summary report from TMCRPT1
If you are not using VMTAPE please contact Bus-Tech Support.
parameters can include the following options:
ALLVOLS - indicating that MDL will allow scratch of volumes with data set names of all blanks. Normally, a volser with a blank DSN is considered to have never been used, and therefore does not need to be scratched.
DEBUG - will cause additional information to be logged into the VTLOG LISTING file. This option should be used when VTSCR is not working properly and the log file should be provided to Bus-Tech support along with the problem description
FREESPACE - may be used to request that the space be occupied by the VOLSERs being scratched be returned to the library as free space. The default of VTSCR is simply to reclassify volumes being scratched as eligible for scratch allocation requests, without freeing up the space occupied by that volume. FREESPACE requires the volumes to already be in scratch status. To immediately free the space VTSCR will need to be run twice. The first execution should be run without the FREESPACE parameter to scratch the
Chapter 6. Using Virtuent with VM 75
volumes and the second execution should be run with the FREESPACE parameter to release the space.
Keep in mind that MDL will automatically free the space of scratched volumes when it needs space so it is generally not necessary to run VTSCR with the FREESPACE parameter.
NODATECHK - allows volumes to be created and scratched on the same day. MDL will normally check the creation date of a tape volume and will not allow any volume to be created and scratched in the same 24 hour period.
NODSNCHK - MDL will normally validates Data Set Names if found in the scratch report as part of the scratch process. A scratch will not successfully complete if the data set name in the scratch report does not match the data set name in the HDR1 label on the volume being scratched. NODSNCHK prevents the dataset name check from being performed and is not recommended for normal use.
PREFIX - specifies a string of prefix characters that will limit processing to volumes whose volume serial numbers (VOLSER) begin with the character(s) specified. Unless otherwise specified by the PREFLEN parameter, the default prefix length is 2. ‘PREFIX AAABAC’ would cause VTSCR to process only volumes whose serial numbers begin with AA, AB, or AC. Coding this parameter prevents VTSCR from trying to unnecessarily scratch volumes that are not stored on the MDL. If no PREFIX is specified VTSCR will process the entire scratch list.
If the string of prefixes exceeds 8 characters, use parentheses to delineate the entire string of prefixes. Separate each group by 1 blank, with at most 8 characters in each group. For example, PREFIX (00010203 04050607 08)
PREFLEN - specifies a single digit between 1 and 5. This value replaces the default prefix length of 2 for the ‘PREFIX’ parameter. ’PREFIX ABCD PREFLEN 1’ will cause VTSCR to process only volumes whose serial numbers begin with A, B, C, or D.
76 Virtuent User’s Guide
For example:
VTSCR 180 VMTAPE NODSNCHK PREFIX 010203 DEBUG
VTSCR will log its activities in VTLOG LISTING A, and will expect its input scratch report in VTSCR INPUT A.
The output VTLOG LISTING A file will maintain a history of the results of each delete request. The file should be a fixed lrecl 133 file. If an error occurs during a scratch request (such as scratching a non-existent volume) the failure will be recorded in the log file, the program will continue with the next scratch request, and a non-zero return code from the program execution will result.
The VTSCR INPUT A file must point to the scratch report that the user has created using the appropriate TMS utility. The scratch report must be generated with a logical record length (LRECL) of 133.
To avoid any possibility of confusion, it is strongly recommended that a single sequence be used that generates a current scratch list file and then runs the VTSCR utility against that file. In this way there is no possibility of accidentally running the VTSCR program against an old scratch report and causing the TMS and the MDL to become out of sync.
In addition, since there is a slight time interval between the creation of the extract file and the processing of the report, the MDL will not scratch a volume that has been created today. Additionally, the utility will not execute against a scratch report that was not created the same day.
The Scratch utility will use the data set name (dsname) information from the scratch report to verify volumes being scratched. If the data set name written in the volume header does not match the data set name on the scratch report for that volume then the scratch request will be rejected.
In must be emphasized that once the VTSCR utility has completed, tapes that were successfully scratched by the utility can be re-used or erased at anytime.
Chapter 6. Using Virtuent with VM 77
VTCMD
The VTCMD program will read one or more MDL commands from the VTCMD INPUT A file and send each command to the MDL for execution.
The VTCMD INPUT A file should be a fixed lrecl 133 file, and contain a list of MDL commands to be sent.
Optionally, the user can enter commands manually rather than input them from a file. A success or failure indication will be logged to the VTLOG LISTING file. However, note that any messages and other textual results of the command that normally display on the MDL console are not returned to the host.
VTCMD can be executed using the following syntax:
VTCMD device OPER
where:
device defines the attached unit address of an MDL tape drive to be used as the control device. If there are multiple tape libraries being used, the user must select a tape device address associated with the library where the commands are to be executed.
OPER is an optional parameter that when specified will cause VTCMD to prompt the user to enter commands from the terminal rather than use the VTCMD INPUT A file. When prompted, the user can enter CMD=command_string. When all commands have been processed, enter END to terminate the program.
For example, entering:
VTCMD 180
will cause VTCMD to read commands from the VTCMD INPUT A file and send them to the tape drive attached to address 180. The results will be logged in VTLOG LISTING A.
Alternatively,
VTCMD 180 OPER
Will result in a command prompt allowing the user to enter MDL commands. VTCMD will continue to prompt until the user types END.
The output VTLOG LISTING A file will maintain a history of the results of each command. The file should be a fixed lrecl 133 file. If an error occurs during a command request (such as invalid syntax) the failure will be recorded in the log file, the program will continue with the next command, and a non-zero return code from the program execution will result. The possible error codes are as
78 Virtuent User’s Guide
follows:
0x01 Invalid data length (must be between 1 and 256 bytes)
0x02 The MDL is configured to not accept Host-initiated console commands
0xFF(-1) A general syntax error occurred. (The MDL console error message “MDL891E: Invalid command syntax” was displayed.)
0xFC (-4) An “E” level error other than general syntax error occurred. (A MDL console error message other than MDL891E was displayed.)
A sample VTLOG output might be as follows:
VTCMD VER 1.0 VTCCTRL = EA82
2004/09/10 12:47:49 CMD ERR=FF: this is an invalid command
2004/09/10 12:47:49 CMD ISSUED: q all
2004/09/10 12:47:49 CMD ERR=FC: q xxxxxxxx
2004/09/10 12:47:49 CMD ISSUED: set size=2g dev=EA80
Using VTCMD to Mount a VOLSER
VTCMD can be used to mount a specific tape volume (VOLSER) on an MDL tape drive using the MDL LOAD Command.
For example, if the contents of VTCMD INPUT A contains:
LOAD VOL=000101 DEV=cntrl0001 SL
Issuing the CMS command:
VTCMD 180
Results is the VOLSER ‘000101’ being mounted on the MDL drive named ‘cntrl0001’
To mount a new scratch volume substitute “SCRTCH” or “PRIVAT” for the VOLSER.
Alternatively, the following command sequence entered from CMS will have the same results:
VTCMD 180 OPER
CMD=LOAD VOL=000101 DEV=cntrl0001 SL
END
Chapter 7. Using Virtuent with Unisys 79
Chapter 7. Using Virtuent with Unisys Virtuent controllers with ESCON interfaces installed can connect to Unisys 2200 mainframes running OS-2200. This chapter discusses issues unique to Virtuent support of Unisys mainframes.
Unique Virtuent Operations for Unisys Mainframes
Autodetection
Virtuent automatically detects that it is attached to a Unisys host when it receives a Load Display containing data that is unique to a Unisys mainframe. When this occurs, a message is displayed on the Virtuent console (“VIR080I: Device devicename UNISYS detected”). You can confirm that Virtuent has recognized that a drive is attached to a Unisys mainframe by reviewing the messages displayed on the Virtuent console or by performing a QUERY CONFIG command (see below).
Load Displays
Unisys does not send the normal ‘M’ mount message; Virtuent determines a Unisys mount request by the FCB byte containing x’48’, and then moves the volser into the proper position for a mount message.
Mount “Ready” Interrupt
The Unisys mainframe does not expect a Not-Ready-to-Ready interrupt when the Virtuent device comes ready. After sending the Load Display, the Unisys mainframe performs repetitive Senses to detect when the device is ready. To accommodate the way the Unisys mainframe works, Virtuent does not send an interrupt when a mount is initiated by a Load Display like it normally would. However, it does send an interrupt when a manual mount is performed at the Virtuent console, and when a manual Not Ready to Ready transition is performed.
Query Config command
The Virtuent Query Config command will display an additional parameter, UNISYS=YES, for a device that has been determined to be attached to a Unisys mainframe.
Ring-Out Mount Request
The Unisys Load Display mount request uses the 8th position of the mount message as a file protect indicator. If that position contains the character ‘F’, the Unisys mainframe expects to have the tape mounted “ring-out” (read-only). Virtuent will honor the ‘F’ indicator and mount the requested volume in read-only mode.
80 Virtuent User’s Guide
Scratch Request
When a Unisys host asks for a scratch tape, MDL will ignore the label type (either explicitly requested in the mount request or implied by the LABEL=x configuration parameter) and will pick any available scratch tape. This behavior is applicable only to Unisys-attached devices. All non-Unisys devices will continue to honor label type for scratch mount requests.
Configuring for Unisys
Device Type
When configuring devices for use by a Unisys mainframe the Device Type should be set to ‘3490’.
Labels
When the Unisys operating system sends a Load Display mount message, it does not specify a label type. Unisys always expects an ANSI label by default. To accommodate this, you must configure each Unisys-attached device with the LABEL=A parameter. This will change the Virtuent default for this device to ANSI labels instead of IBM standard labels. Figure 7-1 shows a sample device definition screen where sixteen tape drives are being defined including the LABEL=A parameter.
Scratch Tapes
The Unisys operating system does not send the “MSCRTCH” message to request a scratch tape as an IBM mainframe would. Instead it sends an “L-BLNK” command. To accommodate for the L-BLNK command, you must specify a scratch synonym equal to “L-BLNK”. Figure 7-1 shows a properly configured scratch synonym for Unisys mainframes.
Initializ
Configu
zing Tape
WhenLABEwill fo
For exdrive
uring the M
VirtueCTS5.PTN
The U
s for Unisy
n initializing EL=A optionollow the AN
xample, to inE980, you w
INITIALIZ
Mainfram
ent devices a136-VSM (nfile must be
Unisys equipm
F
ys
tape volumen on the initiNSI standard
nitialize 100 would enter t
ZE VOL=B0
me for Virt
are configurenon-library)
e installed an
ment code fo
Figure 7-1. Un
es to be usedialize commad.
tapes beginnthe following
00000 DEV=
tuent
ed in OS220subsystems
nd the OS reb
for Virtuent d
Chapter 7
nisys Device P
d with Unisyand to tell th
ning with Vg initialize c
=E980 COU
00 using SCMof 1 to 16 u
booted with
devices is U
7. Using Virt
Panel
ys you must he system th
VOLSER B00command:
UNT=100 LA
MS / SCMS-units. The re
the proper d
47M.
tuent with U
include the at the tape la
0000 using t
ABEL=A
-II as 1 or mesulting ODBdefinitions.
Unisys 81
abels
tape
more B or
Chapt
VT Con
ter 8. SyOnce the mastart o
nsole
The vand is(node
A sepConfion thethe coa vt coapplic
Whenopen oapplic
OperaapplicLikewactivetape (v(Figur
ystem Opthe storage iainframe has
operating the
irtual tape aps known as “) is powered
arate prograguration proe status paneontroller’s (nonsole sessiocation.
never you clion the desktocation. Figur
ation of the vcation will ofwise, the vt ce. Once the Vvt) applicatire 8-1).
perationis attached as been confie Virtuent co
pplication ru“vt”. vt will d on and brou
am named vt ogram’s Statel for each conode’s) log inon allowing
ick the Consop and beginre 8-2 shows
vt applicationften be runn
console progrVirtuent conon at anytim
n and configuregured (and r
ontroller.
uns as a startattempt to aught up.
console cantus panel. Aontroller (nonformation.you to moni
Figure 8-1
sole icon forn displaying s a sample o
n daemon is ing even whram can be r
ntroller is runme by clickin
C
ed, the virture-initialized
ted task (daeautostart whe
n be run at anAs shown in Fode) in the M
The Consoitor and oper
1. Status Panel
r a specific cg messages frof an active v
independenhen the vt corunning withnning you cang the Conso
Chapter 8. S
ual tape devicd if necessary
emon) on theenever the M
nytime fromFigure 8-1 th
MDL; the leftole icon on thrate the Virtu
l
controller (nrom the virtuvt console w
nt of the vt coonsole prograhout the vt apan check theole icon on th
System Oper
ces are definy), you are r
e MDL contrMDL controll
m the Virtuenhere are twot icon will dihe right willuent tape-on
ode) a consoual tape (vt)
window.
onsole. Theam is not stapplication be
e status of thehe Status pan
ration 83
ned, and ready to
roller ler
nt o icons isplay l initiate n-disk
ole will
e vt arted. eing e virtual nel
884 Virtuent
User’s Guid
vt consolethey are ismessages log.
The followmessages
Ho
En
Pg
Pg
The bottocurrent stain Figure command
The follow
Up
Do
Le
Ri
Ct
De
Ct
Ba
de
e is split intossued from tin the log si
wing naviga:
ome – Move
nd – Move to
gUp – Move
gDn – Move
om or smalleatus of the v8-2, the vt a
d line where
wing naviga
p Arrow or C
own Arrow
eft Arrow – m
ight Arrow o
trl+A – mov
el or Ctrl+D
trl+E – move
ackspace or
Figu
o two sectionthe vt applicince the last
ation keys (o
e to the top
o the bottom
e up one scre
e down one s
r section of virtual tape (vapplication isyou may ent
ation keys ca
Ctrl+P – pre
or Ctrl+N –
move 1 char
or Ctrl+F – m
ve to the begi
D – delete one
e to the end
Ctrl+H – ba
ure 8-2. Activ
ns. The largation. On ststartup of vt
r commands
m
een
screen
vt console dvt) applicatis not runningter and edit v
an be used on
vious comm
next comma
racter to the
move 1 chara
inning of the
e character
of the line
ackward dele
ve vt Console
ger, top sectitartup vt cont console or
s) can be use
displays in blon on this cog. Below thvt command
n the comma
mand in histo
and in histor
left in the co
acter to the r
e command l
ete character
ion displays nsole will disthe last 100
ed to scroll th
lue and alwaontroller (no
he VT Status ds.
and line:
ory
ry
ommand line
right in the c
line
r
log messagesplay all ,000 bytes o
hrough the
ays shows thode). As sho line is a
e
command lin
es as
of the
he own
ne
Chapter 8. System Operation 85
Ctrl+K – erase to the end of the line
Ctrl+T – transpose characters
Ctrl+U – discard the line
Ctrl+W – word rubout
To close the vt Console window click the close window button in the top right corner of the screen. The console window will immediately close. Closing the console does not affect the operation of the virtual tape (vt) application in any way.
Starting / Stopping Tape Devices
To start or stop the virtual tape devices you must start or stop the virtual tape (vt) application. Control of the vt application is through the vt Console window (see Figure 8-2). The commands for starting and/or stopping tape emulation on a controller (node) are:
STARTVT to start the vt application and activate devices in the installed configuration file
STOPVT to stop the vt application. Once the application stops, the channel links are disabled and all virtual drives will cease responding to the host until the application restarts. Any I/O from the host while the application is terminated will receive an I/O error (device not operational). For this reason, you should wait for all host applications using devices to finish, and the virtual tape drives should be varied offline from the host operating system before stopping the vt application.
STOPVT will not terminate the application if any virtual drives currently have volumes loaded.
STOPVT! To terminate the application while volumes are loaded. Any virtual tapes currently loaded will be immediately unloaded without any further processing.
Note that this may result in an incomplete output tape volume if the host has not yet completed writing and properly closed the tape. For this reason, the STOPVT! command should only be used in an emergency situation where Virtuent must be brought down immediately. Any virtual tape volumes currently being written should be considered invalid.
When the vt application is active, the VT Console window will show the VT status as “Running” and informational, warning, and error messages from the vt application will scroll on the console (See Figure 8-6).
8
I
86 Virtuent
Initializing
User’s Guid
g Scratch
Before Vitape volumfirst time commandthe tape li
As explaiand may bvolumes iinto each Virtuent wclass and
If you havonly needdefined meach class
The comm
INIT
Where vo(address) numbers t
de
Volumes
irtuent can mmes that youyou start any
d in the Consibrary for Vi
ned in Chapbe sub-dividinto each andstorage clas
will not be abthe mount w
ve not defined to initializemultiple storas you have d
mand to initi
TIALIZE VODI
olser is the stof any tape to initialize,
Figure 8-3
mount a tapeu want Virtuy tape drivessole windowirtuent to use
pter 2, a Virtuded into storad every filess. If there able to satisfy
will remain p
ed storage cle a single ranage classes thdefined.
ialize tapes i
OL=volser DR=dirname
tarting serialdrive pointinn is the clas
3. VT Console
volume in tuent to use ws on Virtuen
w (Figure 8-2e.
uent library age classes. system. But are no scratcy a mount repending.
lasses (othernge of tape vhen you mus
s:
EV=devnam
l number to ing to the tapss these volu
e when vt is A
the tape librawithin that libnt you must i2) or there w
is made up o You do notyou do need
ch volumes iequest for a s
r than the defvolumes to thst initialize a
me COUNT=
initialize, depe library, coumes are to b
Active
ary you musbrary. Thereissue at least
will be no scr
of one or mot have to initd to initializen a storage cscratch withi
fault class 0)he library. Ba range of V
=count CLA
evname is thount is the nube added to,
t initialize thefore the vert one Initialiatch tapes w
ore filesystemtialize new te tape volumclass then in that storag
), then you wBut if you h
VOLSERs for
ASS=n
he device namumber of serand dirnam
he ry ze
within
ms tape
mes
ge
will ave r
me rial e is a
Chapter 8. System Operation 87
specific directory the volumes should be placed in. DIR is an optional parameter. DIR is never required. If DIR is not specified INITIALIZE will place the volumes into the first filesystem it finds within the storage class. During processing, scratch tapes will be automatically moved as needed from one directory (filesystem) to another in the same storage class. However, if you wish to spread scratch volumes across multiple filesystems within a class you may use the DIR parameter to direct a range of tapes to a specific filesystem. CLASS is a required parameter.
Assuming device E980 is a configured device pointing to your tape library then the command to initialize 500 serial numbers to the storage class 0 beginning with VOLSER 000000 would be:
INITIALIZE VOL=000000 DEV=E980 COUNT=500 CLASS=0
This would result with volumes ranging from 000000 – 000499 being created in the first filesystem in class 0.
If your library has two storage classes defined, class 1 and class 2, then the following commands would initialize 1000 volsers into the library making both classes ready for use:
INITIALIZE VOL=000000 DEV=E980 COUNT=1000 CLASS=1 INITIALIZE VOL=001000 DEV=E980 COUNT=1000 CLASS=2
Since the INITIALIZE program automatically generates VOLSERs starting with the VOLSER specified with VOL=, be careful to make sure you do not overlap VOLSER ranges when entering these commands. In the example above VOL=0000000 COUNT=1000 will result in the 1,000 tape volumes being created in the library with serial numbers ranging from 000000 to 000999. VOL=001000 COUNT=1000 will result in volumes ranging from 001000 to 001999 being created. The result of these two commands is a virtual library with 2,000 volumes whose serial numbers range from 000000 – 001999.
If you are initializing tapes on a Unisys mainframe, include the LABEL parameter telling Virtuent the tape volume labels will be ANSI format. For example,
INITIALIZE VOL=000000 DEV=E980 COUNT=500 LABEL=A CLASS=0
Be aware! On IBM mainframes if your tape devices are being defined in an MTL you will also need to define them to the mainframe’s tape configuration database (TCDB). This is accomplished by running the VTLIB utility. See page 34 for instructions on running VTLIB. For a full description of the INITIALIZE command refer to the command list in the next section.
Virtual Tape Operator Commands
When the virtual tape (vt) application is active and the VT Console window is open (See Figure 8-2), there are several virtual tape commands that can be used to control
88 Virtuent User’s Guide
the virtual tape drives on your system. Be aware that these commands will not work and will not be responded to if the vt application is not running.
Command Syntax
Virtual tape operator commands use the following syntax rules:
• UPPER CASE words are keywords and must be spelled as shown. You can enter the keywords in either upper or lower case.
• Lower case words in italics are values that you supply. These values can generally be entered in either upper or lower case. The exceptions are noted in the command description.
• Values in [square brackets] are optional.
• When multiple values are separated by an or-bar ( | ), enter only one of the choices.
• Many commands and keywords can be abbreviated. For those commands and keywords that can be abbreviated, the minimum abbreviation is underlined.
EXPORT Command
EXPORT from to [norun compress encryptkey=n|KEYn|NONE]
See page 125.
FIND Command
FIND VOLUME volser (wildcards)
The FIND Command finds a specific volume (volser) or volumes in the Virtuent library and reports the current status.
For example, ‘FIND VOLUME 000001’ will return the current status of the tape volume with the serial number 000001.
A wildcard may be used to find a range of volumes. For example, FIND VOLUME 010* will find all volumes on the library with serial numbers beginning with 010. (i.e. volumes in the range 010000 through 010999.
The maximum output from the FIND command is limited to 1,000 volumes. This maximum can be changed using the SET MAXDISPLAYCOUNT command.
HELP Command
HELP [ command | message number | ABOUT ]
The HELP command displays helpful information about the virtual tape operator commands and messages.
Chapter 8. System Operation 89
If the command HELP is entered by itself, a summary of all commands is displayed
If a command is specified, a more detailed description of that command is displayed.
If a message number is specified, an explanation of the message is displayed. For example, “HELP 489” would display information about message VIR489E. (Entering the message number as VIR489E, VIR489, or 489 all give the same result.)
A synonym for the word “HELP” is “?”, i.e. “? 489”.
HELP ABOUT displays information about the virtual tape application.
IMPORT Command
IMPORT from to [ norun compress encryptkey=n|KEYn|NONE] [CLASS=CLASSn]
See Page 126.
INITIALIZE Command INITIALIZE VOL=volser DEV=devname [COUNT=count] [CLASS=n] [DIR=dirname] [LABEL=S/A/N] [SCRATCH=Y/N] [EPIC=N/Y]
The INITIALIZE command is used to pre-initialize any number of scratch volumes into a Virtuent tape library.
If you specify a volser without a count only the one volume specified will be created.
If count is specified, volser becomes a template for creating a number of sequential volume serial numbers. volser must end with numeric digits that start with a value that is low enough and has enough digits to contain the number of volumes specified in count. For example, VOL=BT0000 COUNT=1000 would create volumes BT0000 through BT0999. Similarly, VOL=XXX100 COUNT=500 would create volumes XXX100 through XXX599. However, VOL=BTA100 COUNT=1000 would be illegal, as would VOL=ABCDE0 COUNT=11 or VOL=ABCDEF COUNT=2.
Any volume that already exists in the range will be skipped over; it will not be altered in any way.
DEV=devname tells the INITIALIZE function to use the tape library pointed to by devname to determine where to create the new scratch tapes. For example if device E980 points to library /tapelib then the following command will cause 100 scratch tapes to be created into storage class 0 in the library /tapelib:
INIT VOL=B00000 DEV=E980 COUNT=100 CLASS=0
The CLASS parameter is a required parameter that directs the new volumes being initialized to a specific storage class within the library. You must initialize scratch tapes into every new storage class before you attempt to allocate a new scratch volume from that class. If you have not specifically configured storage classes within
90 Virtuent User’s Guide
your library the default storage class is 0 and you must specify CLASS=0 on the initialize command.
The DIR parameter is always optional and allows you to direct the new volumes being initialized to a specific filesytem (directory) within the library. When not specified, new volumes will be initialized into the first filesystem within the storage class. During operation Virtuent will automatically move scratch volumes between filesystems in the same class as needed. Therefore it is not necessary to initialize tape volumes into all filesystems. You only need to make sure that each storage class has scratch tapes. If both DIR and CLASS are specified and the named directory is not in the named class the initialize will fail. If the library identified by the DEV parameter does not contain the directory identified by the DIR parameter the initialize will fail.
The LABEL parameter specifies whether the new volumes are to be created with Standard IBM (EBCDIC) labels (‘S’), ANSI (ASCII) labels (‘A’), or no labels (N). The default is Standard IBM labels. Unisys mainframes require LABEL=A.
Volumes are initialized as scratch volumes by default and are immediately available for allocation in response to a mount scratch tape request. If you want to initialize a volume and not have it default to scratch status, specify SCRATCH=NO.
EPIC=YES places an identifier on the HDR1 label that signifies that the volume is owned by BIM-EPIC tape manager; causing BIM-EPIC to accept the new volume without requiring any host operator intervention. The default is EPIC=NO.
LOAD Command LOAD [VOL=]volser [ON] [DEVICE=]devicename|* [UNLABELED | LABELED | NL | SL | AL] [PROTECTED]
The LOAD command is used to perform a manual load of a virtual tape volume.
A manual LOAD could be used, for instance, to load a volume for a host system that does not send Load Display mount messages, or in a situation where you want to mount a tape other than the one being requested by the Host.
If the devicename is specified as *, the volume will be loaded on the first available (empty) drive.
The label options apply to scratch volumes only, in order to select a scratch with a particular label type. For non-scratch volumes, any label specification is ignored.
• LABELED and SL are synonymous and specify that a volume with standard IBM (EBCDIC) labels should be selected.
• UNLABELED and NL are synonymous and specify that an unlabeled volume should be selected..
• AL specifies that a volume with standard ANSI (ASCII) labels should be selected.
Chapter 8. System Operation 91
If no label option is specified, the default is standard IBM (EBCDIC) labels.
The PROTECTED option loads the tape as read-only. Otherwise, the volume is loaded in normal read-write mode.
QUERY Command
QUERY [[DEVICE=]devicename[+] | ALL | COMPRESSION | CONFIG | ENCRYPTION | LABELS | LOCKS | MOUNTED |PATHS [ASSIGNED] | SPACE | SCRATCHNAMES | STCLASS | VERSION]
The QUERY command is used to display system information.
QUERY with no operands will display the current status of all the virtual tape drives, while DEV=devicename can be used to display a single drive or range of drives. Use a ‘*’ as a wildcard character to display a range of drives. For example, Q E98* will display all the devices E980-E98F.
QUERY ALL displays information about the virtual tape application, the channel interface card(s), and all of the virtual tape devices.
QUERY COMPRESSION shows whether or not the optional hardware data compression board is installed. Sample output from this query appears as:
VIR083I: Compression level set to 1 (0=none,1=faster,9=smaller) VIR010I: Compression hardware available VIR011I: Compression driver version: 1.0.8 VIR012I: Compression card #0: id=9 version=200 state=00000000 VIR013I: Hardware compression set ON VIR013I: Hardware decompression set ON
QUERY CONFIG shows detailed configuration information for all devices.
QUERY ENCRYPTION shows the status of the Virtuent encryption keys.
QUERY LABELS shows the header labels, if any, for all mounted tapes.
QUERY LOCKS shows any tape volumes with locks associated with them.
QUERY MOUNTED displays information only about the drives that currently have virtual tape volumes mounted.
QUERY PATHS shows all of the channel paths established for the Virtuent devices. If ASSIGNED is specified, only channel paths with current host assignment (typically those varied online) are displayed.
QUERY SPACE shows a summary of the disk space used and available in all the tape libraries.
QUERY SCRATCHNAMES displays all of the scratch volume serial number synonyms currently in effect.
92 Virtuent User’s Guide
QUERY STCLASS returns the storage class(es) defined to the library.
QUERY VERSION displays the Virtuent release number.
File-size values reported by the QUERY command reflect the compressed data size, not the original uncompressed size.
For detail information on what a QUERY command displays use the HELP command. For example:
HELP QUERY SPACE
QUIESCE Command
QUIESCE [ [DEVICE=]devicename | ALL | * ]
The QUIESCE command sets one or all of the virtual drives into the ‘quiesced’ state. Quiesced drives will not accept any further mount requests until they are unquiesced. Any mount requests issued to a quiesced drive will remain pending until the drive is unquiesced or the host cancels the mount request.
Other than not accepting any new mount requests, quiesced drives continue to function normally; any volume already loaded on the drive can continue to be accessed normally until it is unloaded.
Quiescing a drive does not send any signal to the Host.
ALL and * are synonymous and mean quiesce all drives at once.
READY Command
READY [DEVICE=]devicename
The READY command can be used to change a virtual drive from the Not Ready to the Ready state.
Entering the READY command for a virtual tape drive is equivalent to pressing the Ready button on a physical tape drive.
A virtual drive must already have a volume mounted and must be in the Not Ready (Intervention Required) state in order to make it Ready. If the specified drive does not have a volume mounted, or is already in the Ready state, the READY command is ignored.
The READY command is not needed during normal processing to make a drive Ready. Normally, a drive automatically becomes Ready whenever a volume is mounted and stays Ready until the volume is unloaded. The Not Ready condition, while a volume is mounted, is an exceptional condition that will only occur when 1) Virtuent runs out of disk space in the tape library while writing to a virtual volume; or 2) the UNREADY command was entered.
Chapter 8. System Operation 93
RESET CHANNEL ADAPTER Command
RESET CHANNEL ADAPTER n
The RESET command restarts the firmware in the specified ESCON or FICON channel adapter number ‘n’.
This command will be rejected if there are any active paths established on this adapter. Vary offline from the host all the devices / paths / channels attached to this adapter before invoking this command.
REWIND Command
REWIND [DEVICE=]devicename
The REWIND command can be used to perform a manual rewind of the specified virtual tape drive.
Entering the REWIND command for a virtual tape drive is equivalent to pressing the Rewind button on a physical tape drive. Like a physical tape drive, the specified virtual tape drive must be in the Not-Ready state in order for the REWIND command to be accepted (see the UNREADY command).
The REWIND command is executed immediately regardless of whether the tape might currently be in use by the host.
Note that the manual repositioning of the tape could result in data being read from or written to the wrong location of the virtual tape volume by the host, if the host is still processing the volume and has not yet properly closed the tape. For this reason, the REWIND command should only be used in an emergency situation when a tape volume is known to not be in use by a host application but needs to be rewound to loadpoint immediately.
SAVE TRACE Command
SAVE [TRACE]
The SAVE TRACE command is used to write all Virtuent trace buffers to disk immediately. Normally, Virtuent traces are buffered in memory and only written to disk periodically, for performance reasons. Before examining or copying the trace files, you should perform the SAVE TRACE command to make sure that all currently buffered trace data has been written to disk.
SAVE TRACE also saves channel adapter firmware trace files to disk.
94 Virtuent User’s Guide
SET Command
SET [ENCRYPTKEY=KEYn|n|NONE] [HWCOMP=ON/OFF] [HWDECOMP=ON/OFF] [IDRC=ON/OFF/FORCE] [MAXDISPLAYCOUNT=nnnn] [PATH=pathname [NOCHECK]] [RECOVER=nn] [RECOVERAMT=nn] [SIZE=xxx] [TIMESTAMPS=NO/YES] [TRACE=n] [WARNING=nn] [DEVICE=devicename|ALL|SYSTEM]
The SET command is used to set various options for the virtual tape devices. Any option set by the SET command is a temporary change, and the setting will revert to the configuration file or default value the next time the virtual tape application is started. To make permanent changes, make the changes in the Virtuent configuration file.
ENCRYPTKEY= KEYn|n|NONE sets the encryption key for the specified device to the key number (1-9) or to no key (and thus no encryption). The ENCRYPTKEY parameter requires a specific DEVICE parameter, and the specified device must not have a tape mounted for the command to be accepted. ‘n’ and ‘KEYn’ are equivalent.
HWCOMP=ON/OFF indicates whether or not Virtuent should perform hardware data compression on a given drive. By default Virtuent will use hardware data compression (HWCOMP=ON) if the compression hardware is present and the mainframe has requested IDRC. If you set HWCOMP=OFF then Virtuent will not use the compression hardware to do data compression; it will perform software compression when IDRC is requested by the mainframe.
HWDECOMP=ON/OFF indicates whether or not Virtuent should perform hardware decompression on a given device. By default Virtuent will use hardware decompression (HWDECOMP=ON) whenever the compression hardware is present and decompression is required. If HWDECOMP=OFF then Virtuent will use software decompression when decompression is required.
IDRC=ON/OFF/FORCE turns on or off write compression on a given drive. FORCE causes Virtuent to compress all data even if the Host does not specify compression on the write. Even if IDRC is set OFF, however, Virtuent will still report to the Host that it supports compression; it just will not actually perform any compression when it writes data to disk. This is because some Host operating systems or tape managers will not use a drive that does not support compression. IDRC=OFF only affects writing of data; even if IDRC is set OFF, Virtuent can read virtual tape volumes that it previously wrote with compression ON.
MAXDISPLAYCOUNT=nnnn changes the maximum number of tape volumes that will be displayed by the FIND VOLUME command. The default is 1,000.
PATH=pathname sets the path for the virtual tape library for a specific device. This option requires a specific DEVICE specification. If a tape volume is not currently loaded on the drive, the new pathname specification takes effect immediately.
Chapter 8. System Operation 95
Otherwise the change takes effect immediately after the current volume is unloaded. The pathname is case-sensitive and must exactly match the disk directory name. Always specify the tape library base directory, i.e. "/tapelib", not a subdirectory of the tape library (i.e. "/tapelib/BA"). The specified tape library and any subdirectories are checked for logical errors, such as a tape volser being in the wrong subdirectory, and if any error is found the path will not be changed. If you absolutely must set the path to a directory which won’t pass validation, you can specify the NOCHECK parameter to accept the path even if it fails validation.
SET PATH can be used to assign a virtual device to a SCSI tape drive in order to use the Direct Tape feature (See page 121). To use SET PATH in this manner specify the SCSI tape driver name. For example: “SET PATH=DRIVE-nnnnnnnnnnnn”.
RECOVER=nnn sets the percentage of disk space usage at which Virtuent starts to recover disk space by deleting the data from scratch volumes (see page 135, “Deleting ("Erasing") a Scratch Volume's Data”). Valid values are from 0 to 100. The default is 95%. If the recovery percentage is set to 100, Virtuent will never automatically delete scratch volume data to recover disk space.
RECOVERAMT=nn sets the maximum amount of space (in percentage of disk space) that Virtuent will attempt to recover once the recovery threshold is reached. The default is 1%.
SIZE=xxx sets the maximum volume size for virtual tape volumes. The valid range is 2M to 32T. A specific DEVICE can be specified, or ALL devices at the same time (the default). The size can be specified as bytes, kilobytes, megabytes, gigabytes, or terabytes (e.g. "SIZE=1500000", "SIZE=500000K", "SIZE=500M", "SIZE=1.5G", “SIZE=1T”). The new size specification takes effect immediately. If a tape is being written at the time the SIZE is changed and the position on the tape is already past the new SIZE value, logical end of volume warnings will be sent on all subsequent write/write tapemark commands, and physical end of volume will be signaled approximately 1 MB past the current position.
TIMESTAMPS=NO/YES indicates whether or not date and time should be included in each message sent to the console display. The default is NO; reducing the amount of data appearing on the console. Messages written to the log files are always timestamped. This parameter only affects messages to the console.
TRACE=n sets the trace level for a specific device if a DEVICE=devicename is specified. If SYSTEM is specified, the trace level is set for the general, non-device specific system trace. If ALL is specified, the trace level is set for all devices plus the general system trace at the same time. The default is ALL if no DEVICE is specified. Valid trace levels are 0 (no tracing) to 4 (trace a lot); the default is 1 (trace errors only).
WARNING=nnn sets the percentage of disk space usage at which Virtuent will begin to warn about usage. The valid range is 0 to 100. The default is 75%.
96 Virtuent User’s Guide
SHOW Command
SHOW CHANNEL ADAPTERS
SHOW DRIVE LIST
SHOW LOCKs
SHOW REJECTED PATHS
The SHOW command can be used to assist in debugging problems with the configuration of Virtuent or Host devices.
SHOW CHANNEL ADAPTERS displays information about all channel adapters in the Virtuent controller.
SHOW DRIVE LIST displays the fibre channel (SCSI) tape drives currently connected to the controller (node).
SHOW LOCKS displays the locks currently set on individual tape volumes. One of three types of locks may be displayed depending on the storage being used:
- Standard NFS locks that may been set by any controller (node) in the library - OCFS/2 Distributed Lock Manager locks set by this controller in a share fibre
channel environment - Virtuent file locks (DD locks) sent by Virtuent when the back-end NFS Server
does not offer the NFS Lock Manager (NLM) service.
SHOW REJECTED PATHS displays connections that the Host has attempted to establish with Virtuent, but which are not configured within Virtuent.
STOPVT Command
STOPVT[!]
This command stops the Virtuent application running on the controller (node).
This command is only valid when the console window indicates the VT Status is Running.
This command will cause all tape emulation to stop. To prevent input / output errors from occurring on the mainframe all tape devices on this controller (node) should be varied offline before issuing this command.
STOPVT will not cause emulation to stop if any tape device on the controller is active. STOPVT! will force termination of the all tape emulation regardless of the status of the tape devices. Stopping tape emulation will result in I/O errors and job termination on the mainframe when tapes are actively being used when STOPVT! is issued.
Chapter 8. System Operation 97
STARTVT Command
STARTVT
This command will start the Virtuent application on the controller (node).
This command is only valid when the console window indicates the VT Status is NOT Running.
Once the Virtuent application has initiated the VT Status will indicate Running. At this point tape devices on this controller (node) may be varied online on the mainframe.
STOP CHANNEL ADAPTER Command
STOP CHANNEL ADAPTER n
This command stops and takes out of service the specified ESCON or FICON channel adapter number ‘n’.
This command will be rejected if there are any active paths established on this adapter. Vary offline from the host all devices / paths / channels attached to this adapter before invoking this command.
To bring the channel adapter back into service, use the RESET CHANNEL ADAPTER command.
UNLOAD Command
UNLOAD [DEVICE=]devicename
The UNLOAD command can be used to perform a manual unload of the specified virtual tape drive.
Entering the UNLOAD command for a virtual tape drive is equivalent to pressing the Unload button on a physical tape drive. Like a physical tape drive, the specified virtual tape drive must be in the Not-Ready state in order for the UNLOAD command to be accepted (see the UNREADY command).
The UNLOAD command is executed immediately regardless of whether the tape might currently be in use by the host.
Note that the unloading of the tape will result in an I/O error (Intervention Required) if the host tries to read from or write to the drive after it is unloaded. For this reason, the UNLOAD command should only be used in an emergency situation when a tape volume is known to not be in use by a host application but needs to be unloaded immediately.
98 Virtuent User’s Guide
UNQUIESCE Command
UNQUIESCE [ [DEVICE=]devicename | ALL | * ]
The UNQUIESCE command takes one or all of the virtual drives out of the ‘quiesced’ state. After being unquiesced, drives will once again accept mount requests. Any pending mount request received while the drive was quiesced will be retried after the UNQUIESCE commend has completed.
Unquiescing a drive does not send any signal to the Host.
ALL and * are synonymous and mean unquiesce all drives at once.
UNREADY Command
UNREADY [DEVICE=]devicename
The UNREADY command can be used to change a virtual drive from the Ready to the Not-Ready (Intervention Required) state.
Entering the UNREADY command for a virtual tape drive is equivalent to pressing the Not Ready button on a physical tape drive.
The UNREADY command is executed immediately regardless of whether the tape might currently be in use by the host.
Note that making the drive Not-Ready will result in an I/O error (Intervention Required) if the host tries to read from or write to the drive while it is not ready. For this reason, the UNREADY command should only be used in an emergency situation when a tape volume is known to not be in use by a host application.
Reboot a Controller
You can re-initialize (reboot) a Virtuent controller (node) from the status page of Virtuent Configuration.
Warning: Be sure all tape devices emulated by the controller (node) are idle and offline on the mainframe before attempting to re-initialize (reboot) the controller. Online and active tape devices will cause I/O errors and job failure if a Virtuent controller is re-initialized.
Reboot of a controller causes the tape emulation to stop and the controller to re-initialize by re-loading its operating environment from internal disk. Reboot of a controller will take 5 to 10 minutes to complete.
To reboot a Virtuent controller go to the Status panel in Virtuent Configuration and click the Reboot button next to the controller (node) you wish to reboot (Figure 8-7).
Set Dat
Note tbutton
te and Tim
The VConsoIf youExtern
TheremanuaNetwo
To mathe Se
If youmore Nthe co
Simplyou m
that if your Mn for each no
me
Virtuent systeole. System u need to adjunal panel of
are 2 methoally set a speork Time Pro
anually set det button. T
ur Virtuent coNetwork Tim
ontroller to g
ly enter eithemake this con
Figure
MDL systemode.
em time is ddate and timust the systeVirtuent Co
Figu
ods for settinecific date anotocol (NTP
date and timeThe date and
ontroller (Mme Protocol
get date and t
er the networnfiguration a
e 8-4. Reboot
m includes m
displayed in tme are used tem date or timonfiguration
ure 8-5. Chan
ng date and tnd time or y
P) server.
e simply adjutime will be
MDL) is conn(NTP) serve
time from th
rk name or Iactive by inst
C
t Button on St
multiple node
the status linto stamp tapme you may(Figure 8-5)
nging Date an
time on a Viyou can confi
ust the date e set in all co
nected to youers are acces
he server(s).
IP address oftalling it, the
Chapter 8. S
atus Page
es there will
ne at the botte volumes b
y do so from ).
nd Time
rtuent controfigure the sys
and time shoontrollers (no
ur corporate ssible, you c
f up to four Ne controller (
System Oper
be a separat
tom of the vtbeing created
the Time ta
oller. You cstem to use a
own and thenodes) in the
network andcan easily co
NTP servers(nodes) in th
ration 99
te Reboot
t d on disk. ab on the
can a
n press system.
d one or nfigure
s. When he
100 Virtuent User’s Guide
configuration will attempt to query the servers from 1 to 4 until it successfully gets date and time.
Note that if you use a network name to identify an NTP server you will need to configure a Domain Name Server (DNS) as part of the network configuration (see the Installation Guide that accompanied your system).
Virtuent Messages
Virtuent controllers continually generate informational, warning, and error messages as they operate. These messages are written to the internal system disk storage on the MDL so that they can be retrieved as necessary during problem determination. Messages will also be automatically displayed on the vt console whenever the vt console application is connected to the controller (node).
Additionally, Virtuent is capable of sending informational, warning, and error messages to any of the following:
- An SNMP management console - One or two customer e-mail addresses - A Bus-Tech support e-mail address (phone home) - The z/OS master console via a z/OS started task.
For sending messages to SNMP and to customer e-mail addresses there are two steps that need to be completed for messages to be sent:
1. Configure Virtuent with a message destination(s). 2. Configure which messages should be sent.
For Bus-Tech support e-mail (phone home) you need to simply tell Virtuent to send vendor messages.
For z/OS messages you must install the z/OS started task and then configure which messages you want sent.
Configuring SNMP Message Notification
To send messages to an SNMP management console your MDL must be connected to the network. To configure SNMP messaging you must enter the name or IP address of the SNMP manager on the Notify tab of the External panel on Virtuent Configuration (Figure 7-20).
You may enter one or two systems where you want SNMP management messages to be sent. If either of the SNMP manager host fields contain a valid host name or IP address then Virtuent will forward messages to that host. If both fields are blank then SNMP messaging is inactive.
Sending
VirtueSMTPNotify
Mfo
Sem
Rem
Syfro
Optiondescrreceiv
Warnsent to“Confthousunlikemail s
Note: Tech “buste
ent will autoP mail servery tab of the E
Mail Server –rward the e-
ender emailessage. Thi
ecipient emessages to.
ystem nameom.
nally you miption. You
ve the e-mail
ing: Be suro your e-mafiguring Meands of infoely you woulserver.
You cannoe-mail addrech.com”.
Figu
omatically ser. To use thiExternal pa
– the IP addr-mails
– an e-mail is may or ma
ail address
e – the name
ay completeu may also ils.
re to review ail addressesessages to beormational mld want thos
ot send messesses. Virtu
ure 8-6. Conf
end messagesis capability
anel of Virtue
ress or host n
address youay not be a r
– the e-mail
of the Virtu
e a Companynclude a Sec
and understs before confe Sent”). Acmessages ovese messages
sages to Busuent will ign
C
figuring Notifi
s to one or twy you must fient Configur
name of an S
u want to be return e-mail
l address you
uent MDL co
y name, Cocond recipie
tand which mfiguring thective Virtuener a short pe to each be s
s-Tech by conore any e-m
Chapter 8. S
ications
wo e-mail adill out the foration:
SMTP mail s
included in l address.
u want Virtu
ontroller the
ntact nameent e-mail a
messages arem (Refer to nt controllereriod of timesent as an e-
oding the e-mmail address
System Oper
ddresses viallowing field
server that w
the from fie
uent to send
e-mail is be
, and Optionddress who w
re configure the section rs can genere and it is hi-mail to you
mail fields wthat include
ration 101
a an ds on the
will
eld of the
eing sent
nal will also
ed to be
rate ighly
ur SMTP
with Bus-es
102 Virtuent User’s Guide
Sending Vendor E-Mail (Phone Home)
Virtuent controllers use e-mail to provide a vendor “phone home” capabilities. Assuming your Virtuent controller is on a network and can send e-mail to an SMTP server, you can configure your controller to send pre-configured error messages to Bus-Tech support.
You cannot configure which messages get sent. You can only configure whether or not you want Virtuent to attempt to send vendor alerts (e-mails) or not.
To send phone home e-mail alerts to Bus-Tech support you must configure the following fields on the Notify tab of the External panel on Virtuent Configuration (Figure 7-20):
Mail Server – the IP address or host name of an SMTP mail server that will forward the e-mails
Mail sender name – a name to be included in the from field of the message. This may or may not be a return e-mail address.
Company name – your Company’s name.
System name – the name of the Virtuent MDL controller the e-mail is being sent from.
Contact name – a contact person’s name that Bus-Tech support can contact if necessary when responding to an alert.
To enable sending e-mail alerts to Bus-Tech support check the Notify Vendor check box.
Configuring Messages to be Sent
As previously indicated, Virtuent controllers send informational, warning, and error messages to SNMP management consoles, customer e-mail, Bus-Tech support, and the z/OS operator console. Using the Messages panel (Figure 8-7) in Virtuent Configuration you can configure which messages get sent to each destination.
As shoand erVirtueerror)represConso
All chcannois provsent to
For SNor you
For excan chtab. T
Warninformmay stime. an e-m
own, the Merror messageent messages. Also displsenting SNMole). At the
heck boxes inot modify whvided only too Bus-Tech a
NMP, Custou can configu
xample, if yoheck the toggThis will res
ing: Bus-Tmational mesend thousan
You must bmail to an e-
Fig
essages panees. Clickings in the categlayed are fou
MP, Vendor E top is a row
n the Vendohich messageo allow you and which w
omer Email, ure each me
ou want all wgle all checksult in all wa
Tech stronglyessages to yonds of informbe selective i-mail addres
gure 8-7. Mes
el has three ( on any one gory identifiur (4) check E-mail, Cust
w of “toggle a
r Email colues are sent toto see which
will not.
and Mainfrassage or eac
warning meskbox under Marning messa
y recommenour e-mail admational anin selecting wss.
C
ssage Configu
(3) tabs repreof the tabs s
ied by the tabboxes to thetomer E-maiall” check b
umn are for io Bus-Tech ah messages w
ame you canch category a
ssages to be Mainframe oages being se
nds not sendiddress(es).
nd warning mwhich messa
Chapter 8. S
uration
esenting infoshows a com
ab (informatie right of eacil, and Main
boxes.
information and which awill result in
n use the pre-as you want.
sent to your on the Warnient to the z/O
ing all warnAn active V
messages ovages are aut
System Oper
ormational, wmplete list of ion, warningch error mesframe (z/OS
purposes onare not. Thisn an e-mail b
-configured .
z/OS consoing messageOS console.
ning and Virtuent contver a short ptomatically s
ration 103
warning, f all g, or sage;
S
nly. You s column being
defaults
ole you routing
troller eriod of sent as
1
V
104 Virtuen
Viewing Me
nt User’s Gui
essage (Log)
Virtuent capplicatioare compr
From the Virtuent cicon for th8-8).
This will issued by messages
ide
) Files
controllers (non. Log filesressed to min
Virtuent Cocontroller (nhat controlle
result in a neVirtuent (Fi.
nodes) mains are automanimize the s
onfiguration ode). To vie
er (node) on
Figu
ew log windigure 8-9). Y
Figu
ntain a log ofatically rotatepace they ta
application yew a log filethe Status pa
ure 8-8. Openin
dow openingYou may scr
ure 8-9. Viewi
f all messageed each day
ake and then
you can viewe for a controanel of Virtu
ng a Log File
g; displayingroll back and
ing a Log file
es issued by at midnightkept for a p
w the currenoller simply uent Configu
g a list of recd forth throu
the virtual ta. Old log fileriod of time
nt log file on click the Louration (Figu
ent log messugh the day’s
ape les e.
a ogs ure
sages s log
User Ad
dministra
By dereadon
The adconfig
The rebut do
A useability
User aVirtue
VirtueDirectand pafirst in
WARNLDAPand yonetwoin not
As shoable towithou
You cover abox to
ation
efault Virtuennly. The def
dmin user haguration as w
eadonly useroes not have
r administray to add, dele
administratioent Configur
ent controlletory Access asswords onnstalled.
NING! Do P unless youou already h
ork. Failuret being able
own in Figuo view the cuut the Reado
can modify ean existing eo the right of
nt-based sysfault passwo
as full adminwell as monit
r can view ththe authorit
ation panel wete, or modif
on is performration (Figur
Fi
ers support twProtocol (LD
n the Virtuen
not attempt ur Virtuent chave the appe to successfto log in to
ure 8-10, theurrent configonly attribute
existing namntry. You cf the user nam
stems ship word for these
nistrator rightor and cont
he configuraty to modify
within Virtuefy user name
med from there 8-10).
igure 8-10. Us
wo types of uDAP). Nativ
nt controller a
to change thcontroller (Mpropriate dirfully attach tthe Virtuent
e Readonly aguration ande set are syst
mes, passwordan remove ame.
C
with two defa two user na
hts and can ctrol operation
ation and checonfiguratio
ent Configures recognize
e Authentica
ser Administr
user adminisve user admand is the de
the authenticMDL) is attarectory serveto an externt Configura
attribute restrd status of thtem adminis
ds, or read oa user from t
Chapter 8. S
ault user namames is “pass
create and/orn of the cont
eck the statuons or opera
ration allowsed by the sys
ation tab on t
ration
stration; natiministration st
efault type w
cation type fached to youer installed a
nal directorytion applica
ricts a user nhe controller.strators with
only attributethe system b
System Oper
mes (ids): adsword”.
r modify thetroller.
s of the contate the contro
s admin userstem.
the External
ive or Lightwtores the use
when the con
from Nativeur corporate and running
y server coulation.
name to only. User namefull access.
es by simplyy clicking D
ration 105
dmin and
e existing
troller(s) ollers.
rs the
l panel of
weight er names ntroller is
e to network
g on the ld result
y being es
y typing Delete
1
L
106 Virtuen
LDAP
nt User’s Gui
Warning!If there asystem.
To add a nof the list
When youDirectorybe maintaVirtuent cname andpassword
To configinformatio
Begin by panel in Vdisplay th
ide
! Be carefulare no admin
new user cliof users.
u configure Vy Access Protained on the controller a cd password th
is correct th
gure a Virtueon telling th
clicking theVirtuent Conhe LDAP con
l not to deletnistrator use
ck the Add
Virtuent usetocol (LDAPVirtuent concall will be mhat has beenhen access w
ent controllere controller
LDAP radionfiguration (Fnfiguration f
Figure
te all user naers you will n
next button.
er authenticatP) server usentroller. Whmade to the Ln entered intowill be given
r to use LDAhow to cont
o button on tFigure 8-10)fields (Figur
e 8-11. LDAP
ames with funot be able t
. A new entr
tion to use aer names andhen a user attLDAP serveo it. If the uto the user.
AP authentictact the LDA
the Authenti). Then clickre 8-11).
Configuration
full administto modify or
ry will appe
an external Ld passwordstempts to log
er searching ser is found
cation you mAP server.
ication tab ok any place o
n
trator priviler operate the
ar at the bot
Lightweight will no longg into the for the user and the
must provide
of the Externon the screen
eges. e
ttom
ger
nal n to
Chapter 8. System Operation 107
Two sections will be displayed, one for administrative users with full update access and one for readonly access. The fields that must be completed are:
LDAP server - the IP address or network name of the LDAP server. Virtuent will use this address / name to contact the LDAP server.
Base DN - the LDAP Distinguished Name (or DN) of the entry on the LDAP server at which to start the search for the authentication credentials. For example, “dc=bustech” or “dc=com”.
Name filter - the criteria to be used in selecting the elements to be used in authentication criteria. For example, ‘(cn=%s)’ indicates that the Common Name (cn) field should be compared against the name entered in the User field of the Virtuent log on screen.
Some LDAP servers may require bind credentials that must be specified in order to bind to the LDAP server and do LDAP authentication. If your LDAP server requires these bind credentials then you will also need to enter the following fields:
Bind DN - The distinguished name (DN) to bind to the LDAP server with.
Bind password - The password to use with the Bind DN in order to bind to the LDAP server.
When configured as shown in Figure 8-11, the LDAP server located at the network name ‘ldap.example.com’ will be searched for entries with distinguishing names ‘example’ or ‘com’. Each entry found will have its common name (cn) compared against the user name that has been entered into the logon screen. If a match is found the password will be verified and the LDAP server will provide positive acknowledgement to the Virtuent Controller; giving the user Administrative privileges. Log in will be completed. If the distinguishing name or common name is not found or if the password does not match, then authentication will fail.
If you intend to have both administrative users and readonly users you will need to complete the fields in both sections of the LDAP configuration screen.
Chapt
VTHHO
ter 9. z/OVirtuecommMDL
To mautility
Using(informare se
OST
The nVTHHfrom tcapabto use
At stacontrobe useidenticontrorange devicemessaVTHH
OS Consent based con
municate betw(see Figure
ake use of My and then co
g the Virtuenmational, want over the c
ame of the hHOST. The the operatorilities for sen
e the z/OS M
artup, VTHHollers (nodesed for commfied with a uollers. A tapof addresses
e address is rages to the z/HOST has be
sole Opentrollers proween a singl9-1).
Figure
MDL z/OS Configure the
nt Configuratarning, or erchannel to th
host utility pVTHHOST. By defaultnding MDL
MODIFY fun
HOST will res) to be supp
munication anunique namepe drive devis that will berequired on /OS consoleeen started.
eration ovide an optie logical par
e 9-1. z/OS to
onsole operaindividual M
tion programrror) messaghe mainframe
roviding z/OT utility runs t, VTHHOSTcommands.
nction in plac
ead a configuported as welnd logging. e so that comice address me used as theeach control. These dev
Host Ut
MDL Mes
MDL Com
Chapte
ional z/OS urtition’s (LP
MDL Commu
ation, you mMDL control
m you can coges and / or we (See page
OS Console Oas a started
T will use W Optionally
ce of WTOR
uration file tll as the deviEach Virtue
mmands can bmust be selece command/cller if you w
vices will not
tility
ssages
mmands
er 9. z/OS C
utility that caPAR) operato
unications
must install thller(s) to com
onfigure whiwhich specif102).
Operation sutask, and ac
Write-to-Opey, you may cR.
that defines tice addresseent controllerbe targeted tcted from eacommunicat
want Virtuentt be eligible
Console Oper
an be used toor console an
he z/OS VTHmmunicate w
ich type fic Virtuent m
upport is ccepts commerator (WTOonfigure VT
the Virtuent s, per contror (node) willto specific ach controlletion path. At to send log for allocatio
ration 109
o nd the
HHOST with it.
messages
mands R)
THHOST
oller, to l be
er’s A 2nd
on once
110 Virtuent User’s Guide
Only log messages that have passed message filtering (see page 102) will be received by the host.
It should be noted that, depending upon the filtering options set on the controllers, there may be many log messages sent to the console(s). Optionally, VTHHOST supports a configuration option to send the messages to a host file instead of the operator’s console.
Installing VTHHOST
VTHHOST is only supported in a single Logical Partition (LPAR). You cannot connect multiple VTHHOST tasks running in multiple LPARs to the same MDL controller.
VTHHOST is distributed in the VTZOS.XMI package located on the MDL utilities CD. See page 29 for information about installing the VTZOS.XMI package.
The VTHHOST utility must be linked as an authorized program into an authorized library under the name VTHHOST. It is highly recommended that RACF be used to restrict the use of VTHHOST to authorized users only.
An example of the JCL required to link VTHHOST follows:
//L EXEC PGM=HEWL,PARM='MAP,LET,LIST,NCAL,AC=1' //SYSLMOD DD DSN=USER.LIBRARY,DISP=SHR //SYSUT1 DD DSN=&&SYSUT1,SPACE=(1024,(120,120),,,ROUND), // UNIT=SYSALLDA,DCB=BUFNO=1 //SYSPRINT DD SYSOUT=* //DDIN DD DSN=BTI.MODULE,DISP=SHR //SYSLIN DD * INCLUDE DDIN(VTHHOST) NAME VTHHOST(R) /*
Running VTHHOST
The following JCL is used to execute VTHHOST:
//VTHSTEP EXEC PGM=VTHHOST,PARM=’parameters’ //VTHCFG DD DSN=PARMLIB(nodecfg),DISP=SHR //VTHLOG DD DSN=logfilename,DISP=SHR //* THE FORMAT OF THE CONFIG FILE IS AS FOLLOWS: //* Col 1 -10 Nodename //* Col 12-15 Command path device address //* Col 17-20 Log path device address //* Col 22-29 Console name
The parameters than can be specified are:
NOLOG - Prevents VTHHOST from receiving continuous log data from any controller. Set this parameter if you plan to use VTHHOST only to send commands from the z/OS Console to the Virtuent
Chapter 9. z/OS Console Operation 111
controller(s). Command responses will be returned even when NOLOG is specified.
NOWTOR - Prevents VTHHOST from issuing the normally outstanding WTOR. When this parameter is specified, MDL commands can issued using the z/OS MODIFY command as the method of communication in place of WTOR.
LOGFILE - Causes any received log data from any Virtuent controller to be recorded in the file pointed to by the VTHLOG DD card. When LOGFILE is specified, the log messages are not sent to any console via WTO. If LOGFILE is not specified, the VTHLOG DD card is not required in the JCL. The LOGFILE dataset should be an FB LRECL 133 file, and will be opened for extend each time the task is started.
VTHHOST Configuration File
The configuration file pointed to by the VTHCFG DD card should be a FB LRECL 80 file that has a single record for each Virtuent controller (node) to be supported. Up to 64 controllers can be defined.
Comments cards can be included in the input configuration file by placing an asterisk in column 1.
The layout of the configuration file records is as follows:
Col. 1 – 10 : NODENAME
The name used by the mainframe operator to identify which controller (node) to communicate with.
Col 12 – 15: CMDDEV
The 4-digit device address of the tape drive that is to be used for operator commands and responses. If this field is left blank, no operator commands can be sent to this nodename.
Col 17 – 20: LOGDEV
The 4-digit device address of the tape drive that is to be used for logging activity whenever logging is active for this node. If left blank, no host logging can occur from the node.
Col 22 - 29: CONSNAME
The console that log messages should be directed to if logging is active for this node. If this field is left blank, the log messages will go to all routcde=5 (tape library) consoles.
112 Virtuent User’s Guide
The following is sample JCL for VTHHOST within a 3 controller (node) configuration supporting both messaging and commands:
VTLNODE1 038E 038F TAPECON1 VTLNODE2 039E 039F TAPECON1 VTLNODE3 03AE 03AF TAPECON1
Using z/OS Console Support
If VTHHOST is active and configured to receive Virtuent messages it will automatically forward any message received to the appropriate console or logfile.
When VTHHOST is executed without the NOWTOR parameter the message
VTH001I ENTER COMMAND, EOJ, OR ? FOR HELP
will be issued to the z/OS console and an outstanding Write to Operator Reply (WTOR) message will remain pending.
To send a command to VTHHOST you need to know the message reply number from the WTOR. To determine the WTOR message number enter the following z/OS command on the operator’s console:
d r,l (or /d r,l from SDSF)
This command will return the reply message number for any outstanding WTORs on the system.
To issue a command to VTHHOST enter the command using the WTOR message number in the following format:
msg#,COMMAND
Where:
msg# is the reply message number returned from the d r,l command
COMMAND is the VTHHOST command to be executed.
When VTHHOST is executed with the NOWTOR parameter the message
VTH002I jobname USE MODIFY TO ENTER COMMAND, EOJ, OR ? FOR HELP
will be issued. Subsequently the z/OS Modify command can be used to issue commands to VTHHOST using the ‘jobname’ indicated in the VTH002I message.
The format of the z/OS Modify command is:
F jobname,command
where:
Chapter 9. z/OS Console Operation 113
jobname is the job name of VTHHOST reported in the VTH002I message.
command is the VTHHOST command to be executed.
VTHHOST Commands
The following commands are recognized by VTHHOST:
CMD= Sends a Virtuent command to a specific Controller (node).
This command requires a nodename also be specified by using the NODE= parameter (or N=).
A nodename of ALL can be specified to send the command to every node.
All Virtuent Operator commands (see Chapter 8) can be entered as parameters to this command.
Following are examples of valid use of this command
CMD=Q SPACE,NODE=NODE1 CMD=FIND VOLUME 000001,N=N1
STOPLOG
The STOPLOG command requests that VTHHOST stop logging controller (node) log messages for a specific controller. This command requires that a nodename be specified by using the NODE= parameter (or N=).
A nodename of ALL can be specified to stop host logging for all defined nodes.
For example:
STOPLOG,N=ALL STOPLOG,N=VTLNODE1
STARTLOG
The STARTLOG command requests that VTHHOST start host logging of node log data for a specific node. This command requires that a nodename be specified by using the NODE= parameter (or N=). A nodename of ALL can be specified to start logging for all defined nodes.
For example:
STARTLOG,N=NODE2 STARTLOG,NODE=ALL
114 Virtuent User’s Guide
STATUS
The STATUS response requests that VTHHOST display the current configuration and status of the command and logging functions.
VTHHOST will issue message:
VTH240I NODENAME CMDDEV LOGDEV CONSNAME
Followed by the status of each configured node.
A y/n next to the device address indicates if the command/logging function is currently active/inactive for that nodename.
For Example:
STATUS
VTH2401 NODENAME CMDDEV LOGDEV CONSNAME NODE1 038E Y 038F Y CON1 NODE2 048E N 048F Y
EOJ
The EOJ Command will terminate the VTHHOST task.
HELP or ?
The Help (?) command returns message VTH000I with a list of the valid VTHHOST commands:
VTH000I COMMANDS ARE:
STARTLOG,N=nodename/ALL
STOPLOG,N=nodename/ALL
C=Command,N=nodename/ALL
STATUS
WTOR Command Examples
When VTHHOST has been executed without the NOWTOR parameter, an outstanding WTOR message reply is used to send commands to VTHHOST. The following are valid examples of VTHHOST commands:
msg#,STATUS
msg#,C=Q SPACE,N=N1
msg#,STOPLOG,N=ALL
where msg# is the message number returned from the d r,l (/d r,l from SDSF).
Chapter 9. z/OS Console Operation 115
The following are valid examples of the same VTHHOST commands when VTHHOST has been executed with the NOWTOR parameter using the jobname VTHHOST:
F VTHHOST,STATUS
F VTHHOST,C=Q SPACE,N=N1
F VTHHOST,STOPLOG,N=ALL
Chapt
ter 10. UVirtue256 enencryp
Data eone orone ofbacke
If youunencseparaan applibrari
As showordsname.not thwithouencrypused taddresthis exdrives
On thdefine
Using Dent includes ncryption aspted.
encryption isr more drivef those drivend storage.
u want some crypted, you ate libraries tpropriate driies (MTLs) a
own, the cons all tape driv. This impliey are encryut encryptioption. Figurto configure sses 10 – 1Fxample). Ths.
he mainframed as MTL1.
Drives 00 – 0MTL1
Drives 10 – 1
MTL2
Data Enca data encry it is being w
s configuredes to performes, the data w
tape volumewill need toto the mainfive. Figure are defined.
Figur
ntroller is coves in the coes that all ta
ypted. But thn and the drre 10-2 showthese device
F, have been his indicates
me two MTLs. The device
0F
1F
cryptionyption modulwritten. Both
d on a drive bm data encrypwill be autom
es to be encro configure yframe allowi10-1 shows
e 10-1. Confi
onfigured witonfiguration ape volumes he drives witives with de
ws sample dees. Notice thconfigured wthat Virtuen
s are definedes 10 – 1F ar
Devices 10Encryption
Devices 00Encryption
Chapte
le allowing yh the tape he
by drive basiption. Each matically enc
rypted and oyour Virtuening you to dian example
figuring for En
th a single liare configurare written tth device ad
evice addressevice add conhat the seconwith an encrnt is to encry
d. In this exare defined as
0 – 1F n = Yes
0 – 0F n = No
er 10. Using
you to encryeader labels
is. That is, ytime a tape
crypted befo
other tape vont controller tirect individu where separ
ncryption
ibrary as a bred using theto the same l
ddresses 00 –ses 10 – 1F anfiguration pnd group of ryption key cypt any volum
ample the des MTL2.
B00000
B
B00002
B
g Data Encry
ypt data usinand the data
you can confvolume is w
ore it is writte
lumes to be to appear as ual tape volurate manual
backend. In oe same tape library whet
– 0F are confare configurpanel that codrives, with class (MFCLme written t
evices 00 – 0
0 – encrypted
B00003
2 – encrypted
B00001
yption 117
ng AES-a files are
figure written to en to the
left two
umes to tape
other library ther or figured ed with ould be
LASS in o these
0F are
1118 Virtuen
nt User’s Guiide Figuree 10-2. Add Deevices Exampple
Confivolumwill nencryp
The abseparaaccomall driyou nebeing
In ordencrypobtainobtainon youprovidinstallto con
FigureFor sicontroFor mconneMDL.gain a
Whenkey clthe keindivi
gured in thismes to be enc
ot be encryppted.
bove exampate drives ba
mplished usinives in the Meed to makewritten to.
der to encrypption procesn its keys. Ifn a license four network, de it with acclation guide nnect and con
e 10-3 showngle control
oller connectmulti-node prect to the Acc. The ACP taccess the RS
n the mainfralass (see Figey class to reidual tape vo
s manner, yocrypted or nopted. Howe
le uses systeased on whetng Bus-Tech
MDL will be sure to spec
pt a tape voluss. Virtuent f you intend or the RSA Kand connectcess to the Rthat accompnfigure your
s how differllers, such asts it to your croducts, suchcess Controlthen acts as SA Key Man
Figure 1
ame starts wrure 10-2) Vi
equest a set oolume can be
Nodes
ACP
our system Aot. If the ACver, if a volu
em managedther they ench’s UIMs or able to read
cify the appr
ume Virtuencommunicatto use data e
Key Managet your VirtueRSA Key Mapanied your Vr controller f
rent Virtuents MDL-1000company neh as MDL-60l Point (ACPan IP gatewanager.
0-3. Connect
riting a tape irtuent will mof keys. Sine encrypted w
RK
Ma
M600
Chapte
ACS routinesCS routine dume is direc
d storage (SMcrypt or not. using simpl
d a previouslyropriate esote
nt needs accetes with the encryption oer from RSAent controlleanager. PleaVirtuent confor network
t controllers 0/2000, an Eetwork for ac000/4000, thP) via the intay connectin
ting to RSA K
volume to amake a call tnce a call is mwith its own
RSA Key anager
M
MDL-00/4000
er 10. Using
s can direct idirects a tapected to MTL2
MS) and MT However, te esoterics. y encrypted eric in the JC
ess to a key tRSA Key M
on the MDL A Security, iner to the netwase refer to tntroller for inaccess.
connect to REthernet port ccess to the Rhe individualternal controng to the cor
Key Manager
a tape drive wto the RSA Kmade for eac
n unique key
MDL-1000 / 2000
g Data Encry
individual ta volume to M2, it will be
TL definitionthe same canIf esoterics tape volume
CL for a tape
to use duringManager from
you will neenstall it on a work in orderthe hardwarenformation o
RSA Key Mon the indiv
RSA Key Ml nodes (conol network wrporate netw
with an encrKey Managech new volu
y.
yption 119
ape MTL1 it
ns to n be are used,
e. But e that is
g the m RSA to ed to server r to e on how
anager. vidual
Manager. ntrollers) within the work to
ryption er using ume, each
1
C
120 Virtuen
Connectin
nt User’s Gui
The RSA encryptionvolume da(includingis never ware discar
When an recognizevolume. The RSA the clear kwill be rettape. Whdiscarded
ng to the R
In order fmust haveinstructionmodel in
AssumingRSA Keywithin Vi
In the exais using Pwith the a
ide
Key Managn key. The cata. The encg the header written to therded.
encrypted voe that the tap
It will then Key Manag
key to retrievturned to thehen the tape
d.
RSA Key M
for Virtuent te access to ans in the MDorder to con
g the controly Manager frrtuent Confi
ample shownPort number appropriate n
ger will returclear key wicryption keyrecords) bef
e tape. On ta
olume is moe has been emake a call
ger will autheve the encrye Virtuent cois unmounte
Manager
to perform da network wiDL installatinnect your M
ller has netwrom the Encriguration (Fi
Figure 10-4.
n, the RSA K38443. Younetwork addr
rn two keys till be writteny will be usedfore the dataape unload b
ounted for inencrypted anto the RSA enticate the r
yption key froontroller so ted both the c
data encryptiith access to on guide tha
MDL to the n
work access, yryption tab igure 10-4).
Connecting t
Key Manageu will need yress and por
to Virtuent; n to the tape d to encrypt
a is written toboth the encr
nput (or modnd retrieve thKey Managrequesting com its data sthat the driveclear and enc
ion, your Virthe RSA Ke
at accompanetwork.
you configuof the Exter
to RSA Key M
r is located ayour RSA adrt for your en
a clear key avolume alonthe volume
o tape. Theryption key a
dification) thehe clear key fer; passing i
controller (nostore. The ee can read (ocryption key
rtuent controey Manager.
nied your spe
ure Virtuent trnal configu
Manager
at IP addressdministrator tnvironment.
and an ng with tape ’s data e encryption and the clear
e tape drive from the tapit the clear kode) and the
encryption keor modify) thys will be
oller (MDL) Follow
ecific MDL
to access theuration panel
s 10.1.4.105to provide y
key r key
will pe key. en use ey he
e l
and you
Chapter 11. Back-End Tape Support 121
Chapter 11. Back-End Tape Support Virtuent controllers allow fibre channel attachment of an IBM 3592 or compatible tape drive. Attachment requires the optional Tape Drive Attachment kit be installed on the controller. The kit provides a single fibre channel port on the rear of the controller and software license for Virtuent physical tape functions. You must provide the IBM 3592 drive and a fibre channel cable to connect the drive to the port on the controller.
Note: Bus-Tech only supports point-to-point attachment of a single 3592 tape drive to the controller. Connection via a fibre channel switch is not supported.
Once the drive is physically attached to the controller there are 2 possible uses:
1. You can map a single Mainframe tape drive (device address) through to the physical tape drive for the purpose of writing and reading real tape cartridges from the mainframe. This capability is referred to as “Direct Tape”.
2. You can use the Virtuent-based Export / Import utilities to copy individual volumes (VOLSERs) from / to tape.
Each of these options will be discussed in this chapter.
Direct Tape
Although Virtuent controllers are primarily intended for use as tape-on-disk controllers, emulating tape drives to the mainframe and storing tape volumes on a back-end disk sub-system, Virtuent will allow mapping of an emulated 3590 tape drive to a physical IBM tape drive attached to the Virtuent controller.
To map a single mainframe device address through to a fibre channel attached IBM 3592 or TS1120 tape drive you would simply modify the Virtuent device definition to point the device to the physical drive instead of a virtual tape library on disk. For the device being mapped to the physical drive you must replace the Tape Library parameter by coding the following parameter:
DRIVE-nnnnnnnnnnnn
where nnnnnnnnnnnn is 12-digit serial number for the tape drive. If your drive serial number is less than 12 characters in length then you must pad the number to the left with zeros. For example, if your serial number is 7818330, then you would enter “DRIVE-000007818330” into the Tape Library field for the mapped drive. Figure 11-1 shows an example configuration where the 16th drive on the controller is mapped to a physical 3592 / TS1120 with serial number 7818330.
1
122 Virtuen
nt User’s Gui
Fig
The emulphysical tdefined as
Also, oncdevice frowhen a reare using address. TACS routlibrary id.representi
When a mrequests wmainframposted to the physictape and r
The tape cmainframVirtuent. have Virtucapable o
ide
gure 11-1. Ma
ated tape dritape drive. As Device Typ
e you have mom other virteal tape is wrMTLs, you Then the online determin. Otherwise ing the other
mainframe dewill work jus
me channel. Athe mainfram
cal drive becready the dri
cartridge wrme attached 3
Virtuent creuent installef reading the
apping a Devic
ive must be As shown inpe 3590.
mapped a detual devices ritten versus would want ly time a phynes a real carwhen the m
r 15 drives a
evice is mapst as they woAllocation ome operator comes readyive.
ritten will be3590 tape drieated cartrid
ed as long as e 3590 / 349
ce to a fibre ch
configured tFigure 10-1
evice in this in the mainfa virtual tapto assign a u
ysical cartridrtridge is to b
mainframe alla virtual volu
pped to a phyould if the drof the drive w
console. Th. Normally
compatibleive unless thdges can be s
those locati0E cartridge
hannel attach
to match the1, the device
fashion, youframe configpe written tounique libradge will be wbe written anlocates to th
ume will be w
ysical tape drrive were dirwill result in he request wthis will req
with 3590 che volume hasent to mainfions have reae.
hed IBM 3592
characterist being confi
u must isolatguration in oo disk. Speciary id (MTL)written is wh
and assigns the library id (written.
drive in this mrectly attach
n a mount reqwill remain oquire an oper
cartridges wras been encryframe locatioal or compat
Tape Drive
tics of the gured must b
te the mainfrorder to contrifically, if yo) to this devihen the systehe appropria(MTL)
manner mouhed to a quest being utstanding urator to moun
ritten from aypted by ons that do ntible tape dri
be
rame rol ou ice em ate
unt
until nt a
any
not ives
Compre
ssion and E
Virtuemappeinstruthan Vother
If the attachwill pdrive.
In thisdrivesbe ablmust bclear koccur
Encryption
ent supports ed to a physict the drive t
Virtuent, wilIBM drives
mainframe dhed tape driverform both
s case the ress not attachele to re-read be configurekey stored o.
mainframe iical fibre chto compress l perform ththat may lat
device confive specifies a
data compre
Figure
sulting cartrid to a Virtuethe tape cart
ed with accesn the tape ca
initiated dataannel attachthe data bef
he data compter attempt to
iguration panan encryptionession and e
e 11-2. Direct
idges writtenent controlletridge. The ss to an RSAartridge in or
Chapter
a compressiohed drive reqfore writing pression in oro read the da
nel mappingn key class (
encryption on
t Tape with En
n WILL NOer. Only a VVirtuent con
A Key Manarder to allow
r 11. Back-E
on. If a maiquests compr
it to tape. Trder to ensurata.
g a device to (see Figure 1n the data be
ncryption
OT BE COMVirtuent attac
ntroller readager that can w decryption
End Tape Su
inframe taperession VirtuThe tape drivre compatibi
a fibre chan11-2) then Vefore writing
PATIBLE wched tape driding these ca
correctly ren to successfu
upport 123
e device uent will ve, rather ility with
nnel Virtuent g to the
with tape ive will artridges esolve the fully
1
T
124 Virtuen
Tape Expo
nt User’s Gui
ort / Impo
As an altethrough toalso incluVirtuent d
These cominteractionoperator c
Because tknowledgbecause Vutilities arphysical twish to usconfigura
To enableconfigura
The next tavailable.
ide
ort Utilities
ernative to Do a physical
udes two utilidisk library a
mmands are n. If a commcan then rety
these commage or regard tVirtuent oftenre disabled itape drive tose the tape e
ation to enab
e the Virtuenation and che
time the Vir
s
Direct Tape wIBM drive cities for expoand a Virtue
executed fromand is enteype the comm
ands copy tato what datan does not hn the default a Virtuent cxport / impole them.
nt Export / Imeck the Tape
Figure 11-3
rtuent applic
where a mainconnected toorting or impnt attached t
om within thered incorrecmand correc
ape volumes a may actuallhave a tape dt Virtuent cocontroller, noort utilities y
mport utilitiee export ena
3. Enabling Ta
ation is resta
nframe tape o the Virtuen
mporting tapetape drive.
he Virtuent actly an error tly.
based only oly be contain
drive physicaonfigurationot being use
you will need
es open the aabled check (
ape Export / I
arted the exp
drive is mapnt controller e volumes be
application amessage wil
on VOLSERned on the vally attached. If you havd by Tape Dd to modify t
active Tape d(Figure 11-3
Import
port / import
pped directly(node), Virt
etween the
and have no ull be issued.
R without volume and d to it, these ve attached aDirect, and yothe Virtuent
device 3).
t utilities wil
y tuent
user The
a ou
ll be
Chapter 11. Back-End Tape Support 125
Export
The format of the tape export command is:
EXPORT from to [norun compress encryptkey=class|NONE]
where from is the full library name of the tape volume (VOLSER) to be copied and to is the name of the device driver for the tape drive the volume is to be written to.
For example:
EXPORT /tapelib/B0/B00104 DRIVE-nnnnnnnnnnnn
will copy tape volume (VOLSER) B00104 from the backend tape library to DRIVE-nnnnnnnnnnn where nnnnnnnnnnn is a 12-character serial number of the fibre channel attached tape drive.
The options for the command are:
norun – telling Virtuent not to unload the tape when the import is complete.
compress – this option indicates whether or not the tape volume should be compressed when being written to the drive. The default is to write the data without compression. If this option is included on the command, Virtuent will instruct the tape drive to compress the data before writing it to media.
If the volume is already compressed and unencrypted on the tape library, Virtuent will decompress the data before writing it to physical tape. Then, if the compress option is specified, Virtuent will tell the drive to compress the data.
If the volume is already encrypted on the tape library then the compress option has no effect on the data. Virtuent copies the encrypted volume as is to the physical tape.
encryptkey=class|NONE – this option tells Virtuent whether or not the data should be encrypted before it is written to tape. The encryption key class you specify must be defined in the RSA Key Manager. The default is encryptkey=NONE.
When the encryptkey option specifies a valid encryption key class Virtuent call the RSA Key Manager in order to get an encryption key and will then encrypt the data before sending it to the tape drive. If the compress option is also specified, Virtuent will compress the data before encrypting it and the drive will not be asked to do compression.
If the data in the disk file is already encrypted, Virtuent will copy the existing encrypted data from the disk to the tape as is. The export utility will not de-encrypt data which is already encrypted on the tape library. In this case, it is not necessary for you to specify the encryption key class on the export command.
Tape volumes written by Virtuent using the EXPORT command which are encrypted (either during the EXPORT or were already encrypted on disk) can only be processed by the Virtuent IMPORT command or Direct Tape. They cannot be processed without using a Virtuent controller.
126 Virtuent User’s Guide
Tape volumes written to an IBM 3592 drive by EXPORT which are not encrypted are compatible with other 3492 drives and can be processed by systems other than Virtuent. For example, a compressed volume written by EXPORT to an IBM 3490E drive could be mounted on a mainframe channel attached 3490E drive and read directly by a mainframe application.
Note: It is the user’s responsibility to make sure the volume does not exceed the physical capacity of the cartridge being written to. If you attempt to write a volume to tape that cannot fit on the cartridge the export will fail and invalidate the data on the tape by rewinding and writing a tapemark at the front of the tape.
Import
The format of the tape import command is:
IMPORT from to [norun compress encryptkey=n|KEYn|NONE class=n|CLASSn
where from is the device name of the tape drive to be read and to is the complete library name of the tape volume (VOLSER) being imported.
For example:
IMPORT DRIVE-nnnnnnnnnnnn /tapelib
will import the tape on drive DRIVE-nnnnnnnnnnn where nnnnnnnnnnn is a 12-character serial number of the fibre channel attached tape drive and write it to the library ‘/tapelib’.
The options on the command are:
norun – telling Virtuent not to unload the tape when the import is complete.
compress – telling Virtuent to compress the volume as it is being written to the library. Virtuent assumes that if the tape is compressed on the cartridge the drive will automatically de-compress it as it is being read from tape. If the compress option is included on the command line Virtuent will compress the data before writing it to the tape library. If this option is not specified the volume will be stored in the library uncompressed
encryptkey=class|NONE - tells Virtuent whether or not to encrypt the data as it is writing it to the library. The encryption key class you specify must be a valid key class in the RSA Key Manager. The default is encryptkey=NONE indicating Virtuent will not do encryption as it is writing the data to the library.
If the volume was previously encrypted by Virtuent then the volume is imported as is onto the tape library. The Virtuent IMPORT command does not decrypt data. Virtuent encrypted tape volumes can only be decrypted by being mounted and read from the mainframe.
CLASS=CLASSn – tells Virtuent which storage class to store the imported volume in on the library. The default, if not specified is CLASS0.
Chapt
ter 12. DAs preusing imagerecordthe vo
For cubetweVirtueflat filmainflength
Couplallowsany ne
The pData Eapplic
Data Exeviously disca specialize
e of a tape vods. Mainframolume exactl
ustomers wheen the mainent provides le support wframe minus hs.
led with Gigs Virtuent coetwork-attac
urpose of thExchange, hcations can u
TapeLibra
xchangecussed, Virtud file formatolume includme jobs readly as if it had
ho wish to usframe and ana capability
writes a flat dtape marks,
gabit Etherneontrollers to ched server (
Figur
is chapter isow to write
use it, and ho
AWS File ary
Virtuent Con
uent controlt. Using thisding tape mading a tape vd been really
se a Virtuentny other, op
y referred to data file that headers, an
et and Netwobe used to e
(Figure 12-1
re 12-1. Flat Fi
to discuss ha flat file fro
ow to read a
les
ntroller
lers normalls format alloarks, headersvolume fromy written to a
t controller ten system (Was flat file sucontains onl
nd trailers an
ork File Systexchange dat).
iles for Data E
how to confiom the mainflat file from
NS
Chapter 12
ly write tapeows Virtuents, trailers, an
m a Virtuent-ba tape.
to provide daWindows, Uupport. As tly the data w
nd without re
tem (NFS), fta between t
Exchange
gure a Virtunframe so othm the mainfr
NFS Server
2. Data Exch
volumes to t to preservend variable lebased library
ata exchangeUnix, Linux, the name im
written by theegard to reco
flat file suppthe mainfram
uent controlleher non-mainrame.
Flat Files
hange 127
disk e an exact ength y receive
e etc.),
mplies, e
ord
port me and
er for nframe
1
C
V
128 Virtuen
Configura
Virtuent Co
nt User’s Gui
ation
ontroller
Bus-Techprimary liyour libraexchange
Figure 12defined fo/dataexchname youdefine the
Once youto connecdata exchlocalhost
ide
h recommendibrary. If yoary, then you
filesystem.
2-2 shows a sor data exchah instead of /tu want as lone primary vir
F
u have definect it to the Viange. Figurin this exam
Figur
ds that you dou are usingu should crea
sample confiange. Notictapelib as th
ng as it is difrtual tape lib
Figure 12-2. D
ed the storagirtuent contrre 12-3 show
mple.
re 12-3. Conn
do not place /tapelib, for
ate a differen
figuration whe the second
he top level idfferent from brary.
Defining Stora
ge in the avaioller (node)
ws that the da
nect the Storag
your data exexample at
nt top level i
here a singled mount poindentifier. Ythe high-lev
age for Data E
ilable storagwhere you p
ata exchange
ge to the Cont
xchange voluthe top leve
identifier for
e filesystem (nt defined usYou can use vel name (/ta
Exchange
ge list (Figurplan to define storage is c
troller (Node)
umes in yourl identifier fr your data
(disk) is beinses the nameany high-lev
apelib) used
e-12-2) you ne tape driveconnected to
r for
ng e vel to
need es for o
Once the davirtua(/tapepoint exampTape L
Once in. Eexcha
Once Add dpointi
the storage iata exchangeal tape librarylib, for examthe tape librple). To doLibrary field
Figur
you have doEnter the entiange volumes
you have endevices wereing to the dat
is connectede disk (filesyy where you
mple), when rary field dir this you nee
d on the devi
re 12-4. Enter
one this the cire mount pos to (Figure
Figure 12-5
ntered the moe filled out asta exchange
d to the contrystem). Howu point the ta
you are defiectly to the med to select “ice definition
ring Free-For
configurator oint name for12-5).
5. Configuring
ount point cls shown in Fdisk as show
roller you cawever, unlikeape library toining disk fomount point“(free-form)n panel (Fig
rm Data into th
will return ar the disk wh
g Devices for D
lick add to cFigure 12-5, wn in Figure
Chapter 12
an then define defining deo the high-levor data exchat (/dataexch/D)” from the pgure 12-4).
he Tape Libra
a free-form fhere you wa
Data Exchang
create the ransixteen devi
e 12-6.
2. Data Exch
ne drives to wevices to wrivel qualifier
ange you neeDISK1, for
pull down lis
ary Field
field for youant to write d
ge
nge of deviceices will be d
hange 129
write to ite to a r ed to
st in the
u to type data
es. If the defined
1
z
V
V
130 Virtuen
z/OS, OS/39
VSE
VM
nt User’s Gui
Once thesbe placedexample, the data edevices co
90 With this mainframin this conconfigurelibrary id.qualifier t2).
VSE instaallocate spexchange
If you areallocates dfrom driv
To isolatedrive to Vsame fold
Data exch
For VM yhave beenone of the
ide
se devices ard on the data
you are usinxchange devonnected to
configuratiome. For exam
nfiguration ad for data ex. Your ACSto determine
allations whipecific tape , run VIRMO
e using a tapedrives for thes using the
e a drive for Virtuent (pagder.
hange drives
you would aln configurede drives not c
Figure
re defined anexchange di
ng MTLs in zvices in a septhe primary
on in place, ymple, if you as MTL1, allxchange wouS routines woe which MTL
ich do not usdrives with OUNT (see
e managemehe tape mana
primary tap
data exchange 28). Assig
s should not b
llocate data ed for data excconnected to
12-6. Data Ex
ny tape volumisk rather thaz/OS to defiparate MTL library.
you would dare using Ml with the sauld be configould then keyL to direct sp
se tape manatheir JCL. Spage 58) usi
ent system, sager and youpe library (/ta
nge include thgn a unique
be under the
exchange vochange. Allo the data ex
xchange Devic
me written tan the virtuaine your MDso that you
define two seMTLs, you mame library idgured as a My off of the hpecific tape v
agement softSo, if you haing that driv
such as Dynau must isolateapelib).
he GROUPgroup numb
e control of t
olumes to onl other volum
xchange libra
ces
to any of theal tape librar
DL library, ycan isolate t
eparate librarmight define t
d. The two MTL 2, with
high level davolumes to (
ftware must mave set aside ve address.
am/T or EPIe the data ex
option whenber to each d
the tape man
ne of the twomes would bary.
se devices wry. If, for ou should plthem from
ries on the the first 14 ddrives a different ataset name (MTL 1 or M
manually a drive for d
IC, then Virtxchange driv
n you define drive going to
nagement sys
o tape drives be allocated t
will
lace
drives
MTL
data
tuent ve
the o the
stem.
that to
Chapter 12. Data Exchange 131
Writing Flat Files
Virtuent determines by volume serial number whether to write the volume in AWS format or into a flat file. Any volume with a volume serial number (VOLSER) in the format “BFLxxx” will be written as a flat file with the filename “BFLxxx.FLAT”. Labeled tapes will be renamed to “BFLxxx.datasetname.FLAT” using the data set name from the HDR1 label when the mainframe writes the HDR1 label. Keep in mind, however, that no header information is written into the flat file. Once the file is closed, all header and trailer information is lost.
Actual file data is written to the output file sequentially without any retention of record lengths and without any data conversion. Data received in EBCDIC format will be written to disk in EBCDIC format. Data received in ASCII will be written in ASCII. It is the user’s responsibility to provide for data conversion either before writing the data to the Virtuent controller or when reading the file from an open server. In z/OS or OS/390 EBCDIC to ASCII conversion can be requested from the operating system by coding OPTCD=Q on the DD for the tape volume.
Only a single data file may be written to the tape volume. Flat file data exchange does not allow multiple files to be written onto one tape volume.
Reading Flat Files
To input a file to the mainframe from an open system you simply have to place the file in a directory connected to a Virtuent tape drive and name the file “BFLxxx.FLAT” where xxx may be any 3 characters allowed in a tape volume serial number (VOLSER).
Existing flat files are always presented to the mainframe as unlabeled tapes.
Virtuent will always return the exact amount of data requested by each read command unless there is not enough data left in the file. Programs reading in a flat file from Virtuent must read fixed length records of the correct length. Many mainframe utilities are unsuitable for use with Virtuent flat files because they specify a maximum read size of 64k –1 and then wait for the read operation to return the actual record length. Virtuent will return 64k – 1 bytes of data in response to such a read unless end of file is reached.
z/OS and OS/390
To read a flat file code BFLxxx as the volume serial number of an unlabeled tape and Virtuent will use the serial number to mount the file BFLxxx.FLAT. When using MTLs your ACS rountine should recognized a VOLSER that begins with “BFL” as an attempt to read a flat file and allocate to the appropriate MTL (library id) where flat files are located. Following is a sample DD statement to read a flat file:
VOL=SER=BFL001,LABEL=(,NL),DISP=OLD
132 Virtuent User’s Guide
VSE
Assuming your Virtuent controller has a separate data exchange directory assigned to a specific tape drive (see Configuration section earlier in this chapter), you need to run VIRMOUNT in order to mount the flat file for processing. For example:
// OPTION PARTDUMP * LIBDEF POINTS TO THE VSE LIBRARY WHERE VIRMOUNT IS CATALOGED // LIBDEF PHASE,SEARCH=USERLIB.PROD * ***************************************************************** * THIS PROGRAM CAUSES A VIRTUAL TAPE VOLUME TO BE MOUNTED. * * YOU MUST ASSIGN SYS004 TO A VIRTUENT DEVICE ADDRESS. * * THE PARMS ARE ENCLOSED IN SINGLE QUOTES AND SEPERATED BY COMMAS * * 1. 6 CHAR TAPE NAME(VOLSER) OR SCRTCH * * 2. N FOR UNLABELED OR S FOR STANDARD LABELED * * ***************************************************************** // ASSGN SYS004,A087 ASSIGN TO A VIRTUENT DEVICE ADDRESS // EXEC VIRMOUNT,SIZE=AUTO,PARM='BFL001,N'
This JCL mounts the flat file named “BFL001.FLAT” on tape drive A087. A subsequent job step can now read the unlabeled tape mounted on A087 in order to complete the data exchange.
.
Appendix A. Volume Handling 133
Appendix A. Volume Handling
Volume Serial Numbers
Virtuent supports only volume serial numbers (VOLSERs) that conform to the IBM standard VOLSER naming convention. IBM standard VOLSERs contain 1 to 6 alphanumeric EBCDIC characters; uppercase A through Z, 0 through 9, and the hyphen. Volume serial numbers are left justified and padded with spaces on the right.
The disk filename of a virtual tape volume is initially derived from the VOLSER requested by the Host in the Load Display Mount message. A simple one to six-character disk filename that matches the requested VOLSER, converted from EBCDIC to ASCII, will be used to hold the virtual tape volume.
Following the analogy of physical tape volumes, the virtual volume's disk filename is equivalent to a physical tape's external label. Just as it is important for a physical tape's external label to always match the VOLSER recorded on the tape so that the tape can be identified, stored, and retrieved, it is vital that a virtual volume's disk filename match the VOLSER recorded in the volume for the same reasons.
As long as the host does not write a different VOLSER to the virtual volume, the disk filename and the VOLSER recorded in the volume will remain the same. Under some circumstances, the host may write a new VOL1 label containing a VOLSER different from the one originally associated with the mounted volume. This usually happens only when the host uses a program such as Ditto to perform a physical tape copy that copies the original volume's labels as well as its data to the new tape. In order to maintain the association between a virtual volume's disk filename and the actual VOLSER recorded in the volume, whenever the host writes a VOL1 label Virtuent checks the VOLSER being written to see if it differs from the original VOLSER under which the volume was mounted. If the new VOLSER is different, Virtuent attempts to rename the volume's disk filename to match the new VOLSER in the VOL1 label being written. If the new disk filename, i.e. new VOLSER, already exists, Virtuent will not rename the mounted volume and it will not allow the new VOL1 label to be written; it will return an error (Unit Check status with Command Reject sense) to the host's write command. In addition, if the new VOLSER begins with a different VOLSER prefix (first two characters) than the mounted volume, the new VOL1 label write will be rejected. This is to prevent a volume from residing in a tape library subdirectory that does not match the VOLSER prefix.
If the host changes a labeled volume to an unlabeled volume by writing over the standard labels with data, Virtuent accepts the change but does not change the volume's filename.
134 Virtuent User’s Guide
Scratching Volumes
Virtual volumes in a tape library exist in one of three states:
• Active – An “active” volume is any volume that is not currently a scratch tape. A scratch volume becomes active whenever it is mounted in response to a request from the Host (or by a manual mount), whether by explicit VOLSER or to fulfill a SCRTCH tape request. Once a volume is active it is no longer a scratch tape, so it can be mounted again only by explicitly requesting it by specific volume serial number, not by a SCRTCH request. An active volume can be recognized by the fact that its file name is exactly the same as its VOLSER. Once a volume is active, it will remain active in the virtual tape library until it is explicitly scratched.
• Scratched – Volumes created by Virtuent INITIALIZE command are initially in the “scratched” state, available to be mounted in response to a SCRTCH tape request. A scratch volume can be recognized by the fact that its file name is preceded by a “~”, for example ~BT0040. When the host requests a scratch volume, Virtuent will select the oldest scratch volume from the tape library directory that has the most free space, but only after any "erased" scratch volumes (see below) have been used. A scratch volume can also be mounted by explicitly requesting it by volume serial number. In either case, whenever a scratch volume is mounted, it is moved back to active status by renaming the file from ~VOLSER back to VOLSER (without the ~) and is no longer a scratch tape. However, if the scratch volume is never accessed by the host before it is unmounted, it is changed back to scratch status when unmounted Volumes can be moved from the “active” to the "scratched" state by a scratch utility running on the host. The Virtuent Utility CD includes scratch utilities for both z/OS-OS/390 (see page 37) and VSE (see 0). These utilities process a host-generated scratch report and send scratch volume requests over the channel to Virtuent. When Virtuent receives a request to scratch an active volume, the disk file for that volume is renamed from VOLSER to ~VOLSER, where VOLSER is the volume serial number. For example, scratching B00004 would rename the file to ~B00004. All of the data in the scratched volume is retained at this time, although it may be deleted later if Virtuent needs the disk space.
• Erased - An "erased" volume is a scratch volume which has had its data deleted to recover disk space. Scratched tapes retain their data for as long as possible until Virtuent needs to reclaim disk space to write new data. When Virtuent starts running out of disk space, it will select the oldest scratched volume from the tape library and delete its data. When a scratch tape is "erased", all of the data in the volume past the standard header labels is deleted. Only the VOL1 and HDR labels are retained (these are retained because some host tape management systems
Appendix A. Volume Handling 135
verify the labels and previous data set name (DSN) on a tape before allowing a previously scratched tape to be re-used). The disk file remains named ~VOLSER. Note that once a Virtuent scratch volume has been erased, the data cannot be recovered unless a backup copy of the volume had been made previously. Virtuent will select an “erased” scratch tape in response to a scratch tape request from the host, before selecting an unerased scratch tape. As with any scratch tape, whenever an erased scratch volume is mounted, it is moved back to active status by renaming the file from ~VOLSER back to VOLSER (without the ~).
Deleting ("Erasing") a Scratch Volume's Data
When a virtual volume is scratched, the data in the volume remains intact for some period of time. This is to give you a chance to "unscratch" a tape that was accidentally scratched. Eventually, as the Virtuent disk fills up, space must be recovered from scratched tapes in order to write new data. When the usage in any tape library directory reaches 95%, Virtuent will begin to recover disk space from scratch volumes in that library. The oldest scratch volumes will be moved to "erased" status, which will delete their data. Virtuent will continue to erase scratched volumes until the disk usage drops below 95%.
If the RECOVERY percentage is set to 100% (see SET command, page 94), Virtuent will never automatically erase data from scratch volumes to recover disk space.
Virtuent will never move an active volume to scratch status automatically, nor will it ever erase data from an active volume.
Mounting Volumes
Mounting A Specific Volume by VOLSER
Requested VOLSER Exists
When the host requests a specific VOLSER, Virtuent first checks to see if the requested VOLSER exists as an active volume in the tape library. If the specified VOLSER is found, the file is opened and positioned to the beginning of the volume (load point). The virtual tape drive presents a Not-Ready-to-Ready interrupt to the host and enters the "Ready" state, ready for I/O from the host.
If the volume is a scratch volume it is changed back to active status by renaming the file VOLSER (without the ~).
If the volume is a scratch volume that has already had its data deleted (it is in the "erased" state), the volume is still mounted as requested. However, if the host attempts to read past the standard labels into the non-existent data, it will receive an I/O error (Unit Check status, Tape Void sense).
136 Virtuent User’s Guide
Requested VOLSER Does Not Already Exist
If the host requests a VOLSER that does not already exist as either an active or scratched volume in the tape library assigned to this device, the mount request is simply ignored, and the virtual tape drive remains in the "Not Ready" state. Just like with a physical tape library, you should pre-initialize all the volumes that might ever be requested by the host (see INITIALIZE command, page 89).
Write-Protected Volumes
If a tape volume’s disk file can only be opened in Read-Only mode (for example, it resides on a read-only medium, in a directory with read-only access, or the file itself is read-only), the Write Protect bit will be set on the virtual tape drive while this volume is mounted. The volume can then only be read, not written, in this situation. Any attempt to write (Write, Write Tapemark, or Erase) to the volume, will result in a Unit Check error being presented to the host.
Mounting a "SCRTCH" or "PRIVAT" Volume
Unlabeled Scratch Request
If the host requests an unlabeled "SCRTCH" or "PRIVAT" volume (determined by an 'N' in the 8th position of the mount message), Virtuent will display an appropriate error message, the mount request is ignored, and the virtual tape drive remains in the "Not Ready" state. This is because an unlabeled scratch tape cannot be subsequently tracked or retrieved since there is no permanent VOLSER associated with the volume.
Labeled Scratch Request
If the host requests a scratch volume using "SCRTCH", "PRIVAT", or a configured scratch pool (Scratch synonym) volume with standard labels (anything other than 'N' in the 8th position of the Load Display Mount message), Virtuent will check the appropriate tape synonym definitions that may exist in order to identify which storage class in the tape library will receive the new tape. Virtuent will search the storage class to identify an eligible scratch volume. Once an eligible tape has been identified, Virtuent will ready the device and then wait for the mainframe to start writing. On first write from the mainframe Virtuent will randomly allocate the volume to a any filesystem within the storage class that has enough space to hold the cartridge being allocated (based on the configured SIZE= parameter). A new VOLSER file will be created. The old scratch volume file (~VOLSER) will be deleted; effectively moving the tape volume from the filesystem where ~VOLSER was located to the filesystem where the new volume (VOLSER) has been created.
If no scratched, erased volume is found within the storage class to fulfill the mount request, an appropriate message is displayed on the Virtuent console, the mount request is ignored, and the virtual tape drive remains in the "Not Ready" state. Just like with a physical tape library, you should pre-initialize enough scratch volumes to fulfill scratch tape requests from the host (see INITIALIZE command, page 89), and
Appendix A. Volume Handling 137
move “active” volumes back to scratch status in sync with the Host (see z/OS-OS/390 scratch utilities, page 37, and VSE scratch utilities in 0).
However, for backwards compatibility with previous releases, Virtuent can be configured to automatically create a tape volume when the Host requests a scratch volume and none is available. If the VOL=prefix parameter is configured, a new scratch tape volume will be automatically created in the tape library. Virtuent will pick the first available (non-existing) VOLSER that starts with the prefix configured for this device. As an example, if the drive is configured with a volume serial number prefix of VOL=BT, Virtuent will attempt to allocate a new volume starting at BT0000, then BT0001, BT0002, etc., until it finds an unused volume serial number. If the library contains a directory matching the prefix, the new tape is created in that directory. For example, the volume BA1001 would be placed in the disk mounted at /tapelib/BA. If a /tapelib/BA directory does not exist, the file would be created in /tapelib. Before coming ready to the host, the new virtual tape volume will be initialized as a standard labeled tape, with a dummy VOL1 label containing the new VOLSER, a dummy (empty) HDR1 label, and two tapemarks. These labels conform to those produced by the MVS IEHINITT tape initialization utility. Note that since there is no data following the standard labels, any attempt to read past the labels will result in an I/O error (Unit Check status with Data Check and Tape Void sense).
Once a volume has been allocated for the mount request, the file is opened and positioned to the beginning of the volume (load point). The virtual tape drive presents a Not-Ready-to-Ready interrupt to the host and enters the "Ready" state, ready for I/O from the host.
When a host-initiated mount request fails for any of the following reasons, the mount request will be retried until it succeeds or until the host sends a new Load Display message that cancels the request:
Volume not found Volume in use elsewhere No scratch available Drive is quiesced
End of Volume Conditions
Logical End of Volume
Virtuent will signal to the host that a virtual tape has reached logical end of volume when:
• The disk file corresponding to the virtual tape volume approaches the maximum volume size specified by the user for this virtual tape device. This maximum volume size is configurable by the user (see SIZE parameter on page 28) from 2-megabytes to 2-terabytes, and defaults to 2-gigabytes if not specified. The configured maximum volume size can also be temporarily overridden with the operator’s SET SIZE command.
138 Virtuent User’s Guide
• The number of blocks written to a volume approaches the number supported by a 3480/3490 tape drive, which is approximately 4 million blocks.
In order to leave room for any remaining data, tapemarks, and labels that the host may need to write at end of volume, logical end of volume is actually signaled approximately 1-megabyte prior to the absolute volume limit.
Virtuent signals the logical end of volume in the same way as a physical tape drive. When the logical end of volume point has been reached, Virtuent returns unit exception status to all write, write tapemark, and erase gap commands. The host is expected to close this volume and open a new volume.
Physical End of Volume
If the host attempts to read or write past the absolute capacity of a virtual tape volume (as defined above), the operation will fail with a unit check. Sense will return Equipment Check and an Error Recovery Procedure Action (ERPA) code of 38 - Physical End of Tape.
End of Data
If the host attempts to read or forward space past the end of the last data written to the virtual tape volume, the operation will fail with a unit check. Sense will return Data Check and an Error Recovery Procedure Action (ERPA) code of 31 - Tape Void.
Error Conditions
Mount Loops
A mount loop occurs when the host requests that a volume be mounted, Virtuent mounts the volume, and then the host immediately unloads the volume and requests the same volume again. This usually happens because the host is dissatisfied with the contents of the volume, especially if the labels on the volume are not what it expects to find. If unchecked, this mount/unmount cycle could continue indefinitely.
Virtuent will detect that a mount loop is occurring when:
• The host requests a volume to be mounted;
• After the volume is mounted, the host reads no more than the first three records from the volume and never writes to the volume;
• The host unloads the volume and requests the same volume again.
If this cycle repeats four times within 30 seconds Virtuent will not honor the next mount request for the same volume, and the virtual drive will remain in the Not Ready state. This gives the host operator the opportunity to correct the problem that is causing the mount loop.
Appendix A. Volume Handling 139
Out of Disk
If a filesystem becomes full while Virtuent is writing a tape volume to it, Virtuent will put the affected virtual tape drive into the Not Ready (Intervention Required) state. Though Not Ready, the virtual tape volume will remain mounted at the current position, and the transfer can continue as soon as there is space available on the disk.
When you have cleared the out of disk condition by deleting unneeded volumes from the tape library, you can continue the interrupted transfer by entering the Virtuent "Ready" command. The virtual drive will become Ready and the transfer will resume.
When the volume resides on an NFS file system, an out of disk conditionis an unrecoverable condition. A unit check error will be returned to the host’s write command.
Appendix B. AWSTAPE Information 141
Appendix B. AWSTAPE Information
Virtuent stores virtual tape volumes on disk in the AWSTAPE format.
Each AWSTAPE disk file emulates one physical tape volume.
Each emulated physical record in the emulated tape volume is represented by one or more pairings of a Block Header followed by data. An emulated tapemark is represented by a Block Header only.
The structure of the AWSTAPE block header is as follows:
/*-------------------------------------------------------------------*/ /* Structure definition for AWSTAPE block header */ /*-------------------------------------------------------------------*/ typedef struct _AWSTAPE_BLKHDR { U16 curblkl; /* Length of this block */ U16 prvblkl; /* Length of previous block */ BYTE flags1; /* Flags byte 1 */ BYTE flags2; /* Flags byte 2 */ } AWSTAPE_BLKHDR; /* Definitions for AWSTAPE_BLKHDR flags byte 1 */ #define AWSTAPE_FLAG1_NEWREC 0x80 /* Start of new record */ #define AWSTAPE_FLAG1_TAPEMARK 0x40 /* Tape mark */ #define AWSTAPE_FLAG1_ENDREC 0x20 /* End of record */ /* SEGMENTED is a Bus-Tech extension: */ #define AWSTAPE_FLAG1_SEGMENTED 0x10 /* Segmented record */ /* Definitions for AWSTAPE_BLKHDR flags byte 2 */ /* ZCMPRS and HWCMPRS are Bus-Tech extensions: */ #define AWSTAPE_FLAG2_ZCMPRS 0x80 /* Compressed with zlib */ #define AWSTAPE_FLAG2_HWCMPRS 0x40 /* Compressed with hardware */
A U16 is a 16-bit unsigned value. Values in a U16 are in Intel (low-byte, hi-byte) format.
A BYTE is an unsigned 8-bit value.
The current and previous block lengths define the length of data in the AWS block, and do not include the length of the block header itself. The maximum AWS data block size is FFFF hex (65535 decimal) bytes.
The first block in an AWSTAPE file has a previous block length (prvblkl) of zero.
A tapemark has a current block length (curblkl) of zero, and the TAPEMARK bit is set in flags1. A tapemark never has ENDREC or NEWREC bits set in flags1.
The NEWREC bit in flags1 signifies the start of a logical tape block and the ENDREC bit in flags1 signifies the end of a logical tape block. When NEWREC and ENDREC are both set, it signifies that the emulated tape block is completely contained in one AWS data block. When an emulated tape block spans more than one
142 Virtuent User’s Guide
AWS data block, NEWREC is set in the first of a chain of AWS data blocks, and ENDREC is set in the last. In this way, emulated tape blocks exceeding 64K-1 bytes can be stored in the AWSTAPE file as a chain of AWS data blocks. If the tape block spans more than two AWS data blocks, the AWS data blocks in the middle will have neither NEWREC nor ENDREC set.
In addition to setting the NEWREC and ENDREC bits appropriately for a tape block that spans multiple AWS data blocks, Virtuent also sets the SEGMENTED bit in the first block header of the chain.
Data in an AWSTAPE file is stored in the format that the mainframe sent it. Normally, mainframe data is in EBCDIC format. But if the mainframe application writes the data in ASCII, then the AWSTAPE file will contain ASCII data.
Appendix C. Load Display Command – CCW Opcode x’9F’ 143
Appendix C. Load Display Command – CCW Opcode x’9F’ IBM-compatible 3480/3490/3590 tape drives support a "Load Display" command that is used to display messages on the tape drive's LED display. These messages are typically sent by the mainframe operating system or tape management system to request that a specific volume be mounted by the operator.
Virtuent relies on these Load Display messages to determine when virtual tape volumes should be mounted on its virtual tape drives. When it sees a Load Display message that it interprets as a mount request of a specific volume serial number (VOLSER), the volume's disk file is opened and the drive “comes ready” to the host – that is, it acts like a tape has been mounted. If Virtuent determines the Load Display is requesting a scratch volume then Virtuent will identify a suitable VOLSER, opens the volume’s disk file and the drive “comes ready” to the host. For a complete description of how Virtuent determines a scratch is being requested please refer to the paragraph titled “Scratch Synonyms” on page 28. Virtuent ignores any Load Display messages not determined to be a mount message.
Since the Load Display messages are intended to be "human readable", they can conceivably vary from mainframe system to system. Virtuent requires a specific Load Display message format in order to determine that the host is requesting a volume mount. Specifically, Virtuent has been designed to recognize the Load Display mount messages issued by z/OS-OS/390.
The format of the mount messages recognized by Virtuent follows. Refer to the tables below for more detailed information about the Load Display messages format.
Format Control Byte (FCB):
Virtuent recognizes Function Select (bits 0-2) values of 000, 010, and 111 as potential mount messages.
Messages 0 and 1:
If the FCB Alternating Message bit (bit 3) is on, first message 0 is checked for a mount message, then message 1.
If the FCB Alternating Message bit (bit 3) is off, the FCB Display Low/High Message bit (bit 5) is checked to determine whether message 0 or 1 is to be checked for a mount message. If bit 5 is on, only message 0 is checked for a mount message. If bit 5 is off, only message 1 is checked for a mount message.
Virtuent recognizes a mount request by the EBCDIC character 'M' in the first position (byte 0) of the message. The EBCDIC volume serial number is located in bytes 1-6 of the message. The last character (byte 7) of the message is a label indicator. If byte 7 is EBCDIC ‘A’ an ANSI (ASCII) labeled volume is being requested. If byte 7 is EBCDIC 'N', an unlabeled volume is being requested; otherwise a standard labeled tape is presumed.
144 Virtuent User’s Guide
If the Load Display message does not pass all the tests to determine a mount request, the message is simply ignored.
Load Display Data
0 Format Control Byte
1-8 Message 0
9-16 Message 1
Format Control Byte (FCB)
Bits Value Description
0-2 Function Select
000 The message specified in bytes 1-8 and 9-16 is maintained until the tape drive next starts tape motion, or until the message is updated.
001 The message specified in bytes 1-8 is maintained until the tape cartridge is physically removed from the tape drive, or until the next unload/load cycle.
010 The message specified in bytes 1-8 is maintained until the drive is next loaded.
011 This value is used to physically access a drive without changing the message display. This option can be used to test whether a control unit can physically communicate with a drive.
100 to 110
Reserved.
111 The message specified in bytes 1-8 and 9-16 is displayed. The message in bytes 1-8 is displayed until a tape cartridge is physically removed from the tape drive, or until the drive is next loaded. The message in bytes 9-16 is displayed until the drive is next loaded (not including the loading of the cleaning cartridge). If no cartridge is present in the drive, the first message is ignored and only the second message is displayed until the drive is next loaded (not including the loading of the cleaning cartridge).
Appendix C. Load Display Command – CCW Opcode x’9F’ 145
3 Alternate Messages
0 The tape drive displays only the message that is specified in bit 5.
1 The tape drive displays both messages specified in bytes 1-8 and 9-16, respectively, alternating them on the message display. The sequence repeats until the message is replaced on the display. When bit 3 is set to 1, bits 4 and 5 are ignored.
4 Blink Message
0 The message specified by setting bit 5 does not blink.
1 The message specified by setting bit 5 blinks repeatedly. When bit 3 is set to 1, bit 4 is ignored.
5 Display Low/High Message
0 The message specified in bytes 1-8 is displayed. This bit is ignored if bit 3 is set to 1.
1 The message specified in bytes 9-16 is displayed. This bit is ignored if bit 3 is set to 1.
6 0 Reserved
7 0 Index Automatic Load (Reserved)
146 Virtuent User’s Guide
The following are some sample Load Display messages. The hex values are in EBCDIC:
48D4C2E3 F0F0F0F1 E2000000 00000000 00
Interpretation:
Display message 0 (bytes 1-8) “MBT0001S”, blink, and retain until loaded. In other words, “Mount volume BT0001”. Volume BT0001 is expected to be a standard labeled volume.
Virtuent would interpret this as a valid mount request for standard labeled volume BT0001.
28D9C2E3 F4F44040 40000000 00000000 00
Interpretation:
Display message 0 (bytes 1-8) “RBT44 ”, blink it, and retain until the tape is removed from the drive. In other words, “Remove volume BT44.
Virtuent would ignore this message since it is not a mount request.
F0D9C2E3 F0F0F2F2 40D4C2E3 F2F7F2F7 E2
Interpretation:
Display in an alternating fashion message 0 (bytes 1-8) "RBT0022 " and message 1 (bytes 9-16) "MBT2727S". Stop displaying (or never display) message 0 when the tape is removed from the drive. Stop displaying (or never display) message 1 when the tape drive is next loaded. In other words, “Remove volume BT0022, then Mount volume BT2727.
Virtuent would interpret this as a valid mount request for standard labeled volume BT2727.
Help and Service Information 147
Help and Service Information If you have questions about your new Bus-Tech product, or require technical assistance, visit the Bus-Tech Web site at http:\\www.bustech.com. You can also get help and information through the Bus-Tech’s Technical Support line, Monday through Friday, 8:30 am – 5:00pm Eastern time. Response time may vary depending on the number and nature of the calls received.
Step 1: Problem Solving
You may be able to solve the problem yourself. Before calling Technical Support, please prepare for the call by following these steps:
1. If you are having installation or configuration problems, refer to the detailed installation and configuration sections found in this manual and review any README.TXT files found on the installation disk(s).
2. Visit the Technical Support section of the Bus-Tech Web site specific to the product you have purchased. Updated installation instructions, hints, and tips, software, or updated system-specific notes are often published in this section.
Step 2: Preparing for the Call
To assist the technical support representative, have available as much of the following information as possible:
1. Product Name.
2. Product Release number.
3. Product Serial Number.
4. Exact wording of the error message (if any).
5. Description of the problem.
6. Hardware and software configuration information for your system.
If possible, be at your computer. Your technical support representative might want to walk you through the problem during the call.
148 Virtuent User’s Guide
Step 3: Placing the Call
If you call after your warranty or maintenance contract has expired, you might be charged a fee.
Support 8:30am – 5:00pm, Monday-Friday
U.S.A. / Puerto Rico 1-800-284-3172
From Outside the U.S.A. 1-781-272-8200
Additional Technical Support Resources
Online technical support is available through the Internet during the life of your product.
Online Technical Support
Bus-Tech Web Site www.bustech.com
Index 149
Index 3480/3490/3590, 1, 32, 33, 45, 138, 143 3490/3590 MTL, 33 3590/3490E
SCSI, 121 Active configuration, 29 Active Directory, 105 admin, 105 ALLOWVSEUTILITIES, 55 AWSTAPE, 1, 141 BIM-EPIC, 19, 57, 58, 64, 65, 66, 67, 69, 90 BTIMOUNT, 58 BTITAPE, 60, 65 CA-EPIC, 66 CCWs, 2, 143 commands, 87
EXPORT, 88 HELP, 88 IMPORT, 89 INITIALIZE, 89 LOAD, 90 MOUNT, 90 NOCHECK, 95 QUERY, 91 QUIESCE, 92 READY, 92 REWIND, 93 SAVE TRACE, 93 SET, 94 SET IDRC, 94 SET PATH, 94 SET RECOVER, 95 SET SIZE, 95 SET TRACE, 95 SET WARNING, 95 SHOW, 96 UNLOAD, 97 UNQUIESCE, 98 UNREADY, 98
configuration control unit, 22 displaying, 91 general parameters, 26 IDRC, 23 LABELS, 24 maximum device address, 22
tapelib path, 22 virtual devices, 19
Data Compression, 45, 69, 94 Data Exchange, 127 Date
NTP Server, 99 device
trace, 24 DFSMShsm, 44 Direct Tape, 121
Compression, 123 Encryption, 123
Disk Subsystem, 7 Dynam/T, 55, 56, 57, 58, 59, 60, 61, 62, 63,
64, 69, 130 Encryption, 117
key, 23 Encryptkey, 94 end of volume
logical, 95 physical, 95
Export, 121, 125 Encryption, 125
FCB, 144 flat files
inputting, 131 outputting, 131
GROUP, 23, 56, 58, 69, 130 help command, 88 IDRC, 94 Import, 121, 126 initializing scratch tapes, 86, 89 Installation, 3 LDAP, 105, 106 Lightweight Directory Access Protocol, 105 lock directory, 7, 11, 16 Log Files, 104 logical end of volume, 95 Manual Tape Library, 33 Max Tapes Report, 53 missing interrupt handler (MIH), 45 mount loop, 138 MVS, 31 NOWTOR, 111, 112, 115 OS/390, 31, 130, 131
150 Virtuent User’s Guide
OS-2200, 79 OSADDR, 24, 56 physical end of volume, 95 PRIVAT, 136 quiesce, 92 readonly, 105 ready state, 92, 98 recover amount, 20 recover percent, 19, 95 rejected paths, 96 RESET CHANNEL ADAPTER, 93 RMM, 41 Scratch Pool, 62 scratch synonyms, 91 scratch tape, 89
initializing, 89 scratch volumes, 37 Scratch Volumes, 86 SCRTCH, 136 Slow Mounts Report, 53 Still in Use Report, 54 STOP CHANNEL ADAPTER, 97 SYNCTIME, 51 System Operation, 83 tape labels
ANSI, 90 IBM, 90 unlabeled, 90
Tape Library Adding a New Subdirectory, 11 Initializing Scratch Tapes, 86 Overview, 7 Query Space, 91
tape size, 95 Throughput Report, 52 Time
NTP Server, 99 TLMS, 42 TMS, 41 traces, 93, 95 UIM, 32, 35 Unisys
Autodetection, 79 Initializing Tapes, 81 Labels, 80
Mount Ready Interrupt, 79 Query Config, 79 Ring-Out, 79 Scratch Tapes, 80
unlabeled tapes, 90 unloading a tape, 97 unquiesce, 98 User Administration, 105 Utilities, 31
Export, 124, 125 Import, 124, 126 VTCMD, 42 VTLIB, 34 VTSCR, 37
VIRCMD, 57, 69, 70, 71 VIRDTERA, 56, 57, 64 VIRDTEXT, 57, 61, 62 VIRDTSCR, 56, 57, 63 VIREPERA, 56, 57, 68, 69 VIREPSCR, 56, 57, 68 VIRLDSPL, 56, 60, 65 VIRMAINT, 56, 57, 59 VIRMOUNT, 23, 24, 56, 57, 58, 130, 132 VIRSSD, 56, 57, 58, 59, 60, 61, 62, 63, 69 VIRSSE, 56, 57, 58, 63, 65, 66, 69 Virtual Devices, 19
Configuring, 19 VM
DMSG, 73 Mount Tape, 73
VM Support, 73 volser, 133, 136 volume size, 24, 95 VSE, 55, 130, 132 VTCMD, 42, 77 VTLIB, 34 VTSCR, 37, 74
Parameters, 74 Report Type, 74 VMTAPE, 74
VTSLOG, 40 warning percent, 19, 95 write protect, 91 WTOR, 109, 112, 114 z/OS, 31, 130, 131
Customer Response If you have comments or suggestions regarding our products and documentation, please send them to:
BUS-TECH, INC. 26 Crosby Drive, Suite 100
Bedford, MA. 01730 ATTENTION: CUSTOMER SUPPORT
Or, call us at: (781) 272-8200 FAX: (781) 272-0342. Or, visit our Web Site at: www.bustech.com
Virtuent User’s Guide Part Number 40-03377-E0-001 October 2010