.pn 49
.bp
.SZ 10 13
.HD
.fo ''- % -''
.ce
\fBAppendix 3 \(em Running SR Programs\fR
.sp 1.5
.lp
This appendix provides a brief overview of the components of the SR system
and the way they are used to run programs.
Detailed descriptions of commands are contained in the 
.i man (1)
pages that follow.
.sh 1 _ .\" reset section numbering
.sh 1 "Simple Programs"
.lp
An SR program is contained in one or more
\fIfile\fP\fB.sr\fP
source files.
The compiler,
.i sr, 
translates the SR source code into a C program,
then calls the C compiler to create a
.b .o
file for each resource.
Source files must be compiled in the correct order to make
exports occur before imports.
.pp
Linking is directed by
.i srl ,
which acts as a front end to the Unix linker,
.i ld (1).
The main resource in the program is specified at this time.
One or more
.b .o
files of resources are combined with the SR and C
runtime libraries to produce an executable program.
.pp
Compilation and linking takes place in the context of an
.i Interfaces
directory, which is used by the compiler and linker
for storing and exchanging interface information.
.pp
A linked SR program that does not use virtual machines
is completely self-contained, relying on only those
files explicitly referenced by the SR program.
.sh 1 "Virtual Machines"
.lp
An SR program using virtual machines runs in cooperation with
an execution-time manager,
.i srx .
.i Srx
starts automatically when the SR program first creates
an instance of the predefined @vm@ resource, or when it calls the predefined
@locate@ operation.
.pp
The
.i srx
program is not contained within the SR program;
it is loaded from a predetermined location
(which can be overridden by the environment variable SRXPATH).
If a new version of the SR system is installed,
existing programs may need to be rebuilt to be compatible with the new
.i srx.
An incompatible version of
.i srx
aborts with an error message.
.sh 1 "Distributed Programs"
.lp
A program is truly distributed if it runs
on more than one physical computer.
From SR's standpoint, any program using @create vm() on n@
is treated as a distributed program,
even if @n@ does not specify a different machine.
The actual interpretation of @n@
is discussed later.
.pp
.i Srx
uses the
.i rsh (1)
command to run remote portions of a distributed program.
Only those networked hosts that you can access via
.i rsh
are usable by SR.
Your login name must be the same on these hosts.
.pp
It is possible under some circumstances,
and with some trickery,
to run a distributed program over machines with dissimilar architectures.
This is discussed further in Sec. 6 below.
In general, though,
SR programs should only be distributed over machines
with compatible CPU types, such as Vaxes or Suns but not both.
(Note: Sun-3 systems can run Sun-2 programs, but not the reverse.)
.sh 1 "Physical Machine Numbers"
.lp
Integers are used to specify the physical machines
upon which new virtual machines are created.
Initially, 0 specifies the machine upon which execution commenced,
and other integers have default meanings depending on the local
network configuration.
.pp
Every machine with a network usable by SR
has a four-byte Internet-style address,
usually given in a form something like @123.45.67.89@.
If a physical machine number @n@
is between 1 and 255, it specifies the machine whose network
address is the same as the current host but with @n@
replacing the last byte.
To a host with address @123.45.67.89@,
physical machine @47@
is the machine whose address is @123.45.67.47@.
Physical machine numbers above 255,
represented in two or more bytes,
replace the corresponding number of bytes of the original host's address.
.pp
The host numbers at your site can be obtained from your network administrator.
.\" (passing the buck?)
Some machines have multiple addresses because they are on multiple networks;
the first address returned by
.i gethostbyname (3N)
is used.
.pp
Default interpretations of physical machine numbers
can be altered by calling @locate@.
This allows, indirectly, the specification of remote
machines by name.
The call
.PS
locate(n,hostame)
.PE
associates the specified machine with the integer @n@.
The second argument, @hostname@, is the symbolic name of some
host machine; this is of course installation dependent.
This association between @n@ and @hostname@
affects the subsequent meaning of machine @n@ on
.i all
virtual machines.
In most cases it is advisable to set up explicit associations
using @locate@ rather than depending on the default mappings.
.sh 1 "Remote Execution"
.lp
When
.i srx
initiates a new virtual machine using
.i rsh ,
it must execute the SR program on the remote host.
Specifying the program's location from the remote host's
viewpoint is a difficult problem.
.pp
An automatic solution is available on systems that support
remote disk access (e.g., NFS) with a systematic naming scheme.
The SR installer configures an
.i srmap
file containing rules for locating and naming files.
The
.i srmap
file is read from a known location by
.i srx;
an alternate file can be substituted by defining
the environment variable SRMAP.
.pp
The automatic scheme can be overridden by using a third parameter
on a @locate@ call:
.PS
locate(n,hostame,pathname)
.PE
sets @pathname@
as the file to be executed by
.i rsh
when a virtual machine is created on host @n@.
.pp
On systems without remote disks,
some sort of manual action is usually needed
to copy the executable SR program to remote machines.
.i Rcp (1)
or
.i rdist (1)
can be used for this.
The remote location will depend on the
.i srmap
file; typically this would be the same location relative to the
login directory on both machines, e.g., ~mike/test/a.out
on both machines.
Be sure to recopy the file each time it is rebuilt;
mixing old and new versions can lead to disaster.
If the automatically generated filename
is unsuitable, again an explicit path in a @locate@
call can be used to override it.
.sh 1 "Heterogeneous Execution"
.lp
Distributed SR programs are intended to execute in
a homogeneous environment.
However, under certain circumstances, dissimilar but related
systems can be used.
It is usually necessary to compile the identical
programs separately under all the different environments
and to arrange (calling @locate@ if necessary) to execute the correct versions.
We offer some guidelines here, but experimentation
may also be required.
.pp
Programs built on Sun-2 systems can distributed to Sun-3
systems without recompilation; however, the reverse is not true.
Separately built Sun-2 and Sun-3 programs can also be used.
.pp
SR programs have been successfully distributed between
Sun-3 and Hewlett-Packard 200 systems, which
have similar architectures.
The identical program was compiled separately on
both systems.
.pp
SR programs have also been successfully run
on Vax machines running a mixture a 4.3 BSD and Ultrix systems.
Again, the identical program was first compiled
twice under the two different environments.
.sh 1 "Additional SR Tools"
.lp
Although only
.i sr
and
.i srl
are needed to run SR programs, other tools assist with related tasks.
.i srm
creates a
.i make (1)
description file for building complex SR programs.
.i srtex
and
.i srgrind
format SR programs for typesetting.
