z/VSE Virtual Tape Support

z/VSE Virtual Tape Support

The Virtual Tape function of z/VSE is described in the VSE/ESA Release Guide V2.6, "Chapter 7:
Virtual Tape Support". This chapter describes important aspects of using and working with the
Virtual Tape Support available with z/VSE 4.1.

In general, the Virtual Tape Support included in VSE is intended to be transparent to applications
and to provide the customer with the ability to read from or write to a virtual tape in the same way
as if it were a physical tape. For technical and performance reasons, the full range of the
capabilities of a physical tape has not been implemented.

Before you use the VSE Virtual Tape Support, please check for PTFs related to your particular
VSE release. Refer to the VSE Homepage for more information.

The following sections are available in this document:

Storage Requirement .................................................................................................................. 2

Defining a Virtual Tape by Job Control Commands.................................................................... 2
Recommendations for the definition of a VSAM virtual tape file ............................................ 2
Recommendations for the definition of remote Virtual Tapes.................................................. 3
Sample jobs ............................................................................................................................ 4
Terminating Virtual Tape operations........................................................................................... 5
Cancellation of an I/O operation to a virtual tape .................................................................... 5
Termination of the Tape Data Handler .................................................................................... 5
Performance considerations ........................................................................................................ 6
Restrictions................................................................................................................................. 7
Limitation for writing data to a VSAM virtual tape................................................................. 7
No alternate tape support: ....................................................................................................... 7
The DITTO "ERASE TAPE" function is not supported for virtual tapes: ................................ 7
SDAID does not support virtual tapes to be used as OUTDEVICE ......................................... 7
No virtual tape support in a stand alone environment .............................................................. 7
Current restriction with respect to label processing ................................................................. 7
Diagnostic Aids .......................................................................................................................... 9
Tracing the Tape Data Handler ............................................................................................. 10
Tracing remote Virtual Tapes................................................................................................ 10
Browser for AWSTAPE files ................................................................................................ 10
ListVOL1 utility ................................................................................................................... 10
Messages 1YM7T or 1YN1D Errors..................................................................................... 11
Loop using VSAM Virtual Tape and TCP/IP 1.5E ................................................................ 11
VTAPE doesn't use PC directory specified by FILE parameter ............................................. 11

Copyright IBM Corp. 2007 Page 1

z/VSE Virtual Tape Support

Storage Requirement
The I/O Supervisor allocates a 1MB buffer for each Virtual Tape in the System-Getvis area of your
VSE system. The buffer space is taken preferred out of the System-Getvis 31 area and PFIXed. It is
used to buffer the tape data before writing/reading them to/from the Virtual Tape. So before using
the "VTAPE START" command make sure that enough PFIXed space is available in the System-
Getvis area of your VSE system.

If the system is short on PFIXed System Getvis storage message 1YN1t (Tape simulator
encountered internal error) is displayed in response to the "VTAPE START" command.

You can check the free PFIXed System-Getvis space of your VSE system by issuing the AR
command "MAP SVA".

Defining a Virtual Tape by Job Control Commands

Every job containing a "VTAPE START,UNIT=<cuu> ..." JCC statement should contain an "ON
$CANCEL GOTO <label>" statement where the label points to the "VTAPE STOP,UNIT=<cuu>"
command. This makes sure that the virtual tape will always be closed at the end of the job - even if
the job is cancelled.

Recommendations for the definition of a VSAM virtual tape file

The VSAM file which should contain the tape image for the VSAM virtual tape must be defined
before a "VTAPE START" command can be issued. It is recommended to use the skeleton
SKVTAPE in the ICCF library 59 for the definition of a VSAM virtual tape file.

Following are some recommendations how to specify the parameters for the definition of a VSAM
virtual tape file:

Share Options Settings for VSAM Virtual Tapes:

The Tape Data Handler will only accept single write or multiple read accesses to a VSAM Virtual
Tape from a single z/VSE system. Therefore it is recommended to specify Share Option 1 for the
creation of a VSAM virtual tape file.

