6 VTCS Stand-Alone Utilities

This chapter describes VTCS stand-alone utilities. These utilities are not issued using the common utility administrator program (SLUADMIN).

RTV Utility

The RTV utility converts VTVs contained on MVCs to data sets on volumes (real tape volumes). This utility is a standalone utility executed using the SWSRTV program.

Refer to the publication Managing HSC and VTCS for detailed information about when to use this utility.

Note:

The RTV utility does not support LTO Generation 6, 7, or 8 media and drives.

Syntax

Figure 6-1 shows RTV utility syntax.

Figure 6-1 RTV utility syntax

Surrounding text describes Figure 6-1 .

Parameters

As shown in Figure 6-1, the RTV utility includes the following parameters:

MVCid

specifies the MVC that contains the VTVs that RTV converts to volume(s) which become real tape versions of the VTVs.

volser indicates the MVC volser.

INUNIT

specifies the name to use to allocate the input tape unit. You can specify an MVS unit address, an esoteric name, or a generic name. The valid values are the same as for the UNIT= JCL parameter.

name indicates the unit name.

VTVid

optionally, specifies one or more VTVs to convert.

volser, vol-range, or vol-list indicate the volsers of one or more VTVs.

ALLVTVS

optionally, convert the most current copy of all VTVs on the specified MVC. That is, if there are multiple copies of a VTV on the specified MVC, RTV only converts the most current copy of the VTV.

Note:

VTVid and ALLVTVS are mutually exclusive.
CPYVOLID

optionally, copy the VTV internal volser from the VTV to the output volume VOL1 record. The default is to not copy the internal volser.

Caution:

Use the CPYVOLID parameter carefully! The volser of the output tape will be changed to the volser of the VTV. If the output tape has an external label or if the output is directed to another VTV, this will cause label mismatches and can cause unpredictable and undesirable results.

Note:

  • If the output tape is non-labelled or has a non-standard tape label, CPYVOLID will be automatically specified for this VTV decompression, and a standard label tape will be created on the output device.

  • RTV supports VTVs created with standard or ANSI labels. If you do not specify CPYVOLID, RTV processes these label types as described in Table 6-1. Note that this only applies to the VOL1 record. The HDR1/HDR2 labels are always copied from the VTV by RTV for every VTV processed.

The following table lists RTV label types:

Table 6-1 RTV Label Types

VTV Label Type Output Standard Label Output ANSI Label Output Non-Label

Standard label

VOL1 label not copied

WTOR issued

VOL1 label is copied

ANSI label

WTOR issued

VOL1 label not copied

VOL1 label is copied

In Table 6-1, the WTOR is as follows:

SWSRTV - Label mismatch - Reply RELABEL, RETRY, or CANCEL

The operator responses produce the following results:

  • RELABEL specifies to decompress the RTV and overwrite the volser on the output volume.

  • RETRY specifies to mount another output volume and retry the operation.

  • CANCEL specifies to not decompress the RTV.

LISTONLY

optionally, lists (but does not convert) the VTVs on the specified MVC. For more information, see "RTV LISTONLY Listing".

BLOCKID

optionally, specifies the logical block ID where the VTV begins on the MVC.

block-id is the logical block ID (8 hexadecimal characters).

Note:

  • BLOCKID and LISTONLY are mutually exclusive. In addition, if you specify the ALLVTVs parameter, or if a list or range of VTVs is specified, the BLOCKid parameter is ignored.

  • Not specifying a BLOCKid value can cause very long execution times with high capacity media. The BLOCKid is used for high speed positioning to a VTV on the MVC.

  • The LISTONLY parameter listing on ”RTV LISTONLY Listing” on page 777 supplies a Block ID value that you can use as input to the RTV utility to convert a VTV to a volume.

PRTID

optionally, specifies the partition id of the VTV being recovered from a partitioned MVC.

partition-id is the hexadecimal partition ID.

Note:

  • If PRTID is specified, BLOCKid must also be specified.

  • PRTID and LISTONLY are mutually exclusive. In addition, if you specify the ALLVTVs parameter, or if a list or range of VTVs is specified, the BLOCKid parameter is ignored.

DUMP

produce a S0C3 abend dump if RTV cannot decompress a VTV. If you specify DUMP, create a SYSMDUMP DD JCL statement to capture the dump.

