File SNORTS.RO

Directory of image this file is from
This file as a plain text file

.UPPER CASE;.NOFILL;.AC;.AP
		SNOBOL-8.2 INTERNAL ROUTINE SUPPORT DESCRIPTION
		===============================================

\\
.title ^^SNOBOL 8.2 Support routines\\
.fill;.
     THE ^^SNOBOL-8.2\\ RUNTIME SYSTEM (^^SNORTS\\) PROVIDES LOW-LEVEL ROUTINES THAT
THE INTERESTED PROGRAMMER MAY WANT TO TAKE ADVANTAGE OF.  ACCESS TO SINGLE
CHARACTERS FROM A STRING IN ^^PAL\\ MODE, 
AND MANIPULATION OF INPUT-OUTPUT 
paramETERS ARE APPLICATIONS THAT CALL FOR ACCESS 
TO SOME INTERNALS OF THE RUN-time
SYSTEM.
.
     THE INTERFACE BETWEEN THE RUN-TIME SYSTEM AND THE USER'S PROGRAM IS
THROUGH THE PARAMETER FILE ^^SNORTS.PR\\, WHICH DEFINES CALLING TABLES AND
OPERATOR DEFINITIONS.  WHILE THIS FILE MAINLY PROVIDES DEFINITION OF COMMON
ROUTINES WHOSE REFERENCES ARE AUTOMATICALLY GENERATED BY THE COMPILER, ALSO
DEFINED ARE SYMBOLS WHICH MAY BE USED TO ACCESS SUPPORT ROUTINES WITHIN
THE RUN-TIME SYSTEM.   THE REST OF THIS DOCUMENT EXPLAINS THE FUNCTION AND USE
OF THOSE ROUTINES CURRENTLY SPECIFIED IN ^^SNORTS.PR\\.
^IT SHOULD BE NOTED
THAT ^^SNORTS.PR\\ MAY CHANGE AS OFTEN AS VERSIONS OF THE RUN-TIME SYSTEM, AND
ALTHOUGH ROUTINES AND NAMES WILL (PROBABLY) NOT BE REMOVED, SOME MAY BE ADDED,
AND SOME MODIFIED IN FUNCTION.  IT IS IMPORTANT TO USE THE CORRECT VERSION OF
THE RUN-TIME SYSTEM WITH THE PROPER VERSION OF ^^SNORTS.PR\\, OTHERWISE UNDEFINED
RESULTS WILL OCCUR.

.TP 8;.nf
^^
THE CALLING TABLES
==================
.f;.
 \\    THERE ARE TWO CALLING TABLES MAINTAINED IN ^^SNORTS\\ TO DISPATCH REFERENCES
TO THE RUN-TIME SYSTEM.  THE FIRST BEGINS WITH THE SYMBOL ^^XINIT\\.  THIS TABLE
DEFINES THE MAIN SUPPORT ROUTINES - THOSE THAT ARE TYPICALLY INVOKED TO HANDLE
USER STATEMENTS.  THE SYMBOLS DEFINED IN THIS GROUP (ALL START WITH A SINGLE
"^X") ARE ESSENTIALLY LABELS THAT MARK LOCATIONS THAT HOLD THE STARTING ADDRESS
FOR THE ROUTINES THEY NAME; E.G. ^^XINIT\\ - INITIALIZATION ROUTINE,^^ PUSHJ\\ -
^^PUSHJ\\ COMMAND, ^^XPAT\\ - PATTERN MATCHING STATEMENTS, ETC.  THERE ARE ALSO A FEW
PARAMETER LOCATIONS:
.lm 9

.b;.I -8;^^XBASE\\	^HOLDS THE BASE THAT THE NUMBER CONVERSION ROUTINES 
USE AS A REFERENCE (INITIALLY SET TO 12(OCTAL) FOR BASE TEN)

