Purpose
ioefsutl format is
a batch utility that formats a VSAM linear data set to become a zFS
compatibility mode aggregate.
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 section 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 the Usage section 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.
Usage
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
8K 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 will be 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 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.