.ap .c;Additional Support for NBS Pascal .send toc ;.indent levels 0,0 .hl1 Utility support for NBS Pascal 1.6\i(\e\c) .send toc ;.indent levels 8,8 .hl2 PX.SAV command line parser .x PX.SAV PX is an alternative program to perform the task of NBS which is described below. To execute PX, type 'R PX'. A '$' prompt will appear in the left margin indicating that PX is ready to accept a filename with options. If is typed PX will identify itself and display the format of command line required and also describe the options available: .b1;.nap;.lm5;.ts20 $program/options .b1 PRE preprocessor option: .br /J - convert FILNAM.P file to FILNAM.PAS - OFF .b1 PASS1 options: .br /C - toggle compiled line count display - OFF .br /G - allow line tracing for compiled program - OFF .br /L - listing output to file (FILNAM.LST) - default TT: .br /Q - no listing (output to NL:) .br /Y - supress array bounds checking - OFF .br /Z - halt terminal output on error or warning - OFF .b1 PASS2 options: .br /F - profile subroutines (use with PROFIL.SAV) - OFF .br /N - do not produce a command line request - OFF .br /P - procedure name index to file (FILNAM.OLS) - OFF .b1 LINK options: .br /B:nnnn - link to specified bottom .br /M - do not LINK file - OFF .br /A - link additional file (/A:extra) .b1 Run-time: /X - do not execute the file - OFF .b1;.lm0;.ap PX creates a command file FILNAM.COM which will auto-execute once the command line has been completed. PX will detect any illegal options which have been typed and strip off the file extension. If there have been compilation errors, etc. in PASS1, then once having edited the offending code, it is a simple matter to manually invoke the command file FILNAM.COM again using the KMON command '@FILNAM'. The PRE preprocessor option is described fully below. .pg;.ap;.hl2 PRE.SAV preprocessor for NBS Pascal 1.6i(ec) .x PRE.SAV As a further convenience to the user, the program PRE.SAV is also distributed. This program, and an associated library file PASCAL.PLB, allow the user to include the abovementioned string handling routines in an abbreviated form in their source code and produce a final listing in a form suitable for compilation. .b1 For example, if the source file TEST.P contained the following lines: .b1;.lm5 Program test; .br const .br ##stringlength#=#60; .b1 _#paslib string length chain; .b1 begin {MAIN} .br _.. .br _.. .br end. .b2;.lm0 The resultant file (TEST.PAS) would contain the expanded lines: .b1;.lm5 Program test; .br const .br ##stringlength#=#60; .b1 type .br ##string#=#array#[1..stringlength+1]#of#char; .br ##relation#=#(lt, le, eq, ge, gt, ne); .b1 function length(s:string):integer;#external; .b1 procedure chain(prog : string); external; .b1 begin {MAIN} .br _.. .br _.. .br end. .b2;.lm0 The program PRE is executed thus: .b1;.lm15 _.R PRE .br $-INPUTFILENAMEOUTPUTFILENAME .b1;.lm0 where the default input file extension is ".P" and the output file extension is ".PAS". .hl3 Additional PRE functions As well as the _#paslib keyword demonstrated above, PRE is also able to include other files and procedures and functions from the users own library of routines. .hl3 _#include keyword The _#include keyword enables the incorporation of whole RT-11 files into the Pascal program. In the most likely event, these files would be separately compiled procedures and functions which been written and debugged at some earlier stage. The syntax of _#include is as follows: _#include file1 file2 ...... filex; .b1 where file1, file2 etc. are RT-11 file names. .hl3 _#library keyword The _#library keyword enables common routines from the users own library to be added to the Pascal source code: _#library lib_name mod1 mod2 ..... modx; .b1 where: lib_name is the name of the users library file .b1 and: mod1, mod2 etc. are the modules contained within this library which are to be added to the Pascal source code. .pg .c;PASREF - NBS Pascal Cross-reference Utility .hl2 PASREF.SAV PASREF is cross-reference utility which was originally distributed in an earlier release of NBS Pascal. This is a modified version of the original program. The program has been altered so that: .list .le an AVL tree is used to hold the identifiers encountered in the source file .le multiple passes can be made to cross reference large files .le various combinations of standard identifiers, standard subprograms and user defined identifiers can be cross referenced .els PASREF will produce a listing of a Pascal source program and cross-reference the identifiers contained within. When typing:######R PASREF######a '$' prompt is given. In response type: #-[option] INPUTFILE OUTPUTFILE .b1 where [option] is X for a cross-reference only .br;.ts 20 P xref Pascal symbols .br S xref standard functions and procedures .br N do not xref user identifiers .b1 INPUTFILE is the Pascal source program (default extension is .PAS) .b1 and OUTPUTFILE is the file to which output is directed (default .CRF) .b1 PASREF can be invoked from NBS (refer to the following section in this document). .pg;.lm0 .hl2 NBS.SAV command line parser This program allows the user to compile programs using the NBS Pascal compilers without the hassle of having to run each pass of the compiler manually. Given a command line, which specifies what to do with the files on the command line, an RT-11 command file is generated and can also be automatically executed. This program no longer fully conforms to the syntax and semantics of the most recent version of NBS Pascal. Commands can be generated for four programs: .b1;.lm20 PRE .br PASS1 .br PASS2 .br PASREF .b1;.lm0 and commands can also be generated to link the resultant object file and to run the executable image. Unless otherwise specified, NBS will generate commands to run PASS1 and PASS2, to link the object file and to run the resulting program. Options are available to run PRE or PASREF, or to exclude any of the other commands. To run NBS the user must type ######R NBS Once started NBS will print a prompt in response to which the user must type a command line. If the command line is empty the program will print a command summary and print the prompt again. The format of the command line is $filename{/option/option...} {filename/option{...}}... Filenames may be specified with or without extensions. If a filename is specified without an extension then a default extension will be used and will depend on the options specified. Filenames, other than the first, will be used in accordance with option(s) specified. There are two types of options: 1) position dependent 2) position independent .b1 Those of the first type define how the filename with which they are associated, will be used. Those of the second type define how the compilation of the program is to proceed, and their position in the command line does not matter. The following is a full description of the options available: .b2;.nap;.ts 12,28 .nf GROUP OPTION DESCRIPTION .b1 Dependent .b1 COM Command file to generate .br P Source file for preprocessor .br PAS Source file for compiler .br INT Intermediate code file .br DAT Intermediate data file .br LST Compiler list file .br OBJ Object file to be produced .br OLS Compiler code list file .br CRF Cross reference list file .br SAV Executable file to be produced .b2 Independent .b1 NBS PRINTER Use LP: Instead of TT: as default .br PRE Run the preprocessor .br NOPASS1 Don't run PASS1 .br NOPASS2 Don't run PASS2 .br CROSSREFERENCE Run the cross-referencer .br NOLINK Don't link the object file .br NORUN Don't run the executable image .br NOINVOKE Don't invoke command file automatically .b2 Independent .b1 PASS1 SEPARATE Separate compilation .br TRACE Generate line trace code .br TABLES Print symbol tables .br NOLIST Do not list source file .br NOWARNINGS Do not flag warnings .br NOARRAYCHECK Relax array compatibility specifications .br PAUSE Pause on error .b2 Independent .b1 PASREF PASSES:n number of passes for larger programs .br NOUSERSYMBOLS do not xref the users identifiers .br PASCALSYMBOLS process Pascal symbols .br STANDARDSYMBOLS xref all standard symbols .br NOSOURCELIST produce a xref only .b2 Independent .b1 PASS2 PROFILE Generate profiling code .br NOCOMMANDLINE No command line required .br CODELIST Print object code .br PROCEDUREINDEX Print procedure index .br STACKDUMP Print stackdump on console .br EXTERNAL Generate external module names .b2 Independent .b1 LINK BOTTOM:n Use n (octal) as base address .f;.b2 .ap If a filename is associated with more than one position dependent option, then that filename must not have an extension explictly specified. Once the command file has been generated the user may execute the command file directly, by-passing NBS, thus speeding up the process of program testing. Finally, a set of examples is provided. Each example consists of the NBS command line and the resultant command file. .lm20;.ts20;.b1 .i-10;i $FUDGE .br R PASS1 .br - FUDGE IOO DOO TT; .br R PASS2 .br - IOO DOO FUDGE TT: .br LINK/EXECUTE:FUDGE FUDGE .br RUN FUDGE .b2 .i-10;ii $FUDGE BLUDGE/SAV/BOTTOM:3000 .br R PRE .br - FUDGE FUDGE .br R PASS1 .br - FUDGE IOO DOO FUDGE .br R PASS 2 .br - IOO DOO FUDGE LP: .br LINK/EXECUTE:BLUDGE/BOTTOM:3000 FUDGE .br RUN BLUDGE .lm0 .ap;.ts 5,20 .pg .ts 5,30 .ap .c;OVRLAY - for NBS Pascal .hl2 OVRLAY Introduction It is possible in RT-11 to reduce the size of programs, with a sacrifice in speed, by using the linker to create an overlay structure for programs. The procedure to do this for NBS Pascal programs is a messy one and not recommended for those who do not know the inner workings of RT-11 and NBS well. However the task is made much easier by using this program which will generate a command file which contains commands for the linker. When executed, this will cause the linker to link the specified program but with certain subprograms overlayed on one another. The algorithm employed by this program is very inefficient and will probably break down for large programs. Users should treat the results of this program with caution. .hl3 OVRLAY Command Syntax The program expects the command line to have the following form: .b1;.c;$-[options]#command#execute#object#......##[list] .b1 where options = the options desired for this run command = the name of the command file to be generated execute = the name of the file to be created by the linker object = the name(s) of the object file(s) to be considered list = optional listing file; conditional on the listing option .b2 The currently valid options are: B = accept further overlay structure information E = extract the modules to be named from the object file(s) L = generate a listing file S = extract all modules from the object file(s) .hl3 Overlaying Problems When any program is having an overlay structure created for it, the following things are happening. The program is split up into groups of subprograms called segments. The memory required is divided into parts called overlay regions. Each segment is then associated with one overlay region. Each overlay region may be associated with more than one segment. If more than one segment is allocated to an overlay region then only one of those segments can reside in memory, in that overlay region, at any time. When a subprogram call is made, code inserted by the linker ensures that if the segment in which the particular subprogram resides is not in memory then it is read into its associated region thus overlaying the segment that was previously residing there. It is up to the constructor of the overlay structure to ensure that when a subprogram return is made, the subprogram to which the return is made is in memory at the time. This means that if subprogram A calls B then B must either reside in the same segment or a different overlay region, and B must not cause A to be overlayed when B calls other subprograms. OVRLAY makes the job easier by ensuring that this condition is true. .hl3 OVRLAY Listing File The listing file generated comes in three parts. The first part is the binary search tree. This is the tree constructed by the program of all the subprogram modules encountered in the object files scanned. This tree is used to locate subprogram names efficiently when needed. The second part is the initial lexical tree. This tree reflects the subprogram call structure of the program under consideration. Each subprogram is listed along with the subprograms it calls. An asterisk indicates that this subprogram also appears further up the tree on the current branch and is used to prevent an infinite loop starting. The third part is the final lexical tree. This tree reflects the final overlay structure for the program. One overlay region is set aside for each level of the tree and programs at level n are assigned to overlay region n. .hl3 Further Overlay Information Usually OVRLAY will only force subprograms to reside in the same segment if necessary. This may result in too great a sacrifice in speed. If this is so the user may inspect the program and locate two or more subprograms which should reside in the segment to speed up the program. If subprograms A and B are forced to reside in the same segment then when one is read into memory the other will also be read in. If they are in different segments but in the same region then if one is in memory the other will not be in memory. It is possible to force two or more subprograms to reside in the same segment by using the B option. If this option is specified, all trees are built as usual but OVRLAY will prompt for further information just before generating the command file. .b1 The user will receive three prompts: Bind Option : Primary Subprogram : Secondary Subprogram : If no bind option is specified, OVRLAY will force the two named subprograms, which must reside on the same level in the final lexical tree, to be loaded into the same segment. If the bind option A is specified then the secondary subprogram and all the subprograms referenced by it (including those called by the secondary, and those called by those called by those called by ....), will be forced to reside in the same segment as the corresponding subprogram in the branch occupied by the primary subprogram, up to, and including the level of the primary subprogram. For example, if subprogram U calls V only and X calls Y only, and U and X are at level three, then if Y is specified as the primary subprogram, then U and X will be forced to reside in the same segment and so will V and Y. Bind option E is used to indicate that no further input is available. The subprograms specified with this option are not significant. .hl3 OVRLAY Object Module Stripping The object modules generated by PASS2 of the NBS compiler are concatenated into the one file. However to create an overlayed executable image, the linker requires that those modules residing in any one segment be in at least one distinct file. This means that the object module from PASS2 must be split up into its component modules at the very least. The S option and the E option are mutually exclusive. The S option will cause all the modules encountered to be copied into another file on the device DK: of the same name as the module name. This will mean that while preserving the PASS2 generated object module, all the component modules will be extracted and placed on the device DK: The E option is similar to the S option, the only difference being that the prompt 'Subprogram :' will appear and only the subprogram specified will be extracted. After the subprogram has been extracted OVRLAY will prompt for another to be extracted. A null response (a carriage return only) will terminate the prompt loop. .hl3 OVRLAY Final Notes Usually OVRLAY would be run once with the L and S options, making sure that there is sufficient room on DK:, and the resulting command file executed. If the resultant overlayed program runs too slowly, OVRLAY would be used again with only the B option and the user could force certain subprograms into the same segment. The new command file would be executed resulting in a faster overlay structure. The E option is most useful when the current program has had changes made to one or two subprograms and only those need to be extracted since the rest are unchanged. Link options such as /B:n may be added to the command file by attaching such options to the execute argument of the command line. OVRLAY may be run from a command file. The B and E options will accept input from the command file. The user should note that the B option prompts for input before the E option.