Directory of image this file is from
This file as a plain text file
SNOBOL-8.2 INTERNAL ROUTINE SUPPORT DESCRIPTION =============================================== 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. THE CALLING TABLES ================== 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: XBASE Holds the base that the number conversion routines use as a reference (initially set to 12(octal) for base ten) 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 DSk is used. XFILSI Normally zero; When set, it provides the minimum output file length specification for ENTER's.
PAGE 2 SNOBOL 8.2 Support routines 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 XX symbols must be added to the value held in XICLTB to give the correct address. For example, to reference the 'XXTOP' entry in the internal calling table: .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 This table also defines both routines and parameters. The parameters are documented below: XXPUTL Holds the PUTVAR table address; discussed below under concatenation XXPVR Holds the PUTVAR variable specification, see above 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. XXTOP Holds the address of the first unused location in field one. VARIABLE STORAGE ================ 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.
PAGE 3 SNOBOL 8.2 Support routines .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 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. READING VARIABLES ================= 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: .PAL 4 TAD XICLTB /THIS IS THE SAME EXAMPLE AS ABOVE TAD (XXGETC DCA GETC /WHERE GETC IS ON PAGE ZERO ^.SNOBOL 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. The following sets up a pointer to the first character of the string 'NAME': .PAL 7 TAD NAME /GET THE STRING STORAGE ADDRESS DCA PNAME CLA IAC /FIRST CHARACTER DCA PNAME+1
PAGE 4 SNOBOL 8.2 Support routines JMP .+3 PNAME, 0;0 ^.SNOBOL 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 CLEARING VARIABLES ================== 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: .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 WRITING VARIABLES ================= 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
PAGE 5 SNOBOL 8.2 Support routines 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: .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 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): .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 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: .PAL 6 TAD XICLTB TAD (XXCLV /OFFSET TO CLOSE VARIABLE ROUTINE DCA TX JMS I TX PNAME /SUPPORT POINTER
PAGE 6 SNOBOL 8.2 Support routines ^.SNOBOL Now 'NAME' may be referenced via SNOBOL code and will contain those characters written during the second stage. CONCATENATING STRINGS ===================== 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: Word 1/ address of string word 2/ (0-9) -character length, (10-11) character position 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: .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
PAGE 7 SNOBOL 8.2 Support routines DCA TX JMS I TX ^.SNOBOL There is no fail return.