ioeagfmt
Purpose
ioeagfmt is a batch utility that formats
a VSAM linear data set to become a version 4 or version 5 zFS compatibility
mode aggregate.
Format
ioeagfmt -aggregate name [-initialempty blocks] [-size blocks] [-logsize blocks]
[-overwrite] [-compat] [-owner {uid|name}][-group {gid|name}] [-perms {number}]
[-grow blocks] [{-newauditfid|-nonewauditfid}][{-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 @ (at sign)
- The # (number sign)
- The $ (dollar).
- -compat
- Indicates that a compatibility mode aggregate should be created. This means that in addition to formatting the VSAM linear data set as a zFS aggregate, a zFS file system is created with the same name as the aggregate and its free space is set to the size of the available blocks on the aggregate. Beginning with z/OS® V2R1, only HFS compatibility mode aggregates can be created. This option is being allowed for compatibility with earlier versions and is not needed.
- -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 ioeagfmt. 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 will use 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.
- -initialempty blocks
- This option is being allowed for compatibility with earlier versions and is ignored. One 8-KB block at the beginning of the aggregate is reserved for IBM® use.
- -level
- Prints the level of the ioeagfmt command. This is useful when you are diagnosing a problem. Except for -help, all other valid options that are specified with -level 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.
- -newauditfid
- Specifies that the aggregate should be formatted with the zFS auditfid and stored in the aggregate. Beginning with z/OS V2R1, -newauditfid is the default.
- -nonewauditfid
- Specifies that the aggregate should not be formatted with a zFS auditfid stored in it. Before z/OS V2R1, this was the default.
- -overwrite
- Required if you are reformatting an existing aggregate. Use this option with caution; it destroys any existing data. This option is not usually specified.
- -owner uid | userid
- 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 ioeagfmt.
- -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 should be a version 1.4 aggregate. See the Usage section for the default value that is used.
- -version5
- Specifies that the aggregate should be a version 1.5 aggregate. See the Usage section for the default value that is used.
Usage notes for ioegfmt
Beginning in z/OS V2R1, ioeagfmt fails if the zFS PFS is not active on the system.
The ioeagfmt utility formats an existing VSAM linear data set as a zFS aggregate. All zFS aggregates must be formatted before use.
The aggregate version will be as specified if the -version4 or -version5 option is used. If neither is used, then the default aggregate version will be obtained from the zFS PFS format_aggrversion setting. See IOEFSPRM for a description of the format_aggrversion variable.
The size of the aggregate is as many 8-KB 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 the VSAM linear data set has a SHAREOPTIONS value of other than 3, ioeagfmt changes it to SHAREOPTIONS 3 during format. -overwrite will also cause the backup change activity flag to be set.
For a batch job, the ioeagfmt 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). Remember that a JCL EXEC PARM is limited to 100 characters. See the topic on the EXEC PARM in z/OS MVS JCL Reference.
Privilege required
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.
- 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.
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.
Examples
//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=IOEAGFMT,REGION=0M,
// PARM=(’-aggregate OMVS.PRV.COMPAT.AGGR001’)
//SYSPRINT DD SYSOUT=H
//STDOUT DD SYSOUT=H
//STDERR DD SYSOUT=H
//SYSUDUMP DD SYSOUT=H
//CEEDUMP DD SYSOUT=H
//*