File LIBDOC.WU

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







                        Version 2.2,    December 1976                        _______ ____    ________ ____






          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.  

          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.  

          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:  

        The Computer Science Research Laboratory
        Northwestern University Technological Institute
        Room B626, 2145 Sheridan Road
        Evanston, Illinois 60201
















PAGE 2 PAL8 SUBROUTINE LIBRARY The Library Scan Program 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. 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: TYPE=JMS I .;XTYPE CRLF=JMS I .;XCRLF . . . 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. 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. To create a file of modules: 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. 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. 3. Run the program as follows: .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
PAGE 3 PAL8 SUBROUTINE LIBRARY The Library Scan Program 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. . 4. Now include your main program in the file you specified as the output file, and assemble and run your program as usual. While running the program, the following errors can occur: OUTPUT ERROR! 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. INPUT ERROR! An error occured while attempting to read a line from the input file. This is caused by a hardware error.
PAL8 SUBROUTINE LIBRARY Creating and Updating a Library file 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. 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 not use them. For example, the subroutine to ___ print return line feed is coded as: 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 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)". 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.
WORKING DOCUMENTATION GENERATOR _______ _____________ _________ GENERAL INFORMATION _______ ___________ 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: 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
PAGE 2 WORKING DOCUMENTATION DOCUMENTATION GENERATION PROGRAM USER INPUT ____ _____ 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. CODE, MINUS, LOOP MODES _____ ______ ____ _____ 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. PLUS ____ 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. CALSEQ, ROUTINES, LOGIC, GLOBAL, TABLE, LOCS _______ _________ ______ _______ ______ ____ 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. VARIABLES _________ 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. ENTRYS ______ 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 3 WORKING DOCUMENTATION DOCUMENTATION GENERATION PROGRAM Working Documentation _______ _____________ Preliminary Specifications ___________ ______________ 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. /+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 / /@LOCAL VARIABLES: LOCAL1, VALUE1 LOCAL2, VALUE2 LOCAL3, VALUE3
PAGE 4 WORKING DOCUMENTATION Preliminary Specifications / /$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. /
PAGE 5 WORKING DOCUMENTATION EXAMPLE OF DOCUMENTATION PRODUCED Below is the documentation produced by the documentation generator program when run on the example module given on the previous page. 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 LOCAL VARIABLES: LOCAL1, VALUE1 LOCAL2, VALUE2 LOCAL3, VALUE3 LOCATIONS USED: Decimal number



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