IOEFSPRM

Purpose

The IOEFSPRM file lists the configuration options for the zFS PFS and the batch utilities ioefsutl and ioeagslv. There is no mandatory information in this file; therefore, it is not required. The options all have defaults. However, if you need to specify any options (for tuning purposes, for example), you must have an IOEFSPRM file.

//IOEZPRM DD DSN=SYS4.PVT.PARMLIB(IOEFSPRM),DISP=SHR

//IOEZPRM  DD  DSN=SYS4.PVT.&SYSNAME..PARMLIB(IOEFSPRM),DISP=SHR

Your IOEFSPRM file might reside in SYS4.PVT.SY1.PARMLIB(IOEFSPRM) on system SY1; in SYS4.PVT.SY2.PARMLIB(IOEFSPRM) on system SY2; and others.

If you want to share a single IOEFSPRM file, you can use system symbols in data set names in the IOEFSPRM file. For example, msg_output_dsn=USERA.&SYSNAME..ZFS.MSGOUT results in USERA.SY1.ZFS.MSGOUT on system SY1. Each system has a single (possibly shared) IOEFSPRM file.

Any line beginning with # or * is considered a comment. The text in the IOEFSPRM file is not case-sensitive. Any option or value can be uppercase or lowercase. Blank lines are allowed. Do not have any sequence numbers in the IOEFSPRM file. If you specify an invalid text value, the default value is assigned. If you specify an invalid numeric value, and it is smaller than the minimum allowed value, the minimum value is assigned. If you specify an invalid numeric value, and it is larger than the maximum allowed value, the maximum value is assigned.

Using PARMLIB (IOEPRMxx)

The preferred alternative to a IOEZPRM DDNAME is specifying the IOEFSPRM file as a parmlib member. In this case, the member has the name IOEPRMxx, where xx is specified in the parmlib member list.

When the IOEFSPRM is specified in a DD statement, there can only be one IOEFSPRM file for each member of a sysplex. Using PARMLIB, zFS configuration options can be specified in a list of configuration parmlib files. This allows an installation to specify configuration options that are common among all members of the sysplex (for example, adm_threads) in a shared IOEPRMxx member and configuration options that are system-specific (for example, trace_dsn) in a separate, system-specific IOEPRMxx member. If a configuration option is specified more than once, the first one found is taken.

FILESYSTYPE TYPE(ZFS) ENTRYPOINT(IOEFSCM)
ASNAME(ZFS,'SUB=MSTR')
PARM('PRM=(01,02,03)')

The parmlib concatenation can also be specified in the ioeagslv and ioefsutl batch utility parameters. Specify the -PRM keyword in the PARM string on the EXEC statement to use IOEPRMxx parameter file members. For more information, see ioeagslv and ioefsutl.

FILESYSTYPE TYPE(ZFS) ENTRYPOINT(IOEFSCM)
ASNAME(ZFS,'SUB=MSTR')
PARM('PRM=(01,&SYSCLONE.)')

See Figure 2 for an example of using PRM.

If &SYSCLONE.=AB, parmlib member IOEPRMAB is searched after parmlib member IOEPRM01. IOEPRM01 can contain common configuration options and IOEPRMAB can contain configuration options that are specific to system AB. If a parmlib member is not found, the search for the configuration option will continue with the next parmlib member.

                                                                    col 72
                                                                       |
                                                                       ▾
FILESYSTYPE TYPE(ZFS) ENTRYPOINT(IOEFSCM) ASNAME(ZFS,'SUB=MSTR')
               PARM('PRM=(00,01,02,03,04,05,06,07,08,09,10,11,12,13,14,
15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31)')
^
|
col 1

If no PRM suffix list is specified (and no IOEZPRM DD is specified in their respective JCL), then parmlib member IOEPRM00 is read. Parmlib support is only used when no IOEZPRM DD is present in the JCL.

IOEFSPRM and IOEPRMxx

