Purpose
ioeagfmt is
a batch utility that formats a VSAM linear data set to become an HFS
compatibility mode aggregate. The aggregate can be either a version
1.4 or version 1.5 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 _ (underscore)
- 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
The ioeagfmt utility
is used to format an existing VSAM linear data set as a zFS aggregate.
All zFS aggregates must be formatted before use.
Beginning
in z/OS V2R1, ioeagfmt fails
if the zFS PFS is not active on the system.
The aggregate version
will be as specified if the -version4 or -version5 parameter
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.
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.
Examples
Figure 1 shows
an example of a job that creates a compatibility mode aggregate and
file system.
Figure 1. Sample job to create a compatibility mode aggregate and 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) -
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
//*
Note: In the PARM=('-aggregate OMVS.PRV.COMPAT.AGGR001') statement,
the -aggregate option must be in lowercase.