Variable Functions
Variable functions are like internal variables, but they take one or more
arguments (which can be environment variables or even other variable
functions) and they return a value.
The list below gives a one-line description of each function, and a
cross-reference which selects a full screen help topic on that function.
A few of the variables are simple enough that the one-line description is
sufficient, but in most cases you should check for any additional
information in the cross-reference topic if you are not already familiar
with a function. You can also obtain help on any function with a HELP
@functionname command at the prompt.
See the discussion after the function list for some additional
information, and examples of how the functions can be used. For
additional examples, see the EXAMPLES.BTM file which came with CMD.EXE.
The variable functions are:
System status
@DOSMEM[b|k|m] Size of largest free memory
block
@READSCR[row,col,len] Read characters from the
screen
Drives and devices
@CDROM[d:] CD-ROM drive detection (0 or
1)
@DEVICE[name] Character device detection
@DISKFREE[d:,b|k|m] Free disk space
@DISKTOTAL[d:,b|k|m] Total disk space
@DISKUSED[d:,b|k|m] Used disk space
@FSTYPE[d:] File system type (FAT, HPFS,
CDFS, etc.)
@LABEL[d:] Volume label
@READY[d:] Drive ready status (0 or 1)
@REMOTE[d:] Remote (network) drive
detection (0 or 1)
@REMOVABLE[d:] Removable drive detection (0
or 1)
Files
@ATTRIB[filename [,-nrhsda]] File attribute test (0 or 1)
@DESCRIPT[filename] File description
@EAREAD[filename,EAname] Read extended attribute
@EAWRITE[filename,EAname,[value]] Write extended attribute
@EXETYPE[filename] Executable file type (DOS, PM,
WIN, etc.)
@FILEAGE[filename[,acw]] File age (date and time)
@FILECLOSE[n] Close a file
@FILEDATE[filename[,acw]] File date
@FILEOPEN[filename,mode] Open a file
@FILEREAD[n [,length]] Read next line from a file
@FILES[filename [,-nrhsda]] Count files matching a
wildcard
@FILESEEK[n,offset,start] Move a file pointer to an
offset
@FILESEEKL[n,offset,start] Move a file pointer to a line
number
@FILESIZE[filename,b|k|m] Size of files matching a
wildcard
@FILETIME[filename[,acw]] File time
@FILEWRITE[n,text] Write next line to a file
@FILEWRITEB[n,length,string] Write bytes from a string to a
file
@FINDCLOSE[filename] Close the search handle opened
by @FINDFIRST
@FINDFIRST[filename [,-nrhsda]] Find first matching file
@FINDNEXT[filename [,-nrhsda]] Find next matching file
@LINE[filename,n] Read a random line from a file
@LINES[filename] Count lines in a file
@SEARCH[filename] Path search
@UNIQUE[d:\path] Create file with unique name
File names
@EXPAND[filename [,-nrhsda]] Names of all matching files
and directories
@EXT[filename] File extension
@FILENAME[filename] File name and extension
@FULL[filename] Full file name with path
@NAME[filename] File name without path or
extension
@PATH[filename] File path without name
Strings and characters
@ASCII[c] Numeric ASCII value for a
character
@CHAR[n] Character value for numeric
ASCII
@FORMAT[[-][x][.y],string] Formats (justifies) a string
@INDEX[string1,string2] Position of one string in
another
@INSERT[n,string1,string2] Insert one string into another
@INSTR[start,length,string] Extract a substring
@LEFT[n,string] Leftmost characters of a
string
@LEN[string] Length of a string
@LOWER[string] Convert string to lower case
@REPEAT[c,n] Repeat a character
@REPLACE[string1,string2,text] Replace all occurrences of one
string with another
@RIGHT[n,string] Rightmost characters of a
string
@STRIP[chars,string] Remove characters from string
@SUBSTR[string,start,length] Extract a substring
@TRIM[string] Remove blanks from a string
@UPPER[string] Convert string to upper case
@WILD[string1,string2] Wildcard comparison
@WORD[["sep",] n,string] Extract a word from a string
@WORDS[["sep",] string] Counts number of words in a
string
Numbers and arithmetic
@COMMA[n] Inserts commas in a number
@CONVERT[input,output,value] Base conversion
@DEC[%var] Decremented value of a
variable
@EVAL[expression] Arithmetic calculations
@INC[%var] Incremented value of a
variable
@INT[n] Integer part of a number
@NUMERIC[string] Test if a string is numeric
@RANDOM[min,max] Generate a random integer
Dates and times
@DATE[mm-dd-yy] Convert date to number of days
@DAY[mm-dd-yy] Day of the month
@DOW[mm-dd-yy] Day of the week
@DOWI[mm-dd-yy] Numeric day of the week
@DOY[mm-dd-yy] Numeric day of the year
@MAKEAGE[n] Convert date/time to file
date/time
@MAKEDATE[n] Convert number of days to date
@MAKETIME[n] Convert number of seconds to
time
@MONTH[mm-dd-yy] Month of the year
@TIME[hh:mm:ss] Convert time to number of
seconds
@TIMER[n] Elapsed time of specified
timer
@YEAR[mm-dd-yy] Year number (2 digits)
Utility
@ALIAS[name] Value of an alias
@CLIP[n] Line from the clipboard
@IF[condition,true,false] Evaluates a test condition
@EXEC[command] Execute a command
@EXECSTR[command] Execute, return string
@REXX[expr] Execute a REXX expression
@SELECT[file,t,l,b,r,title] Menu selection
Additional Notes
Like all environment variables, these variable functions must be preceded
by a percent sign (%@EVAL, %@LEN, etc.). All variable functions must
have square brackets enclosing their argument(s). The argument(s) to a
variable function cannot exceed 255 characters in length for all
arguments taken as a group.
Specific Functions and Arguments
Some variable functions, like @DISKFREE, are shown with "b|k|m" as one of
their arguments. Those functions return a number of bytes, kilobytes, or
megabytes based on the "b|k|m" argument:
b return the number of bytes
K return the number of kilobytes (bytes / 1,024)
k return the number of thousands of bytes (bytes / 1,000)
M return the number of megabytes (bytes / 1,048,576)
m return the number of millions of bytes (bytes / 1,000,000)
You can include commas (or the "thousands separator" character for your
system) in the results from a "b|k|m" function by appending a "c" to the
argument. For example, to add commas to a "b" or number of bytes result,
enter "bc" as the argument. To set the thousands separator see the
ThousandsChar directive.
Functions which accept a date as an argument use the date format and
separators mandated by your country code (for example dd.mm.yy in
Germany, or yy-mm-dd in Japan). The year can be entered as a 4-digit or
2-digit value. Two-digit years between 80 and 99 are interpreted as 1980
- 1999; values between 00 and 79 are interpreted as 2000 - 2079.
Several functions return filenames or parts of filenames. On an HPFS
drive the strings returned by these functions may contain whitespace 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 any whitespace or special characters in the name
properly.
In variable functions which take a drive letter as an argument, 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.
The @FILEREAD, @FILEWRITE, @FILEWRITEB, @FILESEEK, @FILESEEKL, and
@FILECLOSE functions allow you to access files based on their file
handle. These functions should only be used with file handles returned
by @FILEOPEN! If you use them with any other file handle you may damage
other files opened by CMD.EXE (or, in a secondary shell, the program
which started CMD.EXE), or hang your system.
Many functions return values based on information provided by your
operating system. Such functions will only return correct information if
the operating system provides it. For example, @READY will not return
accurate results if your operating system does not provide correct disk
drive status information to the command processor.
Examples
You can use variable functions in a wide variety of ways depending on
your needs. We've included a few examples below to give you an idea of
what's possible. For additional examples, see the EXAMPLES.BTM file
which came with CMD.EXE.
To set the prompt to show the amount of free memory (see PROMPT for
details on including variable functions in your prompt):
[c:\] prompt (%%@dosmem[K]K) $p$g
Set up a simple command-line calculator. The calculator is used with a
command like CALC 3 * (4 + 5):
[c:\] alias calc `echo The answer is: %@eval[%&]`
The following batch file uses variable functions to implement "once a
day" execution of a group of commands. It works by constructing a
6-digit number "yymmdd" from today's date, and comparing that to a number
of the same type stored in the file C:\ONCEADAY.DAT. If today's date is
numerically larger than the saved date, and the time is after 6:00 AM,
then the "once a day" commands are run, and today's date is saved in the
file as the new date for comparison. Otherwise, no action is taken. You
can make this file simpler using the %@DATE and %@TIME functions instead
of using %@INSTR to extract substrings of the %_DATE and %_TIME
variables; we used the approach shown to demonstrate the use of %@INSTR.
rem Temporary variables used to shorten example lines:
rem DD is _date, DY is yymmdd date, TM is _time
set dd=%_date
set dy=%@instr[6,2,%dd]%@instr[0,2,%dd]%@instr[3,2,%dd]
set lastdate=0
iff exist c:\onceaday.dat then
set lastdate=%@line[onceaday.dat,0]
endiff
iff %dy gt %lastdate then
set tm=%_time
iff "%@instr[0,2,%tm]%@instr[3,2,%tm]" gt "0600" then
rem Commands to be executed once a day go here
echo %dy > c:\onceaday.dat
endiff
endiff
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs