OA67431: NEW FUNCTION - Allow zFS filesystem(s) to be re-sized based on a percentage value specified on the zfsadm shrink command.

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• NEW FUNCTION
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: z/OS File System (ZFS) 2.5                   *
  *                 FMID(HZFS450)                                *
  *                                                              *
  *                 z/OS File System (ZFS) 3.1                   *
  *                 FMID(HZFS510)                                *
  ****************************************************************
  * PROBLEM DESCRIPTION: This  apar is providing new function    *
  *                      for the zfsadm shrink command. It       *
  *                      provides additional capabilities        *
  *                      allowing more flexibility managing      *
  *                      zFS file systems and can be used to     *
  *                      obtain more informative information     *
  *                      about shrink operations.                *
  ****************************************************************
  * RECOMMENDATION: APPLY PTF                                    *
  ****************************************************************
  The new function is being delivered in APAR OA67431 for both
  z/OS 2.5 and 3.1 system releases. It provides the zfsadm shrink
  command with the following:
  
  Allow the shrink of one or more zFS file systems by specifying
  a leading or trailing wildcard character against the specified
  aggregate name.
  
  Allow a shrink to specify a percentage of free space to be
  released for the shrink activity as an alternative to
  specifying a specific target size.
  
  Allow a shrink of a zFS file system that is not currently
  mounted without having to manually mount the filesystem.
  
  Allow a shrink of a zFS file system that is currently mounted
  read-only without having to manually re-mount it as read-write.
  
  Display statistics during the shrink operation which indicate
  the number of blocks moved, fragments freed to give the  zFS
  administrator more information about the processing of their
  request.
  
  For complete details and reference, refer to the zfsadm shrink
  section in Chapter 11 in the z/OS 3.2 zFS File System
  Administration for information regarding the new function. New
  message updates can be found in the  z/OS 3.2 zFS File System
  Messages and Codes guide.
  
  For the zFS File System Administration and File System Messages
  and Codes guides, refer to the following links:
  
  https://www.ibm.com/docs/en/SSLTBW_3.2.0/pdf/ioea700_v3r2.pdf
  https://www.ibm.com/docs/en/SSLTBW_3.2.0/pdf/ioea500_v3r2.pdf
  
  Technical changes or additions to the text and illustrations for
  the new function can be identified by a vertical line to the
  left of the change in the z/OS 3.2 edition.
  
  Overview of changes in Chapter 11. zFS commands, in
  the zfsadm shrink section:
  
  Purpose (updated)
  zfsadm shrink reduces the physical size of a zFS aggregate. To
  shrink a single aggregate, the aggregate can be mounted either
  read/write or read-only. It can also be unmounted.
  
  To shrink multiple aggregates on a single request via wildcards,
  the target aggregates must be mounted read/write or read-only.
  
  To shrink aggregates that are mounted read-only, use the
  -remountro option.
  
  The zfsadm shrink command releases unused space from the
  aggregate data set. The resulting physical size of the data set
  is approximately the new total size that was requested by the
  -size option or calculated by using the release option.
  
  Format (new options added/updated)
  zfsadm shrink -aggregate name{-size Kbytes [-noai]|-release
  percent [-noai]|-cancel} [-remountro][-level][-help]
  [-trace file_name]
  
  Options
  -aggregate name (updated)
  The name of the aggregate to shrink. The name can include the
  wildcard character * at the beginning, the end, or at both the
  beginning and end. If the wildcard is used, each mounted
  aggregate whose name matches the name pattern will have a shrink
  command invoked against it.
  
  -size Kbytes (updated)
  The new size of the aggregate in 1 K units. It is rounded up to
  an 8 K boundary if necessary. This new size must be larger than
  the minimum size of an aggregate and must be less than the
  current size of the aggregate minus 8 K. If the amount of free
  space requested to be released is larger than the free space in
  the aggregate, zFS automatically increases the Kbytes value by
  at least 1 MB. The increase results in less free space being
  released than originally requested and might happen due to file
  system activity or the conversion of fragments to blocks during
  the shrink operation.
  
  -cancel (updated)
  Cancels an in-progress shrink operation if there is one
  occurring for the aggregate.
  
  -release percent (new)
  The percentage of free space to be released during the shrink
  operation. The percent value is 1-100. A new size for the
  aggregate is generated, based on the current size of the
  aggregate and the number of 8 K blocks that are free when the
  command was issued. If the amount of free space requested to be
  released is larger than the free space in the aggregate, zFS
  automatically increases the size value by at least 1 MB. The
  increase results in less free space being released than was
  requested. This adjustment occurs only if there is file system
  activity during the shrink operation or if 8 K blocks need to be
  allocated to store objects that were being kept in fragments.
  
  -remountro (new)
  The use of the -remountro option indicates to zFS that if the
  aggregate is mounted read-only, it can be mounted read/write in
  order for the shrink operation to complete. Afterward, the
  aggregate is remounted read-only. In some cases the remount to
  read-only might fail (for example, the user session that issued
  the shrink command was canceled) and the aggregate might remain
  read/write. If you do not want it to remain read/write, you
  must manually remount the aggregate read-only.
  
  Important: Be careful when you use this option because the
  aggregate might be mounted on another system that is not part of
  your single system or shared file system environment. While the
  file system is mounted read/write, applications can change the
  file system.
  
  -noai  (new)
  zFS does not automatically increase the Kbytes value that is
  specified on the -size option or calculated via the -release
  option if there is not enough free space to satisfy the request.
  
  Shrinking a zFS aggregate section added.
  
  Aggregates that can be shrunk section added.
  
  Establishing the shrink line section added.
  
  Calculating the shrink line section added.
  
  Moving the shrink line section added.
  
  Using FSINFO to determine the shrink progress section added.
  
  Usage notes for zfsadm shrink section updated.
  
  Examples section updated.
  
  The following updates have been added to the z/OS File
  System Messages and Codes SC23-6885-xx
  
  The following messages are new:
  
  IOEZ01076E
  IOEZ01079E
  IOEZ01080I
  IOEZ01081I
  IOEZ01082I
  IOEZ01083I
  IOEZ01084I
  IOEZ01085E
  IOEZ01086E
  IOEZ01087I
  IOEZ01088I
  IOEZ01089E
  
  IOEZ01076E Incorrect value Release provided in the argument for
  the -release option.
  Explanation
  An incorrect argument value was provided for the -release option
  of the zfsadm command.
  In the message text:
  Release
  The value that the user entered for the -release option
  argument.
  System action
  The program ends.
  212 z/OS: z/OS File System Messages and Codes
  Administrator response
  Change the -release option argument to an integer in the range
  1-100 and reissue the zfsadm command.
  Severity
  svc_c_sev_error
  
  IOEZ01079E Invalid wildcard pattern in aggregate name
  aggregate_name.
  Explanation
  The zfsadm command only supports wildcards that have '*' at
  either the beginning or the end of the aggregate name, or both.
  In the message text:
  aggregate_name
  The aggregate name with the wildcard.
  System action
  The program ends.
  Administrator response
  Correct the aggregate name and try again.
  Severity
  svc_c_sev_error
  
  IOEZ01080I Shrinking aggregate name aggregate_name to size
  Block_size 8K blocks.
  Explanation
  zFS is starting to shrink the file system for the specified
  aggregate name using the new size provided with the -size option
  or internally calculated by using the argument specified on the
  -release option.
  In the message text:
  aggregate_name
  The aggregate name.
  Block_size
  The targeted size of the file system in 8K blocks.
  System action
  The program continues.
  Administrator response
  None.
  Severity
  svc_c_sev_notice
  
  IOEZ01081I Shrink line for aggregate aggregate_name adjusted to
  block Block_number after moves: Shrink_line_moves.
  Explanation
  zFS has adjusted the shrink line for the aggregate to the block
  number specified using the indicated number of shrink line
  moves.
  In the message text:
  aggregate_name
  The aggregate name.
  Block_number
  The new shrink line of the file system specified as a block
  number.
  Shrink_line_moves
  The number of shrink line moves that occurred while performing
  the shrink operation.
  System action
  The program continues.
  Administrator response
  None.
  Severity
  svc_c_sev_notice
  
  IOEZ01082I Activity detected while shrinking aggregate
  aggregate_name. Blocks allocated Blocks_allocated, blocks freed
  Blocks_freed, blocks reserved by clients Client_blocks.
  Explanation
  zFS detected file system activity during shrink processing which
  could have caused the shrink line to be moved,and therefore
  could have affected the amount of space released from the zFS
  aggregate.
  In the message text:
  aggregate_name
  The aggregate name.
  Blocks_allocated
  The number of 8K blocks allocated.
  Blocks_freed
  The number of 8K blocks freed.
  Client_blocks
  The number of 8K client blocks reserved.
  System action
  The program continues.
  Administrator response
  None.
  Severity
  svc_c_sev_notice
  
  IOEZ01083I Shrink processing for aggregate aggregate_name
  converted Fragments_converted fragments to Blocks_created 8K
  blocks.
  Explanation
  zFS detected that the file system contained legacy fragmented
  objects that are no longer kept as fragmented objects. These
  objects were converted to blocked objects. These conversions
  could have caused the shrink line to move, and therefore, could
  have affected the amount of space released from the zFS
  aggregate.
  In the message text:
  aggregate_name
  The aggregate name.
  Fragments_converted
  The number of 1K fragments converted to blocks.
  Blocks_created
  The number of 8K blocks created from 1K fragments.
  System action
  The program continues.
  Administrator response
  None.
  Severity
  svc_c_sev_notice
  
  IOEZ01084I The -remountro option was provided for unmounted
  aggregate aggregate_name. Attach will be attempted.
  Explanation
  The aggregate name specified is not currently mounted. The
  -remountro option will be ignored and an attach will be
  attempted to complete the zfsadm shrink operation.
  In the message text:
  aggregate_name
  The aggregate name.
  System action
  The program continues.
  Administrator response
  None.
  Severity
  svc_c_sev_notice
  
  IOEZ01085E The remount of aggregate aggregate_name as R/W failed
  prior to the shrink operation.
  Explanation
  The -remountro option of the zfsadm shrink command was
  specified. The file system is mounted R/O. The remount as R/W
  has failed. The shrink operation was not performed.
  In the message text:
  aggregate_name
  The aggregate name.
  System action
  The program ends.
  Administrator response
  Determine why the remount as R/W failed. Reissue the zfsadm
  shrink command after attempting to resolve any conflicts. If the
  problem persists, contact your service representative.
  Severity
  svc_c_sev_error
  
  IOEZ01086E The remount of aggregate aggregate_name as R/O failed
  after completing the shrink operation.
  Explanation
  The -remountro option of the zfsadm shrink command was
  specified. The file system was mounted R/O at that time and was
  internally remounted as R/W in order to shrink the aggregate.
  The internal remount back to R/O either failed or was not able
  to be performed.
  In the message text:
  aggregate_name
  The aggregate name.
  System action
  The program ends.
  Administrator response
  Manually remount the aggregate as R/O if R/W access is not
  desired.
  Severity
  svc_c_sev_error
  
  IOEZ01087I Aggregate aggregate_name was successfully remounted
  as R/O after completing the shrink operation.
  Explanation
  The aggregate name specified was returned to R/O access after
  completing the shrink operation.
  In the message text:
  aggregate_name
  The aggregate name.
  System action
  The program continues.
  Administrator response
  None.
  Severity
  svc_c_sev_notice
  
  IOEZ01088I Aggregate aggregate_name was temporarily remounted as
  R/W prior to completing the shrink operation
  Explanation
  The -remountro option of the zfsadm shrink command was
  specified. The file system was mounted R/O at that time, and was
  internally remounted as R/W in order to shrink the aggregate.
  It will automatically be remounted as R/O once the shrink
  operation completes.
  In the message text:
  aggregate_name
  The aggregate name.
  System action
  The program continues.
  Administrator response
  None.
  Severity
  svc_c_sev_notice
  
  IOEZ01089E Aggregate aggregate_name is no longer mounted. No
  shrink operation performed.
  Explanation
  A zfsadm shrink command was entered using a wildcard. An attempt
  to shrink the specified aggregate failed. The aggregate was
  mounted at the time of the request, but was unmounted prior to
  shrink operation completion.
  The shrink operation was not performed.
  In the message text:
  aggregate_name
  The aggregate name.
  System action
  The program ends.
  Administrator response
  Verify that the provided aggregate is mounted for the duration
  of the wildcard shrink command and retry the request.
  Alternatively, if a shrink of an unmounted aggregate is
  required, retry the request without a wildcard and allow the
  shrink operation to complete using the auto-attach feature.
  Severity
  svc_c_sev_notice
  
  The following reason codes are new:
  6256
  62A7
  
  6256 Detach failed because a long running admin command is in
  process.
  
  Action
  Attempt to use the appropriate zfsadm command with the -cancel
  option to interrupt the log running command. Reissue the detach
  after the long running operation completes. If the problem
  persists, contact the service representative.
  
  
  62A7 AGGR_ID name not specified.
  Action
  The aggregate name in the AGGR_ID must be specified.
  

Problem conclusion

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  UJ99216 UJ99217

Modules/Macros

• IOEAGFMT IOEAGSLV IOEDUMPF IOEFSCM  IOEFSKN  IOEFSTHD IOEFSUTL
  IOEZADM
  

Fix information

• Fixed component name

  ZFS ZSERIES FIL

• Fixed component ID

  5696EFS00

Applicable component levels

• R450 PSY UJ99217

     UP26/03/31 P F603  

• R510 PSY UJ99216

     UP26/03/31 P F603  

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.