Universal Data Mover - forfiles Statement

Introduction

UDM provides a powerful iterative loop structure, forfiles, that iterates through a series of statements for each file found that matches a file specification.

Syntax

The syntax of the forfiles statement is:



forfiles logical_name=file_spec
         [sortby=attribute-name[,ascending | descending]]
         [msecs=yes | no]
  ...
  UDM commands
  ...
end


logical_name is the logical name of a transfer server.

file_spec is the file specification used to select files for the iteration (see File Specification).

From the specified transfer server, UDM builds a list of files that match the file specification. UDM then executes all of the commands listed between the forfiles statement and the end statement, once for each file in the list.

The optional sortby parameter specifies the name of a special attribute attribute-name of the _file built-in variable. The list of files that match file_spec will be sorted based on the value of attribute-name. ascending and descending specify whether the matching files are listed in ascending or descending order. (If neither is specified, the list is sorted in ascending order.)

Since having a sortby attribute in the forfiles loop implies that the file attributes will be used, the file attributes will be retrieved regardless of whether or not fileattrib=yes is present.

The optional msecs parameter adds a milliseconds component for the time and timestamp attributes of the _file built-in variable. If msecs=yes, time values and the time component of timestamp values are displayed in the format hh:mm:ss.nnn, where .nnn is a value in milliseconds. If msecs is not specified or set to no (the default), the .nnn portion of the time and timestamp values is not displayed.

msecs is applied only if fileattrib=yes and/or the sortby options are specified for the forfiles statement. Otherwise, msecs is silently ignored.
 

Note

The file times that include a millisecond value are not available on all file systems and platforms that UDM supports. For any platform that cannot obtain a file time's millisecond value (for example, z/OS), UDM displays an error stating that the msecs parameter is not supported. For any platform that recognizes a millisecond component of file times, but the file system itself does not update it, .000 is shown.


Examples

To obtain a file list, sorted by creation date (earliest to latest):

forfiles src=*.txt sortby=createdate
    # Do some stuff
end


To obtain a file list, ordered by file size from largest to smallest:

forfiles src=*.exe sortby=size,descending
    # Do some more stuff
end


An error would be produced if sortby was present without a value or if it referred to an attribute that does not exist for the _file variable.
 

To display modification times and timestamps for a list of files in the current directory with an extension of *.txt:

forfiles src=*.txt fileattrib=yes msecs=yes
   echo $(_file) ": " $(_file.modtime) ", " $(_file.modtimestamp)
end

Detailed Information

The following pages provide detailed information for the Universal Data Mover forfiles statement: