MODIFY ZFS PROCESS

Purpose

The MODIFY ZFS PROCESS command enables you to query internal zFS counters and values. They are displayed on the system log. It also allows you to initiate or gather debugging information. To use this command, the zFS PFS must be running.

Prior to z/OS V2R2, zFS always ran as a colony address space. The syntax of that command was modify zfs,<cmd>.

Beginning in z/OS V2R2, zFS can be run as a colony address space or in the OMVS address space. In both cases, the syntax of the modify command can be modify omvs,pfs=zfs,<cmd>. This form of the modify command should also be used if you have any zFS modify commands that are issued through an automated process or system automation.

When zFS modify commands in this documentation are mentioned, they are shown in the historical modify zfs,<cmd> form, as they always have been, rather than always mentioning both forms.

Format

You can use any of the following formats for this command.

modify procname,query,{level|settings|threads[,{allwait|oldest}]|status| 
[{kn|vm|lfs|lock|storage|file|stkm|ctkc|svi|iobydasd|dataset|all}]

modifyprocname,reset,{kn|vm|lfs|lock|storage|file|stkm|ctkc|svi|iobydasd | 
   dataset | all}

modify procname,trace,{reset | print}

modify procname,abort

modify procname,dump

modify procname,hangbreak

modify procname,unquiesce,aggregate_name

modify procname,nsvalidate[,print]

modify procname,fsinfo[,{aggrname | all} [,{full | basic | owner | reset} 
[,{select=criteria | exceptions}] [,sort=sort_name]]]

Parameters

procname

The name of the zFS PFS PROC. The default procname is ZFS.

If zFS is running in the OMVS address space (the address space that is used by z/OS UNIX), procname must direct the command to zFS through OMVS. For example:

modify omvs,pfs=zfs,command

command

The action that is performed on the zFS PFS. This parameter can have one of the following values:

abort

Causes zFS to dump and then perform an internal restart. The internal trace table is also printed to the data set specified in the IOEFSPRM file trace_dsn entry.

dump

Causes the zFS PFS to dump and to print the internal trace table to the data set specified in the IOEFSPRM file trace_dsn entry.

fsinfo

Displays detailed information about a zFS file system, which is also known as a zFS aggregate.

aggrname

Specifies the name of the aggregate that the detailed zFS information is for. The aggregate name is not case-sensitive and is converted to uppercase. To specify multiple aggregates with similar names, use an asterisk (*) at the beginning, at the end, or both at the beginning and the end of aggrname as a wildcard. If aggrname is specified with wildcards, the default display is basic. Otherwise, the default display is owner. For more information, see Usage notes for displaying file system information and Examples of displaying file system information.

all

Displays information for all aggregates in the sysplex. It is the default when aggrname is not specified. The default information display will be as if basic were specified.

basic

Displays a line of basic file system information for each specified file system. This option is the default in the following situations:

The all option is specified but full, owner, and reset are not specified.
If aggrname and all are not specified.
aggrname is specified with wildcards.

For more information about what is displayed when the basic option is used, see Table 2.

exceptions

Displays information about any specified aggregate that is quiesced, disabled, had grow failures, is low on space, failed to convert a directory to version5, or is damaged. Any specified aggregate is also displayed if it has had XCF communication failures or an error because it ran out of space or when doing I/O. This option cannot be specified with reset, select, and aggrname with no wildcard.

full

Displays information that is maintained by the system owning each specified file system. It also displays information that is locally maintained by each system in the sysplex that has each specified file system locally mounted.

Tip: If a large number of file systems are to be displayed, a large amount of output will be displayed. For that case, consider using either the basic output option or the zfsadm fsinfo command so that the output can be redirected to a file.

owner

Displays only information that is maintained by the system owning each file system specified. This option is the default when aggrname with no wildcards is specified. For more information about what is displayed when the owner option is used, see Table 2 and Table 3.

reset

Resets zFS statistics that relate to each specified file system. reset cannot be specified with basic, full, owner, exceptions, select, or sort.

select=criteria

Displays each specified file system that matches the criteria.

This option cannot be specified with exceptions, reset, and aggrname with no wildcard.

To use this option, specify a selection criteria from Table 1. Multiple criteria are separated by spaces.

sort=sort_option

Sorts the displayed information using the value of sort_option. The default is to sort by Name. This option cannot be specified with reset. For a list of the sorting options, see Table 4.

hangbreak

Causes a zFS internal restart; this produces the same result as issuing a modify zfs,abort command.

nsvalidate

Initiates the zFS namespace validation on the system where the command is entered. The modify nsvalidate command should only be used in a shared file system environment; typically, it is only used as a part of a recovery procedure when a problem with zFS is suspected. If the command finds an inconsistency, it might cause zFS to abort and internally restart the zFS address space on one or more systems to correct the zFS namespace inconsistency. The modify nsvalidate command consists of the following option:

print: The optional print parameter displays additional name space information that is obtained after validation.

query

Displays zFS counters or values.

level

Displays the zFS level for the zFS physical file system kernel. When running in a shared file system environment, level also displays the zFS sysplex level and the zFS XCF communication interface level (1, 2, 3 or 4). The zFS sysplex level is controlled by the IOEFSPRM sysplex configuration option. When the sysplex level is filesys, the default mount PARM (NORWSHARE or RWSHARE) is also displayed. (As of z/OS® V1R13, zFS always runs with sysplex=filesys.) For an example and more information, see Determining service levels.

settings

Displays the zFS configuration settings, which are based on the IOEFSPRM file and defaults.

status

Displays zFS internal restart information.

threads[,{allwait | oldest }]

Displays the threads that are monitored by the zFS hang detector. To display all zFS threads, use the modify zfs,query,threads,allwait command. The time of day values is shown in Greenwich mean time (GMT). To display the oldest thread of each system, use the modify zfs,query,threads,oldest command.

<report>

One of the following report options. These parameters all produce reports; for details about these reports, see Monitoring zFS performance.

all: Displays all the zFS counters.
ctkc: Displays the client calls to other systems. Output is only displayed when the zFS ctkc component on this system has sent a message to another system.
dataset: Displays zFS statistics about file systems.
file: Displays the requests per zFS file system and aggregate.
iobydasd: Displays the DASD that is attached by volume.
kn: Displays the calls that were made to zFS from z/OS UNIX.
lfs: Displays the file system statistics, including the performance of the zFS metadata caches, the vnode cache, and the aggregate I/O statistics.
lock: Displays the lock contention values.
log: Displays the log statistics.
stkm: Displays the current server token manager (STKM) statistics.
storage: Displays the zFS storage values.
svi: Displays the calls from other systems to this server through the server vnode interface (SVI) component. Output is only displayed when the zFS svi component on this system has received a message from another system.
vm: Displays the user file cache, including cache hit ratios, I/O rates, and storage usage.

reset

Resets zFS counters and consists of the following options:

all: Resets all the zFS counters to zero.
ctkc: Resets the client call statistics.
dataset: Reset the zFS statistics about file systems.
file: Resets the requests for zFS file system and aggregate.
iobydasd: Resets the count of the DASD that is attached by volume.
kn: Resets the calls that were made to zFS from z/OS UNIX.
lfs: Resets the file system statistics, including the performance of the zFS metadata caches, the vnode cache, and the aggregate I/O statistics.
lock: Resets the lock contention values.
log: Resets the log statistics.
stkm: Resets the server token manager (STKM) statistics.
storage: Resets the zFS storage counters.
svi: Resets the received calls from other systems statistics.
vm: Resets the user file cache, including cache hit ratios, I/O rates, and storage usage.

No other options are allowed after reset.

trace

Resets or prints the internal zFS trace table.

print: Formats and sends the current trace table to the data set specified in the IOEFSPRM file trace_dsn entry. This data set must be preallocated as a PDSE with RECFM VB and LRECL 133. It must be large enough to hold the formatted trace table. See Performance and debugging for more information about the trace output data set.
reset: Resets the internal (wrap around) trace table to empty.

unquiesce

Causes a quiesced aggregate to become unquiesced. Only locally attached aggregates can be unquiesced using the modify unquiesce command. You must issue this command on the system that is the zFS owner of the aggregate. Use the z/OS UNIX zfsadm lsaggr command to determine which system is the zFS owner of the aggregate.

Usage notes for MODIFY ZFS PROCESS

The modify zfs command is used to display zFS counters or values and to initiate or gather debugging information. You cannot issue modify zfs commands during a zFS internal restart.

Usage notes for displaying file system information

Use the MODIFY FSINFO command to display detailed information about zFS file systems, which are also known as zFS aggregates. Normally, file systems must be attached before this command can be used to display their information. However, when specifying a specific aggregate name (with no wildcards), the file system does not need to be attached. You can use several methods to specify aggregates, based on their names, as follows:

aggrname with an exact aggregate name. The aggregate can either be mounted or not mounted.
aggrname using a wildcard (*) at the beginning of the name value to select aggregates with a common suffix.
aggrname using a wildcard (*) at the end of the name value to select aggregates with a common prefix.
aggrname using a wildcard (*) at the beginning and the end of the name value to select aggregates with both a common prefix and a common suffix.
all can be specified or defaulted to mean all file systems that are currently mounted in the sysplex.

The MODIFY FSINFO command options are positional. Each option must be separated by a comma. Only the options at the end of the line can be omitted. If options are omitted, the default values are used instead. Examples of supported syntax are as follows:

F ZFS,FSINFO
F ZFS,FSINFO,ALL
F ZFS,FSINFO,ALL,BASIC,SELECT=RW Q
F ZFS,FSINFO,ALL,BASIC,SELECT=RW Q,SORT=REQUESTS

The owner option displays all available information for each specified file system from the zFS-owning system. The information is obtained via XCF communication with the owning system if the owning system is not the local system. It also displays the statistics that are shown in Table 3.

The full option displays statistics for each specified file system from the zFS owning system and from each system in the sysplex that has it locally mounted. This will be obtained via XCF communication with each system in the sysplex. The statistics are described in Table 5.

Aggregates can also be selected using the exceptions option. This option can be useful for identifying file systems which have encountered unexpected conditions, and might need attention. Unexpected conditions include I/O errors, XCF communication failures or being low on space. An aggregate can also be damaged, quiesced, or disabled.

Aggregates can also be selected by use of the select option. To use this option, specify a criteria from the list in Table 1. You can specify more than one criteria by using a space to separate them.

The displayed information has the file system status as part of the output. The status field contains abbreviated values. For quick reference, these values are defined in a Legend string at the end of the output. The full definitions of these abbreviations are listed in Table 2.

All times are in milliseconds. To display large numbers, use the following suffixes:

Letter: Unit of number
b: The number should be multiplied by 1,000,000,000.
G: The number should be multiplied by 1,073,741,824.
t: The number should be multiplied by 1000.
T: The number should be multiplied by 1,099,511,627,776.
tr: The number should be multiplied by 1,000,000,000,000.
m: The number should be multiplied by 1,000,000.
K: The number should be multiplied by 1024.
M: The number should be multiplied by 1,048,576.

Privilege required

This command is a z/OS system command.

Examples for MODIFY ZFS PROCESS

The following example queries all the zFS counters:

modify zfs,query,all

The following example resets the zFS storage counters:

modify zfs,reset,storage

The following example formats and sends the trace table to the data set specified in the IOEFSPRM file trace_dsn entry:

The following example causes the zFS PFS to execute an internal restart:

modify zfs,abort

The following example queries all the zFS counters when zFS is running inside the OMVS address space:

modify omvs,pfs=zfs,query,all

Examples of displaying file system information

To display basic file system information for zFS aggregate PLEX.DCEIMGNK.FSINFO:
```
modify zfs,fsinfo,PLEX.DCEIMGNK.FSINFO,basic
```
To display file system owner status by using a wildcard:
```
modify zfs,fsinfo,PLEX.DCEIMGNK.*,owner
```
To display full file system status for all zFS aggregates that are quiesced, damaged, or disabled:
```
modify zfs,fsinfo,all,full,select=Q DA DI
```
To display basic file system status for all zFS aggregates that are quiesced, damaged, or disabled and also to sort aggregate names by response time:
```
modify zfs,fsinfo,all,basic,select=Q DA DI,sort=response
```

Related information

Files:

IOEFSPRM
zfsadm fsinfo

For details about stopping zFS, see the topic on Recycling z/OS UNIX System Services in z/OS MVS System Commands.