
GCCMVS for MUSIC/SP (GCCMU) - version 1.1

                           Author/distributor: Dave Edwards
                           Download file: gccmu11.zip
                           Date: Oct 16, 2007


                 GCCMU Documentation

1. Introduction
2. References
3. Setup Instructions
4. Usage Notes
5. Release Notes
6. File MD5 digest sums, etc.

NOTICE:
GCCMU is made freely available in the hope that users will
find it useful. However, it is distributed on an "as is"
basis, without any support or warranty. If you choose to
use it, you do so at your own risk. The author or authors
are not responsible for any damages or losses that may occur
from your use of this software.

For license info, see file gccmu11_license_notices.txt

Prerequisites:  The MUSIC/SP update gccmu11.zip does not have
any prerequisites, other than the MUSIC/SP 6.2 Demo system
itself. It is independent of previous versions of GCCMU and
can be installed over a previous version.

GCCMU relies heavily on existing packages, including GCCMVS
and PDPCLIB. My thanks go out to the developers of those
packages, for their great work.

Report bugs or problems in GCCMU to Dave Edwards by posting a
message to the H390-music Yahoo discussion group or via the
"Contact the author" item in the Sim390 home page. Please note
that GCCMU is a "work in progress" and is not fully complete
yet, but functionality improves with each release.


1. Introduction
---------------

The aim of GCCMU ("GCCMVS for MUSIC/SP") is be able to compile
"standard" C source and produce an executable that runs on the
MUSIC/SP operating system (normally under a mainframe emulator
such as Hercules or Sim390) and is free of license restrictions.
Since GCCMU uses the PDPCLIB run-time library, which is in the
public domain, MUSIC/SP executables created with GCCMU are not
subject to any licenses such as GPL or LGPL. You can therefore
use GCCMU to produce a proprietary program, if you wish. We
encourage you to release your programs to the public domain.

NOTE: PDPCLIB, written by Paul Edwards and others, is a
work in progress, and is not a complete C run-time library.
Not all standard C functions are provided, and some of those
that are provided have features missing or work differently.
As time goes on, PDPCLIB is steadily improving.

MUSIC/SP is a historical mainframe operating system. Currently,
it is usually run under the Hercules or Sim390 mainframe
emulator. The most popular version is the MUSIC/SP Demo
system, which is freely available for personal, noncommercial
use.

In the current release of GCCMU, C compilation is done on Windows,
using gccmvs.exe 3.0, which is a variation of the GCC 3.2.3 C
compiler which produces mainframe S/370 assembler source as output.
The gccmvs compiler uses the system include files (stdio.h, etc.)
provided by PDPCLIB.  The resulting assembler source (.asm) file (or
files, if multiple C source files were compiled) are then sent to
MUSIC/SP, usually via FTP, where they are assembled by MUSIC/SP's
assembler (/LOAD ASM, which uses the IFOX00 assembler).  The
resulting object files are linked with the PDPCLIB library object
files, producing a MUSIC/SP load module.  The load module is
executed via /LOAD XMON.  MUSIC/SP's Loader (/LOAD ASM or /LOAD
ASMLG) can also be used ("load and go"), without creating a load
module file.

A Windows batch file, gcccmpil_mu11.bat, is provided, which
simplifies use of gccmvs_v30.exe for the common case of compiling
a single C source file. The batch file supplies the appropriate
compiler options and the location of the PDPCLIB header files.
Here is the command to compile myprog.c, producing myprog.asm
(ready to be sent to MUSIC/SP) as output:

     gcccmpil_mu11 myprog

GCC options can be specified after the source file name. The
warning options -Wall -W are automatically supplied.

A future aim is to port gccmvs to MUSIC/SP, so that the C compiles
can be done on MUSIC/SP itself, rather than on Windows.

MVS is a historical IBM mainframe operating system.  It is now
usually run under the Hercules mainframe emulator.  MVS 3.8 is
freely available, and runs well under Hercules.  Since MUSIC/SP
closely emulates much of the MVS operating system (SVC instructions,
MVS control blocks, etc.), GCCMU is based largely on the GCCMVS
package (GCC C compiler for MVS), and uses the MVS version of
PDPCLIB.  Only a few changes to PDPCLIB were needed for MUSIC/SP.

