TMSBLDVR Utility -- Build TMC Volume Ranges Table

The TMSBLDVR program is invoked by TMSXTEND to read the TMC and create a volume range table based on the ranges it finds, then adding or deleting any volume ranges or DSNBs as requested based on the control statements specified in the SYSIN DD. When executed in standalone mode, TMSBLDVR can be used to identify the volume ranges in an existing TMC, validate volume range or DSNB control statements, and determine the size requirement of the new TMC. The TMSBLDVR utility is a subprogram of TMSXTEND that can also be executed to create a new TMC, replacing functionality provided by the TMSFORMT utility.
ca1tms14
The TMSBLDVR program is invoked by TMSXTEND to read the TMC and create a volume range table based on the ranges it finds, then adding or deleting any volume ranges or DSNBs as requested based on the control statements specified in the SYSIN DD. When executed in standalone mode, TMSBLDVR can be used to identify the volume ranges in an existing TMC, validate volume range or DSNB control statements, and determine the size requirement of the new TMC. The TMSBLDVR utility is a subprogram of TMSXTEND that can also be executed to create a new TMC, replacing functionality provided by the TMSFORMT utility.
TMSBLDVR can also be used to define a new, empty TMC. TMSBLDVR is superior to TMSFORMT for defining a new TMC because of its ability to format alphanumeric volume serial number ranges without the use of the TMSXITE and TMSXITU user exits. Also, when executed in standalone mode with the PARM=NEW parameter is the only time the TMCNEW DD statement is used.
For messages associated with this utility see, TMSBLDVR Messages.
Report Description
TMSBLDVR creates TMS REPORT-80 which displays the volume ranges found in the existing TMC. The report also lists the volume ranges that are built as a result of any add or remove range statements. Statistics are also produced for the number of total and free DSNBs. If you run TMSBLDVR in standalone mode without a PARM=NEW parameter, the report includes the size requirements for the new TMC based on a blocksize of either 340 or 8840. This feature helps ensure that the new TMC is correctly preallocated.
If the required size for the TMC exceeds 4,369 cylinders, allocate the TMC by adding DSNTYPE=LARGE to the DD statement in the allocation step.
The following messages are issued to the report 80 that comes out of TMSBLDVR:
UNIQUE TMC RNAME ACTIVATED
This message is displayed when UNIQUE_RNAME=YES is used to create a TMC and when extending an existing TMC. If you use the Exclude statement, you get an RC=08 error.
UNIQUE TMC RNAME DEACTIVATED
This message is displayed if UNIQUE_RNAME=NO is used when extending an existing TMC and unique RNAME was previously activated.
Job Control Statements
//STEP01 EXEC PGM=TMSBLDVR,REGION=0M [,PARM=NEW] //TMSRPT80 DD SYSOUT=* //TMCNEW DD DSN=new.tmc.name,DISP=OLD,DCB=(BUFNO=60,BLKSIZE=n*340) * NOTE //SYSUDUMP DD SYSOUT=* //* //SYSIN DD * ADDVOL 500000-502999 ADDVOL VT0000-VT2999 ROBTY=88,VENDOR='CA VTAPE' REMVOL TN0100-TN0599 /* //
This is an OPTIONAL DD statement, see PARM=NEW for details. The BLKSIZE may be equal to the LRECL or any multiple of the LRECL. However, when blocking the TMC the smallest valid block size is 1020. Also, when formatting a small blocked test TMC, ensure that it consists of at least 2 blocks. When creating a TMC.N add space allocation and change DISP=OLD to DISP=NEW to the TMCNEW DD.
Parameter Definitions
  • NEW
    When this parameter is specified, a new TMC is formatted without copying volume ranges or DSNB records from an input TMC. The new TMC must be preallocated and cataloged.
    CA 1
    does not have to be active or batch active to run with PARM=NEW.
    You must have at least one ADDVOL statement and one ADDDSNB statement when formatting a new TMC.
JCL Considerations
  • SYSIN
    This DD defines the control statement input data set. When run in standalone mode TMSBLDVR will validate that the function requested is proper for the requested range.
  • TMSRPT80
    This is the report output DD for TMS REPORT-80. This DD statement is required.
  • TMCNEW
    This DD statement is required if PARM=NEW is specified. A newly allocated, empty TMC should be specified.The TMC DCB attributes follow:
    DCB=(RECFM=FB,LRECL=340,BLKSIZE=n*340,DSORG=PSU,BUFNO=60)
