File	Date	Author	Commit
run	2018-03-21	Paul Edwards	[f0f0fa] add documentation about linker bug
example.jcl	2010-12-31	Paul	[43cc73] cleanup
readme.txt	2016-09-07	kerravon86	[90ecce] fix VSE380 environment variable

Read Me

Welcome to VSE/380
------------------


Installation under Windows
--------------------------

To install VSE/380, do the following:

Download VSE/380 from:
http://mvs380.sourceforge.net

Download the DOS/VS 5-pack from here:
http://dosvs.31bits.net/

Download Hercules/380 from here:
http://mvs380.sourceforge.net
and install it. Note that you can use standard Hercules from
http://www.hercules-390.org (in S/370 mode) if you wish, but 
you won't be able to run 31-bit programs such as the shipped GCC.


Set an environment variable VSE380 pointing to c:\vse380\run

c:
cd\
md vse380
cd vse380
unzip %DOWNLOAD%\vse380-whatever.zip
unzip -n %DOWNLOAD%\dosvs5pack-v1r0m1-run.zip

(optionally)
unzip %DOWNLOAD%\dosvs5pack-v1r0m1-support.zip
unzip %DOWNLOAD%\dosvs5pack-v1r0m1-useful-ref.zip


Add c:\herc380;c:\vse380\run (or equivalent) to your PATH.


Run an example program (which compiles a C program) like this:

cd c:\vse380
runvse example.jcl example.txt


That demonstrates the VSE/380 added functionality (ie mainly
a C compiler, operating in 31-bit mode) working. Also you can
see some more info on what was added by looking at the "build.bat"
in the "run/380" directory.

Please refer to the DOS/VS 5-pack for the main documentation
on how to use DOS/VS.




Support can be obtained from here:

http://tech.groups.yahoo.com/group/H390-DOSVS/
http://tech.groups.yahoo.com/group/hercules-os380/


Source code for GCC is separately available at:
http://gccmvs.sourceforge.net and you should read the
license file in it.

Source for PDPCLIB is separately available at:
http://pdos.sourceforge.net

Given that VSE/380 uses the DOS/VS 5-pack as the base, that
documentation is available as well, both offline and online:
http://itbench.speakingmind.com/dosvs5pack-v1r0m1/



Installation under Linux
------------------------

Steps are similar to the above, but you will need
to invoke hercules manually instead of via the
front-end scripts.

This is the main command:

hercules -f vse380.conf



Technical details
-----------------

DOS/VS R34 was used as the base. The reason this was chosen was
because it was before IBM started copyrighting their code.

DOS/VS R34 was not expected to run on a machine with 16 MB of
memory. As such, the shipped IPL program cannot cope with the
address wrap at the 16 MB limit of 24-bit addressing. As such,
the IPL disk was zapped to just fake 15 MB of installed
memory, and thus it is a requirement that you give a minimum
of 16 MB of real memory to VSE/380 (and that's just for the
BTL programs to work - ATL programs like GCC require 128 MB
or so to be defined). Also, the clearing of BTL memory was 
omitted (but note that Hercules clears memory when it starts 
up anyway - but bear this in mind if you plan to do multiple 
IPLs in a single Hercules session).

The linkage editor had a bug in it regarding unnamed CSECTs
(PC - private code). So it was zapped too. You can find details
of these zaps in the "run/380" directory (start with build.bat).

The displayed gregorian date is one day in advance, due to
two bugs (both dealing with 100 years, spilling into the
day field), one of which requires a supervisor regeneration.
So fixing this was an activity deferred.

R34 couldn't handle z/VSE-style parameters in the JCL, so in
order to be able to have long parameters, a job exit was
installed that translated an EXEC with PARM= into an exec
of the program VSEPARM, which then reobtains the original
program and its parameter. The way this was implemented places
a constraint of executables to be less than 3 MB in size,
and indeed, the first 6 MB of the BG region is lost to this
process (if this sort of PARM processing is used for a job step).
You will also see the effect of this substitution in job
logs, ie you will see an EXEC of VSEPARM.

The way VSEPARM has been implemented is to unconditionally
load the executable to the 7 MB location. This allows it
to more-or-less the start location of a normal-bloat 
z/VSE system, which allows non-relocatable programs like
GCC to have a good chance of execution. Since this large
executable is approximately 3 MB in size, that causes
the 7MB-10MB region to be occupied, which makes it 6 MB
from the partition start point (4 MB). So 6 MB of the
partition is lost whenever you code PARM=, which (in the
expanded 10.5 MB region) leaves 4.5 MB for BTL data, which 
is enough for most applications anyway.  GCC in particular
uses very little BTL memory because it runs AMODE 31 and
uses ATL memory. If you do not like 6 MB of the partition
to be lost, simply do not code the VSE-style PARM=. It
is hoped that in due course a solution to this issue will
be found that doesn't require 6 MB of region size to be
sacrificed. Regardless, no partition resizing should be
done without taking this into consideration. Also note
that this internal PARM processing is mostly transparent
to the end user.