.b;.I -8;^^XDEVS\\	^HOLDS THE ADDRESS OF TWO, TWO-WORD DEVICE NAME BLOCKS (IN STANDARD
SIXBIT '^^TEXT'\\ FORM) IN FIELD ZERO.  THE FIRST BLOCK IS THE INPUT DEVICE
(FOR ^^READ'\\S), AND THE SECOND IS THE OUTPUT DEVICE (FOR ^^WRITE'\\s AND
^^WRITEH'\\S).
THESE ARE THE LOCATIONS to modify if a device other than ^D^S^k is used.

.b;.tp 3;.I -8;^^XFILSI\\	^NORMALLY ZERO;  WHEN SET, IT PROVIDES THE MINIMUM OUTPUT FILE LENGTH
SPECIFICATION FOR ^^ENTER'\\S.



.fill;.LM 1;.p THE SECOND TABLE IS LOCATED AT THE ADDRESS SPECIFIED BY ^^XICLTB \\(INTERNAL CALLING TABLE), WHICH IS PART OF THE MAIN TABLE. THE OFFSETS TO THIS TABLE ARE DEFINED IN OFFSET FORM, STARTING WITH ^^XXCLRV\\ (=0; ALL OF THESE SYMBOLS BEGIN WITH TWO ^X'S). THE ABSOLUTE VALUE OF THE ^X^X SYMBOLS MUST BE ADDED TO THE VALUE HELD IN ^^XICLTB\\ TO GIVE THE CORRECT ADDRESS. .TP 8;FOR EXAMPLE, TO REFERence THE '^^XXTOP\\' ENTRY IN THE INTERNAL CALLING TABLE: .UC;.TP 8;.nf .PAL 6 TAD XICLTB /GET THE ADDRESS OF THE INTERNAL TABLE TAD (XXTOP /ADD IN OFFSET DCA TX TAD I TX /GET THE DESIRED VALUE _^_.SNOBOL \\ .fill;.p THIS TABLE ALSO DEFINES BOTH ROUTINES AND PARAMETERS. THE PARAMETERS ARE DOCUMENTED BELOW: .LM 9 .I -8;^^XXPUTL\\ ^HOLDS THE ^^PUTVAR\\ TABLE ADDRESS; DISCUSSED BELOW UNDER CONCATENATION .I -8;^^XXPVR\\ ^HOLDS THE ^^PUTVAR\\ VARIABLE SPECIFICATION, SEE ABOVE .I -8;^^XXSVCHH\\ ^NORMALLY ZERO WHICH MEANS IGNORE ^^ASCII\\ CODES 212-214 (PAPER MOTION CHARACTERS). WHEN SET TO -1, ALL CHARACTERS WITH CODES 212-214 (^^LF, VT, FF)\\ WILL BE PASSED TO INPUT STRINGS ON INPUT, AS THEY APPEAR. CARRiaGE RETURNS ALWAYS DELIMIT LINES. .I -8;^^XXTOP\\ ^HOLDS THE ADDRESS OF THE FIRST UNUSED LOCATION IN FIELD ONE. .LM 1
.TP 8 .nofill;^^ VARIABLE STORAGE ================ .f;.p;\\ WHEN A ^^SNOBOL\\-8.2 PROGRAM IS COMPILED, POINTERS FOR ALL VARAIBLES USED ARE GENERATED IN FIELD ZERO. EACH POINTER CONSISTS OF THE ADDRESS OF THE FIRST CHARACTER WITHIN THE STORAGE AREA IN FIELD ONE. THE STORAGE IS IN A LINKED LIST, WITH STRINGS STORED THREE CHARACTERS FOR TWO WORDS, EDITOR STYLE. THE RUN-TIME SYSTEM GENERATES ITS OWN POINTERS DURING PROCESSING OF USER COMMANDS. THE RUN-TIME SYSTEM'S POINTERS CONSIST OF THE ADDRESS WORD ALONG WITH A charactER POSITION DESIGNATION (ONE, TWO OR THREE - CORRESPONDING TO THE ALIGNMENT OF THE NEXT CHARACTER AT THE SPECIFIED ADDRESS. THEREFORE, OFTEN POINTERS MUST BE SPECIALLY GENERATED WHEN THE USER WISHES TO DEAL DIRECTLY WITH THE SUPPORT ROUTINES.
.nf;.tp 6 .^^PAL 10 TAD NAME /GET THE STRING ADDRESS DCA PNAME CLA IAC /FIRST CHARACTER DCA PNAME+1 JMP .+3 PNAME, 0;0 /NEW VARIABLE POINTER _^.SNOBOL\\ .f;.p THE POINTER '^^PNAME'\\ IS NOW READY FOR USE IN CALLING, FOR EXAMPLE, THE GET CHARACTER ROUTINE, AS DESCRIBED BELOW. IT MUST BE REMEMBERED THAT AFTER SETTING UP A POINTER THIS WAY, BOTH '^^NAME'\\ AND '^^PNAME'\\ REFER TO THE SAME STORAGE AREA, AND IF NAME IS DELETED OR MODIFIED, THEN ^^PNAME\\ MUST BE MODIFIED ACCORDingly, AS THE ADDRESS SPECIFIED BY ^^PNAME\\ HAS BECOME OBSOLETE. .nf;.TP 8;^^ READING VARIABLES\\ ================= .f;. READING A VARIABLE CHARACTER BY CHARACTER IS A SIMPLE TASK VIA ^^PAL\\ CODE. CHARACTERS ARE RETURNED IN EIGHT BIT BYTES, RIGHT JUSTIFIED IN THE ACCUMULATOR. NOTE THAT THE '^^GET CHARACTER'\\ ROUTINE IS DEFINED IN THE INTERNAL CALLING TABLE, SO A CALLING ADDRESS MAY BE SET UP TO FACILITATE SIMPLE CODING, AS: .nf;.tp 7; .^^PAL 4 TAD XICLTB /THIS IS THE SAME EXAMPLE AS ABOVE TAD (XXGETC DCA GETC /WHERE GETC IS ON PAGE ZERO _^.SNOBOL\\ .fill;.p THE NEXT STEP IS TO SET UP A POINTER THAT THE GET CHARACTER ROUTINE WILL USE TO ACCESS THE VARIABLE. IT IS A TWO WORD BLOCK, WHERE THE FIRST WORD CONtains THE ADDRESS OF THE DATA (IN FIELD ONE), AND THE SECOND CONTAINS THE CHARacter POSITION (1, 2 OR 3 - BUT IT IS NOT MODULO THREE - IT CORRESPONDS TO THE STORAGE POSITION, AS CHARACTERS ARE PACKED IN THE EDITOR THREE CHARACTERS FOR TWO WORDS FORMAT). ONE SHOULD NOT ATTEMPT TO COMPUTE THE CHARACTER POSITION FOR A CHARACTER IMBEDDED IN A STRING, AS LINKED LISTS MAKE THE PROGRESSION NON-linear.
.TP 8 THE FOLLOWING SETS UP A POINTER TO THE FIRST CHARACTER OF THE STRING '^^NAME'\\: .nf .^^PAL 7 TAD NAME /GET THE STRING STORAGE ADDRESS DCA PNAME CLA IAC /FIRST CHARACTER DCA PNAME+1 JMP .+3 PNAME, 0;0 _^.SNOBOL\\ .p;.TP 9; FINALLY, TO READ THE NEXT CHARACTER FROM THE STRING: .^^PAL 3 JMS I GETC /AS DEFINED ABOVE PNAME /ARG 1: POINTER ADDRESS JMP DONE /END OF STRING RETURN /OTHERWISE CHARACTER RETURNED IN ACCUMULATOR _^.SNOBOL .TP 6; CLEARING VARIABLES ================== .f;.p;\\ A VARIABLE MAY BE CLEARED SIMPLY BY ZEROING ITS POINTER, HOWEVER, THE SPACE USED BY THE VARIABLE IS NOT RECLAIMED, AND WOULD REMAIN UNCHANGED AND UNACCESSable UNLESS THE ADDRESS WAS SAVED EXPLICITLY. TO RECLAIM THIS AREA, ONE SHOULD CALL THE ^^XXCLRV\\ SUPPORT ROUTINE. THE FOLLOWING CODE WILL DELETE A VARIABLE'S STORAGE AND ITS POINTER: .nf; .^^PAL 11 TAD XICLTB TAD (XXCLRV /OFFSET TO CLEAR VARIABLE ROUTINE /JUMP ADDRESS DCA TX TAD NAME /GET ADDRESS OF STORAGE JMS I TX /RECLAIM THAT STORAGE DCA NAME /AND DELETE THE POINTER JMP .+2 TX, 0 _^.SNOBOL\\
.uc;.tp 8; WRITING VARIABLES ================= .f;.p;\\ WRITING A NEW VARIABLE REQUIRES THREE DISTINCT STEPS: (1) FIND SPACE IN FIELD ONE FOR THE VARIABLE STRING STORAGE, (2) WRITING THE STRING, CHARACTER BY CHARACTER, AND (3) CLOSING THE VARIABLE WHEN DONE. THERE ARE THREE SUPPORT ROUTINES TO HANDLE THESE FUNCTIONS. FIRST, A VARIABLE POINTER FOR THE NEW STRING MUST BE GENERATED. IF THE VARIABLE IS EVER REFERENCED VIA ^^SNOBOL\\ CODE, THEN THAT NAME WILL APPEAR AS A VARIABLE POINTER AUTOMATICALLY. THIS POINTER MUST BE MANIPULATED ONLY VIA ^^SNOBOL\\ CODE, EXCEPT WHEN IT IS INITIALIZED DURING THIS FIRST STAGE. FROM THE POINT AT WHICH THE POINTER IS INITIALIZED TO THE POINT AT WHICH IT IS CLOSED (STAGE 3), THE VARIABLE SHOULD NOT BE REFERENCED BY ^^SNOBOL\\ CODE, ELSE THE END OF THE STRING WILL RUN ON INTO THE NEXT STRING IN VARIABLE STORAGE. A SEPARATE POINTER MUST BE SET UP FOR USE BY THE SUPPORT ROUTINES. THIS POINTER WILL BE UPDATED AS REquired BY THE SUPPORT ROUTINES, AND BECOMES OBSOLETE WHEN THE VARIABLE IS CLOSED. ASSUMING THE VARIABLE (IN THIS EXAMPLE, THE VARIABLE NAME IS '^^NAME'\\ AND IS REFERenced WITHIN ^^SNOBOL\\ CODE) TO BE WRITTEN IS EMPTY AT THIS POINT, THE FOLLowing CODE WILL FIND SPACE FOR THE STRING AND SET UP BOTH POINTERS: .NF; .^^PAL 15 TAD XICLTB TAD (XXFNDS /OFFSET TO FIND SPACE ROUTINE DCA TX JMS I TX /FIND SPACE DCA NAME /SETUP SNOBOL POINTER TAD NAME DCA PNAME /SETUP SUPPORT WRITE POINTER CLA IAC /(FIRST CHARACTER) DCA PNAME+1 JMP .+3 PNAME, 0;0 _^.SNOBOL\\ .f;.; SECOND, ANY NUMBER (UP TO 256) OF CHARACTERS MAY BE WRITTEN TO THIS STRING SEQUENTIALLY BY LOADING THE CHARACTER INTO THE ACCUMULATOR AND CALLING THE WRITE CHARACTER ROUTINE. THIS ROUTINE HAS A FAIL RETURN THAT IS NOT USED (I.E. ANY INSTRUCTION MAY BE PLACED IN THIS POSITION FOLLOWING THE CALL, AND IT WILL NOT BE EXECUTED): .NF; .^^PAL 11 TAD XICLTB TAD (XXWRCH /OFFSET TO WRITE CHARACTER ROUTINE DCA TX TAD ("X /GET AN 'X' TO WRITE TO THE STRING JMS I TX /WRITE IT PNAME /SUPPORT POINTER HLT /FAIL RETURN _^.SNOBOL\\ .f;.; FINALLY, TO CLOSE THE STRING, A CALL TO THE '^^CLOSE VARIABLE'\\ ROUTINE MUST BE MADE WITH THE ADDRESS OF THE POINTER FOLLOWING THE CALL. THERE IS NO FAIL RETURN: .nf;.tp 7; .^^PAL 6 TAD XICLTB TAD (XXCLV /OFFSET TO CLOSE VARIABLE ROUTINE DCA TX JMS I TX PNAME /SUPPORT POINTER _^.SNOBOL\\ .f;.; NOW '^^NAME\\' MAY BE REFERENCED VIA ^^SNOBOL\\ CODE AND WILL CONTAIN THOSE CHARACTERS WRITTEN DURING THE SECOND STAGE.
.nf;.UC;.TP 6 CONCATENATING STRINGS ===================== .f;.p;.LC STRINGS AND PARTS OF STRINGS RESIDING IN FIELD ONE VARIABLE STORAGE MAY BE SIMPLY CONCATENATED INTO A NEW STRING BY USING THE 'PUT VARIABLE' ROUTINE. A TABLE IS SET UP BY THE USER WHICH DESCRIBES THE ADDRESS, CHARACTER POSITION, AND LENGTH OF STRINGS. THEN THE ADDRESS OF A ^^SNOBOL\\ POINTER IS STORED IN THE LOCATION (^^XICLTB)+XXPVR\\. WHEN THE PUT VARIABLE ROUTINE IS INVOKED, THE STRINGS ARE COPIED INTO THE NEW VARIABLE IS THE SPECIFIED ORDER. NOTE THAT THE POINTER SUPPLIED IN LOCATION ^^XXPVR \\IS THE ^^SNOBOL\\ POINTER, AND NOT A SUPPORT POINTER. THIS VARIABLE NEED NOT BE EMPTY - ITS PREVIOUS CONTENTS, IF ANY, ARE DELETED BEFORE THE NEW STRING IS ASSIGNED. ^THE CHARACTER POSITION SPECIFIED FOR EACH SUB-STRING AGAIN CORRESPONDS TO THE STORAGE ALIGNMENT, AND CANNOT BE DEDUCED FROM THE CHARACTER POSITION WITHIN THE STRING. TO FIND THE CORRECT POSITION VALUE FOR AN ARBITRARY CHARACTER WITHIN THE STRING (WHEN A SUB-STRING BEGINNING AT THAT POSITION IS DESIRED), THE '^^GET CHARACTER'\\ ROUTINE SHOULD BE USED TO SPACE TO THE CORRECT POSITION, AND THEN THE SECOND WORD OF THE SUPPORT POINTER CAN BE USED TO SUPPLY THE DESIRED POSITION VALUE. ALSO, THE SUPPORT POINTER SHOULD BE ACCESSED TO GIVE THE CORRECT STRING ADDRESS. THE FORMAT OF THE TABLE IS TWO WORD ENTRIES, TERMINATED BY AN ENTRY WITH WORD ONE BEING NEGATIVE ONE. THE TWO WORD ENTRIES HAVE THE FORM: .nf; WORD 1/ ADDRESS OF STRING WORD 2/ (0-9) -CHARACTER LENGTH, (10-11) CHARACTER POSITION .f;. THE CHARACTER LENGTH MAY BE ZERO TO SPECIFY NO LENGTH LIMITATION, AND THE LENGTH IS ONLY MEANINGFUL IF THERE ARE AT LEAST THAT MANY CHARACTERS BEFORE THE END OF THE STRING. ASSUMING THE TABLE HAS BEEN SET UP (IT BEGINS AT THE LOCATION SPECIFIED BY THE ^^XXPUTL\\ ENTRY IN THE INTERNAL CALLING TABLE), AND THE ^^SNOBOL\\ VARIABLE '^^NAME'\\ IS THE DESIRED TARGET VARIABLE, THE FOLLOWING SEQUENCE WILL ACCOMPLISH THE CONCATENATION FUNCTION: .nf; .^^PAL 14 TAD XICLTB TAD (XXPVR /OFFSET TO TARGET VARIABLE ADDRESS DCA TX TAD (NAME /GET THE ADDRESS OF THE SNOBOL POINTER DCA I TX /SAVE IT FOR PUTVAR TAD XICLTB TAD (XXPUTV /OFFSET FOR PUT VARIABLE ROUTINE DCA TX JMS I TX _^.SNOBOL\\ ^THERE IS NO FAIL RETURN.



Feel free to contact me, David Gesswein djg@pdp8online.com with any questions, comments on the web site, or if you have related equipment, documentation, software etc. you are willing to part with.  I am interested in anything PDP-8 related, computers, peripherals used with them, DEC or third party, or documentation. 

PDP-8 Home Page   PDP-8 Site Map   PDP-8 Site Search