OUTUNIT

the name to use to allocate the output tape unit. You can specify an MVS unit address, an esoteric name, or a generic name. The valid values are the same as for the UNIT= JCL parameter. This parameter is required if you do not specify LISTONLY.

name is the unit name.

VALIDATE

Validates that the RTV utility can successfully process the specified VTV(s) without creating an output tape.

JCL Requirements

The following are required or optional statements for the RTV utility JCL:

STEPLIB

specifies the link library (SEALINK) that contains the RTV modules.

SLSPRINT

specifies the destination of the RTV utility report.

SLSIN

specifies the input to the SWSRTV program (RTV utility name and parameters).

SYSMDUMP

optional DD to capture dump.

Note:

Because the RTV utility must be capable of rewriting the tape standard labels on the output unit and positioning over label information on the input unit, Dynamic Allocation is used to invoke bypass label processing (BLP) on the tape volumes. This requires that the library that contains the SWSRTV executable code be APF authorized.

RTV Utility Report Messages

The RTV report displays the following messages:

Block number too large in compressed data

Explanation: An error was found in a compressed data record while processing a VTV. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Chunked record logic error

Explanation: An error was found while processing a chunked data record for a VTV. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Decompress invalid length parameter

Explanation: This indicates a program logic error. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Decompress invalid parameter list

Explanation: This indicates a program logic error. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Decompress logic error

Explanation: This indicates a program logic error. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Decompress pointer to work area is zero

Explanation: This indicates a program logic error. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Dynamic allocation error. Reason Code = xxxx-xxxx

Explanation: An error was encountered while attempting to dynamically allocate the INUNIT or OUTUNIT device. Refer to the IBM MVS Authorized Assembler Services Guide for a description of the dynamic allocation reason codes.

I/O error on input MVC

Explanation: An I/O error was encountered while reading a MVC. Further processing is stopped. The utility terminates with return code 12.

I/O error on output volume

Explanation: An I/O error was encountered while writing the output VTV. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary

Invalid compressed data block read

Explanation: This indicates that an invalid data record was found while processing this VTV. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Invalid VTV page number encountered

Explanation: A record sequence error was found in a compressed data record while processing a VTV. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Invalid VTV record encountered

Explanation: An error was found in a compressed data record while processing a VTV. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

MVC volser # does not match requested volser #

Explanation: The volume mounted as the input MVC did not match that requested by the MVCid() parameter. The utility terminates with return code 12.

MVC record length error

Explanation: A length error was found in a compressed data record while processing a VTV. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Incorrect algo byte

Explanation: Explanation: An error was found in a compressed data record while processing a VTV. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

No HDR1 record found for requested VTV

Explanation: Following positioning by a BLOCKid() statement, there was no HDR1 record located at the desired position. Remove the BLOCKid statement and rerun the utility. The utility terminates with return code 12.

No HDR1 record found on input MVC

Explanation: The volume mounted as a MVC contained no HDR1 record. The utility terminates with return code 12.

No UHL1 record found on input MVC

Explanation: The volume mounted as a MVC contained no UHL1 record. The utility terminates with return code 12.

No VOL1 record found on input MVC

Explanation: The volume mounted as a MVC contained no VOL1 record. The utility terminates with return code 12.

NULL input buffer pointer

Explanation: This indicates a program logic error. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

NULL output buffer pointer

Explanation: This indicates a program logic error. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Requested VTV not found on MVC

Explanation: The volser requested by the VTVid() parameter was not found on the MVC. The utility terminates with return code 12.

Spanned length final error

Explanation: An error was found while processing a spanned data record for a VTV. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Spanned length intermediate error

Explanation: An error was found while processing a spanned data record for a VTV. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Unexpected request on input I/O

Explanation: This indicates a program logic error. Further processing is stopped. The utility terminates with return code 12.

Unexpected end of tape on output volume

Explanation: While writing the output VTV, an end of tape indication was encountered. The VTV must be completely contained on a single output volume. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Unexpected request on output I/O

Explanation: This indicates a program logic error. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

Unexpected tape mark on input MVC

Explanation: An unexpected tape mark was found on a MVC. Further processing is stopped. The utility terminates with return code 12.

