DIRECTORY_LIST

LANSA Composer

DIRECTORY_LIST

This activity will list the contents of a directory.  Using this activity you can list either the files or the directories contained in the specified directory.  You can also specify whether the list should include contents of nested sub-directories contained in the specified directory.

Optionally, files (but not sub-directories) may be filtered using the FILENAME and/or EXTENSION parameters.  If neither parameter is specified, all available files will be included in the file list (when the content requested is *FILES).

Activities that populate list variables are often followed by a LOOP processing sequence directive or other constructs to process the contents of the list.  Refer to Variables and Lists for more information about the use of list variables.

INPUT Parameters:

DIRECTORY : Required

This parameter should contain the full path of the directory whose contents are to be listed.

For example:   Windows   C:\mydirectory

IBM i     /orders/January

CONTENT : Optional

This parameter specifies whether files or directories contained in the specified directory are to be listed.  You may specify one of the following values:

*FILES  (to list the files)
*DIRECTORIES  (to list the directories)

(The alias value *FOLDERS may also be used as an alternative to *DIRECTORIES)

If this parameter is not specified, a default of *FILES is assumed.

MAXDEPTH : Optional

This parameter specifies whether the content of sub-directories of the specified directory should be included, and, if so, the nested depth to which this should apply.  You may specify one of the following values:

1  (lists only the files or directories that are immediate children of the specified directory)
n  (list files or directories to the nesting depth specified by the integer value)
*MAX  (lists files or directories contained in the specified directory and all descendant directories)

If this parameter is not specified, a default of 1 (one) is assumed.

Note that in order to avoid unintended "runaway" processing, the special value *MAX actually limits the nesting depth to 9 (nine), which would be reasonable for most circumstances.  If you wish to process directory contents to a nesting depth greater than this, then you may do so by explicitly specifying an appropriate integer value.

CAUTION:  Use this parameter with care.  It is very easy to inadvertently make a request much larger than you might have anticipated.  Specifying a value greather than 1 (one) in conjunction with a directory that contains many files or sub-directories may lead to an unexpectedly long processing time for the activity and/or to processing limits being exceeded.

FILENAME : Optional

This parameter may be specified when you wish to list files that match a specified file name and/or extension pattern.  This parameter only applies when the content requested (in the CONTENT parameter) is *FILES.

The filter matching is not case sensitive.  For example a value of 'abc*.txt' will result in only files with an extension of .TXT or .txt and with names beginning with 'ABC' or 'abc' being returned in the file list.

When constructing the file name mask, you may use the following placeholder characters:

  ?

Will match any single character at the specified position of the name or extension of the file name

  *

Will generically match any/all remaining characters in the name or extension component of the file name

Within either the name or extension component of the file name mask, any characters after the first '*' are not effective and will be ignored.  If there is no extension component, then files of any (or no) extension will be matched.

Examples:

*.*

Will list all files (equivalent to omiting this parameter value)

ab*.*

Will list all files whose names begin with 'ab' and with any (or no) file extension

???d*.csv

Will list all files whose names contain 'd' in the 4th position and that have an extension of 'csv'

*.xm*

Will list all files whose file extension begins with 'xm'

 

EXTENSION : Optional

This parameter may be specified when you wish to list only files with a certain extension.  This parameter only applies when the content requested (in the CONTENT parameter) is *FILES.

The filter matching is not case sensitive and does not require the '.' prefix.  For example a value of 'xml' will result in only files with an extension of .XML or .xml being returned in the file list.

This parameter provides better performance than the FILENAME parameter alone if you only want to select files by file extension.  (This is because it is implemented at the LANSA Integrator XMLFileService level, rather than as a post-processing step).  You may specify both the FILENAME and EXTENSION parameters - the value of the EXTENSION parameter is applied first and matching files are then tested aainst the FILENAME mask, if provided.

ORDERBY : Optional

This parameter allows you to specify the order in which the files will be listed in the FILELIST output parameter.  You may specify one value from each of the following two groups (each value should be separated by at least one space):

1.  *NONE | *NAME | *MODIFIED

2.  *ASCEND | *DESCEND

You must specify quote marks around the value(s) to distinguish them from built-in variable names.

The values are described further below.  If you specify more than one value from each group, the last-specified value is effective.  If you do not specify this parameter, the default values is *NONE, meaning that no explicit ordering is performed (in this case the actual order is undefined by LANSA Composer but may be subject to operating environment factors).

1.  *NONE | *NAME | *MODIFIED

These values specify the file attribute that is used to order the list of files.  Specify *NAME to have the list ordered by file path.  Specify *MODIFIED to have the list ordered by the date last modified for each file.

2.  *ASCEND | *DESCEND

These values specify the ordering to apply.  Specify *ASCEND to list the files in ascending order or *DESCEND for descending order.  If not specified, the default is *ASCEND.

For example, specify '*MODIFIED *DESCEND' to have the files listed in descending order of the last-modified date.

NOTE:  The ORDERBY parameter applies whether the content requested (in the CONTENT parameter) is *FILES or *DIRECTORIES.  If the MAXDEPTH parameter specifes a value greater than 1 (one), ORDERBY affects the order of files or directories within each directory listed.

OUTPUT Parameters:

FILELIST

Specifies the name of a list variable that, upon successful completion, will contain a list of the files or directories that match the request.

The list will contain the full path and file or directory name.  If you specify a value other than *NONE for the ORDERBY parameter, the list entries will be ordered as specified (within each sub-directory, if applicable).

For example:  Windows   C:\mydirectory\file1.txt

IBM i    /orders/January/ord01.xml