zfsadm attach

Purpose

zfsadm attach attaches an aggregate to zFS without mounting the file system. Beginning in z/OS V2R2, this aggregate can only contain one file system.

Note: zfsadm aggrinfo displays an attached compatibility mode aggregate as MULT because it is not mounted.

This command will be removed in a future release.

Format

zfsadm attach {-aggregate name   
              [-system sysname]}   
              [-aggrfull threshold,increment] 
              [{-R/O|-ro|-rw}][-nbs|-nonbs]
              [-aggrgrow|-noaggrgrow]
              [-level][-help][-trace file_name]

Options

-aggregate name

Specifies the name of the aggregate to be attached. The aggregate name is not case-sensitive. It is translated to uppercase. This aggregate does not need an entry in the IOEFSPRM file.

Compatibility mode aggregates do not need to be attached with the zfsadm attach command. They are automatically attached on MOUNT of the compatibility mode file system.

-aggrfull threshold,increment

Specifies the threshold and increment for reporting aggregate full error messages to the operator. Both numbers must be specified. The first number is the threshold percentage and the second number is the increment percentage. For example, if 90,5 were specified, the operator is notified when the aggregate is 90% full, then again at 95% full, and again at 100% full. The default is the global aggrfull entry of the IOEFSPRM file.

-aggrgrow

Specifies that the aggregate should be dynamically grown if it runs out of physical space. The aggregate (that is, the VSAM linear data set) must have a secondary allocation specified and there must be space available on the volume. The default is the aggrgrow option of the IOEFSPRM file.

-help

Prints the online help for this command. All other valid options that are specified with this option are ignored.

-level

Prints the level of the zfsadm command. This is useful when you are diagnosing a problem. Except for -help, all other valid options that are specified with -level are ignored.

-nbs

Specifies that new block security is used for file systems in this aggregate. New block security refers to the guarantee made when a system fails. If a file was being extended or new blocks were being allocated for the file, but the user data had not yet made it to the disk when the failure occurred, zFS shows the newly allocated blocks as all binary zeros and not whatever was on disk in those blocks at time of failure.

-nonbs

The NONBS option is no longer supported; if NONBS is specified, it is ignored. zFS always runs with NBS on.

-noaggrgrow

Specifies that the aggregate should not be dynamically grown if it runs out of physical space. The default is the aggrgrow option of the IOEFSPRM file.

-R/O | -ro

Specifies that the aggregate should be opened in read-only mode. The default is read/write unless -R/O or -ro is specified.

-rw

Specifies that the aggregate should be opened in read/write mode. The default is read/write unless -R/O or -ro is specified.

-system sysname

Specifies the name of the system that will be the zFS owner of the aggregate. The system name is not case-sensitive. It is translated to uppercase.

-trace file_name

Specifies the name of the file that will have the trace records written into it. The trace file can be a z/OS UNIX file, an existing MVS sequential data set, or a member of either an existing partitioned data set (PDS) or partitioned data set extended (PDSE). Use this option only at the direction of IBM Support.

For information about preallocation instructions for debugging, see Step 5 (Optional) Preallocate data sets for debugging in zFS installation and configuration steps.

Because MVS data set names must be fully qualified, z/OS UNIX has special rules for specifying MVS data set names in the shell environment. For more information, see Specifying MVS data set names in the shell environment in z/OS UNIX System Services Command Reference.

Usage notes

The zfsadm attach command attaches zFS aggregates on this system. Beginning in z/OS V2R2, zFS only attaches aggregates that contain exactly one file system.
If the attach fails because log recovery is unsuccessful, you can run the ioefsutl salvage batch utility with the -verifyonly option on the aggregate to determine if there is an inconsistency. If so, use ioefsutl salvage to recover the aggregate and reissue the zfsadm attach command.
The zfsadm lsaggr command can be used to display a current list of all aggregates that are attached on this sysplex with the zFS owning system indicated, or this system when -system is used.
If the DASD volume containing the zFS aggregate that being attached is read-only, you might receive message IOEZ00336I. This indicates that the zFS aggregate indicator cannot be set in the catalog (actually, in the VVDS on the volume). The zFS aggregate is successfully attached. DFSMSdss backup (DUMP) will not automatically quiesce and unquiesce the zFS aggregate because it cannot determine that the VSAM linear data set is a zFS aggregate. If the zFS aggregate can be attached with the DASD volume in read/write, the zFS aggregate indicator will be set.
You can determine if the zFS aggregate indicator is set by using IDCAMS LISTCAT ALL against the zFS aggregate and looking for the zFS indicator in the output.
Compatibility mode aggregates do not need to be separately attached because they are attached during MOUNT processing. However, if you want to issue a zfsadm command against a compatibility mode aggregate without mounting the aggregate, you can use the zfsadm attach command. You might attach an aggregate to grow it or display information about it.

Privilege required

The issuer must be logged in as a root user (UID=0) or have READ authority to the SUPERUSER.FILESYS.PFSCTL resource in the z/OS® UNIXPRIV class.

Examples

The following command attaches an aggregate.

zfsadm attach -aggregate OMVS.PRV.AGGR001.LDS0001

Figure 1 shows the same example as a job that invokes zfsadm attach.
Figure 1. Job to attach an aggregate
```
//USERIDA  JOB ,'Zfsadm Attach',
//         CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//AGGRINFO EXEC   PGM=IOEZADM,REGION=0M,
// PARM=('attach -aggregate OMVS.PRV.AGGR001.LDS0001')
//SYSPRINT DD     SYSOUT=H
//STDOUT   DD     SYSOUT=H
//STDERR   DD     SYSOUT=H
//SYSUDUMP DD     SYSOUT=H
//CEEDUMP  DD     SYSOUT=H
//*
```
If you want to specify the R/O option, you must specify a leading slash. Otherwise, Language Environment® treats the characters before the slash as Language Environment parameters. That is, you must use PARM=('/attach OMVS.PRV.AGGR001.LDS0001 -R/O').

Related information

Commands:

zfsadm fsinfo
zfsadm lsaggr

Files:

IOEFSPRM