Descriptions of the valid configuration variables and their respective allowed values follow. If no IOEFSPRM file is found, the default values for each configuration value are used.

Processing options for IOEFSPRM and IOEPRMxx

The following processing options are used for the zFS PFS.

adm_threads

Specifies the number of threads that are defined to handle pfsctl or mount requests. The expected value is a number in the range 1 - 256. For example:

adm_threads=5

The default value is 10.

aggrfull

Specifies the threshold and increment for reporting aggregate utilization messages to the operator. The expected value is two numbers separated by a comma in the range 1 - 99 within parentheses. For example:

aggrfull(90,5)

The aggrfull parameter is independent of fsfull. However, aggrfull reports are based on free 8 K blocks; while fsfull reports are based on free 1 K blocks. The aggrfull value tends to give a more accurate view of free space and is the recommended choice.

If aggrfull is specified for version 1.5 aggregates, fsfull is ignored.

The default value is OFF for version 1.4 aggregates. For version 1.5 aggregates, the fsfull threshold and increment values are used as if they were specified on aggrfull.

aggrgrow

Specifies whether aggregates can be dynamically extended when they become full. By default, a zFS read/write mounted file system that is mounted on a system running z/OS® V1R13 or later attempts to dynamically extend when it runs out of space. The aggregate (that is, the VSAM linear data set) must have a secondary allocation that is specified to be dynamically extended and there must be space on the volumes. This global value can be overridden on the MOUNT command for compatibility mode aggregates.

The expected value is ON or OFF. For example:

aggrgrow=on

The default value is ON.

change_aggrversion_on_mount

Specifies whether a version 1.4 aggregate should be changed to a version 1.5 aggregate on a primary read/write mount. No directories are converted to extended (v5) directories. The CONVERTTOV5 or NOCONVERTTOV5 MOUNT PARM overrides this option.

The expected value is ON or OFF. For example:

change_aggrversion_on_mount=off

The default value is ON.

client_reply_storage

Specifies the amount of storage that is used to handle sysplex server replies. The expected value is a number in the range 2 M - 128 M. K or M can qualify the number. For example:

client_reply_storage=8M

The default value is 10 M.

convert_auditfid

Specifies whether the zFS auditfid of an aggregate is automatically converted from the old form auditfid (binary zeros) to the new form auditfid on a read/write mount (attach). If the auditfid is already the new form, it is not changed. An auditfid of the new form will cause zFS to generate new auditids for files and directories in the file system.

The expected value is ON or OFF. For example:

convert_auditfid=on

The default value is ON.

converttov5

Specifies whether a zFS read/write file system is assigned the converttov5 attribute. If it is assigned the converttov5 attribute and the aggregate is a version 1.5 aggregate, zFS will automatically convert directories from v4 to extended (v5) as they are accessed. If the converttov5 attribute is assigned at primary mount time, a version 1.4 aggregate will be changed to a version 1.5 aggregate. The CONVERTTOV5 or NOCONVERTTOV5 MOUNT PARM overrides this option.

If automatic directory conversion for a directory fails, it is not attempted again until the file system is unmounted and mounted again.

The expected value is ON or OFF. For example:

converttov5=off

The default value is OFF.

edc_buffer_pool

Specifies the real storage that will be reserved for encryption and compression I/O. The expected value is a number in the range 1 M - 1 G. For example:

edc_buffer_pool=64M

The default value is 32 M for the zFS PFS, 10 M for the ioeagslv or ioefsutl batch utilities.

file_threads

Specifies the number of threads that handle sysplex server requests. The expected value is a number in the range 1 - 256. For example:

file_threads=50

The default value is 32.

format_aggrversion

Specifies the default version of an aggregate when formatting it. Each method for formatting a zFS aggregate obtains this value from the zFS PFS if the version is not specified.

You can specify 4 to format a version 1.4 aggregate or 5 to format a version 1.5 aggregate. Because you can no longer format a version 1.4 aggregate, a version 1.5 aggregate is formatted instead if 4 is specified.

