BASIC DOCUMENTATION 02/13/81 BASIC DOCUMENTATION PAGE 2 02/13/81 TABLE OF CONTENTS CHAPTER 1 INTRODUCTION. . . . . . . . . . . . . . . . . . . . 1-1 1.1 STATEMENT AND LINE FORMAT. . . . . . . . . . . . 1-1 1.2 VARIABLE NAMES . . . . . . . . . . . . . . . . . 1-2 1.3 VIRTUAL ARRAYS . . . . . . . . . . . . . . . . . 1-2 1.4 STRING CONSTANTS . . . . . . . . . . . . . . . . 1-3 1.5 DATA AND FILE PRESERVATION . . . . . . . . . . . 1-3 1.6 STRING VARIABLES . . . . . . . . . . . . . . . . 1-3 1.7 EXPONENTIATION . . . . . . . . . . . . . . . . . 1-3 1.8 MCR COMMAND LINE . . . . . . . . . . . . . . . . 1-4 1.9 CONTROL C. . . . . . . . . . . . . . . . . . . . 1-4 1.10 CONTROL O . . . . . . . . . . . . . . . . . . . 1-5 1.11 LOGICAL EXPRESSIONS . . . . . . . . . . . . . . 1-5 CHAPTER 2 LOADING/RUNNING/SAVING PROGRAMS . . . . . . . . . . 2-1 2.1 STOP . . END . . . . . . . . . . . . . . . . . . 2-1 2.2 RUN. . . . . . . . . . . . . . . . . . . . . . . 2-1 2.3 CLEAR. . . . . . . . . . . . . . . . . . . . . . 2-2 2.4 SAVE [N1][-N2][,N3...]. . 2-2 2.5 OLD . . . . . . . . . 2-2 2.6 CHAIN . . . 2-2 2.7 OVERLAY . . 2-3 2.8 LIST [N1][-N2][,N3...] . . . . . . . . . . . . . 2-3 2.9 DELETE N1[-N2][,N3...] . . . . . . . . . . . . . 2-3 2.10 EXIT. . . . . . . . . . . . . . . . . . . . . . 2-4 2.11 STEP [LINE #] . . . . . . . . . . . . . . . . . 2-4 2.12 CON [LINE #]. . . . . . . . . . . . . . . . . . 2-4 CHAPTER 3 PROGRAM STATEMENTS. . . . . . . . . . . . . . . . . 3-1 3.1 GOSUB N . . GOTO N . . . . . . . . . . . . . . . 3-1 3.2 ON GOTO . . . . . . . 3-1 3.3 RETURN . . . . . . . . . . . . . . . . . . . . . 3-1 3.4 DIM. . . . . . . . . . . . . . . . . . . . . . . 3-2 3.5 DIM #N, . . . . . . . . . . . . . . . . . . 3-2 3.6 DEF. . . . . . . . . . . . . . . . . . . . . . . 3-3 3.7 LET. . . . . . . . . . . . . . . . . . . . . . . 3-3 3.8 IF . . . . . . . . . . . . . . . . . . . . . . . 3-4 3.9 REM . . !. . . . . . . . . . . . . . . . . . . . 3-4 3.10 READ . . DATA . . . . . . . . . . . . . . . . . 3-4 3.11 FOR . . . . . . . . . . . . . . . . . . . . . . 3-5 3.12 NEXT. . . . . . . . . . . . . . . . . . . . . . 3-5 3.13 BREAK . . . . . . . . . . . . . . . . . . . . . 3-5 3.14 SET PROMPT/TRACE/READ-PASS-ALL ON/OFF . . . . . 3-6 3.15 ON ERROR GOTO . . . . . . . . . . . . . . . . . 3-6 3.16 SLEEP . . . . . . . . . . . . 3-6 3.17 WAIT . . . . . . . . . . . . 3-7 3.18 PRIORITY . . . . . . . . . . . . . 3-7 3.19 TRACE ON AND OFF. . . . . . . . . . . . . . . . 3-7 CHAPTER 4 ARITHMETIC FUNCTIONS. . . . . . . . . . . . . . . . 4-1 4.1 RND. . . . . . . . . . . . . . . . . . . . . . . 4-1 4.2 RANDOMIZE. . . . . . . . . . . . . . . . . . . . 4-1 4.3 ABS. . . . . . . . . . . . . . . . . . . . . . . 4-1 BASIC DOCUMENTATION PAGE 3 02/13/81 4.4 SGN. . . . . . . . . . . . . . . . . . . . . . . 4-2 4.5 INT. . . . . . . . . . . . . . . . . . . . . . . 4-2 4.6 LOG (NATURAL & BASE 10). . . . . . . . . . . . . 4-2 4.7 EXP. . . . . . . . . . . . . . . . . . . . . . . 4-2 4.8 SIN COS. . . . . . . . . . . . . . . . . . . . . 4-2 4.9 ATN. . . . . . . . . . . . . . . . . . . . . . . 4-3 4.10 SQR . . . . . . . . . . . . . . . . . . . . . . 4-3 4.11 NRC . . . . . . . . . . . . . . . . . . . . . . 4-3 4.12 ERR . . ERL . . FCS . . . . . . . . . . . . . . 4-3 4.13 COR . . . . . . . . . . . . . . . . . . . . . . 4-3 4.14 DAT$. . . . . . . . . . . . . . . . . . . . . . 4-4 4.15 DDAT$ . . . . . . . . . . . . . . . . . . . . . 4-4 4.16 TIM$. . . . . . . . . . . . . . . . . . . . . . 4-4 4.17 DCEN. . . . . . . . . . . . . . . . . . . . . . 4-5 4.18 SEC . . . . . . . . . . . . . . . . . . . . . . 4-5 CHAPTER 5 STRING FUNCTIONS. . . . . . . . . . . . . . . . . . 5-1 5.1 INX . . POS. . . . . . . . . . . . . . . . . . . 5-1 5.2 LEN. . . . . . . . . . . . . . . . . . . . . . . 5-1 5.3 VAL. . . . . . . . . . . . . . . . . . . . . . . 5-1 5.4 OCT. . . . . . . . . . . . . . . . . . . . . . . 5-2 5.5 AR5. . . . . . . . . . . . . . . . . . . . . . . 5-2 5.6 ASC. . . . . . . . . . . . . . . . . . . . . . . 5-2 5.7 CHR$ . . . . . . . . . . . . . . . . . . . . . . 5-2 5.8 SEG$ SBS$ RIGHT LEFT MID . . . . . . . . . . . . 5-2 5.9 PIECE$ . . . . . . . . . . . . . . . . . . . . . 5-3 5.10 STR$. . . . . . . . . . . . . . . . . . . . . . 5-3 5.11 LTR$ TRM$ . . . . . . . . . . . . . . . . . . . 5-4 5.12 OCT$ OCS$ . . . . . . . . . . . . . . . . . . . 5-4 5.13 R5A$. . . . . . . . . . . . . . . . . . . . . . 5-4 5.14 FRMT$(X,W[,D]). . . . . . . . . . . . . . . . . 5-4 5.15 RJS$ . . LJS$ . . . . . . . . . . . . . . . . . 5-5 5.16 SPACE$ . . STRING$. . . . . . . . . . . . . . . 5-5 5.17 TAB . . . . . . . . . . . . . . . . . . . . . . 5-5 CHAPTER 6 I/O & FILE MANIPULATION . . . . . . . . . . . . . . 6-1 6.1 RESTORE. . . . . . . . . . . . . . . . . . . . . 6-1 6.2 PRINT. . . . . . . . . . . . . . . . . . . . . . 6-1 6.3 INPUT. . . . . . . . . . . . . . . . . . . . . . 6-2 6.4 INPUT LINE . . . . . . . . . . . . . . . . . . . 6-3 6.5 SCRATCH . . . . . . . . . . . . 6-3 6.6 OPEN . . . . . . . . . . . . . . . . . . . . . . 6-3 6.7 CLOSE N1[,N2...] . . . . . . . . . . . . . . . . 6-4 6.8 IF END [#N] THEN . . . . . . . . . . . . 6-4 CHAPTER 7 LOADABLE SUBROUTINES. . . . . . . . . . . . . . . . 7-1 7.1 LOAD . . . . . . . . . . . . . 7-1 7.2 UNLOAD . . . . . . . . . . . . . . . . . . . . . 7-1 7.3 CALL "NAME"(ARG1,ARG2,...) . . . . . . . . . . . 7-2 7.4 INSTRG . . . . . . . . . . . . . . . . . . . . . 7-2 7.5 OPEN LIBRARY . . . . . . . . . . . . . . . . . . 7-2 7.6 QUESTION DISPLAY . . . . . . . . . . . . . . . . 7-3 7.7 MDIS . . CDIS . . RDIS . . . . . . . . . . . . . 7-5 7.8 MPOS . . CPOS . . RPOS . . . . . . . . . . . . . 7-6 7.9 MQTXT . . CQTXT . . RQTXT. . . . . . . . . . . . 7-7 BASIC DOCUMENTATION PAGE 4 02/13/81 7.10 MATXT . . CATXT . . RATXT . . . . . . . . . . . 7-7 7.11 CQNAM . . RQNAM . . . . . . . . . . . . . . . . 7-7 7.12 SPAWNB. . . . . . . . . . . . . . . . . . . . . 7-7 APPENDIX A BASIC ERROR VALUES . . . . . . . . . . . . . . . . A-1 APPENDIX B SAMPLE LOADABLE MACRO SUBROUTINE . . . . . . . . . B-1 APPENDIX C USEFUL INTERNAL BASIC SUBROUTINE CALLS . . . . . . C-1 APPENDIX D INDEX. . . . . . . . . . . . . . . . . . . . . . . D-1 02/13/81 CHAPTER 1 INTRODUCTION This BASIC follows DEC's BASIC-11 in its basic orientation. Advanced features tend to follow RSTS BASIC-PLUS (e.g. virtual arrays). Primary differences are in the file I/O. The OPEN, PRINT and INPUT statements have been modified to provide full FILES-11 capability for ASCII files both fixed and variable length and sequential and random access. The statement concatenation character is the colon (:). BASIC can be used in an IMMEDIATE mode. Any legal command entered without a line number (or leading "tab") will be performed immediate- ly. Nearly all the BASIC codes presented in this document can be used in the IMMEDIATE mode and a few can be used only in the IMMEDI- ATE mode. The other BASIC mode is the PROGRAM mode. Any legal command follow- ing a line number or with a leading "tab", (effectively a continua- tion line,) will be stored with the current program and executed in normal program flow. BASIC comes in several 'sizes'. When a user invokes BASIC by calling for BAS, the space reserved for the program and data in main memory contains 2570 bytes. The next 'size' is BA2, 4618 bytes. The larg- est is B11, 23050 bytes. If a user's program calls for more than the space alloted to it, the computer stops execution and prints out a USERS OVERFLOW error mes- sage. Exit and re-enter the BASIC mode at a higher version. All numeric calculation is done in floating point (REAL*4 for you FORTRAN buffs) regardless of the variable types in the expression. 1.1 STATEMENT AND LINE FORMAT Multiple statements may be concatenated on a single line by use of the colon (:) character. A backslash (\) is also allowed for BASIC-PLUS compatibility. A line may be continued on the next line without using a new line number by starting the continued line with a tab or two spaces. Continued lines are treated the same way as in BASIC-PLUS: the end of a physical line is ignored during execution INTRODUCTION PAGE 1-2 02/13/81 so long as an individual BASIC element is not broken across line boundaries. The end of line does not serve to end a statement except when there is no continued line following it. Thus a statement which begins on a continued line must either have a concatenation character at the start of its line or the end of the previous line. There is an exception in the case of a comment (! only) terminating the pre- vious line, in which case no concatenation character is used. Care should be taken not to start an immediate mode command with a tab or double space as it will not be executed but added to the existing program as a continuation of the last entered program line. Note that checking of program statements for verb legality as they are read in by the interpreter is no longer done as it was in earlier versions. All checking is now done at run time. 1.2 VARIABLE NAMES Variable names may be one or two characters of which the first is al- pha and the second (if used) is alphanumeric, followed by an optional type character. If no type character is used, the type is REAL*4. A $ denotes a string variable, % is an integer variable (16 bits) and & is a byte variable (8 bits). Note that unlike standard BASIC, the second character of the variable name is allowed to be alphabetic. In order to gain this flexibility in naming variables, some restric- tions had to be made in the allowed format of the program text: spaces are not allowed within a variable name; variable names must not be the same as BASIC key words (e.g. TO and IF). Also, ambigui- ties may sometimes arise when a variable is next to a keyword in the program text. This can usually be resolved by re-writing the text. Although it is theoretically possible to resolve these cases in the interpreter, the expense in terms of interpreter code length and exe- cution time does not seem to warrant it. Consider the following ex- ample: 100 IF A < MT OR B=5. THEN 500 The T of MT and the O of OR are misinterpreted by BASIC to form the keyword TO. The statement can be rewritten unambiguously as follows: 100 IF (A < MT) OR (B=5.) THEN 500 1.3 VIRTUAL ARRAYS Virtaul arrays are used to store extensive numbers of variable va- lues, usually more than is practical to store in an in-memory array. The use of virtual arrays involves a special form of the DIM state- ment and the file OPEN statement with the block mode switch /BL. See the DIM statement documentation for details of variable mapping into virtual array files. Mechanics of virtual array files: Virtual array files are opened in block mode using the /BL switch. There is no record structure super- INTRODUCTION PAGE 1-3 02/13/81 imposed over the basic block structure. Therefore only the file ac- cess mode switches can be used in conjunction with /BL. This also implies that a virtual array file does not subtract from the total number of files (record type) which may be open simultaneously (cur- rently 6). Virtual arrays are maintained in memory one block at a time (512 bytes). When a variable is accessed, the appropriate block is calcu- lated and, if necessary, read into memory. If any writing to that block is done, a flag is set and when a different block needs to be read in, that one is written out. This has several implications: First, on a virtual file opened for read only access, an illegal write will not be detected until the block as a whole attempts to be written out. Also, in the case that the interpreter aborts or the system crashes, new or changed data may be lost for that block which is then in memory. 1.4 STRING CONSTANTS String constants are specified with double quotes. At this point it is not possible to represent a double quote in a string constant, i.e. a string delimited by double quotes. However, this limitation may be gotten around by using INPUT or READ or the CHR$ function. 1.5 DATA AND FILE PRESERVATION User data is now kept intact except for CLEAR and RUN commands. User files are automatically closed on execution of the RUN or CLEAR com- mands and on exit from BASIC. They remain open (unless explicitly closed by a CLOSE command) on program stop for debugging purposes. 1.6 STRING VARIABLES String variables are declared in a DIM statement and can be either fixed or variable length. See DIM statement for the specifics. 1.7 EXPONENTIATION Exponentiation (^) is done in two ways. If the exponent is an in- teger, the base is multiplied (or divided) by itself the appropriate number of times. If the exponent contains a fractional part, a log - antilog calculation sequence is used. INTRODUCTION PAGE 1-4 02/13/81 1.8 MCR COMMAND LINE BASIC is called from the MCR by typing BASIC (or BAS) in response to the MCR prompt. A may follow for normal interactive use or one of two other options may follow before for special uses. If a space and a ? followed by an arithmetic expression follows BAS, the value of the expression will be printed on the next line followed by a return to the MCR. This is useful for quick desk calculator type calculations. If a space (or tab) and a file name with an optional switch follow, then that file will be read in as a user program just as in the OLD command. If the switch (/RN) is specified, the program will also be run as though the RUN command had been typed. A switch of the form "/RN:NNN" will cause the program to start execution at line # NNN. If the switch (/CO) is added, then the file retrieved will be assumed to be previously compiled and a default extension of BAC will be used. NOTE Note that no quotes are used here as opposed to the OLD and RUN commands. Examples: MCR>BAS MCR>BASIC PROG.BAS/RN MCR>BAS PROG/RN:150 MCR>BAS ? 4*3+2 1.9 CONTROL C The break key for BASIC is the Control-C (^C). A ^C typed at the keyboard when running will cause the program to stop at the next se- quential line (not at a line entered via GOTO, GOSUB, IF etc.). When in immediate mode, ^C will bring up MCR if the terminal has not been set hostile. ^C typed during a list command will terminate the list- ing process after the current line is finished printing out. It causes an immediate return to the interpreter as opposed to ^O which only suppresses printing while the BASIC interpreter still goes through the motions of completing the listing. INTRODUCTION PAGE 1-5 02/13/81 1.10 CONTROL O Control-O (^O) will stop all output from a LIST command and resume printing with READY. It also stops all printing following a RUN com- mand including non-fatal errors. Printing resumes with a STOP or ^C or a fatal error (one which stops program execution). 1.11 LOGICAL EXPRESSIONS Logical expressions are of the form: [...] Where expressions are either arithmetic or string and relational op- erators can be formed by any combination of <, > and =. The two ex- pressions which are related by the relational operator must be of the same type: i.e. string or arithmetic. The result of evaluating the relationship (termed here a logical subexpression) is either true or false. Strings are compared character by character on the basis of their AS- CII codes. When two strings of unequal length match at all common character positions, the shorter one is considered less than the longer one. Logical subexpressions can in turn be related by the logical (Boole- an) operators: AND, OR, XOR and NOT. The order of evaluation is from left to right, but logical subexpressions may be nested with parentheses to any depth desired. One restriction exists with respect to parentheses: no leading ar- ithmetic expression in a logical subexpression should begin with an open parenthesis, otherwise the interpreter will attempt to evaluate it as a nested subexpression. This can easily be gotten around by rearranging the arithmetic expression or adding it to 0. Examples: A < B OR B = .5 NOT (X1 < 1 AND A >= 5) 02/13/81 CHAPTER 2 LOADING/RUNNING/SAVING PROGRAMS The subset of commands listed in this chapter is primarily used to control execution of BASIC programs. Their purpose is to let one lo- ad saved programs, interactively modify/debug them while running, and possibly save modified versions for later use. As such, the equiva- lent commands normally do not exist for compiled languages such as FORTRAN. 2.1 STOP . . END STOP and END statements. Stop user program execution and tell user where program has stopped. Example: 10 STOP 20 END 2.2 RUN May be used in immediate mode to start the program in memory or by specifying a file in quotes to run another BASIC program stored on disk. In program mode, it may be used with a file specifier to chain to another program. The assumed file extension is .BAS. Note that no data is saved across a "RUN" type chain. User loaded subroutines are also unloaded. To preserve data and user files, use "CHAIN" command. A previous restriction against using a variable in the string expres- sion following the RUN command has been removed. The optional switch /RT may be used as with OLD to trim REM and ! statements when the file form of the command is used. The switches /LI and /CO may be used as in the CHAIN statement. Example: RUN RUN "PROGRAM" 10 RUN "PROG1" LOADING/RUNNING/SAVING PROGRAMS PAGE 2-2 02/13/81 2.3 CLEAR This command clears the user data area. It closes all user files be- fore doing the clear operation. 2.4 SAVE [N1][-N2][,N3...] Primarily an immediate mode command. It makes a copy of the present program on the file named in the string filespec (string variable or string in quotes). Optional line numbers or line number ranges can be included. The optional switch will produce a psuedo-compiled version which can be read back with the same switch without re-interpreting the code thus saving a considerable amount of time for long programs. The de- fault extension will be BAC if the switch is included. The default file specifier is: SY:PROGRAM.BAS or the name, extension and device in the last OLD, RUN, CHAIN or OVERLAY command. Example: SAVE "PROGRAM" SAVE "LP:" SAVE "DK2:PROG.BAS" SAVE 2.5 OLD The OLD command reads in a previously saved or edited program from the file named in the string filespec (as in SAVE). The optional switch, when specified, causes truncation of REM and ! statements. The default file specifier is: SY:PROGRAM.BAS The CO switch indi- cates that a compiled basic file is to be used (default extension BAC). Example: OLD "PROG1" OLD "DK3:PROGRAM.BAS" 2.6 CHAIN The CHAIN command reads in another BASIC program while preserving variables and open files' FCB's. GOSUB/RETURN pointers, FOR loop control tables, user DEFined functions and scratch items are all de- leted from the user data area. Thus user functions must be redefined in any new program module. The default file specifier and switches are the same as for the OVER- LOADING/RUNNING/SAVING PROGRAMS PAGE 2-3 02/13/81 LAY command with the addition of the /LI switch which can specify an optional line number to continue execution. Example: 20 CHAIN "PROG2" 2.7 OVERLAY The OVERLAY command reads in additional program text from the speci- fied file and adds them to the existing program just as though they were typed from the keyboard: i.e. new statements with the same line number as an existing statement replace the existing statement. The same precautions regarding function definitions and DATA state- ments during debugging should also be observed when using the OVERLAY statement in program mode. The optional switch (/LI) is significant in program mode only and can be used to specify the line at which execution should resume. The /RT and /CO switches are the same as for the OLD command. Example: OVERLAY "PATCH1" 100 OVERLAY "PATCH2.BAS/LI:500" 2.8 LIST [N1][-N2][,N3...] This is primarily an immediate mode command. With no arguments, the whole program is listed at the user's terminal. Single arguments separated by commas will list only the line numbers requested. Two arguments separated by a dash (minus) will list an inclusive line number range. Example: LIST LIST 20 LIST 50,100 LIST 50-80,135,710-750 2.9 DELETE N1[-N2][,N3...] This also is primarily an immediate mode command. It will delete in- dividual lines with single parameters or inclusive ranges with numbers separated by a dash (minus). If no numbers are specified, the whole program text is deleted (but not program data - this must be done with the CLEAR command). It can be used in program mode al- so, usually to delete a range of line numbers in preparing to OVERLAY another routine. Example: DELETE 30 LOADING/RUNNING/SAVING PROGRAMS PAGE 2-4 02/13/81 DELETE 50-70 DELETE 10-40,60-80 2.10 EXIT This statement stops program execution and exits from BASIC to the MCR. All files are closed before exit. It is equivalent to a STOP followed by a ^Z from the keyboard. Example: 1000 EXIT 2.11 STEP [LINE #] This statement allows one to step through a program one line at a time. The optional line number may be used to start at a different line. If no line number is specified, execution resumes at the line following the last stop. Note that if a branch is taken the line be- ing executed, the program will not stop until the next line after the branch. The stop uses the same internal facilities as the ^B break feature. Example: STEP STEP 510 2.12 CON [LINE #] This command allows one to resume execution of a program after stop- ping it for interactive de-bugging. When used with the optional line number, it functions just like GOTO with the exception that the next available line after the one specified is used if there is no exact match. If no line number is specified, execution is resumed at the line following the last stop. Example: CON CON 100 02/13/81 CHAPTER 3 PROGRAM STATEMENTS The subset of commands listed in this chapter is primarily used to control the flow of program execution, reserve storage area for vari- ables, perform arithmetic calculations, etc. 3.1 GOSUB N . . GOTO N Transfers program control to statement N, where N can be a positive integer constant or an expression which will be truncated to an in- teger. Note that an expression will not produce correct results in the event of a resequence. Example: 10 GOTO 50 20 GOSUB A(I) 3.2 ON GOTO This statement transfers control to the Nth line number in the list. The expression is evaluated as a normal BASIC expression (floating point) and then truncated to get an integer value. If this value does not correspond to a line number in the list, a GOTO error hap- pens. The transfer is handled just as in the standard GOTO and GOSUB statements. Example: 100 ON I GOTO 1000,1200,1400 210 ON X-A(C1) GOSUB 2000,2100,3000 3.3 RETURN Returns to statement following GOSUB which got you here. Other statements may follow a gosub on a line. If the line containing a GOSUB is interactively modified while the subroutine is in the middle of executing, the GOSUB must occupy the same relative statement posi- tion in the line before and after the modification: i.e. it must be PROGRAM STATEMENTS PAGE 3-2 02/13/81 the first or third etc. statement in the line. Example: 10 RETURN 3.4 DIM Declares size of arrays and strings. Also specifies strings as ei- ther fixed or variable length. Arrays may have one or two sub- scripts. String lengths are indicated in square brackets [ ] which are fol- lowed by a 'V' if the string is to have variable length. In the case of a variable length string, the length is the maximum length which the string may assume. A string undeclared in a DIM statement is as- sumed to be varible length with a max of 15 characters. For strings declared in a DIM statement, the defaults are 15 character length (or max length) and fixed type. Arrays have a zeroth element which is the same as the unsubscripted variable name: i.e. B(0) or B(0,0) is the same as B. Unlike other versions of BASIC, arrays do not have any assumed dimensions; they must be declared if they are to be used. Example: 10 DIM A(5,5),B$[10] 20 DIM C$[20]V(10,10),D$(5) 3.5 DIM #N, This statement declares certain variables as "virtual arrays" and de- fines their allocation on the file whose LUN is the value of "exp". A virtual array has its values stored on a file and maintains only a small part of the array in memory at any one time (currently 512 bytes - 1 disk block). The DIM # statement only defines the mapping of the array onto the file. The file itself must be opened via an OPEN statement using the /BL switch. Consequently, several DIM # statements may define several mappings of different variables onto the same file with an effect similar to a FORTRAN EQUIVALENCE state- ment. The rules for mapping follow RSTS BASIC-PLUS. Essentially, no array element may cross block boundaries. This implies that variable sizes must be powers of two. Numeric variables automatically fulfill this condition. Strings are allocated their specified size whether fixed or variable. Variable length strings are null padded on disk, and when used in a program context are automatically trimmed to their size without the null padding. Fixed length virtual strings, as with standard fixed length strings, are blank padded. If the allocation of a variable in a DIM # list would cause it to cross block boundar- ies because of previous allocations in the list, it is started at the PROGRAM STATEMENTS PAGE 3-3 02/13/81 next disk boundary. Subscripts may range up to 32767 and string ele- ments up to 512 characters (in powers of 2). Example: 20 DIM #3,A(20,100),A$[256]V(5000) 30 DIM #3,B(20000),B$[128]V(10000) 40 DIM #7,X(100),Y(100),Z(200) 3.6 DEF One line function definition. The function name is formed with the letters FN followed by any legal variable name. e.g.: FNA, FNX1, FNM$ etc. Dummy arguments may be any numeric or string variable with any number of arguments subject to fitting on one line. The defini- tion itself may be any legal numeric or string expression including system and other user functions. Function names returning string values must end in '$', those return- ing numeric values must not. Functions are recursive, i.e. they may use themselves as arguments in the function call. Function definitions create an internal pointer to the ASCII text to the right of the equal sign. For this reason they should be placed near the beginning of the program to avoid being moved during debug- ging runs by insertions, deletions or changes to lines preceding the function definition. Function definitions are deleted by the CHAIN statement. Example: 30 DEF FNA1(A)=A2 40 DEF FNC$(X$)=X$+"ABC" 50 DEF FNZ3$(X$,I)=SEG$(X$,I,LEN(X$)) 3.7 LET This is the numeric assignment statement. It is also allowable for string assignment. The word itself is optional in this version of BASIC. A single variable name to the left of the '=' is given the value of the numeric or string expression to the right of the equal sign. Variable and expression types must match. Example: 20 LET A=EXP(10.34) 30 A$="ABC"+B$ PROGRAM STATEMENTS PAGE 3-4 02/13/81 3.8 IF Format: IF THEN [ELSE ][ELSE ] IF THEN " " IF GOTO " " If the logical expression is true (see Logical Expressions), then the line number following the THEN or GOTO is branched to or all state- ments following THEN up to the end of the line or an ELSE are execut- ed. If the condition is false, a matching ELSE is searched for. If found, the line number following the ELSE is branched to or all statements following the ELSE to the end of the line or the next ELSE are executed. If no matching ELSE is found, execution continues on the following line. IFs and ELSEs are paired like matching parentheses from the inside out. That is, an ELSE is matched with the IF most immediately preceding it in the line which does not already have a matching ELSE. This implementation of IF-THEN-ELSE is intended to match BASIC-PLUS. Example: 10 IF A > B THEN STOP 20 IF A$ <> B$ GOTO 110 ELSE 500 30 IF A >= 12.5 THEN 160 ELSE PRINT "A < 12.5" : GOTO 300 3.9 REM . . ! The REMark statement is used to insert comments into the text of the BASIC program. It has two forms: REM and !. All text following the REM or ! will be ignored by the BASIC interpreter up to the end of a physical line. No other statements may follow on the same line as they are treated as part of the comment. Example: 10 REM PROGRAM TO ADD ALL NUMBERS FROM 1 TO 10 20 ! AND DEMONSTRATE USE OF REM AND ! 3.10 READ . . DATA The READ statement inputs data from the DATA statement. The rules for INPUT apply to READ, but DATA lists are used as needed whereas INPUT inputs an entire line from a file. Example: 10 DATA 10.5,-76,1E7,FRANK 50 READ A,B,C,D$ PROGRAM STATEMENTS PAGE 3-5 02/13/81 3.11 FOR Format: FOR = TO [STEP ] This statement sets up and controls execution of a FOR-NEXT loop. Any numeric expressions may be used. The variable must be, however, a simple floating variable (no subscript). The statements following the FOR statement until the associated NEXT statement comprise the loop. The loop begins with the variable set equal to EXP1 and continues by incrementing the variable by EXP3 (de- faulted to one) until it reaches or passes the value of EXP2 (there- fore the loop may not be executed at all). Final value of the vari- able is its value the last time through the loop. NOTE Changing the value of the variable within the loop will af- fect the number of times the loop is executed. Example: 40 FOR I=1 TO 5.5 STEP .5 100 FOR J1=-.1 TO -1.5 STEP -.1 3.12 NEXT Format: NEXT This statement terminates the loop begun by the immediately preceding FOR statement with the same variable name. A concatenated form of two NEXT statements is shown in the second example. Note, however that it is not possible to branch to the second (implied) NEXT (NEXT J) without encountering NEXT I. Example: 70 NEXT I 100 NEXT I,J 3.13 BREAK This command causes all output accumulated in the terminal buffer to be printed in write-pass-all mode and with null carriage control. All carriage control must be supplied in the buffer by the program. In order to accumulate text in the terminal's buffer, PRINT state- ments with trailing commas or semicolons must be used. Note: Execution of the BREAK command does not affect the status of flags which are set or cleared by the SET command. Example: PROGRAM STATEMENTS PAGE 3-6 02/13/81 110 PRINT "START TAPE INPUT";CHR$(17); 120 BREAK 3.14 SET PROMPT/TRACE/READ-PASS-ALL ON/OFF This statement is used to set or clear a number of system conditions. The number of conditions is likely to increase in the future as func- tionality is added. Conditions now serviced include: TRACE, PROMPT and READ-PASS-ALL. SET TRACE is equivalent to the TRACE verb and should be used in preference to it because the TRACE verb is expected to disappear in future releases of this interpreter. The PROMPT con- dition is used to turn the INPUT and INPUT LINE question mark prompt on or off. The normal mode of processing is ON. The OFF mode is de- signed for special screen or page formatting and may be used in con- junction with the BREAK command. Example: 210 SET PROMPT OFF 220 SET TRACE ON 3.15 ON ERROR GOTO This statement sets the line number for a transfer on any type of er- ror. It does not cause any branching when it itself is executed, rather it changes the processing of errors in the BASIC interpreter. If this statement has been previously executed with a non-zero line number specified, no error message will be printed and a branch to the specified statement will be made. Normal error processing will be restored after the branch is made or by executing the statement with a zero line number. Thus at least one ON ERROR GOTO must follow the last error and precede the next one for user error handling to occur. This processing is designed to minimize the chance of an endless loop occurring because of an error in the error handling routine. Precise information as to the cause of the error can be had from the func- tions ERR, ERL, FCS detailed elsewhere. Examples: 100 ON ERROR GOTO 1500 510 ON ERROR GOTO 0 ! THIS RESTORES NORMAL ERROR HANDLING 3.16 SLEEP The SLEEP command causes the executing program to pause for the spec- ified amount of time. any valid arithmetic expression may be used to specify the time magnitude. However, a negative result will give an PROGRAM STATEMENTS PAGE 3-7 02/13/81 error and zero will be treated as a no-op. Truncation of the float- ing expression value will be used. The unit of time may be specified as TICKS, SECONDS, MINUTES, HOURS or any abbreviation of those words with the same first letter. No units specification will default to SECONDS. Examples: 510 SLEEP 10 SECONDS 105 SLEEP 2 M 632 SLEEP 25 3.17 WAIT The WAIT command sets parameters for the timeout of terminal input. The format is similar to the SLEEP command. Note that no explicit action is taken on execution of the WAIT command. It is used only to set the length of time to wait for terminal input before causing a timeout error trap. The user may check for the occurence of a timeout error by use of the ON ERROR GOTO command and then check the error code, currently 44. (decimal.) Appropriate action may be taken at this point (EXIT for example). The no timeout condition may be restored by using a magnitude of 0. Examples: 400 WAIT 40 S :! ALL TERMINAL INPUT TO TIME OUT AFTER 40 S 500 WATI 0 :! RESTORE TO NO TIMEOUT CONDITION 3.18 PRIORITY The PRIORITY command causes the interpreter to change its priority to that specified in the following expression. Priorities up to 100 are allowed. Example 500 PRIORITY 30 3.19 TRACE ON AND OFF This statement turns the trace feature on and off. When the trace is on, all transfers out of the normal flow of normal program execution are printed on the user's terminal. This can be used in either imme- diate mode or program mode (for selective tracing). Example: TRACE ON READY PROGRAM STATEMENTS PAGE 3-8 02/13/81 RUN OR 100 TRACE ON ... 200 TRACE OFF 02/13/81 CHAPTER 4 ARITHMETIC FUNCTIONS The functions listed in this chapter are primarily arithmetic in na- ture. They return arithmetic values or certain system values such as the Date or the Time. 4.1 RND This function returns a random number evenly distributed between 0 and 1. The dummy argument has no effect on the value returned. The sequence of numbers returned may be changed by using the RANDOMIZE statement. Example: 120 X=RND(0) 4.2 RANDOMIZE This statement resets the random number generator to a new starting point. The effect of this is to make successive runs of the same program return different values for the RND function. A program should first be debugged without the RANDOMIZE statement and then add it for production use. Example: 50 RANDOMIZE 4.3 ABS This function returns the absolute value of the numeric expression argument. Example: 10 A=ABS(A1+5) ARITHMETIC FUNCTIONS PAGE 4-2 02/13/81 4.4 SGN +1 returned if argument > 0; -1 if argument 0; 0 returned if argu- ment = 0. Example: 10 A=SGN(A1) 4.5 INT Returns greatest integer in the argument. Note: INT(-1.5)=-2 etc. Example: 10 A=INT(X) 4.6 LOG (NATURAL & BASE 10) LOG Returns the natural log of the value of the argument expression. Example: 30 A=LOG(X) LOG10 Returns the base ten (common) log of the value of the argument ex- pression Example: 50 B=LOG10(X) 4.7 EXP Returns the base e exponential of the argument value. Example: 10 A=EXP(X) 4.8 SIN COS These functions return the sine and cosine functions of the argument values. The input argument is in radians. Example: 20 S=SIN(X) 30 C=COS(Y) ARITHMETIC FUNCTIONS PAGE 4-3 02/13/81 4.9 ATN Returns the arctangent function of the argument value. The returned value is in radians. Example: 10 A=ATN(X) 4.10 SQR Returns the square root of the argument value. If the argument value is negative, an error is given. Example: 20 S=SQR(X) 4.11 NRC This function calculates the number of records in the file number which is specified in the argument. The file must be a fixed length record type. A -1 returned indicates a non-existent FDB. A -2 re- turned indicates variable length records. Example: 10 A=NRC(4) 4.12 ERR . . ERL . . FCS These functions return respectively: the number of the last error, the line number of the last error, and the FCS error code (negative) for the last FILES-11 related error. An argument for the function must be included atlhough it will usually be zero. If a non-zero ar- gument is used, it will be treated as a word offset from the inter- preter location containing the normal information for that function. Thus a non-zero offset should only be used in conjunction with a map and assembler listing. Example: 100 A=ERR(0) 110 B=FCS(0) 120 CON ERL(1) 4.13 COR This function returns the free core (in bytes) minus the value of the argument. Example: ARITHMETIC FUNCTIONS PAGE 4-4 02/13/81 100 A=COR(255) 4.14 DAT$ An 8 character string is returned containing the date in the form MO/DA/YR. if the argument is absent or a single character zero, the system date (today's date hopefully!) is returned. If the argument is a positive value, the number is interpreted as the day of the cen- tury, and a corresponding date string is returned. The positive ar- gument is interpreted modulo 36524 (the number of days in a century). If the argument is a zero or negative value (other than a single character '0'), then a null string is returned. Example: 50 A$=DAT$(0) : ! RETURN SYSTEM DATE 60 PRINT DAT$(12752) 70 A$=DAT$() : ! RETURN SYSTEM DATE 4.15 DDAT$ This function returns a string containing the DEC standard date in the form: DD-MMM-YY. The string may be either 8 or 9 chars depend- ing on the number of digits in the day. The argument is interpreted in the same way as in the DAT$ function. Example: 40 A$=DDAT$(0) 4.16 TIM$ Returns time in an 8 character string in the form HR:MN:SC. If the argument is absent or a single character zero, the system time is re- turned. Otherwise, the argument is evaluated. If negative, a null string is returned; if zero or positive, the number is interpreted as the number of seconds since midnight and the corresponding time is returned as a string. The number is interpreted modulo one day worth of seconds. Example: 30 A$=TIM$(0) 40 A$=TIM$() : !RETURN SYSTEM TIME 50 A$=TIM$(A-B) : ! RETURN TIME OF DAY CORRESPONDING TO ! A-B SECONDS SINCE MIDNIGHT ARITHMETIC FUNCTIONS PAGE 4-5 02/13/81 4.17 DCEN This function accepts a single string date argument and returns a number which is the day of the century. The date argument may be the common slash notation of MM/DD/YY, the DEC standard notation of DD-MMM-YY or the undelimited form of MMDDYY. The resulting number is the number of the day in the century with 1 corresponding to 1-Jan-00, and 36524 corresponding to 31-Dec-99. This number is thus suitable for calculating differences between two dates. A thorough check is made of the date string before the conversion and an error code will be returned instead of the day of the century in case of an error. Therefore this function may be used to verify dates which are input from a user program. This routine is programmed to account for 24 leap years per century, omitting a leap year during the '00' year. The error codes returned are as follows: 0 = Null string supplied -1 = Bad date format -2 = Bad day of month -3 = Bad month (not in range 1-12) -4 = Bad year (not in range 0-99) Examples: 150 A=DCEN("12/15/46") 160 B=DCEN("5-AUG-72") 170 C=DCEN(DDAT$(0)) 180 D=DCEN("121546") 4.18 SEC This function accepts a single string time argument and returns a number which is the number of seconds since midnight. The time string must be in the form HH:MM:SS in 24 hour notation. The string is checked for validity and if valid, a positive (or zero) numeric value is returned. If an error is detected, a negative or zero value is returned as follows: 0 = Null string argument (or 00:00:00) -1 = Bad time format -2 = Bad seconds -3 = Bad minutes -4 = Bad hours Examples: 210 A=SEC("12:05:31") 220 B=SEC(A$) 02/13/81 CHAPTER 5 STRING FUNCTIONS The functions listed in this chapter are primarily character string oriented. They provide wide capability for examining and altering variables which contain character strings, and for conversion from/to other data formats. 5.1 INX . . POS Format: POS(STRING1,STRING2 [,P1] [,P2]) This function computes the position of STRING2 in STRING1 starting at optional position P1 (P1 assumed to be 1 if not specified). A second optional parameter P2 specifies the final character position. If it is not specified, it is assumed to be the end of the first string. INX and POS are identical. Example: 10 A=POS("ABC","B") 20 X=POS(A1$,A2$,5,7) 5.2 LEN This function computes the length of a single string expression argu- ment. Example: 30 X=LEN(A$) 5.3 VAL This function takes an ASCII string containing a legal numeric ex- pression and returns a floating point value. Example: 10 A=VAL(A$) STRING FUNCTIONS PAGE 5-2 02/13/81 5.4 OCT This function takes an ASCII string containing a legal octal integer representation and returns a floating point value. Example: 10 A=OCT("1777") 5.5 AR5 This function returns a numeric value corresponding to the DEC RAD50 conversion of the first three characters of the argument string. If less than three characters are supplied, the result is as if the in- put were blank padded at the end. All legal RAD50 characters includ- ing blank and period are converted. Example: 100 A%=AR5("ABC") 110 B1=AR5(A$+B$) 5.6 ASC This function returns the numeric value of the first ASCII character in the string argument. For a null string, 0 is returned. Example: 10 I=ASC("A") 5.7 CHR$ Routine to return a one character string corresponding to a numeric ASCII value. Example: 10 LET A$=CHR$(65) 5.8 SEG$ SBS$ RIGHT LEFT MID Format: SEG$(STRING,A[,B]) SBS$(STRING,A[,B]) MID(STRING,A,[B]) RIGHT(STRING,N) LEFT(STRING,N) Where 'STRING' is a legal string expression and A is the first char- acter in the string to be selected. In SEG$, B is the last character to be included in the output string; in SBS$, it is the number of STRING FUNCTIONS PAGE 5-3 02/13/81 characters to include. If not specified in either case all char- acters to the end of the string are included. A null string is re- turned when the first character position is not within the source string. When the ending position or length places one beyond the end of the source string, all characters to the end are included with no blank fill. If the first position is after the final, a null string is returned. If A is less than 1 a null string is returned. If B places the final character position past the end of the string, it is as though the ending position was specified. RIGHT LEFT and MID are provided for compatibility with other versions of BASIC (in particular RSTS BASIC-PLUS). Note that the names are not followed by '$' even though the results are string values. These functions return the right-most or left most N characters of the string respectively. MID returns B characters, starting at position A, and is thus a synonym for SBS$. Note that some BASIC RIGHT func- tions return the N thru end characters of the string. If programs expect this action, the RIGHT(N) function should be replaced by a SBS$(N) function. Example: 10 A$=SEG$(B$,1,5) 30 X$=SBS$(Y$,6) 5.9 PIECE$ Format: PIECE$(STRING1,STRING2,N1 [,N2]) PIECE$ inspects a specified string (STRING1) and takes from it that substring which lies between two specified occurrences of a particu- lar dividing string (STRING2). The resulting substring begins imme- diately after the N1 minus one occurrence of the dividing string and ends immediately before the N2nd occurrence (or N1st if N2 is unspec- ified). Example: 110 M$=PIECE$("12/1/77","/",1) :! EXTRACT MONTH FROM STRING 120 A$=PIECE$("12/1/77","/",1,2) :! EXTRACT MONTH AND DAY 5.10 STR$ Numeric to character string conversion. (No leading or trailing blanks.) The Ascii string represents the value of the argument. Format: STR$(X) Where 'X' is any legal numeric expression. Example: 30 A$=STR$(EXP(X)+1.4) STRING FUNCTIONS PAGE 5-4 02/13/81 5.11 LTR$ TRM$ Leading and trailing blank trim functions. The resulting string is the argument string without leading blanks for LTR$ or without trail- ing blanks for TRM$. Example: 30 A$=LTR$(A$) 40 B$=TRM$(C$) 5.12 OCT$ OCS$ A single numeric argument is converted to ASCII representation of an octal integer. The numeric expression is evaluated and truncated to an integer prior to conversion. OCT$ produces an unsigned string, while OCS$ produces a signed string. Magnitudes are limited to those representable in one PDP-11 word. Example: 40 PRINT OCS$(-53) 50 PRINT OCT$(I*16) 5.13 R5A$ The RAD50 source value (value range of one integer word) is converted to a 3 character string. Example: 110 A$=R5A$(A) 120 B$=R5A$(X%) 5.14 FRMT$(X,W[,D]) This function creates a string from a number allowing control over the total number of digits and the number of digits to the right of the decimal point. The value to be converted is X, the number of to- tal digits (including sign and decimal point) is W and the number of digits to the right of the decimal point is D. If D is unspecified, then the number produced is an integer with no decimal point. If D is zero, then the number produced will have a decimal point but no numbers to the right. If a negative number is given for D, then the output will be filled with W asterisks unless W is zero or less. If W is less than or equal zero, in any case then a null string will be returned. If W is positive non-zero and unable to fit the number, a string of W asterisks will be returned. Note that meaningless digits will be produced if more than 6 or 7 are asked for. If only signifi- cant digits are wanted, use STR$. Numbers are rounded for printout. STRING FUNCTIONS PAGE 5-5 02/13/81 Example: 130 A$=FRMT$(A+6,5,2) 140 B$=FRMT$(12.75+Z1,7) 5.15 RJS$ . . LJS$ Format: RJS$(B$,I) LJS$(B$,I) Where I is the length of the returned string with B$ right or left justified in it and with leading or trailing blank fill if necessary. If B$ is longer than I characters, then the rightmost or leftmost I characters will be returned. Example: 40 A$=RJS$(B$,9) 70 A$=LJS$(B$,5) 5.16 SPACE$ . . STRING$ Format SPACE$(I) STRING$(C$,I) Where I is the length of the string to be created. In the case of SPACE$, a string of blanks is created. For STRING$, a string of characters matching the first character of C$ is created. If I is zero or negative, a null string is returned. Examples: 120 A$=SPACE$(40) 130 B$=STRING$("-",40) 5.17 TAB The TAB function is used only in the print statement to space to a given column (the value of the numeric argument). The column speci- fied is the one in which subsequent printing will begin. Columns are numbered starting with 1. If the specified column is greater than the width of the device being printed on, the tab is calculated modu- lo the device width. If the specified column is less than the cur- rent print position, the function is ignored. TAB is ignored on bi- nary output files. Example: 10 PRINT A;TAB(20);A$ 02/13/81 CHAPTER 6 I/O & FILE MANIPULATION The commands listed in this chapter are primarily concerned with In- put and Output. They provide the capability of opening files, read- ing/writing data in various formats, and closing the files when done. 6.1 RESTORE Resets data pointer to start of data statements. For files, the RE- STORE statement may be followed by a # sign and an arithmetic expres- sion giving the file number. A sequential file open for read only will be reset to the start. To read a sequential file currently be- ing written, it is necessary to close and then re-open for read. Example: 10 RESTORE 6.2 PRINT Print statement. Format: PRINT [#N,]V1,V2,V3 etc. or PRINT #N@R,V1,V2,V3 etc. Where N is an optional file number and V1, V2, V3, etc. are any le- gal numeric or string expression. In the second form R is a random access record number expression. It may have any value up to the maximum allowed in a double precision signed integer. Floating point values are truncated before use. The file N must have been opened for random access via the /RN switch in the OPEN statement. When expressions are separated by commas, results are printed in fields of 14 characters each. When expressions are separated by sem- icolons, results are printed next to each other without any spaces added. A trailing semicolon will suppress . When printing with comma separation, as many fields are allowed as can fit on the printing device. Note that numeric values, when converted in a PRINT statement normally have a space at each end. To avoid this, use the STR$ function. I/O & FILE MANIPULATION PAGE 6-2 02/13/81 On binary files, the following conditions hold: TAB is ignored, no "field" justification is performed and all data list items must fit into the existing buffer. Floating values are stored as four conse- cutive bytes which are not word aligned. Strings and numeric values are packed together and may be combined in any order. It is up to the user to keep track of the internal storage arrangement for future use with INPUT or other non-BASIC programs. A synonym for PRINT is "?" primarily for convenience in immediate mode use. Example: 50 PRINT A,3.5,"HELLO";A$ 60 PRINT #3,EXP(.5);XY; 6.3 INPUT Format: INPUT [#N,] V1,V2,V3 etc. or INPUT #N@R,V1,V2,V3 etc. Where N is an optional file number and V1, V2, V3 etc. are legal string or numeric variable names. The second form follows the rules for random access described for the PRINT statement. Numeric data must be separated by commas or spaces, successive string variables must be separated by a comma after the required number of characters have been typed in. A character legality check is performed to en- sure that all characters are between octal ASCII codes 40 and 137 in- clusive and 11 (tab). For input from the terminal (no file number), a prompt string (only string defined in quotes allowed) may be specified before the vari- able list. This is equivalent to a PRINT followed by an INPUT. See third example below. For binary files the following conditions hold: four bytes are used for each numeric (floating) variable, strings use as many bytes as they have been dimensioned for. More data than variables is not con- sidered an error. Insufficient data is an error with the following exception: a variable length string will have its length shortened to the available data if data runs out, and a fixed length string will be blank filled. If data runs out while filling a numeric vari- able, the results are unpredictable and in any case terminate the program with an error. Example: 30 INPUT #3,A1,B1$ 50 INPUT #4@R+5,X1,X2,A1$ 80 INPUT "WHAT IS YOUR NAME",N$ : ! READ NAME INTO N$ I/O & FILE MANIPULATION PAGE 6-3 02/13/81 6.4 INPUT LINE This is the same as the input statement except that only string vari- ables are permitted in the input list and no character checking is performed. Thus no delimiters are recognized and string variables are filled sequentially to their dimensioned length whether fixed or variable. Random access is the same as for INPUT. For binary files INPUT LINE is the same as INPUT. Example: 30 INPUT LINE #3,A1$ 6.5 SCRATCH The SCRATCH command must have a file specifier with an explicit ver- sion number in order to delete a file. The default file specifier is: SY:PROGRAM.BAS Example: SCRATCH "DATA.DAT;3" 50 SCRATCH "DK1:DAT3.TMP" 6.6 OPEN OPEN command processor. Form: OPEN #EXP,STRING (WHERE STRING CONTAINS FILESPEC/SWITCHES) Allowed switches: /FX for FIXED LENGTH records (VARIABLE assumed) /RN for RANDOM ACCESS (SEQUENTIAL assumed) /LN:LEN to specify buffer length in bytes (80 assumed) /EN:LNO to specify line no. for control xfer on EOF /BN to specify BINARY file (ASCII assumed) /BL for virtual array files (not to be used with above) The following switches specify file access They are mutually exclusive except for /SH (shared access): /RO for read only access (default) /WR for write access (creating new file) /UP for update (read,write,append) /MO for modification (read,write) /AP for append only /SH to set shared access bit in FDB Possible values of EXP range from 3 to 16. Up to 6 record type files (not /BL) may be open simultaneously. Any number of block mode files (up to 14) may be open simultaneously subject only to total memory availability. The default device for all LUNs is SY0:. Examples: 50 OPEN #4, "LP:/WR" 60 OPEN #3,N$ I/O & FILE MANIPULATION PAGE 6-4 02/13/81 6.7 CLOSE N1[,N2...] This command closes a user data file whose number is N1, N2 etc. Note that no # sign precedes the number. If used with no file number, all user files are closed. Example: 60 CLOSE 4 70 CLOSE I1 95 CLOSE 6.8 IF END [#N] THEN This statement is used to reset the end of file branch on a given file or without the "#N", it sets the terminal end of file branch. The specified file must have been opened with the possibility of be- ing read from (i.e. cannot be /AP or /WR in sequential mode). Examples: 100 IF END THEN 1500 :! SET TERMINAL END OF FILE LINE NO. 120 IF END #3 THEN 2100:! SET END OF FILE LINE NO. ON LUN 3 02/13/81 CHAPTER 7 LOADABLE SUBROUTINES This chapter is primarily concerned with the operation of user writ- ten MACRO subroutines. The capability of calling a machine language subroutine to perform some complex calculation can provide much simpler program operation, and/or significantly increase the speed of operation. Several special MACRO subroutines proved so useful that they were made a permanent part of BASIC and as such do not have to be loaded. Those routines are listed in this chapter. A sample of a MACRO subroutine which will reverse a character string along with a description of the internal BASIC subroutines it uses is included in Appendices B & C of this manual. 7.1 LOAD This command loads the specified file as a user callable subroutine. The default extension is BTK. See Append. B for a sample user load- able subroutine Example: 610 LOAD "REVERS" 7.2 UNLOAD This command unloads all user assembly routines loaded by the LOAD command. Example 500 UNLOAD LOADABLE SUBROUTINES PAGE 7-2 02/13/81 7.3 CALL "NAME"(ARG1,ARG2,...) The CALL statement is used by the BASIC user to call specially writ- ten MACRO subroutines which will perform special functions. The called routine name must be enclosed in quotes as above, or reside in a string expression which is enclosed in parentheses. The NAME may be up to 6 characters in length. The enclosing parentheses are ne- cessary to keep the argument list which follows from appearing as a subscript to a string variable. The arguments can be string or numeric variables or expressions. In the case that a value is to be returned, the argument must be a sim- ple variable (may be subscripted). For values which are passed, ei- ther expressions or variables may be used. The variables and expres- sions used in the argument list must match the type (string or numer- ic) expected by the subroutine. User routines must preserve the text pointer (R1) and on exit, if an argument list is present, must position it just past the close paren- thesis. See APPEND. B for a sample loadable routine. Example: 100 CALL "ABC"(A$,B) 120 CALL (B$)(A-X,Y$+Z$) 7.4 INSTRG Subroutine to insert a string into another string. BASIC CALL: 120 CALL "INSTRG"(S$,E$,P [,L]) WHERE: S$ = STRING VARIABLE INTO WHICH INSERTION IS MADE E$ = STRING EXPRESSION TO BE INSERTED P = POSITION TO START INSERTION L = OPTIONAL MAX LENGTH OF INSERTION If L is not specified, the length of E$ is used by default for the length of the insertion. If L is specified, justification of E$ in a field of that size is performed. A positive value is left justify, negative means right justify. This routine is at least three times as fast as the "cut and paste" method using the SBS$ function. If the "cut and paste" is formatted as a user defined function, the speed increase is a factor of seven. Therefore it is almost always preferable to the SBS$ method. 7.5 OPEN LIBRARY Format: 50 OPEN LIBRARY #N, This command functions similarly to the standard OPEN command except that a MACRO library file is opened for question text output and oth- LOADABLE SUBROUTINES PAGE 7-3 02/13/81 er question processing subroutines invoked by the CALL statement. A LUN must be used that is not already in use and is one of the allow- able numbers as for the standard OPEN. No switches are allowed as all file options are determined internally for handling the library format. Example: 100 OPEN LIBRARY #5,"QUESLS.MLB" 200 OPEN LIBRARY #3,A$ 7.6 QUESTION DISPLAY A series of routines can be used for displaying questions at a termi- nal for interactive data entry applications. The text of the ques- tions themselves resides in a file made by the RSX librarian (LBR) and formatted as a MACRO library (.MLB extension). There are three types of questions that can be displayed: 0) Multi-line text display 1) Single line question (text input) 2) Multiple choice display The questions are formatted as macros with the name of the question being the name of the macro. There is a single argument to the ma- cro, a number which is the type as specified above except in the case of type 2, it is the total number of choices for that multiple choice question (can never be less than 2). The question names are used for linking of multiple choice questions and for question replacement by the librarian. Question names may be up to 6 characters in length. The characters must be legal RAD50 characters i.e. alphanumeric, period and dollar sign. After dis- play, the input of a response is left to the user program. MULTI-LINE TEXT The multi-line text question (need not be an actual question) is re- produced exactly as entered with the carriage (cursor) positioned to the start of the next line. The text display is terminated when the .ENDM directive is encountered as the first entry on a line other than space or tab. Type code is 0. Example: .MACRO MULTXT 0 THIS IS AN EXAMPLE OF A MULTIPLE LINE TEXT QUESTION. IT MAY BE USED AS A QUESTION OR JUST TO PRINT OUT SOME INFORMATION FOR THE PROGRAM USER. ANY NUMBER OF LINES MAY BE USED. .ENDM SINGLE LINE QUESTION This type of question is usually used to solicit text information LOADABLE SUBROUTINES PAGE 7-4 02/13/81 from the user (name, age etc.). Only one line is printed and the carriage (cursor) is positioned at the end of the line. Any further lines of text entered for this question type will not be displayed. Example: .MACRO SINGLE 1 TYPE YOUR NAME: LAST, FIRST .ENDM MULTIPLE CHOICE QUESTION This type of question is used to solicit a number response which is selected from a finite set of choices displayed to the user. A succeeding question may be selected depending on the response to the displayed question. Thus multiple choice branching structures may be set up. The character used to separate the response text from its associated branching question name is the backslash. The number of choices is the number following the question name in the .MACRO line. Example: .MACRO MULCHC 3 SELECT YOUR STATE OF MIND GOOD\MULCH1 FAIR\MULCH2 TGIF\MULCH3 .ENDM COMMON INFORMATION FOR ALL QUESTION PROCESSING CALLS Sbroutines are provided in three different forms to perform a number of different functions. The functions are as follows: 1) Display question 2) Position to question 3) Return question text 4) Return answer text 5) Return question name The three forms of the subroutines are as follows: 1) 'M' form: perform function by name 2) 'C' form: perform function on question linked to prev. quest. 3) 'R' form: perform function on last question accessed In general the 'M' form and 'C' form of the subroutines reset the last question accessed. The 'R' form, since it acts on the last question accessed, does not change it. The one exception is the 'C' form of the return question name function (CQNAM). It does not change the last question accessed. The 'M' form of the subroutines uses a name specified as an input string argument (3rd parameter) to position to the specified question and then perform the required action. The 'C' form uses the last question accessed (positioned to) in order to position to another question. To do this, the last question must have been a multiple choice question and a link must be provided for the answer number specified as the third parameter in the subroutine call. LOADABLE SUBROUTINES PAGE 7-5 02/13/81 The 'R' form uses the previously accessed question (whether by 'M' or 'C') to perform its action. The third parameter is a dummy numeric parameter. GENERAL PARAMETERS Following is a description of the symbolic parameter names used in describing the various subroutine calls. They are, of course, re- placed in the actual calls by legal BASIC expressions in the case of input values and by legal variable names in the case of output va- lues. LUN: Input value containing LUN used in OPEN LIBRARY command STATUS: Output value returning status of action requested +2 or greater = max response # for multiple choice ques. +1 = question was a text input type (single line) 0 = question was multi-line info display -1 = LUN not found (OPEN LIBRARY not done on this LUN) -2 = FCS error during read -3 = Question not found (for a variety of reasons) NAME$: Input string containing question name ('M' type) ANS: Input numeric value with answer to prev. ques. ('c' type) DUMMY: Dummy numeric input ('R' type) NOTE The value of -3 returned for STATUS can indicate a variety of conditions. For 'M' type calls, it means the speciied ques- tion name is not present in the library file. For 'C' type calls, it will be returned if the previous question was not a multiple choice type, if no linked question was recorded for the specified answer, or if the linked question specified was not present in the library. 7.7 MDIS . . CDIS . . RDIS DISPLAY QUESTION SUBROUINES Formats: CALL "MDIS"(LUN,STATUS,NAME$[,STRING$,COUNT]) CALL "CDIS"(LUN,STATUS,ANS[,STRING$,COUNT]) CALL "RDIS"(LUN,STATUS,DUMMY[,STRING$,COUNT]) The named question, linked question or previous question will be dis- played respectively by the above three subroutine calls according to the following rules. If the optional parameters are not specified: MULTI-LINE INFO DISPLAY: Text is displayed as typed. Carriage (cur- sor) is positioned to the start of the next line. All lines up to the line with a leading .ENDM directive will be displayed. LOADABLE SUBROUTINES PAGE 7-6 02/13/81 SINGLE LINE TEXT INPUT: The line of text is displayed with the car- riage (cursor) to the immediate right of the text just displayed. Any spaces required after the text must be either included in the question text or added from the program via a PRINT statement. MULTIPLE CHOICE QUESTION: For this type question the first line is displayed as typed. Subsequent lines are displayed with a leading space and a number which starts at one and increases by one for each succeeding line. The number is then followed by a right parenthesis ')' and another space and then the text for that line. After all lines have been displayed, the carriage (cursor) is then positioned to the start of the next line. NOTE The total number of lines displayed is the number given as the argument on the .MACRO line plus one and is independent of where the .ENDM line occurs. This may lead to not displa- ying all of the typed in question text or the output of gar- bage if the question has not been typed in properly. If the optional parameters are specified (both must be present), the following holds: MULTI-LINE INFO DISPLAY: If N is the number specified in COUNT, then the text is displayed preceded by N characters of STRING$ for each line until the characters in STRING$ are exhausted or the display is complete (normally these should happen together). SINGLE LINE TEXT INPUT: The line of text is displayed as before but with N chracters of STRING$ preceding it. MULTIPLE CHOICE QUESTIONS: In this case the first line is displayed as above, but the subsequent lines (answers) are each preceded by N characters from STRING$. 7.8 MPOS . . CPOS . . RPOS POSITION TO QUESTION SUBROUTINES Formats: CALL "MPOS"(LUN,STATUS,NAME$) CALL "CPOS"(LUN,STATUS,ANS) CALL "RPOS"(LUN,STATUS,DUMMY) In the first two cases, a new question is positioned to (accessed) and a status (count) value returned. In the last case, the position- ing remains unchanged, but the status (count) is returned. LOADABLE SUBROUTINES PAGE 7-7 02/13/81 7.9 MQTXT . . CQTXT . . RQTXT RETURN QUESTION TEXT SUBROUTINES Formats: CALL "MQTXT"(LUN,STATUS,NAME$,STRING$) CALL "CQTXT"(LUN,STATUS,ANS,STRING$) CALL "RQTXT"(LUN,STATUS,DUMMY,STRING$) The question text of the named, linked or current question is re- turned in the variable STRING$ (must be a single variable name). In the case of a multi-line info display (type 0), the first line is re- turned. 7.10 MATXT . . CATXT . . RATXT RETURN ANSWER TEXT SUBROUTINES Formats: CALL "MATXT"(LUN,STATUS,NAME$,STRING$,ANS1) CALL "CATXT"(LUN,STATUS,ANS,STRING$,ANS1) CALL "RATXT"(LUN,STATUS,DUMMY,STRING$,ANS1) The text corresponding to ANS1 is returned in STRING$ for the named, linked or current question. In the case of a multi-line info dis- play, the first answer corresponds to the second line of text and so on. Note that there is no way to discern in advance how many lines there are in this case. Thus the user program should test for the presence of '.ENDM' in the returned line. No internal restraints are placed on the value of ANS1 and so parts of following questions may be returned if care is not exercised. 7.11 CQNAM . . RQNAM RETURN QUESTION NAME SUBROUTINES Formats: CALL "CQNAM"(LUN,STATUS,ANS,STRING$) CALL "RQNAM"(LUN,STATUS,DUMMY,STRING$) In the first case, the name of the question linked by ANS is returned in STRING$. Note that the linked question is not positioned to, thus enabling a user program to record multiple linked names without hav- ing to reposition to the original question. In the second case the current question name will be returned in STRING$. 7.12 SPAWNB Subroutine to spawn a task using the IAS spawn directive. FORMAT: CALL "SPAWNB"(C$ [,S]) This routine passes the MCR command line in C$ to the operating sys- tem. Commands to another BASic program, PIP, etc may be passed in the command line just as with MCR. The exiting status of the spawned task is returned in the (optional) variable S. LOADABLE SUBROUTINES PAGE 7-8 02/13/81 If the STATUS variable is present, the issuing BASIC program will STOP, and continue when the SPAWNED task exits. If no STATUS vari- able is present in the call, BASIC execution continues immediately. During the time that BASIC is STOPPED for the SPAWNED task, control-C's will not have the normal effect. Also BASIC detaches the terminal so PIP lists to the terminal etc. can occur. NOTE SPAWN knows about things like DIR, PRInt, etc., but the task in question must be installed in the system. The auto-install function for infrequently used tasks does not work for SPAWNB. If SPAWN detects that the requested task is unavailable, it returns the system failure status (currently -2 -- Task not installed.) 02/13/81 APPENDIX A BASIC ERROR VALUES 0. USER STORAGE OVERFLOW 1. UNRECOGNIZED STATEMENT - CHECK SPELLING 2. ILLEGAL GOTO OR GOSUB 3. ILLEGAL CHARACTER IN OR TERMINATING INPUT LINE 4. RETURN WITHOUT GOSUB 5. BADLY FORMED SUBSCRIPT 6. SUBSCRIPT OUT OF RANGE 7. MISMATCHED PARENTHESES 8. ILLEGAL LET STATEMENT 9. ILLEGAL RELATIONAL OPERATOR IN IF 10. ILLEGAL IF 11. ILLEGAL PRINT 12. DEVICE OR FILE ERROR %D ON INPUT 13. BAD DIMENSION 14. NOT ENOUGH ROOM IN STORAGE FOR THE ARRAY 15. BADLY FORMED DEFINE 16. ILLEGAL LINE NUMBER OR DIMENSION VALUE 17. DIM OF PREVIOUSLY USED VARIABLE NAME 18. BAD VARIABLE IN INPUT LIST 19. BAD VARIABLE IN READ LIST 20. OUT OF DATA DURING READ 21. BAD DATA IN A DATA STATEMENT 22. ILLEGAL FOR STATEMENT 23. NO NEXT WITHOUT MATCHING FOR 24. NEXT WITHOUT FOR 25. UNMATCHED QUOTES IN STATEMENT 26. EXTERNAL FUNCTION NOT PROPERLY SET UP 27. BADLY FORMED EXPRESSION 28. ERROR IN COMMAND STRING INTERPRETER 29. SBS FUNCTION ERROR 30. SYNTAX ERROR IN FUNCTION 31. SYNTAX ERROR IN OPEN 32. SYNTAX ERROR IN CLOSE 33. INVALID FILE NUMBER 34. END OF FILE ERROR 35. FCS ERROR %D DURING CLOSE 36. FCS ERROR %D DURING OPEN 37. ERROR DURING CALL PROCESSING 38. ERROR IN CALL ARGUMENT LIST 39. ERROR IN STORE DURING CALLED ROUTINE 40. SYNTAX ERROR OR LUN IN USE IN LIBRARY OPEN 41. FCS ERROR %D DURING LIBRARY OPEN OR 1ST READ BASIC ERROR VALUES PAGE A-2 02/13/81 42. SYNTAX ERROR IN SLEEP COMMAND 43. SYNTAX ERROR IN WAIT COMMAND 44. TIMEOUT ERROR - YOU WAITED TOO LONG TO TYPE 45. PRIORITY ERROR 46. BASIC PROGRAM FILE ERROR %D 47. FILE ACCESS MODE ERROR (SEQ/RAN) 48. ERROR IN LOADED USER SUBROUTINE 49. VIRTUAL ACCESS ERROR - FCS %D 50. VIRTUAL FILE OPEN ERROR - FCS %D 51. ERROR IN SET COMMAND 52. USE OF "/CO" SWITCH WITH NORMAL BASIC SOURCE 53. IMMEDIATE MODE COMMAND IN SOURCE TEXT 62. DEBUG #1 AT R3=%P 63. DEBUGGING ERROR #2 - CALL SYSTEM MANAGER 64. LOG OF NEGATIVE OR ZERO NUMBER 65. SQUARE ROOT OF NEGATIVE NUMBER 66. FLOATING DIVIDE BY ZERO 67. NUMBER TOO LARGE TO FIX 68. FLOATING OVERFLOW 69. FLOATING UNDERFLOW 70. NON-EXISTENT VARIABLE 71. TOO MUCH DATA TYPED 72. NOT ENOUGH DATA TYPED 73. ILLEGAL CHARACTERS ON INPUT 74. ERROR IN VALUE FUNCTION 75. NOT ENOUGH DATA TYPED 76. ILLEGAL CHARACTERS ON INPUT 77. ERROR IN VALUE FUNCTION 78. SYNTAX ERROR IN FUNCTION 79. SYNTAX ERROR IN OPEN 200. FLOATING OVERFLOW 202. FLOATING UNDERFLOW 211. LOG OF NEGATIVE OR ZERO VALUE 212. SQUARE ROOT OF NEGATIVE VALUE 02/13/81 APPENDIX B SAMPLE LOADABLE MACRO SUBROUTINE ; ; TEST SUBROUTINE FOR BASIC LOAD COMMAND ; ; THIS SUBROUTINE SHOULD REVERSE A STRING ; ; CALL IS CALL "REVSTR"(IN$,OU$) ; ; WHERE IN$=STRING TO BE REVERSED ; OU$=RESULTANT STRING ; ; IDENTIFYING INFO: .MCALL ULODHD ;CALL MACRO ;IDENTIFY START OF CODE, END OF CODE ;AND ONE ENTRY POINT ULODHD REVSTR,END,REVSTR ; ; NOW THE CODE ITSELF ; ; REVSTR: ;LABLE ACTUAL START OF CODE JSR R4,@#GTRGPI ;GO GET ARGUMENTS IN PI FASHION .BYTE 3,4,0 ;THIS IS ARG TYPE LIST ;3 = INPUT STRING (TO SUBROUTINE) ;4 = OUTPUT STRING (TO MAIN PROG.) .EVEN ;WE NOW HAVE THIS DATA ON THE STACK ;SP+4 5-WORD STRING TABLE ENTRY ; FOR OUTPUT STRING ;SP> 2-WORD INPUT DESCRIPTOR ; (SP)=LEN, 2(SP)=ADDR JSR PC,@#PARCHK ;CHECK FOR TRAILING RIGHT PAREN ;(ALSO BUMPS TEXT POINTER) MOV R1,-(SP) ;SAVE TEXT PTR MOV 2(SP),R0 ;LEN OF INPUT STRING -> R0 BEQ 3$ ;IF ZERO, BRANCH JSR PC,@#TSTU00 ;CHECK FOR ROOM IN USER STORAGE AREA ;WIPES R3,R4, ;R5 -> NEXT BYTE IN USER STORAGE AREA BHI 1$ ;BRANCH IF ROOM EXISTS OVFERR ;ELSE DO ERROR TRAP 1$: MOV R0,R4 ;SAVE LENGTH IN R4 BIS #160000,R0 ;MAKE R0 A "SCRATCH" DATA TYPE HEADER SAMPLE LOADABLE MACRO SUBROUTINE PAGE B-2 02/13/81 MOV R0,(R5)+ ;PUT HEADER IN USER AREA MOV R5,R2 ;SAVE STRING ADDRESS (IN USER AREA) MOV 4(SP),R3 ;ADDRESS OF INPUT STRING -> R3 MOV R4,R0 ;STRING LENGTH -> LOOP COUNTER ADD R4,R3 ;BUMP R3 PAST END OF INPUT STRING 2$: MOVB -(R3),(R5)+ ;REVERSE THE STRING SOB R0,2$ MOV R2,R3 ;OUTPUT STRING ADDRESS -> R3 ;STRING LENGTH STILL IS IN R4 3$: MOV SP,R5 ;GET ADD OF RETURN ARG DESCRIPTOR ADD #6,R5 ;IN R5 JSR PC,@#SSTORE ;AND RETURN THE RESULT TO THE CALLER MOV (SP)+,R1 ;RESTORE TEXT PTR ADD #7*2,SP ;CLEAN STACK OF 7 WORDS RTS PC ;AND RETURN END: ;LABLE END OF CODE .END MACRO COMMAND FILE REVSTR,REVSTR/-SP=LB:[1,202]LOAMAC/ML,[1,202]REVSTR TKB COMMAND FILE REVSTR.ATK/-HD/-FP,REVSTR/-SP=REVSTR LB:[1,1]BSCPUR.STB/SS / STACK=0 UNITS=0 / 02/13/81 APPENDIX C USEFUL INTERNAL BASIC SUBROUTINE CALLS ; GETARG: TO RETRIEVE ADDRESSES OR VALUES FROM AN ARGUMENT LIST ; IN A BASIC "CALL" STATEMENT. ; ; ON ENTRY: R5 POINTS TO A USER TABLE FOR RESULT TO BE PLACED IN ; R1 POINTS TO POS IN ARG LIST (MUST BE "," OR "(" ) ; R0 POINTS TO LIST OF BYTE ARG TYPES (TERM. BY 0 OR > 4) ; ON RETURN: R5 POINTS TO THE FIRST WORD PAST THE RETURNED DATA ; R1 POINTS TO NEXT CHAR FOLLOWING LAST ARG JUST RETURNED ; R0 POINTS TO FIRST BYTE AFTER TERMINATING BYTE ; ARG TYPES IN R0 LIST: ; 1 = INPUT NUMERIC EXPRESSION (2-WORD FLOATING POINT) ; ; 2 = OUTPUT NUMERIC TARGET (5 WORDS) ; 2-WORD FP VALUE ; 2-WORD FP OFFSET ; 1-WORD OFFSET TO HEADER ; ; 3 = INPUT STRING EXPRESSION (2 WORDS) LEN, ADDRESS ; ; 4 = OUTPUT STRING TARGET (5-WORDS) ; 1-WORD ADDRESS ; 1-WORD LENGTH ; 2-WORD FP OFFSET ; 1-WORD HEADER ADDRESS ; ; FOR STANDARD VARIABLE, FP-OFFSET IS FROM STUDAT ; FOR VIRTUAL VARIABLE, FP-OFFSET IS FROM FILE START ; ; 0 OR > 4 = LIST TERMINATOR ; ALL OTHER REGISTERS WILL BE USED AND DESTROYED ; ; GTRGPI: POSITION INDEPENDENT ARGUMENT RETRIEVAL FOR USER LOADED ; ROUTINES. THE ARGUMENT TYPE LIST FOLLOWS THE CODE IN A JSR R4,GTPRI ; INSTRUCTION. THE ARGUMENT LIST ITSELF IS CONSTRUCTED ON THE STACK ; AND POINTED TO BY SP ON RETURN. ; ON ENTRY: ; R4 POINTS TO ARG TYPE LIST (VIA JSR R4,@#GTRGPI) ; OLD R4 ON STACK (WILL BE POPPED) ; ON RETURN: ; SP -> ARG LIST (ON STACK - TO BE REMOVED BY CALLING ROUTINE) ; OTHER REGISTERS: POTENTIALLY ALL ; USEFUL INTERNAL BASIC SUBROUTINE CALLS PAGE C-2 02/13/81 ; ; NSTORE: TO STORE AWAY A VALUE FROM AC0 INTO A LOCATION ; STORED IN A TABLE SUCH AS THAT FILLED IN BY GETARG. ; ON CALL: R5 CONTAINS POINTER TO ADDRESS ; AC0 CONTAINS VALUE TO BE STORED ; ON RETURN: NOTHING CHANGED ; REGISTERS USED: R0, AC1 ; ; ; ; ; ; SSTORE: TAKE A STRING DESCRIBED BY LEN IN R4 AND ADDRESS IN R3 ; AND STORE IT INTO A STRING VARIABLE WHOSE TABLE ENTRY IS ; POINTED TO BY R5. ; ; ON CALL: R3 = ADDRESS OF STRING TO BE STORED ; R4 = LENGTH OF STRING TO BE STORED ; R5 = POINTER TO OUTPUT STRING TABLE ENTRY ; ; ON RETURN: R3 POINTS PAST END OF STRING ; R4 = 0 ; R5 UNCHANGED ; OTHER REGISTERS USED: R0,R2 (ALL BUT R1) ; ; ; ARGCNT: COUNT ARGUMENTS ROUTINE ; ON ENTRY: R1 POINTS TO LEADING OPEN PAREN "(" ; ON EXIT: R1 UNCHANGED ; R0 CONTAINS COUNT OF ARGUMENTS UP TO ")" IN THE LIST ; QUOTED STRINGS AND SUBSCRIPTS ARE ACCOUNTED FOR ; OTHER REGISTERS USED: R2 ; NOTE: AN END OF LINE WILL TERMINATE THE SCAN IRRESPECTIVE OF ; ENCLOSING QUOTES AS LONG AS IT IS USED AS THE INTERNAL ; LINE DELIMITER (S.EOL1 OR S.EOL2) ; ; ; ; ; TSTU00 - CHECK FOR USER STORAGE OVERFLOW ; ; CHECK FOR POSSIBLE USER STORAGE OVERFLOW ; ; ON ENTRY ; R0=NUMBER OF BITES TO PUT IN USER STORAGE ; ON EXIT ; R5-> NEXT AVAILABLE BYTE IN USER STORAGE ; OTHER REGISTERS USED ; R0,R3,R4 ; ; STATUS RETURNED IN C-BIT ; BHI WILL BRANCH IF ROOM EXISTS ; ; ; USEFUL INTERNAL BASIC SUBROUTINE CALLS PAGE C-3 02/13/81 ; PARCHK: CHECK THAT NEXT CHARACTER IN TEXT IS A ")" ; ; CALL WITH ; R1-> PROGRAM TEXT ; ; SUCCESSFUL RETURN ; ")" IN R2 ; R1-> PAST ")" ; ERROR RETURN ; CALL TO "ERROR IN PROCESSING CALL STATEMENT" ; ; ; ; ; SKIP00: SKIP OVER BLANKS IN PROGRAM TEXT - GET NEXT CHARACTER ; ; ENTER WITH R1 -> TEXT ; ; EXIT STATUS ; R2 = CHARACTER ; R1 -> NEXT CHARACTER (AFTER R2 CHARACTER) IN TEXT ; ; ; OTHER REGISTERS USED - NONE ; ; ; ; FORMAT FOR BASIC LOADABLE SUBROUTINES: ; SET UP BY THE "ULODHD" MACRO ; ; FIRST THREE WORDS: ; .WORD ID0001 ;THESE THREE WORDS ARE FILLED IN BY GLOBAL SYMBOLS ; .WORD ID0002 ;FROM A SYMBOL TABLE FOR BASIC, ENSURING CORRECT ; .WORD ID0003 ;SYMBOL LINKAGES (OR ELSE ERROR MESSAGE). ; NEXT TWO WORDS ARE LENGTHS: ; .WORD ?????? ;LENGTH (IN BYTES) OF CODE PLUS ENTRY POINTS ; .WORD ?????? ;LENGTH (IN BYTES) OF ENTRY POINTS ; .WORD ?????? ;# OF ENTRY POINTS ; NEXT ENTRIES ARE THREE WORD BLOCKS DESCRIBING ENTRY POINTS ; .RAD50 /NAME/ ;TWO WORDS OF RAD50 ENTRY POINT NAME ; .WORD ?????? ;OFFSET FROM START OF CODE PROPER ; FINALLY, ONE WORD CONTAINING NUMBER OF WORDS OF CODE PROPER: ; .WORD ?????? ;LEN (IN WORDS) OF CODE PROPER ; ; NOTE: THESE MODULES MUST BE TASK BUILT WITH /-HD/-FP AND: ; STACK=0 ; UNITS=0 ; ; IN ADDITION POSITION INDEPENDENT CODING TECHNIQUES MUST BE USED IN ; WRITING THE CODE BECAUSE ITS POSITION IN THE INTERPRETER WILL VARY ; DEPENDING ON WHAT OTHER ROUTINES ARE LOADED. 02/13/81 APPENDIX D INDEX ! . . . . . . . . . . . . . . . . 3-4 ABS . . . . . . . . . . . . . . . 4-1 Absolute value function . . . . . 4-1 AR5 . . . . . . . . . . . . . . . 5-2 Arctangent function . . . . . . . 4-2 Arithmetic assignment . . . . . . 3-3 ASC . . . . . . . . . . . . . . . 5-2 Ascii to RAD50 conversion function 5-2 Ascii value of character . . . . . 5-2 ATN . . . . . . . . . . . . . . . 4-2 Binary input . . . . . . . . . . . 6-2 Binary output . . . . . . . . . . 6-1 Blank trim functions . . . . . . . 5-3 BREAK . . . . . . . . . . . . . . 3-5 CALL . . . . . . . . . . . . . . . 7-1 CATXT . . . . . . . . . . . . . . 7-7 CDIS . . . . . . . . . . . . . . . 7-5 CHAIN . . . . . . . . . . . . . . 2-2 Character from Ascii value function 5-2 CHR$ . . . . . . . . . . . . . . . 5-2 CLEAR . . . . . . . . . . . . . . 1-3, 2-2 CLOSE . . . . . . . . . . . . . . 6-4 CON . . . . . . . . . . . . . . . 2-4 Control C . . . . . . . . . . . . 1-4 Control O . . . . . . . . . . . . 1-5 COR . . . . . . . . . . . . . . . 4-3 COS . . . . . . . . . . . . . . . 4-2 Cosine function . . . . . . . . . 4-2 CPOS . . . . . . . . . . . . . . . 7-6 CQNAM . . . . . . . . . . . . . . 7-7 CQTXT . . . . . . . . . . . . . . 7-7 DAT$ . . . . . . . . . . . . . . . 4-4 DATA . . . . . . . . . . . . . . . 3-4 Date function . . . . . . . . . . 4-4 Date validity check . . . . . . . 4-4 Day of century function . . . . . 4-4 DCEN . . . . . . . . . . . . . . . 4-4 INDEX PAGE D-2 02/13/81 DDAT$ . . . . . . . . . . . . . . 4-4 DEC standard date function . . . . 4-4 DEF . . . . . . . . . . . . . . . 3-3 DELETE . . . . . . . . . . . . . . 2-3 DIM . . . . . . . . . . . . . . . 3-2 DIM # . . . . . . . . . . . . . . 3-2 END . . . . . . . . . . . . . . . 2-1 ERL . . . . . . . . . . . . . . . 4-3 ERR . . . . . . . . . . . . . . . 4-3 Error code functions . . . . . . . 4-3 EXIT . . . . . . . . . . . . . . . 2-4 EXP . . . . . . . . . . . . . . . 4-2 Exponential function . . . . . . . 4-2 Exponentiation . . . . . . . . . . 1-3 FCS . . . . . . . . . . . . . . . 4-3 File close . . . . . . . . . . . . 1-3, 2-2, 6-4 File open . . . . . . . . . . . . 6-3 File restore . . . . . . . . . . . 6-1 FOR . . . . . . . . . . . . . . . 3-4 Free core function . . . . . . . . 4-3 FRMT$ . . . . . . . . . . . . . . 5-4 Function - user . . . . . . . . . 3-3 GOSUB . . . . . . . . . . . . . . 3-1 GOTO . . . . . . . . . . . . . . . 3-1 IF . . . . . . . . . . . . . . . . 3-3 IF END . . . . . . . . . . . . . . 6-4 IMMEDIATE mode . . . . . . . . . . 1-1 Index string function . . . . . . 5-1 INPUT . . . . . . . . . . . . . . 6-2 INPUT LINE . . . . . . . . . . . . 6-2 INSTRG . . . . . . . . . . . . . . 7-2 INT . . . . . . . . . . . . . . . 4-2 Integer function . . . . . . . . . 4-2 Introduction . . . . . . . . . . . 1-1 INX . . . . . . . . . . . . . . . 5-1 LEFT . . . . . . . . . . . . . . . 5-2 LEN . . . . . . . . . . . . . . . 5-1 Length of string function . . . . 5-1 LET . . . . . . . . . . . . . . . 3-3 Library open . . . . . . . . . . . 7-2 LIST . . . . . . . . . . . . . . . 2-3 LJS$ . . . . . . . . . . . . . . . 5-5 LOAD . . . . . . . . . . . . . . . 7-1 LOG . . . . . . . . . . . . . . . 4-2 LOG10 . . . . . . . . . . . . . . 4-2 Logarithm - base ten . . . . . . . 4-2 Logarithm - natural . . . . . . . 4-2 Logical Expressions . . . . . . . 1-5 LTR$ . . . . . . . . . . . . . . . 5-3 INDEX PAGE D-3 02/13/81 MATXT . . . . . . . . . . . . . . 7-7 MCR COMMAND LINE . . . . . . . . . 1-4 MDIS . . . . . . . . . . . . . . . 7-5 MID . . . . . . . . . . . . . . . 5-2 MPOS . . . . . . . . . . . . . . . 7-6 MQTXT . . . . . . . . . . . . . . 7-7 NEXT . . . . . . . . . . . . . . . 3-5 NRC . . . . . . . . . . . . . . . 4-3 Number of records function . . . . 4-3 Number of seconds from time . . . 4-5 Numeric to character string . . . 5-3 Numeric to string format function . 5-4 Numeric value of string . . . . . 5-1 OCS$ . . . . . . . . . . . . . . . 5-4 OCT . . . . . . . . . . . . . . . 5-1 OCT$ . . . . . . . . . . . . . . . 5-4 Octal to string functions . . . . 5-4 Octal value of string . . . . . . 5-1 OLD . . . . . . . . . . . . . . . 2-2 ON GOSUB . . . 3-1 ON GOTO . . . 3-1 ON ERROR GOTO . . . . . . . . . . 3-6 OPEN . . . . . . . . . . . . . . . 6-3 OPEN LIBRARY . . . . . . . . . . . 7-2 OVERLAY . . . . . . . . . . . . . 2-3 Piece of string by delimiter . . . 5-3 PIECE$ . . . . . . . . . . . . . . 5-3 POS . . . . . . . . . . . . . . . 5-1 Position string function . . . . . 5-1 Powers of numbers . . . . . . . . 1-3 PRINT . . . . . . . . . . . . . . 6-1 Print tab function . . . . . . . . 5-5 PRIORITY . . . . . . . . . . . . . 3-7 Program chain . . . . . . . . . . 2-2 Program continue . . . . . . . . . 2-4 Program delete . . . . . . . . . . 6-3 Program line delete . . . . . . . 2-3 Program list . . . . . . . . . . . 2-3 Program overlay . . . . . . . . . 2-3 Program retrieve . . . . . . . . . 2-2 Program save . . . . . . . . . . . 2-2 PROMPT . . . . . . . . . . . . . . 3-6 Question Display . . . . . . . . . 7-3 R5A$ . . . . . . . . . . . . . . . 5-4 RAD50 to ASCII conversion function 5-4 Random access I/O . . . . . . . . 6-1, 6-2, 6-3 RANDOMIZE . . . . . . . . . . . . 4-1 RATXT . . . . . . . . . . . . . . 7-7 RDIS . . . . . . . . . . . . . . . 7-5 READ . . . . . . . . . . . . . . . 3-4 INDEX PAGE D-4 02/13/81 READ-PASS-ALL . . . . . . . . . . 3-6 Record count function . . . . . . 4-3 REM . . . . . . . . . . . . . . . 3-4 RESTORE . . . . . . . . . . . . . 6-1 RETURN . . . . . . . . . . . . . . 3-1 RIGHT . . . . . . . . . . . . . . 5-2 Right justify function . . . . . . 5-5 RJS$ . . . . . . . . . . . . . . . 5-5 RND . . . . . . . . . . . . . . . 4-1 RPOS . . . . . . . . . . . . . . . 7-6 RQNAM . . . . . . . . . . . . . . 7-7 RQTXT . . . . . . . . . . . . . . 7-7 RUN . . . . . . . . . . . . . . . 1-3, 2-1 SAVE . . . . . . . . . . . . . . . 2-2 SBS$ . . . . . . . . . . . . . . . 5-2 SCRATCH . . . . . . . . . . . . . 6-3 SEC . . . . . . . . . . . . . . . 4-5 SEG$ . . . . . . . . . . . . . . . 5-2 SET PROMPT . . . . . . . . . . . . 3-6 SET READ-PASS-ALL . . . . . . . . 3-6 Set system conditions . . . . . . 3-6 SET TRACE . . . . . . . . . . . . 3-6 SGN . . . . . . . . . . . . . . . 4-1 Sign function . . . . . . . . . . 4-1 SIN . . . . . . . . . . . . . . . 4-2 Sine function . . . . . . . . . . 4-2 Single line execute . . . . . . . 2-4 SLEEP . . . . . . . . . . . . . . 3-6 SPACE$ . . . . . . . . . . . . . . 5-5 SPAWN . . . . . . . . . . . . . . 7-7 SQR . . . . . . . . . . . . . . . 4-3 Square root function . . . . . . . 4-3 Statement and line format . . . . 1-1 STEP . . . . . . . . . . . . . . . 2-4 STOP . . . . . . . . . . . . . . . 2-1 STR$ . . . . . . . . . . . . . . . 5-3 String comparison . . . . . . . . 3-3 String variables . . . . . . . . . 3-2 STRING$ . . . . . . . . . . . . . 5-5 Strings . . . . . . . . . . . . . 1-3 Suboutine call . . . . . . . . . . 7-1 Substring functions . . . . . . . 5-2 TAB . . . . . . . . . . . . . . . 5-5 TIM$ . . . . . . . . . . . . . . . 4-4 Time function . . . . . . . . . . 4-4 Time string validity check . . . . 4-5 TRACE . . . . . . . . . . . . . . 3-6 TRACE ON and OFF . . . . . . . . . 3-7 TRM$ . . . . . . . . . . . . . . . 5-3 UNLOAD . . . . . . . . . . . . . . 7-1 User defined functions . . . . . . 3-3 User subroutine call . . . . . . . 7-1 INDEX PAGE D-5 02/13/81 VAL . . . . . . . . . . . . . . . 5-1 Value of string function . . . . . 5-1 Variables . . . . . . . . . . . . 1-2 Virtual arrays . . . . . . . . . . 1-2, 3-2 WAIT . . . . . . . . . . . . . . . 3-7 ^C . . . . . . . . . . . . . . . . 1-4 ^O . . . . . . . . . . . . . . . . 1-5