COMMENT ⊗   VALID 00012 PAGES VERSION 17-2(6)
RECORD PAGE   DESCRIPTION
 00001 00001
 00003 00002	HISTORY
 00004 00003	Summary of possible Compiler and Exec configurations
 00009 00004	File List
 00011 00005	Compiler creation procedures
 00013 00006	Creation of RUNTIM, LIBSAI
 00019 00007	Creation of shared execs
 00022 00008	Files required (copy or produce) for EXPOrt system.
 00028 00009	Exporting Procedure
 00031 00010	Documentation Aids
 00036 00011	References to other documents
 00037 00012	History of SAIL versions (important SAVE tapes)
 00041 ENDMK
⊗;
COMMENT ⊗HISTORY
AUTHOR,REASON
021  202100000006  ⊗;


COMMENT ⊗
VERSION 17-2(6) 7-11-73 
VERSION 17-2(5) 7-11-73 
VERSION 17-2(4) 1-18-73 BY jrl continue mods for version 17
VERSION 17-2(3) 1-18-73 
VERSION 17-2(2) 1-18-73 
VERSION 17-2(1) 12-13-72 BY JRL PARTIAL UPDATE FOR SAIL VERSION 17

⊗;
Summary of possible Compiler and Exec configurations



I. PROCEDURES FOR CREATION AND MAINTENANCE OF STANFORD SAIL SYSTEM

A. FILE AND SWITCH CONFIGURATIONS FOR VARIOUS SYSTEMS.
 1. See HEAD for Conditional assembly switch definitions, macros which
    use them.
 2. See SAIL for RPG files to make compilers  ---
 3. See FILSPC for library names, segment names, ppn's, default extension etc.
 4. One Segment compiler will be loaded from library.
 5. Two segment compiler will be loaded with SAILOW, to get routines it needs.
 6. Debugging compiler must be loaded with a DDT, should have FTDEBUG on in
    or above SAIL.
 7. Compiler to generate re-entrant code (/H) requires RENSW≠0 in SAIL (default)
 6. See GOGOL for RPG files to make runtime routines.
 7. RUNTIM.REL can be created by assembling HEAD, GOGOL, STRSER, IOSER,...
    together with no special operations. This is all the runtime routines.
 8. LIBSAn.REL is created by running SCISS. Reply Y<cr> to all questions.
 8a.HLBSAn.REL is created by running SCISS, Reply N<cr> to "STANDARD?" and
    request REENTRANT library in both PASS 1 and 2.
 9. The shared runtimes are created via the following mechanism:
   a. CALLIS,HEAD,LOW,FILSPC,GOGOL,STRSER,IOSER,ARYSER,NWORLD are used to get 
      LOWER.REL,
      some fixed-location variables, the UUO trap location, the segment-fetcher,
      and the dispatch to the allocation routines. A unique second segment name
      (of the form SAISGn), its device and PPN locations, are also contained
      therein.
   b. FILSPC and TAILOR are assembled to get TAILOR.REL, a file which when
      loaded provides some global variables with the names (SAISGn, etc.)  which
      should be used for the upper segment file and device -- also parameters
      like write-protection and symbol inclusion for upper segment.  This is 
      done in separate assembly so that these can be changed without re-
      assembling the upper segment (next).
   c. CALLIS,HEAD,UP,ORDER,GOGOL,STRSER,IOSER,ARYSER,NWORLD,LEPRUN,WRDGET
      are assembled to get UPPER.REL, which
      refers to the things in TAILOR as Externals to get name.
   d. Loading UPPER and TAILOR and running it creates SAISGn.REL (name determined
      by FILSPC/TAILOR), the sharable upper segment, by simply writing out
      that part of itself (which has been phased to 400000) which is intended
      to be the upper segment stuff.  In addition, it jams all or part of its
      symbol definitions into the SAILOW-type .REL file with the name that
      FILSPC said.  SAILOW contains the symbol linkages, name, device, and PPN
      (where SAISGn must reside) for SAISGn. Loading SAILOW causes SAISGn to be
      fetched and linked as a segment when the job is started.
 10. Global model segment stuff works similarly -- the file GLB is introduced
      to set the appropriate switch, modifying the definition of the LOWER and
      UPPER assemblies.  GLBSGn and GLBLOW are the corresponding keyed file names.
