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.

The location of the IOEFSPRM file can be specified by the IOEZPRM DD statement in the zFS PROC and in the JCL for the ioefsutl or ioeagslv batch utilities. However, the preferred method for specifying the zFS configurations options file is to use the IOEPRMxx parmlib member as described in Using PARMLIB (IOEPRMxx). If you still want to use a single IOEFSPRM file, specify the IOEZPRM DD statement in your JCL. The IOEFSPRM file is typically a PDS member, so the IOEZPRM DD statement might look like the following example:

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

If you need to have separate IOEFSPRM files and you want to share the zFS PROC in a sysplex, you can use a system variable in the zFS PROC so that it points to different IOEFSPRM files. The IOEZPRM DD might look like the following:

//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. For more information about PARMLIB, see z/OS MVS Initialization and Tuning Reference.

The IOEPRMxx files are contained in the logical parmlib concatenation. The logical parmlib concatenation is a set of up to ten partitioned data sets defined by parmlib statements in the LOADxx member of either SYSn.IPLPARM or SYS1.PARMLIB. The logical parmlib concatenation contains zFS IOEPRMyy members that contain zFS configuration statements. Columns 72-80 are ignored in the IOEPRMyy member. The yy values are specified in the PARM option of the FILESYSTYPE statement for the zFS PFS (in the BPXPRMxx). The only valid value that can be specified on the PARM option for the zFS PFS is the parmlib search parameter PRM=. The PARM string is case-sensitive. As the following example shows, you must enter the string in uppercase.

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.

Up to 32 member suffixes can be specified. You can also use any system symbol that resolves to two characters.

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, this specifies that PARMLIB member IOEPRMAB should be 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.

To specify 32 members, type the member suffixes up to column 71; then, continue them in column 1 on the next line, as shown in Figure 1.

Figure 1. How to specify 32 members

                                                                    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.

Usage

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.

Default value: 10

Expected value: A number in the range 1 - 256.

Example: adm_threads=5

aggrfull

Specifies the threshold and increment for reporting aggregate utilization messages to the operator. 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.

Default value: Off

Expected value: Two numbers in the range 1 - 99 within parentheses that are separated by a comma.

Example: aggrfull(90,5)

aggrgrow

Specifies whether aggregates can be dynamically extended when they become full. As of z/OS® V1R13, by default, a zFS read/write mounted file system 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 volume(s). This global value can be overridden on the MOUNT command for compatibility mode aggregates. For an explanation of the rules for extending a VSAM LDS, see z/OS DFSMS Using Data Sets.

Default value: On

Expected value: On or Off

Example: aggrgrow=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.

Default value: Off

Expected value: On or Off

Example: change_aggrversion_on_mount=off

client_cache_size

Specifies the amount of storage that is used to cache sysplex client user data. You can also specify a fixed option that indicates the pages are permanently fixed for performance. This option is in contrast to user_cache_size (see user_cache_size). This option is only used for zFS sysplex-aware read/write file systems that are owned on a release prior to z/OS V1R13.

The fixed option reserves real storage for use by zFS only.

Default value: 32M

Expected value: A number in the range 10M - 65536M. K or M can qualify the number.

Example: client_cache_size=256M

client_reply_storage

Specifies the amount of storage that is used to handle sysplex server replies.

Default value: 10 M

Expected value: A number in the range 2M - 128M. K or M can qualify the number.

Example: client_reply_storage=8M

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.

Default value: On

Expected value: On or Off

Example: convert_auditfid=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.

Default value: Off

Expected value: On or Off

Example: converttov5=off

file_threads

Specifies the number of threads that handle sysplex server requests.

Default value: 32

Expected value: A number in the range 1 - 256.

Example: file_threads=50

flc

This option will not be supported after z/OS V2R1. It specifies whether large FLC buffers are to be created. They are not created by default and specifications cannot be modified after zFS has initialized. Specifications for mindirsize, bufsize, bufnum and inactive values must be in this format, separated by commas:

flc=mindirsize,bufsize,bufnum,inactive

Default value: None

Expected value: One of the following values:

mindirsize. The minimum size of a directory for which a Large FLC buffer will be used. A K or M can be appended to the value to mean kilobytes or megabytes, respectively.
bufsize. The size of each buffer that will be used to hold the directory entries. A K or M can be appended to the value to mean kilobytes or megabytes, respectively.
bufnum. The number of Large FLC buffers.
inactive. The number of idle seconds before zFS considers Large FLC buffer to be inactive.