This is also true for a multiple z/VSE system environment. Multiple write access to a single Virtual
Tape will cause unpredictable results. Therefore use also Share Option 1 for the definition of a
VSAM tape image file in a multiple VSE system environment.

REUSE Parameter: Specify NOREUSE if you want to write once on the Virtual Tape and
only read it afterwards. Specify REUSE if you want to use the Virtual Tape as a work file.

Record and Control Interval Size: It is recommended to specify 32k for the control
interval size. Make sure that the record size is at least 10 bytes smaller than the control
interval size.

Copyright IBM Corp. 2007 Page 2

z/VSE Virtual Tape Support

Recommendations for the definition of remote Virtual Tapes

Starting the Virtual Tape with the correct stack number

When the VTAPE function is configured/started for the first time message 1YN1D TAPE
SIMULATOR ENCOUNTERED INTERNAL ERROR may be issued. This could be caused by
non-matching TCP/IP stack definitions:

The TAPESRVR job is started with // OPTION SYSPARM='00' and will try to connect to TCP/IP
stack '00'. The problem occurs if the TCP/IP stack has been started with a different stack number,
for example '02'. Therefore no connection can be established and message 1YN1D is issued.

On the PC, the Virtual Tape Server will not show any connection or error messages at all. To solve
that problem include/adapt the // OPTION SYSPARM='nn' statement in your TAPESRVR startup.
You can use skeleton SKVTASTJ in ICCF library 51 to do so.

File name considerations for remote Virtual Tapes

Windows, UNIX or Linux folder names and file names may contain blanks, therefore the FILE
parameter must be enclosed in quotes. A quote within filename must be coded as two single quotes,
for example:

FILE='D:/Frank''s/Virtual Tapes/vt021401.001'

Windows, UNIX or Linux can have more than 100 characters in length. Therefore you may specify
FILE='filename' twice or even three times. The filename information is concatenated in storage,
thus allowing for a file name length of 200 or even 300. The following example is equivalent to the
one from above:

FILE='D:',FILE='/Frank''s/Virtual Tapes/',FILE='vt021401.001'

Windows usually uses back slashes to separate directories (e.g. C:\vtape\tapeiamge.aws). Back
slashes often causes EBCDIC to ASCII code page translation problems; they are translated into
some incorrect characters. Therefore we recommend using forward slashes (e.g.
C:/vtape/tapeiamge.aws) with VTAPE, even when using Windows. Forward slashes usually do not
cause codepage translation problems.

The Java runtime automatically converts forward slashes into back slashes on Windows. If back
slashes are used it can happen that the filename on Windows is treated as relative path instead of an
absolute path and the tape image is created in the Virtual Tape Server's installation directory. This
is because Windows does not recognize the path as absolute if the back slashes are translated into
some incorrect characters.

Copyright IBM Corp. 2007 Page 3

z/VSE Virtual Tape Support

Sample jobs

The following sample job illustrates the use of VTAPE to backup a VSE library:

// JOB BACKUP (Backup a Library to a PC File)

