Virtuent User Guide Rel 7

26 Crosby Driv

P

ve, Suite 100

UserPart Number

0 · B

r’s Guidr 40-03377-E

Bedford, MA

de

E0-001

A 01730 · (781)2772-8200

Bus-Tech Virtuent User’s Guide Part Number 40-03377-E0-001 October 2010

© Copyright 2010 by BUS-TECH, INC. 26 Crosby Drive, Suite 100 Bedford, MA. 01730 Voice: (781) 272-8200 Fax: (781) 272-0342 All Rights Reserved.

The information contained in this document is proprietary.

Duplication of this document or any part thereof should be undertaken only with the written permission of Bus-Tech, Inc.

Acknowledgments: Bus-Tech, Mainframe Data Library, and Virtuent are trademarks of Bus-Tech, Inc.

Ethernet is a registered trademark of Digital Equipment Corporation, Intel® Corporation and Xerox Corporation.

IBM, System/390, and OS/390 are registered trademarks of International Business Machines, Inc.

Other names are used herein for identification purposes only and may be trademarks of their respective owners.

Table of Contents i

Table of Contents About This Publication ....................................v Who Should Use This Publication .....................v

How to Use This Publication .............................v

What is Included in This Publication ............... vi

New in Revision C0 ......................................... vi

New in Revision D0 ......................................... vi

New in Revision E0 ........................................ vii

Chapter 1 . Introduction.................................1

MDL Installation and Configuration .................3

Working with Configuration Files .....................3

Chapter 2 . Defining the Virtual Tape Library ..............................................................7 Overview ............................................................7

Storage Classes ..............................................8 Supporting Multiple Libraries .....................10 Lock Filesystem ...........................................10 Defining a Virtual Tape Library ..................11

Defining Filesystems .......................................11

Defining the Library to be Used by a Node .....15

Defining the Lock Directory ............................16

Backward Compatibility ..................................17

Chapter 3 . Configuring Virtual Devices .....19 Global Options .............................................19 Adding Devices ............................................21

Scratch Synonyms ............................................26

Saving your Configuration ...............................29

Activating (Installing) a Configuration ............29

Chapter 4 . Using Virtuent with z/OS, OS/390, or MVS .............................................31

Mainframe Utilities ..........................................31

Configuring the Devices ..................................32 Real 3480/3490/3590 ...................................32

Manual Tape Libraries .................................33 MTL-Related IBM maintenance ..................35

Bus-Tech’s Unit Information Module .............35

Virtuent Scratch Utility Program .....................37 VTSCR Parameters ......................................38 RMM Considerations ...................................41 TMS (CA-1) Considerations ........................41 TLMS Considerations ..................................42 TSM Considerations ....................................42

VTCMD Utility Program .................................42

DFSMShsm Considerations .............................44

Specifying Tape Compaction ...........................45

Missing Interrupt Timer ...................................45

Dynamic Device Reconfiguration (DDR) Considerations..................................................46

DR Logging .....................................................46 Enabling DR Logging ..................................47 Retrieving the Still In Use Report ................48

GENSTATS Reports ........................................48 Sample Reports ............................................52

Chapter 5 . Using Virtuent with VSE..........55 Overview ..........................................................55

Configuration Parameters Unique to VSE .......55 Global ...........................................................55 Device Specific ............................................56

VSE Programs ..................................................56

VSE Sample Jobs .............................................57

Tape Drives ......................................................57

VIRMOUNT Utility.........................................58

VIRMAINT Utility ..........................................59

Dynam/T Support.............................................59

VIRSSD Utility for Dynam/T Operation .........60

Dynam/T Message Exit ....................................61

ii Virtuent User’s Guide

Using Dynam/T ................................................62 Create New Tape Data Sets .........................62 Prepare a Scratch Pool .................................62 Volume Scratching and Erasing with Dynam/T ......................................................63

BIM-EPIC ACL Support .................................64

VIRSSE Utility for EPIC Operation ................65

Using CA-EPIC or BIM-EPIC .........................66 Creating New Tape Data Sets ......................68 Volume Scratching and Erasing with EPIC .68

All Environments .............................................69 Multiple VSE Images ...................................69 Specifying Tape Compaction .......................69 Sending Console Commands and Running Scripts from VSE .........................................69

Chapter 6 . Using Virtuent with VM ........73 Installing VTSCR and VTCMD ......................73

VTSCR .............................................................74

VTCMD ...........................................................77 Using VTCMD to Mount a VOLSER .........78

Chapter 7 . Using Virtuent with Unisys ......79

Unique Virtuent Operations for Unisys Mainframes ......................................................79

Autodetection ...............................................79 Load Displays ..............................................79 Mount “Ready” Interrupt .............................79 Query Config command ...............................79 Ring-Out Mount Request .............................79 Scratch Request ............................................80

Configuring for Unisys ....................................80

Device Type .....................................................80 Labels ...........................................................80 Scratch Tapes ...............................................80

Initializing Tapes for Unisys ............................81

Configuring the Mainframe for Virtuent .........81

Chapter 8 . System Operation......................83 VT Console ......................................................83

Starting / Stopping Tape Devices ....................85

Initializing Scratch Volumes............................86

Virtual Tape Operator Commands ...................87 Command Syntax .........................................88 EXPORT Command ....................................88 FIND Command ..........................................88 HELP Command ..........................................88 IMPORT Command .....................................89 INITIALIZE Command ...............................89 LOAD Command .........................................90 QUERY Command ......................................91 QUIESCE Command ...................................92 READY Command ......................................92 RESET CHANNEL ADAPTER Command 93 REWIND Command ....................................93 SAVE TRACE Command ...........................93 SET Command .............................................94 SHOW Command ........................................96 STOPVT Command .....................................96 STARTVT Command ..................................97 STOP CHANNEL ADAPTER Command ..97 UNLOAD Command ...................................97 UNQUIESCE Command .............................98 UNREADY Command ................................98

Reboot a Controller ..........................................98

Set Date and Time ............................................99

Virtuent Messages ..........................................100 Configuring SNMP Message Notification .100 Sending E-mail ..........................................101 Sending Vendor E-Mail (Phone Home) .....102 Configuring Messages to be Sent ..............102 Viewing Message (Log) Files ....................104

User Administration .......................................105 LDAP .........................................................106

Chapter 9 . z/OS Console Operation ..........109 VTHHOST .....................................................109

Installing VTHHOST .................................110 Running VTHHOST ..................................110 VTHHOST Configuration File ..................111

Table of Contents iii

Using z/OS Console Support .........................112 VTHHOST Commands ..............................113 WTOR Command Examples .....................114

Chapter 10 . Using Data Encryption .........117 Connecting to the RSA Key Manager ...........120

Chapter 11 . Back-End Tape Support.......121 Direct Tape .....................................................121

Compression and Encryption .....................123

Tape Export / Import Utilities ........................124 Export .........................................................125 Import .........................................................126

Chapter 12 . Data Exchange ......................127 Configuration .................................................128

Virtuent Controller .....................................128 z/OS, OS/390 .............................................130 VSE ............................................................130 VM .............................................................130

Writing Flat Files ...........................................131

Reading Flat Files ..........................................131 z/OS and OS/390 .......................................131 VSE ............................................................132

Appendix A. Volume Handling ...................133 Volume Serial Numbers .................................133

Scratching Volumes .......................................134 Deleting ("Erasing") a Scratch Volume's Data ............................................................135

Mounting Volumes ........................................135 Mounting A Specific Volume by VOLSER135 Mounting a "SCRTCH" or "PRIVAT" Volume .......................................................136

End of Volume Conditions ............................137 Logical End of Volume ..............................137 Physical End of Volume ............................138 End of Data ................................................138

Error Conditions .............................................138 Mount Loops ..............................................138 Out of Disk .................................................139

Appendix B. AWSTAPE Information .......141

Appendix C. Load Display Command – CCW Opcode x’9F’ ......................................143 Load Display Data .........................................144

Format Control Byte (FCB) ...........................144

Help and Service Information.....................147 Step 1: Problem Solving ................................147

Step 2: Preparing for the Call .........................147

Step 3: Placing the Call ..................................148 Additional Technical Support Resources ..148

Index ..............................................................149

Customer Response ......................................151

About This Publication v

About This Publication This Guide provides the information necessary to Bus-Tech Mainframe Data Library controllers running the Virtuent tape-on-disk software..

The following terms may be used as synonyms for the PCI ESCON Adapter in this publication and in some software installation screens:

Bus-Tech PCI to ESCON Adapter

ESCON adapter

channel adapter

The following terms may be used as synonyms for the PCI FICON Adapter in this publication and in some software installation screens:

Bus-Tech PCI Bus to FICON Adapter

FICON Adapter

channel adapter

The following term is used as a synonym for the Mainframe Data Library throughout this publication:

MDL

Who Should Use This Publication

This publication is intended for the system administrator responsible for configuring a Mainframe Data Library running Virtuent tape-on-disk software to connect with a z/OS, OS/390, MVS, VM, or DOS/VSE mainframe.

How to Use This Publication

This publication is specific to the Virtuent tape-on-disk application and its use. Bus-Tech’s Mainframe Data Library (MDL) is a family of controller products for the IBM mainframe which are all built using Virtuent tape-on-disk technology. Documentation for MDL controllers consists of both an MDL Installation and Configuration Guide specific to an MDL model and this User’s Guide covering general configuration and use of Virtuent. The two manuals are used together to install, operate, and manage the MDL controller.

This publication is organized into distinct chapters. Refer to those chapters specific to completing the task(s) you are performing.

vi Virtuent User’s Guide

What is Included in This Publication

This User's Guide contains information on how to complete the following tasks:

Connect, define, and configure an NFS storage subsystem

Configure virtual tape devices

Configure the System/390 mainframe

Operate a Mainframe Data Library running the Virtuent tape-on-disk software

New in Revision C0

In addition to fixing minor typing errors, this revision includes the following changes:

1. A new device specific configuration parameter, VOL=, has been added. See page 25.

2. Sample JCL for installing GENSTATS has been added. See page 48.

3. A new GENSTATS parameter, SYNCTIME, has been added. Pages 49 and 51.

4. Additional DD statements needed when running GENSTATS with the STILLINUSE parameter have been defined. See page 50.

5. Sample GENSTATS reports have been added beginning on page 52.

6. Chapter 9 has been updated documenting the new NOWTOR parameter on the z/OS Started Task (VTHHOST) beginning on page 109.

7. Information was added explaining the use of read-only on library filesystems on page 13.

8. The TMS Considerations on page 41 were updated to correctly indicate the use of the DSN17 field in the TMS scratch reports.

New in Revision D0

Updated GENSTATS Reports section beginning on Page 48.

Updated VT Console section beginning on Page 83.

About This Publication vii

New in Revision E0

Updated page 6 with additional information on installing a configuration.

Updated page 7 to correct description of how Virtuent allocates a new VOLSER to a filesystem in the library.

Updated Storage Classes overview beginning on page 8.

Updated description on how to define a lock directory on page 16.

Enhance section on activating a configuration beginning on page 29.

Updated section on mainframe utilities beginning on page 31.

Update to CA-1 Considerations beginning on page 41.

Updated the SHOW command on page 96.

Updated Appendix A to accurately explain scratch volume allocation within a tape library.

Numerous minor edits throughout the manual.

Chapt

ter 1. InBus-Tor IBMusing softwaconneon mo3490, mainf(See F

The taa singcorrelacquirtape v

The da modbeing origin

Optionthe orapplic

VirtueTheseinterfa

ntroductTech’s MainfM-compatibla common tare runs on a

ections or onodel, Virtuenor 3590 tap

frame is storeFigure 1-1).

Figu

ape data is stgle file holdinlated to a volred from the

volume to be

default file fodified AWST

written so thnally written.

nally, data criginal data rcation can re

ent starts a ve virtual tapeace’s firmwa

tion frame Data Lle mainframtape-on-diska base hardw

ne, two, or thnt controllerse drives. Daed and retrie

ure 1-1. MDL

tored in diskng the data flume by the

e Load Disple mounted fo

ormat for virTAPE formahat variable .

can also be wrecord lengthead the data a

virtual tape tae tasks run coare, emulate

Library is a fmes and for Uk software paware controllhree ESCONs can emulatata written toeved from a d

Controller / N

k files that cofor one tape tape Volumay command

or reading or

rtual tape datat. This formlength recor

written as a phs, labels, anas a sequenti

ask on the coontinuously 3xxx-type t

family of tapUnisys OS22ackage knowler which pro

N connectionte 32 to two o or read frodisk subsyst

Node Stores T

orrespond tovolume. Th

me Serial Numd sent from tr writing.

ta written to mat keeps trards can be re

plain, sequennd tapemarksial dataset.

ontroller forand, in conj

tape drives in

Chapte

pe-on-disk c200. All MDwn as Virtuenovides one os to the mainhundred fift

om these tapetem attached

Tape Volumes

o physical vohe files are idmber (VOLSthe host whe

Virtuent conack of recordead exactly a

ntial (“flat”) s are lost, bu

each active unction withn every way

VOLSER 1

VOLSER n

er 1. Introdu

controllers foDL models arnt. The Virtor two FICOnframe. Depty six (256) 3e drives by td to the contr

on Disk

olumes of tapdentified andSER), whichenever it wan

ntrollers is wd lengths as tas they were

file. In this ut any open-s

virtual tape h the channe

y possible, by

Tape Volumeon Disk

uction 1

or IBM re built tuent

ON pending 3480, the roller

pe, with d h is nts a

written in the file is

format, system

drive. el y:

es k

2 Virtuent User’s Guide

• Receiving and interpreting channel commands (CCWs) from the host;

• Sending and receiving tape data records, and reading and writing corresponding disk data in response to the CCWs;

• Presenting initial, intermediate, and final status to the host commands, and asynchronous status as required;

• Sending and receiving control information (such as sense and load display data) to and from the host in response to the CCWs.

A virtual tape drive is in one of two basic states at any given time: Ready or Not Ready.

In the Not Ready state, the virtual tape drive appears to the host to be online but in an unmounted state. Most channel commands are not accepted in this state and will receive a Unit Check status with Intervention Required sense. While in the Not Ready state, no disk file is opened on the disk subsystem. The Not Ready state is the initial state of all virtual tape drives when Virtuent is activated, and is entered whenever an Unload command is received from the mainframe.

The Ready state is entered when the virtual tape drive receives a load request from the host. For z/OS the Ready state is entered when a mount message is received on the virtual tape drive. For VSE systems Bus-Tech supplies a VSE-based application to detect mount messages on the VSE operator console and forward them to a Virtuent controller.

When the Mount message is received, the disk file associated with the volume specified in the Mount message is opened, and the virtual tape drive comes Ready to the host. The virtual tape drive remains in the Ready state, with the associated disk file open, until an Unload command is received from the host, at which time the disk file is closed and the virtual tape drive enters the Not Ready state.

While in the Ready state, the virtual tape drive will accept all data movement, read, and write commands from the host exactly as would an actual 3xxx tape drive. As the host reads and writes and otherwise positions the virtual tape, the application will maintain synchronization of the associated disk file to exactly match the content and positioning of the virtual tape volume.

Chapter 1. Introduction 3

MDL Installation and Configuration

Installing a Mainframe Data Library tape-on-disk controller involves several steps including:

1. Unpacking and installing the MDL hardware.

2. Connecting the MDL to mainframe channels and a disk subsystem.

3. Defining the disk subsystem to the Virtuent controller(s).

4. Configuring the virtual tape drives.

5. Configuring the tape drives in the System/390 operating system.

6. Configuring VSE interface applications (VSE only).

7. Activating the Virtuent tape drives.

8. Initializing the virtual tape volumes.

9. Verifying the installation and configuration.

Steps 1 and 2 of this process are specific to the MDL model being installed. These steps are discussed in the model specific manual that accompanied your MDL. Steps 3 through 8 focus on configuring the individual Virtuent controller and are the topics of this manual. Step 9 is completed by running test jobs on your mainframe writing and reading from your MDL.

Please refer to the MDL installation guide to complete steps 1 and 2 of the installation process. Then once you have the MDL to the point where you are ready to configure the virtual tape library and tape devices you can continue through the remainder of this manual.

Working with Configuration Files

An HTML-based configuration application is used to configure Virtuent. To access this application you will need a PC / laptop with a Java capable web browser such as Microsoft Internet Explorer or Mozilla Firefox.

To access the configuration application you simply open your web browser and enter the IP address of your Virtuent controller. Refer to the hardware installation guide that accompanied your controller to determine the default IP address.

Once connected, you will be prompted for a User id and Password for the system. The default Userid is “admin”. The default password is “password”.

The default configuration file used by the configuration program is “config”. If you simply access the Virtuent configuration application and begin modifying the configuration you will be working with this default configuration file. Optionally,

44 Virtuent U

User’s Guide

you can cas many cbe the act

To select Virtuent C

By defaulconfigura(Figure 1-

You will napplicatio

e

reate and usconfigurationtive configur

a configuratConfiguratio

lt the configuation file type-3).

now be edition will displa

e your own n files as youration at any

tion file to won (Figure 1-

Figure

uration file ue in a name

Figure 1-3

ing the new ay the config

configuratiou want. How

y point in tim

work with go-2).

e 1-2. Configu

used will be in the config

. Creating a N

configuratioguration file

on files. Virtwever, only

me.

o to the Conf

uration Panel

‘config’. Tguration na

New Configur

on file. The name in the

tuent will alone configu

figurations

ls

To create youamed field an

ration

Virtuent Coe heading are

low you to suration file w

panel on

ur own nd click New

onfiguration ea (Figure 1-

store will

w

-4).

Refer configmust s

After button1-5).

Savinthe acInstal

To inswill o

WARrunni

to subsequeguration optisave the cha

making youn should nowClick the Sa

g the configuctive (last insll button is c

stall the selepen showing

RNING! Ining when th

Figure 1

ent chapters iions. Once y

anges and ins

ur changes rew be active; iave changes

Fig

uration will stalled) confclicked.

cted configug the status a

multiple nohe install but

1-4. Editing a

in this manuyou have finstall it before

eturn to the Cindicating thbutton to sa

gure 1-5. Savi

not automatfiguration, th

uration click and results o

ode configutton is click

a New Configu

ual for informnished creatine it will be u

Configuratiohe configuraave your con

ing a Configu

tically instalhe new chang

k the Install bof installing y

rations all nked.

Chapte

uration File

mation aboutng your new

used by the V

ons panel. Tation has beenfiguration.

uration

l it. Even if ges will not

button. An your configu

nodes must

er 1. Introdu

t the variousw configuratiVirtuent cont

The Save chen modified (

f you have mtake place u

Apply log wuration.

be powered

uction 5

s ion you troller.

hanges (Figure

modified until the

window

d on and

66 Virtuent U

User’s Guide

WARNINonline, wMainframdevices emconfigura

Once a coInstallati(Figure 1-used by th

e

NG! Clickinwill cause theme devices amulated by ation file.

onfiguration ion” field sh-6). The lashe system.

ng Install we controllerare likely tothe entire M

has been insowing the nast configurat

Figure 1-6.

while a Virtu(or control

o be boxed. MDL are va

stalled the Came of the ction file insta

Showing Inst

uent Controllers) to tem It is strong

aried offline

Configurationconfigurationalled is the a

talled Configu

oller is activmporarily gogly recomme prior to in

n panel with n file that waactive config

uration

ve, with devio down. On

mended that nstalling a n

display a “Las installed lguration bein

ices nline

all ew

Last last ng

Chapter 2. Defining the Virtual Tape Library 7

Chapter 2. Defining the Virtual Tape Library This chapter discusses how to define and manage the disk storage used as the virtual tape library behind a Virtuent-based controller.

Overview

The Virtuent tape-on-disk software supports a variety of different types of open-systems storage. Depending on the Mainframe Data Library (MDL) model, your MDL controller may support one or more of the following types of storage within the virtual library:

– IP attached Network File System (NFS) version 3 – Fibre Channel attached Storage Area Network (SAN) storage – Fibre Channel attached Virtual Tape Library (VTL) – IP attached compliant storage

This manual discusses how to define and configure virtual libraries which are disk based; either Network Filesystem (NFS) or fibre channel SAN disk storage. Configuration of fibre channel attached VTL storage or IP attached compliant storage is covered in separate Virtuent documents specific to the storage option your MDL system supports.

A Virtuent Tape Library is normally defined using more than one filesystem. Logically, an open-systems filesystem can be thought of as a single disk. If you are using a Network Attached Storage (NAS) device, for example, than each filesystem is a single NFS export defined on the NAS device for use by Virtuent. If you are using fibre channel storage, then each filesystem is a logical unit (LUN) defined on the fibre channel storage for use by Virtuent.

To provide the best overall performance, especially in FICON environments, multiple filesystems in each library are desirable. And, while there is no strict limitation, a minimum of four (4) filesystems is recommended. When multiple tape volumes are being written from the mainframe to the library, Virtuent will randomly allocate each tape to one of the filesystems in the library in order to balance output across all filesystems in the library.

A virtual tape library is controlled by a top level directory stored on the Virtuent controller’s system disks. Each filesystem to be used as part of the tape library must be defined and mounted as a subdirectory within that top level directory. Virtuent will automatically use all filesystems mounted under the top level directory to store tape volumes. The sample library shown in Figure 2-1 is made up of four filesystems (disks). The virtual tape library is identified by the top level directory named “tapelib”. The four sub-directories defined within tapelib, ‘DISK1’, ‘DISK2’, DISK3’, and ‘DISK4’, each point to a filesystem to be included in the virtual tape library.


The top level tape library name can be made up of any combination of alpha numeric characters. Sub-directories within the tape library must be named using uppercase Alpha characters (A-Z) and numbers only. For example: A0, BB, 00, 01, AA1, and DISK1 would all be valid sub-directory names within tapelib. However, a0, 0b, ab, and disk1 would all be invalid.

Hundreds of thousands of serial numbers can be stored in a Virtuent library. Virtuent will continue to store VOLSERs into each filesytem within the library until space within the filesystem is depleted. Additional filesystems can be added to the library at any time without disrupting the operation of the library. Once a new filesystem is available Virtuent will automatically begin making use of it when creating new tape volumes.

Figure 2-1. Virtual Library Architecture

Individual tape volumes do not span filesystems. Each tape volume (VOLSER) is stored as a single file on one filesystem. Should a filesystem run out of space while writing a VOLSER, the mainframe will receive an end of tape indication on the tape volume. However, since multi-volume datasets are written to more than one tape volume (VOLSER), datasets that span multiple volumes are very likely to spread across more than one filesystem in the library.

Individual VOLSERs can move from one filesystem to another within the virtual library. Like real tape volumes, virtual volumes are written, read, and scratched. Once a VOLSER has been scratched within the library, it can be re-used during a future tape allocation process. When a previously scratched VOLSER is reallocated, it may be moved by Virtuent to a different filesystem within the library.

Storage Classes

Virtuent libraries allow for multiple storage classes to be defined. Each filesystem defined to a virtual library is assigned to one and only one storage class. By default, if you do not configure a different class, any filesystem you define will be assigned to the default storage class 0. During allocation of a new tape volume (VOLSER) the user may use scratch synonyms to specify which storage class a VOLSER should be

/tapelib /DISK1 /DISK2 /DISK3 /DISK4

Each Logical Disk represents a single NFS Export or a single Fibre Channel LUN


stored in. Only filesystems assigned to the requested storage class will be candidates to receive the volume.

Returning to the library pictured in Figure 2-1, if the four filesystems are all defined with the default storage class 0, then the library will treat all four filesystems equally; randomly allocating new VOLSERs to any of the four filesystems with enough space to hold the cartridge as defined by the SIZE= parameter on the device writing the file.

Figure 2-2. Storage Classes

In Figure 2-2, DISK1 and DISK2 are assigned to the default storage class 0. But DISK3 and DISK4 are assigned to storage class 1.

All Virtuent controllers recognize the names ‘SCRTCH’ and ‘PRIVAT’ as a request for a scratch tape. When the controller receives a load CCW with either of these names it will, by default, randomly allocate a new tape volume to one of the filesystems defined to class 0. In the example shown in Figure 2-2, any request for SCRTCH or PRIVAT would result in the tape being placed on DISK1 or DISK2.

To allow tapes to be allocated to storage class 1 (DISK3 and DISK4 above) a scratch synonym (name) needs to be associated with that storage class. For example, to new tapes to be allocated to storage class 1, the default configuration for the synonym ‘PRIVAT’ could be modified to assign it to Class 1 (i.e. PRIVAT=CLASS=CLASS1).

Once PRIVAT has been associated the storage class 1, any job requesting a new tape by coding JCL specifying VOL=SER=SCRTCH will be allocated a VOLSER that will be stored on either DISK1 or DISK2. JCL specifying VOL=SER=PRIVAT will be allocated to a VOLSER that will be stored on DISK3 or DISK4.

Storage classes provide a convenient way to isolate or group tape volumes together within the library. For example, storage classes provide an easy way to isolate DR tapes that you want to replicate to a remote location from work tapes that only need to be kept locally. Continuing with the storage class definitions given above, DISK1

/tapelib /DISK1 /DISK2 /DISK3 /DISK4

Storage Class 0

Storage Class 1


and DISK2 may be local filesytems that are never replicated. DISK3 and DISK4 may be defined as part of a group of disks that get asynchronously replicated over an IP network to a remote disaster recovery site. Any tape volume allocated as ‘PRIVAT’ will be replicated to the DR site. Any tape volume allocated as ‘SCRTCH’ will not be replicated.

Virtuent randomly allocates new tape volumes to any filesystem within the desired storage class; checking to make sure there is enough space in the filesystem to hold the volume. This tends to spread new VOLSERs across all the filesystems within a storage class. If you expect to have many tapes being processed against the same storage class concurrently, you should define multiple filesystems to that class in order to spread the I/O across multiple filesystems and/or disks.

Scratch tapes are class specific. If you define multiple storage classes you will need to initialize scratch tapes (see page 86) into each storage class. Virtuent will move scratch volumes between filesystems within storage class by will not move scratch volumes from one storage class to another.

Supporting Multiple Libraries

Virtuent tape-on-disk software allows definition of more than one virtual tape library within an MDL controller. Creating multiple top level directories on an MDL controller defines multiple independent virtual tape libraries. For example, if you wanted two separate libraries, you might define top level directories /tapelib and /tapelib2.

Each virtual tape library must have its own filesystems (disks) mounted underneath the top level directory as shown in the previous examples. Virtuent software will not allow tape volumes (VOLSERs) to be written to the tope level directory which resides on the MDL system disks.

Each tape drive configured on an MDL controller is permanently connected to one and only one tape library. Suppose, for example, you have defined 2 libraries, /tapelib and /tapelib2. You then configure 32 tape drives. Each of these 32 drives may be individually connected to one of the two libraries. So, for example, you may connect drives 1 – 16 to /tapelib and drives 17 – 32 to /tapelib2.

On the mainframe, if you configure all 32 drives within the same LPAR, you must take care to isolate them into two libraries in order to prevent a mount request on a drive that cannot access the correct virtual tape library.

Lock Filesystem

In addition to defining filesystems (space) to the virtual tape library (or libraries), Virtuent also requires a small filesystem to use as a lock directory. This filesystem must be separate from the filesystems making up your virtual tape library (libraries). When multiple Virtuent controllers (nodes) are sharing a virtual library the lock filesystem must be resident on shared (NFS or fibre channel) storage that all controllers (nodes) can access.

Defining

Definin

Only omay b

The lofor ou10 MB

g a Virtual T

Thereor fibr

1. 2. 3. 4.

Steps once Vdiscus

ng Filesyst

As a mto useintendone fi

To dethe wethe St

The Snumb

one lock filebe defining to

ock filesytemutput. ThereB filesystem

Tape Librar

are four stere channel st

Define the

Define the

Identify th

Initialize s

1 - 3 will beVirtuent is russed in detai

tems

minimum, yoe as a lock did to define. Alesystem to

fine a new feb browser otorage panel

Storage paneler of nodes (

esystem is reo the Virtuen

m is only usefore, the size

m is generally

ry

ps required ttorage and b

e filesystems

e library or li

he lock direc

scratch tapes

e discussed iunning in at l in Chapter

ou will needirectory and As previouseach library

filesystem toon your PC /(Figure 2-3)

l has two or (controllers)

Chap

equired regarnt controller

ed during thee of the locky all that is re

to successfubegin using it

s (disks).

ibraries to be

tory to Virtu

s (VOLSERs

n this chapteleast one co8 beginning

d to define onat least one ly discussedin order to m

Virtuent ac/ laptop. On).

Figure 2-3. S

more tabs; d) within the c

pter 2. Defin

rdless of howr(s).

e process of k filesystem equired.

ully define a t. The steps

e used by ea

uent.

s) into the lib

er. Step 4, inontroller (nodg on page 86

ne small (10filesystem f

d, Bus-Tech rmaximize pe

cess the Virtnce connecte

Storage Definit

depending onconfiguration

ning the Virt

w many virtu

allocating a (directory) c

Virtuent taps are:

ach MDL no

brary.

nitializing tade). Tape in

6.

MByte) filefor each virturecommenderformance.

tuent configed, click on S

tion

n the MDL mn. For singl

tual Tape Li

ual tape libra

new scratchcan be very s

pe library usi

de (controlle

apes, must bnitialization i

esystem for Vual tape libras defining m

guration paneStorage to d

model and thle controllers

ibrary 11

aries you

h volume small. A

ing NFS

er).

e done is

Virtuent ary you

more than

els using display

he s there


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

114 Virtuent

User’s Guid

filesysto dire

Filesythis stwhereShare

Figureconfig“/tapeidentiaddresNFS smeans

Figure 2-5filesystem

You may next butto

de

stem read-onect new tape

ystem – this torage (disk)e the library d SAN Stora

e 2-4 shows guration. Aselib/DISK1” fied by “/tapss 192.168.1server is “diss it is genera

5 shows an em.

add any numon.

nly you muse volumes to

field allows). For fibre is not sharedage configur

