Dr. Donald J. Chesarek
21 Sep 1999
The VTOC Conversion Aid is a tool that will help installations manage the conversion of their VTOCs from the "old" format to the "new" format.
ICKDSF Release 16 with with APAR PN89166(September 1996) changes previously reserved bits in the VTOC's Format 4 DSCB to have new meaning. These new bits provide new VTOC function that assists full volume COPY/RESTORE programs to ensure that they copy all of the data on the volume ... even though the value in the VTOC Format 4 DSCB "total" number of cylinders field does not match the number of (primary+alternate) cylinders on that the device that contains the VTOC.
The VTOC Conversion Aid is Y2K compliant. © Copyright International Business Machines Corporation 1998.
This section gives a summary of changes to the VTOC Conversion Aid.
VTOC Conversion Aid - the tool
Appendix A. The VTOC Conversion Aid Panels
The VTOC Conversion Aid is a set of ISPF panels and associated programs that have been designed to simplify the two tasks:
The Conversion Aid is designed to work with large numbers of volumes.
A VTOC in the new format has information that is placed into the VTOC that should eliminate future software problems due to differences between the capacity of a volume as defined in the VTOC and the capacity as defined by the logical device that contains the volume.
The VTOC Conversion Aid will process all current DASD device capacities, IBM 3380 standard, IBM 3380 D,E,J,K and IBM 3390-1,2,3 and 9.
Prior to the introduction of the IBM 3330, large system DASD did not have an error recovery/management process that handled tracks that had large defects. These problems were handled by either of two mechanisms. (In many cases the HDA was ultimately replaced.)
The first mechanism corresponds to the "BAD SECTOR" management process used with todays PC DASD technology.
The IBM 3330, circa 1969, introduced the use of "alternate tracks" to address this problem. Alternate tracks gave the DASD subsystem the ability to use an alternate track in lieu of a defective track. Alternates could be used to improve manufacturing yields or to handle track damage that occurred after the DASD hardware was shipped. Switching between the defective primary and alternate is function of the DASD subsystem.
Some customers got very clever and developed software to put their data on "unused" alternate tracks. (Think of this as another version of the Y2K problem). DADSM was modified to put the capacity of the volume(primary+alternates) into the "total number of cylinders" field in the VTOC. DF/DSS subtracts the number of alternate cylinders(from the device) from the "total number of cylinders" value from the VTOC when it calculates the number of cylinders to copy/dump. If the "total number of cylinders" in the VTOC does not include the number of alternate cylinders on the device, DF/DSS will not copy/dump the last "number of alternate cylinders" on the volume.
An IBM 3330 device had 7 alternate cylinders, an IBM 3344 device had 2 alternate cylinders, an IBM 3350 device had 5 alternate cylinders. An IBM 3380 device has 1 alternate cylinder and an IBM 3390 Model 1, 2 or 3 device has 1 alternate cylinder. An IBM 3390-9 device has 3 alternate cylinders.
The introduction of the IBM 9392(RAMAC) brought yet another change to the industry. RAID technology has no need for alternate tracks. With RAID technology, support for alternate cylinders becomes an issue of backward software compatibility. The IBM 9392(RAMAC) contains 0 alternate cylinders.
A side effect of the changes to the number of alternate cylinders is the the fact that the total capacity of the volume as stated in a VTOC that was initialized by ICKDSF on an IBM 3390-3 is one cylinder larger that the total capacity of a VTOC initialized on an IBM 9292(RAMAC). The customer useable capacity is the same for both of these devices, 3339 cylinders. Again, this difference caused a number of problems with dump/restore programs. A series of software fixes were issued to address the problem of a mismatch between the capacity of the volume as defined by the VTOC and the capacity of the volume as defined by the device.
The REFORMAT(REFVTOC) command in ICKDSF gives customers the ability to bring the VTOC on any volume into agreement with the characteristics of the device that contains the volume.
The growing use of tools that enhance the ability to copy/move full volumes of data between different technologies, e.g IBM 3390, IBM 9392 (or devices which emulate either of these devices) has once again identified problems with VTOCs that do not match the hardware characteristics. These tools include Dual Copy, PPRC, XRC and most of the software/microcode tools that are designed to minimize the disruption of migrating significant numbers of volumes of data from one technology to a new technology, e.g from IBM 3390-3 to IBM 9393(RVA) or IBM 9392(RAMAC) to IBM 9393(RVA), or between hardware from different vendors.
In September of 1996, IBM introduced a permanent mechanism to address the problem of differences between the VTOC and the logical device by assigning a new use to previously reserved bits the Format 4 DSCB in the VTOC. These bits allow software to correctly manage the full volume copy/dump process from data contained in the VTOC. When these bits are used, the logical volume is decoupled from the characteristics of the device and full volume copy/dump programs will function correctly independently of the device.
A set of APARs for DF/DSS were release that allow DF/DSS to take advantage of the new function.
Two mechanisms are in place to build VTOCs with the new bit assignments. Both are in ICKDSF Release 16 with APAR PN89166. VTOCS built before September 1996 will not exploit the new bit assignments. VTOCS built after September 1996 but before the APAR is applied will not exploit the new bit assignments. You can use SMP/E to assist you in determining when the APAR was applied.
VTOCS processed by the following ICKDSF commands after the APAR is added to ICKDSF will use the new bit assignments. The ICKDSF commands are:
If the VTOC was built without the new bits then the rule is:
"when moving full volumes from one technology to a different technology, ALWAYS run ICKDSF REFORMAT!"
If you don't, there is no way to predict if/when you will encounter software that is sensitive to the fact that the VTOC does not match the hardware that contains the logical volume.
The VTOC Conversion Aid is a software tool that will characterize the state of an existing VTOC and VTOC Index. It will identify those VTOCs that do not use the new format bit assignments. In addition, it will characterize the capacity of the volume as defined in the VTOC and will identify the number of primary and alternate cylinders on the device that contains the VTOC.
This version will also compare the capacity of the volume as defined by the FMT4 DSCB record in the VTOC and the capacity of the volume as calculated from the VTOC index, an indexed VTOC is in use. I will also examine the state of the VTOC Indicators and will identify volumes that
The VTOC Conversion Aid builds three types of jobs:
The VTOC Conversion Aid is an ISPF panel based program. Jobs are built using the VTOC Conversion Aid panels in three steps:
The logic of the aid allows the user to easily delete devices from the list of devices that will be used in creating the VTOC Extent analysis jobs and the ICKDSF jobs.
The panel functions are driven by entering a starting MVS device number and the number of consecutive devices from that starting point. The user can input the starting address for a subsystem that may contain device that needs to be examined and the number of devices whose value includes all of the devices in that subsystem. The aid will do all of the analysis and job creation work. The user then submits jobs that the aid has created.
The maximum number of devices that can be specified in any job creation panel is 128.
Help text is available for each panel and field within a panel.
A user can complete the job creation activity for a single subsystem by using four panels and entering data into 10 fields. A user can complete the job creation process for 30 subsystems (30 * 128 = 3840 devices) by using 4 panels and entering values into 120 fields. If the same number of devices exist on each system, then data is entered into a total of 62 fields.
The Conversion Aid allocates all data sets that are used in the conversion process; it creates both sequential datasets and PDSs.
Dataset names have multiple qualifiers. The high level qualifier and third level qualifier are user defined. The second level qualifier will always be VTXVTOC.
A common naming convention is used for variable 4th level qualifiers in the names of sequential dataset that hold device data and in PDS member names.
On the panels used to create the jobs, two values are specified
These two values are combined to create names using the following logic. The first character of the name is "D". The next 4 characters are the starting MVS device number. If 3 characters were used in the panel, the aid will add a leading 0.
The next set of characters is variable and uses the following logic.
For example, if the starting MVS device number is 6379 and the number of devices is 8, the variable name would be D6379#8. If the starting MVS device number is 360 and the number of devices is 128, the variable name would be D0360128.
You will see the variable name as PDS member names in the PDSs that contain JOBS or certain types of data and, you will see them as qualifiers in the sequential datasets that are used by the IEHLIST jobs.
There are 3 types of jobs which are built by the aid that are important to this use of the Aid. Each of the jobs is described in a section that follows. The job types are
All of the jobs will work with 1 to 128 volumes.
Devices do not need to be on-line to the system that runs these jobs.
A setup job is a job that obtains device information from the DASD hardware. The setup job creates members in two different PDSs.
Each member will contain information about the hardware, including
Each member will contain information about the VTOC and VTOC index on the volume.
Each member will contain the following information about each device in the job that created that member
The ICKDSF REFORMAT(REFVTOC) jobs will cause ICKDSF to make the VTOC match the physical device.
No customer data will be changed on the volume as a result of running the ICKDSF jobs.
The ICKDSF jobs will not create a VTOC Index when one does not already exist on the volume.
When these jobs are run, the device MUST ONLY be on-line to the system that is running the job. VTOC Indexes will be re-built by this job.
To shorten the elapsed time for this process, the VTOC Conversion Aid builds multiple jobs within the single member it creates in the ICKDSF.JOBS PDS. Each job will contain a maximum of 16 REFVTOC commands. The logic that is used to create the job cards for each of the jobs will create jobs with different job names. By submitting a single member, multiple ICKDSF jobs can be executed in parallel.
APAR PN89166 must be applied to ICKDSF before these jobs are run. This APAR will place data into the new bits in the VTOC, thus converting the VTOC to the "new" format at the same time the VTOC contents are adjusted to match the device that contains the volume.
You should review DF/DSS service to ensure that the corresponding APARs have been applied to DF/DSS. As a starting point, review APARs II11078, OW31317 and OW32961.
In some environments, execution of multiple concurrent ICKDSF REFORMAT(REFVTOC) jobs may result in MIH messages. These messages should be ignored.
These are Phase 2 jobs. These jobs are only of interest if you suspect you may have lost data because the VTOC has an old format and there is a mismatch between the capacity as defined by the VTOC and the capacity as defined by the device.
The IEHLIST jobs have two steps. In step 1, an IEHLIST LISTVTOC function is executed. This step produces a formatted VTOC listing for multiple volumes. In step 2, a REXX EXEC is used to analyze the VTOC listing to locate any datasets that contain extents that are on last cylinders on the volume. Last cylinders are defined as the last "device number of alternate cylinders" in the primary cylinder address range. For example, on an IBM 3390-9 there are 10,017 primary cylinders, numbered 0 - 10,016; there are 3 alternate cylinders. Any dataset that has an extent in the range 10,013 - 10,016 will be included in the list. Devices defined to MVS as a 3390 Model 1, 2 or 3, will have any extents on the last primary cylinder included in the list. If datasets are found on this cylinder, they are identified and flagged in the job output AND are listed in a VEXT.DATA dataset.
A large VTOC will produce 20,000+ lines of formatted output. The VTOC.LIST dataset is allocated with a large primary and large secondary extents. The REXX code which does the analysis of this data can take several minutes of CPU time. If you use the TIME parameter on the JOB card, you should set it to 4 or 5 minutes. 4 minutes was sufficient time to analyze the VTOC data from 128 VTOCs on 3390-3 devices in one of the production complexes in IBM San Jose.
The ICKDSF REFORMAT(REFVTOC) command requires that the device can ONLY be online to a single system. This will require careful scheduling in many installations.
For operational ease most installations will work with full subsystems, i.e. vary all of the devices online/offline as a group.
If you want to selectively do the ICKDSF REFORMAT(REFVTOC) then you need to delete devices from the list of devices at the start of the phase 2 build process. All of the device information is available on a single line. By deleting that line, the device will be excluded from both the ICKDSF and IEHLIST jobs.
The elapsed time to execute a REFORMAT(REFVTOC) command depends on the number of datasets on the volume. The bulk of the time is due to the re-building of the VTOC index, which is part of this process.
Use the name DSN="userid.CVTOC20.PDS.XFRSEQ" as the target MVS data set; userid is your TSO userid or a common high level qualifier for a storage management "group". If more than one person will be building migration jobs, the qualifier should be selected to give each potential user access to the common files.
RECEIVE INDSN('userid.CVTOC20.PDS.XFRSEQ')
You will be prompted for the name of the PDS; reply
DSN('userid.CVTOC20.PDS')
The PDS data set does NOT need to be pre-allocated.
There is one LINKedit job that needs to be run before the aid can be used. The load modules MUST be placed into an APF Authorized library. The LINKedit job is contained in DSN=userid.CVTOC20.PDS(LKED). This job linkedits two modules into into an authorized load library. The load library module names are DRDCT02A and DSTAT01B.
The LINKedit job is customized as follows:
The aid supports several different types of job naming conventions and job card generation algorithms.
You will need to select a starting set of job card models based on your installation's requirements for job names. There are three different sets of job card models based on job name requirements; each set of job card models is contained in a member of userid.CVTOC20.PDS.
The generated job names contain variable characters so that generated jobs that will not be serialized due to identical job names. The model contained in JOBCARDM will generate job cards with 4 variable characters at the end of the name. The model contained in JOBCARDT will have 2 variable characters at the end of the name. The model contained in JOBCARD2 will use two variable characters in the job name. The first part of the job name is a constant which you specify when you set up member JOBCARDS.
There is comment text at the beginning of each model to help you understand the details of that model.
Edit member JOBCARDS. Copy into it the model that you have selected. Member JOBCARDS is the member that is used by the job card creation logic. Members JOBCARDM, JOBCARDT and JOBCARD2 are provided to get you started with minimum effort.
Follow the directions in the comment block that is at the start of the member. Change the job card models. Be careful to make sure that each of the REXX assignment statements has a double quote at the end of the statement. PF3 to exit after making the changes.
Edit member CVTOC20. There are two changes required to this member.
There are two techniques that can be used to invoke the aid.
The command is
EXEC 'userid.CVTOC20.PDS(CVTOC20)' EXEC
Sample panels are shown in Appendix A.
As discussed earlier, the job building panels will let you build jobs that will work with 1 to 128 devices. IEHLIST does not support more than 255 DD cards in a single step, so we would need to split subsystems with 256 devices into two sets of devices . If you enter a number of devices value greater that 128 you will receive an "out of range" error message.
The Phase 1 jobs will collect data for both online and offline devices.
The Phase 2 jobs REQUIRE that the devices be online to the system that is executing the job. The IEHLIST jobs can be run with the device online to multiple systems. The ICKDSF REFORMAT(REFVTOC) job requires the volume to be online ONLY to the system that is executing the job.
The panels are designed to work just like the standard ISPF panels.
Help text is available for all of the data entry fields on each panel. Help is invoked using PF1 (just like standard ISPF).
Enter your userid as the high level qualifier and then enter TEST as the Project Level Qualifier.
Select function type "A" and enter your choices into either the VOLSER or the MGMTCLAS/STORCLAS fields.
If your system defaults keep the datasets that are created using the defaults for some time then you can use the defaults.
Depressing the enter key will produce a stream of TSO allocation messages. PF3 back to the primary panel.
Now using ISPF 3.4 look at the VTOC Conversion Aid datasets. These datasets will all have VTXVTOC as the second level qualifier.
Enter "userid.VTXVTOC.TEST" in the Dsname Level field and hit enter.
You should see the following datasets listed
userid.VTXVTOC.TEST.DEVICE.LIST userid.VTXVTOC.TEST.DRDCT02A.DATA userid.VTXVTOC.TEST.DSTAT01B.DATA userid.VTXVTOC.TEST.ICKDSF.JOBS userid.VTXVTOC.TEST.IEHLIST.JOBS userid.VTXVTOC.TEST.PHASE1.JOBS userid.VTXVTOC.TEST.VTOC.DATA
Select the member.
It should have a functional JOB card.
If the job card is not correct, then you need to go back and edit the JOBCARDS member. After you have edited the JOBCARDS member, return to step 6 of the walkthru.
If the job card is correct, submit the job. It should complete with a return code of 0.
If the job terminated with an 047 ABEND, then you did not LINKedit the load modules into an APF authorized library.
The first three fields in each record contains MVS device number, model and volume label. The data to the right of the label consists of multiple fields of hex data. The first field contains 64 bytes of "Read Device Characteristic(RDC)" data from the device, the next field is a 5 byte field that contains the CCHHR of the start of the VTOC. The next field contains the first 28 bytes of the VTOC Format-4 DSCB. Depending on the values in the DS4VOCI(VTOC Indicators byte) of the Format-4 DSCB determine if there are additional fields in the record.
The detailed description of the RDC HEX data field in this record can be found in the 3990 reference manual. The VTOC data is the first part of the Format-4 DSCB. A description of the Format-4 DSCB can be found in the "DFSMSdfp Advanced Services" manual. The Version 1 Release 4 Manual describes the "new" bits.
Each member should look something like the following(this sample was done with a device count of 64 and only part of the output has been included here.)
--Device data--- ---VTOC data--- -INDEX-
MVS Model Volser Primary Alt F Format 4 F Cyls
DEVN Cylinders Cyl m Cylinders l
HEX DEC DEC g DEC
14B0 3390-3 EI14B0 0D0B 3339 0 N 3339 NI
14B1 3390-3 EI14B1 0D0B 3339 0 N 3339 . 3339
14B2 3390-3 PA14B2 0D0B 3339 0 O 3339 . 3339
14B3 3390-3 ADSM14 0D0B 3339 0 N 3339 . 3339
14B4 3390-3 BUILDQ 0D0B 3339 0 O 3339 . 3339
14B5 3390-3 JES902 0D0B 3339 0 N 3339 . 3339
14B6 3390-3 HSM926 0D0B 3339 0 O 3339 . 3339
14B7 3390-3 HSM953 0D0B 3339 0 O 3339 . 3339
14B8 3390-3 BIG938 0D0B 3339 0 O 3339 . 3339
14B9 3390-3 HSM954 0D0B 3339 0 O 3339 . 3339
14BA 3390-3 HSM927 0D0B 3339 0 O 3339 . 3339
14BB 3390-3 BIG901 0D0B 3339 0 O 3339 . 3339
14BC 3390-3 HSMBCD 0D0B 3339 0 O 3339 . 3339
14BD 3390-3 HSM937 0D0B 3339 0 O 3339 . 3339
14BE 3390-3 ??????
14BF 3390-3 ??????
14C0 3390-3 RESI2A 0D0B 3339 0 O 3339 NI
14C1 3390-3 RESI2B 0D0B 3339 0 N 3339 . 3339
14C2 3390-3 PA14C2 0D0B 3339 0 O 3339 . 3339
The column labeled Fm identifies the VTOC format, "N"= new, "O" = old.
Question marks(?) indicate that the data required to complete this field is not available from the device. In the example, the devices at addresses 14BE and 14BF are SPARE devices in an IBM 9392(RAMAC) subsystem.
The column labeled Flg is used to classify data from the VTOC Indicators(DS3VTOCI field) from the VTOC. A "." in this column means that the volume uses an Indexed VTOC and no other "unusual" conditions exist. Exception cases are
During the Phase 2 job build process, devices that have ???? as the model or, ?????? as the label, will automatically be excluded from both the ICKDSF and IEHLIST jobs.
The last few lines of SYSOUT from the Phase 1 job will contain counts of the number of devices and counts of the types of VTOCs encountered. The 64 devices with starting address 14B0 produced the following output.
Total number of device records = 128 Total number of Old format VTOCs= 76 Total number of New format VTOCs= 40 Total number of ? format VTOCs= 9 Total number of VTOC/INDEX MM = 1 Total number of disabled INDEXES= 0 Total number of non-INDEXED vols= 6 Total number of DIRF bit=1 vols= 0 Devices with I/O errors = 3
In the sample SYSOUT, 3 devices had I/O errors during the attempt to obtain device characteristic data. 6 additional devices had device characteristics available, but a Format-4 DSCB could not be read from the VTOC.
14D2 3390-3 BUILD5 00 DS4IVTOC=0, volume does not use an indexed VTOC
In a production setting, you would use the Phase 2 part of the process if you suspected that you had lost data due to a mismatch between the capacity of the volume and the capacity defined by the VTOC.
You will get some comment messages. Clear the screen and you will get a standard ISPF edit screen with the list of volumes from the DEVICE.LIST member. If you want to delete some selected volumes that you DO NOT want to go through the VTOC CONVERSION process(because you have other plans for them), this is the time to delete the control records. Delete the lines by placing a "d" in the control field at the left end of the line. If you don't have any exception cases, PF3 and the job creation process will complete. You will see some informational messages regarding job creation and dataset allocation activity.
PF3 back to the Conversion Aid primary panel.
C816171.VTXVTOC.TEST.Dnnnn#16.VEXT.DATA C816171.VTXVTOC.TEST.Dnnnn#16.VTOC.LIST
The Phase 2 IEHLIST job that does the VTOC Extent analysis will use these both of these datasets. The raw IEHLIST output will go into the VTOC.LIST dataset and exposed datasets will be listed in the VEXT.DATA dataset.
Records in the VEXT.DATA dataset will have the Volume label as the first field, the dataset name in the second field and the highest numbered extent cylinder in the third field.
Any dataset that is in this listing may be subject to software problems due to a mismatch between the VTOC and the hardware.
If all of the volumes are online, submit the job. IEHLIST requires that the volumes be online.
Processing HSM920 HSM920 V932861.B5798DQD.LOAD 3338 <-- Max cylinder extent value is(DSN Count = 477) 3338
Volume HSM920 contains 477 datasets. One dataset has an extent that includes cylinder 3338, the high cylinder range for an IBM 3390-3.
The VTOC Conversion Aid uses ISPF Profile variables to retain information across sessions. You can erase these variables from your profile pool by executing the following command from an TSO command line under ISPF
EXEC "highqual.CVTOC20.PDS(ISPFVARS)' EXEC
Finally, when you are finished using the aid you can delete the CVTOC20.PDS dataset.
VTOC Conversion Aid panels. A high level qualifier of C816171 and a project level qualifier were entered in the primary panel.
Figure 1. Panel PP#0P00A. The VTOC Conversion Aid - Primary panel.
+--------------------------------------------------------------------------------+ | | | PP#0P00A ---------------- VTOC Conversion Aid - Primary Panel -------- | | OPTION ===> | | | | Select one of the following options: | | | | | | 1 ALLOCATE - Allocate/Delete datasets | | 2 BUILD phase 1 - Build data gathering jobs | | | | Jobs built in phase 1 MUST be executed before continuing | | | | 3 BUILD phase 2 - Build conversion jobs | | | | | | | | VTOC Conversion Aid Dataset Name Control Information | | | | High level DSN qualifier ===> C816171 | | Project level qualifier ===> TEST | | | +--------------------------------------------------------------------------------+
Figure 2. Panel AL#0P00A. The VTOC Conversion Aid - File Allocation Panel
+--------------------------------------------------------------------------------+ | | | AL#0P00A ------------ VTOC Conversion Aid - File Allocation Panel ---- | | COMMAND ===> | | | | Function type ===> (A=Allocate or D=delete) | | | | | | To customize the location of VTOC Conversion Aid allocated | | datasets enter values into either VOLSER or MGMTCLAS/STORCLAS fields. | | Blank values in all of the fields will use the default allocation | | algorithms for your system. | | | | VOLSER ===> MGMTCLAS ===> | | STORCLAS ===> | | | | | | | | High DSN qual ===> C816171 | | Cluster qual ===> TEST | | | | Press ENTER to execute function (after entering required information) | | | | Press PF3(END) to exit function | +--------------------------------------------------------------------------------+
Figure 3. Panel B1#0P00A. The VTOC Conversion Aid - Build Phase 1 Jobs Panel
+--------------------------------------------------------------------------------+ | | | B1#0P00A -------------- VTOC Conversion Aid - Build Phase 1 Jobs ----- | | COMMAND ===> | | | | | | Target devices: | | | | Starting MVS Device number ===> | | Number of devices ===> | | | | | | | | | | | | | | High DSN qual ===> C816171 | | Project ===> TEST | | | | Press ENTER to invoke job builder (after entering required information) | | | | Press PF3(END) to exit job builder | +--------------------------------------------------------------------------------+
Figure 4. Panel B2#0P00A. The VTOC Conversion Aid - Build Phase 2 Jobs Panel
+--------------------------------------------------------------------------------+ | | | B2#0P00A -------------- VTOC Conversion Aid - Build Phase 2 Jobs ----- | | COMMAND ===> | | | | | | Target devices: | | | | Starting MVS Device number ===> | | Number of devices ===> | | | | | | | | | | | | | | High DSN qual ===> C816171 | | Project ===> TEST | | | | Press ENTER to invoke job builder (after entering required information) | | | | Press PF3(END) to exit job builder | | | +--------------------------------------------------------------------------------+