An application may enter/exit AMODE 31 via BSM, as normal,
but much of the VSE infrastructure cannot cope with being
called in AMODE 31, so it is the application's responsibility
to return to AMODE 24 before calling the OS function. This
obviously means that your programs will all need to be
RMODE 24 too. Or rather - they will be treated as RMODE 24,
even if they are technically RMODE ANY applications. This
is basically similar to VSE/XA.

One VSE/380 OS call - GETVIS with LOC=ANY - is actually
implemented in (emulated) hardware (Hercules/380), so if ATL
memory is required by an application (e.g. GCC), you will 
need to install that software.

Unfortunately VSE requires you to manage your own extents.
As such, I would suggest that you design your application
so that it expects to be contained on a single disk, with
the first 5000 tracks reserved for system use, and the
extents all named at the beginning of the job for ease of
replacement.

The BG partition is defined as 8 MB - located at virtual
addresses 4 MB to 12 MB, as shown in the output from "MAP":
BG  V5A  300K     6BFFF  8092K    BE6FFF  NO NAME
However, if using the automatic batch files, the 3 main
foreground partitions are set to 0k, which then provides a
10.5 MB region as so:
BG  V5A  300K     6BFFF 10652K    E66FFF  NO NAME

It is recommended that when you link a PHASE (load module/
executable), you specify the origin as S+80 which will
allow the phase to run under all of DOS/VS, VSE/380 and
z/VSE and still be able to process labelled tapes.

As well as the GCC C compiler, VSE/380 is shipped with
several more (24-bit) C utilities - hexdump, mvsendec,
mvsunzip, copyfile, whose usage can be guessed at if
you run them without parameters. Note that when the
utility says a filename, on VSE the format of that is
dd:ddname, where ddname is replaced by some ddname you
defined in JCL. The format of the ddname is in turn
documented as part of GCCVSE (gccvse.txt in the GCCMVS
source code patch). Other behaviour is also documented
there.

There are some helper scripts, such as vsegetp, to
assist in getting programs off VSE/380 for transportation
to a z/VSE system.

Note that (unusually) the C library's header files are
stored in the CIL instead of a macro library. This is
because although PDPCLIB's header files happen to fit
within 80 bytes, other header files may not, so it is
set up for that in the future.

The 3 MB GCC executable when punched by CSERV becomes
4.3 MB and if stored as 81-byte blocks takes up 743
tracks of a 3350, ie a whopping 14 MB due to the
inefficient blocksize. To avoid this inefficiency, punches
can be converted using VSEMANIP to go from F81 to undefined
format, which should take around 235 tracks, and possibly 
compressed too, before being written to tape.



Future Direction
----------------

The following things remain to be done:

* Put the source code under source control, and ensure there
are no control characters or other characters that are not on
(or logically mapped to) a US keyboard ASCII counterpart.

* Ensure that the available source code matches the R34 executables.

* Allow US keyboard characters to display in dumps, perhaps
via the use of the UCS command and a TN print chain.

* Allow multi-line PARMs and more flexible EXEC statements,
and more flexible reservation of memory (ie not an unconditional
6 MB).

* Ensure SVA is loaded automatically at IPL

* Linkage editor and IPL changes should be done at the source
code level, not via zaps.

* Flexible memory detection - ie don't mandate 16 MB minimum.
Probably return to clearing memory at IPL time (even though
Hercules would normally have done this already).

* Y2K date bug fixes.

* Automatic extent tracking.

* Utility to run over object code to make it self-relocating.

* More flexible disk types (e.g. 3350) for the likes of Cobol.

* 3390 support.

* Device-independent SYSIPT should be able to cope with an
LRECL of 81, for the output of SYSPCH.

* Recognize and translate VSE-style private libraries.

* Linkage editor should check the limits of relocation and
produce an error message instead of overwriting memory (bug).

* LBLTYP TAPE syntax should be logically replaced by loader,
as it is in z/VSE.

* GETVIS LOC=ANY should be a feature of VSE/380, not Herc/380,
so this SVC should be supported. It is sufficient for the
SVC to return a hardcoded address of x'01100000' (17 MB) for
everything to work transparently.

* CDDELETE macro and SVC should be supported, even if it is a NOOP.