VI Directory Input Object

The Visual Integrator (VI) Directory input object generates a text file that lists a directory's files and a variety of metadata.

VI Directory Icon

The generated text file, that contains a list of files, requires another input object to read the contents of those files. Most often a Filein input object reads the contents of the files by using the File_List_Input attribute. For more information about the File_List_Input attribute, see the section in VI Filein Input Object.

The Filein object uses a File_List_Input attribute to parse the list of files and expects a text file with a single column named Filename. Therefore, you might need to insert an Alias or Calc process object and set that object to remove the Directory object's Filename column and then alias the Path column to one called Filename.

The Directory object has Closedthree panes where you set attributes.

VI Directory Object All Panes

You set attributes for the Directory object in the Closedobject attributes pane.

VI Dictionary Object Attributes Pane

Attribute Description

Starname

(optional)

Specifies a wildcard name in the Starname box to limit which files are selected from the directory. If not specified, all files in the directory are returned. This attribute does not restrict which subdirectories are walked if the Walk attribute is set.

For starname, you can use the wildcard characters question mark (?) or asterisk (*).

  • ? (question mark)—Matches any single character

  • * (asterisk)—Matches a sequence of characters

Wildcard character matching is case-insensitive and is limited to one directory only. To match in more than one directory, add additional rows to the section.

TIP: If working with case sensitive file names, try using a Directory input object. You can filter on the filename metadata and feed it into a Filein object using the File_List_Input attribute.

With the starname attribute, files are returned in the order that they are found in the directory; they are not necessarily sorted alphabetically. The order can vary across systems, and is often related to how files are deleted and added in the directory. Programs should not rely on the order of starnames.

Directory

(required)

 Specifies the top-level directory where your data files are located. If not specified, the Directory uses the project root.
Filetype_Directories

Specifies if directory entries are listed in the Directory object output flow.

  • True—Only directory entries are listed in the output flow; no files are listed
  • False (default)—Directory entries are not listed in the output flow
Filetype_Files

Specifies if file entries are listed in the Directory object output flow.

  • True—File entries are listed in the output flow
  • False (default)—File entries are not listed in the output flow
Filetype_Links

Specifies if link entries are listed in the Directory object output flow.

  • True—Link entries are listed in the output flow
  • False (default)—Link entries are not listed in the output flow
Walk

Specifies how to handle files within subdirectories in the Directory object output flow.

  • True—Files from the selected directory and any subdirectories are listed in the output flow
  • False (default)—Files only from the selected directory are listed in the output flow, ignoring files in any subdirectories
Hidden

Specifies how to handle files within hidden directories in the Directory object output flow.

  • True—Hidden directory files are listed in the output flow, including subdirectories if the Walk attribute is set to True
  • False (default)—Hidden directory files are not listed in the output flow
Encoding

Defines how files names are read and interpreted in terms of character encoding. Values include:

  • auto—The input object sets the encoding based on the file signature and the Unicode state of other objects in the same task.
  • ascii—The characters in the file are interpreted as ISO-8859-1 or Latin1 characters.

  • gb18030—The file is interpreted as Chinese National Standard 18030-2000 characters. The gb18030 encoding option is supported on Windows platforms only.

  • latin1—The characters in the file are interpreted as ISO-8859-1 or Latin1 characters.
  • utf-8—The file is interpreted as UTF-8 Unicode characters.
  • unicode—The file is interpreted as 2-byte Unicode characters (UCS-2) with native byte swapping, unless overridden by a UCS-2 file signature.

  • unicode-be—The file is interpreted as UCS-2 characters in a big-endian fashion.

  • unicode-le—The file is interpreted as UCS-2 characters in a little-endian fashion.

UCS-2 and UTF-8 files can include a Byte Order Mark (BOM) at the beginning of the file to denote the file encoding. These file signatures are defined as follows:

  • UCS-2 Big Endian—FE FF
  • UCS-2 Little Endian—FF FE
  • UTF-8—EF BB BF

File signatures are common for Unicode files on Windows operating systems. If the file input object reads multiple files, the signature of each file determines its encoding.

If the encoding attribute is auto and no signature is found, the encoding is assumed to be latin1 if no other object in the task handles Unicode data and the VI file is not encoded as utf-8 (using the charset 1208 directive). Otherwise, the encoding is assumed to be utf-8.

See also Integrator Unicode Data Support.
Error_Action

Specifies how to handle errors, such as if a directory cannot be listed or a file cannot be processed, in the Directory object output flow.

  • error (default)—Processing stops with an error
  • warn—Processing continues, and problems are recorded in the log
  • ignore—Processing continues, and problems are not recorded
First

Specifies a number to limit how many records are read from each input file. This attribute is useful for script testing on a small number of records. If not used, all rows are read.
Prefix Defines a prefix that is added to all column names in the flow. If you want a space between the prefix and the column name, include that space in the prefix string definition. Any columns assigned an alias do not use the prefix; instead, the columns use the alias name.
Alias_Lines

Aliases can be set and edited in both the Alias_Lines attribute and the column grid. The column grid allows for graphical editing, while the Alias_Lines attribute is set at the code level in the following format:

OldColumnName=NewColumnName

For example:

inv_nbr=Invoice Number

Where Invoice Number is the alias for inv_nbr.