File List

B.  Original Files (not created during any bootstrapping operation)
 1. Compiler and Execs files
    CALLIS, HEAD, FILSPC
 2. Ptran input
    HEL
 3. Rtran input
    FOO2
 4. Compiler files
    DB, SAIL, PARSE, SYM, HEL2, FOO2, GEN, ARRAYS, STATS,
     EXPRS, TOTAL, COMSER, LEAP, PROCSS
 5. Exec files
    UP, TAILOR, LOW, GLB,GOGOL, STRSER, IOSER, ARYSER,  LEPRUN, MESPRO,
     NWORLD,WRDGET
 6. RPG command files
    IT, THAT, RUN, SGMNT, GSGMNT
 7. Bootstrap programs
    PTRAN.SAI, RTRAN.SAI, MAKTAB.SAI, SCNCMD.SAI
 8. Support software
    EXTRACT.SAI, DATALIST.SAI, GRUMP.FAI, PROFIL.SAI
 9. Export stuff
    TELLEM, DDT, CREF.MAC
 10.Other files.
    BKTBL.BKT or the like. 2OPS2.OPS or the like.
 11.Files of some relevance
    MANUAL.DOC, SAIL.ON, FAIL.ON, 
    ARRSER,EXTEND,SRTSER,SYMSER,SCNCMD,SCNSER,LPDUMP,LPREAD,LP4MAT -- packages

 12.Files to aid in export procedure
    EXAM.FAI

Compiler creation procedures

