Creating a compatibility mode aggregate

Creating a compatibility mode aggregate is typically a two-step process.

Remember:

zFS file system names must be uppercase. The TSO/E MOUNT command will automatically fold the file system name to uppercase. End of change

First, use IDCAMS to create a VSAM linear data set.
Note: Carefully consider defining the aggregate as extended format, extended addressability, and with a secondary allocation size. If you do not use these attributes in the beginning, to add them, you will need to define and format a new zFS aggregate, migrate the data from the original file system into the new one, unmount the original, and then mount the new one. You might want to extend beyond the 4 G aggregate size because version 1.5 aggregates can be much larger than version 1.4 aggregates, or because secondary extents are required to dynamically grow the aggregate, and dynamic grow (aggrgrow) is the default. For more information, see Dynamically growing a compatibility mode aggregate.
Then format the VSAM linear data set as a compatibility mode aggregate and create a file system in the aggregate using ioeagfmt (see ioeagfmt - Batch utility that formats a VSAM linear data set to become a zFS compatibility mode aggregate). Before you can issue ioeagfmt, you must have UPDATE authority to the VSAM linear data set. If you specified -owner, -group, or -perms to override the default values, you must also be UID 0 or have READ authority to the SUPERUSER.FILESYS.PFSCTL resource in the z/OS UNIX UNIXPRIV class.

Beginning in z/OS V2R3, you do not have to explicitly format the VSAM linear data set if it is created with the zfsadm define command, or if it is created with the ZFS keyword on the IDCAMS DEFINE CLUSTER command. It will be automatically formatted the first time it is mounted. For more information about aggregates being formatted during mount processing, see zfsmount - Mount a file system into the z/OS UNIX hierarchy.

Beginning in z/OS V2R1, ioeagfmt fails if the zFS PFS is not active on the system. In addition, if the zFS started task does not have the TRUSTED attribute or the OPERATIONS attribute, the DFS user ID must have at least ALTER authority to all VSAM linear data sets that contain zFS aggregates.

You can also create a compatibility mode aggregate by using the ISHELL, or the automount facility, or the zfsadm define and zfsadm format commands.

For more information about ISHELL, see ISHELL in z/OS UNIX System Services Command Reference.
For more information about automount, see automount: Configure the automount facility in z/OS UNIX System Services Command Reference.
For more information about the zfsadm define command, see zfsadmdefine - Defines VSAM linear data sets.
For more information about the zfsadm format command, see zfsadmformat - Formats a VSAM linear data set.

The VSAM linear data set, the aggregate, and the file system all have the same name and that name is equal to the VSAM linear data set cluster name. The zFS file system is then mounted into the z/OS® UNIX hierarchy.

The Control Interval (CI) size of a VSAM linear data set that is formatted as a zFS aggregate must be 4 K, which is the default for IDCAMS. As such, it is not specified in the following figure, which shows an example of a job that creates a compatibility mode file system.

//USERIDA  JOB ,'Compatibility Mode',
//         CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//DEFINE   EXEC   PGM=IDCAMS
//SYSPRINT DD     SYSOUT=H
//SYSUDUMP DD     SYSOUT=H
//AMSDUMP  DD     SYSOUT=H
//DASD0    DD     DISP=OLD,UNIT=3390,VOL=SER=PRV000
//SYSIN    DD     *
     DEFINE CLUSTER (NAME(OMVS.PRV.COMPAT.AGGR001) -
            VOLUMES(PRV000) -
            ZFS CYL(25 0) SHAREOPTIONS(3))
/*
//CREATE   EXEC   PGM=IOEAGFMT,REGION=0M,
// PARM=('-aggregate OMVS.PRV.COMPAT.AGGR001 -compat')
//SYSPRINT DD     SYSOUT=H
//STDOUT   DD     SYSOUT=H
//STDERR   DD     SYSOUT=H
//SYSUDUMP DD     SYSOUT=H
//CEEDUMP  DD     SYSOUT=H
//*

The -compat parameter in the CREATE step tells ioeagfmt to create a compatibility mode file system. The -compat parameter is the default, but ignored, and zFS always formats a compatibility mode file system. The result of this job is a VSAM linear data set that is formatted as a zFS aggregate and contains one zFS file system. The zFS file system has the same name as the zFS aggregate (and the VSAM linear data set). The size of the zFS file system (that is, its available free space) is based on the size of the aggregate.

Figure 1. Example job to create a compatibility mode file system using IOEFSUTL

//USERIDA JOB ,'Compatibility Mode',
// CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//DEFINE EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=H
//SYSIN DD *
     DEFINE CLUSTER (NAME(OMVS.PRV.COMPAT.AGGR001) -
            VOLUMES(PRV000) -
            ZFS CYL(25 10) SHAREOPTIONS(3))
/*
//CREATE EXEC PGM=IOEFSUTL,REGION=0M,
// PARM=('format -aggregate OMVS.PRV.COMPAT.AGGR001')
//SYSPRINT DD SYSOUT=H
//*

The ioefsutl format utility can also be used to format a compatibility mode file system. It has options similar to ioeagfmt and the same authority requirements. The -compat option is not needed or allowed. The ioefsutl format utility only formats compatibility mode aggregates. You are encouraged to use the ioefsutl format utility rather than the ioeagfmt utility.

The default for the size of the aggregate is the number of 8 KB blocks that fits in the primary allocation. You can specify a -size option giving the number of 8 KB blocks for the aggregate.

If you specify a number that is less than (or equal to) the number of blocks that fits into the primary allocation, the primary allocation size is used.
If you specify a number that is larger than the number of 8 KB blocks that fits into the primary allocation, the VSAM linear data set is extended to the size specified if the total size will fit in the primary allocation and a single extension.

A secondary extension cannot be used; instead, see Growing a compatibility mode aggregate. The single extension must be no larger than a single volume. This occurs during its initial formatting. Sufficient space must be available on the volume. Multiple volumes can be specified on the DEFINE of the VSAM linear data set. The multiple volumes are used during extension of the data set later. If you want to create a multi-volume data set initially that is larger than two volumes, see Creating a multi-volume compatibility mode aggregate. DFSMS decides when to allocate on these volumes during extension. Any VSAM linear data set greater than 4 GB can be specified by using the extended format and extended addressability capability in the data class of the data set. See z/OS DFSMS Using Data Sets for information about VSAM data sets greater than 4 GB in size.

Restriction: zFS does not support the use of a striped VSAM linear data set as a zFS aggregate. If you attempt to mount a compatibility mode file system that was previously formatted and is a striped VSAM linear data set, it is mounted as read-only.

There are several other options to use when you create a compatibility mode file system that set the owner, group, and the permissions of the root directory.

The -owner option specifies the owner of the root directory.
The -group option specifies the group of the root directory.
The -perms option specifies the permissions on the root directory.

Now, you can mount the zFS file system into the z/OS UNIX hierarchy with the TSO/E MOUNT command. For example, the following command mounts the compatibility mode file system that was created.

MOUNT FILESYSTEM('OMVS.PRV.COMPAT.AGGR001') TYPE(ZFS) MODE(RDWR) MOUNTPOINT('/usr/mountpt1')

Alternatively, as the following example shows, you can use the z/OS UNIX mount shell command to mount the compatibility mode file system that was created.

/usr/sbin/mount -t ZFS -f OMVS.PRV.COMPAT.AGGR001 /usr/mountpt1

These examples assume that the directory /usr/mountpt1 exists and is available to become a mount point. For more information about mount points, see z/OS UNIX System Services Planning.