CP/M

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

/ CP/M / CPM_CDROM.iso / enterprs / cpm / utils / s / zbasic.arc / ZBASIC.DOC < prev

Wrap

Text File | 1987-08-27 | 17.3 KB | 348 lines

"ZBASIC.DOC" ZBASIC WAS ORIGINALLY WRITTEN TO RUN UNDER NORTH STAR DOS AND FULLY REPLACE NORTH STAR BASIC. RATHER THAN COMPLETELY REWRITING ALL DISK I/O FUNCTIONS, I DECIDED TO USE AN EXISTING CP/M INTERFACE AND REWRITE AND FULLY INTEGRATE IT. THEREFORE , ZBASIC IS UNABLE TO ACCESS FILES THAT HAVE ANY FILENAME OTHER THAN *.?ZB. THE LAST TWO LETTERS OF THE FILE TYPE MUST BE "ZB" FOR ZBASIC TO RECOGNIZE THE FILE AT ALL. FOR MORE INFORMATION ON FILE NAME SYNTAX REFER TO THE DISK RELATED COMMANDS. ZBASIC IS FULLY NORTH STAR BASIC SYNTAX COMPATIBLE, WITH ALL IT'S ADVANTAGES AND DISADVANTAGES. IT PERFORMS SLIGHTLY FASTER THAN NORTH STAR BASIC. AND, OF COURSE, IT OFFERS SOME EXTRA COMMANDS AND RUNS UNDER CP/M FULLY CONFIGURED, SO YOU DO N'T HAVE TO GO THROUGH THE HASSLE OF INTERFACING IT YOURSELF. ZBASIC IS THE PRODUCT OF TWO YEARS' WORK TRYING TO IMPROVE NORTH STAR BASIC WITHOUT LOSING THE COMPATIBILITY. IN ALL FAIRNESS I HAVE TO ADMIT THAT WITHOUT A DISASSEMBLY OF NORTH STAR BASIC RELEASE 4.0 I WOULD HAVE NOT BEEN ABLE TO DO IT. I MIGHT ADD THAT I WILL MOST LIKELY NEVER TOUCH THE ZBASIC SOURCE CODE AGAIN AND THAT THERE WILL BE NO FURTHER UPDATES OF EITHER THE INTERPRETER OR THIS MANUAL. UNCOMPLETE AS IT IS, THIS DOCUMENT SHOULD BE EASY TO FOLLOW BY ANYONE FAMILIAR W ITH NORTH STAR BASIC. *FP0 *CN1;LIST OF DIRECTLY EXECUTABLE COMMANDS ONLY*CN0 ALOAD APPEND AUTO BYE CAT COMPACT CONT DELETE EDIT LIST LOAD MEMSET PSIZE REN RUN SAVE SCR LIST OF STATEMENTS CHAIN CLOSE CREATE DATA DEF FN DESTROY ELSE END ERRSET EXIT FILL FOR GOSUB GOTO IF INPUT INPUT1 LET LINE NEXT NOENDMARK ON OPEN OUT PRINT READ REM RESET RESTORE RETURN SORT SORT1 STOP TROFF TRON WRITE LIST OF BUILT-IN FUNCTIONS ABS ASC ATN CALL CHR$ COS EXAM EXP FILE FILEPTR FILESIZE FREE INCHAR$ INP INT LEN LOG RND SIN SGN SQRT STR$ TYP VAL$ PLEASE NOTE THAT ALL INPUT TYPED TO ZBASIC WILL BE TRANSLATED TO UPPER CASE, EXCEPT IF IT IS INSIDE QUOTES. THIS ALLOWS YOU TO USE LOWER CASE COMMANDS. ZBASIC DIRECT COMMANDS ALOAD THE ALOAD COMMAND IS SIMILAR TO THE LOAD COMMAND. IT WILL, HOWEVER LOAD A FILE OF TYPE .2ZB WHICH IS IN ASCII. THEREFORE, ZBASIC PROGRAMS CAN NOW BE PREPARED USING AN EDITOR. THE FILES MUST CONFORM TO THE FOLLOWING SIMPLE RULES: 1. NO EMPTY LINES OR LINES STARTING WITH A NON-NUMERIC ASCII CHARACTER. 2. TERMINATED BY A CONTROL/Z. AFTER LOADING THE FILE, ZBASIC WILL TOKENIZE THE PROGRAM. THIS CAN TAKE FROM A FEW SECONDS TO AS MUCH AS ONE MINUTE, DEPENDING ON THE SIZE OF THE PROGRAM. APPEND THE APPEND COMMAND IS USED TO APPEND A PROGRAM FILE TO THE PROGRAM CURRENTLY IN RAM. THE FOLLOWING CONDITIONS MUST BE TRUE: 1. THE HIGHEST LINE NUMBER IN THE CURRENTLY LOADED PROGRAM MUST BE LOWER THAN THE LOWEST LINE NUMBER IN THE PROGRAM TO BE APPENDED. 2. THE PROGRAM TO BE APPENDED MUST BE A TOKENIZED FILE. AUTO AUTO GENERATES LINE NUMBERS AUTOMATICALLY. YOU CAN CONTROL THE STARTING LINE NUMBER AND THE INCREMENT. BOTH DEFAULT TO TEN. EXAMPLE: AUTO 20 STARTS AT LINE 20, INCREMENT 10. AUTO 100,5 STARTS AT 100 WITH INCREMENT OF 5. BYE USED TO EXIT ZBASIC AND RETURN CONTROL TO CP/M. CP/M WILL EXECUTE A WARM BOOT. CAT CAT DISPLAYS THE FILE CATALOG (DIRECTORY). CAT WITHOUT ARGUMENTS DISPLAYS THE CP/M LOGGED DRIVE. OPTIONAL ARGUMENTS ARE DEVICE NUMBER AND DRIVE. THE DEVICE NUMBER IS 0 OR 1 FOR CONSOLE OR PRINTER, RESPECTIVELY, WHILE THE DRIVE NUMBER IS A NUMBER IN RANGE 1..15. PLEASE NOTE THAT CAT WILL CORRECTLY DISPLAY THE DIRECTORY FOR ANY CP/M DRIVE, WHILE ANY OTHER FILE MANIPULATION CAN BE PERFORMED ONLY ON DRIVES 1..7 (A:..G:)! EXAMPLE: CAT #1 WILL SEND THE DEFAULT DRIVE DIRECTORY TO THE PRINTER, CAT #1,5 WILL SHOW THE DIRECTORY OF DRIVE E: ON THE PRINTER. COMPACT THE COMPACT COMMAND WORKS ON THE LOADED PROGRAM AND REMOVES ALL UNNECESSARY BLANKS FOR FAST EXECUTION. BLANKS INSIDE QUOTED STRINGS AND REM STATEMENTS ARE LEFT UNTOUCHED. WHEN COMPACT IS FINISHED, ALL PROGRAM VARIABLES AND DATA WILL BE LOST AND IT HAS TO BE RE-RUN. COMPACT WORKS ONLY IN DIRECT MODE. CONT AFTER STOPPING A PROGRAM WITH CONTROL-C, THE CONT COMMAND CAN BE USED TO RESTART IT. CONT WILL FAIL IF THE PROGRAM HAS BEEN MODIFIED (BUT VARIABLES CAN BE MANIPULATED). DELETE DELETE CAN BE USED TO DELETE MULTIPLE PROGRAM LINES. FOR EXAMPLE, DELETE 100 WILL DELETE ONLY LINE # 100, BUT DELETE 1,100 WILL DELETE ALL LINES FROM 1 TO 100, INCLUSIVELY. EDIT EDIT ALLOWS EDITING A FULL LINE INCLUDING IT'S LINE NUMBER. THE EDIT COMMAND PLACES THE LINE TO BE EDITED INTO AN EDIT BUFFER AND THE FOLLOWING COMMANDS CAN BE USED TO ACT ON THE LINE: CONTROL-A COPIES ONE CHARACTER FROM THE OLD LINE CONTROL-D COPIES CHARACTERS FROM THE OLD LINE UP TO, BUT NOT INCLUDING, THE CHARACTER TYPED IMMEDIATELY AFTER TYPING THE CONTROL-D. CONTROL-G COPY REMAINDER OF LINE CONTROL-Y TOGGLE INSERT MODE (DEFAULT OFF) CONTROL-Z DELETE CHARACTER FROM OLD LINE LIST LISTS ALL OR PART OF A PROGRAM. WITH NO ARGUMENTS, LISTS THE COMPLETE PROGRAM TO THE CONSOLE, PAUSING AFTER EACH SCREENFUL. LIST #1 SENDS THE LISTING TO THE PRINTER, WITH A FORM FEED AT THE BEGINNING AND AFTER EVERY N LINES, WHERE N IS A VA LUE PATCHED INTO ZBASIC (DEFAULT = 56). LIST 10,1000 LISTS ALL LINES BETWEEN 10 AND 1000, INCLUSIVELY. LOAD LOAD IS USED TO LOAD A TOKENIZED ZBASIC PROGRAM FILE. PROGRAM FILES ARE RECOGNIZED BY THE FILE TYPE "2ZB". IF LOAD FAILS OR PRODUCES GARBAGE, THE FILE MAY BE ASCII. USE ALOAD TO LOAD AN ASCII FILE. EXAMPLE: LOAD TOASCII WOULD LOAD THE FILE TOASCII.2ZB FROM THE DEFAULT DRIVE. OVERRIDE DEFAULT DRIVE BY APPENDING A COMMA AND THE DRIVE NUMBER TO THE FILE NAME (FOR EXAMPLE TO LOAD THE FILE FROM DRIVE C:, TYPE LOAD TOASCII,3.) MEMSET USE THE MEMSET COMMAND TO RESERVE MEMORY BELOW THE BDOS. THE ARGUMENT IS THE HIGHEST RAM ADDRESS USED BY ZBASIC, IN DECIMAL. FOR EXAMPLE, MEMSET 32768 RESERVES ALL MEMORY FROM 8001H TO BDOS. PSIZE PSIZE SHOWS THE SIZE OF THE CURRENTLY LOADED PROGRAM IN 256 BYTE BLOCKS. USE THE PSIZE COMMAND TO AID IN CONSTRUCTING AN AUTOLOADING COPY OF ZBASIC. REN THE REN COMMAND ALLOWS FOR RENUMBERING A PROGRAM. REN CAN BE USED WITH UP TO TWO ARGUMENTS, THE STARTING LINE NUMBER AND THE INCREMENT. BOTH DEFAULT TO 10. FOR EXAMPLE, REN WOULD RENUMBER THE PROGRAM STARTING BY MAKING THE LOWEST NEW LINE NUMBER 10, AND INCREMENTING BY 10. REN 100,5 WOULD RENUMBER IN STEPS OF 5, MAKING THE LOWEST NEW LINE NUMBER 100. RUN USE RUN TO EXECUTE OR RE-EXECUTE A PROGRAM IN MEMORY. AN OPTIONAL LINE NUMBER INDICATES WHERE TO START RUNNING THE PROGRAM. BEFORE STARTING A PROGRAM, ALL VARIABLES AND POINTERS ARE RESET! SAVE THE SAVE COMMAND CAN BE USED TO SAVE A PROGRAM IN MEMORY ON DISK. IF THE FILE ALREADY EXISTS, THE PROGRAM WILL BE WRITTEN INTO THE FILE. IT NOW NO LONGER MATTERS WHETHER THE ARGUMENT TO SAVE EXISTS OR NOT, NEITHER DOES ITS SIZE MATTER IN AN Y WAY. SAVE ALWAYS DELETES A PRE-EXISTING FILE BY THAT NAME, THEN SAVES THE NEW FILE. THIS OPERATION IS DONE WITHOUT INTERVENTION FROM THE DOS SIMULATOR PACKAGE. NSAVE IS THEREFORE UNNECESSARY AND NO LONGER INCLUDED. SCR USE THE SCR COMMAND TO SCRATCH (DELETE) THE PROGRAM CURRENTLY IN MEMORY. ALL VARIABLES AND POINTERS WILL BE ZEROED. INCLUDE THE INCLUDE STATEMENT WORKS LIKE APPEND, BUT IS ALLOWED DURING PROGRAM EXECTION. PLEASE BE SURE TO OBSERVE ALL RULES THAT APPLY TO THE USE OF APPEND, AND BE AWARE THAT AFTER EXECUTION OF INCLUDE, ALL VARIABLE SPACE IS ZEROED. THE MAIN USE O F INCLUDE IS TO "PULL IN" A CODE SEGMENT THAT IS COMMON TO A NUMBER OF DIFFERENT PROGRAMS (SUCH AS A SUBROUTINE LIBRARY IN AN ACCOUNTING PACKAGE. INCLUDE SHOULD, NATURALLY, BE THE FIRST STATEMENT EXECUTED IN THE PROGRAM. RESET RESET IS USED AFTER A DISK CHANGE TO REINITIALIZE BDOS. IT, AS WELL AS ALL FOLLOWING NEW KEYWORDS, IS BOTH EXECUTABLE IN PROGRAM AND DIRECT MODE. SORT AND SORT1 SORT AND SORT1 WORK ON STRING VARIABLES ONLY. SORT SORTS THE STRING IN ASCENDING ORDER, WHILE SORT1 SORTS IN DESCENDING ORDER. THE SYNTAX IS: SORT <STRING VARIABLE>,<FIELDS>,<FIELD LENGTH> WHERE <STRING VARIABLE> CAN BE ANY LEGAL STRING VAR IABLE, SUCH AS A$, X9$, F$(7,99), B$(S,E), ETC. <FIELDS> IS THE NUMBER OF SUB-STRINGS TO BE SORTED AND <FIELD LENGTH> IS THE SIZE OF THE SUB-STRING WHICH REPRESENTS THE DATA TO BE SORTED. THIS, OF COURSE, MEANS THAT WITH TWO DIFFERENT SUBSTRINGS, THE SH ORTER ONE HAS TO BE PADDED (USUALLY WITH BLANKS.) THE PRODUCT OF <FIELDS> AND <FIELD LENGTH> MUST ALWAYS BE EQUAL TO OR LESS THAN THE SIZE OF THE STRING REFERENCED IN THE STRING VARIABLE. SINCE ALL SUB-STRINGS HAVE TO BE OF EQUAL LENGTH, THE LENGTH OF A LL SUBSTRINGS IS USUALLY DETERMINED BY THE LENGTH OF THE LONGEST DATA ITEM. EXAMPLES: 10 DIM A$(1000) 20 ... BUILD STRING ETC. 30 SORT A$,5,LEN(A$)/5 IN THIS CASE, EACH SUBSTRING IS ASSUMED TO BE 200 CHARACTERS LONG, WITH 5 SUBSTRINGS FOR A TOTAL OF 1000 BYTES. THE FOLLOWING EXAMPLE WOULD PRODUCE AN ERROR, SINCE 5 * 300 > 1000: 30 SORT A$,5,300 IN THE NEXT CASE, NO ERROR WOULD OCCUR, BUT BYTES 500 THROUGH 1000 IN A$ WOULD BE LEFT UNTOUCHED: 30 SORT A$,5,100 OF COURSE IT IS ALSO POSSIBLE TO USE COMPLEX ARITHMETIC EXPRESSIONS IN THE SORT STATEMENT: 30 SORT A$(N(I),N(J)),FNX(B/5),(N(I)-N(J))/(B/5) WHETHER OR NOT IT WOULD WORK DEPENDS SOLELY ON WHETHER THE EXPRESSIONS EVALUATE TO "IN BOUNDS." TRON, TROFF TRON AND TROFF ARE USED TO TURN THE TRACE FLAG ON AND OFF. IN TRACE MODE, ALL LINENUMBERS ARE DISPLAYED IN SQUARE BRACKETS BEFORE THEY ARE EXECUTED. FOR FURTHER EXAMPLES IN THE FORM OF A PROGRAM LOAD AND RUN THE FILE "TEST.2ZB" WHICH IS INCLUDED IN THIS PACKAGE. PECULIARITIES ZBASIC FOR CP/M IS A COMPROMISE. I DECIDED NOT TO WRITE A COMPLETE NEW SET OF DISK I/O ROUTINES, BUT RATHER SETTLED FOR A QUITE SATISFACTORY PERFORMANCE USING A HIGHLY MODIFIED AND TRIMMED NSCPM INTERFACE. THIS INTERFACE WAS WRITTEN FOR USE WITH NORTH STAR BASIC RELEASE 4 SINGLE DENSITY AND PUT IN THE PUBLIC DOMAIN BY THE CP/M USER GROUP. I MODIFIED AND REDISTRIBUTED IT FOR USE WITH DOUBLE DENSITY BASIC 5.2 AND IT IS AVAILABLE ON MANY RCPM SYSTEMS. THE FOLLOWING IS A LIST OF THINGS TO WATCH OUT FOR WHEN USING ZBASIC. 1. ZBASIC FILE TYPES ARE .?ZB WHERE ? IS THE "NORTH STAR FILE TYPE," IN ASCII. FOR EXAMPLE, "TEST.2ZB" WOULD BE A LOADABLE ZBASIC PROGRAM AND "DATA,3ZB" WOULD BE A DATA FILE. PLEASE NOTE THAT TWO FILES WITH THE SAME NAME, BUT DIFFERENT FILE TYPE, SUCH AS "TEST.2ZB" AND "TEST.3ZB" CANNOT COEXIST ON THE SAME DISK! ALSO, IF YOUR CP/M DIRECTORY SHOWS THE FOLLOWING FILES: TEST .FZB TEST .2ZB TEST .ASM THE FILE ENDING IN .ASM WOULD BE INACCESSIBLE BY ZBASIC. THE FILE TEST.FZB IS ACCESSIBLE, BUT DUE TO THE FACT THE TEST.2ZB IS SECOND IN THE DIRECTORY, IT COULD NOT BE LOADED BY ZBASIC. 2. NORMALLY, ZBASIC DATA FILES USE THE FILE TYPE "3" (AS NORTH STAR BASIC DOES,) BUT 30H IS ADDED TO THE FILE TYPE IN ORDER TO BE ABLE TO PROCESS AND DISPLAY IT. YOU CAN CREATE A FILE OF TYPE N IN ZBASIC, WHERE N MUST BE BETWEEN 0 AND 79, SINCE 7 9+48=127; THE HIGHEST DISPLAYABLE CHARACTER IN ASCII. A TYPE GREATER THAN 79 WILL CAUSE THE ACTUAL FILE TYPE TO BECOME (TYPE MOD 79.) 3. INTERNALLY, ZBASIC SIMULATES A NORTH STAR DOS ENVIRONMENT. THE ONLY EXCEPTION TO THIS RULE IS THAT, BEGINNING WITH VERSION 1.51 AS OF 9/7/83, ZBASIC WILL DEFAULT TO THE CURRENT CP/M DISK. SO, IF YOU ARE LOGGED INTO C:, THE CAT COMMAND WILL SH OW FILES ON DRIVE C:, AND "CAT" WILL BE EQUIVALENT TO THE COMMAND "CAT 3". 4. ZBASIC CAN BE RE-EXECUTED WITH THE ZCPR "GO" COMMAND OR WITH A FILE "GO.COM" OF SIZE 0K. THE LOADED PROGRAM, IF ANY, WILL BE PRESERVED. 5. ZBASIC CAN BE MADE TO AUTO-RUN A FILE IN THE SAME FASHION AS NORTH STAR BASIC. THESE ARE THE STEPS TO ACCOMPLISH THIS (KNOWLEDGE OF CP/M UTILITIES IS ASSUMED.). DETERMINE THE SIZE OF ZBASIC IN 256-BYTE PAGES. NOW, EXECUTE ZBASIC AND LOAD THE PROGRAM TO BE AUTOSTARTED. DO NOT RUN THE PROGRAM! EXECUTE PSIZE TO FIND THE PROGRAM SIZE. ADD THE NUMBER TO THE SIZE OF ZBASIC. NOW SET THE AUTOS FLAG TO 0 BY EXECUTING FILL 261,0. ALSO, DISABLE THE WARMSTART FLAG WITH FILL 260,0. LEAVE ZBASIC WITH BYE AND DO A SAVE XX FILENAME.COM, WHERE XX IS THE TOTAL SIZE OF ZBASIC PLUS THE PROGRAM, AS OBTAINED ABOVE. 6. ZBASIC WILL NOW "UNDERSTAND" LOWER CASE INPUT. ALL LOWER CASE CHARACTERS TYPED IN EITHER AS A COMMAND OR WHEN ENTERING A PROGRAM WILL BE CAPITALIZED BEFORE THEY ARE EXECUTED. TEXT ENCLOSED IN QUOTES (STRING LITERALS) WILL BE LEFT UNCHANGED. THE CAPITALIZATION DOES NOT AFFECT TEXT TYPED AT AN INPUT PROMPT. 7. IF YOU DO NOT USE NORTH STAR HARDWARE, YOU MUST SET THE CONTR BYTE TO 0, OR YOU WILL BE FORCED TO COLD-BOOT EVERY TIME YOU EXECUTE A PROGRAM WHICH USES A "RND(-1)" STATEMENT. IF YOU USE NORTH STAR HARDWARE, THIS BYTE MUST BE SET TO THE MOST S IGNIFICANT BYTE OF YOUR CONTROLLER ADDRESS. NOTE THAT THIS AUTO-SEEDING FEATURE WILL NOT WORK IN NON-NORTH STAR HARDWARE. 8. THERE ARE TWO MORE FEATURES: THE COMMAND LINE (OR ANY PROGRAM LINE, FOR THAT MATTER, MAY NOW BE UP TO 255 CHARACTERS LONG. IT DEFAULTS TO 80 CHARACTERS/LINE, BUT CAN BE CHANGED WITH THE LINE COMMAND. WHEN PRINTING A PROGRAM LISTING WITH LIST #1 (TO THE LST: DEVICE,) THE OUTPT WILL BE PAGED. THIS IS ACCOMPLISHED BY SENDING A FORM FEED CHARACTER AT THE START OF THE LISTING AND AFTER EVERY 60 LINES. THE PRINTER PAGE LENGTH IN LINES IS CHANGEABLE (SEE THE CUSTOMIZATION NOTES.) 9. REVISION 1.3 INTRODUCES THE NEW ALOAD COMMAND FOR ASCII FILE LOADING. I AM WORKING ON ASAVE, BUT MAY NOT IMPLEMENT IT FOR SOME TIME. I HAVE THEREFORE INCLUDED TOASCII.2ZB IN THE PACKAGE, WHICH IS AN UN-TOKENIZING PROGRAM FOR ZBASIC. 10. WHILE PREVIOUS VERSIONS OF ZBASIC MAY HAVE REJECTED DRIVE NUMBERS GREATER THAN 4, THE LATEST VERSIONS WILL NOW ACCEPT DRIVES AS HIGH AS 6, OR CP/M DRIVE F:. A BUG IN THE READ AND WRITE ROUTINES, UNFORTUNATELY, PREVENTS ZBASIC FROM PROPERLY HANDLING DRIVES GREATER THAN F:. THIS UNFEATURE WILL NOT BE FIXED.