ioefsutl format

Purpose

Start of change 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. End of change

Format

ioefsutl format -aggregate name [-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 translated 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).

-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.

-overwrite

Required if you are reformatting an existing aggregate. Use this option with caution because it destroys 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). The default is o755 (owner read/write-execute, group read-execute, other read-execute).

-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 the 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 Start of change

or later

Usage notes for ioefsutl format

Start of change The ioefsutl format utility formats an existing VSAM linear data set as a zFS aggregate. All zFS aggregates must be formatted before use. End of change

The aggregate name is not case-sensitive. It is translated 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 is specified, the aggregate version default is determined by a call to the zFS PFS to obtain the value of the format_aggrversion variable from the IOEFSPRM file. If the zFS PFS is not active, then the format will fail.

The size of the aggregate is as many 8 K blocks as fits in the primary allocation of the VSAM linear data set or as specified in 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.

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 go to the next line, use a continuation character in column 72 (continuing in column 16 with the ending apostrophe on the second line). Remember that a JCL EXEC PARM is limited to 100 characters. See the topic on EXEC PARM in z/OS MVS JCL Reference.

ioefsutl format always formats with a unique auditfid.

Privilege required

The user must meet one of the following authorization requirements:

Have ALTER authority to the VSAM linear data set.
Be UID 0.
Have READ authority to the SUPERUSER.FILESYS.PFSCTL resource in the z/OS UNIXPRIV class.

UPDATE authority to the VSAM linear data set is sufficient for format, but zFS will not be able to set the zFS bit in the catalog unless the issuer has ALTER authority.

If you are changing the owner or group to something other than the issuer or you are changing the permissions to other than the default, you need UID 0 or READ authority to the SUPERUSER.FILESYS.PFSCTL resource in the z/OS UNIXPRIV class.

If you are using an IOEFSPRM file in your ZFS PROC, the issuer must have READ authority to the data set that contains the IOEFSPRM file. If you are using parmlib (IOEPRMxx), the issuer does not need special authorization.

Restrictions

The zFS aggregate cannot be mounted (or attached). The batch job must be issued from a V2R1 Start of change or later End of change system and the VSAM linear data set must exist. If neither -version4 nor -version5 are specified, the value of the format_aggrversion parameter on the server is used. In this case, if the value of the FORMAT_AGGRVERSION parameter 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) -
            LINEAR 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
//*

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