.AUTOPARAGRAPH
.title;Everything You Always Wanted To Know About Sysgen
.subtitle;But Were Afraid To Ask
.RM65
.LM5
.hl1;Introduction

It is assumed that the reader is at least somewhat familiar with the RSX system
and DEC operating systems in general.  This document will give you my perspective
on performing sysgens and may be of use in helping you bypass some problems
that inevitably occur during sysgen.  

.dark;Sysgen
is a word that has struck fear into the heart of many a computer user.
It means system generation, which is a process of configuring the system
software (operating system) to a particular hardware and software environment.
This document will attempt to remove the mysticism from sysgen and hopefully
will endow the reader with enough knowledge and confidence to be able to 
perform a sysgen. The system which will be used for purpose of example
is a PDP-11/70 with 320K words. Your job, should you decide to accept it,
will be to perform an RSX-11M sysgen from scratch, including the application of patches,
the rebuilding of user written drivers and building various system utility programs.

The remainder of this document is divided into the following sections:
.lit

	* Pre-sysgen
	* Autopatch
	* Sysgen
	* Drivers and privileged tasks
	* Creating the target disk


.eli

A question often asked is "Why do I have to do a sysgen?".  The answer is simple:
Assuming you have a running system (i.e., they didn't just wheel in your new
computer) the only reason for doing a sysgen is to make changes to the
executive program. These changes may be necessitated by procuring new hardware,
fixing bugs in RSX (i.e., applying patches), or adding support for new system services.
A sysgen does not have to be performed periodically (RSX doesn't wear out!).
Before we begin there are a few points of terminology that should be discussed.

Privileged tasks are programs which are mapped to the executive (i.e., RSX11M.SYS)
and must be rebuilt after each sysgen because symbolic locations which these
tasks reference may change physical location within the executive each time it
is built. User written drivers must be rebuilt for the same reason. Anything
else need not be rebuilt and can be copied over asis and used from one system to
the next!

The logical assignments SY: and LB: are normally directed to the
system disk (DP0:) for most user's work.  By design SY: was intended to be
the default disk upon which most activity takes place, LB: is the library
device, that is, the device where the programs reside. For the purpose of the
sysgen SY: and LB: frequently have to reassigned to other than the default 
assignments. If you are not familiar with the ASN subcommand of MCR please
take the time to get intimately familiar with it. 

When you log onto the system you find yourself in your logon directory (e.g., [237,34]
on your logon device (assumed to be DP0:).
Users with logon directories with group numbers less than or equal to 7 are privileged,
the rest are nonprivileged.  
For the purpose of the sysgen you must be privileged therefore you should be
logged into a privileged account (e.g., [1,100]).
Your working directory may be changed via the SET /UIC= command (or UIC command
of CCL). Though you change to a nonprivileged directory a privileged user
still retains privilege.

There are sysgens and there are SYSGENS. Not all the steps in this document
need to be followed each time you must do a sysgen. For example, if your
autopatch level doesn't change then you can use the same patched distribution disk for
subsequent sysgens. Use common sense, but when in doubt, start from scratch.
.page
.hl1;Pre-sysgen

Two things to remember before performing a sysgen are to organize what
you are going to do and to have enough free space to work with.  It is
practically impossible to perform a sucessful sysgen on a system without
large disks, that is, any disk bigger than an RL02. For the purpose of 
example we have 3 RP03 drives (40M bytes each). The current running system
is on DP0: and our sysgen will be performed on DP1: or DP2:. Note, only
for the final phase of our procedure (creating the target disk) will we
require the use of both DP1: and DP2:.  Most of the sysgen activity can take place
online, that is, with other users working on the system. 

You should have 3 disk packs free for use in the sysgen, though it is possible
to get by with less.  The disk which is to be the target system disk should
have few (if any) bad blocks.
Copy the RSX11M distribution kit to a pack, label it
"SYSGEN" and date it.  If you have mag tape distribution (and have not made
a BRU copy of it) you must use DSC to create your distribution disk, otherwise
use BRU.
Copy your utility distribution software to another pack and label it "UTIL".
Note, this software may consist of site specific software, such as user written
drivers, and other software that must be rebuilt each sysgen, such as Jim
Downward's KMS accounting system. A plain "vanilla" RSX system will not have
this disk, however, the following procedures rely on a site having implemented
several DECUS utility programs. So if you have a "vanilla" system you will not
be able to do the sysgen as easily as I describe it.
.hl1;Autopatch

DEC Autopatch service provides a cumulative distribution of patches to RSX11M
in machine readable form.  A new autopatch comes out every 4 months (or so)
and includes all patches which appeared in the Software Dispatch.  
The autopatches are cumulative and must be applied to the virgin RSX distribution.
The autopatch consists of source and object patches and command files to automatically
do the operation. In addition to patches for RSX11M executive, drivers,
privileged and utility tasks there are patches to the layered products
(such as FORTRAN).  In this discussion we will not deal with
patching the layered products (it's much easier than doing the RSX patches).
It is not uncommon for autopatch to introduce some bugs so it is best to wait
a few months after the release of autopatch to see if any bugs surface (look
in the software dispatch or talk to some other users).

For our example we will assume that we have a mag tape autopatch distribution.
Though it is easier to run the autopatch from tape we will first transfer
the tape to disk because it is easier to get other patches (ie. for the
layered products) from the disk.
If you don't have virtual disks implemented at your site (tsk tsk) then you
may use a physical disk of at least 10,000 blocks.
On the SYSGEN disk create a virtual disk of 10000. blocks.
Using the FFL program, copy the tape (which is in DOS format) to the virtual
disk. The necessary commands are shown below:
.lit

UIC [200,200]		!Change UIC
MOU DP2:SYSGEN		!Mount sysgen disk
AVD VD:=DP2:AUTPATCH/CR:10000.	!Assign a virtual disk
ALL VD:			!Allocate the virtual disk
INI VD:AUTPATCH		!Initialize the disk
MOU VD:AUTPATCH		!Mount the disk
FFL VD:/UI=MM:[*,*]*.*	!Copy the tape to disk
TYP VD:AUTOPATCH.DOC	!Type out document
PIP DP2:=VD:AUTOPATCH.CMD !Copy command file to sysgen disk
ASN VD:=DM:		!Assign DM: to fool AUTOPATCH.CMD

.eli

At this point you may follow the directions in the AUTOPATCH document. You
should respond DM: when the command file asks what disk the autopatch distribution is on.
If you have DM: type disks you may use another device (which you don't have)
like DB:.
This subterfuge is necessary because AUTOPATCH.CMD has hard coded names of
"legal" autopatch distribution media and VD: or SY: isn't considered valid.
The autopatch should proceed without problem.
Cleanup is as follows:
.lit

DMO VD:		!Dismount the virtual disk
DVD VD:		!Deassign it
DEA VD:		!Deallocate it
ASN =DM:		!Remove assignment

.ELI

At this point you should
back up the sysgen disk with BRU (e.g., BRU /MOU/DEN:1600 DP2: MM:  ). This
backup copy will constitute your first fallback position should something
go wrong in a later phase of sysgen.
.page
.hl1;Sysgen

The sysgen requires the execution of three command files (SYSGEN.CMD,
SYSGEN2.CMD, SYSGEN3.CMD). The first command file collects information
about the specific hardware and software features of your target system
and assembles the executive and device drivers.  SYSGEN2.CMD performs
phase two of the sysgen which includes the taskbuilding of the executive,
drivers, and privileged tasks.  SYSGEN3.CMD performs the final phase of
the sysgen and allows you to build the non-privileged utilities (such as
PIP, BRU, etc.) and the user mode diagnostics.  Once phase 3 has been
performed, for a particular autopatch level, it need not be repeated.
Phase 1 and 2 must be performed every time there is a change to the
executive.

Standalone sysgens use the indirect command file processor BIGIND.TSK,
which has sufficient table space to handle the quantity of symbols
generated by the sysgen command files.  If you run the sysgen online,
be sure to remove ...AT. (the taskname of IND.TSK) and reinstall IND.TSK
with a large increment (as much as it will take). Failure to do this
will cause sysgen to abort quite a while after you have started!

Most installations run BIGMAC and BIGTKB with large task increments. If this
is not the case be sure to remove and reinstall them with an increment of
50000. Failure to do this will greatly slow down your sysgen!
On the subject of the taskbuilder, if you are doing a sysgen online, be sure
the taskbuilder that you use has not been modified to change the default
switch settings.  Many installations customize their taskbuilder to have
defaults of /CP and /FP, sysgen does not expect those defaults, so install
a "virgin" copy of BIGTKB.

Since you are doing the sysgen online you must assign the SYSGEN disk to be
SY: and LB: (e.g., ASN DP2:=SY: etc.).If you have a saved answer file from a previous
sysgen, you may edit it and rename it from SYSAVED.DAT to SYSAVED.CMD.
SYSGEN.CMD will allow you to fill in any answers that are missing.
Now you can proceed with the sysgen 
by typing @[200,200]SYSGEN#.  
If this is a virgin sysgen you will have to answer all the questions, so be sure
to go over the questions before you get to this step (you can't easily back up).
Assuming Phase I succeeds you may proceed to Phase II.  When Phase II completes
you may boot your new system just to be sure it works (first make sure all other users
have logged off the system).
Phase III should then be performed because frequently the utility tasks 
(such as BRU, TKB, or PIP) are patched
by autopatch and must be rebuilt.  Look in the autopatch documentation to
determine what nonprivileged tasks need to be rebuilt.
At this point you should again
backup the sysgen disk with BRU (e.g., BRU /MOU/DEN:1600 DP2: MM:  ). This
backup copy will constitute your second fallback position should something
go wrong in a later phase of sysgen.
In case the current sysgen is not for attaining a new patch level,
this tape will already exist (having been saved from the last "autopatch"
sysgen) and will be your starting point now.

A word must be said about the virtues of FCS resident libraries. Lack of memory
and lack of disk space are two of the most common problems with non 11/70 or
11/44 systems.  A FCS resident library can dramatically help with either problem.
It has been estimated that if each DEC utility was built with FCSRES it would
save about 500 blocks of disk space, allow more simultaneous users in memory
before swapping starts and allow tasks to load faster.  It is beyond the scope
of this document to go into more detail so PLEASE look into the stuff on
FCSRES (including command files to rebuild most DEC utilities) in [344,*]
on the Fall 79 (and subsequent) RSX SIG tapes from DECUS!
.page
.hl1;Drivers and privileged tasks

At this point you should assemble and taskbuild all user written drivers.  Privileged
tasks such as parts of the KMS accounting system must also be rebuilt.
At our site there are several user written drivers in use.  We have constructed a command file
to build each driver.  This activity can take place online using the "old" system.
In addition, we are using most of the KMS software enhancements.  Since many
of these tasks replace the DEC privileged utilities, they must be rebuilt also.
There is a commandfile, KMSGEN.CMD, which does most of the work; however, we need
to prepare the disk for the KMSGEN, so we created a file PREKMS.CMD#. The
procedure is as follows:
.RM80
.lit

1. Log onto a privileged account.
2. Mount the SYSGEN and UTILITY disks and assign SY: to UTILITY
	and LB: to SYSGEN.
3. Run the command files to build the site specific privileged
	tasks (such as WHO and SETPRV) and user written drivers.
4. Execute PREKMS.CMD on the sysgen disk.
5. Change the assignment of SY: to the disk containing the
	KMS sources.
6. Execute KMSGEN.CMD

.eli
.RM65

The KMSGEN is prone to failure so don't get discouraged.
At this point you should
backup the SYSGEN disk with BRU (e.g., BRU /MOU/DEN:1600 DP2: MM:  ). This
backup copy will constitute the final backup and will contain the new system.
.hl1;Creating the target disk

The target disk is the disk that you will actually use as your system disk.
It is better to create a new disk than to use your old disk and copy the
new files from SYSGEN to it for two reasons. One, it is always wise to have
a readily accessable (and immediatly usable) copy of your old system for
several months following a sysgen, in case a serious bug is discovered in the
new system. Second, by "constructing" the disk from scratch it is possible
to position the files on the disk that
will insure minimum seek time for frequently used files (such as TKB and syslib).

The first step in creating a target disk is to run BAD on a pack and initialize it.
We like to use a disk with no bad blocks for our system disk (this insures a 
minimum of fragmentation at disk initialization). The next step is to create
all the UFDs needed (use a command file to do this!). The UFDs needed are the
ones which are active (ie. are not empty) on your current system disk.
Next copy SYSLIB.OLB and
BIGTKB.TSK to the target disk. We then use a command file to copy the privileged
tasks, drivers, and executive built during sysgen to the target disk.

Now comes the time to VMR the new system. You may have already sucessfully
done this on the SYSGEN disk but it now needs to be done on the target disk
because by using PIP to copy the tasks from one disk to another we no longer
maintain the same file IDs, therefore the tasks need to reinstalled on 
the new disk.
Again, use a command file (not SYSVMR.CMD) which contains site specific
information; loadable drivers, privileged tasks, utility tasks, and terminal
setups.  We use a main command file (VMR.CMD) which call several other
command files (e.g., DRIVER.CMD, UTIL.CMD, etc.) so that changes can be
easily made. Don't forget to make a new copy of RSX11M.SYS from RSX11M.TSK
before you attempt the VMR.

At this point copy over the user's accounts with a comand file that
preserves creation date and file ownership!  
Next copy the nonexecutalbe system files such as command files, help files, etc.
Finally copy the account file
[0,0]RSX11.SYS from your current system disk to the new disk.  Then get the
users off the system, shut it down, then
boot and save your new system disk.  Before you allow any
user activity, backup this disk, label it "virgin new system
autopatch level ?" and date it.
.ax Command Files

The following command files are listed:
.lit

	PREKMS.CMD	-Ready a virgin system for the KMSGEN
	COPY.CMD	-Copy the privileged and nonpriv tasks from
			 the UTILITY disk to the TARGET disk
	COPYPRIV.CMD	-Copy the privileged tasks from
			 the SYSGEN disk to the TARGET disk
	COPYNPRIV.CMD	-Copy the nonprivileged tasks from
			 the SYSGEN disk to the TARGET disk
	VMR.CMD		-Main VMR command file (sets up partitions
			and terminals)
	DRIV.CMD	-VMR subfile to load drivers
	PRIV.CMD	-VMR subfile to install privileged tasks
	NPRIV.CMD	-VMR subfile to install nonprivileged tasks