GET_FILESYSTEM

Use the GET_FILESYSTEM script function to retrieve multiple values from a computer's file system, starting at a defined path. This script element is exclusively available for OS agents, including Windows, UNIX, VMS, z/OS, OS/400, NSK, and BS2000.

Important!

Ensure you possess the necessary access rights to the target system folders (e.g., system volume information on Windows). Missing access rights will result in a return code of 0.
This script function automatically commits all open script transactions to the AE database. For more information, see Script Processing.

Syntax

GET_FILESYSTEM ([Host], [Path], File System Value [, Unit] [, include sub directories] [, Login object])

Parameters

Parameter	Description	Format
Host	(Optional) Identifies the name of the agent running on the target host. Tip: If you omit the host name, the system automatically uses the agent from your most recent GET_FILESYSTEM call. This reuses the retrieved results from the previous call, significantly increasing performance since the data is already available. For details, see the examples in Using the Optional Parameters Host and Path.	AE name, script literal, or script variable
Path	(Optional) Describes the files or file systems to evaluate. You can specify files, drives, volumes, paths, or Generation Data Groups (GDGs) based on the target system. You can use the wildcard characters * (any number of characters) or ? (exactly one character). Important! (Windows) You can only use the * and ? wildcards for file names, not for directories within the path. Notes: On Windows, terminate path specifications with a backslash and a * wildcard (e.g., C:\AUTOMIC\). Implement error handling (e.g., sending a message) in case the path does not exist. Use the prefix VOL=* to specify volumes (e.g., VOL=ALG1* targets all 8-character volumes starting with ALG and ending with 1). To specify Generation Data Groups (GDGs), enclose the * character in parentheses. For more information, see Generation Data Group (GDG) Support. Use a double backslash (\\) when designating the path for the root folder.	AE name, script literal, or script variable
File System Value	Determines the specific information to retrieve: PATH_SPACE_ALLOCATED: Allocated memory or hard drive space. PATH_SPACE_RELEASE: (BS2000) Releasable memory. PATH_SPACE_USED: Total size of files in the specified path. (z/OS) The returned data set size might be inaccurate for data sets on Extended Address Volumes (EAV). PATH_SPACE_UNUSED: (BS2000) Unused memory or hard drive space. PATH_FILE_COUNT: Total number of files. Tip: This returns 0 if the directory is empty. Use error handling script functions (like SYS_LAST_ERR_NR) to differentiate an empty directory (0 files) from an actual error (e.g., host inactive returning 0). PATH_FOLDER_COUNT: (Windows, UNIX, and OS/400) Number of folders. FILESYSTEM_SPACE_TOTAL: (Windows and OS/400) Total memory capacity of the hard drive. FILESYSTEM_SPACE_USED: (Windows and OS/400) Used memory. FILESYSTEM_SPACE_FREE: (z/OS, OS/400) Free memory of the volume; (Windows) Free memory of the drive.	AE name, script literal, or script variable
Unit	(Optional) Determines the unit of measurement for the returned file system value. Allowed formats include bytes, KB, MB, GB, and TB. Note: If you define an invalid unit, the system reverts to the default value without aborting, particularly when using the :ON_ERROR statement. Default: If omitted, the host strictly determines the return code format (e.g., BS2000 defaults to returning 1 for 1 PAM page, which equals 2048 bytes).	AE name, script literal, or script variable
include sub directories	(Optional) Dictates whether the search traverses subdirectories within the specified path. This parameter only functions on VMS, UNIX, and Windows agents. Allowed values: Y (default) or N. Important! Enabling this option negatively affects your AE system's performance.	Y or N
Login object	(Optional) Specifies the predefined Login object that supplies the credentials for the FILE Event object.	Name

Return Codes

The script function reflects the queried file system value directly within its return code.

0: Identifies that an error occurred while retrieving the file system value (e.g., the path could not be found). The only exception is PATH_FILE_COUNT, which legitimately returns 0 if a directory is empty.

Tip: Leverage the :ON_ERROR script statement to proactively define actions to take when errors surface. For more information, see Script Elements for Error Handling.