VTVid range parameter is invalid

Explanation: An invalid range value was found in the VTVid() specification. The utility terminates with return code 12.

VTV logical data check encountered

Explanation: A data check indicator was found in a compressed data record while processing a VTV. Further processing of this VTV is stopped. The VTV will be marked in the RTV Decompress Report output. The utility will continue to process other VTVs as necessary.

VTV volser # does not match requested volser #

Explanation: Following positioning by a BLOCKid statement, the VTV volser did not match that requested by the VTVid() parameter. The utility terminates with return code 12. Remove the BLOCKid statement and rerun the utility.

RTV LISTONLY Listing

The following example shows the listing RTV produces when you specify the LISTONLY parameter.

Example 6-1 RTV LISTONLY Listing

SWSRTV             (1.0.0)         StorageTek VTCS RTV Utility                            PAGE 0001
TIME 14:28:33                   Control Card Image Listing                            DATE 12/01/15
RTV MVC(C83107) LISTONLY

SWSRTV             (1.0.0)         StorageTek VTCS RTV Utility                            PAGE 0002
TIME 14:28:33                   MVC C83107 Contents Report                            DATE 12/01/15

VTV      File   Block            <---Created--->            <---Migrated--->       VTVPAGE   VTV
volser   #      ID          Date            Time       Date             Time       Size      Status
VV6825   1      00000000    20150Nov30      12:07:56   2015Nov30        12:15:56   Large
VV6863   2      92005F0F    2015Sep27       12:57:54   2015Sep27        12:59:54   Large
VV6893   3      92005F18    2015Aug18       08:57:26   2015Aug18        08:59:26   Large
VV0403   4      92005F21    2015Aug18       08:57:26   2015Aug18        08:59:26   Large

This report lists the following information for VTVs:

  • Volser

  • Logical file number on the MVC

  • Block ID on the MVC

  • Time created and migrated

  • VTVPAGE size - STANDARD or LARGE

  • Status - Not Current, or if blank, the VTV is current

RTV Decompress Listing

The following example shows the listing RTV produces when you do not specify the LISTONLY parameter (that is, you run RTV to convert VTVs to volumes).

Example 6-2 RTV Decompress Listing

SWSRTV             (1.0.0)         StorageTek VTCS RTV Utility                            PAGE 0001
TIME 14:28:33                   Control Card Image Listing                            DATE 12/01/15
RTV MVC(C8228) VTV(VV6800-VV6900) CPYVOLID

SWSRTV             (1.0.0)         StorageTek VTCS RTV Utility                            PAGE 0002
TIME 14:28:33                   MVC C83223 Contents Report                            DATE 12/01/15

VTV      File   Block            <---Created--->         <---Migrated--->    VTVPAGE   VTV
volser   #      ID          Date         Time       Date             Time    Size      Status
VV6070   1      00000000    20150Nov30   12:07:56   2015Nov30     12:15:56   Large
VV0874   2      2B001384    2015Sep27    12:57:54   2015Sep27     12:59:54   Large
VV0772   3      A3002707    2015Aug18    08:57:26   2015Aug18     08:59:26   Large
VV6828   4      9B002AB9    2015Aug18    08:57:26   2015Aug18     08:59:26   Large     Not current
VV6828   5      9B002AC2    2015Aug18    08:57:26   2015Aug18     08:59:26   Large
VV6826   6      9B002ACB    2015Aug18    08:57:26   2015Aug18     08:59:26   Large
SWSRTV


SWSRTV             (1.0.0)         StorageTek VTCS RTV Utility                            PAGE 0003
TIME 14:28:33                   MVC C83223 Contents Report                            DATE 12/01/15

VTV             Mounted                                Final                 Decompress
volser          Volser                                 Volser                Status
VV6826          XX0772                                 VV6826                Successful
VV6828          XX0773                                 VV6828                Successful

In addition to the contents fields shown in Figure 67 on page 136, the decompress listing shown in Figure 68 on page 137 lists the VTVs:

  • Volser of the output volume as initially mounted

  • Final volser of the output volume; if CPYVOLID is specified, the final volser will be identical to the VTV volser, otherwise is final volser is identical to the volser of the output volume as initially mounted

  • Decompress status