An example of format_aggression is as follows:

format_aggrversion=5

The default value is 5.

format_compression

Specifies whether a newly created zFS aggregate will be formatted with compression. This is the default compression value of an aggregate when the -compress option is not used. Each method for formatting a zFS aggregate obtains this value from the zFS PFS if no compression value is specified.

The expected value is ON or OFF. For example:

format_compression=on

The default value is OFF.

format_encryption

Specifies whether a newly created zFS aggregate will be formatted with encryption. This is the default encryption value of an aggregate when the -encrypt option is not used. Each method for formatting a zFS aggregate obtains this value from the zFS PFS if no encryption value is specified.

The expected value is ON or OFF. For example:

format_encryption=on

The default value is OFF.

format_perms

Specifies the default permissions that are used for the root directory of the file system during a format when the -perms option is not used. Each method for formatting a zFS aggregate obtains this value from the zFS PFS if -perms is not specified.

The expected values are in the range 0 to o7777. The number can be specified as octal (for example, o755), as hexadecimal (for example, x1ED), or as decimal (for example, 493). For example:

format_perms=o644

The default value is o775.

fsfull

Specifies the threshold and increment for reporting file system utilization messages to the operator. The fsfull parameter is independent of aggrfull. While aggrfull reports are based on free 8 K blocks, fsfull reports are based on free 1 K blocks. The aggrfull parameter tends to give a more accurate view of free space and is the recommended choice.

fsfull is ignored for version 1.5 aggregates when aggrfull is specified.

The expected values are two numbers in the range 1 - 99 within parentheses and separated by a comma. For example:

fsfull(85,5)

The default value is OFF.

group