The Alias_Lines method is useful for working with array parameters used as aliases. VI cannot process these array parameters because they are not in a format that VI can interpret.

VI considers these array parameters to be malformed aliases and displays a warning message in the Logs tab. For example:

Alias definition "$(ExternalAliases)" in object
"From List" is not formatted as "OldColumn=NewColumn". When
the line contains a parameter Integrator is most likely able to
resolve it when the parameter is properly defined. To edit this
alias definition use the "Alias_Lines" property.

This message indicates that there is a malformed alias named $(ExternalAliases) in the object named From List. The array parameter displays as $(ExternalAliases) in the script. For VI to interpret this array parameter, you must assign an alias in the VI format.

  1. Select the object in the task flow that is mentioned in the warning message. In this example From List.

  2. Click in the Alias_Lines field, and then click the browse button that appears.

    The ClosedAlias lines for <object_name> dialog box displays.

    VI Alias Lines Dialog Box

  3. Edit the alias in the form of:

    OldColumnName=NewColumnName

    In this example:

    $(ExternalAliases)=External Aliases

  4. Click OK.

  5. The array parameter has an alias, and the error message no longer appears.

Each object has an area where you can enter comments.

It is a DI best practice to enter a note for every object in a VI script. You can set a VI preference to give a warning for each object without a note. For more information, see Visual Integrator Preferences.

ClosedDirectory object with comments.

VI Directory Object with Comment

The ClosedDirectory column grid allows you to choose which metadata to include in the output data flow.

VI Directory Column Grid

Attribute Description
Name View the name of each file metadata input column (read-only).
Alias Defines alternate names for any of the input columns. Spaces before or after an alias column name are ignored. Spaces within an alias column name are acceptable.
Keep Order Manages the order that columns display in the output data flow. By default, columns that are passed to the next object in the data flow are displayed in the order that they appear in the Name column. You can change this order by typing a number in the Keep Order column. When you assign a Keep Order number, the Keep column is checked automatically. The Keep Order numbers might reorder to accommodate any changes you make.
Keep

Manages which columns are kept in the output data flow. If no columns have a Keep check mark, all columns are kept in the output data flow, except for any explicitly marked Remove.

Select the Keep check box for columns you want to explicitly keep in the output data flow. A number is automatically added in the Keep Order column when you select its Keep check box. After marking any column with a Keep check mark, only those marked Keep are kept in the output data flow.

NOTE: After any Keep check boxes are checked, do not use the Remove check boxes as clicking a Remove check box sets all Keep check boxes to unchecked.
Remove

Manages which columns are removed from the output data flow. Select the Remove check box for columns that you want to explicitly suppress from the output data flow.

NOTE: Use the Remove check boxes only when no Keep check boxes are checked.

The Directory input object column grid Closedname column offers various metadata about the files in the directory that you can include as columns in the output data flow. Note, however, that when running within a project, all platform-specific fields (Drive, Access Mode, Inode number) are blank.

VI Directory Column Grid Metadata

Column Description
Filename Returns the file name.
Path Returns the full path, including the file name.
Drive Returns the drive name for Windows platforms. Returns blank for other platforms or UNC paths, for example, \\machine_name\...
File Extension Returns the file name extension.
Relative Path Returns the relative path to the file, relative to the top-level directory as indicated in the Directory attribute.
File Type Returns the file type. On Windows platforms, it returns file or directory. On other platforms, it returns file, directory, link, named pipe, block device, character device, or socket.
File Size Returns the file size in bytes.
Modified Date Returns the date that the file was last modified in standard DI date format (YYYY/MM/DD) based on the local machine.
Accessed Date Returns the date that the file was last accessed in standard DI date format (YYYY/MM/DD) based on the local machine.
Modified Time Returns the time that the file was last modified in standard DI time (HH:MM:SS) based on the local machine.
Accessed Time Returns the time that the file was last accessed in standard DI time (HH:MM:SS) based on the local machine.
File Attributes Returns file attributes for files on Windows platforms as listed by the dir command: Archive (A), Hidden (H), Read-only (R), and System (S). Returns blank on other platforms.
Access Mode Returns the file mode on non-Windows platforms as defined by the UNIX ls command. This mode is a 10-character string where a hyphen represents null access, for example, -rw-r--r--.
Owner Returns the file owner as a string on non-Windows platforms, for example, root. Returns blank on Windows platforms.
Group Returns the file's group as a string on non-Windows platforms, for example, staff. Returns blank on Windows platforms.
UID Returns the user ID (UID) of the file owner as a number on non-Windows platforms. Returns blank on Windows platforms.
GID Returns the group ID (GID) of the file's group as a number on non-Windows platforms. Returns blank on Windows platforms.
Inode Number Returns the i-node number on non-Windows platforms. Returns blank on Windows platforms.
Link Target Returns the target of a symbolic link on non-Windows platforms. Returns blank on Windows platforms, or for non-link directory entries.
File Blocks Returns the allocation size in kilobytes.

NOTE: With the project paradigm in Workbench, only the following information can be returned:

  • Filename
  • Path
  • File Extension
  • Relative Path
  • File Type
  • File Size
  • Modified Date
  • Modified Time
  • C Date
  • C Time

Other file information is beyond the project abstraction and cannot be returned.