SECTION 18

TABLE OF CONTENTS abs, asc, atn, bump, chr$, cos, dec, err$, exp, fnxx, fre, hex$, instr, int, joy, left$, len, log, mid$, peek, pen, {pi}, pointer, pos, pot, rclr, rdot, rgr, right$, rnd, rspcolor, rsppos, rsprite, rwindow, sgn, sin, spc, sqr, str$, tab, tan, usr, val, xor

The 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 ABS

Return absolute value.

     ABS(x)

The absolute value function returns the positive value of the argument.

EXAMPLE:

     PRINT ABS(7*(-5))
      35

18.2 ASC

Return 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 ATN

Return 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 BUMP

Return 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:

PRINT BUMP(1) 12
Indicates that sprites 3 and 4 have collided.

PRINT BUMP(2) 32
Indicates that sprite 6 has collided with an object on the screen.

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:

PRINT CHR$(65) A
Prints the a character

PRINT CHR$(147)
Clears the text screen.

18.6 COS

Return 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 DEC

Return 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 EXP

Return 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 FNxx

Return 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:

10 DEF FNAA(X)=(X-32)*5/9 20 INPUT X 30 PRINT FNAA(X) RUN

? 40

(? is input prompt)

4.44444445

18.11 FRE

Return 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)   
      48893

Returns the number of free bytes for BASIC programs.

     PRINT FRE(1)   
      64256

Returns 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 INSTR

Return 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 INT

Return 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 JOY

Return position of joystick and the status of the fire button.

     JOY(n)

where n equals:

1: JOY returns position of joystick 1
2: JOY returns position of joystick 2

Any value of 128 or more means that the fire button is also pressed. To find the JOY value, add the direction value of the joystick plus 128, if the JOY fire button is pressed. The direction is indicated as follows:

                                   1 
                                8     2
                              7    0     3
                                6     4
                                   5

EXAMPLES:

     JOY(2) is 135

When 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 LEN

Return 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 LOG

Return 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 PEEK

Return 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 NEXT

This example displays the contents of the registers of the VIC chip.

18.21 PEN

Return x and y coordinates of the light pen.

     PEN(n)

where:

n=0: PEN returns the x coordinate of the light pen position.
n=1: PEN returns the y coordinate of the light pen position.
n=2: PEN returns the x coordinate of the light pen position of the 80 column display.
n=3: PEN returns the y coordinate of the light pen position of the 80 column display.
n=4: PEN returns the light pen trigger value.

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.

10 DO UNTIL PEN(4):LOOP
Ensure the read values are valid.

20 X=PEN(2) 30 X=PEN(3) 40 REM:REST OF PROGRAM

18.22 {pi}

Return the value of pi (3.14159265).

     {pi}

EXAMPLE:

     PRINT {pi}
      3.14159265

18.23 POINTER

Return the address of a variable name.

     POINTER(variable name)

EXAMPLE:

     PRINT POINTER(Z)

This example returns the address of variable Z.

18.24 POS

Return 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 10

This displays the current cursor position within the defined text window, in this case 10.

18.25 POT

Return the value of the game-paddle potentiometer.

     POT(n)

when:

n=1: POT returns the position of paddle #1.
n=2: POT returns the position of paddle #2.
n=3: POT returns the position of paddle #3.
n=4: POT returns the position of paddle #4.

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 RCLR

Return 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:

0: RCLR returns the 40-column background color.
1: RCLR returns the bit map foreground color.
2: RCLR returns multicolor 1.
3: RCLR returns multicolor 2.
4: RCLR returns the 40-column border color.
5: RCLR returns the 40- or 80-column character color.
6: RCLR returns the 80-column background color.

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 NEXT

This example prints the color codes for all seven color sources.

18.27 RDOT

Return current position or color of pixel cursor.

     RDOT(n)

where:

n=0: returns the x coordinate of the pixel cursor.
n=1: returns the y coordinate of the pixel cursor.
n=2: returns the color source of the pixel cursor.

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 RGR

Return 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:

VALUE GRAPHIC MODE

0 40 column (VIC) text.

1 Standard bit map.

2 Split screen bit map.

3 Multicolor bit map.

4 Split screen multicolor bit map.

5 80 column (VDC 8563) text.

EXAMPLE:

     PRINT RGR(0)
      1

This 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 RND

Return 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 = 0

RND returns a random number based on the hardware clock.

     If x > 0

RND generates a reproducable pseudo-random number based on the seed value (see below - "If x < 0").

     If x < 0

Produces 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)
      .507824123

This displays a random number.

     PRINT INT(RND(1)*100 + 1)
      89

This displays a random positive number less than 100.

18.31 RSPCOLOR

Return sprite multicolor values.

     RSPCOLOR(n)

When:

n=1: RSPCOLOR returns the sprite multicolor 1.
n=2: RSPCOLOR returns the sprite multicolor 2.

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 7

In 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 RSPPOS

Return 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:

0: RSPPOS returns the current x position of the specified sprite.
1: RSPPOS returns the current y position of the specified sprite.
2: RSPPOS returns the speed (0-15) of the specified sprite.

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 RSPRITE

Return 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:

Characteristic
RSPRITE returns these values:

0
Enabled (1) / Disabled (0).

1
Sprite color (0-16).

2
Sprites are displayed in front of (0) or behind (1).

3
Expand in x direction,
yes=1, no=0.

4
Expand in y direction,
yes=1, no=0.

5
Multicolor,
yes=1, no=0.

EXAMPLE:

     10 FOR I=0 TO 5
     20 PRINT RSPRITE(1,I)
     30 NEXT

This example prints all 6 characteristics of sprite 1.

18.34 RWINDOW

Return the size of the current window.

     RWINDOW(n)

When n equals:

0: RWINDOW returns the number of lines in the current window.
1: RWINDOW returns the number of rows in the current window.
2: RWINDOW returns either of the values 40 or 80, depending on the current screen output format you are using.

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  40

This 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 SGN

Return 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 SIN

Return 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 SPC

Skip 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 SQR

Return 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 TAB

Moves 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 TAN

Return 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 USR

Call 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):

10 POKE 4633,0

20 POKE 4634,192
NOTE: Default Commodore 128 bank is 15.

30 A = USR(X) 40 PRINT A

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 VAL

Return 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 XOR

Returns 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