Variable functions are very similar to internal variables, but they take one or more parameters (which can be environment variables or even other variable functions).

 

Variable functions are useful at the command prompt as well as in aliases and batch files to check on available system resources, manipulate strings and numbers, and work with files and filenames.

 

The variable functions built into TCC are listed in alphabetical order in subsequent topics. You can also obtain help from the command prompt on any function with a HELP @functionname  command, or by pressing Ctrl-F1 when the cursor is on the function name. See the HELP command for details

 

Note: The FUNCTION command can be used to create, edit, or display user-defined variable functions, and the UNFUNCTION to delete them.

 

For a list of Variable Functions organized by general categories of use, see Variable Functions by Category.

 

Syntax

 

To have either a user-defined or a built-in variable function evaluated, its name must be preceded by a percent sign % (%@EVAL, %@LEN, etc.). All variable functions must have square brackets [ ] enclosing their parameter(s), if any. No space is allowed between the function name and the [.

 

Memory Size / Disk Space / File Size Units and Report Format

 

Some variable functions, such as @DISKFREE, accept an optional parameter scale code. These functions return a size of a disk or of an entity on the disk as a multiple of the specified scale factor from the table below. Lower case letters denote a power of 1,000, upper case letters a power of 1,024.

 

 

Code

Scale Factor

Code

Scale Factor

Unit Name

b

1

 

B

1

 

byte

k

1,000

10**3

K

1,024

2**10

kilobyte

m

1,000,000

10**6

M

1,048,576

2**20

megabyte

g

1,000,000,000

10**9

G

1,073,741,824

2**30

gigabyte

t

1,000,000,000,000

10**12

T

1,099,511,627,776

2**40

terabyte

p

1,000,000,000,000,000

10**15

P

1,125,899,906,842,624

2**50

petabyte

e

1,000,000,000,000,000,000

10**18

E

1,152,921,504,606,846,976

2**60

exabyte

 

 

You can include commas (or the thousands separator) in the value returned from a  function by appending the letter c to the  scale code. For example, to add commas to a b (number of bytes) result, enter bc as the parameter, i.e.:

 

echo %@DISKFREE[C,bc]

 

Notes

 

1)Disk manufacturers use the prefixes adopted from the metric system (kilo, mega, giga, tera) in their original meaning (powers of 1,000), while memory manufacturers and Microsoft use the slightly larger powers of 1,024 (2**10).

 

2)The scale code is one of the few instances in which TCC is case sensitive.

 

Date Parameter Format

 

See the Date Formats topic.

 

File Name Parameters

 

Filenames passed as variable function parameters must be enclosed in double quotes if they contain white space or special characters. Several functions also return filenames or parts of filenames. On LFN drives, the strings returned by these functions may contain white space or other special characters. To avoid problems which could be caused by these characters, quote the returned name before you pass it to other commands. For example (either of these methods would work):

 

set fname="%@findfirst[pro*]"

echo First PRO file contains:

type %fname

.....

set fname=%@findfirst[pro*]

echo First PRO file contains:

type "%fname"

.....

 

If you don't use the quotes in the SET or TYPE command in this example, TYPE will not interpret white space or special characters in the name properly.

 

Drive Letter Parameters

 

In variable functions which take a drive letter as a parameter, like @DISKFREE or @READY, the drive letter must be followed by a colon. The function will not work properly if you use the drive letter without the colon.

 

Functions Accessing File Handles

 

The @FILEREAD, @FILEWRITE, @FILEWRITEB, @FILESEEK, @FILESEEKL, and @FILECLOSE functions allow you to access files based on their file handle. These functions must be used only with file handles returned by @FILEOPEN, unless otherwise noted under the individual functions. If you use them with any other file handle you may damage files.

 

File Attributes

 

Several  functions accept a file attribute string to help determine which files to process. The rules for constructing the attribute string are the same as the ones for Attribute Switches in commands.

 

Examples

 

You can use variable functions in a wide variety of ways depending on your needs. Here are a couple of examples to give you an idea of what's possible:

 

The command below sets the prompt to show the amount of free memory (see PROMPT for details on including variable functions in your prompt):

 

prompt (%%@dosmem[K]K) $p$g

 

Set up a simple command line calculator. The calculator is used with a command such as CALC 3 * (4 + 5):

 

alias calc `echo The answer is:  %@eval[%$]`