Example:

flc=256K,8M,30,45
flc=256K,8M,30,45

format_aggrversion

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

Default value: 4

Expected value: 4 (meaning format a version 1.4 aggregate) or 5 (meaning format a version 1.5 aggregate)

Example: format_aggrversion=4

fsfull

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

Default value: Off

Expected value: Two numbers in the range 1 - 99 within parentheses and separated by a comma.

Example: fsfull(85,5)

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. For more details, see the GRPNAME parameter of the IXCJOIN macro in z/OS MVS Programming: Sysplex Services Reference.

Default value: IOEZFS

Expected value: 1 to 8 characters

Example: group=IOEZFS1

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.

Default value: 16 M

Expected value: 1 to 8 characters

Example: log_cache_size=32M,fixed

meta_cache_size

Specifies the size of the cache 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

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. For more information, see ZFS_VERIFY_CACHESIZE in IBM Health Checker for z/OS: User's Guide.

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 and there is no metaback_cache created.
If this amount is between 64 M and 100 M, then meta_cache_size is assigned 10% of real storage size and there is no metaback_cache created.
If this amount is in the range 100 M to 2G+100M, then meta_cache_size is assigned 100 M and metaback_cache_size is assigned the remainder of the 10% of real storage size.
If the amount is greater than 2G+100M, then meta_cache_size is assigned 100M and metaback_cache_size is assigned 2 G.

Expected value: A number in the range 1 M - 1024 M. A K or M can be appended to the value to mean kilobytes or megabytes, respectively.

Example: meta_cache_size=64M,fixed

metaback_cache_size

Specifies the size of the backing cache that is used to contain metadata. This resides in a data space and can optionally be used to extend the size of the metadata cache. You can also specify a fixed option, which indicates that the pages are permanently fixed for performance. Note, the fixed option reserves real storage for usage by zFS only.

Default value: If meta_cache_size is specified then no metaback cache is created. Otherwise, see the default calculation description in meta_cache_size.

Expected value: 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.

Example: metaback_cache_size=64M,fixed

quiesce_message_delay

Specifies the minimum number of seconds to delay issuing the IOEZ00581E message after it is determined there is at least one quiesced aggregate and it needs to be displayed.

Default value: 30

Expected value: A number in the range 30 - 21474836.

Example: quiesce_message_delay=300

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.

Default value: Off

Expected value: On or Off

Example: romount_recovery=on

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.

Default value: 256 M

Expected value: A number in the range 128 M - 512 M.

Example: recovery_max_storage=128M

sync_interval

Specifies the number of seconds between syncs.

Default value: 30

Expected value: A number in the range 11 - 21474836.

Example: sync_interval=45

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.

Default value: filesys

Expected value: Off, filesys, or On, if BPXPRMxx specifies SYSPLEX(YES).

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

Tip: Specify sysplex=filesys.

Example: sysplex=filesys

sysplex_filesys_sharemode

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

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

Expected value: rwshare or norwshare

Example: sysplex_filesys_sharemode=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 initially allocated for the server token manager cache is 20480.

Default value: Double the number of vnodes (see vnode_cache_size) when running in a shared file system environment and sysplex-aware, or 20480 when running in a shared file system environment and non-sysplex aware, or <no value> otherwise (only meaningful when zFS is running sysplex-aware).

Expected value: A number in the range 20480 - 2621440.

Example: token_cache_size=30720

tran_cache_size

Specifies the initial number of transactions in the transaction cache.

Default value: 2000

Expected value: A number in the range 200 - 10000000

Example: tran_cache_size=4000

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 option reserves real storage for usage by zFS only.

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.

Expected value: A number in the range 10 MB - 65536 MB (64 G). K or M can be appended to the value to mean kilobytes or megabytes.

Example: user_cache_size=64M,fixed

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.

Default value: 32768 (will grow if z/OS UNIX needs more than this number)

Expected value: A number in the range 32 to 500000.

Example: vnode_cache_size=131072

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

cmd_trace

