ioefsutl format

Purpose

ioefsutl format is a batch utility that formats a VSAM linear data set to become a version 4 or version 5 zFS compatibility mode aggregate.

Format

ioefsutl format -aggregate name
                [-encrypt|-noencrypt][-compress|-nocompress] 
                [-size blocks][-logsize blocks] 
                [-owner uid|name][-group gid|name]     
                [-perms number][-grow blocks]
                [-overwrite][{-version4|-version5}]
                [-level][-help]

Options

-aggregate name
Specifies the name of the data set to format. This is also the aggregate name. The aggregate name is always converted to uppercase and cannot be longer than 44 characters. The following characters can be included in the name of an aggregate:
  • All uppercase and lowercase alphabetic characters (a to z, A to Z)
  • All numerals (0 to 9)
  • The . (period)
  • The - (dash)
  • The _ (underscore)
  • The @ (at sign)
  • The # (number sign)
  • The $ (dollar)
-compress
Specifies that the aggregate is compressed. For information about how the default compression option is determined, see Usage notes for ioefsutl format.
-encrypt
Specifies that the aggregate is encrypted. For information about how the default encryption option is determined, see Usage notes for ioefsutl format.
-group gid|name
Specifies the group owner for the root directory of the file system. It can be specified as a z/OS® group name or as a GID. The default is the GID of the issuer of ioefsutl format. If only -owner name is specified, the group is that owner's default group. If only -owner uid is specified, the group is the issuer's group.
-grow blocks
Specifies the number of 8-KB blocks that zFS uses as the increment for extension when the -size option specifies a size greater than the primary allocation.
-help
Prints the online help for this command. All other valid options that are specified with this option are ignored.
-logsize blocks
Specifies the size in 8-KB blocks of the log. The valid range is from 13 to 16384 blocks (128 megabytes). The default is 1% of the aggregate size. This default logsize will never be smaller than 14 blocks and it will never be larger than 4096 blocks (32 megabytes). This size is normally sufficient. However, a small aggregate that is grown to be very large will still have a small log. You might want to specify a larger log if you expect the aggregate to grow very large.
-level
Prints the level of the ioefsutl command. This information is useful when you are diagnosing a problem. Except for -help, all other valid options that are specified with -level are ignored.
-nocompress
Specifies that the aggregate will not be compressed. For information about how the default compression option is determined, see Usage notes for ioefsutl format.
-noencrypt
Specifies that the aggregate will not be encrypted. For information about how the default encryption option is determined, see Usage notes for ioefsutl format.
-overwrite
Required if you are reformatting an existing aggregate. Use this option with caution because it deletes any existing data. This option is not usually specified.
-owner uid | name
Specifies the owner for the root directory of the file system. It can be specified as a z/OS user ID or as a UID. The default is the UID of the issuer of ioefsutl format.
-perms number
Specifies the permissions for the root directory of the file system. The number can be specified as octal (for example, o755), as hexadecimal (for example, x1ED), or as decimal (for example, 493). For information about how the permissions for the file system root directory are determined, see Usage notes for ioefsutl format.
-size blocks
Specifies the number of 8-KB blocks that should be formatted to form the zFS aggregate. The default is the number of blocks that will fit in the primary allocation of the VSAM linear data set. If a number less than the default is specified, it is rounded up to the default. If a number greater than the default is specified, a single extend of the VSAM linear data set is attempted after the primary allocation is formatted unless the -grow option is specified. In that case, multiple extensions of the amount that is specified in the -grow option will be attempted until the -size is satisfied. The size can be rounded up to a control area (CA) boundary by DFSMS. It is not necessary to specify a secondary allocation size on the DEFINE of the VSAM linear data set for this extension to occur. Space must be available on the volume.
-version4
Specifies that the aggregate is to be formatted as a version 1.4 aggregate. See Usage notes for ioefsutl format for information about how the default aggregate version is determined.
-version5
Specifies that the aggregate is to be formatted as a version 1.5 aggregate. See Usage notes for ioefsutl format for information about how the default aggregate version is determined. IBM® recommends that you do not use -version5 until all your systems are at z/OS V2R1 or later.

