| layout | sheet |
|---|---|
| title | BASIC Functions |
| permalink | /docs/bdman/cmd/basic/func/ |
{% include header.html %}
Functions can be used in any expression, in BASIC programs or at the prompt (eg, PRINT SQR(2)). Functions whose names end with $ return strings; all others return numbers.
- Numeric functions: ABS, ATN, CDBL, CINT, COS, CSNG, EXP, FIX, INT, LOG, RND, RND%, SGN, SIN, SQR, TAN
- String functions: ASC, CHR$, HEX$, INSTR, LCASE$, LEFT$, LEN, MID$, OCT$, RIGHT$, SPACE$, SPC, STR$, STRING$, TAB, UCASE$, VAL
- File functions: CVD, CVI, CVL, DIR$, EOF, EXISTS, LOC, LOF, MKD$, MKI$, MKL$
- System functions: ARG$, CSRLIN, CURDIR$, DATE$, DOS, ERL, ERR, FRE, INKEY$, MOUSE, PATH$, PEEK, POS, SCREEN, TIME$
- Predefined constants: ERRORLEVEL, MAXINT
You can also define your own functions with DEF.
The trigonometric functions use radians, and all floating-point calculations use 64-bit (double-precision) values, with about 15 significant digits. If floating-point support is disabled (see Starting BASIC-DOS), numeric variables default to integers, and / and ^ are integer operations.
ABS(x)
Returns the absolute value of x.
ATN(x)
Returns the arctangent of x, in radians (eg, 4*ATN(1) is pi).
CDBL(x)
CSNG(x)
Returns x as a double (since all floating-point values are double-precision, CSNG is the same as CDBL).
CINT(x)
Returns x rounded to an integer, the same way that assigning x to an integer variable rounds it (eg, CINT(2.6) is 3). Unlike Microsoft BASIC, the result is a 32-bit integer.
COS(x)
Returns the cosine of x, where x is in radians.
EXP(x)
Returns e (2.71828...) raised to the power of x.
FIX(x)
Returns x truncated to an integer (eg, FIX(-2.5) is -2). See also INT.
INT(x)
Returns the largest integer less than or equal to x (eg, INT(-2.5) is -3). See also FIX.
LOG(x)
Returns the natural logarithm of x, which must be greater than zero.
RND[(n)]
Returns a random number from 0 up to (but not including) 1. n has the same effect as with RND%.
RND%[(n)]
Returns a random integer between 0 and MAXINT, inclusive. If n is negative, the generator is reseeded first, and if n is zero, the previous random integer is returned.
SGN(x)
Returns -1 if x is negative, 0 if x is zero, or 1 if x is positive.
SIN(x)
Returns the sine of x, where x is in radians.
SQR(x)
Returns the square root of x, which must not be negative.
TAN(x)
Returns the tangent of x, where x is in radians.
Strings can contain up to 255 characters. Character positions start at 1.
ASC(string)
Returns the character code (0-255) of the first character of string. As in MSBASIC, an empty string is an "Illegal function call" error.
CHR$(code)
Returns a one-character string containing the character with the specified code (0-255).
HEX$(n)
Returns the hexadecimal representation of the integer n. Negative values are treated as unsigned 32-bit values (eg, HEX$(-1) is "FFFFFFFF").
INSTR([start,]string1,string2)
Returns the position of string2 within string1, searching from position start (default 1), or 0 if not found.
LCASE$(string)
Returns string with all upper-case letters converted to lower-case.
LEFT$(string,n)
Returns the leftmost n characters of string.
LEN(string)
Returns the number of characters in string (0-255).
MID$(string,start[,n])
Returns n characters of string, beginning at position start (or the rest of string if n is omitted). The MID$ statement (eg, MID$(A$,2) = "X") isn't supported yet.
OCT$(n)
Returns the octal representation of the integer n.
RIGHT$(string,n)
Returns the rightmost n characters of string.
SPACE$(n)
SPC(n)
Returns a string of n spaces. SPC is the same (eg, PRINT "A"; SPC(5); "B").
STR$(x)
Returns x as a string, with a leading space if x is not negative.
STRING$(n,char)
Returns a string of n copies of char, which can be either a character code or a string (whose first character is used).
TAB(n)
Returns enough spaces to move the cursor to column n (1-254), for PRINT (eg, PRINT "A"; TAB(10); "B"); if the cursor is already past column n, the spaces start on the next line.
UCASE$(string)
Returns string with all lower-case letters converted to upper-case.
VAL(string)
Returns the numeric value of string, ignoring any blanks. If string does not begin with a number, the result is 0. Like numeric constants, string can use the &H (hexadecimal) and &O (octal) prefixes; & alone also means octal (eg, VAL("&HFF") is 255, and VAL("&17") is 15). Without floating-point (eg, when the FPU$ driver isn't loaded; see MEM), the result is an integer (eg, VAL("3.9") is 3).
CVI(string)
CVL(string)
CVD(string)
Return the integer stored in the first 2 bytes of string by MKI$ (-32768 to 32767), the integer stored in the first 4 bytes by MKL$, or the double stored in the first 8 bytes by MKD$; a shorter string is an "Illegal function call" error. Use them to read numbers from random access files (see FIELD).
DIR$[(filespec[,attributes])]
Returns the first file or directory matching filespec (which may contain wildcards), or if filespec is omitted (or empty), the next match. An empty string means there are no (more) matches. The default attributes (&H16) include hidden, system, and directory entries; use &H10 to skip hidden and system files as DIR does, or 8 to find the volume label.
Each match is a string that contains the entry's directory information, followed by its name:
| Position | Length | Contents | Example |
|---|---|---|---|
| 1 | 1 | attributes | ASC(F$) (&H10 = directory) |
| 2 | 2 | time | CVI(MID$(F$,2)) |
| 4 | 2 | date | CVI(MID$(F$,4)) |
| 6 | 4 | size | CVL(MID$(F$,6)) |
| 10 | 1-12 | name | MID$(F$,10) |
The time and date are in PC DOS directory format (add 65536 to a negative value first): the hour is time \ 2048, the minute is (time \ 32) AND 63, the year is date \ 512 + 1980, the month is (date \ 32) AND 15, and the day is date AND 31. For example:
F$ = DIR$("*.BAS")
WHILE F$ <> "" : PRINT MID$(F$,10), CVL(MID$(F$,6)) : F$ = DIR$ : WEND
Commands that search for files (eg, DIR, or COPY, DEL, and TYPE with wildcards) start searches of their own, so call DIR$ with a filespec again after using one. The TESTS folder's DIR.BAS displays a listing like DIR's, using DIR$.
EOF(n)
Returns -1 (true) if file n, which must be open for INPUT or RANDOM (see OPEN), is at its end (or at a CTRL-Z), or 0 (false) if not (eg, WHILE NOT EOF(1)).
EXISTS(filespec)
Returns -1 (true) if a file or directory matching filespec exists, or 0 (false) if not; filespec may contain wildcards (eg, EXISTS("C:\SAMPLES\*.BAS")). For example, a batch file can create a directory only if it doesn't already exist:
IF NOT EXISTS("OBJ") THEN MD OBJ
PC DOS batch files use IF EXIST (and IF NOT EXIST) for the same purpose.
IOCTL$(n,code[,value])
Sends an IOCTL request with the specified code (and value in DX) to the device or volume open as file n (see the IOCTL # statement), and returns the data (up to 255 bytes) that the driver stored in response, or an empty string if it stored nothing. For example, FORMAT.BAS gets a hard disk's geometry and partition table with the hard disk driver's IOCTL_GETPART (&HF3) request, which the diskette driver answers with an empty string. Errors are the same as for IOCTL #.
LOC(n)
Returns the last record number used by GET # or PUT # for file n, or for a sequential file, its position divided by 128.
LOF(n)
Returns the size of file n, in bytes.
MKI$(n)
MKL$(n)
MKD$(x)
Return a 2-byte string containing the integer n (its low 16 bits), a 4-byte string containing n, or an 8-byte string containing the double x, for storing numbers in random access files (see LSET). Doubles are stored in IEEE format, not the MBF format used by Microsoft BASIC, so Microsoft BASIC files that contain MKS$ or MKD$ values can't be read with CVD (and MKS$ and CVS aren't supported).
ARG$[(n)]
Returns an argument from the command line that ran the current BAS or BAT file: ARG$(0) is the file's name (as typed), ARG$(1) is the first argument, and so on, and ARG$ alone returns all the arguments. Arguments are separated by spaces, and a quoted argument (eg, "two words") can contain spaces; the quotes aren't included. The result is an empty string if there's no such argument, or if no BAS or BAT file is running (eg, at the prompt). A BAS or BAT file run by another one has its own arguments. For example, if SHOW.BAS contains:
PRINT ARG$(0); " has "; ARG$(1); " and "; ARG$(2)
then typing SHOW one "two three" displays SHOW has one and two three.
CSRLIN
Returns the cursor's row, starting at 1 (see POS and LOCATE).
CURDIR$
Returns the current drive and directory as a string, in the same form that CD displays (eg, C:\BASIC, or C:\ in the root directory). LEFT$(CURDIR$,1) is the current drive letter.
DATE$
Returns the current date as a string in the form MM-DD-YYYY.
DOS(n)
Returns register AX (n = 0), BX (1), CX (2), or DX (3), as DOS returned it to the last DOS statement, as a value from 0 to 65535. Any other n is an "Illegal function call". For example, after DOS &H3600, 0, 0, 0 (get disk info for the current drive), DOS(0) * DOS(1) * DOS(2) is the number of bytes free.
ERL
Returns the line number of the last error (see ON ERROR), or 0 if it occurred in a program without line numbers.
ERR
Returns the number of the last error (see ON ERROR).
FRE(x)
Compacts string memory and returns the number of bytes available, or if x is negative (eg, FRE(-1)), the number of bytes of memory owned by the current session (its command processor's memory blocks, including its program, variables, and strings). Other sessions can't change that amount, so it's useful for checking for memory leaks while other sessions are running.
INKEY$
Returns the next key pressed, without waiting (an empty string if no key was pressed). Extended keys (eg, cursor keys) return two characters: a null and the key's scan code.
10 LET K$ = INKEY$:IF K$ = "" THEN GOTO 10
PRINT "You pressed "; K$
MOUSE(n)
Returns the next mouse button event (n = 0), the position of that event (1 and 2), or the current position (3 and 4) or buttons (5). See MOUSE for details.
PATH$ PATH$ = string
Returns (or sets) the directories, separated by semicolons, that are searched for a program (or a file to LOAD) that isn't in the current directory (eg, PATH$ = "A:\;A:\BIN;A:\DEMOS;A:\SAMPLES"); see Running Programs. Unlike other variables, PATH$ keeps its value when variables are cleared (eg, by NEW or CLEAR), and each session has its own. It's usually set on a SHELL line in CONFIG.SYS, and it's limited to 120 characters.
PEEK(offset)
Returns the byte at offset in the segment set by DEF SEG. For example, this returns the low byte of the BIOS timer tick count:
DEF SEG=0:PRINT PEEK(&H46C)
POS(n)
Returns the cursor's column, starting at 1 (n is ignored).
SCREEN(row,col[,z])
Returns the character code at row and col (starting at 1), or if z is non-zero, its attributes (eg, SCREEN(1,1,1) returns 7 for a white-on-black character). A position outside the console is an illegal function call. For the SCREEN statement, see SCREEN.
TIME$
Returns the current time as a string in the form HH:MM:SS.
Equal to the return code from the last program executed, or for an internal command (eg, COPY or DEL), 0 if it succeeded or 1 if it failed (eg, IF ERRORLEVEL THEN PRINT "Failed").
Equal to the largest positive integer (2147483647).
{% include footer.html prev="RETURN:../return/" next="Device Commands:../../device/" %}