SECTION 18The format of the function description is: FUNCTION(argument)where the argument can be a numeric value, variable or string. Each function description is following by an example. 18.1 ABSReturn absolute value. ABS(x) The absolute value function returns the positive value of the argument. EXAMPLE:PRINT ABS(7*(-5)) 35 18.2 ASCReturn CBM ASCII code for character. ASC(x$) This function returns the ASCII code for the first character of x$. In C128 mode you no longer have to append CHR$(0) to a null string; ILLEGAL QUANTITY ERROR is no longer issued. EXAMPLE:X$="C128":PRINTASC(X$) 67 18.3 ATNReturn angle whose tangent is X radians. ATN(x) This function returns the angle whose tangent is x, measured in radians. EXAMPLE:PRINT ATN(3) 1.24904577 18.4 BUMPReturn sprite collision information. BUMP(n) To determine which sprites have collided since the last check, use the BUMP function. BUMP(1) records which sprites have collided with each other and BUMP(2) records which sprites have collided with other objects on the screen. COLLISION need not be active to use BUMP. The bit positions (0-7) in the BUMP value correspond to sprites 1 through 8 respectively. BUMP(n) is reset to zero after each call. The value returned by BUMP is the result of two raised to the power of the bit position. Remember bit position range from zero to seven, so a bit position corresponds to the sprite number - 1. For example, if BUMP returned a value of 16, sprite 5 was involved since 2 raised to the power (5 minus 1) equals 16. EXAMPLES:
18.5 CHR$Return ASCII character for specified CBM ASCII code. CHR$(x) This is the opposite of ASC and returns the string character whose CBM ASCII code is x. Refer to Appendix E for a table of CHR$ codes. EXAMPLES:
18.6 COSReturn cosine of angle of x radians. COS(x)This function returns the value of the cosine of x, where x is an angle measured in radians. EXAMPLE:PRINT COS({pi}) -1 18.7 DECReturn decimal value of hexadecimal number string. DEC(hexadecimal-string)This function returns the decimal value of hexadecimal-string. EXAMPLES:PRINT DEC("D020") 53280 F$="F":PRINT DEC(F$) 15 18.8 ERR$Return the string describing an error condition. ERR$(n)This function returns a string describing an error condition. Also see system variables EL and ER, in paragraph 19.1, and Appendix A for a list of BASIC error messages. EXAMPLE:PRINT ERR$(10) NEXT WITHOUT FOR 18.9 EXPReturn value of an approximation of e (2.7182813) raised to the power x. EXP(x)This function returns a value of e (2.7182813) raised to the power x. EXAMPLE:PRINT EXP(1) 2.7182813 18.10 FNxxReturn value from user defined function. FNxx(x)This function returns the value from the user-defined function xx created by a DEF FNxx statement. EXAMPLE:
18.11 FREReturn number of available bytes in memory. FRE(x)Where x is the bank number. x=0 BASIC program storage, and x=1 to check for available BASIC variable storage. EXAMPLES:PRINT FRE(0) 48893Returns the number of free bytes for BASIC programs. PRINT FRE(1) 64256Returns the number of free bytes for BASIC variable storage. 18.12 HEX$Return hexadecimal number string from decimal number. HEX$(x)This function returns a four-character string containing the hexadecimal representation of value x (0 <= x < 65536). The decimal counterpart of this function is DEC. EXAMPLE:PRINT HEX$(53280) D020 NOTE: HEX$(0) is "0000". 18.13 INSTRReturn position of string 1 in string 2. INSTR(string 1, string 2 [, starting position])The INSTR function searches for the first occurrance of string 2 within string 1, and returns the position within string 1 where the match is found. The optional parameter for starting position establishes the position in string 1 where the search begins. The starting position must be in the range of 1 through 255. If no match is found or, if starting position is greater than the length of string 1 or if string 1 is null, INSTR returns the value 0. If string 2 is null, INSTR returns 0. EXAMPLE:PRINT INSTR("COMMODORE 128","128") 11 18.14 INTReturn integer form (whole number part) of a floating point value. INT(x)This function returns the integer value of the expression. If the expression is positive, the fractional part is left out. If the expression is negative, any fraction causes the next lower integer to be returned. EXAMPLES:PRINT INT(3.14) 3 PRINT INT(-3.14) -4 18.15 JOYReturn position of joystick and the status of the fire button. JOY(n)where n equals:
1 8 2 7 0 3 6 4 5 EXAMPLES:JOY(2) is 135When joystick 2 fires and goes to the left. IF (JOY(1) AND 128) = 128 THEN PRINT "FIRE"Determines whether the fire button of joystick 1 is pressed. 18.16 LEFT$Return the leftmost characters of string. LEFT$(string, length)This function returns a string comprised of the number of leftmost characters of the string determined by the length argument. The length argument must be an integer in the range of 0 to 255. If this integer value is greater than the length of the string, the entire string is returned. If the value is equal to zero, then a null string (of zero length) is returned. EXAMPLE:PRINT LEFT$("COMMODORE",5) COMMO 18.17 LENReturn the length of a string. LEN(string)This function returns the number of characters in the string expression. Non-printable characters and blanks are included. EXAMPLE:PRINT LEN("COMMODORE128") 12 18.18 LOGReturn natural log of x. LOG(x)This function returns the natural log of x. The natural log is log to the base e (see EXP(x), in paragraph 18.9). To convert to log base 10, divide by LOG(10). EXAMPLE:PRINT LOG(37 / 5) 2.00148 18.19 MID$Return a substring from a larger string or overlay a substring into a larger string. MID$(string, starting position [, length])This function returns a substring specified by the length, starting at the character specified by the starting position. The starting position of the substring defines the first character where the substring begins. The length of the substring is specified by the length argument. Both of the numeric arguments can have values ranging from 0 to 255. If the starting position value is greater than the length of the string, or if the length of the string is zero, then MID$ returns a null string value (of length zero). If the length argument is left out, all characters to the right of the starting position are returned (which is equivalent with RIGHT$). EXAMPLE:PRINT MID$("COMMODORE 128",3,5) MMODO EXAMPLE using overlay:A$="123456":MID$(A$,3,2)="ABCDE":PRINT A$ 12AB56 NOTE: Overlay cannot be used to expand the size of a string, thus in the example above MID$(A$,3,5) is not possible. 18.20 PEEKReturn contents of a specific memory location. PEEK(x)This function returns the contents of memory location x, where x is located in the range 0 through 65535, returning a result between 0 and 255 (inclusive). This is the counterpart of the POKE statement. The data will be returned from the bank selected by the most recent BANK command. See the BANK command, in paragraph 17.4 of Section 17. EXAMPLE:10 BANK 15:VIC=DEC("D000") 20 FOR I=1 TO 47 30 PRINT PEEK(VIC+I) 40 NEXTThis example displays the contents of the registers of the VIC chip. 18.21 PENReturn x and y coordinates of the light pen. PEN(n)where:
Note that, like sprite coordinates, the PEN value is not scaled and uses real coordinates, not graphic bit map coordinates. The x position is given as a number, ranging from approximately 60 to 320, while the y position can be any number from 50 to 250. These are the visible screen coordinate ranges, where all other values are not visible on the screen. A value of zero for either position means the light pen is off screen and has not triggered an interrupt since the last read. Note that COLLISION need not be active to use PEN. A white background is usually required to stimulate the light pen. PEN values vary from system to system. Unlike the 40 column (VIC), the 80 column (VDC 8563) coordinates are character row and column positions and not pixel coordinates, like the VIC screen. Both the 40 and 80 column screen coordinate values are approximate and vary, due to the nature of light pens. The read values are not valid until PEN(4) is true. EXAMPLES:10 PRINT PEN(0);PEN(1)Display the x and y coordinates of the light pen.
18.22 {pi}Return the value of pi (3.14159265). {pi} EXAMPLE:PRINT {pi} 3.14159265 18.23 POINTERReturn the address of a variable name. POINTER(variable name) EXAMPLE:PRINT POINTER(Z)This example returns the address of variable Z. 18.24 POSReturn the current cursor column position within the current screen window. POS(x)The POS function indicates where the cursor is within the defined screen window. X is a dummy argument, which must be specified, but the value is ignored. EXAMPLE:PRINT "0123456789"POS(1) 0123456789 10This displays the current cursor position within the defined text window, in this case 10. 18.25 POTReturn the value of the game-paddle potentiometer. POT(n)when:
The values for POT range from 0 to 255. Any value of 256 or more means that the fire button is also depressed. EXAMPLE:10 PRINT POT(1) 20 IF POT(1) >=256 THEN PRINT"FIRE"This example displays the value of the game paddle 1. Note: A value of 255 is returned if no paddles are connected. 18.26 RCLRReturn color of color source. RCLR(n)This function returns the color (1 to 16) assigned to the color source n (0 <= n <= 6), where the following n values apply:
The counterpart to the RCLR function is the COLOR command. EXAMPLE:10 FOR I=0 TO 6 20 PRINT "SOURCE";I;"IS COLOR CODE";RCLR(I) 30 NEXTThis example prints the color codes for all seven color sources. 18.27 RDOTReturn current position or color of pixel cursor. RDOT(n)where:
This function returns the location of the current position of the pixel cursor (PC) or the current color source ot the pixel cursor. EXAMPLES:PRINT RDOT(0)Returns x position of PC. PRINT RDOT(1)Returns y position of PC. PRINT RDOT(2)Returns color source of PC (0 to 3). 18.28 RGRReturn current graphic mode. RGR(x)This function returns the current graphic mode. x is a dummy argument, which must be specified. The counterpart of the RGR function is the GRAPHIC command. The value returned by RGR(x) pertains to the following modes:
EXAMPLE:PRINT RGR(0) 1This displays the current graphic mode, in this case, standard bit map mode. 18.29 RIGHT$Return substring from rightmost end of string. RIGHT$(<string> , <length>)This function returns a substring taken from the rightmost characters of the string argument. The length of the substring is defined by the length argument, which can be any integer in the range of 0 to 255. If the value of length is zero, then a null string ("") is returned. If the value given in the length argument is greater than the length of the string, the entire string is returned. Also see LEFT$ and MID$ functions, in paragraphs 18.16 and 18.19, respectively. EXAMPLE:PRINT RIGHT$("BASEBALL",5) EBALL 18.30 RNDReturn a random number. RND(x)This function returns a random number, which value lies between 0 (inclusive) and 1 (exclusive). This is usefull in games, to simulate dice roll and other elements of chance. It is also used in some statistical applications. If x = 0RND returns a random number based on the hardware clock. If x > 0RND generates a reproducable pseudo-random number based on the seed value (see below - "If x < 0"). If x < 0Produces a random number which is used as a base called a seed. To simulate the rolling of a dice, use the formula INT(RND(1) * 6 + 1). First the random number is multiplied by 6, which expands the range to 0-6 (actually, less than six). Then 1 is added, making the range from 1 to less than 7. The INT function truncates all the decimal places, leaving the result as a digit from 1 to 6. EXAMPLES:PRINT RND(0) .507824123This displays a random number. PRINT INT(RND(1)*100 + 1) 89This displays a random positive number less than 100. 18.31 RSPCOLORReturn sprite multicolor values. RSPCOLOR(n)When:
The returned color value is a value between 1 and 16 (inclusive). The counterpart of the RSPCOLOR function is the SPRCOLOR command. Also see the SPRCOLOR command, in paragraph 17.87 of Section 17. EXAMPLE:10 SPRITE 1,1,2,0,1,1,1 20 SPRCOLOR 5,7 30 PRINT"SPRITE MULTICOLOR 1 IS";RSPCOLOR(1) 40 PRINT"SPRITE MULTICOLOR 2 IS";RSPCOLOR(2) RUN SPRITE MULTICOLOR 1 IS 5 SPRITE MULTICOLOR 2 IS 7In this example line 10 turns on sprite 1, colors it white, expands it in both the x and y directions and displays it in multicolor mode. Line 20 selects sprite multicolors 1 and 2. Lines 30 and 40 print the RSPCOLOR values for multicolor 1 and 2. 18.32 RSPPOSReturn the speed and position values of a sprite. RSPPOS(sprite number, n)where sprite number identifies which sprite is being checked and n specifies x and y coordinates or the sprite's speed. When n equals:
EXAMPLE:10 SPRITE 1,1,2 20 MOVSPR 1,45#13 30 PRINT RSPPOS(1,0);RSPPOS(1,1);RSPPOS(1,2)This example returns the current x and y sprite coordinates and the speed (13), all of sprite 1. 18.33 RSPRITEReturn sprite characteristics. RSPRITE(sprite number, characteristic)RSPRITE returns sprite characteristics that were specified in the SPRITE command. Sprite number specifies the sprite you are checking and the argument characteristics specifies the sprite's display qualities as follows:
EXAMPLE:10 FOR I=0 TO 5 20 PRINT RSPRITE(1,I) 30 NEXTThis example prints all 6 characteristics of sprite 1. 18.34 RWINDOWReturn the size of the current window. RWINDOW(n)When n equals:
The counterpart of the RWINDOW function is the WINDOW command. EXAMPLE:10 WINDOW 1,1,10,10 20 PRINT RWINDOW(0);RWINDOW(1);RWINDOW(2); RUN 9 9 40This example returns the number of lines (9) and columns (9) in the current window. The example assumes you are displaying the window in 40 column format. 18.35 SGNReturn sign of argument x. SGN(x)This function returns the sign (positive, negative or zero) of x. The result is +1 if x > 0, 0 if x = 0, and -1 if x < 0. EXAMPLE:PRINT SGN(4.5);SGN(0);SGN(-2.3) 1 0 -1 18.36 SINReturn sine of argument x. SIN(x)This is the trigonometric sine function. The result is the sine of x, where x is an angle measured in radians. EXAMPLE:PRINT SIN({pi}/3) .866025404 18.37 SPCSkip spaces on the screen. SPC(x)This function is used in PRINT or PRINT# commands to control the formatting of data, as either output to the screen or output to a logical file. The number of SPaCes specified by the x parameter determines the number of characters to fill with spaces across the screen or in a file. For screen or tape files, the value of the argument is in the range 0 to 255, and for disk files the maximum is 254. For printer files, an automatic carriage-return and line-feed will be performed by the printer if a SPaCe is printed in the last character position of a line; no SPaCes are printed on the following line. EXAMPLE:PRINT "COMMODORE";SPC(3);"128" COMMODORE 128 18.38 SQRReturn square root of argument. SQR(x)This function returns the value of the SQuare Root of x, where x is a positive number or 0. The value of the argument must not be negative, or the BASIC error message ?ILLEGAL QUANTITY ERROR is displayed. EXAMPLE:PRINT SQR(25) 5 18.39 STR$Return string representation of number. STR$(x)This function returns the STRing representation of the numeric value of the argument x. When the STR$ value is converted, any number displayed is preceded and followed by a space except for negative numbers, which are preceded by a minus sign. The counterpart of the STR$ function is the VAL function. EXAMPLES:PRINT STR$(123.45) 123.45 PRINT STR$(-89.03) -89.03 PRINT STR$(1E20) 1E+20 18.40 TABMoves cursor to tab position in present statement. TAB(x)This function moves the cursor forward if possible to a relative position on the text screen given by the argument x, starting with the leftmost position of the current line. The value of the argument can range from 0 to 255. If the current print position is already beyond position x, the TAB function is ignored. The TAB function should only be used with the PRINT statement, since it has varied effects if used with the PRINT# to a logical file, depending on the device being used. EXAMPLE:10 PRINT"COMMODORE"TAB(25)"128" COMMODORE 128 18.41 TANReturn tangent of argument. TAN(x)This function returns the tangent of x, where x is an angle measured in radians. EXAMPLE:PRINT TAN(.785398163) 1 18.42 USRCall user-defined subfunction USR(x)When this function is used, the program jumps to a machine language program whose starting point is contained in memory locations (low order byte first, high order byte last): 4633 ($1219) and 4634 ($121A) ... C128 mode 785 ($0311) and 786 ($0312) ... C64 mode The parameter x is passed to the machine language program in the floating point accumulator. A value is returned to the BASIC program through the calling variable. You must redirect the value into a variable in your program in order to receive the value back from the floating point accumulator. An ILLEGAL QUANTITY ERROR results if you don't specify this variable. This allows the user to exchange a variable between machine code and BASIC. EXAMPLE (128 Only):
Place starting location ($C000=49152: $00=0: $C0=192) of machine language routine in location 4633 and 4634. Line 30 stores the returning value from the floating point accumulator. 18.43 VALReturn the numeric value of a number string. VAL(numeric string)This function converts the numeric string argument into a number. It is the inverse operation of STR$. The string is examined from the leftmost character to the right, for as many characters as are in recognizable number format. If the Commodore 128 finds illegal characters, only the portion of the string up to that point is converted. If no numeric characters are present VAL returns a 0. EXAMPLE:10 A$ = "120" 20 B$ = "365" 30 PRINT VAL(A$) + VAL(B$) 485 18.44 XORReturns exclusive OR XOR(n1,n2)This function provides the exclusive OR of the argument values n1 and n2. x = XOR(n1,n2)where n1, n2 are 2 unsigned values (0-65535). EXAMPLE:PRINT XOR(128,64) 192 NOTE: n1 and n2 need not be whole numbers. |
page URL: www.bigfoot.com/~c128page/c128sg/sect-18.htm
contact: c128page@bigfoot.com