For your information, gccmvs.exe 3.0 was created as a "patch"
(modification) of the standard GCC 3.2.3 compiler source, and was
built using the MinGW version of GCC.  The gccmvs.exe is the same
one used by GCCMVS in its build process for the GCC that runs under
MVS.


2. References
-------------

For info about GCCMVS, the GCCMVS "patch" to GCC, and PDPCLIB, see:

     http://gccmvs.sourceforge.net/  - home page for GCCMVS.

     http://sourceforge.net/projects/gccmvs  - project page for GCCMVS.
           Click on the "download" link or button to get to the
           GCCMVS files page, where the project files are listed and
           you can download each one. These include the Windows
           executable and PDPCLIB.

For the GCC C compiler, see:

     http://gcc.gnu.org

For info about the Sim390 mainframe emulator and the MUSIC/SP
Demo system, see:

     http://www.geocities.com/sim390

     http://webpages.mcgill.ca/staff/group3/dedwar1/web

For the Hercules mainframe emulator, see:

     http://www.hercules-390.org

For MinGW (Minimalist GNU for Windows), which provides Win32
versions of GCC and other utilities, see:

     http://www.mingw.org


3. Setup Instructions
---------------------

(1) Go to the GCCMVS project page (see the URL above), click on the
    "download" link or button, and download gccmvs-V3-mvs-win.zip
    (884 KB). Extract gccmvs.exe from the zip file, into a new
    directory on your Windows hard disk, and rename it to
    gccmvs_v30.exe (I used directory c:\my\gccmvs; if you use a
    different one you will have to modify the .bat file below).

(2) From the same location, download pdpc084.zip (PDPCLIB 0.84, 96 KB)
    and unzip its files to a new temporary directory.

(3) Copy all the .h header files from PDPCLIB to a subdirectory
    of the directory in (1). (I used c:\my\gccmvs\clibinc084; if you
    use a different one you will have to modify the .bat file below).

(4) (a) Download gccmu11.zip (follow the links to the MUSIC/SP Demo
    system updates on the Download page of
    http://www.geocities.com/sim390) and unzip its files to a new
    temporary directory.

    (b) Copy gcccmpil_mu11.bat to a directory in your Windows search
    path.  You can rename this .bat file to a more convenient name
    if you like.

    (c) Transfer the binary archive file gccmu11.mfarc to your
    MUSIC/SP system (version 6.2 or higher is recommended) and
    restore (by MFREST with the REPL=T option) the files it contains
    to MUSIC/SP.  This is normally done by signing on to userid
    $000, pressing F3 to exit from Admin, then executing
    gccmu11.mfarc by typing its name on the command line of the *Go
    mode screen.  Some of the files are restored to a new userid
    $GCC.  File gccmu11_nams.txt lists all the file names.  Naming
    convention:  files with _mu in the name contain modifications
    for MUSIC/SP or fixes to the original PDPCLIB run-time library
    components.

(5) Review file gcccmpil_mu11.bat and make any necessary changes to
    directory names, GCC compiler options on the gccmvs command,
    etc.  If you used the suggested directory names in steps (1)
    and (3), no changes are required.

Setup is now complete. See the next section for how to compile
your C programs and run them on MUSIC/SP.


4. Usage Notes
--------------

The basic steps in building a C program using GCCMU are:

- Compile your C source files (.c) on Windows, using gcccmpil_mu11.bat.
- Transfer the resulting .asm files to MUSIC/SP.
- Assemble the .asm files on MUSIC/SP, using the GCCASM command,
  to produce .obj files.
- Execute your program on MUSIC/SP, using either the Loader
  ("load and go") or the Linkage Editor. Using the Linkage Editor
  gives the fastest start-up time for your program, and involves
  creating a load module file (.lmod). If you don't want to create
  a load module file, you can use the gccloadgo command to load
  and execute the .obj file if there is only one object file.

gcccmpil_mu11.bat is used, in a Windows command window, to compile a
C source file xxx.c (using gccmvs_v30.exe), producing
an assembler source file xxx.asm as output. You can open a command
window (also sometimes called a "DOS" window) by Start / Run, then
type cmd.exe (or command.exe in some earlier versions of Windows
such as Win 95/98). A typical command is:  gcccmpil_mu11 xxx
You can add extra GCC compiler options after xxx. For example:

     gcccmpil_mu11 myprog -Wno-sign-compare

Any extra options you specify are added to the options specified
on the gccmvs command in the .bat file. The above example command
compiles myprog.c to myprog.asm. If myprog.asm already exists,
it is replaced, but the original file is copied to myprog.asmold1.
This is a safeguard, to prevent accidental loss of a file.
If the .asmold1 file already exists, it is copied to .asmold2,
etc., for up to 3 generations of old files.

To transfer the resulting .asm file to MUSIC/SP, I suggest you
use the FTP client program (ftp.exe) of Windows. Here is an example
FTP session, assuming your MUSIC/SP FTPD server is listening on
port 621 and you are using userid $000 on MUSIC/SP:

     ftp
     open localhost 621
     (enter userid $000 and its password when prompted)
     put myprog.asm
     bye

To save time, you can keep the FTP session open, in its own window,
to use for transfer of other .asm files later. I find it useful to
increase the command window size to 43 x 80 and define a large
screen buffer size (e.g. 300 lines), to allow scroll-back. Use
Properties in the window's File menu (click on the icon in the
top left corner).  You may also find it useful to increase the
DROP timeout option in $tcp:ftpd to a larger number of minutes.

