COMMENT ⊗   VALID 00012 PAGES VERSION 17-2(1)
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
 00017 00007	Creation of shared execs
 00020 00008	Files required (copy or produce) for EXPOrt system.
 00026 00009	Exporting Procedure
 00029 00010	Documentation Aids
 00030 00011	References to other documents
 00031 00012	History of SAIL versions (important SAVE tapes)
 00035 ENDMK
⊗;
COMMENT ⊗HISTORY
AUTHOR,REASON
021  202100000001  ⊗;


COMMENT ⊗
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. One Segment compiler requires that COM2SW be turned off in SAIL, and
      that GOGOL and STRSER be included in the compilation
 4. Two segment compiler will be loaded with SAILOW, to get routines it needs.
 5. Debugging compiler must be loaded with a DDT, should have FTDEBUG on in
    or above SAIL.
 5a.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. LIBSAI.REL is created by running SCISS, RENSW overriden to 0.
 8a.HLBSAI.REL is created by running SCISS, RENSW defaulted to 1, renaming
    LIBSAI to HLBSAI.
 9. The shared runtimes are created via the following mechanism:
   a. CALLIS,HEAD,LOW,FILSPC,GOGOL 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,GOGOL,STRSER,IOSER 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
    HEL2
 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, 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. 1OPS1.OPS or the like.
 11.Files of some relevance
    MANUAL.PUB, SAIL.ON, FAIL.ON, 
    ARRSER,EXTEND,SRTSER,SYMSER,SCNCMD,SCNSER -- packages
 12.Files to aid in export procedure
    EXAM.FAI, COPY.MAC
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 CMDSCN.REL) if no DMPs.
   b. RU PTRAN
   c. *PROD←HEL2
   d. *

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

 3. Two-segment debugging compiler
   a. COMPILE @THAT
   b. R LOADER
   c. */Y/VSAIL<alt> (/1V for DD)
   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. 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
  0a.Set RENSW to 0 in GOGOL, if making single-segment library
     (LIBSAI).  Otherwise, make sure the default-override is missing.
  1. RU SCISS[S,AIL]
  2. List of yes/no questions -- answer Y<cr> for Yes, otherwise
     for No -- some may not be asked, depending:
     STANDARD? Yes if want whole LIBSAI created automatically
     DO HEAD? Yes if want USERCON's User Table Externals file
       assembled into library (default Y in standard version).
       --- HEAD must not have line numbers (FAIL barfs if so).
     DO LEAP? Yes if want LEPRUN in library (default Y)
     PASS 2 NOW?  Yes if want to bypass assembly phase and go on
       to library composition phase.
     LINK TO FAIL? Yes if want to call FAIL after creating QQFAIL
       command file (will assemble library entries) (default Y).
     SELECT? Yes if want to let list of possible library entries
       (of form SAIccc) to be presented for inclusion or exclusion.
       List is located in early pages of GOGOL -- e.g., 
       COMMENT ⊗ORDER LOR,LUP,SGC,COR,....⊗
       LOR, LUP, SGC, ... are possible values for ccc.
       (Default is SELECT all)
     SPECIFY? Yes if want to type names of the for SAIccc -- only
       these will be included.
  3. If SELECT was chosen, each name will be typed -- answer with
     Y (yes, include), N, (no, exclude), or D (done, use last answer
     given for all the rest).
  4. If SPECIFY was chosen, type each desired SAIccc entry, terminate
     with DONE.
  5. SCISS will talk for a while, go on to FAIL (if specified), and
     come back (by magic) for pass 2.
  6. STANDARD?  it will say -- answer as above.
  7. MAKE A LIBRARY? Yes (default) if want all the little .REL files
      merged to LIBSAI.REL
  8. DELETE INTERMEDIATE FILES? Yes to delete all but original files
      and final LIBSAI.REL file -- otherwise all sorts of junk left
      around.
  9. SELECT?, SPECIFY? as above, although names need not necessarily
      match.
  10.SCISS now gets selections, deletes, copies, talks about things
      as directed, finish up with or without a LIBSAI.REL.
  11.If RENSW was on (default), rename LIBSAI to HLBSAI before trans-
      ferring to SYS -- the re-entrant library files.
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.FAI.

 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[SAIL] hopefully DEC latest modified (soon)
	LIBSAI.REL[T,AIL] and EXPO-ized library (with HEAD), created by SCISS
      If MTA used for transmission:

 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.FAI[IFN] (segment-tailoring file)
	LOW.FAI[IFN] (low part tailoring file)
	TAILOR[IFN] (FILSPC parameterizes it -- used to create final segments)
	GOGOL[IFN←SAIL]*
	STRSER[IFN←SAIL]
	IOSER [IFN]
	NWORLD[IFN]
	LEPRUN[IFN] (possibly screwed up in DECUS version).
	WRDGET
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[S,AIL]*
	MAKTAB.SAI[S,AIL] (makes 1OPS1.OPS)
 4. Extra files to complete SAIL Features
	1OPS1.OPS (created by MAKTAB -- transfer to SYS for START_CODE)
	BKTBL.BKT[1,3] parameter file for STDBRK
 5. Optional helpful files
	SAVE[CSP,SYS]* magtape file program (soon to be DAEMON)
	LOADER.052[CSP,SYS]* suitably diddled -- any v52 will do
	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.
	MANUAL.PUB, TJ.MAN
	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.
12. Modify SCISS as given, run it to get LIBSAI.
13. Run Sciss again if HLBSAI 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.
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.