Specifies whether command tracing is done for the ioeagfmt batch utility or a zfsadm command. If On, a zFS trace will be printed in the dataset specified by the zFS PFS trace_dsn configuration option after the batch utility or command completes. A trace from ioeagfmt will have a member name of IOEAGT01. A trace from a zfsadm command will have a member name of ZFSADT01.

Default value: Off

Expected value: On or Off.

Example: cmd_trace=on

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.

Default value: None

Expected value: The name of a data set containing debug classes to enable.

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

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.

Default value: 100000

Expected value: A number in the range 1000 - 1000000

Example: MAX_ERRORS=5000

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.

Default value: None

Expected value: The name of a data set containing translated zFS messages.

Example: msg_input_dsn=usera.sioemjpn

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.

Default value: None

Expected value: The name of a data set that contains zFS PFS messages issued.

Example: msg_output_dsn=usera.zfs.msg.out

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. Traces that come from the zFS PFS kernel have member names of ZFSKNTnn. Traces from the salvager program have member names of ZFSSLVnn. Traces that come from the ioefsutl program have member names that start with FSUTLnn..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. This is not a required parameter. If it is not specified, only a dump is generated if an abend occurs.

Default value: None

Expected value: The name of a PDSE data set.

Example: user_running_hangdump=ON

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 salvager address space 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 2048M, but to print the trace to a PDSE you must limit its size to 750 M.

Default value:

16 M for the zFS address space
64 M for the salvager address space

Expected value: A number in the range 1M - 2048 M.

Example: trace_table_size=1M

user_running_hangdump

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

Default value: Off

Expected value: On or Off

Example: user_running_hangdump=ON

xcf_trace_table_size

Specifies the size of the XCF trace table.

Default value: 4 M

Expected value: A number in the range 1M - 2048M

Example: xcf_trace_table_size=8M

Examples

Following is a sample IOEFSPRM file that contains program options.

**********************************************************************
* zFS Sample Parameter File:  IOEFSPRM
* For a description of these and other zFS parameters, refer to the
* zFS Administration document.
* Notes:
*  1. The IOEFSPRM file and parameters in the file are optional but it
*     is recommended that the parameter file be created in order to be
*     referenced by the DDNAME=IOEZPRM statement the PROCLIB JCL for
*     the zFS started task or through the IOEPRMxx parmlib member.
*  2. An asterisk in column 1 identifies a comment line.
*  3. A parameter specification must begin in column 1.
************************************************************************
* The following msg_output_dsn parameter defines the optional output
* message data set. If this parameter is not specified, or if the data
* set is not found, messages will be written to the system log.
* You must delete the * from a line to activate the parameter.
************************************************************************
*msg_output_dsn=usera.zfs.msg.out
************************************************************************
* The following msg_input_dsn parameter is ONLY required if the optional
* NLS feature is installed. The parameter specifies the
* message input data set containing the NLS message text which is
* supplied by the NLS feature. If this parameter is not specified or if
* the data set is not found, English language messages will be generated
* by zFS. You must delete the * from a line to activate the parameter.
************************************************************************
*msg_input_dsn=usera.sioemjpn
************************************************************************
* The following are examples of some of the optional parameters that
* control the sizes of caches, tuning options, and program operation.
* You must delete the * from a line to activate a parameter.
************************************************************************
*adm_threads=5
*aggrfull(90,5)
*aggrgrow=on
*change_aggrversion_on_mount=off
*client_cache_size=32M
*client_reply_storage=10M
*cmd_trace=off
*convert_auditfid=off
*converttov5=off
*file_threads=40
*format_aggrversion=4
*fsfull(85,5)
*group=IOEZFS1
*log_cache_size=32M
*meta_cache_size=64M
*metaback_cache_size=64M
*romount_recovery=off
*recovery_max_storage=128M
*sync_interval=45
*sysplex=filesys
*sysplex_filesys_sharemode=norwshare
*token_cache_size=65536
*tran_cache_size=4000
*user_cache_size=256M
*vnode_cache_size=131072
**********************************************************************
* The following are examples of some of the options that control zFS
* debug facilities. These parameters are not required for normal
* operation and should only be specified on the recommendation of IBM.
* You must delete the * column from a line to activate a parameter.
**********************************************************************
*debug_settings_dsn=usera.zfs.debug(file1)
*trace_dsn=usera.zfs.trace.out
*trace_table_size=1M
*xcf_trace_table_size=8M