SWAPBUILDIX and EXPANDVTOC statement

SWAPBUILDIX statement

This statement initiates an FDRPAS utility task to build or rebuild the indexed VTOC (VTOCIX) on an online volume. It must be the first statement in the input; only one SWAPBUILDIX statement is allowed per execution. SWAPBUILDIX must be followed by one or more MOUNT statements to identify the online volumes on which to build the VTOCIX and may optionally be followed by one or more EXCLUDE statements to exclude certain systems that do not have the volumes online; a maximum of 250 MOUNT and EXCLUDE statements may be present.

The SWAPBUILDIX and EXPANDVTOC Statement Syntax is as follows:

The MOUNT and optional EXCLUDE statements that follow the SWAPBUILDIX statement are the same as those used with the SWAP and SWAPDUMP statements (SWAP & SWAPDUMP Task MOUNT Statement and SWAP Task EXCLUDE Statement). On the MOUNT statement, the VOL= operand identifies the volume where the VTOCIX is to be built, and the SWAPUNIT= operand identifies an offline monitor DASD volume that FDRPAS uses to coordinate the BUILDIX between the systems. If you have multiple MOUNT statements in one SWAPBUILDIX step, they can use the same SWAPUNIT= value since they are executed serially. However, if you submit multiple SWAPBUILDIX jobs for concurrent execution, each one must use a unique offline SWAPUNIT= device.

Like FDRPAS SWAP and SWAPDUMP operations, the SWAPBUILDIX task executes on only one system in a multi-system environment. On the other systems, you must execute FDRPAS MONITOR tasks, similar to the MONITOR tasks used with SWAP and SWAPDUMP. The MONITOR tasks must monitor the same offline monitor DASD device(s) specified by SWAPUNIT= in the SWAPBUILDIX task. The considerations for running MONITOR tasks and the systems where they must be executed are the same as for SWAP and SWAPDUMP and are discussed elsewhere in this manual, with one exception. A MONITOR task that monitors SWAPBUILDIX or EXPANDVTOC operations, and uses only one SWAPUNIT, defaults to DURATION=1 after the first operation. That is, once the MONITOR task has completed one SWAPBUILDIX or EXPANDVTOC, the MONITOR task terminates automatically after 1 minute of inactivity. This is appropriate if all of the SWAPBUILDIX or EXPANDVTOC operations are in one job step, or in several steps or jobs that run in quick succession. If there are longer intervals between the SWAPBUILDIX or EXPANDVTOC operations and you want the MONITOR task to stay up between them, specify a sufficient value for DURATION=, for example, DURATION=1000; then when you are done, terminate the MONITOR with the console command “P jobname”.

The online volumes must contain a SYS1.VTOCIX.volser data set before the SWAPBUILDIX begins; FDRPAS does not allocate the VTOCIX if it does not exist. The operation fails if the VTOCIX data set is not present. The IBM Device Support Facilities (ICKDSF) User’s Guide and Reference (GC35-0033) contains information on allocating and sizing the VTOCIX.

If the VTOCIX is present but inactive on the volume, FDRPAS invokes ICKDSF to build the VTOCIX, then the MONITOR tasks on the other systems update their respective systems with the VTOCIX information. If the VTOCIX is already active, ICKDSF is not invoked, but FDRPAS ensures that the VTOCIX information is correct on every system.

SWAPBUILDIX uses code and techniques normally used for a SWAPDUMP operation; you may notice that many FDRPAS messages say “DUMP” when a SWAPBUILDIX is executed. SWAPBUILDIX modifies the offline monitor DASD device, so you must be sure that offline DASD volume does not contain any data that must be preserved. If you want to bring the offline monitor DASD volume online, you need to re-initialize it with ICKDSF first.

A RACROUTE call is issued to verify that the user has READ authority to resource FDRPAS.SWAPBUILDIX in the FACILITY class, if that resource is protected. If FDRPAS.SWAPBUILDIX is not protected, the operation continues.

If you have security checking enabled (see ALLCALL), SWAPBUILDIX checks that the user has ALTER authority to the source volume under the DASDVOL security class. If the user does not have DASDVOL authority, the operation fails. If the volume is not protected by DASDVOL, FDRPAS checks that the user has ALTER authority in the DATASET class to every data set on the volume; if any data set is not authorized, the operation fails.

If you have restricted the use of ICKDSF, then the FDRPAS SWAPBUILDIX job must be authorized to use it.

EXPANDVTOC statement

