BASIC DOCUMENTATION 03/06/81 BASIC DOCUMENTATION PAGE 2 03/06/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-4 1.8 MCR COMMAND LINE . . . . . . . . . . . . . . . . 1-4 1.9 CONTROL C. . . . . . . . . . . . . . . . . . . . 1-5 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-7 3.17 WAIT . . . . . . . . . . . . 3-7 3.18 PRIORITY . . . . . . . . . . . . . 3-7 3.19 TRACE ON AND OFF. . . . . . . . . . . . . . . . 3-8 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 03/06/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-7 7.9 MQTXT . . CQTXT . . RQTXT. . . . . . . . . . . . 7-7 BASIC DOCUMENTATION PAGE 4 03/06/81 7.10 MATXT . . CATXT . . RATXT . . . . . . . . . . . 7-7 7.11 CQNAM . . RQNAM . . . . . . . . . . . . . . . . 7-7 7.12 SPAWNB. . . . . . . . . . . . . . . . . . . . . 7-8 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 03/06/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 concate- nation character is the colon (:). BASIC can be used in an IMMEDIATE mode. Any legal command en- tered without a line number (or leading "tab") will be performed immediately. Nearly all the BASIC codes presented in this docu- ment can be used in the IMMEDIATE mode and a few can be used only in the IMMEDIATE mode. The other BASIC mode is the PROGRAM mode. Any legal command fol- lowing a line number or with a leading "tab", (effectively a con- tinuation line,) will be stored with the current program and exe- cuted 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 largest 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 er- ror message. Exit and re-enter the BASIC mode at a higher ver- sion. All numeric calculation is done in floating point (REAL*4 for you FORTRAN buffs) regardless of the variable types in the expres- sion. 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 INTRODUCTION PAGE 1-2 03/06/81 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 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 ei- ther 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 previous 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 alpha 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 vari- able (16 bits) and & is a byte variable (8 bits). Note that un- like standard BASIC, the second character of the variable name is allowed to be alphabetic. In order to gain this flexibility in naming variables, some restrictions had to be made in the allowed format of the program text: spaces are not allowed within a var- iable name; variable names must not be the same as BASIC key words (e.g. TO and IF). Also, ambiguities 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 execution time does not seem to warrant it. Consider the following example: 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 values, usually more than is practical to store in an in-memory array. The use of virtual arrays involves a special form of the INTRODUCTION PAGE 1-3 03/06/81 DIM statement 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 superimposed over the basic block structure. Therefore only the file access 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 (currently 6). Virtual arrays are maintained in memory one block at a time (512 bytes). When a variable is accessed, the appropriate block is calculated 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 ac- cess, an illegal write will not be detected until the block as a whole attempts to be written out. Also, in the case that the in- terpreter 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 con- stant, 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 commands and on exit from BASIC. They remain open (unless explicitly closed by a CLOSE command) on program stop for debug- ging purposes. 1.6 STRING VARIABLES String variables are declared in a DIM statement and can be ei- ther fixed or variable length. See DIM statement for the specif- ics. INTRODUCTION PAGE 1-4 03/06/81 1.7 EXPONENTIATION Exponentiation (^) is done in two ways. If the exponent is an integer, the base is multiplied (or divided) by itself the appro- priate number of times. If the exponent contains a fractional part, a log - antilog calculation sequence is used. 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 fol- low, 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 as- sumed 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>ABASB MCR>ABASIC PROG.BAS/RNB MCR>ABAS PROG/RN:150B MCR>ABAS ? 4*3+2B INTRODUCTION PAGE 1-5 03/06/81 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 sequential 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 termi- nate the listing 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. 1.10 CONTROL O Control-O (^O) will stop all output from a LIST command and re- sume printing with READY. It also stops all printing following a RUN command 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 operators can be formed by any combination of <, > and =. The two expressions 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 ASCII 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 (Bo- olean) 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 arithmetic 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: AA < B OR B = .5B INTRODUCTION PAGE 1-6 03/06/81 ANOT (X1 < 1 AND A >= 5)B 03/06/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 load saved programs, interactively modify/debug them while running, and possibly save modified versions for later use. As such, the equivalent 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: A10 STOPB A20 ENDB 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 subrou- tines are also unloaded. To preserve data and user files, use "CHAIN" command. A previous restriction against using a variable in the string ex- pression following the RUN command has been removed. The option- al 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: ARUNB ARUN "PROGRAM"B A10 RUN "PROG1"B LOADING/RUNNING/SAVING PROGRAMS PAGE 2-2 03/06/81 2.3 CLEAR This command clears the user data area. It closes all user files before doing the clear operation. 2.4 SAVE [N1][-N2][,N3...] Primarily an immediate mode command. It makes a copy of the pre- sent 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 default extension will be BAC if the switch is included. The default file specifier is: SY:PROGRAM.BAS or the name, ex- tension and device in the last OLD, RUN, CHAIN or OVERLAY com- mand. Example: ASAVE "PROGRAM"B ASAVE "LP:"B ASAVE "DK2:PROG.BAS"B ASAVEB 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 op- tional switch, when specified, causes truncation of REM and ! statements. The default file specifier is: SY:PROGRAM.BAS The CO switch indicates that a compiled basic file is to be used (de- fault extension BAC). Example: AOLD "PROG1"B AOLD "DK3:PROGRAM.BAS"B 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 deleted from the user data area. Thus user functions must be re- defined in any new program module. LOADING/RUNNING/SAVING PROGRAMS PAGE 2-3 03/06/81 The default file specifier and switches are the same as for the OVERLAY command with the addition of the /LI switch which can specify an optional line number to continue execution. Example: A20 CHAIN "PROG2"B 2.7 OVERLAY The OVERLAY command reads in additional program text from the specified 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 de- finitions and DATA statements during debugging should also be ob- served 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: AOVERLAY "PATCH1"B A100 OVERLAY "PATCH2.BAS/LI:500"B 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 argu- ments separated by commas will list only the line numbers re- quested. Two arguments separated by a dash (minus) will list an inclusive line number range. Example: ALISTB ALIST 20B ALIST 50,100B ALIST 50-80,135,710-750B 2.9 DELETE N1[-N2][,N3...] This also is primarily an immediate mode command. It will delete individual lines with single parameters or inclusive ranges with numbers separated by a dash (minus). If no numbers are speci- fied, 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 also, usually to delete a range of line numbers in preparing to OVERLAY another routine. Example: LOADING/RUNNING/SAVING PROGRAMS PAGE 2-4 03/06/81 ADELETE 30B ADELETE 50-70B ADELETE 10-40,60-80B 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: A1000 EXITB 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 differ- ent 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 being executed, the program will not stop until the next line after the branch. The stop uses the same internal facili- ties as the ^B break feature. Example: ASTEPB ASTEP 510B 2.12 CON [LINE #] This command allows one to resume execution of a program after stopping it for interactive de-bugging. When used with the op- tional line number, it functions just like GOTO with the excep- tion that the next available line after the one specified is used if there is no exact match. If no line number is specified, exe- cution is resumed at the line following the last stop. Example: ACONB ACON 100B 03/06/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 variables, perform arithmetic calculations, etc. 3.1 GOSUB N . . GOTO N Transfers program control to statement N, where N can be a posi- tive integer constant or an expression which will be truncated to an integer. Note that an expression will not produce correct re- sults in the event of a resequence. Example: A10 GOTO 50B A20 GOSUB A(I)B 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 happens. The transfer is handled just as in the stan- dard GOTO and GOSUB statements. Example: A100 ON I GOTO 1000,1200,1400B A210 ON X-A(C1) GOSUB 2000,2100,3000B 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 position in the line before and after the modification: PROGRAM STATEMENTS PAGE 3-2 03/06/81 i.e. it must be the first or third etc. statement in the line. Example: A10 RETURNB 3.4 DIM Declares size of arrays and strings. Also specifies strings as either fixed or variable length. Arrays may have one or two sub- scripts. String lengths are indicated in square brackets [ ] which are followed 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 assumed to be varible length with a max of 15 char- acters. 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 unsub- scripted 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: A10 DIM A(5,5),B$[10]B A20 DIM C$[20]V(10,10),D$(5)B 3.5 DIM #N, This statement declares certain variables as "virtual arrays" and defines their allocation on the file whose LUN is the value of "exp". A virtual array has its values stored on a file and main- tains 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 map- pings of different variables onto the same file with an effect similar to a FORTRAN EQUIVALENCE statement. The rules for mapping follow RSTS BASIC-PLUS. Essentially, no array element may cross block boundaries. This implies that var- iable sizes must be powers of two. Numeric variables automati- cally fulfill this condition. Strings are allocated their speci- fied size whether fixed or variable. Variable length strings are null padded on disk, and when used in a program context are auto- matically 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 boundaries because of previous PROGRAM STATEMENTS PAGE 3-3 03/06/81 allocations in the list, it is started at the next disk boundary. Subscripts may range up to 32767 and string elements up to 512 characters (in powers of 2). Example: A20 DIM #3,A(20,100),A$[256]V(5000)B A30 DIM #3,B(20000),B$[128]V(10000)B A40 DIM #7,X(100),Y(100),Z(200)B 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 definition itself may be any legal numeric or string expression including system and other user functions. Function names returning string values must end in '$', those re- turning 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 debugging runs by insertions, deletions or changes to lines preceding the function definition. Function definitions are deleted by the CHAIN statement. Example: A30 DEF FNA1(A)=A2B A40 DEF FNC$(X$)=X$+"ABC"B A50 DEF FNZ3$(X$,I)=SEG$(X$,I,LEN(X$))B 3.7 LET This is the numeric assignment statement. It is also allowable for string assignment. The word itself is optional in this ver- sion 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: A20 LET A=EXP(10.34)B A30 A$="ABC"+B$B PROGRAM STATEMENTS PAGE 3-4 03/06/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 statements following THEN up to the end of the line or an ELSE are executed. 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 con- tinues on the following line. IFs and ELSEs are paired like matching parentheses from the in- side out. That is, an ELSE is matched with the IF most immedi- ately 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: A10 IF A > B THEN STOPB A20 IF A$ <> B$ GOTO 110 ELSE 500B A30 IF A >= 12.5 THEN 160 ELSE PRINT "A < 12.5" : GOTO 300B 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 fol- lowing 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: A10 REM PROGRAM TO ADD ALL NUMBERS FROM 1 TO 10B A20 ! AND DEMONSTRATE USE OF REM AND !B 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: A10 DATA 10.5,-76,1E7,FRANKB A50 READ A,B,C,D$B PROGRAM STATEMENTS PAGE 3-5 03/06/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 vari- able set equal to EXP1 and continues by incrementing the variable by EXP3 (defaulted to one) until it reaches or passes the value of EXP2 (therefore the loop may not be executed at all). Final value of the variable is its value the last time through the lo- op. NOTE Changing the value of the variable within the loop will affect the number of times the loop is executed. Example: A40 FOR I=1 TO 5.5 STEP .5B A100 FOR J1=-.1 TO -1.5 STEP -.1B 3.12 NEXT Format: NEXT This statement terminates the loop begun by the immediately preceding FOR statement with the same variable name. A concaten- ated 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: A70 NEXT IB A100 NEXT I,JB 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 con- trol. All carriage control must be supplied in the buffer by the program. In order to accumulate text in the terminal's buffer, PRINT statements 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. PROGRAM STATEMENTS PAGE 3-6 03/06/81 Example: A110 PRINT "START TAPE INPUT";CHR$(17);B A120 BREAKB 3.14 SET PROMPT/TRACE/READ-PASS-ALL ON/OFF This statement is used to set or clear a number of system condi- tions. The number of conditions is likely to increase in the fu- ture as functionality 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 condition 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 designed for special screen or page formatting and may be used in conjunction with the BREAK command. Example: A210 SET PROMPT OFFB A220 SET TRACE ONB 3.15 ON ERROR GOTO This statement sets the line number for a transfer on any type of error. It does not cause any branching when it itself is execut- ed, rather it changes the processing of errors in the BASIC in- terpreter. 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 functions ERR, ERL, FCS detailed elsewhere. Examples: A100 ON ERROR GOTO 1500B A510 ON ERROR GOTO 0 ! THIS RESTORES NORMAL ERROR HANDLINGB PROGRAM STATEMENTS PAGE 3-7 03/06/81 3.16 SLEEP The SLEEP command causes the executing program to pause for the specified amount of time. any valid arithmetic expression may be used to specify the time magnitude. However, a negative result will give an error and zero will be treated as a no-op. Truncation of the floating 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: A510 SLEEP 10 SECONDSB A105 SLEEP 2 MB A632 SLEEP 25B 3.17 WAIT The WAIT command sets parameters for the timeout of terminal in- put. 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, current- ly 44. (decimal.) Appropriate action may be taken at this point (EXIT for example). The no timeout condition may be restored by using a 0 magnitude. Examples: A400 WAIT 40 S :! ALL TERMINAL INPUT TO TIME OUT AFTER 40 SB A500 WAIT 0 :! RESTORE TO NO TIMEOUT CONDITIONB 3.18 PRIORITY The PRIORITY command causes the interpreter to change its priori- ty to that specified in the following expression. Priorities up to 100 are allowed. Example A500 PRIORITY 30B PROGRAM STATEMENTS PAGE 3-8 03/06/81 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 pro- gram execution are printed on the user's terminal. This can be used in either immediate mode or program mode (for selective tracing). Example: ATRACE ONB READY ARUNB OR A100 TRACE ONB A...B A200 TRACE OFFB 03/06/81 CHAPTER 4 ARITHMETIC FUNCTIONS The functions listed in this chapter are primarily arithmetic in nature. 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 RAN- DOMIZE statement. Example: A120 X=RND(0)B 4.2 RANDOMIZE This statement resets the random number generator to a new start- ing 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: A50 RANDOMIZEB 4.3 ABS This function returns the absolute value of the numeric expres- sion argument. Example: A10 A=ABS(A1+5)B ARITHMETIC FUNCTIONS PAGE 4-2 03/06/81 4.4 SGN +1 returned if argument > 0; -1 if argument 0; 0 returned if argument = 0. Example: A10 A=SGN(A1)B 4.5 INT Returns greatest integer in the argument. Note: INT(-1.5)=-2 etc. Example: A10 A=INT(X)B 4.6 LOG (NATURAL & BASE 10) LOG Returns the natural log of the value of the argument expression. Example: A30 A=LOG(X)B LOG10 Returns the base ten (common) log of the value of the argument expression Example: A50 B=LOG10(X)B 4.7 EXP Returns the base e exponential of the argument value. Example: A10 A=EXP(X)B 4.8 SIN COS These functions return the sine and cosine functions of the argu- ment values. The input argument is in radians. Example: A20 S=SIN(X)B A30 C=COS(Y)B ARITHMETIC FUNCTIONS PAGE 4-3 03/06/81 4.9 ATN Returns the arctangent function of the argument value. The re- turned value is in radians. Example: A10 A=ATN(X)B 4.10 SQR Returns the square root of the argument value. If the argument value is negative, an error is given. Example: A20 S=SQR(X)B 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 returned indicates variable length records. Example: A10 A=NRC(4)B 4.12 ERR . . ERL . . FCS These functions return respectively: the number of the last er- ror, 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 argument is used, it will be treated as a word off- set from the interpreter location containing the normal informa- tion for that function. Thus a non-zero offset should only be used in conjunction with a map and assembler listing. Example: A100 A=ERR(0)B A110 B=FCS(0)B A120 CON ERL(1)B 4.13 COR This function returns the free core (in bytes) minus the value of the argument. Example: ARITHMETIC FUNCTIONS PAGE 4-4 03/06/81 A100 A=COR(255)B 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 century, and a corresponding date string is returned. The positive argument 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 re- turned. Example: A50 A$=DAT$(0) : ! RETURN SYSTEM DATEB A60 PRINT DAT$(12752)B A70 A$=DAT$() : ! RETURN SYSTEM DATEB 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 depending on the number of digits in the day. The argument is interpreted in the same way as in the DAT$ function. Example: A40 A$=DDAT$(0)B 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 returned. Otherwise, the argument is evaluated. If ne- gative, 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: A30 A$=TIM$(0)B A40 A$=TIM$() : !RETURN SYSTEM TIMEB A50 A$=TIM$(A-B) : ! RETURN TIME OF DAY CORRESPONDING TOB ! A-B SECONDS SINCE MIDNIGHT ARITHMETIC FUNCTIONS PAGE 4-5 03/06/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 correspond- ing 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 cen- tury, 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: A150 A=DCEN("12/15/46")B A160 B=DCEN("5-AUG-72")B A170 C=DCEN(DDAT$(0))B A180 D=DCEN("121546")B 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: A210 A=SEC("12:05:31")B A220 B=SEC(A$)B 03/06/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 start- ing at optional position P1 (P1 assumed to be 1 if not speci- fied). A second optional parameter P2 specifies the final char- acter position. If it is not specified, it is assumed to be the end of the first string. INX and POS are identical. Example: A10 A=POS("ABC","B")B A20 X=POS(A1$,A2$,5,7)B 5.2 LEN This function computes the length of a single string expression argument. Example: A30 X=LEN(A$)B 5.3 VAL This function takes an ASCII string containing a legal numeric expression and returns a floating point value. Example: A10 A=VAL(A$)B STRING FUNCTIONS PAGE 5-2 03/06/81 5.4 OCT This function takes an ASCII string containing a legal octal in- teger representation and returns a floating point value. Example: A10 A=OCT("1777")B 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 input were blank padded at the end. All legal RAD50 characters including blank and period are converted. Example: A100 A%=AR5("ABC")B A110 B1=AR5(A$+B$)B 5.6 ASC This function returns the numeric value of the first ASCII char- acter in the string argument. For a null string, 0 is returned. Example: A10 I=ASC("A")B 5.7 CHR$ Routine to return a one character string corresponding to a num- eric ASCII value. Example: A10 LET A$=CHR$(65)B 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 character in the string to be selected. In SEG$, B is the last character to be included in the output string; in SBS$, it is STRING FUNCTIONS PAGE 5-3 03/06/81 the number of characters to include. If not specified in either case all characters to the end of the string are included. A null string is returned 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 po- sition past the end of the string, it is as though the ending po- sition was specified. RIGHT LEFT and MID are provided for compatibility with other ver- sions 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 functions 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: A10 A$=SEG$(B$,1,5)B A30 X$=SBS$(Y$,6)B 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 particular dividing string (STRING2). The resulting substring begins immediately after the N1 minus one occurrence of the di- viding string and ends immediately before the N2nd occurrence (or N1st if N2 is unspecified). Example: A110 M$=PIECE$("12/1/77","/",1) :! EXTRACT MONTH FROM STRINGB A120 A$=PIECE$("12/1/77","/",1,2) :! EXTRACT MONTH AND DAYB 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: A30 A$=STR$(EXP(X)+1.4)B STRING FUNCTIONS PAGE 5-4 03/06/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 trailing blanks for TRM$. Example: A30 A$=LTR$(A$)B A40 B$=TRM$(C$)B 5.12 OCT$ OCS$ A single numeric argument is converted to ASCII representation of an octal integer. The numeric expression is evaluated and trun- cated to an integer prior to conversion. OCT$ produces an un- signed string, while OCS$ produces a signed string. Magnitudes are limited to those representable in one PDP-11 word. Example: A40 PRINT OCS$(-53)B A50 PRINT OCT$(I*16)B 5.13 R5A$ The RAD50 source value (value range of one integer word) is con- verted to a 3 character string. Example: A110 A$=R5A$(A)B A120 B$=R5A$(X%)B 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 total 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 as- terisks 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 as- terisks will be returned. Note that meaningless digits will be produced if more than 6 or 7 are asked for. If only significant STRING FUNCTIONS PAGE 5-5 03/06/81 digits are wanted, use STR$. Numbers are rounded for printout. Example: A130 A$=FRMT$(A+6,5,2)B A140 B$=FRMT$(12.75+Z1,7)B 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: A40 A$=RJS$(B$,9)B A70 A$=LJS$(B$,5)B 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: A120 A$=SPACE$(40)B A130 B$=STRING$("-",40)B 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 specified 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 modulo the device width. If the specified column is less than the current print position, the function is ignored. TAB is ignored on binary output files. Example: A10 PRINT A;TAB(20);A$B 03/06/81 CHAPTER 6 I/O & FILE MANIPULATION The commands listed in this chapter are primarily concerned with Input and Output. They provide the capability of opening files, reading/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 RESTORE statement may be followed by a # sign and an arithmetic expression giving the file number. A sequential file open for read only will be reset to the start. To read a sequential file currently being written, it is necessary to close and then re-open for read. Example: A10 RESTOREB 6.2 PRINT Print statement. Format: PRINT [#N,]V1,V2,V3 etc. or PRINT #NR,V1,V2,V3 etc. Where N is an optional file number and V1, V2, V3, etc. are any legal 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 semicolons, 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 I/O & FILE MANIPULATION PAGE 6-2 03/06/81 fit on the printing device. Note that numeric values, when con- verted in a PRINT statement normally have a space at each end. To avoid this, use the STR$ function. 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 consecutive 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 sto- rage arrangement for future use with INPUT or other non-BASIC programs. A synonym for PRINT is "?" primarily for convenience in immediate mode use. Example: A50 PRINT A,3.5,"HELLO";A$B A60 PRINT #3,EXP(.5);XY;B 6.3 INPUT Format: INPUT [#N,] V1,V2,V3 etc. or INPUT #NR,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 ensure that all characters are between oc- tal ASCII codes 40 and 137 inclusive 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 variable 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 vari- ables is not considered 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 variable, the results are unpredictable and in any case terminate the program with an error. Example: A30 INPUT #3,A1,B1$B A50 INPUT #4R+5,X1,X2,A1$B I/O & FILE MANIPULATION PAGE 6-3 03/06/81 A80 INPUT "WHAT IS YOUR NAME",N$ : ! READ NAME INTO N$B 6.4 INPUT LINE This is the same as the input statement except that only string variables are permitted in the input list and no character check- ing 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 IN- PUT. For binary files INPUT LINE is the same as INPUT. Example: A30 INPUT LINE #3,A1$B 6.5 SCRATCH The SCRATCH command must have a file specifier with an explicit version number in order to delete a file. The default file spec- ifier is: SY:PROGRAM.BAS Example: ASCRATCH "DATA.DAT;3"B A50 SCRATCH "DK1:DAT3.TMP"B 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 I/O & FILE MANIPULATION PAGE 6-4 03/06/81 mode files (up to 14) may be open simultaneously subject only to total memory availability. The default device for all LUNs is SY0:. Examples: A50 OPEN #4, "LP:/WR"B A60 OPEN #3,N$B 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: A60 CLOSE 4B A70 CLOSE I1B A95 CLOSEB 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 possi- bility of being read from (i.e. cannot be /AP or /WR in sequen- tial mode). Examples: A100 IF END THEN 1500 :! SET TERMINAL END OF FILE LINE NO.B A120 IF END #3 THEN 2100:! SET END OF FILE LINE NO. ON LUN 3B 03/06/81 CHAPTER 7 LOADABLE SUBROUTINES This chapter is primarily concerned with the operation of user written MACRO subroutines. The capability of calling a machine language subroutine to perform some complex calculation can pro- vide much simpler program operation, and/or significantly incre- ase 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 lo- aded. 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 subrou- tine. The default extension is BTK. See Append. B for a sample user loadable subroutine Example: A610 LOAD "REVERS"B 7.2 UNLOAD This command unloads all user assembly routines loaded by the LO- AD command. Example A500 UNLOADB LOADABLE SUBROUTINES PAGE 7-2 03/06/81 7.3 CALL "NAME"(ARG1,ARG2,...) The CALL statement is used by the BASIC user to call specially written 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 par- entheses are necessary 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 simple variable (may be subscripted). For values which are passed, either expressions or variables may be used. The vari- ables and expressions used in the argument list must match the type (string or numeric) 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 parenthesis. See APPEND. B for a sample loadable routine. Example: A100 CALL "ABC"(A$,B)B A120 CALL (B$)(A-X,Y$+Z$)B 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 de- fined 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 ex- cept that a MACRO library file is opened for question text output LOADABLE SUBROUTINES PAGE 7-3 03/06/81 and other question processing subroutines invoked by the CALL statement. A LUN must be used that is not already in use and is one of the allowable numbers as for the standard OPEN. No switches are allowed as all file options are determined internal- ly for handling the library format. Example: A100 OPEN LIBRARY #5,"QUESLS.MLB"B A200 OPEN LIBRARY #3,A$B 7.6 QUESTION DISPLAY A series of routines can be used for displaying questions at a terminal for interactive data entry applications. The text of the questions themselves resides in a file made by the RSX li- brarian (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 ques- tion being the name of the macro. There is a single argument to the macro, 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 ques- tions 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 display, 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 reproduced exactly as entered with the carriage (cursor) positi- oned to the start of the next line. The text display is termi- nated when the .ENDM directive is encountered as the first entry on a line other than space or tab. Type code is 0. Example: A.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. .ENDMB SINGLE LINE QUESTION LOADABLE SUBROUTINES PAGE 7-4 03/06/81 This type of question is usually used to solicit text information 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: A.MACRO SINGLE 1 TYPE YOUR NAME: LAST, FIRST .ENDMB 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 struc- tures may be set up. The character used to separate the response text from its associated branching question name is the back- slash. The number of choices is the number following the ques- tion name in the .MACRO line. Example: A.MACRO MULCHC 3 SELECT YOUR STATE OF MIND GOOD\MULCH1 FAIR\MULCH2 TGIF\MULCH3 .ENDMB 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 LOADABLE SUBROUTINES PAGE 7-5 03/06/81 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. The 'R' form uses the previously accessed question (whether by 'M' or 'C') to perform its action. The third parameter is a dum- my numeric parameter. GENERAL PARAMETERS Following is a description of the symbolic parameter names used in describing the various subroutine calls. They are, of course, replaced in the actual calls by legal BASIC expressions in the case of input values and by legal variable names in the case of output values. 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 varie- ty of conditions. For 'M' type calls, it means the spe- ciied question 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]) LOADABLE SUBROUTINES PAGE 7-6 03/06/81 The named question, linked question or previous question will be displayed respectively by the above three subroutine calls ac- cording to the following rules. If the optional parameters are not specified: MULTI-LINE INFO DISPLAY: Text is displayed as typed. Carriage (cursor) is positioned to the start of the next line. All lines up to the line with a leading .ENDM directive will be displayed. SINGLE LINE TEXT INPUT: The line of text is displayed with the carriage (cursor) to the immediate right of the text just displa- yed. Any spaces required after the text must be either included in the question text or added from the program via a PRINT state- ment. 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 inde- pendent of where the .ENDM line occurs. This may lead to not displaying all of the typed in question text or the output of garbage 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 dis- played as above, but the subsequent lines (answers) are each pre- ceded by N characters from STRING$. LOADABLE SUBROUTINES PAGE 7-7 03/06/81 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 (ac- cessed) and a status (count) value returned. In the last case, the positioning remains unchanged, but the status (count) is re- turned. 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 returned. 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 display, 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 re- turned in STRING$. Note that the linked question is not positi- oned to, thus enabling a user program to record multiple linked LOADABLE SUBROUTINES PAGE 7-8 03/06/81 names without having 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 system. 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. If the STATUS variable is present, the issuing BASIC program will STOP, and continue when the SPAWNED task exits. If no STATUS variable is present in the call, BASIC execution continues imme- diately. During the time that BASIC is STOPPED for the SPAWNED task, con- trol-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.) 03/06/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 03/06/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 03/06/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 SAMPLE LOADABLE MACRO SUBROUTINE PAGE B-2 03/06/81 1$: MOV R0,R4 ;SAVE LENGTH IN R4 BIS #160000,R0 ;MAKE R0 A "SCRATCH" DATA TYPE HEADER 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 / 03/06/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 USEFUL INTERNAL BASIC SUBROUTINE CALLS PAGE C-2 03/06/81 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 ; ; ; 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 USEFUL INTERNAL BASIC SUBROUTINE CALLS PAGE C-3 03/06/81 ; ; 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 ; ; ; ; 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 USEFUL INTERNAL BASIC SUBROUTINE CALLS PAGE C-4 03/06/81 ; .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. 03/06/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-5 Control O . . . . . . . . . . . 1-5 COR . . . . . . . . . . . . . . 4-3 COS . . . . . . . . . . . . . . 4-2 Cosine function . . . . . . . . 4-2 CPOS . . . . . . . . . . . . . . 7-7 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 03/06/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-4 FCS . . . . . . . . . . . . . . 4-3 File close . . . . . . . . . . . 1-3, 2-2, 6-4 File open . . . . . . . . . . . 6-3 File restore . . . . . . . . . . 6-1 FOR . . . . . . . . . . . . . . 3-5 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-3 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 03/06/81 MATXT . . . . . . . . . . . . . 7-7 MCR COMMAND LINE . . . . . . . . 1-4 MDIS . . . . . . . . . . . . . . 7-5 MID . . . . . . . . . . . . . . 5-2 MPOS . . . . . . . . . . . . . . 7-7 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-4 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 03/06/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-7 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-8 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 03/06/81 VAL . . . . . . . . . . . . . . 5-1 Value of string function . . . . 5-1 Variables . . . . . . . . . . . 1-2 Virtual arrays . . . . . . . . . 1-2, 3-2 WAIT . . . . . . . . . . . . . . 3-7 ^C . . . . . . . . . . . . . . . 1-5 ^O . . . . . . . . . . . . . . . 1-5