Once the .asm file is on MUSIC/SP, use the gccasm command (which is
a Rexx program in $gcc:gccasm) on MUSIC/SP to assemble it, producing
a .obj file. The command format is:  gccasm xxx [options]
For example, to assemble myprog.asm to myprog.obj :

     gccasm myprog

File myprog.obj is replaced if it already exists. Possible options
are -list (saves an assembler listing file in xxx.lst) and -sys
(uses an expanded SYSLIB macro library, as needed for assembling
some of the PDPCLIB system interface modules).  For example:

     gccasm myprog -list

Once you have assembled the file or files that make up your C
program, you have two choices for how to execute the program.
Both involve combining your program object with the PDPCLIB
run-time object:

(1) "Load and Go" method: Use the MUSIC/SP loader (via /LOAD ASM)
    to load and execute all the object files. Your executable
    file contains the required control statements and /INCLUDE
    statements for your object files. See the sample file in
    $gcc:loadgo.samplejob .  If your C program consists of just
    one object file xxx.obj, you can run it by the command:
    gccloadgo xxx

(2) Load module (lmod) method: Use the MUSIC/SP Linkage Editor
    (/LOAD LKED) to create a load module (.lmod) file. This is
    done once (or whenever you change your C program). The
    executable file for your program uses /LOAD XMON, with any
    required control statements, to run the load module.
    This gives faster start-up for the program, compared with
    the "Load and Go" method. See the sample lked job in
    $gcc:lked.samplejob and the sample executor file in
    $gcc:go.samplejob .

Typically, "Load and Go" is used while you are developing and
debugging your program, and a load module is used for a
production executable once the program is stable.

There are some sample C programs in $gcc:test_*
To list the files, use the command:  libr $gcc:test_*
See also the test programs in files test_* in the distribution
.zip file. For example, to run the test_args program, enter
the command:

     $gcc:test_args 123 abcd        (uses a load module)

or   $gcc:test_args.ldgo 123 abcd        (uses the Loader)


5. Release Notes
----------------

- Some improvements in PDPCLIB 0.84:  Most math functions (exp,
  sqrt, sin, cos, etc.) are now supported. scanf() supports
  floating-point formats for input (e,E,f,g,G); to read a double
  value, use the l modifier (%lf, etc.). printf() supports
  floating-point formats for output.

- GCCMU 1.1 has a modification to stdio.c (stdio_mu.c) to add
  support for the following:
  - Formats %hd and %hu are supported correctly in printf().
  - In printf() and sprintf(), floating-point formats update the
    character count and work for output to a string.
  - In scanf() and sscanf(), types c (1 character) and u, modifier h,
    and EOF (-1) return value are supported.
  Note: If you wish to use this version of stdio.c in MVS or some
  other non-MUSIC/SP system, it is recommended that you wait for
  the official stdio.c that will be in the next release of PDPCLIB.
  which will include these mods.