// ON $CANCEL OR $ABEND GOTO VTAPSTOP
VTAPE START,UNIT=480,LOC=9.164.186.20:2285, C
FILE='D:\VSE Backup\prd2.001'
MTC REW,480
// EXEC LIBR
BACKUP LIB=PRD2 TAPE=480
/*
/. VTAPSTOP
VTAPE STOP,UNIT=480
/&

The following job illustrates the use of VTAPE in combination with logical units:

* $$ JOB JNM=VSAMBKUP,DISP=L,CLASS=0
// JOB VSAMBKUP
// ON $CANCEL OR $ABEND GOTO VTAPSTOP
* THIS JOB BACKS UP VSAM DATASETS
// DLBL IJSYSUC,' catalog ',,VSAM
VTAPE START,UNIT=181,LOC=ip-addr,FILE='filename on workstation',SCRATCH
// ASSGN SYS005,181
// EXEC IDCAMS,SIZE=AUTO
BACKUP ( cluster ) -
REW
NOCOMPACT -
BUFFERS(3)
/*
/. VTAPSTOP
// ASSGN SYS005,UA
VTAPE STOP,UNIT=181
/&
* $$ EOJ

Note: If you omit the ASSGN SYS005,UA, you will receive message 1YN5D TAPE 181 IS
ASSIGNED at VTAPE STOP.

Copyright IBM Corp. 2007 Page 4

z/VSE Virtual Tape Support

Terminating Virtual Tape operations

Cancellation of an I/O operation to a virtual tape
A CANCEL cuu, FORCE command to a Virtual Tape will not always terminate an I/O operation to
a Virtual Tape. But in case of a VSAM virtual tape this is the only possibility to terminate an
ongoing I/O operation. Check after the successful cancellation with LISTIO,<cuu> for remaining
logical assignments to the virtual tape and un-assign them with the ASSGN SYSxxx,UA
command before you reuse the virtual tape.

Update available with DY45848 / UD52135

If you issue a "CANCEL <cuu>,FORCE" command and the CUU is used to access a remote virtual
tape, then as consequence of the cancel command it may happen that the CUU can no longer be
used to access the virtual tape. To be able to re-use the CUU again, do the following:
Issue a "VTAPE STOP" command for the CUU whose I/O was canceled.
Define the virtual tape again with a "VTAPE START ... command.

In case of a remote virtual tape, the easiest way to cancel an ongoing I/O operation is to flush the
connection:
Enter
xxx FLUSH <ip-address of the remote vtape>,<port of remote vtape>
where xxx is the partition ID of the TCP/IP partition.

This causes TCP/IP for z/VSE to flush all data and terminate all connections with the specified IP
and port address. The virtual tape can no longer be used after the flush command. After the flush
command, check for any logical assignment to the virtual tape by entering the AR command:
LISTIO <cuu> where <cuu> is the physical address of your virtual tape. Issue an ASSGN,
SYSxxx,UA command for each assignment that still exits for the virtual tape. After that terminate
the virtual tape with:
VTAPE STOP,UNIT=<cuu>.
This will cause the necessary cleanup so that you should be able to restart the virtual tape with a
VTAPE START command after that.

Termination of the Tape Data Handler

The Tape Data Handler is to be considered as a subsystem in the VSE system. Therefore it is not
recommended to cancel the Tape Data Handler with the intention to terminate virtual tape
processing.

If you want to terminate the Tape Data Handler Subsystem then close all virtual tapes with the
"VTAPE STOP" command. The Tape Data Handler will then automatically terminate after 30
seconds. To find out which tape units are defined as virtual, use the VOLUME command. After the
termination of the Tape Data Handler verify after that no virtual tapes are active any more. In case
there are still virtual tapes defined, issue a 'VTAPE STOP against the remaining virtual tapes.

In case the Tape Data Handler is canceled due to an error condition (for instance program check)
you must close all open virtual tapes to avoid inconsistencies in the system. Display the open
virtual tapes with the AR command "VOLUME". A tape device type of "VTAP-00" in the
command output indicates a virtual tape.

Copyright IBM Corp. 2007 Page 5

z/VSE Virtual Tape Support

Performance considerations
If there is a remote Virtual Tape started whose TCP/IP connection is slow, then this may have an
impact on the performance of other Virtual Tapes. Therefore ensure that the TCP/IP connection to
the Virtual Tape is stable and fast enough to handle high data transfer rates.

Using TCP/IP 1.5E, the performance of sending data to a remote host can be improved be setting
the "Send Performance Option". This option can be activated in the $SOCKOPT.PHASE. By
default it is not set. Before setting the option you must install the zap ZP15E101. The zap can be
downloaded from the CSI Home Page. Setting the Send Performance Option results in TCP/IP
sending out data packets without waiting for an ACK (acknowledgement).

The following job provides a new $SOCKOPT.PHASE with the Send Performance Option set.
Ensure, that the library with the new $SOCKOPT.PHASE is in front of the TCP/IP library in the
LIBDEF SEARCH CHAIN.
* $$ JOB JNM=SOCKOPT,CLASS=0,DISP=D
// JOB $SOCKOPT
// OPTION CATAL
LOG
// LIBDEF *,SEARCH=PRD2.TCPBETA
// LIBDEF *,CATALOG=PRD2.TEST
* Catalog a new $SOCKOPT phase for TCP/IP 1.5E which includes the
* CSI-supplied options plus the "do not wait after send" option.
* Please ensure that the library with this new $SOCKOPT phase is in
* front of your TCP/IP library within your appl's LIBDEF chain.
NOLOG
// PAUSE OK? Press ENTER to continue
// EXEC ASMA90,SIZE=ASMA90,PARM='SZ(MAX-200K,ABOVE)'
PUNCH ' PHASE $SOCKOPT,* '
$SOCKOPT CSECT
*
* * This phase is used by the BSD-C and SSL interfaces to set options
* * that affect the operation of the interface in a partition...
*
SOCKOPT CSECT, Generate a csect X
BSDCFG1=$OPTSNWT+$OPTMECB, NO-ACK-WAIT, M-ECB-Support X
BSDCFG2=00, Option flag 2 X
CLST=-1, Seconds to wait for close X
CSRT=59, Seconds before socket reuse X
SSLLIBN=KEYLIB, SSL library name X
SSLSUBN=SSLKEYS, SSL sublib name X
SSLMEMN=MYKEY512, SSL member name for keys X
SSLDEBG=00, SSL debugging flag X
SSLFLG1=00, $OPTSRQC, SSL req close_notify alert X
SSLFLG2=00, $OPTSFZA, Force use Z/arch instructns X
SSLFLG3=00, SSL option flag 3 X
SSLSTOR=80, SSL storage useage percent X
SYSID=00, Use this TCP/IP sysid X
SNOWMAX=262144, 256K max for send nowait X
BSDXPHS=IPNRBSDC Name of BSD/C phase
*
END $SOCKOPT
/*
/&
* $$ EOJ

Copyright IBM Corp. 2007 Page 6

z/VSE Virtual Tape Support

Restrictions

Limitation for writing data to a VSAM virtual tape

The VSAM virtual tape is intended for sequential read and write access. After a "VTAPE START"
command data can be written sequentially to the VSAM virtual tape starting from the beginning of
the tape. No partial overwrite of data is possible. It is only possible to overwrite all the data starting
from the beginning of the tape. To do this, position the tape at the beginning and then write your
data.

Make sure, that the virtual tape is defined with the "REUSE" parameter, otherwise no overwrite at
all is possible. Once a "VTAPE STOP" command has been issued the EOV ("end of volume")
indication is written to the virtual tape and no further data can be appended. Even when the virtual
tape is re-defined with a new "VTAPE START" command, writing to the tape must start again at
the beginning of the tape.

No alternate tape support:

There is no alternate tape support for virtual tapes. In case of a VSAM virtual tape choose the
primary and secondary allocation of the virtual tape file large enough so that an "end of volume"
condition does not occur during processing of the virtual tape. In case of a remote virtual tape the
size of the remote virtual tape file is assigned due to the PC file rules. Look at them if you get an
"end of volume" condition for your remote virtual tape.

The DITTO "ERASE TAPE" function is not supported for virtual tapes:
An application issuing the ERASE TAPE function will be cancelled. Use the equivalent VSAM
and PC file system functions instead.

SDAID does not support virtual tapes to be used as OUTDEVICE

SDAID does not support virtual tapes to be used as OUTDEVICE. However, tracing virtual tape
I/Os is possible.

No virtual tape support in a stand alone environment

There is no virtual tape support in a stand alone environment.

Current restriction with respect to label processing

The following job sequence will cause a deadlock between the BG and the Tape
Data Handler partition:

// OPTION STDLABEL=ADD
// DLBL VTAPFIL,'VTAPFIL.TEST.FILE',,VSAM,CAT=IJSYSCT
// VTAPE START,UNIT=181,LOC=VSAM,FILE='VTAPFIL'

The problem is that the VTAPE command will cause a deadlock, if the BG partition is concurrently
updating system standard labels (that is // OPTION STDLABEL is in effect).

Copyright IBM Corp. 2007 Page 7

z/VSE Virtual Tape Support

Circumvention: Terminate the standard label processing for example by issuing "// OPTION
USRLABEL" before the 'VTAPE START' statement. A correct job control sequence is therefore:

// OPTION STDLABEL=ADD
// DLBL VTAPFIL,'VTAPFIL.TEST.FILE',,VSAM,CAT=IJSYSCT
// OPTION USRLABEL
// VTAPE START,UNIT=181,LOC=VSAM,FILE='VTAPFIL'

Copyright IBM Corp. 2007 Page 8

z/VSE Virtual Tape Support

Diagnostic Aids
In case of an error situation in virtual tape processing, z/VSE will sometimes return sense
information for the Virtual Tape. The sense information contains a reason code in the bytes 14-15
and a return code in bytes 16-17.

Example:

BG 14 0P49I C PERM ERROR SYS_99=280

CCSW=010051D1B0020040DC CCB=51D178
SNS= 10442047 00002120 00000000 00000196 00C80088 04010101
010100F0 000000FF

In the above example the return code is x00C8 and the reason code is x0196

The Return and Reason Codes are also contained in the Trace for the Tape Data Handler.

Return Codes (hex):

0064 TCP/IP connection error

00C8 VTAPE error
0012C internal error
00190 Tape data handler was cancel

Reason Codes (hex):

0067 allocation of control blocks failed

0069 write access to vtape requested but only read access allowed
006F host name could not be resolved
00CD the same virtual tape is used concurrently with read and write access
00CE user requested cancel
00CF Tape Data Handler canceled
012F no socket received for connection
0130 session could not be established - maybe wrong ip address specified
0132 unrecoverable send error
0133 unrecoverable read error
0134 error when closing the connection
0135 allocation of control blocks failed
0138 timeout when establishing the session - no session established
0191 invalid parameter
0192 null pointer , coding error or GETVIS problem
0193 OPEN failure of VTAPE image
0195 no vaild AWSTAPE format
0196 write rejected , not EOF or file not defined as REUSE
0197 read error , e.g I/O error
0198 write error e.g no more space / extents available
019A repositioning error , intenal error e.g I/O error
019C buffer handling error , invalid buffer format
019E buffer too small, internal error

Copyright IBM Corp. 2007 Page 9

z/VSE Virtual Tape Support

Tracing the Tape Data Handler

To enable the VTAPE trace, change the TAPESRVR job (use skeleton SKVTASTJ in ICCF lib 59)

// EXEC $VTMAIN,SIZE=$VTMAIN,PARM='TRACE'

and set DEBUG ON. The Trace messages will go to SYSLST (job output).

Note: The TAPESRVR completes with a return code of 0008 when running with trace active.

Tracing remote Virtual Tapes

To trace the Virtual Tape Server running on a java platform do the following:
1. Set messages=on in the VirtualTapeServer.properties file. This will show some more trace
messages written to STDOUT. See especially the Exceptions in this trace.
2. Edit the run.bat or run.cmd start script and change the java call as follows:
java -Dcom.ibm.vse.vtape.trace=trace.txt com.ibm.vse.vtape.VirtualTapeServer
This activates the internal trace. Trace output goes to a file named trace.txt in the current
directory.
3. Set the TCP/IP BSD Trace on. Rename XSOCKDBG.PHASE in PRD1.BASE to
$SOCJDBG.PHASE. This shows Trace messages on SYSLOG/SYSLST for each Socket
call.

Browser for AWSTAPE files

To aid those users seeking tools and information for so-called AWS or AWSTAPE virtual tapes,
the following links may be of help:
http://www.cbttape.org/awstape.htm
or
http://www.cbttape.org/~fish/hercgui-index.html

ListVOL1 utility
The ListVOL1 utility (download here
http://www.ibm.com/servers/eserver/zseries/zvse/downloads/tools.html#listvol1)
reads the first 2 tape records of tape image in AWSTAPE format residing in a VSAM ESDS cluster.
It prints the VOLSER and FILEID from the VOL1 and HDR1 labels on the tape. ListVOL1 runs in
a VSE partition (dynamic or static). The partition size must be at least 5 MB. ListVOL1 is started
using

// EXEC LISTVOL1
<DLBL name of VSAM file>
<DLBL name of VSAM file>
/*

where <DLBL name of VSAM file> specifies the DLBL name of a VSAMESDS cluster containing
a VTAPE tape image in AWSTAPE format.

The output looks as follows:

LISTVOL1 UTILITY - LIST VOL1/HDR1 LABELS OF VTAPES

FILENAME: VOLSER FILE-ID
-----------------------------------------------------
Copyright IBM Corp. 2007 Page 10
z/VSE Virtual Tape Support

VTAPE1 : TAPE  TAPE.DATASET. 

VTAPE2 : PRDDAT PRODUCTON.DATA
VTAPE3 : BACKUP MY.BACKUP.FILE
-----------------------------------------------------
LISTVOL1 UTILITY - FINISHED

Messages 1YM7T or 1YN1D Errors

The following error messages 1YM7T TAPE DATA HANDLER ENCOUNTERED
CONNECTION ERROR or 1YN1D TAPE SIMULATOR ENCOUNTERED INTERNAL
ERROR may have other explanations than found in the message explanation:

1. TCP/IP for z/VSE has been started with a system whose system ID is specified:

// EXEC IPNET,SIZE=IPNET,PARM='ID=nn,INIT=.....

Where the default for "nn" is "00". To use the TCP/IP services from within another partition
this partition has to 'know' the system ID. This is specified as follows:

// OPTION SYSPARM='nn'

where 'nn' is the system ID. Customers may use the skeleton SKVTASTJ in ICCF lib 59 to
add this statement. This is described in TCP/IP for VSE Programmer's Reference

2. The wrong $EDCTCPV.PHASE is used. VSE ships a dummy $EDCTCPV.PHASE in

PRD2.SCEEBASE. TCP/IP ships a second $EDCTCPV.PHASE (typically in PRD1.BASE
or in the product library). In case the dummy phase from PRD2.SCEEBASE is used, socket
calls will not work. Instead an EDCxxx message is issued to SYSLST: "EDCxxx Function
nnn not implemented". Make sure the $EDCTCPV.PHASE from TCP/IP is used (adjust the
LIBDEFs).

Loop using VSAM Virtual Tape and TCP/IP 1.5E

Using VSAM Virtual Tapes together with TCP/IP 1.5E may cause a loop. Install PTF UD53047
(available for z/VSE 3.1) to fix this problem.

VTAPE doesn't use PC directory specified by FILE parameter

When specifying file names, the following should be considered.
Windows, UNIX or Linux folder names and file names may contain blanks, therefore the FILE
parameter must be enclosed in quotes. A quote within filename must be coded as two single
quotes, for example:

FILE='D:/Frank''s/Virtual Tapes/vt021401.001'

Windows, UNIX or Linux can have more than 100 characters in length. Therefore you may
specify FILE='filename' twice or even three times. The filename information is concatenated in
storage, thus allowing for a file name length of 200 or even 300. The following example is
equivalent to the one from above:
Copyright IBM Corp. 2007 Page 11
z/VSE Virtual Tape Support

FILE='D:',FILE='/Frank''s/Virtual Tapes/',FILE='vt021401.001'

Windows usually uses back slashes to separate directories (e.g. C:\vtape\tapeiamge.aws). Back
slashes often causes EBCDIC to ASCII code page translation problems; they are translated into
some incorrect characters. Therefore we recommend using forward slashes (e.g.
C:/vtape/tapeiamge.aws) with VTAPE, even when using Windows. Forward slashes usually do
not cause codepage translation problems. The Java runtime automatically converts forward
slashes into back slashes on Windows. If back slashes are used it can happen that the filename
on Windows is treated as relative path instead of an absolute path and the tape image is created
in the Virtual Tape Server's installation directory. This is because Windows does not recognize
the path as absolute if the back slashes are translated into some incorrect characters.

Copyright IBM Corp. 2007 Page 12