Syntax

diskspace logical-name[=path] [qty=nnn{b|k|m|g}] [cond={GT|LT}]

Description

The diskspace command retrieves the amount of space available on a volume or file system.

UDM executes the command on the system identified by the logical-name parameter. This parameter must match a logical name specified in the open command. Use "local" to refer to the primary server session in a two-party transfer.

To retrieve the available space for an entire volume or file system, simply specify any directory path that exists there. If no path is specified, UDM uses the current working directory to determine which device to check.

Whenever UDM executes the diskspace command, it stores the number of available bytes in the _diskspace built-in variable. The .kb, .mb, and .gb attributes provide access to the available quantity in kilobytes, megabytes, or gigabytes. For example, the amount of available space in megabytes is accessed using $(_diskspace.mb).

While the $(_diskspace) variable may be used in calculations and evaluations, the diskspace command provides the optional qty and cond parameters to quickly test whether the amount of available space is more or less than a specified quantity. UDM sets the _lastrc built-in variable to 0 (zero) if the result of the test evaluates to true. UDM sets $(_lastrc.result) to a non-zero value when the test evaluates to false.

The amount of space that the diskspace command will check for is specified with the qty parameter. The quantity can be expressed in terms of bytes, kilobytes, megabytes and gigabytes. If no unit is specified, the default is bytes.

The optional cond parameter specifies whether the diskspace command will test for available space that is greater than (GT, the default) or less than (LT) the specified quantity (qty).

If the test succeeds, diskspace sets $(_lastrc.result) to 0 (zero) and $(_lastrc.message) to "SUCCESS". If the test fails, diskspace sets $(_lastrc.result) to non-zero and $(_lastrc.message) to "ERROR".

For example, given a diskspace command where qty=100m and cond=GT, UDM sets $(_lastrc.result) to 0 (zero) if more than 100 megabtyes (MB) of space is available. If exactly 100MB or less is available, then $(_lastrc.result) is set to a non-zero value. Conversely, if qty=100m and cond=LT, UDM sets $(_lastrc.result) to 0 only when there is less than 100MB space available.

Parameters

Parameter	Description
logical_name	Name of the system where UDM checks available space. If path is specified, diskspace checks the volume or file system where that directory resides. Otherwise, the current working directory is used. Note On z/OS and IBM i, the current file system must be set to HFS (see the filesys command).
qty	Amount of space that diskspace should look for. To specify a unit for the quantity, add one of the following letters to the quantity amount: b - bytes k - kilobytes (1,024 bytes) m - megabytes (1,048,576 bytes) g - gigabytes (1,073,741,824 bytes) If no unit is specified, the default (b - bytes) is used. If no quantity is specified, diskspace displays the available space.
cond	Instructs diskspace to check for an amount that is greater than (GT) or less than (LT) the specified quantity. This parameter is optional. If no condition is specified, GT is used.

Examples

The following example displays the amount of space available on the volume or file system that contains the directory c:\somedir.

The following example verifies that the available space for the volume or file system that contains the current working directory is greater than 10GB.

The statements below repeat the previous example using the $(_diskspace) built-in variable with the .gb attribute.

The following example uses diskspace in the context of a forfiles statement, using the file's size in the comparison.

The statements below repeat the previous example using the $(_diskspace) built-in variable. The if statement only allows the file copy if the number of bytes available on c: is greater than the size of the input file.

The following example uses diskspace in the context of a forfiles loop, using the total size of several files to determine the quantity of space needed.

The statements below repeat the previous example using the $(_diskspace) built-in variable.

The following example would prevent a copy if the available space for the volume or file system that contains the specified directory is less than 20MB.