GET_FILESYSTEM

Use the GET_FILESYSTEM script function to retrieve several values from a file system of a computer starting at a defined path. This script element is only available for OS agents such as Windows, UNIX, VMS, z/OS, OS/400, NSK and BS2000.

Important!

Make sure that you have access rights to system folders (system volume information, Windows). Missing rights result in code 0.
This script statement causes all open transactions of the script to be written 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

GET_FILESYSTEM
Retrieves several values from a file system of a host
Host
(Optional) Name of the agent that runs on the host whose information should be retrieved
Format: AE name, script literal or script variable
Tip: If you do not specify the host name, the agent that you have last used with the GET_FILESYSTEM script function is used. Instead of retrieving the values from the agent again, the result values from the previous call are used. In doing so, you can increase performance because the data is already available. For details, see the examples in Using the Optional Parameters Host and Path
Path
(Optional) Description of files or file systems whose information should be supplied.
You can name files, drives, volumes, paths, Generation Data Groups, or the like, depending on the respective system. The * or ? wildcard characters can be used. * indicates any number of characters, ? stands for exactly one character.
Important! (Windows) You can use the * and ? wildcard characters for the file names. You cannot use them for directories within the path.
Format: AE name, script literal or script variable
Notes:
- End path specifications on Windows with a backslash and a * wildcard character.
  Example: C:\AUTOMIC\*
  Use script functions to define actions that should be taken when errors occur such as sending an error message if the path does not exist. For more information, see Script Elements for Error Handling
- The prefix VOL= is required if you set one or more volumes.
  Example: VOL=ALG*1 supplies information about all volumes that start with the letter combination ALG and end on 1. Any number of characters can come in between. Our example is limited to 4 characters of your choice because the complete name of a volume consists of 8 characters.
- If you name Generation Data Groups, enclose the * character in parentheses. For more information, see Generation Data Group (GDG) Support
File System Value
You can retrieve the following information:
- PATH_SPACE_ALLOCATED
  Allocated memory or hard drive space
- PATH_SPACE_RELEASE
  (BS2000) Releasable memory
- PATH_SPACE_USED
  Sum of file sizes in the specified path
  (z/OS) The data set size that is returned might be inaccurate when the data set resides on EAV (Extended Address Volumes)
- PATH_SPACE_UNUSED
  (BS2000) Unused memory or hard drive space
- PATH_FILE_COUNT
  Number of files
  Tip: If you use PATH_FILE_COUNT, this script function can return 0 when the directory does not contain any files. Therefore, you can also use the script functions for error handling such as SYS_LAST_ERR_NR. Errors, such as the host is not active, can be detected and you can distinguish whether return code 0 refers to the file number or an error.
- PATH_FOLDER_COUNT
  (Windows, UNIX and OS/400) Number of folders
- FILESYSTEM_SPACE_TOTAL
  (Windows and OS/400) Total memory 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
Format: AE name, script literal or script variable
Unit
(Optional) Specify the form in which a file system value should be returned.
Return code: If this parameter is not defined, the return code is determined by the host (default). For example, A BS2000 computer returns the value 1 for 1 PAM page. This value corresponds to 2048 bytes.
If this parameter is defined, the return code is calculated in the specified format. Allowed formats are bytes, KB, MB, GB, and TB.

Format: AE name, script literal or script variable
Note: If you define an invalid value for the unit, the default value is used. Therefore, this script function does not abort when you use the :ON_ERROR script statement. For more information, see :ON_ERROR.
Include sub-directories
(Optional) Specifies whether the sub-directories of the specified path should be searched. This parameter is only effective for VMS, UNIX and Windows agents.
Allowed values: Y (default) and N
Important! Activating this option affects the performance of your AE system.
Login object
(Optional) Name of the predefined Login object which transfers the login data for the FILE Event object.

Return Codes

The script function shows the result of the searched file system value in its return code.

0
An error occurred while retrieving the file system value. For example, the path cannot be found. An exception is PATH_FILE_COUNT, see the parameter description)

Tip: Use the :ON_ERROR script statement to define actions that should be taken in case of an error. For more information, see Script Elements for Error Handling.

Using the Optional Parameters Host and Path

Example 1

When a FILE Event occurs, you can use the GET_FILESYSTEM script function to retrieve information about the file system, memory, and drive space. All information is received from the agent and you can query each item separately with the indication of the File System Value. In this case, you use this script function without the Host and Path parameters as they are already defined in the Details pane of the event.

Example 2

You can use GET_FILESYSTEM in the Process pages of all executable objects, such as Workflows. For more information, see Process Pages and Object Types

Host and Path are always required, except when GET_FILESYSTEM was already used in the script. In this case, the value that is returned is the same as in the last call.

The example shows that the first call for GET_FILESYSTEM supplies the number of files that were found in the C:\Temp directory (for example, 50). If some of these files are now deleted, this script function still supplies value 50 because you do not specify Host and Path. The third call finally recalculates the File System Value and supplies a reduced number of files.

: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

The following file system values and information apply to specific platforms only.

BS2000
Only in BS2000, allocated and used disk space can differ from each other. 1000 PAM pages can be reserved, for example. The actual file content, however, can still only be 100 PAM pages.
OS/400
Always specify a library and a file to obtain valid file system values.
z/OS
- PATH_SPACE_ALLOCATED
  The allotted disk space in z/OS cannot be retrieved. Returns used disk space.
- PATH_SPACE_USED
  Used disk spaces
- PATH_SPACE_UNUSED
  This parameter is always zero because the value is the difference between PATH_SPACE_ALLOCATED and PATH_SPACE_USED.
If a GDG name is indicated, the script function retrieves the following file system values: PATH_SPACE_USED and PATH_FILE_COUNT.
Other operating systems such as 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 same results as PATH_SPACE_USED and PATH_SPACE_ALLOCATED.

Examples

The following example uses the GET_FILESYSTEM script function to retrieve the number of all existing files, and to send a corresponding message. The example is an abstract of a script that is used in an event which you know because the Host and Path parameters are not specified.

:SET &NUMBER# = GET_FILESYSTEM(,,PATH_FILE_COUNT)
:SEND_MSG "BROWN","IT","&NUMBER# files are available for processing."

The next example uses the GET_FILESYSTEM script function in the Process page of a job. All available information about the drive is retrieved and written to 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 following examples show how you can use this script function with GDG:

!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)