[Toc][Index]

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