GET_FILESYSTEM

Script Function: Retrieves several file-system values from a computer starting at a defined path.

Syntax

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

Syntax	Description/Format
Host	The name of the agent that runs on the computer of which the information should be retrieved. Format: AE name, script literal or script variable Note: The agent that has last been used with the script function GET_FILESYSTEM is used if no host name is specified. The values that have been retrieved with the last call are used.
Path	The description of files or file systems for which information should be supplied. Files, drives, volumes, paths, Generation Data Groups etc. can be named here, depending on the respective system. The wildcard characters "" or "?" can be used. "" indicates any number of characters, "?" stands for exactly one character. Warning! Note that Windows only allows using the wildcard characters "" and "?" for the file names. You cannot use them for directories within the path. The characters and ? are always used as wildcard characters. Note that you cannot use them to define specific files that include these characters in their names. Format: AE name, script literal or script variable. Note: The path name last used with the script function GET_FILESYSTEM is used if no path name is specified. The values retrieved with the last call are used. Note: End path specifications on Windows with a "\". Use script functions to define actions to take when errors occur, such as sending an error message if the path does not exist. For more information, see Script Elements for Error Handling. Example:* C:\AUTOMIC\* Note: The prefix "VOL=" is required if one or more volumes are indicated. Example: "VOL=ALG1" supplies information about all volumes starting with the letters "ALG" and ending on "1". Any number of characters can come in between. In our example, we are limited to 4 characters of your choice because the complete name of a volume consists of 8 characters. Note:* When naming Generation Data Groups, enclose the wildcard character * in parentheses. For more information, see GDG Support.
File System Value	The following information can be retrieved using this script function: PATH_SPACE_ALLOCATED - The allocated memory or hard drive space. PATH_SPACE_RELEASE - The releasable memory (BS2000 only). PATH_SPACE_USED - The sum of file sizes in the in the specified path. PATH_SPACE_UNUSED - The unused memory or hard drive space (BS2000 only). PATH_FILE_COUNT - The number of files. PATH_FOLDER_COUNT - The number of folders (Windows, UNIX and OS/400 only). FILESYSTEM_SPACE_TOTAL - The total memory of the hard drive (Windows and OS/400 only). FILESYSTEM_SPACE_USED - Used memory (Windows and OS/400 only). FILESYSTEM_SPACE_FREE - Free memory of the volume (z/OS, OS/400) or drive (Windows). Format: AE name, script literal or script variable
Unit	You can specify the form in which a file-system value should be returned. Without a definition of Unit, the return code is determined by the host (default). A BS2000 computer returns the value "1" for 1 PAM page, for example. This corresponds to 2048 bytes. With a definition of Unit, the return code is converted as specified. Permitted values: "Bytes", "KB", "MB", "GB" or "TB". Format: AE name, script literal or script variable Note: The default value is used if an invalid unit has been specified. Therefore, this script function will not abort if you use the :ON_ERROR script statement. For more information, see :ON_ERROR.
Include sub-directories	The specification whether the sub-directories of the specified path should be searched. Allowed values: "Y" (default) and "N" This parameter is only effective for VMS, UNIX and Windows agents. Warning! Note that activating this option affects the performance of your AE system.
Login object	Name of the previously defined Login object; serves to enable transfer of login data for the File-System Event object. (optional)

Return Codes
Result of the searched file-system value. "0" - An error occurred while retrieving the file-system value (exception: PATH_FILE_COUNT, see below)

Warning! This script element can only be used with OS agents (Windows, UNIX, VMS, z/OS, OS/400, NSK and BS2000).

The return code of this function is zero if an error occurs while accessing information about the file system (such as path not found).

Tip: Use the :ON_ERROR script statement to define action to take in case of an error. For more information, see Script Elements for Error Handling.

Warning! If you use this script function with PATH_FILE_COUNT, it can return 0 when the directory does not contain any files. Therefore, additionally use the script functions for error handling (such as SYS_LAST_ERR_NR). Errors (such as host is not active) can so be detected and it is possible to distinguish whether return code 0 refers to the file number or an error.

Warning! In z/OS, the data set size returned (PATH_SPACE_USED) might be inaccurate if the data set resides on EAV (Extended Address Volumes).

Warning! Missing access rights to system folders (System Volume Information, Windows) also result in return code 0.

Note: The script statement causes all open transactions of the script to be written to the AE database. For more information, see Script Processing.

Optional Parameters Host and Path

Examples

When a FILE Event occurs, the script function GET_FILESYSTEM can be used to retrieve information about the file system, memory and drive space. All information is transferred to the agent. Each item can then be queried separately with the indication of the File System Value. In this case, the script function is called without the indication of Host and Path as these parameters have already been defined in the event's Detail tab.

GET_FILESYSTEM can be used in the Process tabs of all executable objects, such as Workflows. For more information, see Process Pages and Objects.

Host and Path are always required when calling this script function. These parameters can only be omitted if GET_FILESYSTEM was already called in the script. In such a case, the returned value remains the same as in the last call.

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

The first call for GET_FILESYSTEM supplies the number of files found in the directory C:\Temp (such as 50). If some of these files are now being deleted, this script function still supplies value 50. The third call finally re-calculates the file-system values and supplies a reduced number of files.

Platform-specific Considerations

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

OS/400
Always specify a library and a file in order 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 - It 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.
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.
Other operating systems such as UNIX and VMS
- PATH_FILE_COUNT - The number of files.
- PATH_FOLDER_COUNT - The number of folders.
- PATH_SPACE_USED - The sum of file sizes in the specified path.
- PATH_SPACE_TOTAL - It supplies the same results as PATH_SPACE_USED and PATH_SPACE_ALLOCATED.

Examples

In the following example, the script function GET_FILESYSTEM is used to retrieve the number of all existing files and to send a corresponding message. It is an abstract of an event's script which can be seen from the fact that the first two 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 script function GET_FILESYSTEM in a job's script. 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 the script function is used 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)