BASIC DOCUMENTATION 03/06/81 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 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-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-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 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-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: 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-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-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-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 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-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-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 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-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 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-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 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-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-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-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 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 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 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-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 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-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-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