- The MUSIC/SP command gccloadgo is new.

- The default run-time stack size has been increased from 64K to
  128K. If you need a larger stack size, you can increase MAINSTK
  in mvsstart.asm. Object files $gcc:mvsstart_mu.512k and
  gcc:mvsstart_mu.1024k can be used in place of $gcc:mvsstart_mu.obj
  in $gcc:libinc and $gcc:libinc.noentry, to get a stack size of
  512K or 1024K respectively.

- Because of the stack size increase and other changes, you may have
  to increase the region size for existing GCCMU 1.0 programs.
  The recommended size is at least 512K (/sys region=512).

- The i/o interface (mvssupa_mu.asm) now uses BSAM READ macro for
  file input, instead of the previous QSAM GET-L. This may require
  using the v(256) option (or v(n) with some other record length n)
  on the /JOB control statement (or the member name record for
  /LOAD LKED). See the comments in $gcc:gccmu.loadgo .

- The entry point name is now @@CRT0. For compatibility with GCCMU
  1.0, the previous entry point name @@MVSTRT can also be used.

- For compatibility with GCCMU 1.0 library object file names,
  files $gcc:stdio.obj (same as $gcc:stdio_mu.obj) and
  $gcc:time_mu.obj (same as $gcc:time.obj) are provided.

- On MUSIC/SP, if your C program writes output lines to the screen
  that start with a spacing control character (blank, 0, 1, +, -)
  and you want the control characters to be treated as normal data
  characters, use the following control statement in your job:
  /file sysprint prt osrecfm(f) oslrecl(256)

- Currently, the gccmvs compiler truncates "static" global variable
  names and "static" function names to 8 characters. (The "static"
  declaration in C means that the item is local to its own source
  file.) This can cause assembler errors ("duplicate name") if such
  names are not unique in the first 8 characters. These names do
  not appear in the object file, therefore gccmvs SHOULD generate
  unique 8-character internal replacement names for them, but it
  currently does not. One solution is to use #define statements in
  your source to change the long names to shorter (unique) ones.
  Another solution is to move "static" global variables into a
  structure, and use a short name for the structure. The problem
  of long external names (which must appear in the object file)
  will not be solved by a change to the gccmvs compiler, since it
  relates to the format of object files in MVS, CMS, and MUSIC/SP.
  You should always choose external names that are unique in the
  first 8 characters.


6. File MD5 digest sums, etc.
-----------------------------

Specifications of the gccmu11.mfarc file:

   Date: Oct 16, 2007          # of files: 93
   Is .mfarc file executable (self-restoring)?  Yes
   Total space of restored files: about 1040 K
   Size of .mfarc file (on MUSIC/SP): 1000 K
   # of 80-byte records in .mfarc file: 13626
   Size of .mfarc file (on PC): 1090080 bytes = 1.04 MB
   MD5 digest of .mfarc file: 9700E10C 39EC9144 47D56C94 7DC69FD6
   SHA1 digest: 70D9AF37 E0896CFE A75DCDB4 BFAC4B1D 76D2F6AC
   Check sum (by CHECKSUM) of .mfarc file (on MUSIC/SP): 061804965

gccmvs-V3-mvs-win.zip
   905201 bytes
   MD5 digest: 98DB372D BDF59DD3 4BA0DF8C 49D594C7
   SHA1 digest: 4ACDF6CF 685AD1A4 2F2C832E 44BCD0D0 9855BE6C

gccmvs.exe 3.0 (dated 2006-03-09) (= gccmvs_v30.exe)
   1868800 bytes
   MD5 digest: 083E606F 27107B33 CDDB26EB E2AFF858
   SHA1 digest: 49718C25 CCA1A85B B55E88E5 985CA021 5E720A00

pdpc084.zip
   97487 bytes
   MD5 digest: 5290ECE6 319F9F2D D712FA25 DC673C59
   SHA1 digest: 0EF02749 13334B7E 8C34C479 B3D44C12 3C8A16D8
