Virtuent User Guide Rel 7

User Guid rs de
Part Number 40-03377-E P r E0-001
26 Crosby Driv Suite 100 ve, 0
Bedford, MA 01730 B A
(781)272-8200 7
Bus-Tech Virtuent Users Guide Part Number 40-03377-E0-001 October 2010 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.
Copyright
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 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 Table of Contents i Manual Tape Libraries .................................33 MTL-Related IBM maintenance ..................35 Bus-Techs 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
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 ii Virtuent Users Guide
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
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 x9F......................................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
Table of Contents iii
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. BusTechs 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 Users 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.
About This Publication v
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.
vi Virtuent Users Guide
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.
About This Publication vii
Chapt 1. In ter ntroduct tion

Bus-T Techs Mainf frame Data Library is a f L family of tap pe-on-disk c controllers fo IBM or or IBM M-compatibl mainfram and for U le mes Unisys OS22 200. All MD models ar built DL re using a common tape-on-disk software pa t k ackage know as Virtuen The Virt wn nt. tuent softwa runs on a base hardw controll which pro are ware ler ovides one o two FICO or ON conne ections or on two, or th ESCON connections to the main ne, hree N nframe. Dep pending on mo odel, Virtuen controllers can emulat 32 to two hundred fift six (256) 3 nt s te ty 3480, 3490, or 3590 tape drives. Da written to or read fro these tape drives by t ata o om e the mainf frame is store and retrie ed eved from a d subsyst attached to the contr disk tem d roller (See Figure 1-1). F
VOLSER 1
Tape Volume es on Disk k

VOLSER n
Figu 1-1. MDL Controller / N ure Node Stores T Tape Volumes on Disk
The ta data is st ape tored in disk files that co k orrespond to physical vo o olumes of tap with pe, a sing file holdin the data for one tape volume. Th files are id gle ng f he dentified and d correl lated to a vol lume by the tape Volum Serial Num me mber (VOLS SER), which is h acquir from the Load Display command sent from t host whe red e d the enever it wan a nts tape volume to be mounted fo reading or writing. v e or r The default file fo d ormat for vir rtual tape dat written to Virtuent con ta ntrollers is w written in a mod dified AWST TAPE forma This form keeps tra of record lengths as t file is at. mat ack d the being written so th variable length recor can be re exactly a they were hat rds ead as origin nally written. . Option nally, data can also be written as a p c w plain, sequen ntial (flat) file. In this format, the or riginal data record length labels, an tapemarks are lost, bu any open-s r hs, nd s ut system applic cation can re the data as a sequenti dataset. ead a ial Virtue starts a virtual tape ta on the co ent v ask ontroller for each active virtual tape drive. These virtual tape tasks run co e e ontinuously and, in conjunction with the channe h el interfa aces firmwa emulate 3xxx-type t are, tape drives in every way possible, by n y y:
Chapte 1. Introdu er uction 1
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.
2 Virtuent Users Guide
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,
Chapter 1. Introduction 3
you can create and use your own configuratio files. Virt on tuent will allow you to s store as many configuration files as you want. How c n u wever, only one configu uration file w will be the act configur tive ration at any point in tim y me. To select a configurat tion file to work with go to the Conf w o figurations panel on Virtuent Configuratio (Figure 1C on -2).
Figure 1-2. Configu e uration Panel ls
By defaul the configu lt uration file used will be config. T create you own u To ur configura ation file type in a name in the config e guration na amed field an click New nd w (Figure 1-3).
Figure 1-3. Creating a N Configur New ration
You will now be editi the new configuratio file. The Virtuent Co n ing on onfiguration applicatio will displa the config on ay guration file name in the heading are (Figure 1e ea -4).
4 Virtuent Users Guide U e
Figure 1-4. Editing a New Configu 1 uration File
Refer to subseque chapters in this manu for inform ent i ual mation about the various t s config guration opti ions. Once you have fin y nished creatin your new configurati you ng w ion must save the cha s anges and ins stall it before it will be u e used by the V Virtuent cont troller. After making you changes re ur eturn to the C Configuratio panel. T Save ch ons The hanges button should now be active; indicating th configura n w i he ation has bee modified ( en (Figure 1-5). Click the Sa changes button to sa your con ave ave nfiguration.
Fig gure 1-5. Savi a Configu ing uration
uration will not automat tically install it. Even if you have m f modified Saving the configu the ac ctive (last ins stalled) conf figuration, th new chang will not take place u he ges until the Instal button is clicked. ll c To ins stall the selected configu uration click the Install b k button. An Apply log w window will open showing the status and results o installing y g a of your configu uration. WAR RNING! In multiple no configu rations all n ode nodes must be powered on and d runni when th install but ing he tton is click ked.
Chapte 1. Introdu er uction 5
WARNIN NG! Clickin Install while a Virtu ng w uent Contro oller is activ with devi ve, ices online, will cause the controller (or control w e llers) to tem mporarily go down. On o nline Mainfram devices are likely to be boxed. It is strong recomm me a o gly mended that all devices em mulated by the entire MDL are va M aried offline prior to in e nstalling a new configura ation file. Once a co onfiguration has been ins stalled the C Configuration panel with display a L n Last Installati ion field showing the na of the c ame configuration file that wa installed l n as last (Figure 1-6). The las configurat st tion file insta alled is the a active config guration bein ng used by th system. he
Figure 1-6. Showing Inst talled Configu uration
6 Virtuent Users Guide U e
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 opensystems 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 controllers 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.
Chapter 2. Defining the Virtual Tape Library 7
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.
/tapelib /DISK1 /DISK2 /DISK3 /DISK4
Each Logical Disk represents a single NFS Export or a single Fibre Channel LUN
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 8 Virtuent Users Guide
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.
/tapelib /DISK1 /DISK2 /DISK3 /DISK4
Storage Class 0
Storage Class 1
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
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. 10 Virtuent Users Guide
Only one lock file o esystem is re equired regar rdless of how many virtu tape libra w ual aries you may be defining to the Virtuen controller b o nt r(s). The lo filesytem is only use during the process of allocating a new scratch volume ock m ed e h for ou utput. Therefore, the size of the lock filesystem (directory) c be very s e k can small. A equired. 10 MB filesystem is generally all that is re B m y Defining a Virtual Tape Librar g T ry There are four steps required to successfu define a Virtuent tap library usi NFS t ully pe ing or fibr channel st re torage and begin using it The steps are: b t. s 1. Define the filesystems (disks). e s 2. Define the library or li e ibraries to be used by ea MDL node (controlle e ach er). 3. Identify th lock directory to Virtu he uent. 4. Initialize scratch tapes (VOLSERs into the lib s s s) brary. Steps 1 - 3 will be discussed in this chapte Step 4, in e er. nitializing ta apes, must be done once Virtuent is ru V unning in at least one co ontroller (nod de). Tape in nitialization i is discus ssed in detail in Chapter 8 beginning on page 86 g 6.
Definin Filesyst ng tems

As a minimum, yo will need to define on small (10 MByte) file m ou d ne esystem for V Virtuent to use as a lock di e irectory and at least one filesystem f each virtu tape libra you for ual ary intend to define. As previously discussed Bus-Tech r d A d, recommends defining m more than one filesystem to each library in order to m maximize pe erformance. To define a new filesystem to Virtuent ac cess the Virt f tuent config guration pane using els the we browser on your PC / laptop. On connecte click on S eb o nce ed, Storage to d display the St torage panel (Figure 2-3) ).
Figure 2-3. S Storage Definit tion
The Storage panel has two or more tabs; d S l depending on the MDL m n model and th he number of nodes (controllers) within the c ( ) configuration For singl controllers there n. le s
Chap 2. Defin the Virt Tape Li pter ning tual ibrary 11
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
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
filesys stem read-on you must make sure to use scratc synonyms (see page 2 nly ch 26) to dire new tape volumes to filesystems not configu ect e ured as read-o only. Filesy ystem this field allows you to selec the type o filesystem to be used o s ct of on this st torage (disk) For fibre channel stor ). rage on a sin Virtuent controller ngle t where the library is not shared Bus-Tech recommend selecting e e d, ds ext3. For M MDL Shared SAN Stora configur age rations you m select O must OCFS/2. Figure 2-4 shows an example adding an N filesyste to the sto e NFS em orage config guration. As shown, the new filesys tem will be mounted at t mount point s the /tape elib/DISK1 implying th filesystem is part of th virtual tap library his m he pe identified by /tap pelib. The actual storag is located on the NFS server at IP a ge d S P addres 192.168.1 ss 1.20. The ex xport name b being used to export the storage on th o he NFS server is dis s sk1. This filesystem is defaulting t storage cla 0, which f to ass h means it is genera storage not assigned to a specific c s al o class.
Figure 2-4. Adding an NFS Filesyst n tem
Figure 2-5 shows an example of adding a fibr channel L 5 e a re LUN using th OCFS/2 he filesystem m.
Figure 2-5. Adding a Fibr Channel Fil A re lesystem
You may add any num mber of files systems to th available storage by c he clicking the A Add on. next butto
14 Virtuent Users Guid de
Definin the Libr ng rary to be Used by a Node