an example s shown, the implying th

pelib”. The a1.20. The exsk1”. This fal storage no

Figure 2

example of a

Figure 2-5. A

mber of files

t make sure filesystems

s you to selecchannel stor

d, Bus-Tech rations you m

adding an Nnew filesys

his filesystemactual storag

xport name bfilesystem is t assigned to

-4. Adding an

adding a fibr

Adding a Fibr

systems to th

to use scratcnot configu

ct the type orage on a sinrecommend

must select O

NFS filesystetem will be

m is part of thge is locatedbeing used to

defaulting to a specific c

n NFS Filesyst

re channel L

re Channel Fil

he available

ch synonymured as read-o

of filesystem ngle Virtuentds selecting eOCFS/2.

em to the stomounted at the virtual tap

d on the NFSo export the to storage claclass.

tem

LUN using th

lesystem

storage by c

s (see page 2only.

to be used ot controller ext3. For M

orage the mount ppe library

S server at IPstorage on thass 0, which

he OCFS/2

clicking the A

26)

on

MDL

oint

P he

h

Add

Definin

ng the Libr

Becauoperattape li

On thesingleconfig(contrit defi

Once to the storagmanua

Simplshowsdefine

You maccessall fou

If muldiffere

If youconnesure to

Warnsure tinclud

rary to be

use some Mating nodes, tibraries are t

e storage pane MDL contrguration panroller) there wines.

you have senode will be

ge on the “aval to define s

ly click the cs a sample coed with 4 file

must always sing a libraryur filesystem

ltiple librarieent libraries.

u are definingected to one lo include bo

ing: If you that all nodedes 4 filesyst

Used by a

ainframe Datthe second stto be used by

nel, select throllers there els in this uswill be mult

lected a node displayed.

vailable” tabstorage to V

check boxes onfigurationesystems alo

connect the y, then it sho

ms have been

es are define.

Figur

g multiple lilibrary and o

oth library’s

are defininges / controlletems and an

Chap

a Node

ta Library mtep of storagy devices on

he tab for thewill only beser’s guide. tiple tabs wit

de (controller If nothing . Follow insirtuent.

for the storan where a sinong with the

lock fileysteould always n selected for

ed, then you

re 2-6. Definin

braries and wother tape drstorage in th

g a library aers include another only h

pter 2. Defin

models includge configuratn each Virtue

e controller ye one tab; lab

For MDL mth each tab i

r) to configuis displayed

structions in

age you wanngle virtual t

lock filesyst

em to all nodaccess all dir use by the

may configu

ng Storage to

want the conrives to be cohe node (con

across more all the same has the first

ning the Virt

de multiple, tion is to defent controlle

you wish to beled “localhmodels with indicating th

ure a list of ad, then you hn the previou

nt this node ttape library (tem.

des. Additiisks in that lMDL contro

ure different

the Node

ntroller to haonnected to

ntroller) conf

than one nofilesystems.

t 3, then the

tual Tape Li

independentfine which ver.

configure. Fhost” in the smore than o

he name of th

all storage avhave yet to dus section of

to use. Figur(tapelib) has

ionally, if a nibrary. As soller.

t nodes to co

ave some tapa second libfiguration.

ode / control. If one consecond cont

ibrary 15

tly virtual

For sample one node he node

vailable define

the

re 2-6 been

node is shown,

onnect to

pe drives rary, be

ller be ntroller troller

1

D

16 Virtuent

Defining th

User’s Guid

will be unthe fourth

Repeat th

he Lock D

The final filesystemtape volumshould be

The samelibrary. T

The lock VOLSERGlobal op

To defineparametescreen. Th

VOLS

Where “/ldirectory chapter).

de

nable to acceh filesystem.

e storage sel

Directory

step to confm (disk) to usmes. Theref

e plenty rega

e lock directoThe same loc

directory is RLOCKDIR.ptions on the

e the lock dirers”. Then ehe format of

SERLOCKD

lockdir/disknon the Avail

ess tape volu.

lection proce

figuring a Vise as the locfore, the file

ardless of how

ory MUST bck directory

identified to This param

e node Devic

Figure 2-7. G

rectory clickenter the lockf the lock dir

DIR /lockdir/

name” is thelable storage