The EXPANDVTOC statement is similar in some ways to the SWAPBUILDIX statement, but it has the additional function of expanding the VTOC on the indicated volumes. EXPANDVTOC works only if the program library contains a licensed copy of both FDRPAS and FDRMOVE.

The MOUNT statement used with EXPANDVTOC is described in SWAP & SWAPDUMP Task MOUNT Statement, except that it supports an additional operand, VTOCSIZE=nnnnn (new VTOC size in tracks). If the current VTOC is equal to or larger than VTOCSIZE=, the volume is not changed. For example,

MOUNT VOL=vol,SWAPUNIT=uuuu,VTOCSIZE=nnnn

The SWAPUNIT is used only for communication between the LPARs; only control information is written to it. You should not run more than one EXPANDVTOC function concurrently. To expand the VTOC, all data sets that follow the VTOC in the space required must be moved. To do so, FDRPAS invokes enhanced functions of FDRCPK (FAST COMPAKTION). EXPANDVTOC moves the VTOCIX and VVDS if necessary, even if they are active, and any other data sets that occupy the required space. However, if any of those other data sets are active (enqueued) they cannot be moved and the EXPANDVTOC fails (messages identify such data sets so that you can take action to make them idle).

The VTOCIX is expanded to be 1/16th of the size of the new VTOC, unless it is already larger than that. This is based on IBM manual Device Support Facilities (ICKDSF) User’s Guide and Reference (GC35-0033) that documents the max VTOC and INDEX sizes for each size device. On a 3390-9, the maximum VTOC size is 2,944 tracks and the Index size is 150 tracks. The Index comes out as five percent of the VTOC. We default to 6.25 percent. A SWAPBUILDIX is done automatically after building the new VTOC and VTOCIX.

You should pick an appropriate VTOC size based on the expected usage of the volume. Maximum size VTOCs are not recommended unless you expect many 1-track data sets.

EXPANDVTOC holds an enqueue/reserve on the VTOC and VVDS during the expansion. Unless these reserves are converted to global enqueues, this means that all access to the volume from other LPARs is inhibited during the expansion. The elapsed time can be from ten seconds to several minutes. Therefore, you should run the EXPANDVTOC from the LPAR with the most activity to the volume, since that LPAR is still able to access the volume. You may want to run EXPANDVTOC during a quiet time.

If you have third-party products that access the VTOC or VVDS without an enqueue, the third-party products may experience errors if they run during the VTOC expansion.

Like SWAPBUILDIX, the EXPANDVTOC task executes on only one system in a multi-system environment. On the other systems, you must execute FDRPAS MONITOR tasks, similar to the MONITOR tasks used with SWAP and SWAPDUMP. The MONITOR tasks must monitor the same offline monitor DASD volume(s) specified by SWAPUNIT= in the EXPANDVTOC task. These MONITOR tasks also update the new VTOC, VTOCIX, and VVDS information on each LPAR. You can use the same SWAPUNIT= on each MOUNT in the EXPANDVTOC step. It is essential the MONITOR tasks run from the same program library as the FDRPAS job, since code updates are required. The considerations for running MONITOR tasks and the systems where they must be executed are the same as for SWAPBUILDIX, (see SWAPBUILDIX Statement).

You should not run multiple concurrent EXPANDVTOC jobs; but if you do, you must use a different SWAPUNIT= for each job.

EXPANDVTOC can be executed either before or after an FDRPAS swap of a volume but not during a swap. If there is not sufficient free space on the volume to expand the VTOC before the swap, you can run it after the swap to a larger volume. VTOCSIZE= cannot be specified in a swap operation.

SWAPBUILDIX and EXPANDVTOC statement operands

TYPE=FULL

Must be specified on the SWAPBUILDIX and EXPANDVTOC statement.

LOGMESS=

LM=

NO

No SYSLOG/console messages are written.

YES

Messages are written to SYSLOG (and usually to an operator console) documenting that the SWAPBUILDIX is occurring, and has completed.

Default: NO

STGADMIN

If specified, FDRPAS checks to see if the user ID under which it is running is authorized to security class FACILITY profile name STGADMIN.ADR.STGADMIN.DUMP. If so, all security checks are bypassed for all FDRPAS operations, including system allocation and catalog functions. Using STGADMIN allows FDRPAS to move all DASD volumes without needing any additional security.

Default: FDRPAS does normal security checks including system allocation and catalog security. The user id under which FDRPAS runs is authorized to move any data set, but has no authority to those data sets outside of FDRPAS. The security system overhead may be significant if many data sets are involved.

We recommend the use of the STGADMIN.ADR.STGADMIN.DUMP profile for all FDRPAS operations when ALLCALL is enabled.