          MVS/380 - a free 31-bit version of MVS
          --------------------------------------


Version 1.0, released 2009-06-08


Note that the code in here is public domain, and is
an extension on IBM's MVS 3.8j which is also in the
public domain.

However, a normal installation would make use of some
other products, such as GCC, which, while not public domain,
is still freeware. You can find the license agreements
for the various products once you start up MVS. E.g.
GCC's is in GCC.DOC(COPYING) by default. If those licence
agreements are not acceptable to you, then you will need
to do a custom build of MVS/380 that excludes them.



INTRODUCTION
------------

After porting GCC 3.2.3 and PDPCLIB to the mainframe, it was
found that the memory requirements to get GCCMVS to
recompile itself were roughly 20 MB, not including the
size of the executable (3 MB), nor what the operating system
itself required. This exceeded the 16 MB limit of 24-bit 
addressing used by S/370 and MVS 3.8j. This problem was 
overcome by creating a new 31-bit architecture dubbed S/380,
and a new 31-bit operating system dubbed MVS/380. The history 
and rationale for this is documented separately in os380.doc.



INSTALLING
----------

You need the following things:

1. Hercules/380 version 3.06 v4.0 or above. This can be
obtained from http://mvs380.sourceforge.net
One day, something that can run the latest version of
MVS/380 may be available from http://www.hercules390.org

2. Turnkey MVS version 3 (TK3) which you can get from here:
http://www.bsp-gmbh.com/turnkey/tk3_faq.html#q001
Also it may be available here:
http://www.open-bpm.org/index.php/mainframes.html
And also there may be a later version released which may
still be compatible with the MVS/380 infrastructure.

3. A shadow update containing an MVS/380 build. There is
not a one-size-fits-all approach to what products an MVS/380
site should install (the same is true of any IBM site). So 
you need to find a distribution that uses the infrastructure 
and build process of MVS/380 to produce something suitable 
for your site's requirements.
Try here:
http://www.open-bpm.org/index.php/mainframes.html
or here:
http://tech.groups.yahoo.com/group/hercules-os380/
for more information on a suitable shadow archive. Note that
Sourceforge doesn't normally host operating systems,
but since this is a moderately-sized distribution in this
form, it has been allowed. Note that there is an expectation
that as a result of following these build instructions,
there will be some basic facilities made available at an
MVS/380 site, such as the GCC C compiler.

4. Some optional facilities, such as zippds, make use of
some other utilities such as "sed", which need to be obtained
independently if you wish to use them. One way of obtaining
those things is by installing Cygwin.


Then follow the instructions in install\inst380.txt on what
to do next.



DEVELOPMENT ENVIRONMENT
-----------------------

GCCMVS is provided which will show you 31-bit mode in
action.  If you compile an example C program, e.g. by
running GCC.JCL(EXAMPLE), you will see Hercules display
"31" during the compile step. Note that your installation
may have changed the name of the dataset, so you would
need to refer to any extra instructions it provided.

If you wish to operate from a Windows shell instead of,
or in addition to, working on MVS, the following utilities
are provided:


startmvs - start up MVS, optionally running a startup
script. Typical usage would be "startmvs ipl148" to
automatically IPL volume 148. If you just ran "startmvs"
you would be required to type "ipl 148" and "/r 00,clpa".


starterm - starts up a terminal session so that you can
log on to TSO. Usually run immediately after Hercules
starts, so that it can connect to Hercules. If you start
it after MVS/380 has finished IPLing, it will still work,
but you may be required to hit enter on the screen before
logging on. You log on by either typing "herc01" or
"logon herc01". herc02 is also available, but will require
a password ("cul8tr") to be entered.


runmvs - starts MVS and runs the specified JCL, to produce
the execution output. It can also take care of sending a
tape up to MVS at the same time, e.g. a zip file, and also
take care of handling an output file, e.g. an XMIT that
may have been produced.


mf2pc - will copy a single file from the mainframe to the
PC, optionally converting it from EBCDIC to ASCII.


pc2mf - will copy a single file from the PC to the mainframe,
optionally converting it from ASCII to EBCDIC.


mvsgcc - will compile an ASCII C program and produce S/370
assembly output, also in ASCII, after starting up MVS/380
to do the compile.