umes (VOLS

ess for each

irtuent librark directory. system can bw big a libra

be defined tocan be used

o Virtuent wimeter is definces panel (Fi

Global Option

k on the hypek directory prectory param

/diskname

e mount poine panel (see

SERs) writte

node (contro

ry storage is This filesysbe small in sary you are d

o each node afor more tha

ith a global pned as an addigure 2-7).

ns on the Devic

erlink “clickparameter intmeter is:

nt you previo“Defining F

en by the firs

oller) in you

to tell Virtustem will nosize. 10 MBdefining.

accessing a van one virtua

parameter caditional para

ce Panel

k to add free-to the free-fo

ously definedFilesystems”

rst controller

ur configurat

uent which ot be used to Bytes of stora

virtual tape al tape librar

alled ameter under

-form orm area on

d for the loc” earlier in th

r into

tion.

store age

ry.

r the

the

k his

Backwa

Figurefilesys

ard Comp

Custocontrocontro

To opdefineVOLScontrowith V

Keep compaforce.the firFilesyfilesyscan be

If youthat yofull ad

e 2-8 shows stem located

patibility

mers installioller environoller in comp

perate in come a lock direcSERLOCKDoller (node) wVirtuent soft

in mind thatatibility mod Specificallrst 2 characteystems are gestems addede used.

u are definingou define a ldvantage of t

an example d at mount po

Fig

ing a Virtuennment with apatibility mo

mpatibility mctory filesys

DIR parametewill assume tware older t

t if the Virtude then the ry, each filesers of the VOenerally rest

d to the librar

g a new MDlock directorthe Virtuent

Chap

where the looint ‘/lockdi

gure 2-8. Free

nt 7 (or highan earlier verode.

mode using anstem in the cer has not bethat the virt

than release

uent controlleestrictions o

system must OLSERs thatricted to 10,ry must have

DL virtual tapry filesystem7 enhanced

pter 2. Defin

ock directoryir/lock’.

e-Form Param

her) based corsion of softw

n existing vionfigurationeen defined tual tape libr7.0.

er (node) is rof the previou

be defined (at will be sto,000 VOLSEe VOLSERs

pe library Bum as described filesystem a

ning the Virt

y has been d

meters

ontroller intoware can op

irtual libraryn. When theon a control

rary is an exi

running in bus library ar(mounted) in

ored in that fiERs per filess initialized i

us-Tech stroed in this maarchitecture.

tual Tape Li

defined as th

o an existingerate their n

y, you simplye ler (node), thisting library

backward rchitecture arn the library filesystem. system and ninto them be

ongly recommanual in orde.

ibrary 17

he

g multiple ew

y do not

he y created

re all in using

new efore they

mends er to take


If you must run in compatibility mode because of existing controllers, please refer to the Virtuent User’s Guide, part number 40-03208-xx-001 for documentation on the earlier generation library architecture.

Chapter 3. Configuring Virtual Devices 19

Chapter 3. Configuring Virtual Devices Once the tape library has been defined you are ready to begin configuring your virtual tape devices. Depending on your controller model, you will be able to define up to some number of virtual 3480/3490/3590 tape drives on each Virtuent controller (node). MDL model 100 controllers, for example, allow a maximum of 32 devices to be configured. MDL 1000, 2000, 4000, and 6000 all allow up to 256 devices to be configured per controller (node).

For z/OS systems you should plan for one virtual device that will be offline all the time that can be used by Bus-Tech supplied z/OS utilities to communicate with the MDL. Additionally, if you plan to run the Virtuent z/OS started task, you should plan for one virtual device per node (controller) that will remain offline and be used by the started task to communicate with the node / controller.

For VSE/ESA systems with tape management software installed you should define one virtual tape drive for control. This drive will be used to receive Load Display Mount messages and will not be available for use by applications. So, for example, if you define sixteen (16) tape drives only fifteen (15) will be useable by your applications. For BIM-EPIC environments, read the “BUSTECH MAS Support” section of the “BIM-EPIC Installation and System Guide” before configuring any virtual tape drives.

Virtuent device configuration is done using the Devices panel of the Virtuent configuration utility (See Figure 3-1).

Global Options

At the top of the Devices panel are Global options that can be set for the entire Virtuent Controller. These parameters include:

Warn at – Sets the percentage of disk space usage at which Virtuent will begin to warn about usage. Each time the contents of a filesystem changes Virtuent will check the space used against this value. If the used space in the filesystem is above this value a warning will be issued. The valid range is 0 to 100. The default is 75%.

Start space recovery at – Sets the percentage of disk space usage at which Virtuent automatically starts to recover disk space by deleting the data from scratch volumes (see page 135, “Deleting ("Erasing") a Scratch Volume's Data”). Valid values are from 0 to 100. The default is 95%. If the recovery percentage is set to 100, Virtuent will never automatically delete scratch volume data to recover disk space.

220 Virtuent

User’s Guid

Recovspace space erasedto 100filesys

Tape exportIBM 3Virtuecopy (TS112volumcontroetc). check

Writecontrocontrobackwa newvolumcontroinstall“Allow

de

ver amount it will contihas been rec

d. Valid valu0 will cause Vstem once th

export enabt / import uti3592 or TS1ent controlle(export) a ta20 cartridge

me (VOLSERoller and are By default t

kbox will ena

e compatibiloller needs bollers. By deward compat

w Virtuent comes with oldeoller can be rlations, wherw new featu

(1-100) – Wnue erasingcovered or uues are 1 to Virtuent to e

he start space

Figure 3-

bled – indicailities. Virt120 tape dri

er, export / imape volume (

or copy (imR) in the Vir

outside of athese utilitieable the Exp

lity – the wrbackward comefault, Virtutible with preontroller can er Virtuent cread by othere no existinures but lose

When Virtuendata from sc

until there ar100. The deerase the date recovery v

-1. Device Con

ates whethertuent controlive. When amport utilitieVOLSER) f

mport) a physrtuent libraryany mainframs are disableort / Import

rite compatibmpatibility went is configevious versiobe installed

controllers. er, older Virtng Virtuent ce backward

nt starts to aucratch volume no more scefault is 1%.ta from all scvalue has bee

nfiguration Pa

r or not this llers allow pha real IBM dres are availabfrom the librsical 3592 / Ty. These utilme security ped. Checkinutilities.

bility field inwith previougured so thatons of Virtuinto an exisSpecificallytuent based ccontrollers exd compatibil

automaticallymes until thiscratch volum. Setting reccratch volumen reached.

anel

controller ishysical attac

drive is attachable on the corary to a phyTS1120 cartrlities are exeprograms (R

ng this config

ndicates wheus generationt it will write

uent. This desting library y, volumes wcontrollers. xist, this optlity”. This w

y recover diss amount of mes that can covery amou

mes on this

s to provide chment of anhed to the ontroller tha

ysical 3592 / ridge to a tapecuted on the

RACF, ACF/guration

ether or not tn Virtuent e data that isefault insuresand share ta

written by thi For new

tion can be swill allow th

sk free be unt

n

at will

pe e /2,

this

s s that

ape is

set to he

Adding D

coco

Adpathcliin

See palibrari

Devices

Belowunits syou bemainf

The ficonfigvalid cthe cocontro

ontroller to taontroller.

dditional paarameters deat can be maick on click clude:

VOLSERfilesystempreviouslypage 11) a

age 16 for a ies.

w the global section and tegin the proc

frame by this

irst step to dguration. Ascontrol unit

ontroller. Fool unit value

ake full adva

arameters –scribed abovanually enterto add free-f

RLOCKDIRm to be used by defined to Vas well as bei

full descript

options sectthe Scratch scess of defins node / cont

efining devis shown in Fnumber and

or ESCON vas are 00-FF.

Fi

antage of all

– In addition ve there are gred into the c-form param

R /mountpoinby the controVirtuent on ting selected

tion on defin

ion of the desynonyms sening virtual ttroller.

ces is to addFigure 3-2, a d selecting a alid control Click the “

gure 3-2. Add

Chapter 3.

l features of

to the pre-dglobal free-fconfiguratio

meters. Curr

nt – defines oller. The mthe Availablon the node

ning a lock d

evices panel ection. The tape devices

d one or mornew controldevice type unit values a

“+” button to

ding a Contro

Configuring

the current g

defined globaform configu

on. To add arent free-form

the location mount point mle tab of the e storage pan

directory for

are two sectControl unit

s (drives) to b

re controllersl unit is addefor the deviare 00-0F. Fo complete th

ol Unit

g Virtual De

generation V

al configuraturation parama free-form pm parameter

of the lock must have bestorage pane

nel.

each of you

tions; the Cots section is be emulated

s to the ed by enterinces to be defFor FICON vhe add.

evices 21

Virtuent

tion meters

parameter rs

een el (see

ur virtual

ontrol where

d to the

ng a fined on valid

222 Virtuent

User’s Guid

The contrdefined th

The param

Contrdevice

Add ayou w

Initiadevicemainfrange device0F andE900,long.

Tape the lisStoragStorag

de

rol unit will bhe Add devic

meters you c

rol Unit - Thes on.

address ranwish to add to

al device name. Bus-Techframe operatof devices b

e. For examd you enter E, E901, E902

Library – Ist of availablge panel (seege panel (see

be added to ces configur

Figure

can configure

he control un

nge – The stao the control

me - A uniquh recommendting system. being created

mple, if you aE900 in this 2, ... E90F. T

Identifies thele libraries, se page 14) ane page 15).

the list. Oncation section

3-3. Add devi

e for each de

nit from the

arting and enller.

ue device nads using the The name yd and will beare defining

field, the coThe name yo

e library thisstorage mustnd be conne

ce at least onn will displa

ices Paramete

evice are:

list above th

nding hexade

ame must be same device

you enter wie incremente16 devices wonfigurator wou enter may

s device is cot be defined cted to the n

ne control unay (Figure 3-

ers

hat you wish

ecimal devic

created for e name as dell be the inited for each swith an addrwill name thy be from 1 t

onnected to. on the Avai

node on the n

ntil has been-3).

h to configur

ce unit addre

each Virtuenefined on thetial device insubsequent ess range of e 16 devicesto 8 characte

To appear ilable tab of node tab of t

n

e

esses

nt e n the

f 00 – s ers

in the the


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).

2

S

26 Virtuent

Scratch Sy

User’s Guid

Note: If yon the marather thatwo contr

ynonyms

When theload displto be mou“VOL=SEdevice indthe drive. and then r

z/OS usesrequest forecognizerequest tocommandthe contromount it o

Most comallowing tscratch ta

Customercharacter request fotape poolssynonyms

de

you are confainframe bean defining rol units with

e mainframe lay commanunted. For exER=000001”dicating the After sendi

reads the VO

s the default or a scratch te these 2 chao mount an ed containing oller will locon the reque

mmercial tapethe customer

ape.

rs using tapestrings that

or a scratch ts, Virtuent as” to the Vir

Fig

figuring thee aware that

32 devices oh 16 devices

wants a taped is sent ovexample, in z”, then z/OStape volumeing the load

OL1 label to

character strtape to be moaracter stringexisting VOLeither SCRT

cate an availasted device t

e managemer to define th

e pools with tthe compute

tape from a sallows the curtuent contro

gure 3-4. Curr

e tape deviceMTLs only

on a single cs each.

e volume (Ver the channez/OS if a use will send a

e with VOLSdisplay, z/Overify the se

rings “SCRTounted for o

gs as a requesLSER. WheTCH or PRIVable scratch to be used fo

ent systems (heir own scr

their TMS wer operators aspecific poolustomer to deoller. The sy

rent devices

es into a Maallow 16 de

control unit,

VOLSER) moel to the dev

er codes JCLload display

SER ‘00000OS waits for erial number

TCH” and “Poutput. By dst for a new en Virtuent rVAT insteadtape in the v

or output.

(TMS) suppratch pools fo

will have defand/or tape ll of scratch tefine their owynonyms, alo

anual Tape Levices per co, you would

ounted on a vice identifyiL for a tape vy command t01’ needs to the device tor.

PRIVAT” todefault Virtue

scratch tapereceives a lod of a volumvirtual tape l

ort the concfor use when

fined their owlibrary musttapes. In supwn unique “ong with SC

Library (MTontroller. So

want to defi

tape device ing the VOLvolume that rto the tape be mounted o become re

o indicate a ent controllee, rather thanoad display

me serial numlibrary and

ept of tape pn mounting a

wn special t recognize apport of TM“scratch CRTCH and

TL) o fine

a LSER reads

on ady

ers n a

mber,

pools; a new

as a MS


PRIVAT, will be recognized by the Virtuent controller as a request for a new scratch volume when they are received in a load display command.

On the Device panel, next to the control units section is a section for adding your own scratch synonyms (tape pool names). See Figure 3-1.

The format for defining a scratch synonym is:

synonym=(prefix1,prefix2,…CLASS=(CLASSn,CLASSn,…))

where:

synonym – is the character string to be used as the synonym. Synonyms may be 1 – 10 characters in length and must contain only letters A-Z and numbers 0-9. Synonyms are not case sensitive and may be entered in either upper or lower case.

prefixn – a scratch synonym may be associated with a specific set of VOLSERs. prefixn defines the prefix characters of the VOLSERs that can be assigned in response to a scratch request made with this synonym. For example, SCRTCH=(00,01) would imply that any load request received for SCRTCH must be satisfied with a VOLSER that startes with either “00” or “01”. Valid VOLSERs that could be mounted by Virtuent would include any VOLSER in the range 000000 – 019999; assuming only numeric VOLSERs are in use. If there are no scratch tapes with VOLSERs beginning with “00” or “01” then Virtuent will not mount a tape and the mount will remain pending.

Each prefix can be from 1 to 6 characters in length.

If a VOLSER prefix is not defined for a specific scratch synonym then any available scratch tape will be used.

CLASSn – defines the storage class or classes associated with this scratch synonym. For example, PRIVAT=(CLASS=CLASS1) would indicate that any load request received for PRIVAT must be satisfied by allocating a scratch VOLSER in storage class 1. Virtuent will randomly allocate each new tape volume to any filesystem in the storage class with enough space for the cartridge (volume) being written as defined by the SIZE= parameter for the device.

If a class is not specified for a synonm, then the synonym will allocate new volumes to the default storage class 0.

228 Virtuent

User’s Guid

Figure 3-5

In this exaavailable

A requestassigned awith thesepending.

PRIVAT tape withithe mount

Syntax is

DR

defines twnumbers bserial num

Whereas d

DR

correctly beginning

Finally, kBy defaultape avail

de

5 show a sam

ample any mscratch tape

t for SCRTCa volume wie prefixes ar

tapes will goin that class t will remain

important w

RTAPE=(00

wo synonymbeginning w

mbers CLAS

defining:

RTAPE=((0

establishes tg with 00 or

keep in mind lt, Virtuent wlable on the d

Figure 3-

mple scratch

mount requese in the defau

CH will also ith a serial nure available t

o to storage will be used

n pending.

when coding

0,01),CLASS

s, DRTAPE with 00 or 01SS1 and CLA

00,01),CLAS

the single sc01 located in

that it is notwill allocate default (clas

-5. Defining S

h synonym co

sted with theult storage cl

go to defaulumber beginthe mount w

assigned to d. If there a

scratch syno

S=(CLASS1

and CLASSin Class 0 s

ASS2.

SS=(CLASS

ratch synonyn either stora

t necessary tany request

ss 0) storage

cratch Synony

onfiguration

e synonym Wlass 0.

lt storage (clnning with 0

will not be sat

storage clasare no availab

onyms. For

1,CLASS2)

S. DRTAPEstorage. CLA

1,CLASS2))

ym DRTAPEage class 1 o

to define anyfor SCRTCclass.

yms

n.

WORK will b

ass 0), but w0 or 01. If ntisfied and w

s 1. Any avble scratch t

example, de

E will use voASS will use

)

E using VOLor storage cl

y scratch synH or PRIVA

be assigned

will only be no scratch tawill remain

vailable scrattapes in class

efining:

olume serial e only volum

LSERs ass 2.

nonyms at alAT to any scr

any

apes

tch s 1,

me

ll. ratch

Saving

Activat

g your Con

Once the Co(Figur

ting (Insta

In ordinstallwill nyour c

WARrestarthe mmainfinstal

Be awdetectHoweinstallnot toexistinwill coconfignode)

nfiguration

you have deonfigurationre 3-6).

alling) a Co

der for any coled. Even wot become aconfiguration

RNING! Whrted. Any e

mainframe oframe you slling a new c

ware that if yting a chang

ever, if you al the configu modify anyng nodes do ontinue to ruguration, savwithout disr

n

efined the con panel click

onfigurati

onfigurationwhen you moactive until yn click the In

hen you clicemulated, onperating sys

should idle aconfiguratio

your systemge to its curare adding a uration whiley of the exist

not detect aun without reve the updatrupting the o

onfiguration k Save Chan

Figure 3-6.

ion

n to be used bodify the curryou re-installnstall button

ck the Instalnline tape dstem. If youall tape drivon (i.e. befo

m has multiprrent configunew control

e the existinging controlle

any changes estarting. Tted configuraoperation of

Chapter 3.

the way younges to save

Saving Chang

by the Virturently installl the configun on the Con

ll button thedrive will go ur controlleves and varyre clicking t

ple controlleuration willller (node) tog nodes are aers (nodes) ceffecting the

This allows yation, and inthe library.

Configuring

u want it, youe your config

ges

uent controlleled configur

uration. To infiguration

e Virtuent c offline ander is currenty them offlithe Install b

ers (nodes) l automatico an existingactive as lonconfigurationeir current coyou to add thnstall it (to ac

g Virtual De

u need to savguration to d

er(s) in mustration the chainstall (and apanel (Figur

controller(s)d may be boxtly online wine prior to button).

every contrally restart.

g system young as you takns. As longonfigurationhe new nodectivate the n

evices 29

ve it. On disk

t be anges activate) re 3-6).

) will be xed by

with the

roller .

u can ke care g as the n they e to the ew

Chapter 4. Using Virtuent with z/OS, OS/390, or MVS 31

Chapter 4. Using Virtuent with z/OS, OS/390, or MVS

Mainframe Utilities

Bus-Tech provides several small utilities as well as a Unit Information Module (UIM) for the z/OS, OS/390 and MVS environments. The utilities provided include:

VTSCR – A scratch utility which sends volser scratch requests to Virtuent

VTCMD – A utility allowing Virtuent commands to be sent from the mainframe console

VTLIB – A utility allowing you to define scratch volumes to an MTL

VTHHOST – A program that runs as a started task in z/OS to allow message and command exchange between the z/OS operator console and the Virtuent controller(s).

GENSTATS – A utility that provides statistics reports on the usage of the Virtuent controller(s).

To use any of these utilities or the UIM you will need to upload a file from the MDL Host Utilities CD to your mainframe. The file you will need is called /UTIL/MVS/VT7ZOS.XMI. This file should be FTP’d to the mainframe as follows:

ftp target_system_name

(satisfy login requirements of the mainframe)

quote site recfm=fb lrecl=80

bin

put vt7zos.xmi (the file will be placed on the host as ’uid.vtzos.xmi’, where uid is the login user id used for the ftp. Alternatively, you may use put vtzos.xmi ‘filename’ to force a specific filename of your choice.)

quit

Once the file is on the mainframe use ISPF function 6 (Command Shell), and issue the command :

receive indataset(‘uid.vtzos.xmi’)

When prompted with ‘Enter restore parameters or delete or end’ enter:

da(‘BTI.MODULE’)

A ‘BTI.MODULE’ will be created with members:

CBDEC255 - The Unit Data Table for the UIM

CBDUC255 - The UIM for the Bus-Tech virtual devices


VTLIB - A utility to add volumes to an MTL

VTSCR - The Virtuent scratch utility

VTCMD - The Virtuent command utility

VTHHOST - The Virtuent z/OS console utility

GENSTATS – Virtuent reports utility

Configuring the Devices

z/OS, OS/390, and MVS use the Hardware Configuration Definition (HCD) utility to define devices to the system. HCD provides an interactive interface that allows you to define the system’s hardware configuration to both the channel subsystem and the operating system.

There are three alternatives for configuring Mainframe Appliance for Storage devices to the mainframe. They are:

1. Configure the devices as real 3480, 3490. or 3590 tape drives.

2. Configure the devices as a Manual Tape Library (MTL).

3. Configure the devices with a unique device type using Bus-Tech’s Unit Information Module (UIM).

Each of these alternatives will be discussed.

If you are planning on using MDL with IBM’s Object Access Method (OAM) then you should configure the Virtuent devices using alternative 2, a Manual Tape Library. OAM requires tape drives to be SMS managed. Bus-Tech’s UIM cannot be used with OAM because OAM does not recognize UIM devices as a supported drive model. The IBM document SC35-0426, “DFSMS Object Access Method Planning, Installation, and Storage Administration Guide for Object Support”, describes how to use a library for OAM object use.

Bus-Tech’s support web site contains sample I/O device gens (IOCDS) in the HCD guides found under the title “Knowledge Base” at the following link:

http://www.bustech.com/support/vtechtips.asp

Real 3480/3490/3590

Virtuent can emulate 3480, 3490, or 3590 tape drives. If your mainframe installation does not have one of these device types installed you can elect to install the Virtuent devices using that type. The advantage of using 3480/3490/3590 device types is that some applications or access methods examine device type to make sure they are writing/reading to a known tape device and these applications won’t necessarily work with Bus-Tech’s Unit Information Module (UIM).


However if you have real 3480, 3490, or 3590 tape drives configured in your system do not attempt to define Virtuent devices in this manner. Configuring Virtuent devices as a device type that is already present can result in mis-allocation where OS/390 will request a real 3480/3490/3590 cartridge on a Virtuent device or request a Virtuent tape-on-disk volume on a real 3480/3490/3590 drive.

If you do plan to use one of these device types to define Virtuent devices make sure that the esoterics configured for tape in your installation do not include this device type. More specifically, if your JCL is using the esoteric TAPE (UNIT=TAPE) then make sure that TAPE does not include the device type (3480, 3490, or 3590) you are using to define Virtuent devices.

Manual Tape Libraries

If you have 3480, 3490, and 3590 tape drives all installed in your installation then you should not define Virtuent devices as real tape drives. Doing so can result in allocation errors as described in the previous sub-section. But if you plan to use Virtuent devices with OAM or any application that checks device type then you also cannot use Bus-Tech’s Unit Information Module (UIM). In this case you must define your Virtuent devices as 3490 or 3590 tape drives and then include them in a Manual Tape Library (MTL) so that they will be isolated from your other 3490s or 3590s.

IBM introduced the concept of a Manual Tape Library (MTL) with APAR OW45271. This APAR allows standalone tape drives and their associated volumes to be SMS managed by treating a group of such drives as a logical tape library. Allocations to such a logical library are managed by SMS just as any automated tape library dataserver (ATLDS) would be with the exception that mount messages will be routed to a tape operator console rather than the ATLDS robotics. IBM document SC35-0427, “PISA Guide for Tape Libraries”, describes the issues regarding MTL support.

Begin by configuring the Virtuent devices as either 3490 or 3590 tape devices using HCD. The standard HCD 3490 / 3590 definitions should be used. On the Device/Parameter Feature definition screen for each drive, you must select MTL as YES and supply an artificial LIBRARY-ID and LIBPORT-ID. The control unit should also be defined as a 3490 / 3590 with 16 tape drives available.

All the devices in the same logical library should have the same LIBRARY-ID, with each group of 16 devices having a unique LIBPORT-ID. IBM’s requirement that there can be only 16 tape drives to a LIBPORT-ID will require you to configure multiple control units on the same channel using different logical control unit addresses when you want to configure more than 16 drives. Each control unit’s devices would have the same LIBRARY-ID, but have a unique LIBPORT-ID per control unit. For example:


Dev Add CU Log CU Library-ID Libport-ID E800 CU800 00 12345 01 E801 CU800 00 12345 01 E80F CU800 00 12345 01 E810 CU810 01 12345 02 E811 CU810 01 12345 02 E81F CU810 01 12345 02

Once the MTL has been defined to HCD it must be defined to SMS using the library management function. Then your ACS routines should be updated to allow jobs to select the new library with appropriate user defined ACS management, data, and storage classes and groups. For example, if you define a new esoteric called “VTAPE”, your ACS routines could allocate the dataset to the SMS storage group using the MTL whenever UNIT=VTAPE is specified in JCL.

The characteristics of Virtuent virtual tape cartridges match the SMS Media Type; “MEDIA2” for 3490 or “MEDIA4” for 3590. Be sure to specify the appropriate media type (MEDIA2 or MEDIA4) on the Library Definition screen. In addition, since SMS will request scratch tapes using the media type, you must add MEDIA2 or MEDIA4 to the list of Virtuent scratch name synonyms (see page 28).

Note that once the MTL is configured, it is treated much the same as a real library. That is, cartridges must be ‘entered’ into the library before they can be used. Therefore, you will need to define any VOLSERs to be used in your Virtuent library to the mainframe. To simplify this, the VTLIB utility may be used to enter cartridges into the MTL.

VTLIB must be executed out of an authorized library. An example of the JCL required to link VTLIB follows:

//L EXEC PGM=HEWL,PARM=’MAP,LET,LIST,NCAL,AC=1’ //SYSLMOD DD DSN=USER.LIBRARY,DISP=SHR //SYSUT1 DD DSN=&&SYSUT1,SPACE=(1024,(120,120),,,ROUND), // UNIT=SYSALLDA,DCB=BUFNO=1 //SYSPRINT DD SYSOUT=* //DDIN DD DSN=BTI.MODULE,DISP=SHR //SYSLIN DD * INCLUDE DDIN(VTLIB) NAME VTLIB® /*


The following is an example of JCL to run VTLIB:

//S2 EXEC PGM=VTLIB //SYSUDUMP DD SYSOUT=* //OUTDD DD DSN=VTLIB.LOG,DISP=SHR (recfm=fb,lrecl=80,blksize=4000) //INDD DD * * TO ENTER VOLUMES INTO THE MTL, THE SYNTAX IS AS FOLLOWS: * 1ST CHAR MUST BE AN 'M' * 4-9 IS THE STARTING VOLSER * 11-18 IS THE LIBRARY NAME ASSIGNED DURING SMS LIBRARY ADD * 20 IS THE MEDIA TYPE (DEFAULT=2). SPECIFY 4 FOR 3590 LIBRARY * 21-25 COUNT OF VOLSERS TO BE ADDED (DEFAULTS TO 1 IF BLANK * MAX COUNT=10000) * VOLSER LIB COUNT M BT0000 MTL1 5000 M AA0000 MTL2 10000 /*

The log file will list the result of each cartridge entry request, including any error codes. The VTLIB utility uses IBM's CBRXLCS macro, and the return codes and reason codes can be found in:

DFSMSdfp Diagnosis Reference (GY27-7618) section 11.4.1.

MTL-Related IBM maintenance

The PTFs for the following APARs should be applied before using Virtuent in an MTL environment:

APAR OA03749 MTL more than 1 device fails to vary on-line

APAR OA06698 Replacement tape drives get MSG IEA437I in an MTL environment

APAR OA07945 Mount hangs / timeouts using MTL with OEM Automated Library

APAR OA08963

Tape volume capacity incorrect for OAM object support users

APAR OA10482 MTL scratch volume mount error

Bus-Tech’s Unit Information Module

As an alternative to defining real 3480s, 3490s, or 3590s or using a MTL, Bus-Tech provides a user Unit Information Module (UIM) that allows Virtuent tape devices to be configured to HCD using a unique device type. Using the Bus-Tech UIM prevents the operating system from allocating Virtuent tape drives to jobs requesting a mount


of a real tape cartridge and vice-versa. If you are not using OAM or an application that checks device types the Bus-Tech UIM is the easiest way to configure Virtuent devices so that there will not be any allocation errors with real tape drives. Information regarding user UIMs can be found in IBM’s MVS/ESA Device Validation Support (GC28-1447) manual.

Bus-Tech’s UIM and associated UDT (Unit Data Table) must be installed into SYS1.NUCLEUS, prior to configuring the Virtuent devices in HCD. Prior to installing the UIM, it is important to back up the SYSRES volume containing the SYS1.NUCLEUS dataset in order to provide a recovery mechanism should anything fail to operate properly.

Use ISPF function 3.3 (Utilities; Move/Copy) and copy CBDEC255 and CBDUC255 from ‘BTI.MODULE’ (see page 31) into ‘SYS1.NUCLEUS’.

If CBDEC255 or CBDUC255 already exist in SYS1.NUCLEUS, then some other vendor has already supplied a user UIM using the same user device number of 255. Contact Bus-Tech support and we will arrange for a different module name to be used.

Once the UIM is installed, you can now configure the Virtuent devices in HCD. The UIM provides for four (4) control unit types of V3480, V3481, V3482 and V3483; supporting device types of V3480, V3481, V3482, and V3483 respectively. The generic names for these devices are also V3480, V3481, V3482, and V3483. If you have already defined a generic name of V348x, please contact Bus-Tech for support. Multiple virtual device types are defined to support multiple Virtuent systems or a single Virtuent with multiple virtual tape libraries configured.

You need to define a V348x tape drive to the hardware configuration for each virtual tape device you have configured in the MDL. All virtual tape drives assigned to the same virtual tape library need to be defined with the same generic name (V3480, for example). If you plan to have some drives assigned to a different virtual tape library (see page 28), then you should define that drive to a separate generic name (V3481, for example).

Once the Virtuent device definitions are active, you must either specify UNIT=V348x or hard code the unit address to allocate to a Virtuent device. In this way, regular jobs that call for real tape drives or use tapes previously catalogued on real 3480s will not allocate to Virtuent devices. Once a tape is catalogued as having been created on a Virtuent V348x device, it will only allocate to that same device type when it is called for again. Conversely, a tape catalogued as created on a real tape drive will not be allocated to a Virtuent V348x device.

Note: Bus-Tech’s UIM does not support auto-switching. If you need to auto-switch tape devices between LPARs in a sysplex, do not configure your devices with the UIM.


Virtuent Scratch Utility Program

Virtuent provides the VTSCR utility which can be used with any of the major tape management systems to keep your tape management system scratch status in sync with the Virtuent scratch status.

The VTSCR utility must be linked as an authorized program into an authorized library under the name VTSCR. It is highly recommended that RACF be used to restrict the use of VTSCR to authorized users only.

An example of the JCL required to link VTSCR follows:

//L EXEC PGM=HEWL,PARM='MAP,LET,LIST,NCAL,AC=1' //SYSLMOD DD DSN=USER.LIBRARY,DISP=SHR //SYSUT1 DD DSN=&&SYSUT1,SPACE=(1024,(120,120),,,ROUND), // UNIT=SYSALLDA,DCB=BUFNO=1 //SYSPRINT DD SYSOUT=* //DDIN DD DSN=BTI.MODULE,DISP=SHR //SYSLIN DD * INCLUDE DDIN(VTSCR) NAME VTSCR(R) /*

VTSCR runs on the mainframe and sends volume scratch requests to Virtuent. Since the tape management system (TMS) may dynamically release tapes back to scratch status, VTSCR should be periodically run to maintain synchronization between the TMS catalog and the MDL. To use VTSCR the user must run a TMS scratch report and then input that scratch report into VTSCR. VTSCR scans the scratch report for Virtuent owned volumes and sends the appropriate scratch requests to the MDL.

There are 2 methods of running VTSCR. Method 1 uses an offline tape device which points to the Virtuent controller (node). This is the preferred approach and should be used whenever you are not planning to use all the tape drives in your library.

For example, let’s assume you plan to use (32) drives on the controller (node). In the controller’s configuration, configure 33 active drives.

On your IBM mainframe define all 33 devices to z/OS. But configure the 33rd drive to remain offline at IPL. If you are defining the devices into an MTL, leave the offline drive out of the MTL. To prevent accidental allocation to this device if it were to be varied online you may wish to define it into its own unused MTL. When using this method the commands are sent to the control device without having to mount a tape volume (VOLSER) on the device.

The following JCL will run the VTSCR using the offline device:

<JCL to Generate Scratch Report Here> //LOG EXEC PGM=VTSCR,PARM=’DEV=xxxx,parms’ //VTSLOG DD DSN=VT.LOGFILE,DISP=OLD //VTSSCR DD DSN=SCRATCH.REPORT,DISP=OLD


where xxxx is the device address of the offline device and parms may include any of the parameters described below.

The second method for running VTSCR is to use a dedicated control tape. When using a control tape (VOLSER) rather than an offline device, VTSCR uses a control file called VTSCTRL. A DD statement for this file must be added to the JCL. The first time you run VTSCR use the following JCL:

<JCL to Generate Scratch Report Here> //LOG EXEC PGM=VTSCR,PARM='parms' //VTSLOG DD DSN=VT.LOGFILE,DISP=OLD //VTSSCR DD DSN=SCRATCH.REPORT,DISP=OLD //VTSCTRL DD DSN=VT.CTRL,UNIT=VTAPE,VOL=SER=, // DISP=(,CATLG)

Do not code the DEV=xxxx parm when using the VTSCTRL DD statement. Then, following the initial execution of VTSCR update the VTSCTRL DD statement to use the same control tape on subsequent executions of VTSCR:

<JCL to Generate Scratch Report Here> //LOG EXEC PGM=VTSCR,PARM='parms' //VTSLOG DD DSN=VT.LOGFILE,DISP=OLD //VTSSCR DD DSN=SCRATCH.REPORT,DISP=OLD //VTSCTRL DD DSN=VT.CTRL,DISP=(,KEEP)

Using VTSCR in this fashion creates a permanent control tape in the MDL library.

VTSCR Parameters

In addition to the DEV parmameter described above, any of the following parameters may be substituted as needed for parms in the sample JCL:

TYPE=x where x is used to select the tape management system. Valid types include RMM, TMS, TLMS, ZARA, CTLM, or CTLT. This is the only required parameter.

PREFIX=y where y is a string of prefix characters that will limit processing to volumes whose volume serial numbers (VOLSER) begin with the character(s) specified. Unless otherwise specified by the PREFIXLN parameter, the default prefix length is 2. ‘PREFIX=AAABAC’ would cause VTSCR to process only volumes whose serial numbers begin with AA, AB, or AC. Coding this parameter prevents VTSCR from trying to unnecessarily scratch volumes that are not stored on the MDL. If no PREFIX is specified VTSCR will process the entire scratch list.

PREFIXLN=n where n can be a single digit between 1 and 5. This value replaces the default prefix length of 2 for the ‘PREFIX=’ parameter. PARM=’PREFIX=ABCD,PREFIXLN=1’ will


cause VTSCR to process only volumes whose serial numbers begin with A, B, C, or D.

NODSNCHK Virtuent will normally validate Data Set Names if found in the scratch report as part of the scratch process. A scratch will not successfully complete if the data set name in the scratch report does not match the data set name in the HDR1 label on the volume being scratched. NODSNCHK prevents the dataset name check from being performed and is not recommended for normal use.

FREESPACE The default of VTSCR is simply to reclassify volumes being scratched as eligible for scratch allocation requests, without freeing up the space occupied by that volume. The FREESPACE parameter may be used to request that the space be freed. Note that FREESPACE requires the volumes to already be in scratch status. Therefore to immediately free the space, VTSCR will need to be run twice. The first execution should be run without the FREESPACE parameter to scratch the volumes and the second execution should be run with the FREESPACE parameter to release the space.

Keep in mind that Virtuent will automatically free the space of scratched volumes when it needs space so it is generally not necessary to run VTSCR with the FREESPACE parameter.

FREEAFTERSCR While the FREESPACE option requires a volume to already be in a scratched state, FREEAFTERSCR will immediately free space from a volume as soon as VTSCR scratches it. While FREEAFTERSCR allows you to scratch a volume and free the space associated in a single execution of VTSCR, it should be recognized that once the space has been freed the volume cannot be recovered if it was scratched by mistake.

NODATECHK Virtuent will normally check the creation date of a tape volume and will not allow any volume to be created and scratched in the same 24 hour period. Setting this parameter will allow volumes to be created and scratched on the same day. This parameter ignores the default date check in VTSCR.

IGNLCSERR This parameter will ignore any errors reported by Library Call Subsystem used by OAM with MTL volumes. Normally VTSCR will log any error returned by LCS and will stop processing scratch tapes when these errors occur. If this parameter is set, VTSCR scratch processing will continue even when LCS errors are encountered.


ALLVOLS This parameter will allow scratch of volumes with data set names of all zeros.

IGNLCSRC4 This will allow VTSCR processing to continue after a return code 4 from LCS processing, but terminate if the return code from LCS processing is greater than 4.

NOTCDB This will prevent VTSCR from attempting any TCDB updates. This should only be used if the TMS already performs this function.

NOTIFSCR This will prevent VTSCR from attempting to change the TCDB use attribute to scratch if Virtuent reports that the volser was already a scratch.

The output VTSLOG file will maintain a history of the results of each scratch request. The file should have a logical record length (LRECL) of 133. If an error occurs during a scratch request (such as scratching a non-existent volume) the failure will be recorded in the log file, the program will continue with the next scratch request, and a non-zero return code from the program execution will result.

The output VTSCTRL file is used to allocate a Virtuent tape device for use as a control path to pass the scratch request(s). If there are multiple tape libraries being used to contain the virtual volumes, the user must select a tape device address associated with the library containing the volumes to be scratched. Do not specify a VTSCTRL file if the DEV= parameter is used.

The VTSSCR file must point to the scratch report that the user has created using the appropriate TMS utility. The scratch report must be generated with a logical record length (LRECL) of 133. To avoid any possibility of confusion, it is strongly recommended that a single job be used that generates a current scratch list file and then runs the VTSCR utility against that file. In this way there is no possibility of accidentally running the VTSCR program against an old scratch report and causing the TMS and the MDL to become out of sync. In addition, since there is a slight time interval between the creation of the extract file and the processing of the report, Virtuent will not scratch a volume that has been created today. Additionally, the utility will not execute against a scratch report that was not created the same day.

The Scratch utility will use the data set name (dsname) information from the scratch report to verify volumes being scratched. If the data set name written in the volume header does not match the data set name on the scratch report for that volume the scratch request will be rejected.

It must be emphasized that once the VTSCR utility has completed, tapes that were successfully scratched by the utility can be re-used or erased at anytime. See page 134 for a complete description of the scratch process.


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 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(VTCMD) NAME VTCMD(R) /*

Like VTSCR (see page 37), VTCMD can be run using a dedicated control device or a dedicated control tape (VOLSER).

To run VTCMD using a control device use the following JCL:

//LOG EXEC PGM=VTCMD,PARM=DEV=xxxx //VTCLOG DD DSN=VT.LOGFILE,DISP=OLD //VTCCMD DD DSN=COMMANDS,DISP=OLD

Where xxxx is the device address of the control device. Typically this device would be offline as described in the previous section on VTSCR.

Alternatively, to run VTCMD using a control tape, use the following JCL:

//LOG EXEC PGM=VTCMD //VTCLOG DD DSN=VT.LOGFILE,DISP=OLD //VTCCTRL DD DSN=VT.CTRL,UNIT=VTAPE,VOL=SER=, DISP=(,CATLG) //VTCCMD DD DSN=COMMANDS,DISP=OLD

You may use the same control tape as you used with VTSCR.

The VTCMD program will read one or more Virtuent commands from the VTCCMD input file, and send each command to Virtuent for execution. A success or failure indication will be logged to the file pointed to by the VTCLOG DD statement. Note that any messages and other textual results of the command that display on the Virtuent console are not returned to the host.

The VTCCTRL file is used to allocate a Virtuent device for use as a control path to pass the Virtuent command(s). Any available virtual tape device can be used for the VTCCTRL device. Do not specify a VTCCTRL file if the DEV= parameter is used.

The VTCCMD DD statement should point to a list of Virtuent commands to be sent. The LRECL of VTCCMD cannot exceed 256. When possible, it should be created using the NONUM ISPF edit option to avoid sequence numbers at the end of the command line. This can optionally be an in-stream input file (VTCCMD DD *) of commands.

The VTCLOG DD statement points to a sequential file for logging the VTCMD results. This file should have a logical record length (LRECL) of 133. If an error occurs during command processing, the failure will be recorded in the log file, and a non-zero return code from VTCMD will result. The possible error codes are as follows:


0x01 Invalid data length (must be between 1 and 256 bytes)

0x02 Virtuent is configured to not accept Host-initiated console commands

0xFF(-1) A general syntax error occurred. (The Virtuent console error message “VIR891E: Invalid command syntax” was displayed.)

0xFC (-4) An “E” level error other than general syntax error occurred. (A Virtuent console error message other than VIR891E was displayed.)

A sample VTLOG output might be as follows:

VTCMD VER 1.0 VTCTRL = EA82 2004/09/10 12:47:49 CMD ERR=FF: this is an invalid command 2004/09/10 12:47:49 CMD ISSUED: q all 2004/09/10 12:47:49 CMD ERR=FC: q xxxxxxxx 2004/09/10 12:47:49 CMD ISSUED: set size=2g dev=EA80

There are two additional methods of passing the commands to VTCMD. They are:

1. Use of PARM=’WTOR’. This will result in message VIR070I ENTER Virtuent COMMAND being issued to the operator, who can then reply with the Virtuent command. The VIR070I message will be re-issued after each Virtuent command is accepted until END is entered as the reply. The VTCMD input file is not used if this method is employed. e.g.:

//LOG EXEC PGM=VTCMD,PARM=’WTOR’ //VTCLOG DD DSN=VT.LOGFILE,DISP=OLD //VTCCTRL DD DSN=VT.CTRL,UNIT=VTAPE,VOL=SER=, DISP=(,KEEP)

2. Use of PARM=’CMD=’. This allows the user to pass a single Virtuent command on the EXEC card rather than using the VTCMD input file. This also allows a user to call VTCMD from another program, and pass the command as an entry parameter. e.g.:

//LOG EXEC PGM=VTCMD,PARM=’CMD=Q SPACE’ //VTCLOG DD DSN=VT.LOGFILE,DISP=OLD //VTCCTRL DD DSN=VT.CTRL,UNIT=VTAPE,VOL=SER=, DISP=(,KEEP)

DFSMShsm Considerations

For those who plan to use Virtuent with HSM, the various SETSYS tape parameters will not accept V348x generic names as valid. For these environments, it is necessary to define Esoteric names that are unique to the various V348x devices.


To identify esoteric tape unit names to DFSMShsm, you must first define these esoteric tape unit names to MVS during system I/O generation (HCD). Then, you must include the esoteric tape unit names in a DFSMShsm SETSYS USERUNITTABLE command. Only after they have been successfully specified with the SETSYS USERUNITTABLE command can they be recognized and used as valid unit names with subsequent DFSMShsm commands.

Specifying Tape Compaction

Compaction of the virtual tape data under z/OS or OS/390 is initiated the same way as for a real compression-capable (IDRC) 3480/3490/3590. That is, the user may specify the use of compaction in the JCL by using the DCB=TRTCH=COMP parameter on the appropriate DD cards for output tapes. No JCL parameter is required for input compressed tapes.

Alternatively, the system programmer may specify the COMPACT=YES parameter in the DEVSUPxx PARMLIB member. This would result in compaction being the default option for all of the virtual drives.

It should be noted that while the compaction option should significantly reduce the amount of storage required on the Virtuent’s target file systems, there will be some impact on the data transfer performance compared to uncompressed data. The efficiency of the compaction as well as the performance impact will vary depending upon the data.

If you are writing to storage that performs data de-duplication and you want to make sure the Virtuent controller is not performing data compression you may set compression off by setting the IDRC parameter to “No” on the device configuration. IDRC=No causes the drive to ignore the compression flag received from the mainframe and write the data to the store without compressing it.

The file-size values reported by the Virtuent “QUERY” command as well as the awsdir and awsprint utilities reflect the compressed data size, not the original uncompressed size.

Missing Interrupt Timer

The MVS, OS/390, or z/OS Missing Interrupt Handler (MIH) timer value is often set at a value that is too low for the sometimes lengthy operations that can occur on a large tape cartridge. If an operation takes longer than the MIH value, the operating system will report I/O errors and possibly "box" the device, taking it out of service. For this reason, IBM recommends a MIH timer value of 20 minutes or more for tape drives, including virtual tape drives such as those on Virtuent.


Starting in release 3.10, Virtuent reports a preferred MIH timer value of 3000 seconds (50:00 minutes) to the Host when it is varied online, and the Host should take this value as the Virtuent devices' MIH time.

To determine the current MIH timer value, you can use the following MVS operator command:

D IOS,MIH,DEV=xxxx

where xxxx is any Virtuent tape drive address.

You can temporarily change the MIH value for Virtuent devices by entering the following MVS operator command:

SETIOS MIH,DEV=(xxxx-xxxx),TIME=mm:ss

where (xxxx-xxxx) is the range of Virtuent tape drive addresses.

For more information about the MIH timer and tape drives, refer to the IBM manual 3490 Magnetic Tape Subsystem Introduction and Planning Guide, number GA32-0297.

Dynamic Device Reconfiguration (DDR) Considerations

Since Virtuent is a virtual tape control unit, it cannot benefit from an operator or system-initiated 'swap' function. Accordingly, following any message 'IGF500I SWAP xxxx TO xxxx - I/O ERROR' for any Virtuent device, the operator must reply NO to the subsequent “## IGF500D REPLY 'YES', DEVICE, OR 'NO' ".

If the user has configured the Virtuent devices as V348x devices using the UIM, DDR swap is automatically disabled for those devices, and a swap cannot occur.

DR Logging

In z/OS environments, Virtuent controllers provide a service referred to as “DR Logging” which will log tape volume mounts and unmounts to a log file on the virtual tape library. When DR Logging is enabled, each Virtuent controller (node) defined as part of the virtual tape library will create a log file on each of the filesystems writing a single log record to the file showing each tape volume (VOLSER) it mounts and unmounts from the filesystem (Figure 13-1).

Enabling

These(VOL

If a cogeneravirtuaunmou

The pincom

By placontrorecovecomplbe usetime o

g DR Loggi

By detape lipresen

The .vonly u

N

N

e log files areLSER) files.

ontroller (noated using th

al tape libraryunted.

urpose of thmplete follow

acing the DRoller’s internery site alonlete loss of ted to help idof the failure

ng

efault, Virtueibrary. To ent in each fil

vstats file mauses the pres

Node N1

Node N2

Ch

Fi

e hidden from

de) outage she GENSTAy and report

is report is twing a contro

R log files innal storage, tng with the tathe primary pentify all tap

e.

ent controlleenable DR lolesystem wh

ay be emptysence of the f

hapter 4. Usi

igure 4-1. DR

m view so th

should occurATS utility. T

those tape v

o help determoller failure.

n the virtual the log files cape volumesprocessing fape volumes t

rs will not auogging, a hidere logging

. Virtuent dfile to determ

ing Virtuent

Logging Over

hat they cann

r, a Virtuent This report wvolumes whi

mine which

tape library can be replic

s. Then, in thfacility, the Vthat were in

automaticallydden control is to be perf

does not lookmine whethe

N1 Lo

N2 Lo

N1 Lo

N2 Lo

t with z/OS,

rview

not be mista

“Still in Usewill read all ich were mo

tape volume

rather than wcated to a sehe unlikely e

Virtuent Stilluse at the pr

y create DR filed named

formed.

k at the conteer or not to p

og

og

og

og

OS/390, or

aken for tape

e” report canthe log filesunted and ne

es may be

writing themcondary disaevent there il in Use reporimary site a

logs on the vd “.vstats”, m

ents of the fiperform DR

VOLSERs

Filesystem 1

Filesystem 2

MVS 47

e volume

n be s in the ever

m on the aster is a ort can at the

virtual must be

ile. It logging.

s


The procedure to create the .vstats file in a filesystem varies by Virtuent controller model. Please refer to the hardware installation guide that accompanied your system for information on how to create this control file.

Retrieving the Still In Use Report

The Still In Use report is part of the standard Virtuent general statistics report program, GENSTATS.

Please refer to the next section in this manual for instructions on how to use GENSTATS.

Running GENSTATS with the STILLINUSE parameter will produce the Still In Use report from available DR Logs.

GENSTATS Reports

In z/OS environments Virtuent controllers include a general reporting utility named GENSTATS. GENSTATS provides any or all of the following reports:

Throughput – Showing input / output by hour for the reported period

Maxtapes – Showing maximum tapes in use by hour for the reported period

Slowest Mounts – Showing the slowest tape mounts during the reported period

Still In Use – Showing tapes mounted and never unmounted

As indicated at the beginning of this chapter the GENSTATS utility is included in the VTZOS.XMI file along with other z/OS utilities. If you wish to use GENSTATS reporting you will need to first install the GENSTATS utility. The following sample JCL can be modified to suit your installation’s needs:

//L EXEC PGM=HEWL,PARM=’MAP,LET,LIST,NCAL,AC=1’ //SYSLMOD DD DSN=USER.LIBRARY,DISP=SHR //SYSUT1 DD DSN=&&SYSUT1,SPACFE=(1024,(120,120),,,ROUND), UNIT=SYSALLDA,DCB=BUFNO=1 //SYSPRINT DD SYSOUT=* //DDIN DD DSN=BTI.MODULE,DISP=SHR //SYSLIN DD * INCLUDE DDIN(GENSTATS) NAME GENSTATS(R) /*

Running GENSTATS reports is a two step process:

1. Run a collection routine on the Virtuent Controller to collect statistics into a tape volume on the virtual tape library.

2. Run the GENSTATS Utility to produce the desired report or reports.


The following JCL can be used to prepare GENSTATS reports for a single Virtuent controller (node).

//* PASS A COMMAND TO RUN THE STATFMT SCRIPT //STEP1 EXEC PGM=VTCMD,PARM=’CMD=RUNWAIT 99,DEV=xxxx’

//VTCLOG DD DSN=VT.LOGFILE,DISP=SHR

//* NOW PROCESS THE TAPE CREATED IN STEP1

//STEP2 EXEC PGM=GENSTATS,PARM=’see input parameter description below’ //GENIN DD DSN=BFLLCL,UNIT=VTAPE,LABEL=(,NL),VOL=SER=BFLLCL

//SYSPRINT DD SYSOUT=*

//SYSIN DD *

Parameters may be entered here in place of on the EXEC statement

/*

Where:

xxxx is the control device configured for this Virtuent controller

In this example, VTAPE is an esoteric that directs allocation to a Virtuent tape device.

The parameters that can be specified are:

DATESTART - Optional. Will exclude statistics information for records preceeding the date specified.

DATEEND - Optional. Will exclude statistics information for records dated later than the date specified.

DAYCNT=xxxx - By default GENSTATS will process up to 128 days of data. DAYCNT can be used to increase the number of days to be included in the report.

DEV=xxxx - Optionally this parameter can be used in place of the GENIN DD card to target a specific device address. This can be useful when using cross-controller (node) MTL definitions and a specific controller (node) must be targeted. This parameter requires the use of the VOL= parameter to identify the tape volume (VOLSER) to be mounted. If using z/OS 1.11 or higher, it is recommended to use the SMSHONOR JCL parameter instead of DEV=, to target a specific address within an MTL.

DEVCNT=xxxx - By default GENSTATS will process up to 2000 devices. DEVCNT can be used to increase the number of devices to be processed.

MAXTAPES - This will produce a report detailing the highest number of concurrent tapes in use by hour for each of the days


processed. If no tapes were active during any particular hour, that cell will show a ‘***’.

When MAXTAPES is specified GENSTATS will invoke an internal sort. The following DD cards must be included in the GENSTATS JCL when MAXTAPES is specified:

//SORTIN DD (temporary work file) //SORTOUT DD (temporary work file) //SYSOUT DD SYSOUT=*

NODENAME - Since many MDL nodes may have statistics on the input file, this allows the input to be filtered to select a particular nodename. This parameter is ignored if the input file does not contain DR Logging records.

PATHCNT=xxxx - By default GENSTATS will process up to 512 paths. PATHCNT can be used to increase the number of paths processed.

PATHNAME - This allows the input data to be filtered for a particular pathname or group of pathnames. This parameter will be ignored if the input file does not contain DR Logging records. The characters specified will be used to match against the pathnames of the input records. Only the characters specified need match to accept a record. For example, if PATHNAME=/tapelib/DISK were specified, and the node paths included /tapelib/DISK1, /tapelib/DISK2, etc., all of the /tapelib/DISKx records would be processed.

STILLINUSE - This will list any tape that was mounted but has no matching unmount record.

When STILLINUSE is specified GENSTATS will invoke an internal sort. The following DD cards must be included in the GENSTATS JCL when STILLINUSE is specified:

//SORTIN DD (temporary work file) //SORTOUT DD (temporary work file) //SYSOUT DD SYSOUT=*

SLOWMOUNTS - This report will first show the average mount times for the entire day range covered. It will then list the slowest ‘n’ mount times along with the related Volser, Nodename, Pathname, Date and Time. This report can be used to identify any peak slow periods, and can provide the information required to investigate such periods, if any.


SYNCTIME - This parameter can only be used along with the DATEEND and STILLINUSE parameters. When SYNCTIME is specified, the combination of DATEEND and SYNCTIME will be used to determine the point at which time the STILLINUSE check will be applied. In addition, tapes mounted after SYNCTIME will be listed for user evaluation purposes.

THROUGHPUT - This will produce a report detailing the daily and hourly throughput numbers in GB/sec for the records that meet the NODENAME, PATHNAME, and DATE filtering parameters, if specified. At the end of the daily detail summary, the report will list some overall maximums for the range of days covered.

VOL=volser - The VOL parameter is required when using the DEV parameter to identify the tape volume (VOLSER) to be mounted.

By default, using the JCL shown above, GENSTATS will report statistics from a single Virtuent controller. However, if used in conjunction with DR Logging (see page 46) GENSTATS can produce reports including statistics from all Virtuent controllers (nodes) in a single virtual tape library.

To use GENSTATS with DR Logging you must replace the volser “BFLLCL” with volser “BFLDRL” and replace “CMD=RUNWAIT 99” with “CMD=RUNWAIT 98” in the parameter list (PARM=) on the EXEC statement for VTCMD.

Assuming that device 384 is a control device on a Virtuent controller in the library, the following JCL would produce a Still In Use report using the DR Logging log files in the virtual tape library.

//* PASS A COMMAND TO RUN THE STATFMT SCRIPT //STEP1 EXEC PGM=VTCMD,PARM=’CMD=RUNWAIT 98,DEV=384’

//VTCLOG DD DSN=VT.LOGFILE,DISP=SHR

//* NOW PROCESS THE TAPE CREATED IN STEP1

//STEP2 EXEC PGM=GENSTATS,PARM=’STILLINUSE’ //GENIN DD DSN=BFLLCL,UNIT=VTAPE,LABEL=(,NL),VOL=SER=BFLLCL //SORTIN DD SPACE=(CYL,(50)),UNIT=SYSDA //SORTOUT DD SPACE=(CYL,(50)),UNIT=SYSDA //SYSOUT DD SYSOUT=*

//SYSPRINT DD SYSOUT=*

//SYSIN DD *

/*


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.): NODENAME TIME VOLSER DATE TIME PATH bti 000.058 H00090 2008/11/07 17:27:12 tapelib2/H0 bti 000.059 GF0491 2008/11/07 18:06:57 tapelib/GF bti 000.059 G00541 2008/11/07 18:58:34 tapelib2/G0 bti 000.059 H00143 2008/11/07 18:09:31 tapelib2/H0 bti 000.060 GB0147 2008/11/07 17:27:12 tapelib/GB bti 000.060 G00592 2008/11/07 18:05:39 tapelib/G0 bti 000.061 GB0337 2008/11/07 18:06:57 tapelib/GB bti 000.061 H00300 2008/11/07 18:54:26 tapelib2/H0 bti 000.061 GC0574 2008/11/07 18:54:26 tapelib/GC bti 000.061 G00562 2008/11/07 19:06:16 tapelib2/G0 bti 000.061 GC0575 2008/11/07 18:54:26 tapelib/GC bti 000.061 G00319 2008/11/07 17:39:40 tapelib2/G0 bti 000.061 G10018 2008/11/07 17:14:22 tapelib/G1 bti 000.062 G40051 2008/11/07 17:14:22 tapelib/G4 bti 000.063 G40169 2008/11/07 18:54:26 tapelib/G4 bti 000.063 G30567 2008/11/07 18:13:17 tapelib/G3 bti 000.064 G10019 2008/11/07 17:19:14 tapelib/G1 bti 000.064 G10058 2008/11/07 18:39:58 tapelib/G1 bti 000.064 G50379 2008/11/07 17:23:39 tapelib/G5 bti 000.064 G00312 2008/11/07 17:36:26 tapelib2/G0 bti 000.064 H00111 2008/11/07 17:43:25 tapelib2/H0 bti 000.064 GB0318 2008/11/07 17:58:40 tapelib/GB bti 000.065 G00110 2008/11/07 17:01:29 tapelib2/G0 bti 000.065 GA0560 2008/11/07 17:54:14 tapelib/GA bti 000.065 G70006 2008/11/07 18:39:58 tapelib/G7


Still in Use Report

The Still in Use report processes the Virtuent DR Logs (see the section title “DR Logging” on page 46) and produces a list of tapes that have been mounted and never unmounted.

VOLSERS STILL MOUNTED : NODENAME DEVICE VOLSER LAST MOUNTED PATH bti A405 GF0825 2008/11/10 10:23:18 tapelib/GF bti A404 GF0826 2008/11/10 10:23:18 tapelib/GF bti A419 G09009 2008/11/07 19:26:43 tapelib/G0 bti A415 G09005 2008/11/07 19:26:43 tapelib/G0 bti A414 G09004 2008/11/07 19:26:43 tapelib/G0 bti A413 G09003 2008/11/07 19:26:43 tapelib/G0 bti A40F H00365 2008/11/10 10:23:18 tapelib2/H0

Chapt

Overvie

Configu

Global

ter 5. U

ew

In z/Othe oprequesdrive.volumInsteaLoad Virtueused twheth

uration Pa

Whenbe spepage (

Using Vir

OS and OS/3perating systst for a volum Virtuent use

mes. Howevead, VSE showDisplay coment using justo send a Loaher you are u

arameters

n configuringecified as an(See Figure

ALLOWV

rtuent wi

90 environmem. Originame on a speces the Load er, VSE doews either the

mmand, so mst the operatiad Display c

using Epic, D

Unique to

g Virtuent fon additional p5.1 ) in orde

VSEUTILITI

Figure

C

ith VSE

ments, Virtuelly, these cocific tape driDisplay com

es not send Le job name o

mount requesing system fucommand to Dynam/T or

o VSE

or use with Vparameter iner to allow th

IES YES

5-1. Global O

Chapter 5. U

E

ent receives ommands infive by lighti

mmands to mLoad Displayor the mountsts cannot befunctions. In

Virtuent. Tno TMS.

VSE systemsn the Global ohe VSE utilit

Options for VS

Using Virtuen

Load Displaformed an oping the LCDmount scratchy commandsted volume se fulfilled aunstead, a utilThe program

s the followinoptions sectities to work

SE Systems

nt with VSE/

ay commandperator of a m on the top oh tapes or in

s the way z/Oserial numbeutomatically lity program used depend

ng parameteion on the Dproperly:

/ESA 55

ds from mount of the nput OS does. er in the by must be

ds upon

er should Device


Device Specific

When configuring virtual devices for VSE use, there are two device specific parameters used to help direct mount requests and send replies to the VSE console.

OSADDR – This parameter is required to specify a 4 digit address (0180) for each drive to use when replying to a mount request from a TMS or VIRMOUNT. Note: There may be a difference between the real channel address and the VSE address when running VSE under VM.

GROUP – Used to define several devices for use by one VSE system. When more than one VSE LPAR, CPU, or guest share a Virtuent controller, you must set up a separate group for each VSE. This allows the screen scraper or the VIRMOUNT program to ensure that when a mount request is received, the volume is mounted on a virtual address belonging to that VSE.

See the section ‘Adding Devices’ in the chapter Configuring Virtual Devices for more detailed information.

VSE Programs

The following VSE programs are supplied with all Virtuent-based controllers:

VIRMOUNT– Utility for mounting volumes in a non tape manager environment or for some specialized situations such as mounting an unlabeled tape.

VIRSSE and VIRSSD – REXX scripts for the EPIC or Dynam/T environments that are run continuously, usually in a dynamic partition.

VIRLDSPL – An assembler subprogram that is invoked by the REXX scripts.

VIREPSCR and VIRDTSCR – Programs are used to scratch volumes used by Epic and Dynam/T respectively. Uses a module supplied by the TMS vender to access the catalog and search for volumes in scratch status. The volume is placed in scratch status and will eventually be overwritten as space is used up, but it is not erased during this execution.

VIREPERA and VIRDTERA - Programs are used to erase the contents of volumes used by Epic and Dynam/T respectively. Uses a module supplied by the TMS vender to access the catalog and search for volumes in scratch status. If the volume has already been scratched by the VIRxxSCR program, then it will be erased to free up space. Use of these programs is optional.

VIRMAINT – Program reads commands on SYSIPT and can be used in a non tape manager environment to scratch, erase, or unscratch volumes. It can also be used in TMS environments. Note: Use of the erase function can result in lost data if used improperly. Make sure of your SYSIPT data when running this program.

Chapter 5. Using Virtuent with VSE/ESA 57

VIRCMD – Program reads SYSIPT and sends console commands or script execution commands to the unit.

VIRDTEXT – Dynam/T message exit program that may be used instead of VIRSSD screen scraper. Invoked by DTOPTIONS MSGHOOK(VIRDTEXT).

VSE Sample Jobs

Please note: These are samples of JCL and may need to be modified to fit you environment and library requirements.

JMOUNT – Execute the VIRMOUNT program

JVIRSSE and JVIRSSD – Executes the Epic or Dynam/T screen scraper REXX script (VIRSSE or VIRSSD).

JEPSCR and JDTSCR – Executes the Epic or Dynam/T scratch utility (VIREPSCR or VIRDTSCR).

JEPERA and JDTERA – Executes the Epic or Dynam/T erase utility (VIREPERA or VIRDTERA).

JVIRMNT – Executes the VIRMAINT utility.

JVIRCMD – Executes the VIRCMD utility.

Tape Drives

A tape drive address must be configured in VSE for each active virtual tape drive defined to Virtuent. In addition, when a tape management system like Dynam/T, CA-EPIC, or BIM-EPIC is in use one tape drive address will be reserved for use as a control device and will not be available for use by VSE applications. It is not recommended that you mix device types on one unit, but if you do so, make sure you allocate device types on a control unit boundary (usually 16 devices per CU).

VSE

You may use the following device types:

3490E Mode EML

3590B (TPA) Mode EML

EPIC ERD 3490E - ADD UCB=CUU,DEV=3490,FEAT=EI

3590B - ADD UCB=CUU,DEV=TPA,FEAT=TI


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


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 (A00000-A99999), it might look like this:

Nodes=2 Node1=0180 Node2=0390 Ownid1=A

To invoke the exit program after it is catalogued, set

DTOPTIONS MSGHOOK(VIRDTEXT)

And restart Dynam/T.

Using Dynam/T

The VIRSSD REXX script or Dynam/T message exit look for CADT008D and CADT004D mount messages issued by Dynam/T. CADT008D messages (mount a scratch volume) are checked for the required owner id and are ignored if it does not match. The CADT004D messages (mount an input volume) are checked for a volume label starting with the same character(s) as the owner ID and are ignored if the there is not a match.

When the Dynam/T mount message indicates that the input or scratch volume belongs to Virtuent, the volume will be mounted on an available virtual tape address, and the CADTxxxx message will receive a reply with the drive address.

Create New Tape Data Sets

JCL statements that define new tape data sets to the Dynam/T catalog which will reside on a Virtuent volume must include the OWNER=c, and CLOSE=UNL parameters. The CLOSE=UNL parameter is important to ensure that the virtual volume is not left mounted after the job completes.

Example – Define a Dataset for the VTC

// JOB DEFINE // EXEC DYNCAT DEFINE 'VIR.TEST.1' TAPE OWNER=B CLOSE=UNL /* /&

Prepare a Scratch Pool

Virtuent has a console command (INIT) used to initialize scratch tape volumes in groups by specifying a starting volume number and the number of volumes to create. You should use the following example to create a scratch pool in the DYNAM


catalog and specify the same volume numbers as you created on the Virtuent controller. Note that the first character of the volume numbers must match the Owner ID used for VIRSSD or VIRSSE and the dataset definitions.

NOTE: You must specify PROTECT=YES in your Dynam/T option macro to allow volumes defined with SCRPOOL to be opened by Virtuent without physically initializing them.

It is extremely important that Virtuent volumes have been predefined with SCRPOOL.

If Virtuent mounts a scratch volume which has not been defined with SCRPOOL, Dynam/T will reissue the mount message. Conversely, if you have plenty of volumes defined in the scratch pool, but you have not created them on the virtual library with using the Virtuent INIT function, the mounts will not be satisfied and you will get messages on the Virtuent console that there are no volumes available.

EXAMPLE – Prepare a Scratch Pool for the VTC

// JOB DYNAM SCRPOOL // EXEC DYNCAT SCRPOOL FIRSTVOL=A00000 LASTVOL=A99999 DEN=NO OWNER=A /* /&

Volume Scratching and Erasing with Dynam/T

When tapes are changed to scratch status in the Dynam/T catalog, it is necessary to inform Virtuent to scratch the virtual tape files associated with those volumes; making the volumes available again as scratch tapes. The VIRDTSCR program is provided for that purpose.

VIRDTSCR is provided on the Virtuent Utilities CD in the file /UTIL/VSE/VIRDTSCR. The file includes the assembler source code along with sample JCL statements for cataloging VIRDTSCR. Access to the vendor supplied DYNACC object module is required. Modify the JCL to meet your installation’s needs and catalog the VIRDTSCR phase into a VSE library.

The sample JCL below runs the VIRDTSCR utility to scratch volumes on the tape library. You must specify a parm with the owner ID. If you have more than one library prefix, you need to execute the program again with that owner ID.

// JOB JSCRTCH SCRATCH VIRTUAL TAPE VOLUMES // ASSGN SYS005,421 ASSIGN TO AN AVAILABLE DEVICE ADDRESS // EXEC VIRDTSCR,SIZE=AUTO,PARM=’B’ // EXEC VIRDTSCR,SIZE=AUTO,PARM=’C’ /&

Once volumes are scratched on the tape library, they are eligible to be overwritten in the future should the storage capacity reach a predefined threshold. If you wish to


free up space before that, VIRDTERA can be used. This will look in the Dynam/T catalog for scratch volumes that match the volume prefix in the user supplied parm and, if the volume is scratched on the virtual tape library, it will be erased down to the VOL1 and HDR1 labels.

VIRDTERA is provided on the Virtuent Utilities CD in the file /UTIL/VSE/VIRDTERA. The file includes the assembler source code along with sample JCL statements for cataloging VIRDTERA. Access to the vendor supplied DYNACC object module is required. Modify the JCL to meet your installation’s needs and catalog the VIRDTERA phase into a VSE library.

The sample JCL below runs the VIRDTERA utility to erase scratch volumes on the library. You must specify a parm with the owner ID. If you have more than one library prefix, you need to execute the program again with that owner ID.

// JOB JERASE ERASE VIRTUAL TAPE VOLUMES // ASSGN SYS005,421 ASSIGN TO AN AVAILABLE DEVICE ADDRESS // EXEC VIRDTERA,SIZE=AUTO,PARM=’B‘ // EXEC VIRDTERA,SIZE=AUTO,PARM=’C‘ /&

BIM-EPIC ACL Support

The support described in this section is provided by BIM-EPIC Release 6.4B and above. BIM-EPIC users with a single Virtuent controller or multiple Virtuent controllers that do not share volumes, are encouraged to use this option. Synchronization between the BIM-EPIC catalog and the Virtuent controller is done automatically.

BIM-EPIC supports the Virtuent controller as an Automatic Cartridge Loader (ACL) device in the same manner it supports ACL’s from other vendors.

BIM-EPIC uses an application program interface (API) to communicate directly with Virtuent in order to mount, scratch, or unscratch Virtuent-resident tape volumes. None of the Virtuent supplied VSE utilities described elsewhere in this manual are used in these activities.

The “BIM-EPIC Installation and System Guide” describes how Virtuent is defined to BIM-EPIC.

BIM-EPIC tape pools must be used for Virtuent-resident tape volumes. Their definition must correspond to the Virtuent volser prefix used. The “ MAS Support” section of the “BIM-EPIC Installation and System Guide” describes how this is done. (Note: Mainframe Appliance for Storage or MAS was the original product name for Virtuent-based controllers). All references to tape volume serial numbers required are now user definable as a one character prefix. IE: B or A, etc. followed by 5 digits. Make sure the tape pool consists of the same volume serial numbers as you define with the Virtuent INIT function.


For each VSE BIM-EPIC system (VM Guest, LPAR, or physical CPU) that will use the same Virtuent controller, a "control drive" must be reserved to communicate with Virtuent. This drive is not usable for tape I/O purposes, but is required for BIM-EPIC's internal use.

VIRSSE Utility for EPIC Operation

Installation of VIRSSE is only required if your system is running EPIC and you are not using the BIM ACL support.

The REXX procedure VIRSSE captures mount requests issued by EPIC and sends them to Virtuent. VIRSSE runs continuously under VSE. VIRSSE uses an assembler program named VIRLDSPL to send load display messages to Virtuent.

Three installation steps must be completed to successfully install VIRSSE:

1. You must catalog the VIRLDSPL phase into a VSE Library.

2. You must catalog the VIRSSE procedure into a VSE library.

3. You must tailor the JCL and set the correct parms for the REXX script.

VIRLDSPL is provided on the Virtuent Utilities CD in /UTIL/VSE. The file includes the assembler source code along with sample JCL statements for cataloging VIRLDSPL.

VIRSSE is provided on the Virtuent Utilities CD in /UTIL/VSE.

Once VIRLDSPL and VIRSSE are cataloged you can tailor the JCL to send mount requests to Virtuent.

The parameters separated by spaces are as follows:

Single digit indicating the number of units or nodes supported (1 – 6).

One character Pool ID used for the first volume pool and library.

Synonym used for scratch requests for the first library. If no synonym is specified on the unit, use SCRTCH.

Optional parms if more than one prefix/library is used:

One character Pool ID used for the second volume pool and library.

Synonym used for scratch requests for the second library. If no synonym is specified on the unit, use SCRTCH.

One character Pool ID used for the third volume pool and library.

Synonym used for scratch requests for the third library. If no synonym is specified on the unit, use SCRTCH.

Sample execute statement for EPIC environment:


// 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), X (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 installation’s needs and catalog the VIREPSCR phase into a VSE library.

The sample JCL below runs the VIREPSCR utility to remove scratch volumes from the Virtuent library. You must specify a parm with the Pool ID. If you have more than one Pool prefix, you need to execute the program again with that Pool ID.

// JOB JSCRTCH SCRATCH VIRTUAL TAPE VOLUMES // ASSGN SYS005,421 ASSIGN TO AN AVAILABLE DEVICE ADDRESS // EXEC VIREPSCR,SIZE=AUTO,PARM=’B’ // EXEC VIREPSCR,SIZE=AUTO,PARM=’C’ /&

Once volumes are scratched on the Virtuent library, they are eligible to be overwritten in the future should the storage capacity reach a predefined threshold. If you wish to free up space before that, VIREPERA can be used. This will look in the EPIC catalog for scratched volumes matched the Pool ID in the user supplied parm and, if the volume is scratched on Virtuent, it will be erased down to the VOL1 and HDR1 labels.

VIREPERA is provided on the Virtuent Utilities CD in the file /UTIL/VSE/VIREPERA. The file includes the assembler source code along with sample JCL statements for cataloging VIREPERA. Access to the vendor supplied DYNACC object module is required. Modify the JCL to meet your installation’s needs and catalog the VIREPERA phase into a VSE library.


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 user’s responsibility to put the necessary command(s) inside the script to make it do so.

Scripts invoked by the RUN command will not be able to read from standard input (the keyboard). stdin will be closed before starting the script process, so any program attempting to read from stdin will get an error (end of file). This doesn't prevent redirection of input to programs from within the scripts.

All output from the scripts will by default be discarded. If a script's output needs to be retained (in a file, for example), it is the user’s responsibility to put the necessary redirection command(s) inside the script to make it do so. The feedback returned to the Host from Virtuent says whether or not the Virtuent command itself (in this case, RUN) was successfully executed. This says nothing about whether the invoked script itself, or anything run in the script, successfully accomplished anything.

If the RUN command without the WAIT option is used, Virtuent will return status to the Host as soon as the RUN command is executed; the invoked script will continue to run asynchronously for however long it takes. There will be no notification to the Host when (or if) the script ends. Additional commands could be sent to Virtuent while the script is executing in the background.

If the RUNWAIT variation is used and the RUNWAIT command execution is successful, Virtuent will wait for some time for the script to complete before returning status to the Host. You can specify the optional maximum wait period in seconds. Syntax requires the wait period to be specified in parenthesis to distinguish it from the script number. If omitted, the default is 110 seconds. If the script completes within the time limit specified, Virtuent will return a successful status code to the Host. If the script does not complete within the time limit specified, Virtuent will cancel the script at the expiration of the time limit and return a failure status code to the Host.


With the WAIT option, the drive will be "busy" executing a Load Display (x'0F') CCW throughout the wait period. If the wait for completion exceeds the Host's missing interrupt time limit, the Host application will abend because of a missing interrupt.

Example:

// JOB JCMD SEND COMMANDS TO VIRTUENT // ASSGN SYS005,421 ASSIGN TO AN AVAILABLE DEVICE ADDRESS // EXEC VIRCMD,SIZE=AUTO Q SPACE (display storage usage) UNREADY 425 (make a virtual drive not ready) UNLOAD 425 (unload a virtual drive) RUN 2 (run script #2) RUN 21 (run script 21) RUNWAIT (300) 32 p1 s2 (run script 32 with a time limit of 300 seconds and pass 2 arguments, p1 and s2) /* /&

Chapter 6. Using Virtuent with VM 73

Chapter 6. Using Virtuent with VM Virtuent tape devices can be used by VM just as any other 3480, 3490, or 3590 tape drive would be used. Bus-Tech provides two small utilities for VM / CMS. VTSCR is a scratch utility that can be used to scratch VOLSERs on the MDL that are no longer needed. VTCMD is a command utility that will send MDL commands to a Virtuent controller.

Like VSE, VM does not send any Load Display CCWs over the channel when a tape volume needs to be mounted. There are 3 methods that can be used to send mount requests to MDL:

1. Use DMSG utility for CMS. This utility, available as part of a VM download package from IBM, is specifically intended to send a LOAD DISPLAY CCW to a tape device. The CMS user simply issues the DMSG command with a tape device address and VOLSER. MDL recognizes the Load Display CCW and mounts the VOLSER on the drive.

2. Use VTCMD and send an MDL Mount command to the MDL. This is equivalent to using DMSG except that the MDL MOUNT command allows you to mount the VOLSER on a different device than the device the VTCMD uses for sending the command.

3. You can create (or modify) your own program to send a standard Load Display CCW to the MDL.

Installing VTSCR and VTCMD

To install VTSCR and VTCMD in VM you will need to upload files from the MDL Utilities CD to your mainframe. The files you will need are located in the directory /UTIL/VM and are named VTSCR.MODULE and VTCMD.MODULE. You will need to FTP them to the system in binary, and set FIX 1024 before the put of VTSCR MODULE and VTCMD MODULE as in:

ftp> bin ftp> quote site fix 1024 ftp> put vtscr.module ftp> put vtcmd.module

Once they are transferred, they must then be unpacked:

copyfile vtscr module a (unpack copyfile vtcmd module a (unpack

The modules are now ready to be executed.


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 Invalid data length (must be between 1 and 256 bytes)

0x02 The MDL is configured to not accept Host-initiated console commands

0xFF(-1) A general syntax error occurred. (The MDL console error message “MDL891E: Invalid command syntax” was displayed.)

0xFC (-4) An “E” level error other than general syntax error occurred. (A MDL console error message other than MDL891E was displayed.)

A sample VTLOG output might be as follows:

VTCMD VER 1.0 VTCCTRL = EA82

2004/09/10 12:47:49 CMD ERR=FF: this is an invalid command

2004/09/10 12:47:49 CMD ISSUED: q all

2004/09/10 12:47:49 CMD ERR=FC: q xxxxxxxx

2004/09/10 12:47:49 CMD ISSUED: set size=2g dev=EA80

Using VTCMD to Mount a VOLSER

VTCMD can be used to mount a specific tape volume (VOLSER) on an MDL tape drive using the MDL LOAD Command.

For example, if the contents of VTCMD INPUT A contains:

LOAD VOL=000101 DEV=cntrl0001 SL

Issuing the CMS command:

VTCMD 180

Results is the VOLSER ‘000101’ being mounted on the MDL drive named ‘cntrl0001’

To mount a new scratch volume substitute “SCRTCH” or “PRIVAT” for the VOLSER.

Alternatively, the following command sequence entered from CMS will have the same results:

VTCMD 180 OPER

CMD=LOAD VOL=000101 DEV=cntrl0001 SL

END

Chapter 7. Using Virtuent with Unisys 79

Chapter 7. Using Virtuent with Unisys Virtuent controllers with ESCON interfaces installed can connect to Unisys 2200 mainframes running OS-2200. This chapter discusses issues unique to Virtuent support of Unisys mainframes.

Unique Virtuent Operations for Unisys Mainframes

Autodetection

Virtuent automatically detects that it is attached to a Unisys host when it receives a Load Display containing data that is unique to a Unisys mainframe. When this occurs, a message is displayed on the Virtuent console (“VIR080I: Device devicename UNISYS detected”). You can confirm that Virtuent has recognized that a drive is attached to a Unisys mainframe by reviewing the messages displayed on the Virtuent console or by performing a QUERY CONFIG command (see below).

Load Displays

Unisys does not send the normal ‘M’ mount message; Virtuent determines a Unisys mount request by the FCB byte containing x’48’, and then moves the volser into the proper position for a mount message.

Mount “Ready” Interrupt

The Unisys mainframe does not expect a Not-Ready-to-Ready interrupt when the Virtuent device comes ready. After sending the Load Display, the Unisys mainframe performs repetitive Senses to detect when the device is ready. To accommodate the way the Unisys mainframe works, Virtuent does not send an interrupt when a mount is initiated by a Load Display like it normally would. However, it does send an interrupt when a manual mount is performed at the Virtuent console, and when a manual Not Ready to Ready transition is performed.

Query Config command

The Virtuent Query Config command will display an additional parameter, UNISYS=YES, for a device that has been determined to be attached to a Unisys mainframe.

Ring-Out Mount Request

The Unisys Load Display mount request uses the 8th position of the mount message as a file protect indicator. If that position contains the character ‘F’, the Unisys mainframe expects to have the tape mounted “ring-out” (read-only). Virtuent will honor the ‘F’ indicator and mount the requested volume in read-only mode.


Scratch Request

When a Unisys host asks for a scratch tape, MDL will ignore the label type (either explicitly requested in the mount request or implied by the LABEL=x configuration parameter) and will pick any available scratch tape. This behavior is applicable only to Unisys-attached devices. All non-Unisys devices will continue to honor label type for scratch mount requests.

Configuring for Unisys

Device Type

When configuring devices for use by a Unisys mainframe the Device Type should be set to ‘3490’.

Labels

When the Unisys operating system sends a Load Display mount message, it does not specify a label type. Unisys always expects an ANSI label by default. To accommodate this, you must configure each Unisys-attached device with the LABEL=A parameter. This will change the Virtuent default for this device to ANSI labels instead of IBM standard labels. Figure 7-1 shows a sample device definition screen where sixteen tape drives are being defined including the LABEL=A parameter.

Scratch Tapes

The Unisys operating system does not send the “MSCRTCH” message to request a scratch tape as an IBM mainframe would. Instead it sends an “L-BLNK” command. To accommodate for the L-BLNK command, you must specify a scratch synonym equal to “L-BLNK”. Figure 7-1 shows a properly configured scratch synonym for Unisys mainframes.

Initializ

Configu

zing Tape

WhenLABEwill fo

For exdrive

uring the M

VirtueCTS5.PTN

The U

s for Unisy

n initializing EL=A optionollow the AN

xample, to inE980, you w

INITIALIZ

Mainfram

ent devices a136-VSM (nfile must be

Unisys equipm

F

ys

tape volumen on the initiNSI standard

nitialize 100 would enter t

ZE VOL=B0

me for Virt

are configurenon-library)

e installed an

ment code fo

Figure 7-1. Un

es to be usedialize commad.

tapes beginnthe following

00000 DEV=

tuent

ed in OS220subsystems

nd the OS reb

for Virtuent d

Chapter 7

nisys Device P

d with Unisyand to tell th

ning with Vg initialize c

=E980 COU

00 using SCMof 1 to 16 u

booted with

devices is U

7. Using Virt

Panel

ys you must he system th

VOLSER B00command:

UNT=100 LA

MS / SCMS-units. The re

the proper d

47M.

tuent with U

include the at the tape la

0000 using t

ABEL=A

-II as 1 or mesulting ODBdefinitions.

Unisys 81

abels

tape

more B or

Chapt

VT Con

ter 8. SyOnce the mastart o

nsole

The vand is(node

A sepConfion thethe coa vt coapplic

Whenopen oapplic

OperaapplicLikewactivetape (v(Figur

ystem Opthe storage iainframe has

operating the

irtual tape aps known as “) is powered

arate prograguration proe status paneontroller’s (nonsole sessiocation.

never you clion the desktocation. Figur

ation of the vcation will ofwise, the vt ce. Once the Vvt) applicatire 8-1).

perationis attached as been confie Virtuent co

pplication ru“vt”. vt will d on and brou

am named vt ogram’s Statel for each conode’s) log inon allowing

ick the Consop and beginre 8-2 shows

vt applicationften be runn

console progrVirtuent conon at anytim

n and configuregured (and r

ontroller.

uns as a startattempt to aught up.

console cantus panel. Aontroller (nonformation.you to moni

Figure 8-1

sole icon forn displaying s a sample o

n daemon is ing even whram can be r

ntroller is runme by clickin

C

ed, the virture-initialized

ted task (daeautostart whe

n be run at anAs shown in Fode) in the M

The Consoitor and oper

1. Status Panel

r a specific cg messages frof an active v

independenhen the vt corunning withnning you cang the Conso

Chapter 8. S

ual tape devicd if necessary

emon) on theenever the M

nytime fromFigure 8-1 th

MDL; the leftole icon on thrate the Virtu

l

controller (nrom the virtuvt console w

nt of the vt coonsole prograhout the vt apan check theole icon on th

System Oper

ces are definy), you are r

e MDL contrMDL controll

m the Virtuenhere are twot icon will dihe right willuent tape-on

ode) a consoual tape (vt)

window.

onsole. Theam is not stapplication be

e status of thehe Status pan

ration 83

ned, and ready to

roller ler

nt o icons isplay l initiate n-disk

ole will

e vt arted. eing e virtual nel

884 Virtuent

User’s Guid

vt consolethey are ismessages log.

The followmessages

Ho

En

Pg

Pg

The bottocurrent stain Figure command

The follow

Up

Do

Le

Ri

Ct

De

Ct

Ba

de

e is split intossued from tin the log si

wing naviga:

ome – Move

nd – Move to

gUp – Move

gDn – Move

om or smalleatus of the v8-2, the vt a

d line where

wing naviga

p Arrow or C

own Arrow

eft Arrow – m

ight Arrow o

trl+A – mov

el or Ctrl+D

trl+E – move

ackspace or

Figu

o two sectionthe vt applicince the last

ation keys (o

e to the top

o the bottom

e up one scre

e down one s

r section of virtual tape (vapplication isyou may ent

ation keys ca

Ctrl+P – pre

or Ctrl+N –

move 1 char

or Ctrl+F – m

ve to the begi

D – delete one

e to the end

Ctrl+H – ba

ure 8-2. Activ

ns. The largation. On ststartup of vt

r commands

m

een

screen

vt console dvt) applicatis not runningter and edit v

an be used on

vious comm

next comma

racter to the

move 1 chara

inning of the

e character

of the line

ackward dele

ve vt Console

ger, top sectitartup vt cont console or

s) can be use

displays in blon on this cog. Below thvt command

n the comma

mand in histo

and in histor

left in the co

acter to the r

e command l

ete character

ion displays nsole will disthe last 100

ed to scroll th

lue and alwaontroller (no

he VT Status ds.

and line:

ory

ry

ommand line

right in the c

line

r

log messagesplay all ,000 bytes o

hrough the

ays shows thode). As sho line is a

e

command lin

es as

of the

he own

ne

Chapter 8. System Operation 85

Ctrl+K – erase to the end of the line

Ctrl+T – transpose characters

Ctrl+U – discard the line

Ctrl+W – word rubout

To close the vt Console window click the close window button in the top right corner of the screen. The console window will immediately close. Closing the console does not affect the operation of the virtual tape (vt) application in any way.

Starting / Stopping Tape Devices

To start or stop the virtual tape devices you must start or stop the virtual tape (vt) application. Control of the vt application is through the vt Console window (see Figure 8-2). The commands for starting and/or stopping tape emulation on a controller (node) are:

STARTVT to start the vt application and activate devices in the installed configuration file

STOPVT to stop the vt application. Once the application stops, the channel links are disabled and all virtual drives will cease responding to the host until the application restarts. Any I/O from the host while the application is terminated will receive an I/O error (device not operational). For this reason, you should wait for all host applications using devices to finish, and the virtual tape drives should be varied offline from the host operating system before stopping the vt application.

STOPVT will not terminate the application if any virtual drives currently have volumes loaded.

STOPVT! To terminate the application while volumes are loaded. Any virtual tapes currently loaded will be immediately unloaded without any further processing.

Note that this may result in an incomplete output tape volume if the host has not yet completed writing and properly closed the tape. For this reason, the STOPVT! command should only be used in an emergency situation where Virtuent must be brought down immediately. Any virtual tape volumes currently being written should be considered invalid.

When the vt application is active, the VT Console window will show the VT status as “Running” and informational, warning, and error messages from the vt application will scroll on the console (See Figure 8-6).

8

I

86 Virtuent

Initializing

User’s Guid

g Scratch

Before Vitape volumfirst time commandthe tape li

As explaiand may bvolumes iinto each Virtuent wclass and

If you havonly needdefined meach class

The comm

INIT

Where vo(address) numbers t

de

Volumes

irtuent can mmes that youyou start any

d in the Consibrary for Vi

ned in Chapbe sub-dividinto each andstorage clas

will not be abthe mount w

ve not defined to initializemultiple storas you have d

mand to initi

TIALIZE VODI

olser is the stof any tape to initialize,

Figure 8-3

mount a tapeu want Virtuy tape drivessole windowirtuent to use

pter 2, a Virtuded into storad every filess. If there able to satisfy

will remain p

ed storage cle a single ranage classes thdefined.

ialize tapes i

OL=volser DR=dirname

tarting serialdrive pointinn is the clas

3. VT Console

volume in tuent to use ws on Virtuen

w (Figure 8-2e.

uent library age classes. system. But are no scratcy a mount repending.

lasses (othernge of tape vhen you mus

s:

EV=devnam

l number to ing to the tapss these volu

e when vt is A

the tape librawithin that libnt you must i2) or there w

is made up o You do notyou do need

ch volumes iequest for a s

r than the defvolumes to thst initialize a

me COUNT=

initialize, depe library, coumes are to b

Active

ary you musbrary. Thereissue at least

will be no scr

of one or mot have to initd to initializen a storage cscratch withi

fault class 0)he library. Ba range of V

=count CLA

evname is thount is the nube added to,

t initialize thefore the vert one Initialiatch tapes w

ore filesystemtialize new te tape volumclass then in that storag

), then you wBut if you h

VOLSERs for

ASS=n

he device namumber of serand dirnam

he ry ze

within

ms tape

mes

ge

will ave r

me rial e is a


specific directory the volumes should be placed in. DIR is an optional parameter. DIR is never required. If DIR is not specified INITIALIZE will place the volumes into the first filesystem it finds within the storage class. During processing, scratch tapes will be automatically moved as needed from one directory (filesystem) to another in the same storage class. However, if you wish to spread scratch volumes across multiple filesystems within a class you may use the DIR parameter to direct a range of tapes to a specific filesystem. CLASS is a required parameter.

Assuming device E980 is a configured device pointing to your tape library then the command to initialize 500 serial numbers to the storage class 0 beginning with VOLSER 000000 would be:

INITIALIZE VOL=000000 DEV=E980 COUNT=500 CLASS=0

This would result with volumes ranging from 000000 – 000499 being created in the first filesystem in class 0.

If your library has two storage classes defined, class 1 and class 2, then the following commands would initialize 1000 volsers into the library making both classes ready for use:

INITIALIZE VOL=000000 DEV=E980 COUNT=1000 CLASS=1 INITIALIZE VOL=001000 DEV=E980 COUNT=1000 CLASS=2

Since the INITIALIZE program automatically generates VOLSERs starting with the VOLSER specified with VOL=, be careful to make sure you do not overlap VOLSER ranges when entering these commands. In the example above VOL=0000000 COUNT=1000 will result in the 1,000 tape volumes being created in the library with serial numbers ranging from 000000 to 000999. VOL=001000 COUNT=1000 will result in volumes ranging from 001000 to 001999 being created. The result of these two commands is a virtual library with 2,000 volumes whose serial numbers range from 000000 – 001999.

If you are initializing tapes on a Unisys mainframe, include the LABEL parameter telling Virtuent the tape volume labels will be ANSI format. For example,

INITIALIZE VOL=000000 DEV=E980 COUNT=500 LABEL=A CLASS=0

Be aware! On IBM mainframes if your tape devices are being defined in an MTL you will also need to define them to the mainframe’s tape configuration database (TCDB). This is accomplished by running the VTLIB utility. See page 34 for instructions on running VTLIB. For a full description of the INITIALIZE command refer to the command list in the next section.

Virtual Tape Operator Commands

When the virtual tape (vt) application is active and the VT Console window is open (See Figure 8-2), there are several virtual tape commands that can be used to control


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: Compression level set to 1 (0=none,1=faster,9=smaller) VIR010I: Compression hardware available VIR011I: Compression driver version: 1.0.8 VIR012I: Compression card #0: id=9 version=200 state=00000000 VIR013I: Hardware compression set ON VIR013I: Hardware decompression set ON

QUERY CONFIG shows detailed configuration information for all devices.

QUERY ENCRYPTION shows the status of the Virtuent encryption keys.

QUERY LABELS shows the header labels, if any, for all mounted tapes.

QUERY LOCKS shows any tape volumes with locks associated with them.

QUERY MOUNTED displays information only about the drives that currently have virtual tape volumes mounted.

QUERY PATHS shows all of the channel paths established for the Virtuent devices. If ASSIGNED is specified, only channel paths with current host assignment (typically those varied online) are displayed.

QUERY SPACE shows a summary of the disk space used and available in all the tape libraries.

QUERY SCRATCHNAMES displays all of the scratch volume serial number synonyms currently in effect.


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.


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.


Otherwise the change takes effect immediately after the current volume is unloaded. The pathname is case-sensitive and must exactly match the disk directory name. Always specify the tape library base directory, i.e. "/tapelib", not a subdirectory of the tape library (i.e. "/tapelib/BA"). The specified tape library and any subdirectories are checked for logical errors, such as a tape volser being in the wrong subdirectory, and if any error is found the path will not be changed. If you absolutely must set the path to a directory which won’t pass validation, you can specify the NOCHECK parameter to accept the path even if it fails validation.

SET PATH can be used to assign a virtual device to a SCSI tape drive in order to use the Direct Tape feature (See page 121). To use SET PATH in this manner specify the SCSI tape driver name. For example: “SET PATH=DRIVE-nnnnnnnnnnnn”.

RECOVER=nnn sets the percentage of disk space usage at which Virtuent starts to recover disk space by deleting the data from scratch volumes (see page 135, “Deleting ("Erasing") a Scratch Volume's Data”). Valid values are from 0 to 100. The default is 95%. If the recovery percentage is set to 100, Virtuent will never automatically delete scratch volume data to recover disk space.

RECOVERAMT=nn sets the maximum amount of space (in percentage of disk space) that Virtuent will attempt to recover once the recovery threshold is reached. The default is 1%.

SIZE=xxx sets the maximum volume size for virtual tape volumes. The valid range is 2M to 32T. A specific DEVICE can be specified, or ALL devices at the same time (the default). The size can be specified as bytes, kilobytes, megabytes, gigabytes, or terabytes (e.g. "SIZE=1500000", "SIZE=500000K", "SIZE=500M", "SIZE=1.5G", “SIZE=1T”). The new size specification takes effect immediately. If a tape is being written at the time the SIZE is changed and the position on the tape is already past the new SIZE value, logical end of volume warnings will be sent on all subsequent write/write tapemark commands, and physical end of volume will be signaled approximately 1 MB past the current position.

TIMESTAMPS=NO/YES indicates whether or not date and time should be included in each message sent to the console display. The default is NO; reducing the amount of data appearing on the console. Messages written to the log files are always timestamped. This parameter only affects messages to the console.

TRACE=n sets the trace level for a specific device if a DEVICE=devicename is specified. If SYSTEM is specified, the trace level is set for the general, non-device specific system trace. If ALL is specified, the trace level is set for all devices plus the general system trace at the same time. The default is ALL if no DEVICE is specified. Valid trace levels are 0 (no tracing) to 4 (trace a lot); the default is 1 (trace errors only).

WARNING=nnn sets the percentage of disk space usage at which Virtuent will begin to warn about usage. The valid range is 0 to 100. The default is 75%.


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 re-initialize by re-loading its operating environment from internal disk. Reboot of a controller will take 5 to 10 minutes to complete.

To reboot a Virtuent controller go to the Status panel in Virtuent Configuration and click the Reboot button next to the controller (node) you wish to reboot (Figure 8-7).

Set Dat

Note tbutton

te and Tim

The VConsoIf youExtern

TheremanuaNetwo

To mathe Se

If youmore Nthe co

Simplyou m

that if your Mn for each no

me

Virtuent systeole. System u need to adjunal panel of

are 2 methoally set a speork Time Pro

anually set det button. T

ur Virtuent coNetwork Tim

ontroller to g

ly enter eithemake this con

Figure

MDL systemode.

em time is ddate and timust the systeVirtuent Co

Figu

ods for settinecific date anotocol (NTP

date and timeThe date and

ontroller (Mme Protocol

get date and t

er the networnfiguration a

e 8-4. Reboot

m includes m

displayed in tme are used tem date or timonfiguration

ure 8-5. Chan

ng date and tnd time or y

P) server.

e simply adjutime will be

MDL) is conn(NTP) serve

time from th

rk name or Iactive by inst

C

t Button on St

multiple node

the status linto stamp tapme you may(Figure 8-5)

nging Date an

time on a Viyou can confi

ust the date e set in all co

nected to youers are acces

he server(s).

IP address oftalling it, the

Chapter 8. S

atus Page

es there will

ne at the botte volumes b

y do so from ).

nd Time

rtuent controfigure the sys

and time shoontrollers (no

ur corporate ssible, you c

f up to four Ne controller (

System Oper

be a separat

tom of the vtbeing created

the Time ta

oller. You cstem to use a

own and thenodes) in the

network andcan easily co

NTP servers(nodes) in th

ration 99

te Reboot

t d on disk. ab on the

can a

n press system.

d one or nfigure

s. When he


configuration will attempt to query the servers from 1 to 4 until it successfully gets date and time.

Note that if you use a network name to identify an NTP server you will need to configure a Domain Name Server (DNS) as part of the network configuration (see the Installation Guide that accompanied your system).

Virtuent Messages

Virtuent controllers continually generate informational, warning, and error messages as they operate. These messages are written to the internal system disk storage on the MDL so that they can be retrieved as necessary during problem determination. Messages will also be automatically displayed on the vt console whenever the vt console application is connected to the controller (node).

Additionally, Virtuent is capable of sending informational, warning, and error messages to any of the following:

- An SNMP management console - One or two customer e-mail addresses - A Bus-Tech support e-mail address (phone home) - The z/OS master console via a z/OS started task.

For sending messages to SNMP and to customer e-mail addresses there are two steps that need to be completed for messages to be sent:

1. Configure Virtuent with a message destination(s). 2. Configure which messages should be sent.

For Bus-Tech support e-mail (phone home) you need to simply tell Virtuent to send vendor messages.

For z/OS messages you must install the z/OS started task and then configure which messages you want sent.

Configuring SNMP Message Notification

To send messages to an SNMP management console your MDL must be connected to the network. To configure SNMP messaging you must enter the name or IP address of the SNMP manager on the Notify tab of the External panel on Virtuent Configuration (Figure 7-20).

You may enter one or two systems where you want SNMP management messages to be sent. If either of the SNMP manager host fields contain a valid host name or IP address then Virtuent will forward messages to that host. If both fields are blank then SNMP messaging is inactive.

Sending

E-mail

VirtueSMTPNotify

Mfo

Sem

Rem

Syfro

Optiondescrreceiv

Warnsent to“Confthousunlikemail s

Note: Tech “buste

ent will autoP mail servery tab of the E

Mail Server –rward the e-

ender emailessage. Thi

ecipient emessages to.

ystem nameom.

nally you miption. You

ve the e-mail

ing: Be suro your e-mafiguring Meands of infoely you woulserver.

You cannoe-mail addrech.com”.

Figu

omatically ser. To use thiExternal pa

– the IP addr-mails

– an e-mail is may or ma

ail address

e – the name

ay completeu may also ils.

re to review ail addressesessages to beormational mld want thos

ot send messesses. Virtu

ure 8-6. Conf

end messagesis capability

anel of Virtue

ress or host n

address youay not be a r

– the e-mail

of the Virtu

e a Companynclude a Sec

and understs before confe Sent”). Acmessages ovese messages

sages to Busuent will ign

C

figuring Notifi

s to one or twy you must fient Configur

name of an S

u want to be return e-mail

l address you

uent MDL co

y name, Cocond recipie

tand which mfiguring thective Virtuener a short pe to each be s

s-Tech by conore any e-m

Chapter 8. S

ications

wo e-mail adill out the foration:

SMTP mail s

included in l address.

u want Virtu

ontroller the

ntact nameent e-mail a

messages arem (Refer to nt controllereriod of timesent as an e-

oding the e-mmail address

System Oper

ddresses viallowing field

server that w

the from fie

uent to send

e-mail is be

, and Optionddress who w

re configure the section rs can genere and it is hi-mail to you

mail fields wthat include

ration 101

a an ds on the

will

eld of the

eing sent

nal will also

ed to be

rate ighly

ur SMTP

with Bus-es


Sending Vendor E-Mail (Phone Home)

Virtuent controllers use e-mail to provide a vendor “phone home” capabilities. Assuming your Virtuent controller is on a network and can send e-mail to an SMTP server, you can configure your controller to send pre-configured error messages to Bus-Tech support.

You cannot configure which messages get sent. You can only configure whether or not you want Virtuent to attempt to send vendor alerts (e-mails) or not.

To send phone home e-mail alerts to Bus-Tech support you must configure the following fields on the Notify tab of the External panel on Virtuent Configuration (Figure 7-20):

Mail Server – the IP address or host name of an SMTP mail server that will forward the e-mails

Mail sender name – a name to be included in the from field of the message. This may or may not be a return e-mail address.

Company name – your Company’s name.

System name – the name of the Virtuent MDL controller the e-mail is being sent from.

Contact name – a contact person’s name that Bus-Tech support can contact if necessary when responding to an alert.

To enable sending e-mail alerts to Bus-Tech support check the Notify Vendor check box.

Configuring Messages to be Sent

As previously indicated, Virtuent controllers send informational, warning, and error messages to SNMP management consoles, customer e-mail, Bus-Tech support, and the z/OS operator console. Using the Messages panel (Figure 8-7) in Virtuent Configuration you can configure which messages get sent to each destination.

As shoand erVirtueerror)represConso

All chcannois provsent to

For SNor you

For excan chtab. T

Warninformmay stime. an e-m

own, the Merror messageent messages. Also displsenting SNMole). At the

heck boxes inot modify whvided only too Bus-Tech a

NMP, Custou can configu

xample, if yoheck the toggThis will res

ing: Bus-Tmational mesend thousan

You must bmail to an e-

Fig

essages panees. Clickings in the categlayed are fou

MP, Vendor E top is a row

n the Vendohich messageo allow you and which w

omer Email, ure each me

ou want all wgle all checksult in all wa

Tech stronglyessages to yonds of informbe selective i-mail addres

gure 8-7. Mes

el has three ( on any one gory identifiur (4) check E-mail, Cust

w of “toggle a

r Email colues are sent toto see which

will not.

and Mainfrassage or eac

warning meskbox under Marning messa

y recommenour e-mail admational anin selecting wss.

C

ssage Configu

(3) tabs repreof the tabs s

ied by the tabboxes to thetomer E-maiall” check b

umn are for io Bus-Tech ah messages w

ame you canch category a

ssages to be Mainframe oages being se

nds not sendiddress(es).

nd warning mwhich messa

Chapter 8. S

uration

esenting infoshows a com

ab (informatie right of eacil, and Main

boxes.

information and which awill result in

n use the pre-as you want.

sent to your on the Warnient to the z/O

ing all warnAn active V

messages ovages are aut

System Oper

ormational, wmplete list of ion, warningch error mesframe (z/OS

purposes onare not. Thisn an e-mail b

-configured .

z/OS consoing messageOS console.

ning and Virtuent contver a short ptomatically s

ration 103

warning, f all g, or sage;

S

nly. You s column being

defaults

ole you routing

troller eriod of sent as

1

V

104 Virtuen

Viewing Me

nt User’s Gui

essage (Log)

Virtuent capplicatioare compr

From the Virtuent cicon for th8-8).

This will issued by messages

ide

) Files

controllers (non. Log filesressed to min

Virtuent Cocontroller (nhat controlle

result in a neVirtuent (Fi.

nodes) mains are automanimize the s

onfiguration ode). To vie

er (node) on

Figu

ew log windigure 8-9). Y

Figu

ntain a log ofatically rotatepace they ta

application yew a log filethe Status pa

ure 8-8. Openin

dow openingYou may scr

ure 8-9. Viewi

f all messageed each day

ake and then

you can viewe for a controanel of Virtu

ng a Log File

g; displayingroll back and

ing a Log file

es issued by at midnightkept for a p

w the currenoller simply uent Configu

g a list of recd forth throu

the virtual ta. Old log fileriod of time

nt log file on click the Louration (Figu

ent log messugh the day’s

ape les e.

a ogs ure

sages s log

User Ad

dministra

By dereadon

The adconfig

The rebut do

A useability

User aVirtue

VirtueDirectand pafirst in

WARNLDAPand yonetwoin not

As shoable towithou

You cover abox to

ation

efault Virtuennly. The def

dmin user haguration as w

eadonly useroes not have

r administray to add, dele

administratioent Configur

ent controlletory Access asswords onnstalled.

NING! Do P unless youou already h

ork. Failuret being able

own in Figuo view the cuut the Reado

can modify ean existing eo the right of

nt-based sysfault passwo

as full adminwell as monit

r can view ththe authorit

ation panel wete, or modif

on is performration (Figur

Fi

ers support twProtocol (LD

n the Virtuen

not attempt ur Virtuent chave the appe to successfto log in to

ure 8-10, theurrent configonly attribute

existing namntry. You cf the user nam

stems ship word for these

nistrator rightor and cont

he configuraty to modify

within Virtuefy user name

med from there 8-10).

igure 8-10. Us

wo types of uDAP). Nativ

nt controller a

to change thcontroller (Mpropriate dirfully attach tthe Virtuent

e Readonly aguration ande set are syst

mes, passwordan remove ame.

C

with two defa two user na

hts and can ctrol operation

ation and checonfiguratio

ent Configures recognize

e Authentica

ser Administr

user adminisve user admand is the de

the authenticMDL) is attarectory serveto an externt Configura

attribute restrd status of thtem adminis

ds, or read oa user from t

Chapter 8. S

ault user namames is “pass

create and/orn of the cont

eck the statuons or opera

ration allowsed by the sys

ation tab on t

ration

stration; natiministration st

efault type w

cation type fached to youer installed a

nal directorytion applica

ricts a user nhe controller.strators with

only attributethe system b

System Oper

mes (ids): adsword”.

r modify thetroller.

s of the contate the contro

s admin userstem.

the External

ive or Lightwtores the use

when the con

from Nativeur corporate and running

y server coulation.

name to only. User namefull access.

es by simplyy clicking D

ration 105

dmin and

e existing

troller(s) ollers.

rs the

l panel of

weight er names ntroller is

e to network

g on the ld result

y being es

y typing Delete

1

L

106 Virtuen

LDAP

nt User’s Gui

Warning!If there asystem.

To add a nof the list

When youDirectorybe maintaVirtuent cname andpassword

To configinformatio

Begin by panel in Vdisplay th

ide

! Be carefulare no admin

new user cliof users.

u configure Vy Access Protained on the controller a cd password th

is correct th

gure a Virtueon telling th

clicking theVirtuent Conhe LDAP con

l not to deletnistrator use

ck the Add

Virtuent usetocol (LDAPVirtuent concall will be mhat has beenhen access w

ent controllere controller

LDAP radionfiguration (Fnfiguration f

Figure

te all user naers you will n

next button.

er authenticatP) server usentroller. Whmade to the Ln entered intowill be given

r to use LDAhow to cont

o button on tFigure 8-10)fields (Figur

e 8-11. LDAP

ames with funot be able t

. A new entr

tion to use aer names andhen a user attLDAP serveo it. If the uto the user.

AP authentictact the LDA

the Authenti). Then clickre 8-11).

Configuration

full administto modify or

ry will appe

an external Ld passwordstempts to log

er searching ser is found

cation you mAP server.

ication tab ok any place o

n

trator priviler operate the

ar at the bot

Lightweight will no longg into the for the user and the

must provide

of the Externon the screen

eges. e

ttom

ger

nal n to


Two sections will be displayed, one for administrative users with full update access and one for readonly access. The fields that must be completed are:

LDAP server - the IP address or network name of the LDAP server. Virtuent will use this address / name to contact the LDAP server.

Base DN - the LDAP Distinguished Name (or DN) of the entry on the LDAP server at which to start the search for the authentication credentials. For example, “dc=bustech” or “dc=com”.

Name filter - the criteria to be used in selecting the elements to be used in authentication criteria. For example, ‘(cn=%s)’ indicates that the Common Name (cn) field should be compared against the name entered in the User field of the Virtuent log on screen.

Some LDAP servers may require bind credentials that must be specified in order to bind to the LDAP server and do LDAP authentication. If your LDAP server requires these bind credentials then you will also need to enter the following fields:

Bind DN - The distinguished name (DN) to bind to the LDAP server with.

Bind password - The password to use with the Bind DN in order to bind to the LDAP server.

When configured as shown in Figure 8-11, the LDAP server located at the network name ‘ldap.example.com’ will be searched for entries with distinguishing names ‘example’ or ‘com’. Each entry found will have its common name (cn) compared against the user name that has been entered into the logon screen. If a match is found the password will be verified and the LDAP server will provide positive acknowledgement to the Virtuent Controller; giving the user Administrative privileges. Log in will be completed. If the distinguishing name or common name is not found or if the password does not match, then authentication will fail.

If you intend to have both administrative users and readonly users you will need to complete the fields in both sections of the LDAP configuration screen.

Chapt

VTHHO

ter 9. z/OVirtuecommMDL

To mautility

Using(informare se

OST

The nVTHHfrom tcapabto use

At stacontrobe useidenticontrorange devicemessaVTHH

OS Consent based con

municate betw(see Figure

ake use of My and then co

g the Virtuenmational, want over the c

ame of the hHOST. The the operatorilities for sen

e the z/OS M

artup, VTHHollers (nodesed for commfied with a uollers. A tapof addresses

e address is rages to the z/HOST has be

sole Opentrollers proween a singl9-1).

Figure

MDL z/OS Configure the

nt Configuratarning, or erchannel to th

host utility pVTHHOST. By defaultnding MDL

MODIFY fun

HOST will res) to be supp

munication anunique namepe drive devis that will berequired on /OS consoleeen started.

eration ovide an optie logical par

e 9-1. z/OS to

onsole operaindividual M

tion programrror) messaghe mainframe

roviding z/OT utility runs t, VTHHOSTcommands.

nction in plac

ead a configuported as welnd logging. e so that comice address me used as theeach control. These dev

Host Ut

MDL Mes

MDL Com

Chapte

ional z/OS urtition’s (LP

MDL Commu

ation, you mMDL control

m you can coges and / or we (See page

OS Console Oas a started

T will use W Optionally

ce of WTOR

uration file tll as the deviEach Virtue

mmands can bmust be selece command/cller if you w

vices will not

tility

ssages

mmands

er 9. z/OS C

utility that caPAR) operato

unications

must install thller(s) to com

onfigure whiwhich specif102).

Operation sutask, and ac

Write-to-Opey, you may cR.

that defines tice addresseent controllerbe targeted tcted from eacommunicat

want Virtuentt be eligible

Console Oper

an be used toor console an

he z/OS VTHmmunicate w

ich type fic Virtuent m

upport is ccepts commerator (WTOonfigure VT

the Virtuent s, per contror (node) willto specific ach controlletion path. At to send log for allocatio

ration 109

o nd the

HHOST with it.

messages

mands R)

THHOST

oller, to l be

er’s A 2nd

on once


Only log messages that have passed message filtering (see page 102) will be received by the host.

It should be noted that, depending upon the filtering options set on the controllers, there may be many log messages sent to the console(s). Optionally, VTHHOST supports a configuration option to send the messages to a host file instead of the operator’s console.

Installing VTHHOST

VTHHOST is only supported in a single Logical Partition (LPAR). You cannot connect multiple VTHHOST tasks running in multiple LPARs to the same MDL controller.

VTHHOST is distributed in the VTZOS.XMI package located on the MDL utilities CD. See page 29 for information about installing the VTZOS.XMI package.

The VTHHOST utility must be linked as an authorized program into an authorized library under the name VTHHOST. It is highly recommended that RACF be used to restrict the use of VTHHOST to authorized users only.

An example of the JCL required to link VTHHOST follows:

//L EXEC PGM=HEWL,PARM='MAP,LET,LIST,NCAL,AC=1' //SYSLMOD DD DSN=USER.LIBRARY,DISP=SHR //SYSUT1 DD DSN=&&SYSUT1,SPACE=(1024,(120,120),,,ROUND), // UNIT=SYSALLDA,DCB=BUFNO=1 //SYSPRINT DD SYSOUT=* //DDIN DD DSN=BTI.MODULE,DISP=SHR //SYSLIN DD * INCLUDE DDIN(VTHHOST) NAME VTHHOST(R) /*

Running VTHHOST

The following JCL is used to execute VTHHOST:

//VTHSTEP EXEC PGM=VTHHOST,PARM=’parameters’ //VTHCFG DD DSN=PARMLIB(nodecfg),DISP=SHR //VTHLOG DD DSN=logfilename,DISP=SHR //* THE FORMAT OF THE CONFIG FILE IS AS FOLLOWS: //* Col 1 -10 Nodename //* Col 12-15 Command path device address //* Col 17-20 Log path device address //* Col 22-29 Console name

The parameters than can be specified are:

NOLOG - Prevents VTHHOST from receiving continuous log data from any controller. Set this parameter if you plan to use VTHHOST only to send commands from the z/OS Console to the Virtuent

Chapter 9. z/OS Console Operation 111

controller(s). Command responses will be returned even when NOLOG is specified.

NOWTOR - Prevents VTHHOST from issuing the normally outstanding WTOR. When this parameter is specified, MDL commands can issued using the z/OS MODIFY command as the method of communication in place of WTOR.

LOGFILE - Causes any received log data from any Virtuent controller to be recorded in the file pointed to by the VTHLOG DD card. When LOGFILE is specified, the log messages are not sent to any console via WTO. If LOGFILE is not specified, the VTHLOG DD card is not required in the JCL. The LOGFILE dataset should be an FB LRECL 133 file, and will be opened for extend each time the task is started.

VTHHOST Configuration File

The configuration file pointed to by the VTHCFG DD card should be a FB LRECL 80 file that has a single record for each Virtuent controller (node) to be supported. Up to 64 controllers can be defined.

Comments cards can be included in the input configuration file by placing an asterisk in column 1.

The layout of the configuration file records is as follows:

Col. 1 – 10 : NODENAME

The name used by the mainframe operator to identify which controller (node) to communicate with.

Col 12 – 15: CMDDEV

The 4-digit device address of the tape drive that is to be used for operator commands and responses. If this field is left blank, no operator commands can be sent to this nodename.

Col 17 – 20: LOGDEV

The 4-digit device address of the tape drive that is to be used for logging activity whenever logging is active for this node. If left blank, no host logging can occur from the node.

Col 22 - 29: CONSNAME

The console that log messages should be directed to if logging is active for this node. If this field is left blank, the log messages will go to all routcde=5 (tape library) consoles.


The following is sample JCL for VTHHOST within a 3 controller (node) configuration supporting both messaging and commands:

VTLNODE1 038E 038F TAPECON1 VTLNODE2 039E 039F TAPECON1 VTLNODE3 03AE 03AF TAPECON1

Using z/OS Console Support

If VTHHOST is active and configured to receive Virtuent messages it will automatically forward any message received to the appropriate console or logfile.

When VTHHOST is executed without the NOWTOR parameter the message

VTH001I ENTER COMMAND, EOJ, OR ? FOR HELP

will be issued to the z/OS console and an outstanding Write to Operator Reply (WTOR) message will remain pending.

To send a command to VTHHOST you need to know the message reply number from the WTOR. To determine the WTOR message number enter the following z/OS command on the operator’s console:

d r,l (or /d r,l from SDSF)

This command will return the reply message number for any outstanding WTORs on the system.

To issue a command to VTHHOST enter the command using the WTOR message number in the following format:

msg#,COMMAND

Where:

msg# is the reply message number returned from the d r,l command

COMMAND is the VTHHOST command to be executed.

When VTHHOST is executed with the NOWTOR parameter the message

VTH002I jobname USE MODIFY TO ENTER COMMAND, EOJ, OR ? FOR HELP

will be issued. Subsequently the z/OS Modify command can be used to issue commands to VTHHOST using the ‘jobname’ indicated in the VTH002I message.

The format of the z/OS Modify command is:

F jobname,command

where:


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).


The following are valid examples of the same VTHHOST commands when VTHHOST has been executed with the NOWTOR parameter using the jobname VTHHOST:

F VTHHOST,STATUS

F VTHHOST,C=Q SPACE,N=N1

F VTHHOST,STOPLOG,N=ALL

Chapt

ter 10. UVirtue256 enencryp

Data eone orone ofbacke

If youunencseparaan applibrari

As showordsname.not thwithouencrypused taddresthis exdrives

On thdefine

Using Dent includes ncryption aspted.

encryption isr more drivef those drivend storage.

u want some crypted, you ate libraries tpropriate driies (MTLs) a

own, the cons all tape driv. This impliey are encryut encryptioption. Figurto configure sses 10 – 1Fxample). Ths.

he mainframed as MTL1.

Drives 00 – 0MTL1

Drives 10 – 1

MTL2

Data Enca data encry it is being w

s configuredes to performes, the data w

tape volumewill need toto the mainfive. Figure are defined.

Figur

ntroller is coves in the coes that all ta

ypted. But thn and the drre 10-2 showthese device

F, have been his indicates

me two MTLs. The device

0F

1F

cryptionyption modulwritten. Both

d on a drive bm data encrypwill be autom

es to be encro configure yframe allowi10-1 shows

e 10-1. Confi

onfigured witonfiguration ape volumes he drives witives with de

ws sample dees. Notice thconfigured wthat Virtuen

s are definedes 10 – 1F ar

Devices 10Encryption

Devices 00Encryption

Chapte

le allowing yh the tape he

by drive basiption. Each matically enc

rypted and oyour Virtuening you to dian example

figuring for En

th a single liare configurare written tth device ad

evice addressevice add conhat the seconwith an encrnt is to encry

d. In this exare defined as

0 – 1F n = Yes

0 – 0F n = No

er 10. Using

you to encryeader labels

is. That is, ytime a tape

crypted befo

other tape vont controller tirect individu where separ

ncryption

ibrary as a bred using theto the same l

ddresses 00 –ses 10 – 1F anfiguration pnd group of ryption key cypt any volum

ample the des MTL2.

B00000

B

B00002

B

g Data Encry

ypt data usinand the data

you can confvolume is w

ore it is writte

lumes to be to appear as ual tape volurate manual

backend. In oe same tape library whet

– 0F are confare configurpanel that codrives, with class (MFCLme written t

evices 00 – 0

0 – encrypted

B00003

2 – encrypted

B00001

yption 117

ng AES-a files are

figure written to en to the

left two

umes to tape

other library ther or figured ed with ould be

LASS in o these

0F are

1118 Virtuen

nt User’s Guiide Figuree 10-2. Add Deevices Exampple

Confivolumwill nencryp

The abseparaaccomall driyou nebeing

In ordencrypobtainobtainon youprovidinstallto con

FigureFor sicontroFor mconneMDL.gain a

Whenkey clthe keindivi

gured in thismes to be enc

ot be encryppted.

bove exampate drives ba

mplished usinives in the Meed to makewritten to.

der to encrypption procesn its keys. Ifn a license four network, de it with acclation guide nnect and con

e 10-3 showngle control

oller connectmulti-node prect to the Acc. The ACP taccess the RS

n the mainfralass (see Figey class to reidual tape vo

s manner, yocrypted or nopted. Howe

le uses systeased on whetng Bus-Tech

MDL will be sure to spec

pt a tape voluss. Virtuent f you intend or the RSA Kand connectcess to the Rthat accompnfigure your

s how differllers, such asts it to your croducts, suchcess Controlthen acts as SA Key Man

Figure 1

ame starts wrure 10-2) Vi

equest a set oolume can be

Nodes

ACP

our system Aot. If the ACver, if a volu

em managedther they ench’s UIMs or able to read

cify the appr

ume Virtuencommunicatto use data e

Key Managet your VirtueRSA Key Mapanied your Vr controller f

rent Virtuents MDL-1000company neh as MDL-60l Point (ACPan IP gatewanager.

0-3. Connect

riting a tape irtuent will mof keys. Sine encrypted w

RK

Ma

M600

Chapte

ACS routinesCS routine dume is direc

d storage (SMcrypt or not. using simpl

d a previouslyropriate esote

nt needs accetes with the encryption oer from RSAent controlleanager. PleaVirtuent confor network

t controllers 0/2000, an Eetwork for ac000/4000, thP) via the intay connectin

ting to RSA K

volume to amake a call tnce a call is mwith its own

RSA Key anager

M

MDL-00/4000

er 10. Using

s can direct idirects a tapected to MTL2

MS) and MT However, te esoterics. y encrypted eric in the JC

ess to a key tRSA Key M

on the MDL A Security, iner to the netwase refer to tntroller for inaccess.

connect to REthernet port ccess to the Rhe individualternal controng to the cor

Key Manager

a tape drive wto the RSA Kmade for eac

n unique key

MDL-1000 / 2000

g Data Encry

individual ta volume to M2, it will be

TL definitionthe same canIf esoterics tape volume

CL for a tape

to use duringManager from

you will neenstall it on a work in orderthe hardwarenformation o

RSA Key Mon the indiv

RSA Key Ml nodes (conol network wrporate netw

with an encrKey Managech new volu

y.

yption 119

ape MTL1 it

ns to n be are used,

e. But e that is

g the m RSA to ed to server r to e on how

anager. vidual

Manager. ntrollers) within the work to

ryption er using ume, each

1

C

120 Virtuen

Connectin

nt User’s Gui

The RSA encryptionvolume da(includingis never ware discar

When an recognizevolume. The RSA the clear kwill be rettape. Whdiscarded

ng to the R

In order fmust haveinstructionmodel in

AssumingRSA Keywithin Vi

In the exais using Pwith the a

ide

Key Managn key. The cata. The encg the header written to therded.

encrypted voe that the tap

It will then Key Manag

key to retrievturned to thehen the tape

d.

RSA Key M

for Virtuent te access to ans in the MDorder to con

g the controly Manager frrtuent Confi

ample shownPort number appropriate n

ger will returclear key wicryption keyrecords) bef

e tape. On ta

olume is moe has been emake a call

ger will autheve the encrye Virtuent cois unmounte

Manager

to perform da network wiDL installatinnect your M

ller has netwrom the Encriguration (Fi

Figure 10-4.

n, the RSA K38443. Younetwork addr

rn two keys till be writteny will be usedfore the dataape unload b

ounted for inencrypted anto the RSA enticate the r

yption key froontroller so ted both the c

data encryptiith access to on guide tha

MDL to the n

work access, yryption tab igure 10-4).

Connecting t

Key Manageu will need yress and por

to Virtuent; n to the tape d to encrypt

a is written toboth the encr

nput (or modnd retrieve thKey Managrequesting com its data sthat the driveclear and enc

ion, your Virthe RSA Ke

at accompanetwork.

you configuof the Exter

to RSA Key M

r is located ayour RSA adrt for your en

a clear key avolume alonthe volume

o tape. Theryption key a

dification) thehe clear key fer; passing i

controller (nostore. The ee can read (ocryption key

rtuent controey Manager.

nied your spe

ure Virtuent trnal configu

Manager

at IP addressdministrator tnvironment.

and an ng with tape ’s data e encryption and the clear

e tape drive from the tapit the clear kode) and the

encryption keor modify) thys will be

oller (MDL) Follow

ecific MDL

to access theuration panel

s 10.1.4.105to provide y

key r key

will pe key. en use ey he

e l

and you

Chapter 11. Back-End Tape Support 121

Chapter 11. Back-End Tape Support Virtuent controllers allow fibre channel attachment of an IBM 3592 or compatible tape drive. Attachment requires the optional Tape Drive Attachment kit be installed on the controller. The kit provides a single fibre channel port on the rear of the controller and software license for Virtuent physical tape functions. You must provide the IBM 3592 drive and a fibre channel cable to connect the drive to the port on the controller.

Note: Bus-Tech only supports point-to-point attachment of a single 3592 tape drive to the controller. Connection via a fibre channel switch is not supported.

Once the drive is physically attached to the controller there are 2 possible uses:

1. You can map a single Mainframe tape drive (device address) through to the physical tape drive for the purpose of writing and reading real tape cartridges from the mainframe. This capability is referred to as “Direct Tape”.

2. You can use the Virtuent-based Export / Import utilities to copy individual volumes (VOLSERs) from / to tape.

Each of these options will be discussed in this chapter.

Direct Tape

Although Virtuent controllers are primarily intended for use as tape-on-disk controllers, emulating tape drives to the mainframe and storing tape volumes on a back-end disk sub-system, Virtuent will allow mapping of an emulated 3590 tape drive to a physical IBM tape drive attached to the Virtuent controller.

To map a single mainframe device address through to a fibre channel attached IBM 3592 or TS1120 tape drive you would simply modify the Virtuent device definition to point the device to the physical drive instead of a virtual tape library on disk. For the device being mapped to the physical drive you must replace the Tape Library parameter by coding the following parameter:

DRIVE-nnnnnnnnnnnn

where nnnnnnnnnnnn is 12-digit serial number for the tape drive. If your drive serial number is less than 12 characters in length then you must pad the number to the left with zeros. For example, if your serial number is 7818330, then you would enter “DRIVE-000007818330” into the Tape Library field for the mapped drive. Figure 11-1 shows an example configuration where the 16th drive on the controller is mapped to a physical 3592 / TS1120 with serial number 7818330.

1

122 Virtuen

nt User’s Gui

Fig

The emulphysical tdefined as

Also, oncdevice frowhen a reare using address. TACS routlibrary id.representi

When a mrequests wmainframposted to the physictape and r

The tape cmainframVirtuent. have Virtucapable o

ide

gure 11-1. Ma

ated tape dritape drive. As Device Typ

e you have mom other virteal tape is wrMTLs, you Then the online determin. Otherwise ing the other

mainframe dewill work jus

me channel. Athe mainfram

cal drive becready the dri

cartridge wrme attached 3

Virtuent creuent installef reading the

apping a Devic

ive must be As shown inpe 3590.

mapped a detual devices ritten versus would want ly time a phynes a real carwhen the m

r 15 drives a

evice is mapst as they woAllocation ome operator comes readyive.

ritten will be3590 tape drieated cartrid

ed as long as e 3590 / 349

ce to a fibre ch

configured tFigure 10-1

evice in this in the mainfa virtual tapto assign a u

ysical cartridrtridge is to b

mainframe alla virtual volu

pped to a phyould if the drof the drive w

console. Th. Normally

compatibleive unless thdges can be s

those locati0E cartridge

hannel attach

to match the1, the device

fashion, youframe configpe written tounique libradge will be wbe written anlocates to th

ume will be w

ysical tape drrive were dirwill result in he request wthis will req

with 3590 che volume hasent to mainfions have reae.

hed IBM 3592

characterist being confi

u must isolatguration in oo disk. Speciary id (MTL)written is wh

and assigns the library id (written.

drive in this mrectly attach

n a mount reqwill remain oquire an oper

cartridges wras been encryframe locatioal or compat

Tape Drive

tics of the gured must b

te the mainfrorder to contrifically, if yo) to this devihen the systehe appropria(MTL)

manner mouhed to a quest being utstanding urator to moun

ritten from aypted by ons that do ntible tape dri

be

rame rol ou ice em ate

unt

until nt a

any

not ives

Compre

ssion and E

Virtuemappeinstruthan Vother

If the attachwill pdrive.

In thisdrivesbe ablmust bclear koccur

Encryption

ent supports ed to a physict the drive t

Virtuent, wilIBM drives

mainframe dhed tape driverform both

s case the ress not attachele to re-read be configurekey stored o.

mainframe iical fibre chto compress l perform ththat may lat

device confive specifies a

data compre

Figure

sulting cartrid to a Virtuethe tape cart

ed with accesn the tape ca

initiated dataannel attachthe data bef

he data compter attempt to

iguration panan encryptionession and e

e 11-2. Direct

idges writtenent controlletridge. The ss to an RSAartridge in or

Chapter

a compressiohed drive reqfore writing pression in oro read the da

nel mappingn key class (

encryption on

t Tape with En

n WILL NOer. Only a VVirtuent con

A Key Manarder to allow

r 11. Back-E

on. If a maiquests compr

it to tape. Trder to ensurata.

g a device to (see Figure 1n the data be

ncryption

OT BE COMVirtuent attac

ntroller readager that can w decryption

End Tape Su

inframe taperession VirtuThe tape drivre compatibi

a fibre chan11-2) then Vefore writing

PATIBLE wched tape driding these ca

correctly ren to successfu

upport 123

e device uent will ve, rather ility with

nnel Virtuent g to the

with tape ive will artridges esolve the fully

1

T

124 Virtuen

Tape Expo

nt User’s Gui

ort / Impo

As an altethrough toalso incluVirtuent d

These cominteractionoperator c

Because tknowledgbecause Vutilities arphysical twish to usconfigura

To enableconfigura

The next tavailable.

ide

ort Utilities

ernative to Do a physical

udes two utilidisk library a

mmands are n. If a commcan then rety

these commage or regard tVirtuent oftenre disabled itape drive tose the tape e

ation to enab

e the Virtuenation and che

time the Vir

s

Direct Tape wIBM drive cities for expoand a Virtue

executed fromand is enteype the comm

ands copy tato what datan does not hn the default a Virtuent cxport / impole them.

nt Export / Imeck the Tape

Figure 11-3

rtuent applic

where a mainconnected toorting or impnt attached t

om within thered incorrecmand correc

ape volumes a may actuallhave a tape dt Virtuent cocontroller, noort utilities y

mport utilitiee export ena

3. Enabling Ta

ation is resta

nframe tape o the Virtuen

mporting tapetape drive.

he Virtuent actly an error tly.

based only oly be contain

drive physicaonfigurationot being use

you will need

es open the aabled check (

ape Export / I

arted the exp

drive is mapnt controller e volumes be

application amessage wil

on VOLSERned on the vally attached. If you havd by Tape Dd to modify t

active Tape d(Figure 11-3

Import

port / import

pped directly(node), Virt

etween the

and have no ull be issued.

R without volume and d to it, these ve attached aDirect, and yothe Virtuent

device 3).

t utilities wil

y tuent

user The

a ou

ll be

Chapter 11. Back-End Tape Support 125

Export

The format of the tape export command is:

EXPORT from to [norun compress encryptkey=class|NONE]

where from is the full library name of the tape volume (VOLSER) to be copied and to is the name of the device driver for the tape drive the volume is to be written to.

For example:

EXPORT /tapelib/B0/B00104 DRIVE-nnnnnnnnnnnn

will copy tape volume (VOLSER) B00104 from the backend tape library to DRIVE-nnnnnnnnnnn where nnnnnnnnnnn is a 12-character serial number of the fibre channel attached tape drive.

The options for the command are:

norun – telling Virtuent not to unload the tape when the import is complete.

compress – this option indicates whether or not the tape volume should be compressed when being written to the drive. The default is to write the data without compression. If this option is included on the command, Virtuent will instruct the tape drive to compress the data before writing it to media.

If the volume is already compressed and unencrypted on the tape library, Virtuent will decompress the data before writing it to physical tape. Then, if the compress option is specified, Virtuent will tell the drive to compress the data.

If the volume is already encrypted on the tape library then the compress option has no effect on the data. Virtuent copies the encrypted volume as is to the physical tape.

encryptkey=class|NONE – this option tells Virtuent whether or not the data should be encrypted before it is written to tape. The encryption key class you specify must be defined in the RSA Key Manager. The default is encryptkey=NONE.

When the encryptkey option specifies a valid encryption key class Virtuent call the RSA Key Manager in order to get an encryption key and will then encrypt the data before sending it to the tape drive. If the compress option is also specified, Virtuent will compress the data before encrypting it and the drive will not be asked to do compression.

If the data in the disk file is already encrypted, Virtuent will copy the existing encrypted data from the disk to the tape as is. The export utility will not de-encrypt data which is already encrypted on the tape library. In this case, it is not necessary for you to specify the encryption key class on the export command.

Tape volumes written by Virtuent using the EXPORT command which are encrypted (either during the EXPORT or were already encrypted on disk) can only be processed by the Virtuent IMPORT command or Direct Tape. They cannot be processed without using a Virtuent controller.


Tape volumes written to an IBM 3592 drive by EXPORT which are not encrypted are compatible with other 3492 drives and can be processed by systems other than Virtuent. For example, a compressed volume written by EXPORT to an IBM 3490E drive could be mounted on a mainframe channel attached 3490E drive and read directly by a mainframe application.

Note: It is the user’s responsibility to make sure the volume does not exceed the physical capacity of the cartridge being written to. If you attempt to write a volume to tape that cannot fit on the cartridge the export will fail and invalidate the data on the tape by rewinding and writing a tapemark at the front of the tape.

Import

The format of the tape import command is:

IMPORT from to [norun compress encryptkey=n|KEYn|NONE class=n|CLASSn

where from is the device name of the tape drive to be read and to is the complete library name of the tape volume (VOLSER) being imported.

For example:

IMPORT DRIVE-nnnnnnnnnnnn /tapelib

will import the tape on drive DRIVE-nnnnnnnnnnn where nnnnnnnnnnn is a 12-character serial number of the fibre channel attached tape drive and write it to the library ‘/tapelib’.

The options on the command are:

norun – telling Virtuent not to unload the tape when the import is complete.

compress – telling Virtuent to compress the volume as it is being written to the library. Virtuent assumes that if the tape is compressed on the cartridge the drive will automatically de-compress it as it is being read from tape. If the compress option is included on the command line Virtuent will compress the data before writing it to the tape library. If this option is not specified the volume will be stored in the library uncompressed

encryptkey=class|NONE - tells Virtuent whether or not to encrypt the data as it is writing it to the library. The encryption key class you specify must be a valid key class in the RSA Key Manager. The default is encryptkey=NONE indicating Virtuent will not do encryption as it is writing the data to the library.

If the volume was previously encrypted by Virtuent then the volume is imported as is onto the tape library. The Virtuent IMPORT command does not decrypt data. Virtuent encrypted tape volumes can only be decrypted by being mounted and read from the mainframe.

CLASS=CLASSn – tells Virtuent which storage class to store the imported volume in on the library. The default, if not specified is CLASS0.

Chapt

ter 12. DAs preusing imagerecordthe vo

For cubetweVirtueflat filmainflength

Couplallowsany ne

The pData Eapplic

Data Exeviously disca specialize

e of a tape vods. Mainframolume exactl

ustomers wheen the mainent provides le support wframe minus hs.

led with Gigs Virtuent coetwork-attac

urpose of thExchange, hcations can u

TapeLibra

xchangecussed, Virtud file formatolume includme jobs readly as if it had

ho wish to usframe and ana capability

writes a flat dtape marks,

gabit Etherneontrollers to ched server (

Figur

is chapter isow to write

use it, and ho

AWS File ary

Virtuent Con

uent controlt. Using thisding tape mading a tape vd been really

se a Virtuentny other, op

y referred to data file that headers, an

et and Netwobe used to e

(Figure 12-1

re 12-1. Flat Fi

to discuss ha flat file fro

ow to read a

les

ntroller

lers normalls format alloarks, headersvolume fromy written to a

t controller ten system (Was flat file sucontains onl

nd trailers an

ork File Systexchange dat).

iles for Data E

how to confiom the mainflat file from

NS

Chapter 12

ly write tapeows Virtuents, trailers, an

m a Virtuent-ba tape.

to provide daWindows, Uupport. As tly the data w

nd without re

tem (NFS), fta between t

Exchange

gure a Virtunframe so othm the mainfr

NFS Server

2. Data Exch

volumes to t to preservend variable lebased library

ata exchangeUnix, Linux, the name im

written by theegard to reco

flat file suppthe mainfram

uent controlleher non-mainrame.

Flat Files

hange 127

disk e an exact ength y receive

e etc.),

mplies, e

ord

port me and

er for nframe

1

C

V

128 Virtuen

Configura

Virtuent Co

nt User’s Gui

ation

ontroller

Bus-Techprimary liyour libraexchange

Figure 12defined fo/dataexchname youdefine the

Once youto connecdata exchlocalhost

ide

h recommendibrary. If yoary, then you

filesystem.

2-2 shows a sor data exchah instead of /tu want as lone primary vir

F

u have definect it to the Viange. Figurin this exam

Figur

ds that you dou are usingu should crea

sample confiange. Notictapelib as th

ng as it is difrtual tape lib

Figure 12-2. D

ed the storagirtuent contrre 12-3 show

mple.

re 12-3. Conn

do not place /tapelib, for

ate a differen

figuration whe the second

he top level idfferent from brary.

Defining Stora

ge in the avaioller (node)

ws that the da

nect the Storag

your data exexample at

nt top level i

here a singled mount poindentifier. Ythe high-lev

age for Data E

ilable storagwhere you p

ata exchange

ge to the Cont

xchange voluthe top leve

identifier for

e filesystem (nt defined usYou can use vel name (/ta

Exchange

ge list (Figurplan to define storage is c

troller (Node)

umes in yourl identifier fr your data

(disk) is beinses the nameany high-lev

apelib) used

e-12-2) you ne tape driveconnected to

r for

ng e vel to

need es for o

Once the davirtua(/tapepoint exampTape L

Once in. Eexcha

Once Add dpointi

the storage iata exchangeal tape librarylib, for examthe tape librple). To doLibrary field

Figur

you have doEnter the entiange volumes

you have endevices wereing to the dat

is connectede disk (filesyy where you

mple), when rary field dir this you nee

d on the devi

re 12-4. Enter

one this the cire mount pos to (Figure

Figure 12-5

ntered the moe filled out asta exchange

d to the contrystem). Howu point the ta

you are defiectly to the med to select “ice definition

ring Free-For

configurator oint name for12-5).

5. Configuring

ount point cls shown in Fdisk as show

roller you cawever, unlikeape library toining disk fomount point“(free-form)n panel (Fig

rm Data into th

will return ar the disk wh

g Devices for D

lick add to cFigure 12-5, wn in Figure

Chapter 12

an then define defining deo the high-levor data exchat (/dataexch/D)” from the pgure 12-4).

he Tape Libra

a free-form fhere you wa

Data Exchang

create the ransixteen devi

e 12-6.

2. Data Exch

ne drives to wevices to wrivel qualifier

ange you neeDISK1, for

pull down lis

ary Field

field for youant to write d

ge

nge of deviceices will be d

hange 129

write to ite to a r ed to

st in the

u to type data

es. If the defined

1

z

V

V

130 Virtuen

z/OS, OS/39

VSE

VM

nt User’s Gui

Once thesbe placedexample, the data edevices co

90 With this mainframin this conconfigurelibrary id.qualifier t2).

VSE instaallocate spexchange

If you areallocates dfrom driv

To isolatedrive to Vsame fold

Data exch

For VM yhave beenone of the

ide

se devices ard on the data

you are usinxchange devonnected to

configuratiome. For exam

nfiguration ad for data ex. Your ACSto determine

allations whipecific tape , run VIRMO

e using a tapedrives for thes using the

e a drive for Virtuent (pagder.

hange drives

you would aln configurede drives not c

Figure

re defined anexchange di

ng MTLs in zvices in a septhe primary

on in place, ymple, if you as MTL1, allxchange wouS routines woe which MTL

ich do not usdrives with OUNT (see

e managemehe tape mana

primary tap

data exchange 28). Assig

s should not b

llocate data ed for data excconnected to

12-6. Data Ex

ny tape volumisk rather thaz/OS to defiparate MTL library.

you would dare using Ml with the sauld be configould then keyL to direct sp

se tape manatheir JCL. Spage 58) usi

ent system, sager and youpe library (/ta

nge include thgn a unique

be under the

exchange vochange. Allo the data ex

xchange Devic

me written tan the virtuaine your MDso that you

define two seMTLs, you mame library idgured as a My off of the hpecific tape v

agement softSo, if you haing that driv

such as Dynau must isolateapelib).

he GROUPgroup numb

e control of t

olumes to onl other volum

xchange libra

ces

to any of theal tape librar

DL library, ycan isolate t

eparate librarmight define t

d. The two MTL 2, with

high level davolumes to (

ftware must mave set aside ve address.

am/T or EPIe the data ex

option whenber to each d

the tape man

ne of the twomes would bary.

se devices wry. If, for ou should plthem from

ries on the the first 14 ddrives a different ataset name (MTL 1 or M

manually a drive for d

IC, then Virtxchange driv

n you define drive going to

nagement sys

o tape drives be allocated t

will

lace

drives

MTL

data

tuent ve

the o the

stem.

that to

Chapter 12. Data Exchange 131

Writing Flat Files

Virtuent determines by volume serial number whether to write the volume in AWS format or into a flat file. Any volume with a volume serial number (VOLSER) in the format “BFLxxx” will be written as a flat file with the filename “BFLxxx.FLAT”. Labeled tapes will be renamed to “BFLxxx.datasetname.FLAT” using the data set name from the HDR1 label when the mainframe writes the HDR1 label. Keep in mind, however, that no header information is written into the flat file. Once the file is closed, all header and trailer information is lost.

Actual file data is written to the output file sequentially without any retention of record lengths and without any data conversion. Data received in EBCDIC format will be written to disk in EBCDIC format. Data received in ASCII will be written in ASCII. It is the user’s responsibility to provide for data conversion either before writing the data to the Virtuent controller or when reading the file from an open server. In z/OS or OS/390 EBCDIC to ASCII conversion can be requested from the operating system by coding OPTCD=Q on the DD for the tape volume.

Only a single data file may be written to the tape volume. Flat file data exchange does not allow multiple files to be written onto one tape volume.

Reading Flat Files

To input a file to the mainframe from an open system you simply have to place the file in a directory connected to a Virtuent tape drive and name the file “BFLxxx.FLAT” where xxx may be any 3 characters allowed in a tape volume serial number (VOLSER).

Existing flat files are always presented to the mainframe as unlabeled tapes.

Virtuent will always return the exact amount of data requested by each read command unless there is not enough data left in the file. Programs reading in a flat file from Virtuent must read fixed length records of the correct length. Many mainframe utilities are unsuitable for use with Virtuent flat files because they specify a maximum read size of 64k –1 and then wait for the read operation to return the actual record length. Virtuent will return 64k – 1 bytes of data in response to such a read unless end of file is reached.

z/OS and OS/390

To read a flat file code BFLxxx as the volume serial number of an unlabeled tape and Virtuent will use the serial number to mount the file BFLxxx.FLAT. When using MTLs your ACS rountine should recognized a VOLSER that begins with “BFL” as an attempt to read a flat file and allocate to the appropriate MTL (library id) where flat files are located. Following is a sample DD statement to read a flat file:

VOL=SER=BFL001,LABEL=(,NL),DISP=OLD


VSE

Assuming your Virtuent controller has a separate data exchange directory assigned to a specific tape drive (see Configuration section earlier in this chapter), you need to run VIRMOUNT in order to mount the flat file for processing. For example:

// OPTION PARTDUMP * LIBDEF POINTS TO THE VSE LIBRARY WHERE VIRMOUNT IS CATALOGED // LIBDEF PHASE,SEARCH=USERLIB.PROD * ***************************************************************** * THIS PROGRAM CAUSES A VIRTUAL TAPE VOLUME TO BE MOUNTED. * * YOU MUST ASSIGN SYS004 TO A VIRTUENT DEVICE ADDRESS. * * THE PARMS ARE ENCLOSED IN SINGLE QUOTES AND SEPERATED BY COMMAS * * 1. 6 CHAR TAPE NAME(VOLSER) OR SCRTCH * * 2. N FOR UNLABELED OR S FOR STANDARD LABELED * * ***************************************************************** // ASSGN SYS004,A087 ASSIGN TO A VIRTUENT DEVICE ADDRESS // EXEC VIRMOUNT,SIZE=AUTO,PARM='BFL001,N'

This JCL mounts the flat file named “BFL001.FLAT” on tape drive A087. A subsequent job step can now read the unlabeled tape mounted on A087 in order to complete the data exchange.

.

Appendix A. Volume Handling 133

Appendix A. Volume Handling

Volume Serial Numbers

Virtuent supports only volume serial numbers (VOLSERs) that conform to the IBM standard VOLSER naming convention. IBM standard VOLSERs contain 1 to 6 alphanumeric EBCDIC characters; uppercase A through Z, 0 through 9, and the hyphen. Volume serial numbers are left justified and padded with spaces on the right.

The disk filename of a virtual tape volume is initially derived from the VOLSER requested by the Host in the Load Display Mount message. A simple one to six-character disk filename that matches the requested VOLSER, converted from EBCDIC to ASCII, will be used to hold the virtual tape volume.

Following the analogy of physical tape volumes, the virtual volume's disk filename is equivalent to a physical tape's external label. Just as it is important for a physical tape's external label to always match the VOLSER recorded on the tape so that the tape can be identified, stored, and retrieved, it is vital that a virtual volume's disk filename match the VOLSER recorded in the volume for the same reasons.

As long as the host does not write a different VOLSER to the virtual volume, the disk filename and the VOLSER recorded in the volume will remain the same. Under some circumstances, the host may write a new VOL1 label containing a VOLSER different from the one originally associated with the mounted volume. This usually happens only when the host uses a program such as Ditto to perform a physical tape copy that copies the original volume's labels as well as its data to the new tape. In order to maintain the association between a virtual volume's disk filename and the actual VOLSER recorded in the volume, whenever the host writes a VOL1 label Virtuent checks the VOLSER being written to see if it differs from the original VOLSER under which the volume was mounted. If the new VOLSER is different, Virtuent attempts to rename the volume's disk filename to match the new VOLSER in the VOL1 label being written. If the new disk filename, i.e. new VOLSER, already exists, Virtuent will not rename the mounted volume and it will not allow the new VOL1 label to be written; it will return an error (Unit Check status with Command Reject sense) to the host's write command. In addition, if the new VOLSER begins with a different VOLSER prefix (first two characters) than the mounted volume, the new VOL1 label write will be rejected. This is to prevent a volume from residing in a tape library subdirectory that does not match the VOLSER prefix.

If the host changes a labeled volume to an unlabeled volume by writing over the standard labels with data, Virtuent accepts the change but does not change the volume's filename.


Scratching Volumes

Virtual volumes in a tape library exist in one of three states:

• Active – An “active” volume is any volume that is not currently a scratch tape. A scratch volume becomes active whenever it is mounted in response to a request from the Host (or by a manual mount), whether by explicit VOLSER or to fulfill a SCRTCH tape request. Once a volume is active it is no longer a scratch tape, so it can be mounted again only by explicitly requesting it by specific volume serial number, not by a SCRTCH request. An active volume can be recognized by the fact that its file name is exactly the same as its VOLSER. Once a volume is active, it will remain active in the virtual tape library until it is explicitly scratched.

• Scratched – Volumes created by Virtuent INITIALIZE command are initially in the “scratched” state, available to be mounted in response to a SCRTCH tape request. A scratch volume can be recognized by the fact that its file name is preceded by a “~”, for example ~BT0040. When the host requests a scratch volume, Virtuent will select the oldest scratch volume from the tape library directory that has the most free space, but only after any "erased" scratch volumes (see below) have been used. A scratch volume can also be mounted by explicitly requesting it by volume serial number. In either case, whenever a scratch volume is mounted, it is moved back to active status by renaming the file from ~VOLSER back to VOLSER (without the ~) and is no longer a scratch tape. However, if the scratch volume is never accessed by the host before it is unmounted, it is changed back to scratch status when unmounted Volumes can be moved from the “active” to the "scratched" state by a scratch utility running on the host. The Virtuent Utility CD includes scratch utilities for both z/OS-OS/390 (see page 37) and VSE (see 0). These utilities process a host-generated scratch report and send scratch volume requests over the channel to Virtuent. When Virtuent receives a request to scratch an active volume, the disk file for that volume is renamed from VOLSER to ~VOLSER, where VOLSER is the volume serial number. For example, scratching B00004 would rename the file to ~B00004. All of the data in the scratched volume is retained at this time, although it may be deleted later if Virtuent needs the disk space.

• Erased - An "erased" volume is a scratch volume which has had its data deleted to recover disk space. Scratched tapes retain their data for as long as possible until Virtuent needs to reclaim disk space to write new data. When Virtuent starts running out of disk space, it will select the oldest scratched volume from the tape library and delete its data. When a scratch tape is "erased", all of the data in the volume past the standard header labels is deleted. Only the VOL1 and HDR labels are retained (these are retained because some host tape management systems


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 volume’s disk file can only be opened in Read-Only mode (for example, it resides on a read-only medium, in a directory with read-only access, or the file itself is read-only), the Write Protect bit will be set on the virtual tape drive while this volume is mounted. The volume can then only be read, not written, in this situation. Any attempt to write (Write, Write Tapemark, or Erase) to the volume, will result in a Unit Check error being presented to the host.

Mounting a "SCRTCH" or "PRIVAT" Volume

Unlabeled Scratch Request

If the host requests an unlabeled "SCRTCH" or "PRIVAT" volume (determined by an 'N' in the 8th position of the mount message), Virtuent will display an appropriate error message, the mount request is ignored, and the virtual tape drive remains in the "Not Ready" state. This is because an unlabeled scratch tape cannot be subsequently tracked or retrieved since there is no permanent VOLSER associated with the volume.

Labeled Scratch Request

If the host requests a scratch volume using "SCRTCH", "PRIVAT", or a configured scratch pool (Scratch synonym) volume with standard labels (anything other than 'N' in the 8th position of the Load Display Mount message), Virtuent will check the appropriate tape synonym definitions that may exist in order to identify which storage class in the tape library will receive the new tape. Virtuent will search the storage class to identify an eligible scratch volume. Once an eligible tape has been identified, Virtuent will ready the device and then wait for the mainframe to start writing. On first write from the mainframe Virtuent will randomly allocate the volume to a any filesystem within the storage class that has enough space to hold the cartridge being allocated (based on the configured SIZE= parameter). A new VOLSER file will be created. The old scratch volume file (~VOLSER) will be deleted; effectively moving the tape volume from the filesystem where ~VOLSER was located to the filesystem where the new volume (VOLSER) has been created.

If no scratched, erased volume is found within the storage class to fulfill the mount request, an appropriate message is displayed on the Virtuent console, the mount request is ignored, and the virtual tape drive remains in the "Not Ready" state. Just like with a physical tape library, you should pre-initialize enough scratch volumes to fulfill scratch tape requests from the host (see INITIALIZE command, page 89), and


move “active” volumes back to scratch status in sync with the Host (see z/OS-OS/390 scratch utilities, page 37, and VSE scratch utilities in 0).

However, for backwards compatibility with previous releases, Virtuent can be configured to automatically create a tape volume when the Host requests a scratch volume and none is available. If the VOL=prefix parameter is configured, a new scratch tape volume will be automatically created in the tape library. Virtuent will pick the first available (non-existing) VOLSER that starts with the prefix configured for this device. As an example, if the drive is configured with a volume serial number prefix of VOL=BT, Virtuent will attempt to allocate a new volume starting at BT0000, then BT0001, BT0002, etc., until it finds an unused volume serial number. If the library contains a directory matching the prefix, the new tape is created in that directory. For example, the volume BA1001 would be placed in the disk mounted at /tapelib/BA. If a /tapelib/BA directory does not exist, the file would be created in /tapelib. Before coming ready to the host, the new virtual tape volume will be initialized as a standard labeled tape, with a dummy VOL1 label containing the new VOLSER, a dummy (empty) HDR1 label, and two tapemarks. These labels conform to those produced by the MVS IEHINITT tape initialization utility. Note that since there is no data following the standard labels, any attempt to read past the labels will result in an I/O error (Unit Check status with Data Check and Tape Void sense).

Once a volume has been allocated for the mount request, the file is opened and positioned to the beginning of the volume (load point). The virtual tape drive presents a Not-Ready-to-Ready interrupt to the host and enters the "Ready" state, ready for I/O from the host.

When a host-initiated mount request fails for any of the following reasons, the mount request will be retried until it succeeds or until the host sends a new Load Display message that cancels the request:

Volume not found Volume in use elsewhere No scratch available Drive is quiesced

End of Volume Conditions

Logical End of Volume

Virtuent will signal to the host that a virtual tape has reached logical end of volume when:

• The disk file corresponding to the virtual tape volume approaches the maximum volume size specified by the user for this virtual tape device. This maximum volume size is configurable by the user (see SIZE parameter on page 28) from 2-megabytes to 2-terabytes, and defaults to 2-gigabytes if not specified. The configured maximum volume size can also be temporarily overridden with the operator’s SET SIZE command.


• 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 host’s write command.

Appendix B. AWSTAPE Information 141

Appendix B. AWSTAPE Information

Virtuent stores virtual tape volumes on disk in the AWSTAPE format.

Each AWSTAPE disk file emulates one physical tape volume.

Each emulated physical record in the emulated tape volume is represented by one or more pairings of a Block Header followed by data. An emulated tapemark is represented by a Block Header only.

The structure of the AWSTAPE block header is as follows:

/*-------------------------------------------------------------------*/ /* Structure definition for AWSTAPE block header */ /*-------------------------------------------------------------------*/ typedef struct _AWSTAPE_BLKHDR { U16 curblkl; /* Length of this block */ U16 prvblkl; /* Length of previous block */ BYTE flags1; /* Flags byte 1 */ BYTE flags2; /* Flags byte 2 */ } AWSTAPE_BLKHDR; /* Definitions for AWSTAPE_BLKHDR flags byte 1 */ #define AWSTAPE_FLAG1_NEWREC 0x80 /* Start of new record */ #define AWSTAPE_FLAG1_TAPEMARK 0x40 /* Tape mark */ #define AWSTAPE_FLAG1_ENDREC 0x20 /* End of record */ /* SEGMENTED is a Bus-Tech extension: */ #define AWSTAPE_FLAG1_SEGMENTED 0x10 /* Segmented record */ /* Definitions for AWSTAPE_BLKHDR flags byte 2 */ /* ZCMPRS and HWCMPRS are Bus-Tech extensions: */ #define AWSTAPE_FLAG2_ZCMPRS 0x80 /* Compressed with zlib */ #define AWSTAPE_FLAG2_HWCMPRS 0x40 /* Compressed with hardware */

A U16 is a 16-bit unsigned value. Values in a U16 are in Intel (low-byte, hi-byte) format.

A BYTE is an unsigned 8-bit value.

The current and previous block lengths define the length of data in the AWS block, and do not include the length of the block header itself. The maximum AWS data block size is FFFF hex (65535 decimal) bytes.

The first block in an AWSTAPE file has a previous block length (prvblkl) of zero.

A tapemark has a current block length (curblkl) of zero, and the TAPEMARK bit is set in flags1. A tapemark never has ENDREC or NEWREC bits set in flags1.

The NEWREC bit in flags1 signifies the start of a logical tape block and the ENDREC bit in flags1 signifies the end of a logical tape block. When NEWREC and ENDREC are both set, it signifies that the emulated tape block is completely contained in one AWS data block. When an emulated tape block spans more than one


AWS data block, NEWREC is set in the first of a chain of AWS data blocks, and ENDREC is set in the last. In this way, emulated tape blocks exceeding 64K-1 bytes can be stored in the AWSTAPE file as a chain of AWS data blocks. If the tape block spans more than two AWS data blocks, the AWS data blocks in the middle will have neither NEWREC nor ENDREC set.

In addition to setting the NEWREC and ENDREC bits appropriately for a tape block that spans multiple AWS data blocks, Virtuent also sets the SEGMENTED bit in the first block header of the chain.

Data in an AWSTAPE file is stored in the format that the mainframe sent it. Normally, mainframe data is in EBCDIC format. But if the mainframe application writes the data in ASCII, then the AWSTAPE file will contain ASCII data.

Appendix C. Load Display Command – CCW Opcode x’9F’ 143

Appendix C. Load Display Command – CCW Opcode x’9F’ IBM-compatible 3480/3490/3590 tape drives support a "Load Display" command that is used to display messages on the tape drive's LED display. These messages are typically sent by the mainframe operating system or tape management system to request that a specific volume be mounted by the operator.

Virtuent relies on these Load Display messages to determine when virtual tape volumes should be mounted on its virtual tape drives. When it sees a Load Display message that it interprets as a mount request of a specific volume serial number (VOLSER), the volume's disk file is opened and the drive “comes ready” to the host – that is, it acts like a tape has been mounted. If Virtuent determines the Load Display is requesting a scratch volume then Virtuent will identify a suitable VOLSER, opens the volume’s disk file and the drive “comes ready” to the host. For a complete description of how Virtuent determines a scratch is being requested please refer to the paragraph titled “Scratch Synonyms” on page 28. Virtuent ignores any Load Display messages not determined to be a mount message.

Since the Load Display messages are intended to be "human readable", they can conceivably vary from mainframe system to system. Virtuent requires a specific Load Display message format in order to determine that the host is requesting a volume mount. Specifically, Virtuent has been designed to recognize the Load Display mount messages issued by z/OS-OS/390.

The format of the mount messages recognized by Virtuent follows. Refer to the tables below for more detailed information about the Load Display messages format.

Format Control Byte (FCB):

Virtuent recognizes Function Select (bits 0-2) values of 000, 010, and 111 as potential mount messages.

Messages 0 and 1:

If the FCB Alternating Message bit (bit 3) is on, first message 0 is checked for a mount message, then message 1.

If the FCB Alternating Message bit (bit 3) is off, the FCB Display Low/High Message bit (bit 5) is checked to determine whether message 0 or 1 is to be checked for a mount message. If bit 5 is on, only message 0 is checked for a mount message. If bit 5 is off, only message 1 is checked for a mount message.

Virtuent recognizes a mount request by the EBCDIC character 'M' in the first position (byte 0) of the message. The EBCDIC volume serial number is located in bytes 1-6 of the message. The last character (byte 7) of the message is a label indicator. If byte 7 is EBCDIC ‘A’ an ANSI (ASCII) labeled volume is being requested. If byte 7 is EBCDIC 'N', an unlabeled volume is being requested; otherwise a standard labeled tape is presumed.


If the Load Display message does not pass all the tests to determine a mount request, the message is simply ignored.

Load Display Data

0 Format Control Byte

1-8 Message 0

9-16 Message 1

Format Control Byte (FCB)

Bits Value Description

0-2 Function Select

000 The message specified in bytes 1-8 and 9-16 is maintained until the tape drive next starts tape motion, or until the message is updated.

001 The message specified in bytes 1-8 is maintained until the tape cartridge is physically removed from the tape drive, or until the next unload/load cycle.

010 The message specified in bytes 1-8 is maintained until the drive is next loaded.

011 This value is used to physically access a drive without changing the message display. This option can be used to test whether a control unit can physically communicate with a drive.

100 to 110

Reserved.

111 The message specified in bytes 1-8 and 9-16 is displayed. The message in bytes 1-8 is displayed until a tape cartridge is physically removed from the tape drive, or until the drive is next loaded. The message in bytes 9-16 is displayed until the drive is next loaded (not including the loading of the cleaning cartridge). If no cartridge is present in the drive, the first message is ignored and only the second message is displayed until the drive is next loaded (not including the loading of the cleaning cartridge).

Appendix C. Load Display Command – CCW Opcode x’9F’ 145

3 Alternate Messages

0 The tape drive displays only the message that is specified in bit 5.

1 The tape drive displays both messages specified in bytes 1-8 and 9-16, respectively, alternating them on the message display. The sequence repeats until the message is replaced on the display. When bit 3 is set to 1, bits 4 and 5 are ignored.

4 Blink Message

0 The message specified by setting bit 5 does not blink.

1 The message specified by setting bit 5 blinks repeatedly. When bit 3 is set to 1, bit 4 is ignored.

5 Display Low/High Message

0 The message specified in bytes 1-8 is displayed. This bit is ignored if bit 3 is set to 1.

1 The message specified in bytes 9-16 is displayed. This bit is ignored if bit 3 is set to 1.

6 0 Reserved

7 0 Index Automatic Load (Reserved)


The following are some sample Load Display messages. The hex values are in EBCDIC:

48D4C2E3 F0F0F0F1 E2000000 00000000 00

Interpretation:

Display message 0 (bytes 1-8) “MBT0001S”, blink, and retain until loaded. In other words, “Mount volume BT0001”. Volume BT0001 is expected to be a standard labeled volume.

Virtuent would interpret this as a valid mount request for standard labeled volume BT0001.

28D9C2E3 F4F44040 40000000 00000000 00

Interpretation:

Display message 0 (bytes 1-8) “RBT44 ”, blink it, and retain until the tape is removed from the drive. In other words, “Remove volume BT44.

Virtuent would ignore this message since it is not a mount request.

F0D9C2E3 F0F0F2F2 40D4C2E3 F2F7F2F7 E2

Interpretation:

Display in an alternating fashion message 0 (bytes 1-8) "RBT0022 " and message 1 (bytes 9-16) "MBT2727S". Stop displaying (or never display) message 0 when the tape is removed from the drive. Stop displaying (or never display) message 1 when the tape drive is next loaded. In other words, “Remove volume BT0022, then Mount volume BT2727.

Virtuent would interpret this as a valid mount request for standard labeled volume BT2727.

Help and Service Information 147

Help and Service Information If you have questions about your new Bus-Tech product, or require technical assistance, visit the Bus-Tech Web site at http:\\www.bustech.com. You can also get help and information through the Bus-Tech’s Technical Support line, Monday through Friday, 8:30 am – 5:00pm Eastern time. Response time may vary depending on the number and nature of the calls received.

Step 1: Problem Solving

You may be able to solve the problem yourself. Before calling Technical Support, please prepare for the call by following these steps:

1. If you are having installation or configuration problems, refer to the detailed installation and configuration sections found in this manual and review any README.TXT files found on the installation disk(s).

2. Visit the Technical Support section of the Bus-Tech Web site specific to the product you have purchased. Updated installation instructions, hints, and tips, software, or updated system-specific notes are often published in this section.

Step 2: Preparing for the Call

To assist the technical support representative, have available as much of the following information as possible:

1. Product Name.

2. Product Release number.

3. Product Serial Number.

4. Exact wording of the error message (if any).

5. Description of the problem.

6. Hardware and software configuration information for your system.

If possible, be at your computer. Your technical support representative might want to walk you through the problem during the call.


Step 3: Placing the Call

If you call after your warranty or maintenance contract has expired, you might be charged a fee.

Support 8:30am – 5:00pm, Monday-Friday

U.S.A. / Puerto Rico 1-800-284-3172

From Outside the U.S.A. 1-781-272-8200

Additional Technical Support Resources

Online technical support is available through the Internet during the life of your product.

Online Technical Support

Bus-Tech Web Site www.bustech.com

Index 149

Index 3480/3490/3590, 1, 32, 33, 45, 138, 143 3490/3590 MTL, 33 3590/3490E

SCSI, 121 Active configuration, 29 Active Directory, 105 admin, 105 ALLOWVSEUTILITIES, 55 AWSTAPE, 1, 141 BIM-EPIC, 19, 57, 58, 64, 65, 66, 67, 69, 90 BTIMOUNT, 58 BTITAPE, 60, 65 CA-EPIC, 66 CCWs, 2, 143 commands, 87

EXPORT, 88 HELP, 88 IMPORT, 89 INITIALIZE, 89 LOAD, 90 MOUNT, 90 NOCHECK, 95 QUERY, 91 QUIESCE, 92 READY, 92 REWIND, 93 SAVE TRACE, 93 SET, 94 SET IDRC, 94 SET PATH, 94 SET RECOVER, 95 SET SIZE, 95 SET TRACE, 95 SET WARNING, 95 SHOW, 96 UNLOAD, 97 UNQUIESCE, 98 UNREADY, 98

configuration control unit, 22 displaying, 91 general parameters, 26 IDRC, 23 LABELS, 24 maximum device address, 22

tapelib path, 22 virtual devices, 19

Data Compression, 45, 69, 94 Data Exchange, 127 Date

NTP Server, 99 device

trace, 24 DFSMShsm, 44 Direct Tape, 121

Compression, 123 Encryption, 123

Disk Subsystem, 7 Dynam/T, 55, 56, 57, 58, 59, 60, 61, 62, 63,

64, 69, 130 Encryption, 117

key, 23 Encryptkey, 94 end of volume

logical, 95 physical, 95

Export, 121, 125 Encryption, 125

FCB, 144 flat files

inputting, 131 outputting, 131

GROUP, 23, 56, 58, 69, 130 help command, 88 IDRC, 94 Import, 121, 126 initializing scratch tapes, 86, 89 Installation, 3 LDAP, 105, 106 Lightweight Directory Access Protocol, 105 lock directory, 7, 11, 16 Log Files, 104 logical end of volume, 95 Manual Tape Library, 33 Max Tapes Report, 53 missing interrupt handler (MIH), 45 mount loop, 138 MVS, 31 NOWTOR, 111, 112, 115 OS/390, 31, 130, 131


OS-2200, 79 OSADDR, 24, 56 physical end of volume, 95 PRIVAT, 136 quiesce, 92 readonly, 105 ready state, 92, 98 recover amount, 20 recover percent, 19, 95 rejected paths, 96 RESET CHANNEL ADAPTER, 93 RMM, 41 Scratch Pool, 62 scratch synonyms, 91 scratch tape, 89

initializing, 89 scratch volumes, 37 Scratch Volumes, 86 SCRTCH, 136 Slow Mounts Report, 53 Still in Use Report, 54 STOP CHANNEL ADAPTER, 97 SYNCTIME, 51 System Operation, 83 tape labels

ANSI, 90 IBM, 90 unlabeled, 90

Tape Library Adding a New Subdirectory, 11 Initializing Scratch Tapes, 86 Overview, 7 Query Space, 91

tape size, 95 Throughput Report, 52 Time

NTP Server, 99 TLMS, 42 TMS, 41 traces, 93, 95 UIM, 32, 35 Unisys

Autodetection, 79 Initializing Tapes, 81 Labels, 80

Mount Ready Interrupt, 79 Query Config, 79 Ring-Out, 79 Scratch Tapes, 80

unlabeled tapes, 90 unloading a tape, 97 unquiesce, 98 User Administration, 105 Utilities, 31

Export, 124, 125 Import, 124, 126 VTCMD, 42 VTLIB, 34 VTSCR, 37

VIRCMD, 57, 69, 70, 71 VIRDTERA, 56, 57, 64 VIRDTEXT, 57, 61, 62 VIRDTSCR, 56, 57, 63 VIREPERA, 56, 57, 68, 69 VIREPSCR, 56, 57, 68 VIRLDSPL, 56, 60, 65 VIRMAINT, 56, 57, 59 VIRMOUNT, 23, 24, 56, 57, 58, 130, 132 VIRSSD, 56, 57, 58, 59, 60, 61, 62, 63, 69 VIRSSE, 56, 57, 58, 63, 65, 66, 69 Virtual Devices, 19

Configuring, 19 VM

DMSG, 73 Mount Tape, 73

VM Support, 73 volser, 133, 136 volume size, 24, 95 VSE, 55, 130, 132 VTCMD, 42, 77 VTLIB, 34 VTSCR, 37, 74

Parameters, 74 Report Type, 74 VMTAPE, 74

VTSLOG, 40 warning percent, 19, 95 write protect, 91 WTOR, 109, 112, 114 z/OS, 31, 130, 131

Customer Response If you have comments or suggestions regarding our products and documentation, please send them to:

BUS-TECH, INC. 26 Crosby Drive, Suite 100

Bedford, MA. 01730 ATTENTION: CUSTOMER SUPPORT

Or, call us at: (781) 272-8200 FAX: (781) 272-0342. Or, visit our Web Site at: www.bustech.com

Virtuent User’s Guide Part Number 40-03377-E0-001 October 2010

Date post:	28-Oct-2014
Category:	Documents
Upload:	keydet88
View:	472 times
Download:	11 times

Virtuent User Guide Rel 7

Documents