Completion Codes
The following completion codes are issued by TMSBLDVR:
  • 0
    Program completed successfully.
  • 4
    Program completed with minor errors. Review TMSRPT80 report for details on errors.
  • 12
    Program failed due to an invalid control statement.Review TMSRPT80 report for details on control statement errors.
Control Statement Specifications
ADDDSNB nnnnnnnn
Requests that you add nnnnnnnn free DSNB records to the new TMC. A maximum of 99,999,999 total DSNBs can be defined.
ADDVOL
Lowvol-Highvol DEN=nn ROBTY=nn TRTCH=nn VENDOR=cccccccc DELETE specifies that the volume range lowvol-highvol are added to the new TMC. Optional parameters are provided to initialize the volume records with a density (DEN), robot type (ROBTY) recording technique (TRTCH), and vendor (VENDOR). For the DEN, ROBTY and TRTCH parameters, replace nn with hexadecimal values. For a list of these values, see TMC Volume Record Definition with Keywords in the
Programming
. The DELETE parameter simply indicates that the volumes are added in DELETE status in the new TMC. VENDOR is a one-through-eight character string that is used to identify the media manufacturer. In addition to a range, you can specify a single VOLSER on the ADDVOL statement. If you do not use DELETE in the control statement, the added volumes are in SCRATCH status.
If you use spaces in the VENDOR field, place single quotes around the value. When you code an alphanumeric volser range, use the same alpha portion both in the beginning volser and in the ending volser.
Example:
A00000-A99999 is valid but AA0000-AB9999 is invalid.
REMDSNB nnnnnnnn
Requests that you remove nnnnnnnn free DSNB records from the new TMC. A maximum of 99,999,999 total DSNBs can be defined.
REMDSNB is not valid with PARM=NEW and is mutually exclusive with the ADDDSNB control statement.
REMVOL lowvol-highvol
Specifies that all volumes in the range lowvol-highvol are removed from the TMC. All volumes in this range must be in DELETE status, otherwise the entire range is not removed.
You cannot remove all VOLSER entries from a TMC
.
REMVOL is not valid with PARM=NEW.When you code an alphanumeric volser range, use the same alpha portion both in the beginning volser and in the ending volser.
Example:
A00000-A99999 is valid but AA0000-AB9999 is invalid.
UNIQUE_RNAME=[
YES
|
NO
]
Specifies if UNIQUE_RNAME is used with this TMC. If you code this control statement, code it as the first control statement in the SYSIN DD. You can also use the
CSM
configuration user interface to set this option on. Add "Unique_RNAME=YES/NO" on TMSBLDVR job when you configure the creation of a new TMC using
CSM
.
The following messages are issued to report 80:
  • UNIQUE_TMC RNAME ACTIVATED
    This message displays when UNIQUE_RNAME=YES is used to create a TMC and when you are extending an existing TMC.
  • UNIQUE_RNAME= MUST BE FIRST CONTROL STATEMENT
    This message displays if UNIQUE_RNAME is not the first control statement coded. TMSBLDVR ends with the reason code 12.
TMS Report 80 - Report Field Definitions
TMS REPORT=80 JOB=MORTBLDV STEP=TMSBLDVR THURSDAY, APRIL 17, 2008.108 TIME=09:23:41 THURSDAY, APRIL 17, 2008.108 Y O U R C O M P A N Y N A M E ROxxxxx PAGE=00001 TMSBLDVR VOLUME DEFINITIONS TMSBLDVR IS RUNNING STANDALONE MODE TMC BEING READ: CAI.CA1.TMC CURRENT TMC VOLUME RANGES EXTERNAL VSN TMC REC NUMBER 120000-126999 0000004-0007003 D00001-D99999 0007004-0107002 HP0000-HP9999 0107003-0117002 H10000-H79999 0117003-0187002 KR0000-KR9999 0187003-0197002 KS0000-KS9999 0197003-0207002 K00001-K99999 0207003-0307001 O00001-O50000 0307002-0357001 P00001-P02500 0357002-0359501 TA0000-TA9999 0359502-0369501 TB0000-TB9999 0369502-0379501 TC0000-TC9999 0379502-0389501
  • External VOLSER Range
    This field shows the low and high VOLSER numbers for a range found in the TMC.
  • TMC Rec Number
    This field shows the low and high relative record number of the volume serial numbers for each range in the TMC.
In addition, TMS REPORT-80 also lists the TMC name being evaluated. The input control statements specified and the ranges that would be created for the new TMC. It also gives the number of DSNB's currently allocated, currently unused, and how many can be removed. Finally, it gives the space requirements of the TMC based on a unblocked TMC or a TMC allocated with a blocksize of 8840 (this is only reported if TMSBLDVR is run in standalone mode).