S3 version 2.0 is nearing BETA testing release. There are numerous
changes in the S3 syntax and general usage. Version 1.0 basically
provided a main routine and a library, and the user had to create or
modify a Makefile to generate an executable. The user then ran the S3
program seperately, a two step affair. Version 2.0 now provides the
ability to compile, link, and execute an S3 program in one step. To
accomplish the compiling and linking, the user needs to specify which
object files and libraries are to be used. This is accomplished via an
"EMT" file (which basically replaces the Makefile).

The general format of the s3 command line is
  s3exec [-bdefnpv] [-c controlfile] [mainpct]
where the command line options are:
  -b  perform runtime dataset bounds checking (same as Ver 1.0)

  -c  Read initialization data from a control file "controlfile"

  -d  Generate reams of debugging information that you probably do not
      want to see.

  -e  create an executable link based on the main pct file, i.e assume
      your main pct file was called "fubar.pct". using the commandline
      "s3exec -e fubar" would create an executable link with the name
      fubar so that next time you wanted to run fubar.pct, instead of
      typing "s3exec fubar" you would simply type "fubar". No
      executable file is created, instead a symbolic link between the 
      name "fubar" and s3exec is created. When you type in "fubar"
      you are causing s3exec to be run with fubar read in as the main
      pct/pdt files.

  -f  Translate the PDT and PCT files into FORTRAN 77 as is currently
      being handled by the s3tof77 utility. (This option is currently
      under construction...)

  -n  Do not check the object files to see if they are up to date.
      Note: when used with the executable link created by the -e
            switch the default action is to NOT check the files and
            using the -n switch will cause the files to be checked.

  -p  Generate an execution profile of modules called from the pct
      level. Also generated is a report concerning system resource
      usage (providing the same information that is available via the
      "time" command.)

  -v  Verbose execution. Prints information upon entering and exiting
      each module called from the pct level.


Changes and New features:

  * S3 now uses an EMT file to store information concerning the object
    modules and libraries used. This is the same information that was 
    needed in the Makefile for Version 1.0. The syntax of the EMT file
    is as follows:

    - The main pct is defined by the name of the s3 program, the sub-pcts
      are defined in the EMT file using the following syntax:
        spct : <pct-name> : <pct-filename> ;
      where:
        <pct-name> is the name of the pct as used in the s3 program,
        <pct-filename> is the name of the pct file containing <pct-name>.

    - The name and type of the executable procedures are defined using the
      "proc" statement, i.e.:
        proc : <type> : <name-list> ;
      where:
        <type> is cf, cs, ff, or fs. Note that the df and ds routines
               are already "known" by the s3 system and should not be explicitly
               declared.
        <name-list> is a comma seperated list of 1 or more subroutine/function
                    names (the name of the executable module, NOT the name of
                    the file containing the module.

    - The name of the files containing the executable code are given in the
      "objs" statement, i.e.:
        objs : <filename-list> ;
      where:
        <filename-list> is a comma seperated list of files (primarily ".o" files)
                        that conatin the executable object code. If the files do
                        not exist, s3 will attempt to create them by compiling the
                        (hopefully) source code contained in the file with the same
                        name, but different extension (.f or .c).

    - The names of any library files to be used are given by the "libs" 
      statement, i.e.:
        libs : <filename-list> ;
      where:
        <filename-list> is a comma seperated list of the names
                        (full path names) of any library (".a" files)
                        to be used.

      
  * The Syntax of the PCT file has changed somewhat to provide
    additional flexibility and clarity. The changes include:

    - The first three lines of the file no longer have to be in a 
      specific format. The description line (1st line) is no longer
      required. The same information can be contained in comments.

    - The syntax of the EOL declaration has been changed to:
        EOL = <eol-list>;
      where <eol-list> is a comma separated list of characters, i.e. 
        EOL = a, b, c, d;
      Comments can be included in the EOL list as follows:
        EOL = a,     !this is a comment about the pct entry labeled a
              b,     !obviously this would be a comment about b...
              c,     !hopefully by now you get the general idea.
              d;     !do I need a further example?

    - The syntax of the EOI declaration has been changed to:
        EOI = <eoi-value>;
      where <eoi-value> is an integer value starting at 0

    - Comments now start with an exclamation point (!) instead of a
      semi-colon (;). The semi-colon is now exclusively used as a
      statement termination character.

    - The backslash (\) character is no longer needed to indicate 
      a continuation onto the next line. S3 now simply continues
      parsing the statement until it reaches a semi-colon.

    - The syntax of the executable entry lines no longer require the
      type of the executable module. i.e the syntax is now:
        <label> : <name> [: <parameter-list> ];
      where:
        <label> is a single character in the range a through z.
        <name>  is the name of the executable module.
        <parameter-list> is a comma separated list of datasets to be
                         passed to the executable (optional).
        [] The square brackets indicate what is enclosed is optional.

    - The syntax of the pct entry lines have changed. The pct filename
      is no longer passed (that is handled in the EMT file). Instead,
      eoi and eol values for the called pct can be passed. The passed
      values are only used for that particular call, the default
      values are not changed (the default values are those specified
      by the EOL and EOI statements in the called pct.). The default
      EOI and EOL values can be changed using the set_eol and set_eoi
      routines. The New syntax is:
        <label> : <name> [: <eoi-value> [, <eol-string> ]];
      where :
        <label> is a single character in the range a through z.
        <name>  is the name of the pct.
        <eoi-value> is an integer value, dataset, or constant.
        <eol-string> is a character string representing the eol list.

  * The syntax of the PDT file has remained pretty much the same,
    except for the following:

    - Comments now start with an exclamation point (!) instead of a
      semi-colon (;). The semi-colon is now exclusively used as a
      statement termination character.

    - The backslash (\) character is no longer needed to indicate 
      a continuation onto the next line. S3 now simply continues
      parsing the statement until it reaches a semi-colon.

    - Initialization of a single value can optionally use the curly
      brackets ({}) to enclose the value. The brackets are not
      required.

  * A control file can now be used to initialize datasets in addition
    to whatever initialization occurs in the PDT file. Reading a
    control file can occur either immediately after the PDT and PCT
    files have been parsed, or under the control of the user via the
    "read_control_file" executable module, which can be called from a
    pct. The syntax of the control file is similar to the dataset
    declaration statements in the PDT file, but without the type and
    dimensioning information, i.e.:
      <name> = <value>;
    or
      <name> = {<value-list>};