Becau some Ma use ainframe Dat Library m ta models includ multiple, independent de tly operat ting nodes, the second st of storag configurat t tep ge tion is to def which v fine virtual tape li ibraries are to be used by devices on each Virtue controlle t y n ent er. On the storage pan select th tab for the controller y wish to configure. F e nel, he e you For single MDL contr e rollers there will only be one tab; lab e beled localh host in the s sample config guration panels in this us sers guide. For MDL m models with more than o node one (contr roller) there will be mult w tiple tabs wit each tab i th indicating th name of th node he he it defi ines. Once you have selected a nod (controller to configu a list of a storage av de r) ure all vailable to the node will be displayed. If nothing is displayed then you h e d, have yet to d define storag on the av ge vailable tab. Follow ins structions in the previou section of the n us manua to define storage to Virtuent. al s Simpl click the check boxes for the stora you wan this node t use. Figur 2-6 ly c age nt to re shows a sample co s onfiguration where a sin n ngle virtual t tape library ( (tapelib) has been define with 4 file ed esystems alo with the lock filesyst ong tem. You must always connect the lock fileyste to all nod m em des. Additi ionally, if a n node is access sing a library then it sho y, ould always access all di isks in that library. As s shown, all fou filesystem have been selected for use by the MDL contro ur ms n r oller. If mul ltiple librarie are define then you may configu different nodes to co es ed, ure t onnect to differe libraries. ent .
re ng Figur 2-6. Definin Storage to the Node
If you are defining multiple libraries and w u g want the con ntroller to ha some tap drives ave pe conne ected to one library and other tape dr l o rives to be co onnected to a second library, be sure to include bo librarys storage in th node (con o oth he ntroller) conf figuration. Warning: If you are defining a library a g across more than one no / control be ode ller t es ers all . ntroller sure that all node / controlle include a the same filesystems. If one con includ 4 filesyst des tems and an nother only h the first 3, then the second cont has t troller
will be un nable to acce tape volu ess umes (VOLS SERs) writte by the firs controller into en rst r the fourth filesystem. h . Repeat the storage sel lection proce for each node (contro ess oller) in you configurat ur tion.
D Defining th Lock Directory he D

The final step to conf figuring a Vi irtuent librar storage is to tell Virtu which ry uent filesystem (disk) to us as the lock directory. This filesys m se stem will no be used to store ot tape volum mes. Theref fore, the filesystem can b small in s be size. 10 MB Bytes of stora age should be plenty rega e ardless of how big a libra you are d w ary defining. The same lock directo MUST be defined to each node a e ory b o accessing a v virtual tape library. The same loc directory can be used for more tha one virtua tape librar T ck an al ry. The lock directory is identified to Virtuent wi a global p o ith parameter ca alled VOLSER RLOCKDIR. This param meter is defin as an add ned ditional para ameter under the r Global op ptions on the node Devic panel (Fi e ces igure 2-7).
Figure 2-7. Global Option on the Devic Panel G ns ce
To define the lock dir e rectory click on the hype k erlink click to add freek -form paramete ers. Then enter the lock directory p e k parameter int the free-fo area on the to orm screen. Th format of the lock dir he f rectory param meter is: VOLS SERLOCKD /lockdir/ DIR /diskname Where /l lockdir/diskn name is the mount poin you previo e nt ously defined for the lock d directory on the Avail lable storage panel (see Defining F e Filesystems earlier in th his chapter).
1 Virtuent Users Guid 16 de
Figure 2-8 shows an example where the lo directory has been d e ock y defined as th he filesys stem located at mount po /lockdi d oint ir/lock.
Fig gure 2-8. Free e-Form Param meters
Backwa Comp ard patibility

Customers installi a Virtuen 7 (or high based co ing nt her) ontroller into an existing multiple o g contro oller environ nment with an earlier ver a rsion of softw can operate their new ware contro oller in comp patibility mo ode. To op perate in com mpatibility mode using an existing vi m n irtual library you simply do not y, y define a lock direc e ctory filesys stem in the c onfiguration When the n. e VOLS SERLOCKD paramete has not be defined on a controller (node), th DIR er een he contro oller (node) will assume that the virt tape libr w tual rary is an exi isting library created y with Virtuent soft V tware older than release 7.0. t Keep in mind that if the Virtu controlle (node) is r t uent er running in b backward compa atibility mod then the restrictions o the previou library ar de of us rchitecture ar all in re force. Specifically, each files system must be defined ( (mounted) in the library using n the fir 2 characte of the VO rst ers OLSERs tha will be sto at ored in that fi filesystem. Filesy ystems are ge enerally rest tricted to 10, ,000 VOLSE per files ERs system and n new filesys stems added to the librar must have VOLSERs initialized i d ry e s into them be efore they can be used. e If you are defining a new MD virtual tap library Bu u g DL pe us-Tech stro ongly recomm mends that yo define a lock director filesystem as describe in this ma ou l ry m ed anual in orde to take er full ad dvantage of the Virtuent 7 enhanced filesystem a t d architecture. .
If you must run in compatibility mode because of existing controllers, please refer to the Virtuent Users Guide, part number 40-03208-xx-001 for documentation on the earlier generation library architecture.
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.
Chapter 3. Configuring Virtual Devices 19
Recov amount (1-100) When Virtuen starts to au ver W nt automatically recover dis y sk space it will continue erasing data from sc cratch volum until this amount of free mes s space has been rec covered or until there ar e no more sc u cratch volum that can be mes d. ues efault is 1%. Setting rec . covery amou unt erased Valid valu are 1 to 100. The de to 100 will cause Virtuent to erase the dat from all sc 0 V e ta cratch volum on this mes filesys stem once th start space recovery v he e value has bee reached. en
Figure 3- Device Con -1. nfiguration Pa anel
Tape export enab bled indica whether or not this controller is to provide ates r s export / import uti t ilities. Virt tuent control llers allow ph hysical attac chment of an n IBM 3592 or TS1120 tape dri 3 ive. When a real IBM dr is attach to the drive hed Virtue controlle export / im ent er, mport utilitie are availab on the co es able ontroller tha will at copy (export) a ta volume (VOLSER) f ( ape from the libr rary to a phy ysical 3592 / TS112 cartridge or copy (im 20 mport) a phys sical 3592 / T TS1120 cartr ridge to a tap pe volum (VOLSER in the Vir me R) rtuent library These util y. lities are exe ecuted on the e contro oller and are outside of any mainfram security p a me programs (R RACF, ACF/ /2, etc). By default these utilities are disable Checkin this config t ed. ng guration check kbox will ena the Export / Import utilities. able Write compatibil the wr compatib e lity rite bility field in ndicates whe ether or not t this contro oller needs backward com b mpatibility w previou generation Virtuent with us n contro ollers. By de efault, Virtuent is config gured so that it will write data that is t e s s backw ward compat tible with pre evious versio of Virtu ons uent. This de efault insures that a new Virtuent co w ontroller can be installed into an exis sting library and share ta ape volum with olde Virtuent controllers. Specifically volumes w mes er c y, written by thi is contro oller can be read by othe older Virt r er, tuent based c controllers. For new install lations, wher no existin Virtuent c re ng controllers ex this opt xist, tion can be s to set Allow new featu w ures but lose backward compatibil e d lity. This w allow th will he 20 Virtuent Users Guid de
co ontroller to ta full adva ake antage of all features of the current g l generation V Virtuent co ontroller. Ad dditional pa arameters In addition to the pre-d defined globa configurat al tion pa arameters described abov there are g ve global free-f form configu uration param meters that can be ma anually enter into the c red configuratio To add a free-form p on. parameter cli on click to add free-f ick -form param meters. Curr free-form parameter rent m rs include: VOLSER RLOCKDIR /mountpoin defines the location of the lock R nt filesystem to be used by the contro m b oller. The m mount point m have be must een previously defined to Virtuent on t Availabl tab of the storage pane (see y V the le el page 11) as well as bei selected on the node storage pan a ing e nel. See pa 16 for a full descript age tion on defin ning a lock d directory for each of you virtual ur librari ies. Adding Devices D Below the global options section of the de w evices panel are two sect tions; the Co ontrol units section and the Scratch synonyms se s t s ection. The Control unit section is where ts you be egin the proc of defin cess ning virtual t tape devices (drives) to b emulated to the s be d mainf frame by this node / cont s troller. The fi step to defining devices is to add one or mor controllers to the irst d re s config guration. As shown in Figure 3-2, a new control unit is adde by enterin a s F l ed ng valid control unit number and selecting a device type for the devices to be def c d fined on the co ontroller. Fo ESCON va control unit values a 00-0F. F FICON v or alid are For valid contro unit values are 00-FF. Click the button to complete th add. ol + o he
Figure 3-2. Add ding a Contro Unit ol
Chapter 3. Configuring Virtual De g evices 21
The contr unit will be added to the list. Onc at least on control un has been rol b ce ne ntil n defined th Add devic configuration section will displa (Figure 3he ces n ay -3).
Figure 3-3. Add devi ices Paramete ers
The param meters you can configure for each de c e evice are: Contr Unit - Th control un from the list above th you wish to configure rol he nit hat h device on. es Add address ran The sta a nge arting and en nding hexade ecimal devic unit addre ce esses you wish to add to the control w o ller. Initia device nam - A uniqu device na must be created for each Virtuen al me ue ame nt device Bus-Tech recommend using the same device name as de e. h ds e efined on the e mainf frame operat ting system. The name y enter will be the init device in the you tial n range of devices being created and will be incremente for each s b d e ed subsequent device For exam e. mple, if you are defining 16 devices w an address range of 00 a with f 0F and you enter E900 in this field, the co d E onfigurator w name the 16 devices will s E900, E901, E902 ... E90F. The name yo enter may be from 1 t 8 characte , 2, T ou y to ers long. I e s onnected to. To appear i in Tape Library Identifies the library this device is co the lis of availabl libraries, storage must be defined on the Available tab of the st le s t Storag panel (see page 14) an be conne cted to the n ge e nd node on the n node tab of t the Storag panel (see page 15). ge e
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.
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)
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).
Fig gure 3-4. Curr rent devices
Note: If you are conf y figuring the tape device into a Ma e es anual Tape L Library (MT TL) on the ma ainframe be aware that MTLs only allow 16 de e evices per co ontroller. So o rather tha defining 32 devices on a single c an o control unit, you would want to defi , fine two contr units with 16 devices each. rol h s
S Scratch Sy ynonyms
When the mainframe wants a tape volume (V e e VOLSER) mo ounted on a tape device a load displ command is sent ove the channe to the dev identifyi the VOL lay er el vice ing LSER to be mou unted. For ex xample, in z/OS if a use codes JCL for a tape v z er L volume that r reads VOL=SE ER=000001 then z/OS will send a load display command t the tape , y to device ind dicating the tape volume with VOLS e SER 00000 needs to be mounted on 01 the drive. After sendi the load display, z/O waits for the device to become ready ing OS o and then reads the VO label to verify the se r OL1 erial number r. z/OS uses the default character str s rings SCRT TCH and P PRIVAT to indicate a o request fo a scratch tape to be mo or t ounted for o output. By d default Virtue controlle ent ers recognize these 2 cha e aracter string as a reques for a new scratch tape rather than a gs st e, n request to mount an existing VOL o e LSER. Whe Virtuent r en receives a lo display oad command containing either SCRT d TCH or PRIV VAT instead of a volum serial num d me mber, the contro oller will loc an availa scratch tape in the v cate able virtual tape l library and mount it on the requested device to be used fo output. o t or Most com mmercial tape manageme systems ( e ent (TMS) support the concept of tape p pools; allowing the customer to define th own scr t r heir ratch pools fo use when mounting a new for n scratch ta ape. Customer using tape pools with their TMS w have def rs e t will fined their ow special wn character strings that the compute operators a er and/or tape l library must recognize a a t as or t s l tapes. In sup pport of TM MS request fo a scratch tape from a specific pool of scratch t tape pools Virtuent allows the cu s, a ustomer to de efine their ow unique wn scratch synonyms to the Vir s rtuent contro oller. The sy ynonyms, alo with SC ong CRTCH and 2 Virtuent Users Guid 26 de
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.
Figure 3- Defining S cratch Synony -5. yms
Figure 3-5 show a sam scratch synonym co 5 mple h onfiguration n. In this exa ample any mount reques with the synonym W m sted e WORK will b assigned any be available scratch tape in the defau storage cl 0. e ult lass A request for SCRTC will also go to defaul storage (class 0), but w only be t CH lt will assigned a volume wi a serial nu ith umber begin nning with 00 or 01. If n scratch ta no apes with these prefixes ar available the mount w not be sat e re t will tisfied and w remain will pending. PRIVAT tapes will go to storage assigned to storage class 1. Any av o vailable scrat tch tape withi that class will be used If there a no availab scratch t in d. are ble tapes in class 1, s the mount will remain pending. t n Syntax is important when coding scratch syno w onyms. For example, de efining: RTAPE=(00 0,01),CLASS S=(CLASS1 1,CLASS2) DR defines tw synonyms, DRTAPE and CLASS DRTAPE will use vo wo S. E olume serial numbers beginning with 00 or 01 in Class 0 s b w storage. CLA will use only volum ASS e me serial num mbers CLAS and CLA SS1 ASS2. Whereas defining: d DR RTAPE=((0 00,01),CLAS SS=(CLASS 1,CLASS2)) ) correctly establishes the single scratch synony DRTAPE using VOL t ym E LSERs beginning with 00 or 01 located in either stora class 1 o storage class 2. g n age or Finally, keep in mind that it is not necessary t define any scratch syn k t to y nonyms at al ll. By defaul Virtuent will allocate any request for SCRTCH or PRIVA to any scr lt, w AT ratch tape avail lable on the default (clas 0) storage class. d ss
Saving your Con g nfiguration n

Once you have de efined the co onfiguration the way you want it, you need to sav it. On u u ve the Co onfiguration panel click Save Chan n k nges to save your config e guration to d disk (Figur 3-6). re
Figure 3-6. Saving Chang ges
Activat ting (Insta alling) a Co onfigurati ion

In ord for any co der onfiguration to be used b the Virtu controlle n by uent er(s) in must be t install led. Even when you mo w odify the curr rently install configur led ration the cha anges will not become active until you re-install the configu a y l uration. To i install (and a activate) your configuration click the In c n nstall button on the Con n nfiguration panel (Figur 3-6). re WAR RNING! Wh you clic the Instal button the Virtuent c hen ck ll e controller(s) will be ) restar rted. Any emulated, on e nline tape d drive will go offline and may be box by d xed the mainframe operating sys m stem. If you controlle is current online w the ur er tly with mainf frame you should idle all tape driv and vary them offli prior to s a ves y ine instal lling a new configuratio (i.e. befo re clicking t Install b c on the button). Be aw ware that if your system has multip controlle (nodes) every contr y m ple ers roller detect ting a chang to its cur ge rrent configu uration will automatically restart. l . Howe ever, if you are adding a new control (node) to an existing system you can a ller o g u install the configu l uration while the existing nodes are a e g active as lon as you tak care ng ke not to modify any of the existing controlle (nodes) c y ers configuration As long as the ns. g existin nodes do not detect any changes effecting the current co ng a eir onfiguration they n will co ontinue to ru without re un estarting. T allows y to add th new node to the This you he e config guration, sav the updat configura ve ted ation, and in nstall it (to ac ctivate the new node) without disr rupting the operation of the library. o
Chapter 3. Configuring Virtual De g evices 29
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 FTPd 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
Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 31
VTLIB VTSCR VTCMD
- A utility to add volumes to an MTL - The Virtuent scratch utility - 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 systems 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-Techs Unit Information Module (UIM). Each of these alternatives will be discussed. If you are planning on using MDL with IBMs 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-Techs 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-Techs 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 wont necessarily work with Bus-Techs Unit Information Module (UIM).
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-Techs 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 SC350427, 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. IBMs 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 units devices would have the same LIBRARY-ID, but have a unique LIBPORT-ID per control unit. For example:
Dev Add E800 E801 E80F E810 E811 E81F
CU CU800 CU800 CU800 CU810 CU810 CU810
Log CU 00 00 00 01 01 01
Library-ID 12345 12345 12345 12345 12345 12345
Libport-ID 01 01 01 02 02 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 /*
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-Techs 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
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 IBMs MVS/ESA Device Validation Support (GC28-1447) manual. Bus-Techs 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-Techs UIM does not support auto-switching. If you need to autoswitch tape devices between LPARs in a sysplex, do not configure your devices with the UIM.
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, lets assume you plan to use (32) drives on the controller (node). In the controllers 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
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. 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. 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
PREFIX=y
PREFIXLN=n
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. 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. 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.
FREESPACE
IGNLCSERR
ALLVOLS IGNLCSRC4
This parameter will allow scratch of volumes with data set names of all zeros. 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. This will prevent VTSCR from attempting any TCDB updates. This should only be used if the TMS already performs this function. This will prevent VTSCR from attempting to change the TCDB use attribute to scratch if Virtuent reports that the volser was already a scratch.
NOTCDB
NOTIFSCR
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.
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
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 //SYSLMOD //SYSUT1 // //SYSPRINT //DDIN EXEC PGM=HEWL,PARM='MAP,LET,LIST,NCAL,AC=1' DD DSN=USER.LIBRARY,DISP=SHR DD DSN=&&SYSUT1,SPACE=(1024,(120,120),,,ROUND), UNIT=SYSALLDA,DCB=BUFNO=1 DD SYSOUT=* DD DSN=BTI.MODULE,DISP=SHR
//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 //VTCLOG //VTCCMD EXEC PGM=VTCMD,PARM=DEV=xxxx DSN=VT.LOGFILE,DISP=OLD DSN=COMMANDS,DISP=OLD
DD DD
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 //VTCLOG DD //VTCCTRL DD //VTCCMD DD EXEC PGM=VTCMD DSN=VT.LOGFILE,DISP=OLD DSN=VT.CTRL,UNIT=VTAPE,VOL=SER=, DISP=(,CATLG) 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:
0x01 0x02
Invalid data length (must be between 1 and 256 bytes) 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 = 2004/09/10 12:47:49 CMD 2004/09/10 12:47:49 CMD 2004/09/10 12:47:49 CMD 2004/09/10 12:47:49 CMD EA82 ERR=FF: ISSUED: ERR=FC: ISSUED:
this is an invalid command q all q xxxxxxxx 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 //VTCLOG DD //VTCCTRL DD
EXEC PGM=VTCMD,PARM=WTOR DSN=VT.LOGFILE,DISP=OLD 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 //VTCLOG DD //VTCCTRL DD EXEC PGM=VTCMD,PARM=CMD=Q SPACE DSN=VT.LOGFILE,DISP=OLD 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. 44 Virtuent Users Guide
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 Virtuents 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.
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 GA320297.
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).
Filesystem 1 Node N1 N N1 Lo og VOLSERs s N2 Lo og Node N2 N
Filesystem 2
N1 Lo og N2 Lo og
Fi igure 4-1. DR Logging Over rview
These log files are hidden from view so th they cann be mista e e m hat not aken for tape volume e (VOL LSER) files. If a co ontroller (node) outage should occur a Virtuent Still in Use report can be s r, e n genera using th GENSTA utility. T report w read all the log files in the ated he ATS This will s virtua tape library and report those tape v al y volumes whi were mounted and ne ich ever unmou unted. The purpose of this report is to help determ which tape volume may be mine es incom mplete follow wing a contro oller failure. By pla acing the DR log files in the virtual t R n writing them on the m tape library rather than w contro ollers intern storage, the log files c be replic nal can cated to a secondary disa aster recove site alon with the ta volumes Then, in th unlikely e ery ng ape s. he event there i a is compl loss of the primary processing fa lete t p facility, the V Virtuent Still in Use repo can l ort be use to help identify all tap volumes t ed pe that were in use at the pr rimary site a the at time of the failure o e. Enabling DR Logging g By de efault, Virtue controllers will not au ent automatically create DR logs on the v y virtual tape li ibrary. To enable DR lo e ogging, a hid dden control filed named .vstats, m be d must presen in each fil nt lesystem where logging is to be perf formed. The .v vstats file ma be empty. Virtuent d ay does not look at the conte of the fi It k ents ile. only uses the pres u sence of the file to determ whethe or not to p f mine er perform DR logging.
Ch hapter 4. Usi Virtuent with z/OS, OS/390, or MVS 47 ing t
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 Maxtapes Still In Use Showing input / output by hour for the reported period Showing maximum tapes in use by hour for the reported period Showing tapes mounted and never unmounted
Slowest Mounts Showing the slowest tape mounts during the reported period
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 installations needs:
//L //SYSLMOD //SYSUT1 EXEC PGM=HEWL,PARM=MAP,LET,LIST,NCAL,AC=1 DD DSN=USER.LIBRARY,DISP=SHR 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.
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 DATEEND Optional. Will exclude statistics information for records preceeding the date specified.
- Optional. Will exclude statistics information for records dated later than the date specified. 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. 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. By default GENSTATS will process up to 2000 devices. DEVCNT can be used to increase the number of devices to be processed. This will produce a report detailing the highest number of concurrent tapes in use by hour for each of the days
DAYCNT=xxxx -
DEV=xxxx
DEVCNT=xxxx -
MAXTAPES
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. 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.
STILLINUSE
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. 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. The VOL parameter is required when using the DEV parameter to identify the tape volume (VOLSER) to be mounted.
THROUGHPUT -
VOL=volser
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 * /*
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
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.):
VOLSER H00090 GF0491 G00541 H00143 GB0147 G00592 GB0337 H00300 GC0574 G00562 GC0575 G00319 G10018 G40051 G40169 G30567 G10019 G10058 G50379 G00312 H00111 GB0318 G00110 GA0560 G70006 DATE 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 2008/11/07 TIME 17:27:12 18:06:57 18:58:34 18:09:31 17:27:12 18:05:39 18:06:57 18:54:26 18:54:26 19:06:16 18:54:26 17:39:40 17:14:22 17:14:22 18:54:26 18:13:17 17:19:14 18:39:58 17:23:39 17:36:26 17:43:25 17:58:40 17:01:29 17:54:14 18:39:58 PATH tapelib2/H0 tapelib/GF tapelib2/G0 tapelib2/H0 tapelib/GB tapelib/G0 tapelib/GB tapelib2/H0 tapelib/GC tapelib2/G0 tapelib/GC tapelib2/G0 tapelib/G1 tapelib/G4 tapelib/G4 tapelib/G3 tapelib/G1 tapelib/G1 tapelib/G5 tapelib2/G0 tapelib2/H0 tapelib/GB tapelib2/G0 tapelib/GA tapelib/G7
NODENAME bti bti bti bti bti bti bti bti bti bti bti bti bti bti bti bti bti bti bti bti bti bti bti bti bti
TIME 000.058 000.059 000.059 000.059 000.060 000.060 000.061 000.061 000.061 000.061 000.061 000.061 000.061 000.062 000.063 000.063 000.064 000.064 000.064 000.064 000.064 000.064 000.065 000.065 000.065
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 bti bti bti bti bti bti bti DEVICE A405 A404 A419 A415 A414 A413 A40F VOLSER GF0825 GF0826 G09009 G09005 G09004 G09003 H00365
:
PATH tapelib/GF tapelib/GF tapelib/G0 tapelib/G0 tapelib/G0 tapelib/G0 tapelib2/H0
LAST MOUNTED 2008/11/10 10:23:18 2008/11/10 10:23:18 2008/11/07 19:26:43 2008/11/07 19:26:43 2008/11/07 19:26:43 2008/11/07 19:26:43 2008/11/10 10:23:18
Chapt 5. Using Vir ter U rtuent wi VSE ith E

Overvie ew
In z/O and OS/390 environm OS ments, Virtue receives Load Displa command from ent ay ds the op perating system. Originally, these co ommands inf formed an op perator of a m mount reques for a volum on a spec st me cific tape dri by lighti the LCD on the top o the ive ing of drive. Virtuent use the Load Display com es mmands to m mount scratch tapes or in h nput volum mes. Howeve VSE doe not send L er, es Load Display commands the way z/O does. y s OS Instea VSE show either the job name o the mount volume s ad, ws e or ted serial numbe in the er Load Display com mmand, so mount reques cannot be fulfilled au m sts e utomatically by Virtue using jus the operati system fu ent st ing functions. In nstead, a util program must be lity used to send a Loa Display command to Virtuent. T program used depend upon t ad c The ds wheth you are using Epic, Dynam/T or no TMS. her u D
Configu uration Pa arameters Unique to VSE o

Global When configuring Virtuent fo use with V systems the followin paramete should n g or VSE s ng er be spe ecified as an additional parameter in the Global o n p n options secti on the D ion Device page (See Figure 5.1 ) in orde to allow th VSE utilit to work properly: ( er he ties ALLOWV VSEUTILITI YES IES
Figure 5-1. Global O Options for VS Systems SE
C Chapter 5. U Using Virtuen with VSE/ nt /ESA 55
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.
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, CAEPIC, 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
Chapter 5. Using Virtuent with VSE/ESA 57
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.
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)
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 60 Virtuent Users Guide
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 * * ********************************************************************
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 (A00000A99999), 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 62 Virtuent Users Guide
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 installations 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
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 installations 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 ACLs 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. 64 Virtuent Users Guide
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 BIMEPIC'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:
// 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.
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), (G,G00000,G00100),TAPE=YES TSIDMAP END=YES END /* // EXEC LNKEDT /* SET SDL TSIDPOL,SVA /* /& /* /&
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 installations 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 installations needs and catalog the VIREPERA phase into a VSE library. 68 Virtuent Users Guide
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
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 users 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 users 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. 70 Virtuent Users Guide
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

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> ftp> ftp> ftp> bin quote site fix 1024 put vtscr.module 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.
Chapter 6. Using Virtuent with VM 73
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
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.
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.
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
follows: 0x01 0x02 Invalid data length (must be between 1 and 256 bytes) 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

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 x48, 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.
Chapter 7. Using Virtuent with Unisys 79
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.
Figure 7-1. Un F nisys Device P Panel
Initializ zing Tapes for Unisy ys

When initializing tape volume to be used with Unisy you must include the n es d ys LABE EL=A option on the initi n ialize comma to tell th system that the tape la and he abels will fo ollow the AN standard NSI d. For ex xample, to in nitialize 100 tapes beginn ning with V VOLSER B00 0000 using t tape drive E980, you would enter the following initialize c w t g command: INITIALIZ VOL=B0 ZE 00000 DEV= =E980 COU UNT=100 LA ABEL=A
Configu uring the Mainfram for Virt M me tuent

Virtue devices are configure in OS220 using SCM / SCMS- as 1 or m ent a ed 00 MS -II more CTS5136-VSM (n non-library) subsystems of 1 to 16 u units. The re esulting ODB or B .PTN file must be installed an the OS reb e nd booted with the proper d definitions. U ment fo devices is U47M. The Unisys equipm code for Virtuent d
Chapter 7 Using Virt 7. tuent with U Unisys 81
Chapt 8. Sy ter ystem Op peration n

Once the storage is attached and configure the virtu tape devic are defin and i a ed, ual ces ned, the ma ainframe has been configured (and r s re-initialized if necessary you are r d y), ready to start operating the Virtuent co o e ontroller.
VT Con nsole
The virtual tape ap pplication ru as a start task (dae uns ted emon) on the MDL contr e roller and is known as vt. vt will attempt to a s autostart whe enever the M MDL controll ler (node) is powered on and brou d ught up. A separate progra named vt console can be run at an am n nytime from the Virtuen m nt ograms Stat panel. A shown in F tus As Figure 8-1 th are two icons here o Configuration pro on the status pane for each co e el ontroller (no ode) in the M MDL; the left icon will di t isplay the co ontrollers (n nodes) log in nformation. The Conso icon on th right will initiate ole he l a vt co onsole sessio allowing you to moni and oper the Virtu tape-on on itor rate uent n-disk applic cation.
Figure 8-1 Status Panel 1. l
When never you cli the Cons icon for a specific c ick sole r controller (node) a conso will ole open on the deskto and begin displaying messages fr o op n g rom the virtu tape (vt) ual applic cation. Figur 8-2 shows a sample o an active v console w re s of vt window. Opera ation of the vt application daemon is independen of the vt co v n nt onsole. The vt e applic cation will of be running even wh the vt co ften hen onsole progra is not sta am arted. Likew wise, the vt console progr can be r c ram running with hout the vt ap pplication be eing active Once the Virtuent con e. V ntroller is run nning you ca check the status of the virtual an e e tape (v application at anytim by clickin the Conso icon on th Status pan vt) me ng ole he nel (Figur 8-1). re
C Chapter 8. S System Oper ration 83
Figu 8-2. Activ vt Console ure ve
vt console is split into two section The larg top secti displays log message as e o ns. ger, ion es they are is ssued from the vt application. On st t tartup vt con nsole will dis splay all messages in the log si ince the last startup of vt console or the last 100,000 bytes o the t of log. The follow wing naviga ation keys (or commands can be use to scroll th s) ed hrough the messages: Ho Move to the top ome e En Move to the bottom nd o m Pg Move up one scre gUp e een Pg Move down one screen gDn e s The botto or smaller section of vt console d om displays in bl and alwa shows th lue ays he current sta of the virtual tape (v applicati on on this co atus v vt) ontroller (no ode). As sho own in Figure 8-2, the vt application is not running Below th VT Status line is a a s g. he command line where you may ent and edit v command d ter vt ds. The follow wing naviga ation keys ca be used on the comma line: an n and Up Arrow or Ctrl+P previous comm p C mand in histo ory Do Arrow or Ctrl+N next comma in histor own and ry Le Arrow move 1 char eft m racter to the left in the co ommand line e Ri ight Arrow or Ctrl+F move 1 chara o m acter to the r right in the c command lin ne Ct trl+A mov to the begi ve inning of the command l e line De or Ctrl+D delete one character el D e Ct trl+E move to the end of the line e Ba ackspace or Ctrl+H ba ackward dele character ete r 84 Virtuent Users Guid de
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 STOPVT to start the vt application and activate devices in the installed configuration file 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).
Chapter 8. System Operation 85
Figure 8-3 VT Console when vt is A 3. e Active
I Initializing Scratch Volumes g

Before Vi irtuent can mount a tape volume in t tape libra you must initialize th m the ary he tape volum that you want Virtu to use w mes u uent within that lib brary. There efore the ver ry first time you start any tape drives on Virtuen you must i y s nt issue at least one Initialize t command in the Cons window (Figure 8-2 or there w be no scratch tapes w d sole w 2) will within the tape li ibrary for Vi irtuent to use e. As explained in Chap 2, a Virtu library is made up o one or mo filesystem pter uent of ore ms and may be sub-divid into stora classes. You do not have to init b ded age t tialize new t tape volumes into each and every files i d system. But you do need to initialize tape volum d e mes into each storage class. If there are no scratc volumes in a storage c a ch class then w ble y equest for a s scratch withi that storag in ge Virtuent will not be ab to satisfy a mount re class and the mount will remain pending. w p If you hav not define storage cl ve ed lasses (other than the def r fault class 0) then you w ), will only need to initialize a single ran of tape v d e nge volumes to th library. B if you have he But defined multiple stora classes th you mus initialize a range of V m age hen st VOLSERs for r each class you have defined. s d The comm mand to initi ialize tapes is: INIT TIALIZE VO OL=volser DEV=devnam COUNT= me =count CLA ASS=n DIR=dirname Where vo olser is the st tarting serial number to i l initialize, de evname is th device nam he me (address) of any tape drive pointin to the tap library, co ng pe ount is the nu umber of ser rial numbers to initialize, n is the clas these volu t ss umes are to b added to, and dirname is a be 8 Virtuent Users Guid 86 de
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 mainframes 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
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.
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
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.
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: VIR010I: VIR011I: VIR012I: VIR013I: VIR013I: Compression level set to 1 (0=none,1=faster,9=smaller) Compression hardware available Compression driver version: 1.0.8 Compression card #0: id=9 version=200 state=00000000 Hardware compression set ON 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.
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. 92 Virtuent Users Guide
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.
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. 94 Virtuent Users Guide
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 wont 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%.
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.
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.
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 reinitialize 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).
Figure 8-4. Reboot Button on Status Page e t
Note that if your MDL system includes m t M m multiple node there will be a separat Reboot es te button for each no n ode.
Set Dat and Tim te me

The Virtuent syste time is displayed in t status lin at the bott V em d the ne tom of the vt t Conso System date and tim are used t stamp tape volumes b ole. me to being created on disk. d If you need to adju the syste date or tim you may do so from the Time ta on the u ust em me y ab Extern panel of Virtuent Co nal onfiguration (Figure 8-5) ).
Figu 8-5. Chan ure nging Date an Time nd
There are 2 metho for settin date and t ods ng time on a Virtuent contro oller. You c can manua set a spe ally ecific date an time or y can confi nd you figure the sys stem to use a Netwo Time Pro ork otocol (NTP server. P) To ma anually set date and time simply adju the date and time sho and then press d e ust own n the Se button. The date and time will be set in all co et T e ontrollers (no odes) in the system. If you Virtuent co ur ontroller (M MDL) is conn nected to you corporate network and one or ur d more Network Tim Protocol (NTP) serve are acces N me ers ssible, you c easily configure can the co ontroller to get date and time from th server(s). g t he Simpl enter eithe the networ name or I address of up to four N servers When ly er rk IP f NTP s. you make this con m nfiguration active by inst a talling it, the controller ( e (nodes) in th he
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.
Figu 8-6. Conf ure figuring Notifi ications
Sending E-mail Virtue will auto ent omatically se messages to one or tw e-mail ad end s wo ddresses via an a SMTP mail server To use thi capability you must fi out the following field on the P r. is y ill ds Notify tab of the External pa of Virtue Configur y E anel ent ration: Mail Server the IP addr or host n M ress name of an S SMTP mail s server that w will forward the e-mails Se ender email an e-mail address you want to be included in the from fie of the u eld message. Thi may or ma not be a r is ay return e-mail address. l Re ecipient email address the e-mail address you want Virtu to send l u uent messages to. ystem name the name of the Virtu MDL co e uent ontroller the e-mail is be eing sent Sy fro om. Option nally you may complete a Company name, Contact name, and Option e y nal description. You may also include a Sec u cond recipie e-mail address who w also ent will receiv the e-mail ve ls. Warning: Be sur to review and underst re tand which m messages ar configure to be re ed sent to your e-ma addresses before conf o ail s figuring the (Refer to the section em Conf figuring Me essages to be Sent). Ac e ctive Virtuen controller can gener nt rs rate thousands of info ormational messages ove a short pe m er eriod of time and it is hi e ighly ely ld se sent as an e-mail to you SMTP ur unlike you woul want thos messages to each be s mail server. s Note: You canno send mess ot sages to Bus s-Tech by co oding the e-m fields w Busmail with Tech e-mail addresses. Virtu uent will ign nore any e-m address that include mail es buste ech.com.
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 Companys name. System name the name of the Virtuent MDL controller the e-mail is being sent from. Contact name a contact persons 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.
Fig gure 8-7. Mes ssage Configu uration
As sho own, the Me essages pane has three ( tabs repre el (3) esenting info ormational, w warning, and er message Clicking on any one of the tabs s rror es. shows a com mplete list of all f Virtue messages in the categ ent s gory identifi by the tab (informati ied ab ion, warning or g, error). Also displ layed are fou (4) check boxes to the right of eac error message; ur e ch repres senting SNM Vendor E-mail, Cust MP, E tomer E-mai and Mainframe (z/OS il, S Conso ole). At the top is a row of toggle a check b w all boxes. All ch heck boxes in the Vendor Email colu n umn are for i information purposes on nly. You canno modify wh message are sent to Bus-Tech a which a not. This column ot hich es o and are s is prov vided only to allow you to see which messages w result in an e-mail b o h will n being sent to Bus-Tech and which will not. o a w For SN NMP, Custo omer Email, and Mainfra you can use the preame n -configured defaults or you can configu each message or eac category a you want. u ure ch as . For ex xample, if yo want all warning mes ou w ssages to be sent to your z/OS conso you ole can ch heck the togg all check gle kbox under M Mainframe o the Warni message routing on ing tab. This will res in all wa T sult arning messa ages being se to the z/O console. ent OS Warning: Bus-T Tech strongly recommen not sendi all warn y nds ing ning and inform mational me essages to yo e-mail ad our ddress(es). An active V Virtuent cont troller may send thousan of inform s nds mational an warning m nd messages ov a short period of ver time. You must be selective in selecting w b i which messa ages are aut tomatically s sent as mail -mail addres ss. an e-m to an e-
V Viewing Me essage (Log) Files ) Virtuent controllers (n c nodes) main ntain a log of all message issued by the virtual ta f es ape applicatio Log files are automa on. s atically rotate each day at midnight. Old log fil ed les are compr ressed to min nimize the space they ta and then kept for a period of time ake e. From the Virtuent Co onfiguration application y can view the curren log file on a you w nt Virtuent controller (node). To vie a log file for a contro c ew e oller simply click the Lo ogs icon for th controlle (node) on the Status pa of Virtu Configu hat er anel uent uration (Figu ure 8-8).
Figu 8-8. Openin a Log File ure ng
This will result in a ne log wind opening displaying a list of recent log mess ew dow g; g sages issued by Virtuent (Fi igure 8-9). You may scr back and forth throu the days log Y roll d ugh s messages.
Figu 8-9. Viewi a Log file ure ing
1 104 Virtuen Users Gui nt ide
User Ad dministra ation

By de efault Virtuen nt-based sys stems ship w two defa user nam (ids): ad with ault mes dmin and readon nly. The def fault passwo for these two user na ord ames is pass sword. The ad dmin user ha full admin as nistrator righ and can c hts create and/or modify the existing r e config guration as well as monit and cont operation of the cont w tor trol n troller. The re eadonly user can view th configura r he ation and che the status of the cont eck troller(s) but do not have the authorit to modify configuratio or opera the contro oes ty ons ate ollers. A user administra ation panel within Virtue Configur w ent ration allows admin user the s rs ability to add, dele or modif user name recognize by the sys y ete, fy es ed stem. User administratio is perform from the Authentica a on med e ation tab on t External panel of the l Virtue Configur ent ration (Figur 8-10). re
Fi igure 8-10. Us Administr ser ration
Virtue controlle support tw types of u adminis ent ers wo user stration; nati or Lightw ive weight Direct tory Access Protocol (LD DAP). Nativ user adm ve ministration st tores the use names er and pa asswords on the Virtuen controller a is the de n nt and efault type w when the con ntroller is first in nstalled. WARN NING! Do not attempt to change th authentic the cation type f from Native to e LDAP unless you Virtuent controller (M P ur c MDL) is atta ached to you corporate network ur and yo already have the app ou h propriate dir rectory serve installed a running on the er and g netwo ork. Failure to successf e fully attach t an extern directory server coul result to nal y ld in not being able to log in to the Virtuent Configuration applica t t ation. As sho in Figu 8-10, the Readonly a own ure e attribute restr ricts a user n name to only being y able to view the cu o urrent config guration and status of th controller. User name d he . es withou the Reado ut only attribute set are syst adminis e tem strators with full access. You can modify existing nam password or read o c e mes, ds, only attribute by simply typing es y over an existing entry. You can remove a user from t system by clicking D a the Delete box to the right of the user nam o f me.
Warning! Be careful not to delet all user na ! l te ames with fu administ full trator privile eges. If there are no admin a nistrator use you will n be able t modify or operate the ers not to r e system. n . ry ttom To add a new user click the Add next button. A new entr will appear at the bot of the list of users. L LDAP When you configure Virtuent use authenticat u V er tion to use a external L an Lightweight Directory Access Prot y tocol (LDAP server use names and passwords will no long P) er d ger be mainta ained on the Virtuent con ntroller. Wh a user att hen tempts to log into the g Virtuent controller a call will be made to the L c c m LDAP serve searching for the user er name and password th has been entered into it. If the user is found and the d hat n o password is correct th access will be given to the user. hen w gure a Virtue controller to use LDA authentic ent r AP cation you m provide must To config informatio telling the controller how to cont the LDA server. on tact AP Begin by clicking the LDAP radio button on t Authenti o the ication tab o the Extern of nal V nfiguration (F Figure 8-10) Then click any place o the screen to ). k on n panel in Virtuent Con display th LDAP con he nfiguration fields (Figur 8-11). f re
Figure 8-11. LDAP Configuration e n
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 Base DN the IP address or network name of the LDAP server. Virtuent will use this address / name to contact the LDAP server. 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. 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.
Name filter -
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 9. z/O Cons Ope ter OS sole eration

Virtue based con ent ntrollers pro ovide an opti ional z/OS u utility that ca be used to an o comm municate betw ween a single logical par rtitions (LP PAR) operato console an the or nd MDL (see Figure 9-1).
MDL Com mmands
Host Ut tility
MDL Mes ssages Figure 9-1. z/OS to MDL Commu e unications
ake M ation, you m install th z/OS VTH must he HHOST To ma use of MDL z/OS Console opera utility and then co y onfigure the individual M MDL control ller(s) to com mmunicate w it. with Using the Virtuen Configurat g nt tion program you can co m onfigure whi type ich (inform mational, wa arning, or er rror) messag and / or w ges which specif Virtuent m fic messages are sent over the channel to th mainframe (See page 102). c he e
VTHHO OST
The name of the host utility providing z/O Console O h OS Operation su upport is VTHH HOST. The VTHHOST utility runs as a started task, and ac T ccepts comm mands from the operator. By default VTHHOST will use W t t, T Write-to-Ope erator (WTOR) capabilities for sen nding MDL commands. Optionally you may configure VT y, THHOST to use the z/OS MODIFY fun e M nction in plac of WTOR ce R. At sta artup, VTHH HOST will re a configu ead uration file t defines t Virtuent that the contro ollers (nodes to be supp s) ported as wel as the devi addresses, per contro ll ice oller, to be use for comm ed munication an logging. Each Virtue controller (node) will be nd ent r l identified with a unique name so that com u e mmands can b targeted t specific be to contro ollers. A tap drive devi address m be selec from ea controlle pe ice must cted ach ers range of addresses that will be used as the command/c s e e communicat tion path. A 2nd device address is required on each control if you w Virtuent to send log e r ller want t messa ages to the z/ /OS console. These dev vices will not be eligible for allocatio once t on VTHH HOST has be started. een
Chapte 9. z/OS C er Console Oper ration 109
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 operators 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
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.
Chapter 9. z/OS Console Operation 111
The following is sample JCL for VTHHOST within a 3 controller (node) configuration supporting both messaging and commands:
VTLNODE1 VTLNODE2 VTLNODE3 038E 038F TAPECON1 039E 039F TAPECON1 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 operators 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: 112 Virtuent Users Guide
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
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). 114 Virtuent Users Guide
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 10. Using Data Enc ter U D cryption

Virtue includes a data encry ent yption modul allowing y to encry data usin AESle you ypt ng 256 en ncryption as it is being written. Both the tape he w h eader labels and the data files are a encryp pted. Data encryption is configured on a drive b drive basi That is, y can conf e s d by is. you figure one or more drive to perform data encryp r es m ption. Each time a tape volume is w written to one of those drive the data will be autom f es, w matically enc crypted befo it is writte to the ore en backend storage. If you want some tape volume to be encr u es rypted and o other tape volumes to be left unenc crypted, you will need to configure y o your Virtuen controller t appear as two nt to separa libraries to the mainf ate t frame allowi you to di ing irect individu tape volu ual umes to an app propriate dri ive. Figure 10-1 shows an example where separ manual tape rate librari (MTLs) are defined. ies a
Drives 00 0F 0 MTL1 1 Drives 10 1F MTL2
Devices 00 0F 0 Encryption = No n B00000 encrypted 0 B B00001 Devices 10 1F 0 Encryption = Yes n B00002 encrypted 2 B B00003
Figure 10-1. Confi figuring for En ncryption
As sho own, the con ntroller is co onfigured wit a single li th ibrary as a b backend. In o other words all tape driv in the co s ves onfiguration are configur using the same tape library red e name. This implies that all ta volumes are written t the same l . ape to library whet ther or not they are encry ypted. But th drives wit device ad he th ddresses 00 0F are conf figured withou encryption and the drives with de ut evice address 10 1F a configured with ses are encryp ption. Figur 10-2 show sample de re ws evice add con nfiguration p panel that co ould be used to configure these device Notice th the secon group of drives, with t es. hat nd addres 10 1F have been configured w an encr sses F, with ryption key c class (MFCL LASS in this ex xample). Th indicates that Virtuen is to encry any volum written to these his nt ypt me drives s. On th mainfram two MTLs are defined In this exa he me s d. ample the de evices 00 0 are 0F define as MTL1. The device 10 1F ar defined as MTL2. ed . es re s
Chapte 10. Using Data Encry er g yption 117
Figure 10-2. Add De vices Example e e p
118 Virtuen Users Guide nt i
Configured in this manner, yo system A s our ACS routines can direct i s individual ta ape volum to be enc mes crypted or no If the AC routine d ot. CS directs a tape volume to M MTL1 it will not be encryp pted. However, if a volu is direc to MTL2 it will be ume cted 2, encryp pted. The ab bove example uses syste managed storage (SM and MT definition to em d MS) TL ns separa drives ba ate ased on whet ther they enc crypt or not. However, t same can be the n accom mplished usin Bus-Tech UIMs or using simple esoterics. If esoterics are used, ng hs all dri ives in the MDL will be able to read a previously encrypted tape volume But M d y e. you ne to make sure to spec the appr eed cify ropriate esote in the JC for a tape that is eric CL e being written to. In ord to encryp a tape volu Virtuen needs acce to a key t use during the der pt ume nt ess to g encryp ption proces Virtuent communicat with the RSA Key M ss. tes Manager from RSA to m obtain its keys. If you intend to use data e n f encryption o the MDL you will nee to on ed obtain a license fo the RSA Key Manage from RSA Security, in n or K er A nstall it on a server on you network, and connect your Virtue controlle to the netw ur t ent er work in order to r provid it with acc to the RSA Key Ma de cess R anager. Plea refer to t hardware ase the e install lation guide that accomp panied your V Virtuent con ntroller for in nformation o how on to con nnect and con nfigure your controller f network access. r for Figure 10-3 shows how differ Virtuent controllers connect to R e rent t RSA Key Manager. For single control llers, such as MDL-1000 s 0/2000, an E Ethernet port on the indiv vidual oller connect it to your company ne ts c etwork for ac ccess to the R RSA Key M Manager. contro For multi-node pr m roducts, such as MDL-60 h 000/4000, th individual nodes (con he l ntrollers) conne to the Acc Control Point (ACP via the int ect cess l P) ternal contro network w ol within the MDL. The ACP then acts as an IP gatewa connectin to the cor . t ay ng rporate netw work to gain access the RS Key Man a SA nager.
M MDL600 00/4000
Nodes
M MDL-1000 / 2000 ACP
R RSA K Key Ma anager
Figure 10-3. Connect ting to RSA K Manager Key
When the mainfra starts wr n ame riting a tape volume to a tape drive w an encr with ryption key cl (see Figure 10-2) Vi lass irtuent will m make a call t the RSA K Manage using to Key er the ke class to re ey equest a set of keys. Sin a call is m o nce made for eac new volu ch ume, each indivi idual tape vo olume can be encrypted w its own unique key e with n y.
Chapte 10. Using Data Encry er g yption 119
The RSA Key Manag will retur two keys t Virtuent; a clear key a an ger rn to and encryption key. The clear key wi be written to the tape volume alon with tape n c ill n ng volume da The enc ata. cryption key will be used to encrypt the volumes data y d (including the header records) bef g fore the data is written to tape. The encryption key a o e is never written to the tape. On ta unload b w e ape both the encr ryption key a the clear key and r are discar rded. When an encrypted vo olume is mo ounted for in nput (or mod dification) the tape drive will e recognize that the tape has been encrypted an retrieve th clear key f e e nd he from the tap pe volume. It will then make a call to the RSA Key Manager; passing i the clear k it key. The RSA Key Manag will authe requesting c ger enticate the r controller (no ode) and the use en the clear key to retriev the encry k ve yption key fro its data s om store. The e encryption ke ey will be ret turned to the Virtuent co e ontroller so t that the drive can read (o modify) th e or he tape. Wh the tape is unmounte both the c hen ed clear and enc cryption key will be ys discarded d.
C Connectin to the RSA Key Manager ng R M

In order for Virtuent to perform data encrypti f t d ion, your Vir rtuent contro oller (MDL) must have access to a network wi access to the RSA Ke Manager. Follow e ith ey instruction in the MD installation guide tha accompan your spe ns DL at nied ecific MDL model in order to con nnect your MDL to the n etwork. M g ller work access, y configu Virtuent t access the you ure to e Assuming the control has netw RSA Key Manager fr y rom the Encr ryption tab of the Exter rnal configu uration panel l within Virtuent Confi iguration (Fi igure 10-4).
Figure 10-4. Connecting t RSA Key M to Manager
ample shown the RSA Key Manage r is located a IP address 10.1.4.105 and n, K at s In the exa to is using Port number 38443. You will need y P u your RSA ad dministrator t provide y you with the appropriate network addr and por for your en a n ress rt nvironment.
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.
Chapter 11. Back-End Tape Support 121
Fig gure 11-1. Ma apping a Devic to a fibre ch ce hannel attach IBM 3592 Tape Drive hed
The emulated tape dri must be configured t match the characterist of the ive to tics t A 1, be physical tape drive. As shown in Figure 10-1 the device being configured must b defined as Device Typ 3590. s pe Also, once you have mapped a de m evice in this fashion, you must isolat the mainfr u te rame device fro other virt devices in the mainf om tual frame config guration in o order to contr rol when a re tape is wr eal ritten versus a virtual tap written to disk. Speci pe o ifically, if yo ou are using MTLs, you would want to assign a u unique libra id (MTL) to this devi ary ) ice address. Then the onl time a phy T ly ysical cartrid will be w dge written is wh the syste hen em ACS routine determin a real car nes rtridge is to b written an assigns th appropria be and he ate library id. Otherwise when the mainframe all . m locates to the library id ( (MTL) representi the other 15 drives a virtual volu will be w ing r ume written. When a mainframe de m evice is map pped to a phy ysical tape dr in this m drive manner mou unt requests will work jus as they wo w st ould if the dr were dir rive rectly attach to a hed mainfram channel. Allocation of the drive w result in a mount req me A o will n quest being posted to the mainfram operator console. Th request w remain outstanding u me he will until the physic drive bec cal comes ready. Normally this will req quire an oper rator to moun a nt tape and ready the dri r ive. The tape cartridge wr c ritten will be compatible with 3590 c cartridges wr ritten from a any mainfram attached 3590 tape dri unless th volume ha been encry me 3 ive he as ypted by Virtuent. Virtuent cre eated cartrid dges can be s sent to mainf frame locatio that do n ons not have Virtu installe as long as those locati uent ed ions have rea or compat al tible tape dri ives capable of reading the 3590 / 3490E cartridge e e.
Compression and Encryption E Virtue supports mainframe initiated data compressio If a mai ent i a on. inframe tape device e mappe to a physi fibre channel attach drive req ed ical hed quests compr ression Virtu will uent instruct the drive to compress the data bef t fore writing it to tape. T tape driv rather The ve, than Virtuent, will perform th data comp V he pression in or rder to ensur compatibi re ility with other IBM drives that may lat attempt to read the da ter o ata. If the mainframe device confi d iguration pan mapping a device to a fibre chan nel g nnel attach tape driv specifies an encryption key class ( hed ve a n (see Figure 1 11-2) then V Virtuent will perform both data compre ession and e encryption on the data be n efore writing to the g drive.
Figure 11-2. Direct Tape with En e t ncryption
In this case the res s sulting cartri idges written WILL NO BE COMPATIBLE w tape n OT with drives not attached to a Virtue controlle Only a V s ent er. Virtuent attac ched tape dri will ive be abl to re-read the tape cart le tridge. The Virtuent con ntroller read ding these ca artridges must be configure with acces to an RSA Key Mana b ed ss A ager that can correctly re esolve the clear key stored on the tape ca k artridge in or rder to allow decryption to successfu w n fully occur.
Chapter 11. Back-E Tape Su r End upport 123
T Tape Expo / Impo Utilities ort ort s

As an alte ernative to Direct Tape where a main D w nframe tape drive is map pped directly y through to a physical IBM drive connected to the Virtuen controller (node), Virt o c o nt tuent also inclu udes two utili ities for expo orting or imp mporting tape volumes be e etween the Virtuent disk library and a Virtuent attached t d a tape drive. These com mmands are executed fro within th Virtuent a om he application a have no u and user interaction If a comm n. mand is ente ered incorrec an error message wil be issued. The ctly ll operator can then rety the comm c ype mand correc tly. Because these comma t ands copy ta volumes based only o VOLSER without ape on R knowledg or regard to what data may actuall be contain on the v ge t a ly ned volume and because Virtuent often does not have a tape d V n h drive physica attached to it, these ally d utilities ar disabled in the default Virtuent co re t onfiguration. If you hav attached a ve physical tape drive to a Virtuent controller, no being used by Tape D t c ot Direct, and yo ou wish to us the tape export / impo utilities y will need to modify t Virtuent se ort you d the configura ation to enable them. To enable the Virtuen Export / Im e nt mport utilitie open the a es active Tape d device configura ation and che the Tape export ena eck e abled check ( (Figure 11-3 3).
Figure 11-3 Enabling Ta Export / I 3. ape Import
The next time the Vir t rtuent application is resta arted the exp / import utilities wil be port t ll available.
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 DRIVEnnnnnnnnnnn 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 deencrypt 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.
Chapter 11. Back-End Tape Support 125
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 users 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 12character 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 12. Data Ex ter D xchange

As pre eviously disc cussed, Virtu controllers normall write tape volumes to disk uent ly using a specialized file format Using this format allo Virtuent to preserve an exact t. s ows t e image of a tape vo e olume includ ding tape ma arks, headers trailers, an variable le s, nd ength record Mainfram jobs read ds. me ding a tape v volume from a Virtuent-b m based library receive y the vo olume exactl as if it had been really written to a tape. ly d y For cu ustomers wh wish to us a Virtuent controller t provide da exchange ho se t to ata e betwe the mainframe and an other, op en system (W een ny Windows, U Unix, Linux, etc.), Virtue provides a capability referred to as flat file su ent y upport. As t name im the mplies, flat fil support writes a flat data file that contains onl the data w le w d ly written by the e mainf frame minus tape marks, headers, an trailers an without re nd nd egard to reco ord length hs. Coupl with Gig led gabit Etherne and Netwo File Syst (NFS), f file supp et ork tem flat port allows Virtuent co s ontrollers to be used to e exchange dat between t mainfram and ta the me any ne etwork-attac ched server (Figure 12-1 ). (
Virtuent Con ntroller

N NFS S Server Flat Files
Tape e Libra ary
AWS Fil les
Figur 12-1. Flat Fi for Data E re iles Exchange
The purpose of this chapter is to discuss h how to configure a Virtu controlle for uent er Data Exchange, how to write a flat file fro the main E om nframe so oth non-main her nframe applic cations can use it, and ho to read a flat file from the mainfr u ow m rame.
Chapter 12 Data Exch 2. hange 127
C Configura ation
V Virtuent Co ontroller h ds d xchange volu umes in your r Bus-Tech recommend that you do not place your data ex primary li ibrary. If yo are using /tapelib, for example at the top level identifier f ou for your libra then you should crea a differen top level i ary, u ate nt identifier for your data r exchange filesystem. Figure 12 shows a sample confi 2-2 s figuration wh here a single filesystem ( e (disk) is bein ng defined fo data excha or ange. Notice the second mount poin defined us the name d nt ses e /dataexch instead of /t h tapelib as th top level id he dentifier. Y can use any high-lev You vel name you want as lon as it is dif u ng fferent from the high-lev name (/ta vel apelib) used to define the primary vir e rtual tape lib brary.
Figure 12-2. Defining Stora for Data E F D age Exchange
Once you have define the storag in the avai u ed ge ilable storag list (Figure-12-2) you need ge to connec it to the Vi ct irtuent controller (node) where you p to defin tape drive for plan ne es data exchange. Figur 12-3 show that the da exchange storage is c re ws ata e connected to o localhost in this exam mple.
Figur 12-3. Conn the Storag to the Cont re nect ge troller (Node)
Once the storage is connected to the contr i d roller you ca then defin drives to w an ne write to the da exchange disk (filesy ata e ystem). How wever, unlike defining de e evices to wri to a ite virtua tape library where you point the ta library to the high-lev qualifier al y u ape o vel r (/tapelib, for exam mple), when you are defi ining disk fo data excha or ange you nee to ed point the tape libr rary field directly to the m mount point (/dataexch/D t DISK1, for examp ple). To do this you nee to select ed (free-form) from the p down lis in the ) pull st Tape Library field on the devi definition panel (Fig L d ice n gure 12-4).
Figur 12-4. Enter re ring Free-For Data into th Tape Libra Field rm he ary
Once you have do this the configurator will return a free-form f one c field for you to type u in. Enter the enti mount po name for the disk wh you wa to write d E ire oint r here ant data excha ange volumes to (Figure 12-5). s
Figure 12-5 Configuring Devices for D 5. g Data Exchang ge
Once you have en ntered the mo ount point cl lick add to c create the ran of device If the nge es. Add devices were filled out as shown in F d e s Figure 12-5, sixteen devi ices will be d defined pointi to the dat exchange disk as show in Figure 12-6. ing ta wn e
Chapter 12 Data Exch 2. hange 129
Figure 12-6. Data Ex xchange Devic ces
Once thes devices ar defined an tape volum written t any of these devices w se re ny me to will be placed on the data exchange di rather tha the virtua tape librar If, for d isk an al ry. example, you are usin MTLs in z/OS to defi your MD library, you should pl ng z ine DL lace the data exchange dev vices in a sep parate MTL so that you can isolate t them from devices co onnected to the primary library. z z/OS, OS/39 90 on y define two se eparate librar on the ries With this configuratio in place, you would d me. mple, if you are using M MTLs, you m might define t first 14 d the drives mainfram For exam in this con nfiguration as MTL1, all with the sa library id The two drives a l ame d. configured for data ex xchange wou be config uld gured as a M 2, with a different MTL library id. Your ACS routines wo . S ould then key off of the h y high level da ataset name qualifier to determine which MTL to direct sp t e L pecific tape v volumes to ( (MTL 1 or M MTL 2). V VSE allations whi do not us tape mana ich se agement soft ftware must m manually VSE insta allocate sp pecific tape drives with their JCL. S if you ha set aside a drive for d So, ave data exchange, run VIRMO OUNT (see page 58) usi that driv address. ing ve If you are using a tape manageme system, s e e ent such as Dyna am/T or EPI then Virt IC, tuent allocates drives for th tape mana d he ager and you must isolate the data ex u e xchange driv ve from drives using the primary tap library (/ta pe apelib). To isolate a drive for data exchan include th GROUP option when you define the e nge he n drive to Virtuent (pag 28). Assig a unique group numb to each d V ge gn ber drive going to the o same fold der. Data exch hange drives should not be under the control of t tape man s b e the nagement sys stem. V VM For VM you would al y llocate data exchange vo e olumes to on of the two tape drives that ne o have been configured for data exc n d change. All other volum would b allocated t l mes be to one of the drives not connected to the data ex e c o xchange libra ary. 1 130 Virtuen Users Gui nt ide
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 users 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
Chapter 12. Data Exchange 131
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

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 sixcharacter 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.
Appendix A. Volume Handling 133
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 hostgenerated 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
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).
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 volumes 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 136 Virtuent Users Guide
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 operators SET SIZE command. Appendix A. Volume Handling 137
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.
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 hosts write command.
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 Appendix B. AWSTAPE Information 141
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 x9F

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 volumes 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. Appendix C. Load Display Command CCW Opcode x9F 143
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 1-8 9-16 Format Control Byte Message 0 Message 1
Format Control Byte (FCB)
Bits 0-2
Value Function Select 000 001 010 011
Description
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. 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. The message specified in bytes 1-8 is maintained until the drive is next loaded. 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. Reserved. 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).
100 to 110 111
3 0 1
Alternate Messages The tape drive displays only the message that is specified in bit 5. 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. Blink Message 0 1 The message specified by setting bit 5 does not blink. The message specified by setting bit 5 blinks repeatedly. When bit 3 is set to 1, bit 4 is ignored. Display Low/High Message 0 1 The message specified in bytes 1-8 is displayed. This bit is ignored if bit 3 is set to 1. The message specified in bytes 9-16 is displayed. This bit is ignored if bit 3 is set to 1. Reserved Index Automatic Load (Reserved)
6 7
0 0
Appendix C. Load Display Command CCW Opcode x9F 145
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

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-Techs 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.
Help and Service Information 147
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 From Outside the U.S.A. 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 1-800-284-3172 1-781-272-8200
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 Index 149
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 Users Guide Part Number 40-03377-E0-001 October 2010

Virtuent User Guide Rel 7

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Virtuent User Guide Rel 7

Uploaded by

Copyright:

Available Formats

User Guid rs de

Part Number 40-03377-E P r E0-001

26 Crosby Driv Suite 100 ve, 0

Table of Contents iii

About This Publication

Who Should Use This Publication

How to Use This Publication

About This Publication v

What is Included in This Publication

vi Virtuent Users Guide

About This Publication vii

Chapt 1. In ter ntroduct tion

Tape Volume es on Disk k

Chapte 1. Introdu er uction 1

2 Virtuent Users Guide

MDL Installation and Configuration

Working with Configuration Files

Figure 1-2. Configu e uration Panel ls

Figure 1-3. Creating a N Configur New ration

4 Virtuent Users Guide U e

Figure 1-4. Editing a New Configu 1 uration File

Fig gure 1-5. Savi a Configu ing uration

Chapte 1. Introdu er uction 5

Figure 1-6. Showing Inst talled Configu uration

6 Virtuent Users Guide U e

Chapter 2. Defining the Virtual Tape Library

Chapter 2. Defining the Virtual Tape Library 7

/tapelib /DISK1 /DISK2 /DISK3 /DISK4

Figure 2-1. Virtual Library Architecture

/tapelib /DISK1 /DISK2 /DISK3 /DISK4

Figure 2-2. Storage Classes

Chapter 2. Defining the Virtual Tape Library 9

Definin Filesyst ng tems

Figure 2-3. S Storage Definit tion

Chap 2. Defin the Virt Tape Li pter ning tual ibrary 11

12 Virtuent Users Guide

Chapter 2. Defining the Virtual Tape Library 13

Figure 2-4. Adding an NFS Filesyst n tem

Figure 2-5. Adding a Fibr Channel Fil A re lesystem

14 Virtuent Users Guid de

Definin the Libr ng rary to be Used by a Node

re ng Figur 2-6. Definin Storage to the Node

Chap 2. Defin the Virt Tape Li pter ning tual ibrary 15

D Defining th Lock Directory he D

Figure 2-7. Global Option on the Devic Panel G ns ce

1 Virtuent Users Guid 16 de

Fig gure 2-8. Free e-Form Param meters

Backwa Comp ard patibility

Chap 2. Defin the Virt Tape Li pter ning tual ibrary 17

18 Virtuent Users Guide

Chapter 3. Configuring Virtual Devices

Chapter 3. Configuring Virtual Devices 19

Figure 3- Device Con -1. nfiguration Pa anel

Figure 3-2. Add ding a Contro Unit ol

Chapter 3. Configuring Virtual De g evices 21

Figure 3-3. Add devi ices Paramete ers

22 Virtuent Users Guid de

Chapter 3. Configuring Virtual Devices 23

24 Virtuent Users Guide

Chapter 3. Configuring Virtual Devices 25

Fig gure 3-4. Curr rent devices

Chapter 3. Configuring Virtual Devices 27

Figure 3- Defining S cratch Synony -5. yms