C. CREATING SAIL COMPILERS
 (parts 1 and 2 are automatically done by parts 3 and 4 if
  necessary, but are included here for clarity.

 1. Create production tables, reserved-word list for RTRAN
   a. COMPILE PTRAN.SAI and RTRAN.SAI (require SCNCMD.SAI,WNTSLS) if no DMPs.
   b. RU PTRAN
   c. *PROD←HEL
   d. *

 2. Create reserved word tables
   a. RU RTRAN
   b. *RESTAB←PROD,FOO2
   c. *

 3. Two-segment debugging compiler
   a. COMPILE @THAT
   b. R LOADER
   c. */Y/VSAIL<alt>
   d. SAVE SAILD, or SAILII, or something reasonable.

 4. Two-segment non-debugging compiler.
   a. COMPILE @IT
   b. R LOADER
   c. */Y/SSAIL/V<alt>
   d. START
   e. SAVE SAIL, can also place on system.


Creation of RUNTIM, LIBSAI

D. CREATION OF SINGLE-SEGMENT, NON-LIBRARY RUNTIME ROUTINES

  1. COMPILE @RUN
  2. Load RUNTIM.REL with SAIL-compiled programs -- provides
     all runtime routines at maximum cost.
 
E. CREATION OF LIBRARY OF SAIL RUNTIME ROUTINES
1. Current library version number in ORDER (following "NAM") and FILSpc
2. RU SCISS[S,AIL]
3. SCISS will ask the question "STANDARD?" before PASS 1 and before
   PASS2 (unless PASS 1 was totally suppressed). To get the standard LIBSAn
   simply reply Y<cr> to both questions. Otherwise type N<cr> and then you
   will get a list of options.

   PASS 1

	1  PASS 2 NOW
	2  DON'T CHAIN TO FAIL
	3  DON'T CREATE INTERMEDIATE FILES
	4  MAKE REENTRANT LIBRARY
	5  SELECT ENTRIES FROM PROMPT-LIST
	6  SPECIFY ENTRIES EXPLICITLY
	7  DON'T DELETE INTERMEDIATE FILES (PASS 2)
	8  DON'T MAKE A LIBRARY(PASS 2)

   Type the indices of those options you wish to invoke:

   1. Pass 2 now means don't create the SAIxxx.FAI files or call FAIL.
      This makes sense only if SCISS has been run before and the SAIxxx.REL
      files still exist. This option will cause the copying of the .REL files
      (which ones, may be specified by invoking options 5 or 6) to form a
      library (unless inhibited by option 8) and then deleting the .FAI and
      .REL files (unless inhibited by option 7). The library will be named
      HLBSAn if option 4 is requested (The .REL files should have been created
      by running SCISS with a REENTRANT library requested during the first pass).

   2. Don't chain to FAIL means just create the .FAI files. Don't assemble them.
	
   3. Don't create intermediate files. Don't create the .FAI files but
      unless inhibited assemble the .FAI files generated previously.

   4. Make REENTRANT library means to make a HLBSAn instead of a LIBSAn.
	(command must be given to both PASS 1 and PASS 2)

   5. Select entries from prompt-list means that SCISS will type the
      library entries and let you indicate whether you desire that entry in
       the library. This option and the next are very useful in avoiding
      reassembling everything when an assembly error has occurred in one or
      two library entries. SCISS will type the names of the library entries
      like SAICOR, pausing for your response:
		Y<cr> retain this entry
		N<cr> omit this entry
		DONE  dispose of the rest of the entries as you did the
		      last (all Y or N)

   6. Specify entries explicitly - type the names of the entries you want
      (SAILOR etc) separated by <cr>. After all the names you want
      type DONE<cr>

   7. Don't delete intermediate files- don't delete the .FAI or .REL
      files (only meaningful if doing PASS 2 now)

   8. Don't make library.(only meaningful doing PASS 2 now).

  
PASS 2

   An important thing to remember is that SCISS doesn't remember what you
requested at the beginning of PASS 1 so if you want something unusual
(e.g. a reentrant library or a library without certain entries) you are
going to have to tell SCISS again.

	1 DON'T DELETE INTERMEDIATE FILES
	2 DON'T MAKE A LIBRARY
	3 MAKE A REENTRANT LIBRARY
	4 SELECT ENTRIES FROM PROMPT-LIST
	5 SPECIFY ENTRIES EXPLICITLY

These have the same meaning as they did in PASS 1.

				GOOD LUCK WITH SCISS

Creation of shared execs

F.  CREATION OF SHARED, STANDARD (non-global model) EXECS

 1. When changing the transfer vector, making major changes, or creating 
        special	systems, change FILXXX (SAISGn), not SLOFIL (SAILOW) in FILSPC,
 	by incrementing n for production systems.  Also change the global
	equivalents in GLB.

 2. Other FILSPC parameters of interest may be changed:
	SGDEVC -- the device (default device for global model) in SIXBIT
	 (merely a definition for it)
	SGPPNN -- the PPN (default for global) for the segment in SIXBIT
	LOCSYM -- on if local symbols are to be transferred from UPPER to
	 SAILWn.
	NOPROT -- on if the upper segment is to be left unprotected
	 (Stanford  non-global only) -- these latter two switches are likely 
	 set together.

3.  JOBVER in GOGOL should be <'SGn',,SAIL version> for grins.  The production 
	lower segment name should be SYS:SAILOW, or the LOADER should be
	told about the change. (soon RPG will do the /Y, not LOADER--then
        LOADER can be real ignorant).

 4. LOA @SGMNT (@GSGMNT), see GOGOL.  This assembles TAILOR, UPPER, and
	LOWER.  It loads TAILOR and UPPER.  Changes to FILSPC (GLB) will
	cause only TAILOR and LOWER to be reassembled.

 5. Start the job.  Created as if from nowhere will be SAISGn.REL, and SAILOW.REL
	as specified in FILSPC.  They go together, in that if SAILOW properly
	specified the device and PPN, etc. when a job containing it is started,
	the right segment will come up.

 6. I suggest a SAILWT and SAISGT on [S,AIL] with all debugging aids deployed.

 7. All this goes more or less symmetrically for GLBSGn, GLBLOW (try to keep
	versions synched).
Files required (copy or produce) for EXPOrt system.

II. CREATING AN EXPORT SYSTEM

A. Required files for EXPO SAIL (transfer to T,AIL, modified as specified)
 1. To get working SAIL abroad:
	TELLEM[S,AIL]
	LOADER.REL[T,AIL] -- from CSP,SYS DEC v54 modified, although any 
	  v54 with SAILSW and FAILSW on will work if prodded (try to delete need)
	SAIL.REL[T,AIL] (assembled from IFN'd files described below.
	DDT.REL[1,3] hopefully DEC latest modified (soon)
	LIBSAn.REL[T,AIL] and EXPO-ized library (with HEAD), created by SCISS

 2. To modify compiler or Execs.
    a. Used by SAIL and RUNTIM
	HEAD[IFN←S,AIL]*
	FILSPC[IFN]

    b. SAIL only
	SAIL[IFN etc.]*
	PARSE[IFN]
	HEL2[S,AIL]*
	FOO2[S,AIL]* (CLRBUF excised in version sent to DECUS)
	PROD[T,AIL] created by PTRAN (possibly screwed up in DECUS version).
	PROD.QQQ[T,AIL] created by PTRAN
	RESTAB[T,AIL] created by RTRAN
	SYM[IFN]
	GEN[IFN]
	ARRAY[IFN]
	EXPRS[IFN]
	STATS[IFN]
	LEAP[IFN]
	TOTAL[IFN]
	PROCSS[IFN]
	COMSER[IFN]
    c. Execs only
	UP[IFN] (segment-tailoring file)
	LOW[IFN] (low part tailoring file)
	TAILOR[IFN] (FILSPC parameterizes it -- used to create final segments)
	GOGOL[IFN←SAIL]*
	STRSER[IFN←SAIL]
	IOSER [IFN]
	ARYSER [IFN]
	NWORLD[IFN]
	LEPRUN[IFN] (possibly screwed up in DECUS version).
	WRDGET
	ORDER (library description for SCISS)
ON, probably
    d. Used by PTRAN, RTRAN
	HEL[S,AIL]*
	FOO2[S,AIL]*
    e. Required Software support (in addition to LOADER and DDT above)
	FAIL.REL[T,AIL] from CSP,SYS
	PTRAN.SAI[S,AIL]
	RTRAN.SAI[S,AIL]
	SCNCMD.SAI[1,DCS]*
	WNTSLS.SAI[S,AIL]
	MAKTAB.SAI[S,AIL] (makes 2OPS2.OPS)
 4. Extra files to complete SAIL Features
	2OPS2.OPS (created by MAKTAB -- transfer to SYS for START_CODE)
	BKTBL.BKT[1,3] parameter file for STDBRK
 5. Optional helpful files
	FAIL[CSP,SYS]*
	DDT[S,AIL]
	CREF.MAC[S,AIL]
	SCISS.SAI[S,AIL]* makes LIBSAI.REL when run, uses CCL
	PROFIL.SAI, User program to list KOUNTER files.
	SCNSER.SAI, SCNCMD.SAI -- REQUIREd by PROFIL.
	EXTRACT.SAI[S,AIL] removes interesting stuff from SAIL CREF
	DATALIST.SAI[S,AIL] makes sense out of it.
	SAIL.DOC, FAIL.ON[CSP,SYS] -- final manuals.
	EXAM.FAI[S,AIL] -- EX on [T,AIL] to get list of files with
		line numbers -- don't send out
	IFN.SAI[S,AIL] -- don't send out -- pre-conditionally assembles

 6. Files not necessary to most people, provided after EOT as separate list,
     may be ignored by most people.
	ARRSER,EXTEND,SRTSER,SYMSER,SCNCMD,SCNSER -- FIGURE 'EM OUT

 * modifications:
	HEL -- turn off global switch
	FOO2 -- delete Stanford-only routines
	SCNCMD--turn off STANSW
	FAIL -- turn off STANSW
	HEAD, GOGOL, SAIL -- change conditional switches if you
		don't like the defaults (two-segment, ftdebug, etc.)
	LOADER--set appropriate switches (.052 OK as defaulted if SAILSW
		and FAILSW are on).
	SCISS -- STANSW off.
Exporting Procedure


B. Exporting Procedure (on T,AIL)

 1. Create IFN file, containing all necessary IFN transfer commands --
	put on [T,AIL] as IFN or something.
 2. Copy QQIFN.RPG←IFN. (RPG file gets deleted occasionally)
 3. Make an IFN.REL from IFN.SAI[S,AIL]; start it at RPG location.
 4. If errors occur, edit IFN to delete already assembled things, go
     back to step 2.
 5. Rename all .UPD files to null ext. files, (except LOW.FAI, UP.FAI)
 6. Copy over all additional files needed for SAIL system test; make
     mods as given above.
 7. Run PTRAN and RTRAN to create PROD, etc.
 8. Run FAIL (glom IT from somewhere, modify, create DB) to make an
      SAIL -- load with modified DDT. (block structure).
 9. Patch CALLI TMPCOR (find it by running to ILLUUO) to JFCL, save as SAIL.
10. See if it will compile something, iterate till it will.
11. Modify SCISS as given, run it to get LIBSAn.
13. Run Sciss again if HLBSAn desired.
14. Make SAILOW, SAISGn, etc. as described on page 1.
15. Copy and modify as shown the remaining files as described above.
16. EX EXAM[S,AIL] to check for `T' and line-numbered files, remove
    the directories and line numbers, delete spurious files.
17. FAILSAFE all first section files to tape
18. After EOT, FAILSAFE the optional files, most of which must be loaded
    from a previous tape.
19. Send hard-copy of TELLEM,a manual if necessary, and the tape.

Documentation Aids

III. DATALIST AND EXTRACT DOCUMENTATION PROGRAMS

1. ADD LINE #s TO ALL FILES, FIX UP "BEND RESTAB" IN RESTAB

2. COM /CREF /COM @THAT (with (xlr) in FAIL string)

3. R CREF
4. *DSK:SAIL.CRF←SAIL.LST
5. *DSK:CREFIL←SAIL.LST/S
6. *↑C

7. EX EXTRACT[S,AIL]
 
8. EX DATALIST
9. P

10.RENAME PRTCRF=CREFIL or DEL CREFIL

11. Examine DIRECT -- if it's OK, delete everything else
    and list it -- otherwise back up as necessary.
C. DATALIST, EXTRACT -- hairy SAIL programs


These programs, combined with a CREF listing of the compiler, provide
a  large  file  full of useful summations and cross-references to the
code of the compiler.  Proceed in the following fashion:

1.  Make a listing file via FAIL  of  the  selected  version  of  the
compiler, starting out with
	,SAIL/C←HEAD(XLR),SAIL,....  The (XLR) is important to select
the proper listing options.

2.  Assemble our version of CREF.MAC.  Load and run it, following the
script as:
	*DSK:SAIL.CRF←SAIL.LST
	*DSK:CREFIL←SAIL.LST/S
	*↑C

This  forms one complete CREF listing, and one (CREFIL) with just the
cross-reference tables in it.

3. EX EXTRACT

This SAIL program removes  from  the  body  of  SAIL.CRF  just  those
portions which are useful for the remaining procedures.

4. EX DATALIST Then type P<cr> to continue.

This  program  uses  EXTRACT  (the  result  of the previous step) and
CREFIL to make a file containing:

a. A summary of all DATA names in  the  compiler,  along  with  their
locations (EDIT10 (STOPGAP) and CREF numbers, block and file names)

b.   A  summary  of  all  the  DSCR  macro  names  (DSCR  stands  for
DESCRIPTION, and is ignored by FAIL), and their locatons --  usually,
the DSCR's describe routines.

c.  A  nice  listing of all the data declarations, their accompanying
comments, etc., wherever they appear in the compiler.

d.  An expansion of all the DSCRS in the  file,  giving  a  standard,
formatted description of all the major routines.

e.  An  alphabetical  summarized  cross-reference  of  all  the  data
declarations.

f.  An alphabetical summarized  cross-reference  of  all  the  DSCR'd
routines.

5. After verifying that DIRECT (the result of DATALIST) is OK, delete
all intermediate files.  You'll  also  have  to  list  the  CREF,  of
course,  to  get  anything  out  of the CREF line numbers provided in
DIRECT.

This file should be very helpful in learning some  things  about  the
compiler.


References to other documents

For Conditional assembly switches and their parameter files,
	see HEAD

For Command files for various and sundry above procedures,
	see SAIL (early pages) and GOGOL (early pages).

For History of implementations (and bugs they fixed) see FILSPC,
	page 2.

For Export Users' installation instructions, see TELLEM.

For New Features as told to Users, see NEWMAN

For brief descriptions of changes which are or should soon be in
 SAIL manual, see DOCS.UPD (usually more current and concise than NEWMAN).

History of SAIL versions (important SAVE tapes)

A. Tape labeled A
   9-7-71
   556 bpi =128 word records, 7-track SAVE format
   IFN'ed EXPORT version
   2 logical tapes, as per this and the TELLEM document

	This version will form the base files for DECUS distribution of
   SAIL.  I will really try not to
   allow subsequent featueres and fixes to weaken my resolve to make this
   the base set unless the bugs are blatent. This set of files was also
   send to CASE (Alan Rosenfeld) and Western Electric in Princeton.

B. Tape labeled B
   9-7-71
   556 bpi =128 word records, 7-track SAVE format
   logical tape #1 -- COMPLETE S,AIL
   logical tape #2 -- FAIL, RAID, DDT, LOADER, TJ, MAKER, MANUAL, packages, etc.

	This version (see A) will form my base set for future mods for R.
   Sproull, Suppyes, Erman, etc.  If changes are made, I'll send SOUP files
   along with the initial distribution.

D. Tape labelled D (BLISS files on C)
   11-3-71
   556 bpi =128 word records, 7-track SAVE format
   IFN'ed EXPORT version
   2 logical tapes, as per this and the TELLEM document

	This is identical to (A) above.  It was written because tape A has
   data errors, and because PROFIL, SCNSER, and SCNCMD were on logical tape
   2 instead of 1. Otherwise, not a bit is different (although it should be,
   since %SIZES is SIZES in SAIL -- bug to be fixed next SOUP.
F.	2-15-72 [S,AIL] DAEMON FORMAT
		[S,AIL] to date.  These files represent a probably 
		non-working set of files, some stage of SAIL development.
		Some, but not many of the changes since last release are
		contained in them.  This area was saved to supplement
		the next group.  Any file not found there should be con-
		sidered current in this area.
	2-15-72 [AIL,DCS] DAEMON FORMAT
		The "pre-cut" version of SAIL.  To my knowledge, it works
		correctly, although many changes were made.  I've tested it
		on many programs.  This version represents many changes
		for fixes and features not considered major.  It does not
		include the work of RHT, HJS, JRL.  It was created to 
		provide a base for sending updates to other people, before
		the world collapses.  Hopefully, no corrections will have
		to be added to it (it should be good enough).  This is
		known to assemble at least adequate copies of the compiler,
		and all types of runtimes.  If the file you want doesn't
		exist here, look on the [S,AIL] dump above.