Directory of image this file is from
This file as a plain text file
.margins 6,65;.uc;.subtitle INTRODUCTION .Title PAL8 SUBROUTINE LIBRARY .bl 3 .c;^&Version 2.2, December 1976\& .bl 5 .p There has been an attempt to produce a library of commonly used PAL8 subroutine sources. The library was not designed to replace the library maintenance facilities of relocatable assembler/loader systems, but rather to be a quick solution to the present common problems facing the PDP-8 programmer. .p The purpose of this document is to briefly describe each routine, including the related programs needed to access the library. Also included is a short description of the working documentation concept which is Closely associated with the library idea. In the first section the SNOBOL program which does the source extraction is described. In the next section each of the subroutines is described with documentation that is taken directly from the source. See the description of the "WORKING DOCUMENTATION GENERATOR" for more information on this process. .p This document is in a "WORKING" form in the sense that it is constantly being updated and improved. For example, in some earlier versions the characters ">" and "<" were used as flag characters; they are unacceptable because they are the characters used for conditional assembly in PAL8. Any constructive comments or suggestions would be appreciated at this time. Also needed are subroutines which you feel should be included, or similar routines in different forms. Please direct any comments or questions to: .b;.nf The Computer Science Research Laboratory Northwestern University Technological Institute Room B626, 2145 Sheridan Road Evanston, Illinois 60201 .f .page
.subtitle The Library Scan Program .p The Library Scan Program is a SNOBOL program to scan the subroutine library for desired modules and write these modules to a file. The program will also generate page zero links to the modules, if desired. .p There are two ways to link the library modules with your own main program. One way is to have the program generate page zero links of the form: .nf;.b 2 TYPE=JMS I .;XTYPE CRLF=JMS I .;XCRLF . . . .f;.j .p;This will allow the programmer to use a pseudo high level language. For example, instead of using the statement JMS XTYPE, he may now use the statement TYPE. Page zero links begin at location 20, and extend to the end of page zero. Following the page zero pointers, space is allocated for any global variables. .p If page zero links are not desired, the programmer must either generate his own links or allow PAL8 to generate the links for him, by calling the modules directly with the "JMS". Both forms of the call are used interchangably in the descriptions of calling sequences. .p To create a file of modules: .b;1. SCAN must run in OS/8, so the fist step is to copy SCAN.SV, the library scanning program, to your OS/8 device. .b 2. Copy the most recent version of the library to your OS/8 device. For SNOBOL 8.2 all files must be on the DSK: device. .tp 10;.b;3. Run the program as follows: .NF;.b 1;.m 9,72 _.R SCAN SUBROUTINE LIBRARY PROCESSING PROGRAM INPUT: [Enter the OS/8 name of the library] OUTPUT: [Enter the filename to contain the modules] ENTER NAMES OF DESIRED ROUTINES, TERMINATE WITH "END" ?TEST ?MSGC ?TYPE ?END [To end] PAGE ZERO LINKS (Y OR N)? Y [Answer appropriately] PASS ONE MODULES: TYPE CRLF MSGC MSG END OF PASS ONE MISSING MODULES ** TEST ** [Not found in pass one] SECONDARY MODULES: MSG CRACK CRLF [Modules not requested, but included because they were needed by other included modules] PASS TWO MODULES: [Modules loaded during second scan of library] TYPE CRLF CRACK _etc. _.
.m 1,65 .b 2 4. Now include your main program in the file you specified as the output file, and assemble and run your program as usual. .b 3 .p While running the program, the following errors can occur: .NF;.b 3 OUTPUT ERROR! .P The program could not output a line to the output file. This could be caused by a disk error or, more likely, a full disk. .B 2 INPUT ERROR! .P An error occured while attempting to read a line from the input file. This is caused by a hardware error. .f;.j .MARGINS 1,72;.NO NUMBER
.page .SUBTITLe Creating and Updating a Library file .p The library file can be created and updated using almost any standard editor. The form of the file was designed so that most routines could be extracted directly from already written programs with only a few modifications. The minumum needed for operation of the SCAN program is a "/+module name" before the module and a "/-module name" after it. If the working documentation generator is to be used, a "/:" must be inserted before the code. If the automatic capialization feature is used, care must be taken in the formatting of the text description between the "/+" and the "/:". Another approach is to edit the RUNOFF input file after it is extracted from the program. .p The subroutine library processor does not handle multiple entry points at this time; it is assumed that the entry point of any subroutine is given by it's name followed by a comma. This means that even if page zero links are going to be used, the subroutine should be written as though it did ^¬\& use them. For example, the subroutine to print return line feed is coded as: .nf THIS: NOT THIS: CRLF, 0 XCRLF, 0 TAD (215 TAD (215 JMS TYPE TYPE TAD (212 TAD (212 JMS TYPE TYPE JMP I CRLF JMP I XCRLF .F;.P The SCAN program will convert the first form into the second if page zero links are indicated. The user should reference other modules by "JMS (tab) module name", and all references to the entry point should be of the form "(space or tab) modulename (space or tab)". .p The key character in the "/$LOCATIONS:n" "/_#ROUTINES#USED:##a,b,c" and "/*GLOBAL#VARIABLES:##x,y,z" is the colon. Everything between the flag character and the colon is ignored. Separators may be spaces, tabs or commas. The number of locations is a decimal number including any possible off page links or current page literals. If the number of locations is not specified in a module, it is assumed that it must be placed on it's own page. Very little error checking is done on these items, so it is important to follow the form correctly.
.NOTITLE;.PAGE .NF;.UC .CW; ^&WORKING DOCUMENTATION GENERATOR\& .TITLE WORKING DOCUMENTATION .SUBTITLE DOCUMENTATION GENERATION PROGRAM \\.AP;.AC;.FLAG CAPITAlIZE ";.NUMBER 1 .TP 8;.B 2;.CW; ^&^^GENERAL INFORMATION\&\\ .FILL;.P THIS PROGRAM CAN BE USED TO GENERATE A WORKING DOCUMENT FROM A SOURCE PROGRAM WHICH FOLLOWS THE RULES FOR COMMENTING OUTLINED BELOW. USUALLY THIS WILL BE A "PAL" SOURCE, ALTHOUGH OTHER LANGUAGES MAY BE ADDED IN THE FUTURE. THIS IS A PROGRAM WRITTEN FOR THE "SNOBOL 8.2" COMPILER TO RUN UNDER "OS/8". THE PROGRAM GENERATES COMMANDS FOR THE PROGRAM "RUNOFF" (FORMERLY CALLED "PRINTR") WHICH ASSUMES ALL INPUT IS IN UPPER CASE. HOWEVER, ANY LOWER CASE COMMENTS WILL BE TRANSMITTED IN LOWER CASE. THE ONLY MAJOR DRAWBACK IS THAT THE PARAGRAPH DESCRIPTIONS FOLLOWING THE /+ FLAG CHARACTER ARE MAPPED INTO UPPER/LOWER CASE IN A NON-INTELLIGENT FASHION. TO SEE EXACTLY HOW THIS IS DONE, CONSULT THE "RUNOFF" MANUAL, KEEPING IN MIND THAT THE MODE USED IS: "FILL", "JUSTIFY", "AUTOPARAGRAPH", "AUTOCAPITALIZE", AND "FLAGCAPITALIZE#_"". THIS ESSENTIALLY MEANS THAT ALL SENTANCES MUST END WITH A PERIOD, PARAGRAPHS MUST BE SEPARATED BY A BLANK "COMMENT" LINE FOLLOWED BY A LINE STARTING WITH TWO SPACES, AND NAMES WHICH SHOULD REMAIN IN CAPS SHOULD BE ENCLOSED IN QUOTES. IF THIS AUTOMATIC CAPITALIZTION FEATURE IS NOT DESIRED, ANSWER THE RUN-TIME QUESTION: ^^AUTO CAPS (Y OR N) ?\\ WITH AN "N". ALL FLAG CHARACTERS MUST BE PRECEEDED BY A slash as the first non-blank character in the line. THE FOLOWING IS A TABLE OF THE PRESENT FLAG CHARACTERS AND A SHORT DESCRIPTION OF THE EFFECT OF EACH: .B 2;.NF;^^^&FLAG NAME EFFECT\& + "PLUS" \\^PARAGRAPH DESCRIPTION - "MINUS" ^SEARCHES FOR NEXT "PLUS" _& "CALLING" "SEQUENCE" ^OUTPUTS COMMENTS AS THEY ARE, WITH NO FILLING, CASE MAPPING, ETC. _# "ROUTINES" "USED" ^DITTO ; "LOGIC" ^DITTO * "GLOBAL" "VARIABLES" ^DITTO = "TABLE" ^DITTO $ "LOCATIONS" ^DITTO @ "VARIABLES" ^PRINTS OUT EVERYTHING UNTIL THE NEXT FLAG CHARACTER. ! "ENTRY" "POINTS" ^TREATS FOLLOWING LINES STARTING WITH "PLUS" AS NAMES OF ENTRY POINTS. _" "TIMING" ^SEPARATE PARAGRAPH IF IN "PLUS" MODE : "CODE" ^MUST BE ONE OF THESE OR ANOTHER FLAG CHARACTER AFTER EVERY "PLUS". IGNORES EVERYTHING UNTIL NEXT "PLUS"
.TP 8;.CW; ^&^^USER INPUT\&\\ .FILL;.P THE PROGRAM FIRST ASKS FOR THE INPUT AND OUTPUT FILES. AFTER GETTING TWO GOOD RESPOSES, THE PROGRAM WILL PRINT: ^^AUTO#CAPS#(Y#OR#N)#?\\ ANSWER THIS QUESTION DEPENDING ON IF IT IS DESIRED FOR "RUNOFF" TO DO THE UPPER/LOWER CASE CONVERSIONS. THE PROGRAM WILL THEN PRINT: "MODULES" "DOCUMENTED:" IT WILL OUTPUT SOME "RUNOFF" COMMANDS TO THE FILE AND USE THE FIRST LINE OF INPUT (IF IT IS A COMMENT) AS THE TITLE OF THE DOCUMENT. THE PROGRAM PASSES DOCUMENTATION THROUGH IN FIVE MAJOR MODES WHICH ARE DESCRIBED BELOW. .TP 8;.B 2;.CW; ^&^^CODE, MINUS, LOOP MODES\&\\ .FILL;.P "CODE" MODE IS OBTAINED AT THE BEGINING OF THE FILE, AND AFTER ANY /- OR /:. IN THIS MODE, NOTHING IS OUTPUT ALTHOUGH EACH LINE IS SCANNED FOR A /+ IN THE FIRST COLUMN. .TP 8;.B 2;.CW; ^&^^PLUS \&\\ .FILL;.P "PLUS" MODE IS ENTERED AFTER SEEING A SLASH PLUS IN COLUMN 1. THE COMMENTS AFTER A SLASH PLUS ARE FIRST SCANNED FOR OTHER FLAG CHARACTERS, AND THEN ARE SIMPLY TRANSMITTED TO THE OUTPUT FILE. HOWEVER, THE "RUNOFF" COMMANDS PLACED BEFORE THE LINES IMPLY THAT ANYTHING ON THE COMMENT LINE IS PART OF A TEXT PARAGRAPH, AND WILL THEREFORE BE FILLED AND JUSTIFIED. .TP 8;.B 2;.CW; ^&^^CALSEQ, ROUTINES, LOGIC, GLOBAL, TABLE, LOCS\&\\ .FILL;.P "TABLE" MODE IS OBTAINED BY ANY OF THE FOLLOWING FLAG CHARACTERS: _" _& _# * = ; $. IN THIS MODE EVERYTHING IS PUT IN UPPER CASE THROUGH "RUNOFF" WITH NO FILLING SO THAT SPACING IS NOT AFFECTED. .TP 8;.B 2;.CW; ^&^^VARIABLES\&\\ .FILL;.P "VARIABLE" MODE IS OBTAINED BY THE /@ FLAG. IN THIS MODE "EVERY" LINE OF INPUT IS SENT TO THE OUTPUT FILE, ALTHOUGH SLASHES ARE REMOVED FROM COMMENTS. IT IS VERY IMPORTANT THAT ANOTHER FLAG CHARACTER IS USED TO GET OUT OF THIS MODE OR THE ENTIRE PROGRAM WILL BE SENT TO THE OUTPUT FILE. .b 1;.tp 5;.CW; ^&^^ENTRYS\&\\ .FILL;.P "ENTRY" MODE IS USED TO PROCESS THE "/!ENTRY" "POINT" FLAG. FOLLOWING LINES STARTING WITH "/+" WILL BE PUT IN CAPS ON THE SAME LINE. THE FIRST LINE NOT STARTING WITH "/+" GOES BACK INTO "PLUS" MODE.
.PAGE .upper case;.nf .subtitle Preliminary Specifications .c; ^&Working Documentation \& .c; ^&Preliminary Specifications\& .b 4;.fill The following is a sample module documented with flag characters. The documentation extraction program assumes that the first line of the "PROGRAM" (not each module), if it is a comment, can be used as a title like the one used for PAL8 listings. At present these specifications apply only for PAL-8 programs, although a subset of the specifications could be used for other possibly higher-level languages. .b 3;.nf /+NAME (Full Name goes here) / / Following the flag that starts the module, / it is assumed that there will be a general / explanitory section of text in paragraph / form here. In fact, in some trivial modules, / this will be all the documentation that will / be included. For the sake of saving extra work / the best practice is to include only those sections / that apply to this module. / / /;LOGIC / This section usually includes a "PASCAL" or ALGOL- / like description of the logic of the module. / /!ENTRY POINTS: (only if multiple entry points) /+ENTRY1 /+ENTRY2 / / /_"TIMING: Optional if timing is not critical / /=TABLE: Used to preceed tables which will / be included in the documentation. / /_#ROUTINES CALLED: NAME1,NAME2 NAME3 NAME4 / use one space or a comma to separate items. / /_&CALLING SEQUENCE: Description of transmission / of prameters, multiple returns, etc. / /*GLOBAL VARIABLES: VAR1,VAR2 VAR3,VAR4 VAR5 / .TP 4 /@LOCAL VARIABLES: LOCAL1, VALUE1 LOCAL2, VALUE2 LOCAL3, VALUE3 / .tp 3 /$LOCATIONS USED: Decimal number / /:CODE: last flag before code - there must be one / of these or a "/-" in each module / at the end of the working documentation. / NAME, ENTRY /Entry point should have same name /Comments in the body of the module /are not extracted. OPCODE OPERAND /Usually separate symbols /with "TABS" for readability. JMS NAME1 /calls to other modules, /if not using page zero links. NAME2 /Calls to other modules if page /zero links are being used. /and NAME2= JMS I [XNAME2 ISZ NAME /References to the entry point /should follow the same pattern. JMP I NAME /Usual method of returning. /-NAME / /The "/-" denotes the end of the module; /anything between the "/-" and the next "/+" is /ignored by the documentation generator. /
.SUBTITLE EXAMPLE OF DOCUMENTATION PRODUCED .PAGE .B 1;.fill;.m 5,65 Below is the documentation produced by the documentation generator program when run on the example module given on the previous page. .b 2 .NF;.UC;.m 1,72 .AP;.AC;.FLAG CAPITAlIZE " .TP 8;.B 2;.CW; ^&^^NAME (Full Name goes here)\& .FILL;.P Following the flag that starts the module, it is assumed that there will be a general explanitory section of text in paragraph form here. In fact, in some trivial modules, this will be all the documentation that will be included. For the sake of saving extra work the best practice is to include only those sections that apply to this module. .B 2;.NF;^^LOGIC This section usually includes a "PASCAL" or ALGOL- like description of the logic of the module. .b;^ENTRY POINTS: (only if multiple entry points) "ENTRY1 "ENTRY2 "TIMING: Optional if timing is not critical TABLE: Used to preceed tables which will be included in the documentation. ROUTINES CALLED: NAME1,NAME2 NAME3 NAME4 use one space or a comma to separate items. CALLING SEQUENCE: Description of transmission of prameters, multiple returns, etc. GLOBAL VARIABLES: VAR1,VAR2 VAR3,VAR4 VAR5 LOCAL VARIABLES: LOCAL1, VALUE1 LOCAL2, VALUE2 LOCAL3, VALUE3 LOCATIONS USED: Decimal number