Specifies the XCF group that zFS uses to communicate between sysplex members. The Expected value characters must be acceptable to XCF. Generally, the characters A-Z, 0-9 and the national characters ($, # and @) are acceptable. The value that is specified must match on all systems in the sysplex that participate in a shared file system environment. Normally, there is no reason to specify this option.

The expected value is 1 to 8 characters. For example:

group=IOEZFS1

The default value is IOEZFS.

HA

Specifies whether high availability is enabled by default for mounts of sysplex-aware file systems.

The expected value is ON or OFF. For example:

HA = ON

The default value is OFF.

honor_syslist

Specifies whether to use the z/OS UNIX automove option that is specified during mount to control zFS ownership movement. The default is ON. For more information about zFS ownership movement, see Dynamic movement of the zFS owner.

The honor_syslist option is no longer supported. If it is specified, it is accepted but not used.

The expected value is ON or OFF. For example:

honor_syslist=on

The default value is ON.

log_cache_size

Specifies the size of the cache that is used to contain buffers for log file pages. You can also specify a fixed option, which indicates that the pages are permanently fixed for performance. The fixed option reserves real storage for usage by zFS only.

The expected value is a number in the range of 2 M - 1024 M. A K or M can be appended to the value to mean kilobytes or megabytes, respectively. For example:

log_cache_size=32M,fixed

The default value is 16 M.

long_cmd_threads

Specifies the number of foreground and background threads that are defined to handle long-running administrative commands. A foreground thread handles the overall operation while the background threads are used by the foreground thread to allow for parallelism in the processing of individual anodes.

For the expected value, the first value must be in the range 1-3 and the second value in the range 1-64. For example:

long_cmd_threads=3,30

The default value is 1,24.

meta_cache_size

Specifies the size of the cache that is used to contain metadata. You can also specify a fixed option, which indicates that the pages are permanently fixed for performance. The fixed option reserves real storage for usage by zFS only

If metaback_cache_size is specified, the size of the entire metadata cache will be a combination of the two values. It is not required, but it is recommended to keep your IOEFSPRM configuration file clean of outdated specifications for simplicity. Therefore, IBM recommends not to use the metaback_cache_size option. Rather, the size of the entire metadata cache should be assigned to the meta_cache_size option.

zFS provides a check to see if the metadata cache size is less than the calculated default metadata cache size. See ZFS_VERIFY_CACHESIZE in IBM Health Checker for z/OS User's Guide.

The expected value is a number in the range 1 M - 64 G. A K or M or G can be appended to the value to mean kilobytes, megabytes, or gigabytes, respectively. For example:

meta_cache_size=64M,fixed

For the default value, if metaback_cache_size is specified, then meta_cache_size is 64 M. If metaback_cache_size is not specified, zFS calculates 10% of real storage that the system has available during zFS initialization.

• If this amount is less than 64 M, then meta_cache_size is assigned 64 M.
• If this amount is between 64 M and 2 G+100 M, then meta_cache_size is assigned 10% of real storage size.
• If the amount is greater than 2 G+100 M, then meta_cache_size is assigned 2 G+100 M

metaback_cache_size

Specifies the size of the backing portion of the metadata cache. The backing cache is no longer in a data space. Rather, it is combined with meta_cache_size into one cache with a size of the sum of the two values.

Tip: To avoid confusion, do not keep outdated specifications in your IOEFSPRM configuration file. Use only the meta_cache_size option to specify the entire size of the metadata cache.

zFS provides a check to see if the sum of the metadata cache size and metadata backing cache size is less than the sum of the default metadata cache size and metadata backing cache size. See ZFS_VERIFY_CACHESIZE in IBM Health Checker for z/OS User's Guide.

zFS provides a check to indicate whether this configuration option is specified. See ZFS_CACHE_REMOVALS in IBM Health Checker for z/OS User's Guide.

The expected value is a number in the range 1 M - 2048 M. A K or M can be appended to the value to mean kilobytes or megabytes, respectively. For example:

metaback_cache_size=64M

There is no default value for the met aback cache if meta_cache_size is specified. Otherwise, see the default calculation description in meta_cache_size.

modify_cmd_threads

Specifies the number of threads that are defined to handle zFS modify commands. The expected value is a number in the range 1 - 256. For example:

modify_cmd_threads=1

The default value is 3.

quiesce_message_delay

Specifies the minimum number of seconds to delay issuing the IOEZ00830E message after it is determined that there is at least one quiesced aggregate and it needs to be displayed. The expected value is a number number in the range 30 - 21474836. For example:

quiesce_message_delay=300

The default value is 30.

quiesceinfo_message_delay

Specifies the minimum number of seconds to delay issuing the IOEZ00581E message after it is determined that there is at least one task waiting to access a quiesced aggregate and it needs to be displayed. The expected value is a number in the range 30 - 21474836. For example:

quiesceinfo_message_delay=300

The default value is 30.

recovery_max_storage

Indicates the maximum amount of zFS address space storage to use for concurrent log recovery during multiple concurrent aggregate mounts (attaches). This allows multiple concurrent mounts to occur when sufficient storage is available for multiple concurrent log recovery processing.

The expected value is a number in the range 128 M - 512 M. For example:

recovery_max_storage=128M

The default value is 256 M.

romount_recovery

Specifies whether zFS will automatically avoid a read-only mount failure because of the need to run log recovery for this aggregate. This can occur when the aggregate has been mounted read/write, and then a failure occurs before it was unmounted. If the next mount is for read-only, log recovery must run for the mount to be successful. When this situation occurs and romount_recovery=on, zFS temporarily mounts the aggregate read/write to run log recovery, and then zFS unmounts and mounts the aggregate read-only.

The expected value is ON or OFF. For example:

romount_recovery=off

The default value is ON.

-smf_recording

Specifies that data is to be collected and recorded by System Management Facilities (SMF). The expected value is ON, OFF, or on,intvl, where intvl specifies the number of minutes between the periodic recording of statistics. The number must be in the range 1 - 60. For example:

smf_recording=ON,60 

The default value is OFF.

sync_interval

Specifies the number of seconds between syncs. The expected value is a number in the range 11 - 21474836. For example:

sync_interval=45

The default value is 30.

sysplex

Starting with z/OS V1R13, zFS always runs sysplex-aware by file system, regardless of the sysplex specification. If you specify sysplex=on, zFS changes the default of sysplex_filesys_sharemode to rwshare. Otherwise, the default for sysplex_filesys_sharemode is norwshare. If you specify sysplex=off, the result is the same as specifying sysplex=filesys. For information about whether to make a read/write file system sysplex-aware, see Using zFS read/write sysplex-aware file systems.

The expected value is Off, filesys, or On, if BPXPRMxx specifies SYSPLEX(YES). For example,

sysplex=filesys

Ignored, if BPXPRMxx does not specify SYSPLEX(YES).

The default value is filesys.

Tip: Specify sysplex=filesys.

sysplex_filesys_sharemode

Specifies the default for the mount PARM for a zFS read/write file system that is mounted in a shared file system environment. For information about whether to make a read/write file system sysplex-aware, see Using zFS read/write sysplex-aware file systems.

The expected value is rwshare or norwshare. For example:

sysplex_filesys_sharemode=rwshare

The default value is norwshare (unless sysplex=on was specified, then the default is rwshare).

token_cache_size

Specifies the maximum number of tokens in the server token manager cache to use for cache consistency between zFS members. The number of tokens that are initially allocated for the server token manager cache is 20480.

The expected value is a number in the range 20480 - 20 million. For example:

token_cache_size=30720

For the default value, double the number of vnodes (see vnode_cache_size) when running in a shared file system environment. If you are not running in a shared file system environment, then there is no default value. This option is meaningful only when zFS is running sysplex-aware.

user_cache_size

Specifies the size, in bytes, of the cache that is used to contain file data. You can also specify a fixed option, which indicates that the pages are permanently fixed for performance. The fixed and edcfixed options can fix the user file cache in real memory.

• The fixed option avoids page fix and page unfix for disk I/Os that do not use compression.
• The edcfixed option avoids page fix and page unfix for disk I/Os that use compression. It also avoids data movement for compression I/Os. If the edcfixed option is used, zFS will wait during the initialization process for zEDC to be available. While it is waiting, zFS will display message IOEZ01001I. When zEDC is ready, zFS will continue the initialization process.

zFS provides a check to see if the user cache size is less than the default user cache size. For more information, see ZOSMIGV2R1_ZFS_VERIFY_CACHESIZE in IBM Health Checker for z/OS User's Guide.

zFS also provides a check to see if all the user cache pages are registered with the zEDC Express service if there are compressed aggregates. This check raises an exception if the user cache pages are not registered. For more information, see ZFS_VERIFY_COMPRESSION_HEALTH in IBM Health Checker for z/OS User's Guide.

The expected value is a number in the range 10 MB - 65536 MB (64 G) if the edcfixed option is not used. If the edcfixed option is used, the user cache size should be in the range 10 MB – 14336 MB (14 G) due to zEDC compression limitations. K or M can be appended to the value to mean kilobytes or megabytes. For example:

• user_cache_size=64M,fixed

For the default value, zFS calculates 10% of real storage the system has available during zFS initialization. If this amount is less than 256 M, then the default is 256 M. If this amount is between 256 M and 2 G, then the default is 10% of real storage. If the amount is greater than 2 G, then the default is 2 G.

user_running_hangdump

Specifies whether a hang dump should be taken for a user task that has been hanging for approximately 5 minutes. The expected value is ON or OFF. For example:

user_running_hangdump=on

The default value is OFF.

vnode_cache_size

Specifies the initial number of vnodes that will be cached by zFS. The number of vnodes with vnode extensions will not exceed this number.

The expected value is a number in the range 1000 to 10 million. For example:

vnode_cache_size=131072

The default value is 32768. That number will be increased if z/OS UNIX needs more than this number.

The following options are used during debugging of the zFS PFS and the batch utilities (ioeagfmt, ioeagslv, and ioefsutl). They might not apply to the utilities and commands that are listed in the preceding section.

cmd_trace

Specifies whether command tracing is done for the batch utilities. If On, a zFS trace will be printed in the data set that is specified by the zFS PFS trace_dsn configuration option after the batch utility completes.

• Traces from ioeagfmt have a member name of IOEAGT01.
• Traces from ioeagslv have a member name of SALVAT01.
• Traces from ioefsutl have a member name of FSUTLT01.

The expected value is ON or OFF. For example:

cmd_trace=on

The default value is OFF.

debug_settings_dsn

Specifies the name of a data set containing debug classes to enable when the zFS PFS or the batch utilities start. It is read when zFS is started (or restarted). The debug classes are also used by the batch utilities.

The expected value is the name of a data set containing debug classes to enable. For example:

debug_settings_dsn=usera.zfs.debug.input(file1)

There is no default value.

max_errors

The maximum number of errors that the salvager program allows before it stops. If this limit is exceeded, the salvager program ends with message IOEZ00752E.

The expected value is a number in the range 1000 - 1000000. For example:

MAX_ERRORS=5000

The default value is 100000.

msg_input_dsn

Specifies the name of a data set containing translated zFS messages. It is specified when the installation uses messages that are in languages other than English. (When you use English messages, do not specify this option.) It is read when zFS or the batch job is started (or restarted). Currently, Japanese messages are supported.

The expected value is the name of the data set that contains translated zFS messages. For example:

msg_input_dsn=usera.sioemjpn

There is no default value.

msg_output_dsn

Specifies the name of a data set that contains any output messages that come from the zFS PFS during initialization. See Performance and debugging. This is not a required parameter.

The expected value is the name of a data set that contains the zFS PFS messages that were issued. For example:

msg_output_dsn=usera.zfs.msg.out

There is no default value.

trace_dsn

Specifies the name of a data set that contains the output of any operator MODIFY ZFS,TRACE,PRINT commands or the trace output if the zFS PFS or the batch utilities abends. Each trace output creates a member in the PDSE. This is not a required parameter. If it is not specified, only a dump is generated if an abend occurs.

• Traces that come from the ioeagfmt program are named IOEAGTnn.
• Traces that come from the zFS PFS kernel have member names of ZFSKNTnn.
• Traces from the salvager program have member names of SALVATnn.
• Traces that come from the ioefsutl program have member names that start with FSUTLTnn. Note that nn starts with 01 and increments for each trace output. nn is reset to 01 when zFS is started (or restarted). See Performance and debugging.

The expected value is the name of a PDSE data set. For example:

trace_dsn=usera.zfs.trace.out

There is no default value.

trace_table_size

Specifies the size, in bytes, of the internal trace table. This is the size of the wrap-around trace table in the zFS address space and the batch utility address spaces that is used for internal tracing that is always on. The trace can be sent to the trace_dsn by using the operator MODIFY ZFS,TRACE,PRINT command. You can set the trace_table_size up to 65535 M, but to print the trace to a PDSE you must limit its size to 750 M.

The expected value is a number in the range 1 M - 65535 M. For example:

trace_table_size=256M

The default value is as follows:

• 16 M for the zFS address space.
• 64 M for the batch utility address spaces.

user_running_hangdump

Specifies that if a user task appears to be hung for approximately 5 minutes, a dump of the user address space is obtained by the ZFS hang detector. This dump is with abend code 2C3 and reason code EA5805DB. This dump is accompanied by message IOEZ00605I. Use this message description to diagnose the problem.

The expected value is ON or OFF. For example:

user_running_hangdump=ON

The default is OFF.

xcf_trace_table_size

Specifies the size of the XCF trace table. The expected value is a number in the range 1 M - 65535 M. For example:

xcf_trace_table_size=8M

The default value is 4 M.