Usage notes for ioefsutl format

  1. The ioefsutl format utility formats an existing VSAM linear data set as a zFS aggregate. All zFS aggregates must be formatted before use.
  2. The aggregate name is not case-sensitive. It is converted to uppercase. If -version4 or -version5 is specified, you can run ioefsutl format even if the zFS PFS is not active on the system. If neither option is specified, the aggregate version default is determined by a call to the zFS PFS to obtain the value of the format_aggrversion option from the IOEFSPRM file. If the zFS PFS is not active, then the format will fail.
  3. The encryption status of the compatibility mode aggregate that was created can be specified by using the -encrypt or the -noencrypt option. If neither option is specified, then the default aggregate encryption status is obtained from the zFS PFS format_encryption setting. See Processing options for IOEFSPRM and IOEPRMxx for a description of the format_encryption option. If the zFS PFS is not active while the format_encryption setting is obtained and if the aggregate is not a version 4 aggregate and already has a key label defined, zFS will format the aggregate with encryption. Otherwise, zFS will format the aggregate without encryption.
  4. The compression status of the compatibility mode aggregate that was created can be specified by using the -compress or -nocompress option. If you do not use either option, then the setting of the zFS PFS format_compression is used. See Processing options for IOEFSPRM and IOEPRMxx for a description of the format_compression option. If the zFS PFS is not active when the format_compression setting is obtained, zFS will format the aggregate without compression.
  5. The permissions on the file system root directory can be specified by using the -perms option. If the -perms option is not used, then the setting of the zFS PFS format_perms IOEFSPRM option is used. See Processing options for IOEFSPRM and IOEPRMxx for a description of the format_perms option. When the zFS PFS is not active when obtaining the format_perms setting, the root directory permissions will be o755.
  6. The size of the aggregate is either the number of 8-K blocks that fits in the primary allocation of the VSAM linear data set or the number that was specified by the -size option. The -size option can cause one additional extension to occur during formatting. To extend it further, use the zfsadm grow command. If -overwrite is specified, all existing primary and secondary allocations are formatted and the size includes all of that space. If -overwrite is specified, the backup change activity flag is set. If the VSAM linear data set has a SHAREOPTIONS value of other than 3, ioefsutl format changes it to SHAREOPTIONS 3 during format.
  7. For a batch job, the ioefsutl format options are specified in the EXEC PARM as a single subparameter (a single character string enclosed in apostrophes with no commas separating the options). You cannot put the ending apostrophe in column 72. If it needs to go to the next line, use a continuation character in column 72 (continuing in column 16 with the ending apostrophe on the second line). A JCL EXEC PARM is limited to 100 characters. For more information about the PARM parameter, see z/OS MVS JCL Reference.
  8. ioefsutl format always formats with a unique auditfid.

Privilege required

Before you can issue ioefsutl format, you must have UPDATE authority to the VSAM linear data set.

If you specified -owner, -group, or -perms with values that differ from the defaults, you must also be UID 0 or have READ authority to the SUPERUSER.FILESYS.PFSCTL resource in the z/OS UNIX UNIXPRIV class. The defaults for -owner and -group are determined from the credentials of the issuer. The default for -perms is the value of the IOEFSPRM FORMAT_PERMS option.

Restrictions

The zFS aggregate cannot be mounted (or attached). The batch job must be issued from a V2R1 or later system and the VSAM linear data set must exist. If neither -version4 nor -version5 is specified, the value of the format_aggrversion option on the server is used. In this case, if the value of the format_aggrversion option cannot be determined, the format will fail.

Examples

Figure 1 shows an example of a job that creates and formats a version 1.4 aggregate.
Figure 1. Sample job to create and format a version 1.4 aggregate 
//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=IOEFSUTL,REGION=0M,
// PARM=('format -aggregate OMVS.PRV.COMPAT.AGGR001 -version4')
//SYSPRINT DD SYSOUT=H
//STDOUT DD SYSOUT=H
//STDERR DD SYSOUT=H
//SYSUDUMP DD SYSOUT=H
//CEEDUMP DD SYSOUT=H
//*

In the PARM=('format -aggregate OMVS.PRV.COMPAT.AGGR001 -version4') statement, the format, and options -aggregate and -version4 must be in lowercase.