unload - will unload an entire MVS PDS onto aws tape. There
are utilities such as cmstape that can extract files from
an AWS tape.


load - will load an AWS tape onto a preallocated MVS dataset.


zippds - will zip up the entire contents of an MVS PDS,
optionally converting to ASCII at the same time, and produce
a zip file on the PC.


ziptopds - will take a zip file from the PC and extract it
into a preallocated PDS, optionally doing an ASCII to
EBCDIC conversion at the same time.


Note that these utilities are not meant to be run while
MVS/380 is already started. It is possible that the batch
files could be tailored so that they instead interact with
an already-running MVS/380.

Also note that while these scripts are not currently provided
for Unix users, MVS/380 is known to work on Unix. Unix
scripts will probably be provided in a later release.



PROGRAM INTERFACE
-----------------

The program interface, basically a Principles of Operation,
is provided separately in a document called os380.doc.
This explains how to write your programs so that they will 
run on both MVS/380 and z/OS - without needing to do
conditional compilation or execution, because they are
valid programs in either environment. In addition, the actual 
load module can be produced on either system, and transported
(via XMIT etc) to the other, and not require any further
processing.



OBTAINING
---------

The latest version currently resides at
http://mvs380.sourceforge.net



DEVELOPING
----------

Code changes are most welcome! But please keep MVS public domain
by not submitting non-public-domain changes. A tentative list of
modifications required can be found in work.txt.



SUPPORT
-------

Most activity related to this project is done in this group:
http://tech.groups.yahoo.com/group/hercules-os380/



HISTORY
-------

History of MVS/380

Version 0.1 released 2007-11-22:

Using the new S/380 architecture, this version of MVS/380
passed on the newly available memory to applications by
providing each task with a preallocated 30 MB chunk of
memory starting at address 04100000. Programmers were
warned that they must ensure their job was single-streamed
via an appropriate job class due to some internal restrictions.
Note that MVS/380 version 0.1 was in fact identical to
MVS 3.8j. It was just a conceptual change. Not one iota of
code was changed. Hercules changed (about 15 lines), but not
MVS 3.8j.


Version 0.2 released 2007-12-07:

API changed so that all applications must request ATL memory
via a new SVC, 233, and free that memory after use, via the
same SVC. Programmers were warned that the SVC was probably
going to change soon. Programmers were restricted in that
until they issued the ATL FREE, no further requests for ATL
memory could be made. ie, only one chunk could be obtained.
However, the 30 MB limit was lifted and now programmers can
request whatever they want up to available memory. There
were some known problems with the implementation, but so
long as the programmer was careful, it worked.


Version 0.3 released 2007-12-08:

Some macros were changed to be 31-bit clean.


Version 0.4 released 2008-03-04:

Many more macros were changed to be 31-bit clean, line numbers
stripped from modified macros. AMODE, RMODE, BSM, BASSM now
work under IFOX assembles. LOC=ANY and BELOW supported on the
GETMAIN macro. Applications are no longer allowed to obtain
memory by calling SVC 233 directly, they must use GETMAIN
with LOC=ANY instead. Same restrictions still apply as before
though. Note that executables produced on MVS/380 should still
not be shipped to other systems, but the source code is now
compatible. Many applications are now bundled - gcc, bison,
sed, bwbasic, diff, diff3, flex, m4, patch and minizip.


Version 0.9 released 2009-01-26:

The Holy Grail. A change from Gerhard Postpischil enabled
GETMAIN to work as intended thus allowing 31-bit binary
compatibility with z/OS. Addresses no longer need to be
hardcoded and no special SVC required, as the normal SVC 120
has been intercepted. Even memory partitioning is available
to allow multiple 31-bit programs.


Version 1.0 released 2009-06-08:

A different Holy Grail. GCCMVS is now C90-compliant having
had all the known bugs fixed. A number of other infrastructural
changes mean that jobs that use a binary file, e.g. a zip
file containing source, can be submitted and read data via
tape. This is much cleaner, and helps provide the ability to
do MVS compiles from a remote machine. In fact, you even
have a Windows batch file like "mvsgcc" that takes an ASCII
ASCII C program as the first parameter and produces an
ASCII assembler output to the second parameter - after having
done the compile on MVS.
