8bitfiles.net/archives

home *** CD-ROM | disk | FTP | other *** search

/ 8bitfiles.net/archives / archives.tar / archives / canada-remote-systems / c64 / utils / evsbasic.arc / EVSKEYWORDS.A-D < prev next >

Wrap

Text File | 2019-04-13 | 14.4 KB | 422 lines

EVS Basic 1.00 Keyword Descriptions (C) 1988 by Anton Treuenfels Last Revision: 08/30/88 This document describes the EVS Basic keywords and what they do. Each description also includes a few examples of the use of the keyword (although these examples appear as they would in program mode, all keywords also function in immediate mode). Most EVS Basic keywords require one or more parameters. The type and number of parameters are indicated between angle brackets after the keyword itself: keyword <parameter>. Many EVS Basic keywords also accept optional parameters, which are indicated by square brackets surrounding the angle brackets: [<optional>]. Ellipses within square brackets mean that the entire enclosed block of parameters may be repeated as often as desired: [[<optional>]...]. When an optional parameter of a keyword is used in a statement there is often also a separator character (usually a comma) required to distinguish it from any other parameters: <required> [, <optional>] or [<optional>,] <required>. A few keywords have a series of "semi-optional" parameters: [ <optional> [, <optional> [, <optional>]]]. Such series usually indicate that at least one but not necessarily all of the <optional> parameters be present. With a series of optional parameters it is possible to "skip over" any the programmer does not wish to use by just using the separator character to indicate an unused parameter: <optional>, , , <optional>. The separator character is required between used and unused optional parameters only up to the last one actually present. The separator character is not required or accepted beyond that point. --------------------------------------- BIN$(<hex$>) The BIN$() function combines pairs of ASCII Hex characters from <hex$> to produce an equivalent binary string. If <hex$> has an odd number of characters, BIN$() will ignore the last character. The sixteen ASCII Hex characters are "0" to "9" and "A" to "F". Each ASCII Hex character represents half of a binary character, so two are needed for each character in the finished binary string (thus a character pattern for IMAGE requires sixteen ASCII Hex characters, and a sprite image requires 126). The first character of each pair is taken as the "left" or "upper" half of a binary character, while the second is taken as the "right" or "lower" half (from a more technical point of view, the first character represents the "high nybble" and the second character the "low nybble" of eight-bit bytes). The binary patterns represented by each ASCII Hex char are listed below: ASCII Hex Pattern: "0" 0 0 0 0 "1" 0 0 0 1 "2" 0 0 1 0 "3" 0 0 1 1 "4" 0 1 0 0 "5" 0 1 0 1 "6" 0 1 1 0 "7" 0 1 1 1 "8" 1 0 0 0 "9" 1 0 0 1 "A" 1 0 1 0 "B" 1 0 1 1 "C" 1 1 0 0 "D" 1 1 0 1 "E" 1 1 1 0 "F" 1 1 1 1 Examples: 10 A$= BIN$(B$) 20 IMAGE "T", BIN$("3C42A581A599423C"): REM HAPPY FACE 30 FOR I=0 TO 15: READ A$: IMAGE I, BIN$(A$): NEXT --------------------------------------- CAT [<pattern$>] [, <dvc#>] The CAT command is used to display all or part of the directory of a diskette. The CAT keyword by itself lists the entire directory of the diskette in the default disk device (normally device 8) to the screen. <Pattern$> can be used to list only filenames containing that pattern. The wildcard characters "?" and "*" can be used in the pattern and have their normal meaning. <Dvc#> may be used to select any particular disk device, including the default device. A directory is normally taken from drive 0, but if the device is dual drive either drive may be specified by using the first two characters of <pattern$>: "0:" (for drive 0) or "1:" (for drive 1). Examples: 10 CAT 20 CAT "TEST" 30 CAT , 8 40 CAT "1:", 9 --------------------------------------- CUR(<nexp>) This function returns a value indicating the cursor X- or Y-position or the value "under" the cursor. The sign of <nexp> determines the type of value returned by CUR(). If zero, CUR() returns the physical (not logical) X-position of the cursor. If positive, CUR() returns the physical (not logical) Y-position of the cursor. If negative, CUR() "looks under" the cursor and returns either the screen code of the character (if in a text mode) or the pen value of the pixel (if in a bitmap mode) found there. Examples: 10 X = CUR(0): Y = CUR(1) 20 LINE CUR(0) + 5, CUR(1) - 10 30 IF CUR(-1) = 3 THEN EXIT --------------------------------------- DIR [<pattern$>] [, <dvc#>] The DIR command is used to display all or part of the directory of a diskette. The DIR keyword by itself lists the entire directory of the diskette in the default disk device (normally device 8) to the screen. <Pattern$> can be used to list only filenames which begin with the pattern. The wildcard characters "?" and "*" can be used in the pattern and have their normal meaning. Alternatively, filetypes instead of filenames can be matched using a "*=<filetype>" pattern. <Dvc#> may be used to select any particular disk device, including the default device. A directory is normally taken from drive 0, but if the device is dual drive either drive may be specified by using the first two characters of <pattern$>: "0:" (for drive 0) or "1:" (for drive 1). Examples: 10 DIR 20 DIR "B?N?N?" 30 DIR , 8 40 DIR "*=PRG" --------------------------------------- DO [WHILE/UNTIL <exp>] The DO statement marks the start of a DO/LOOP repeat structure. The DO statement is physically the first statement of the loop. Every DO must have one, and only one, matching LOOP statement. The basic DO/LOOP structure is unconditional, and all program statements between a DO statement and a LOOP statement will repeatedly execute in order forever (or until the program is halted by the STOP key). This is useful in some cases, but more often a program exits from a DO/LOOP when some condition is fulfilled. A DO statement may optionally be followed by either the WHILE or UNTIL conditional statements. A WHILE conditional will continue repeating the loop only so long as <exp> is true. An UNTIL conditional will continue repeating the loop only so long as <exp> is false. Note that since either condition is evaluated before the first program statement contained within the loop is executed, it is possible to create a loop which may never actually be executed. When a DO/LOOP is terminated by WHILE, UNTIL, or EXIT, normal program execution continues starting with the next statement after the LOOP matching the DO. DO/LOOPs may be nested within each other or within FOR/NEXT loops, and FOR/NEXT loops may be nested within DO/LOOPs. The total number of active nested loops of both kinds should not exceed nine. Examples: 10 DO: PRINT "HELLO": LOOP 20 DO UNTIL A<0: READ A: PRINT A: LOOP --------------------------------------- DOS <command$> [, <dvc#>] The DOS statement sends a <command$> to the command channel of a disk device. The <command$> may be any legal disk command that in V2 Basic would normally be PRINTed to channel 15 (the disk command channel). The most common uses for this statement are initializing a drive, formatting a diskette, and scratching unneeded files. Less often used commands include validating a disk, renaming a file, copying a file, and direct disk access. See Chapter 4 of the "1541 User's Manual" for details of the various disk commands. <Dvc#> may be used to select any particular disk device, including the default device. Examples: 10 DOS "I0" 20 DOS "S0:TEST*" 30 DOS "N0:MYDISK,MD",8 --------------------------------------- DRAW <shape$> [[;][<shape$>]...] The DRAW statement "draws" a figure defined by a <shape$> on a bitmap screen. In general a <shape$> can be drawn much more quickly and is more easily relocated about the screen than an equivalent shape drawn with LINE statements. On the other hand, it is usually not as easy to create a <shape$> as it is to simply list points to be connected by LINE. DRAW interprets a <shape$> as a coded list of graphics commands. Commands are included to move the cursor, plot points, draw lines, paint an area, change the pen, and expand or contract the shape in the X- or Y-directions. Each command is two, four, or six characters long and is of the general form: CHR$(128) + CHR$(command) [+ param$] By default DRAW draws a <shape$> at the current cursor position using the current pen in the current size. After a <shape$> is drawn the cursor, pen, and size are left as last set by the <shape$> definition. The first <shape$> definition can optionally be followed by as many more <shape$> definitions as will fit on a program line. The 17 commands recognized by DRAW are described below. Unrecognized commands generate an "?UNKNOWN CHAR" error. The following six commands require coordinate parameters: Move cursor: "m"+X$+Y$ or "M"+X$+Y$ Plot point: "d"+X$+Y$ or "D"+X$+Y$ Draw line: "l"+X$+Y$ or "L"+X$+Y$ DRAW interprets the coordinates specified in the above commands as being relative to the current cursor position rather than absolute, so they may be either positive or negative values. Also, DRAW uses only the physical coordinate system of the bitmap screen (0,0 is the upper left hand corner and 319,199 the lower right), so that positive X is right, negative X is left, positive Y is down, and negative Y is up. The use of relative coordinates enables a shape to be drawn anywhere on the screen. The difference between the lowercase and uppercase forms of each command is the allowed range of coordinates, and thus the overall number of characters needed to specify that range. The lowercase forms allow X and Y values in the range -127 to +127 and require two characters, while the uppercase forms may range from -319 to +319 for X and -199 to +199 for Y and require four characters. Note that since the cursor is not allowed to move outside the physical screen range the maximum range values may not always be available. The parameter characters needed for the lowercase forms of the above commands can be created in several steps. First, the numeric value of each character is calculated using the following function: DEF FN LC(C)= C - 256 * (C<0) This function is valid for the range -127 to +127. Given X and Y in this range, the two characters necessary to the lowercase form can be created: X$ = CHR$(FN RP(X)) Y$ = CHR$(FN RP(Y)) A similar method can be employed for the uppercase forms of the commands. First, functions to create the numeric value: DEF FN UL(C)= (C - 65536 * (C<0)) AND 255 DEF FN UH(C)= (C - 65536 * (C<0)) / 256 These functions are valid for the range -32767 to +32767, which is far more than needed. The characters themselves can be formed like this: X$ = CHR$(FN UL(X)) + CHR$(FN UH(X)) Y$ = CHR$(FN UL(Y)) + CHR$(FN UH(Y)) A complete move, point, or line command thus looks like: CHR$(128) + command$ + X$ + Y$ where <command$> is "m", "M", "d", "D", "l" or "L". The only other DRAW command that requires parameters is the paint command: Paint area: "p"+T$+B$ or "P"+T$+B$ The lowercase paint is a threshold paint in the range 0-63 or 128-191, and T$=CHR$(threshold). The uppercase paint is a pattern paint, and T$ represents the character to use as the pattern. In either case B$ is the boundary of the filled area. The boundary value can be a particular pixel value in the range 0-3 or it may be 255 to stop the fill at any non-zero pixel, and B$=CHR$(boundary). A complete paint command thus looks like: CHR$(128) + command$ + T$ + B$ where <command$> is "p" or "P". The following DRAW commands change the current pen: Set pen 0: CTRL-Z or CHR$(26) Set pen 1: CTRL-X or CHR$(24) Set pen 2: CTRL-C or CHR$(3) Set pen 3: CTRL-V or CHR$(22) Set pen 4: CTRL-B or CHR$(2) The following DRAW commands change the current size of the shape: Normal X-size: F1 or CHR$(133) Double X-size: F2 or CHR$(137) Normal Y-size: F3 or CHR$(134) Double Y-size: F4 or CHR$(138) Both of the above sets of commands require no parameters and have the form: CHR$(128) + command$ where <command$> is one of the CHR$() values shown. All DRAW commands are required to begin with CHR$(128) followed by a legal command character. There is one exception to this rule: a command which does not start with CHR$(128) is assumed to be an "l" command, that is, a line command in the range -127 to +127. In this case the "l" character does not have to be specified either, so only the two coordinate parameter characters are needed. Examples: 10 DRAW A$ 20 DRAW A$(I) 30 DRAW CHR$(128)+CHR$(137);A$ --------------------------------------- DS and DS$ DS and DS$ are pseudo-variables relating to the error status of a disk device. They may be used in any way normal variables are except that they cannot be assigned values. Instead, each time DS$ is referenced it will return the current status message of the most recently used disk device. DS always returns the number of the last message retrieved by DS$. A disk status message has the general form "error number, error message, track, sector". After a successfully executed disk command DS$ will return the string "00,OK,00,00" and DS will have the value 0. See Appendix B of the "1541 User's Manual" for complete descriptions of other error messages and their causes. Note that the value of DS never changes except when DS$ changes. This can be useful if an error occurs when a disk drive attempts to execute a command (the activity light begins to blink). Only the very next reference to DS$ will return the correct error message. After that the error is "cleared" (the activity light stops blinking) and any new reference to DS$ will return the "OK" message. DS, on the other hand, will return the number associated with the now-cleared error until the next reference to DS$. Examples: 10 PRINT "DISK STATUS "; DS$ 20 A$ = DS$ 30 IF DS > 0 AND DS <> 50 THEN 9000 --------------------------------------- DVC <nexp> The DVC statement sets the default mass-storage device number. If a command requires a device number and none is explicitly specified, then the command is directed to the default device. The default device can be the tape drive or any of the disk drives. EVS Basic uses device 8 (the first disk drive) as the default device until changed by DVC. LOAD, SAVE, and VERIFY do not care what the default device is, but CAT, DIR, and DOS will signal an "?ILLEGAL DEVICE ERROR" if they are directed to the tape drive. Examples: 10 DVC 1 20 DVC 10 20 DVC IO(A)