Using the Optional Parameters Host and Path

Example 1: FILE Event Context

When a FILE Event occurs, you can use the GET_FILESYSTEM script function to pull information regarding the file system, memory, and drive space. Because the host retrieves all related information simultaneously, you can query each individual detail separately by indicating the File System Value. In this scenario, you can cleanly omit the Host and Path parameters, as they are already inherently defined in the event's Details pane.

Example 2: Process Pages and Data Caching

You can deploy GET_FILESYSTEM within the Process pages of executable objects like Workflows. For more information, see Defining the Process Pages in Jobs and Understanding the Object Types in Automic Automation.

The Host and Path are normally mandatory parameters. However, if you already utilized GET_FILESYSTEM earlier in the script, you can omit them; the system will simply reuse the cached values from the preceding call.

The following example demonstrates this logic. The first call calculates the file count in C:\Temp (e.g., 50 files). If files are deleted shortly after, the second call still supplies the cached value of 50 because the Host and Path were omitted. The third call formally specifies the Host and Path again, forcing the system to recalculate and supply the updated, reduced file count.

:SET &NumberFiles# = GET_FILESYSTEM(WIN01, "C:\Temp", PATH_FILE_COUNT)

!several script lines

:SET &NumberFolders# = GET_FILESYSTEM(,, PATH_FOLDER_COUNT)

!several script lines

:SET &NumberFiles# = GET_FILESYSTEM(WIN01, "C:\Temp", PATH_FILE_COUNT)

Platform-specific Considerations

Be aware of the following platform-specific file system details and nuances:

BS2000: Allocated and used disk space can distinctly differ. For example, 1000 PAM pages might be reserved, but the actual file content might only consume 100 PAM pages.
OS/400: You must explicitly specify a library and a file to obtain valid file system values.
z/OS:
- PATH_SPACE_ALLOCATED: Cannot be retrieved; returns the used disk space instead.
- PATH_SPACE_USED: Returns used disk spaces.
- PATH_SPACE_UNUSED: Always returns zero because it calculates the difference between PATH_SPACE_ALLOCATED and PATH_SPACE_USED.
- GDGs: If a Generation Data Group name is indicated, the script exclusively retrieves PATH_SPACE_USED and PATH_FILE_COUNT.
UNIX and VMS:
- PATH_FILE_COUNT: Number of files.
- PATH_FOLDER_COUNT: Number of folders.
- PATH_SPACE_USED: Sum of file sizes in the specified path.
- PATH_SPACE_TOTAL: Supplies the exact same results as PATH_SPACE_USED and PATH_SPACE_ALLOCATED.

Examples

The following example uses the GET_FILESYSTEM script function to evaluate the total number of existing files and dispatches a corresponding message. This abstract illustrates script usage inside an event, where omitting the Host and Path parameters is permitted because they are inherently known by the event context:

:SET &NUMBER# = GET_FILESYSTEM(,,PATH_FILE_COUNT)

:SEND_MSG "BROWN", "IT", "&NUMBER# files are available for processing."

The next example executes GET_FILESYSTEM within a job's Process page. It actively fetches all accessible drive storage details and prints them neatly into the activation report:

:SET &E1# = GET_FILESYSTEM(WIN01, "E:\\", FILESYSTEM_SPACE_TOTAL, MB)

:SET &E2# = GET_FILESYSTEM(,, FILESYSTEM_SPACE_USED, MB)

:SET &E3# = GET_FILESYSTEM(,, FILESYSTEM_SPACE_FREE, MB)

:PRINT "Memory capacity of the drive: &E1# MB"

:PRINT "Used drive space: &E2# MB"

:PRINT "Available space: &E3# MB"

The final examples reveal how to successfully execute this script function targeting Generation Data Groups (GDGs):

!Number of file generations of the group TEST.XXX

:SET &FILENAME# = GET_FILESYSTEM("MVSHOST", "TEST.XXX(*)", PATH_FILE_COUNT)

!Sum of the space used by the current generation

:SET &SPACE# = GET_FILESYSTEM("MVSHOST", "TEST.XXX(0)", PATH_SPACE_USED)