Preliminary 2703 BSC Support

Only allows Point to Point connection.


Hercules device statement :

CCUU 2703 lport=port lhost=host rhost=host rport=port dial=IN|OUT|INOUT|NO
          [pto=nnn|0|-1] [rto=nnn|0|-1] [eto=nnn|0|-1]

lport : the local TCP port number or service name on which the line will listen
        for incoming TCP calls
        This parameter is irrelevant and is ignored for DIAL=OUT
        for DIAL=IN|INOUT|NO, this parameter is mandatory

cwlhost : The local interface IP address on which to listen.
        if not specified, all interfaces will be used.
        ex:
        lhost=127.0.0.1 : Only accept calls from local host
        lhost=192.168.0.1 : Only accept calls from hosts
                that can be routed through the interface
                that has an IP address of 192.168.0.1
                If there is no 192.168.0.1 local IP address,
                this will fail.
        This parameter is irrelevant and is ignored for DIAL=OUT
        for DIAL=IN|INOUT|NO, this parameter is mandatory


rhost : the remote host ip address or name
        This parameter is irrelevant and is ignored for DIAL=IN
        for DIAL=OUT|INOUT|NO, this parameter is mandatory

rport : the remote port number or service name
        This parameter is irrelevant and is ignored for DIAL=IN
        for DIAL=OUT|INOUT|NO, this parameter is mandatory

rto, pto, eto : Read, Poll and Enable Timeout values in miliseconds.
        specifying 0 means No Timeout (infinite wait). -1 Means immediate
        timeout.

        The read timeout is how long the handler will wait for an ending
        character after the last character was received or the I/O initiated.
        The read timeout default is 3000 Miliseconds (3 Seconds)

        The poll timeout is how long the handler will wait for a polled
        station to respond to a poll request.
        The poll timeout default is 3000 Miliseconds (3 Seconds)

        The enable timeout is how long the handler will wait for the TCP
        connection to be established.
        The enable timeout default is 10000 Miliseconds (10 Seconds), except
        if DIAL=NO is also specified, in which case the enable timeout defaults
        to 0.

        Note : the ETO parameter is ignored if DIAL=NO is not specified.
               for a dialed line, there is no enable timeout. If the eto
               parameter is specified and DIAL is not "NO", then a warning message
               is issued and the parameter is ignored.


dial=IN|OUT|INOUT|NO
        Indicate call direction (if any).
        This parameter also modifies the behaviour of certain CCWS
        as well as TCP incoming call handling :

        ENABLE :
                DIAL=IN|DIAL=INOUT
                        Wait forever for an incoming call

                DIAL=NO
                        Completes immediatelly if a call
                        is already present
                        Otherwise, attemps connecting to the
                        remote end
                        if the call fails, ENABLE exits with
                        Int Req status
                DIAL=OUT
                        Enable is not a valid CCW for a DIALOUT
                        only line
        DIAL :
                DIAL=IN|DIAL=NO
                        DIAL is not a valid CCW for a DIAL IN
                        or non-switched line
                DIAL=OUT|DIAL=INOUT
                        The outgoing call is attempted

        Incomming TCP call :
                In any case, if a call is already present, the
                call is rejected.

                DIAL=NO :
                        The call is accepted, even if no CCW is
                        currently executing

                DIAL=OUT :
                        The call is rejected

                DIAL=IN|DIAL=INOUT
                        The call is accepted if the line is currently
                        executing an ENABLE ccw.


The communication protocol :

        The communication protocol is basic. Every character written
        by the guest program with a WRITE CCW is transfered to the
        remote end, untranslated and untouched (except for Transparent
        BSC rules which deem that DLE characters are doubled when the
        program has previously written a DLE/STX sequence).


Dial data format

        Dial data is originally as follows :
                x x x x 0 0 0 0 : Dial # 0
                  .........
                x x x x 1 0 0 1 : Dial # 9
                x x x x 1 1 0 0 : EON
                x x x x 1 1 0 1 : SEP

        In order to perform an outgoing call,
        the data must follow these specifications :

        N[N[N]]SEPN[N[N]]SEPN[N[N]]SEPN[N[N]]]SEPN[..[N]][EON]

        Where N is any dialing number from 0 to 9 and SEP
        is the separator.

        The 4 first group of digits represet the IP address.
        The last group represent a TCP port number.

        For example (* is the SEP character representation) :

        192*168*0*1*8888 : will issue a TCP connection to
                           192.168.0.1 port 8888

        The EON is optional. If it is present, it must be the
        last character of the dial data.

Bugs, Caveats

        The Address Prepare is not implemented
        The POLL CCW Has not been tested
        Group DIAL IN is not implemented
        DIAL CCW Not tested
        There is 1 thread per line, when there should be 1 thread for ALL lines.
        MAXDEVT may have to be adjusted under WINDOWS to accomodate for a large number of lines
            (because some I/O may take an undefinite amount of time).
        There is no 'REAL' Bsc line support yet.

-------------------------------------------------------------------------------

                       Hercules Dynamic Modules

                             (on Windows)

-------------------------------------------------------------------------------

                             Required Files


Required files:

  makefile:       "{modname}.msvc"    defines module name and source file(s)
  resource file:  "{modname}.rc"      the module's version resource file

-------------------------------------------------------------------------------

                            makefile stub format


Required makefile format:

    # Module name:

    DYNMOD = {modname}

    # Source files:

    DYNOBJ = \
        $(O){srcfile1}.obj \
        $(O){srcfile2}.obj \
        $(O){srcfile3}.obj
        ... etc...

  Your makefile is !INCLUDEd as part of Hercules's main makefile and
  thus your dynamic module gets built along with the rest of Hercules.

-------------------------------------------------------------------------------

                          The MAKE/BUILD command


Building (making):


    dynmake.bat {projdir} {modname} {build_type} {num_cpus} [-a|clean]

  e.g.:

   "X:\Hercules\dynmake.bat"  "$(SolutionDir)"  {modname}  RETAIL  32  -a


  The {projdir} value you pass MUST be a fully qualified path to your
  dynamic module's project directory where all of your files are. The
  dynamke.bat command you invoke should also be a fully qualifed path
  to the desired Hercules dynmake.bat file. The other arguments (i.e.
  {build_type}, {num_cpus}, etc) are identical to the values normally
  specified for the main Hercules "makefile.bat" command used to build
  Hercules with. Refer to makefile.bat for details.

-------------------------------------------------------------------------------

             Pre-Build event and Post-Build event callbacks


Optional files:

    prebuild.bat   Called before the main Hercules makefile.bat is called.
    postbld.bat    Called after  the main Hercules makefile.bat is called.

  During the build process, dynmake.bat checks if the file exists in your
  specified project directory and if it does, calls it with the following
  parameters:

        {hercdir}  {modname}  {build_type}  {num_cpus}  [-a|clean]

  The {hercdir} value is the fully qualified path the main Hercules source
  code directory. The other parameters are the same values that you passed
  to the dynmake.bat command.

-------------------------------------------------------------------------------

                            Resource Compiler


For your convenience the following #defines are also passed to the resource
compiler on the command-line during the actual build process:

    VERSION              The Hercules version string  (e.g. "3.06-svn-5602")
    TARGETFILENAME       Your module name string      (e.g. "{modname}.dll")
    MAX_CPU_ENGINES_STR  Number of CPUs as a string   (e.g. "32")

  Use them in your .rc resource file's VERSIONINFO structure as needed.

-------------------------------------------------------------------------------

                            The Build Process


Dynmake.bat first creates a work subdirectory beneath Hercules's main source
code directory using the same name as the {modname} you passed to it.

It then calls your prebuild.bat file if it exists. Use this callback to
perform any pre-build adjustments to your source files that may be necessary
before the actual build process begins.

When your prebuild.bat returns, it then copys all *.c, *.h, *.rc, *.rc2 and
*.msvc files from your project directory into its {modname} subdirectory and
invokes Hercules's primary "makefile.bat" script to perform the actual build.

When the build is done it then calls your postbld.bat callback if it exists.
You can use this callback to copy the resulting binary from Hercules's output
directory to your project directory or whatever other post-build processing
your product may require.

-------------------------------------------------------------------------------

                            More Information


For additional information regarding dynamic modules please see the "Hercules
Dynamic Loader" readme document called "README.HDL".

-------------------------------------------------------------------------------

ECPS:VM : Extended Control Program Support : VM/370
               - AND -
Extended VM Assists - Partial Privop Simulation And Virtual Interval Timer

************ CHANGE LOG ****************
07/07/03 : Changed description for configuration and commands
           ECPS:VM changed to ECPSVM (config)
           ecpsvm changed to ecpsvm (command)

     - PARTIAL IMPLEMENTATION DOCUMENTATION -

*************************

Affected operating systems :

VM/370 Release 6 (PTFs required - PLC 029 works fine)

up to

VM/SP 6 (with or without HPO option)

--- VM/XA SF, VM/XA SP, VM/ESA and z/VM do NOT use these Assists,
    but rely on the SIE instruction to perform some of these functions.

A VM/SP Guest (or VM/370 Guest with 4K Storage key updates) running under
[z/]VM[/[XA|ESA]] will NOT have access to either the CP assists or VM Assists.
The ECPS:VM Feature is disabled when running under SIE.

************************

How to enable VM Assists :

In the HERCULES.CNF file, in the configuration section :

ECPSVM YES|NO|LEVEL n (where n is the requested level.)

If "YES" is specified, the most appropriate level is returned (Level 20)

n Doesn't affect the operations of the assist but what level is reported to
        the program.

    - CAUTION - Use the 'n' form is not recommended, and is only provided
                for engineering use.

**********

New panel command : 'ecpsvm'

Subcommands :

ecpsvm stats : Shows ECPS:VM Call/Hit statistics
ecpsvm enable/disable feature : Enable/Disable named feature
ecpsvm help : (guess)
ecpsvm debug [feature|ALL|CPASSIST|VMASSIST] : Turn on debugging messages for a specific feature
ecpsvm nodebug [feature|ALL|CPASSIST|VMASSIST] : Turn off...
ecpsvm level [nn] : Force ECPS:VM to report a certain support level
        (or display the current support level)

NOTE : ecpsvm disable does NOT entirelly disables CP ASSISTS. If it did (i.e. generate a program interrupt whenever a E6xx instruction is invoked) VM would abend immediatelly. Rather, ommit the ECPSVM statement in the configuration file.

To determine the feature names, type "ecpsvm enable ALL".
        All the enabled features will be listed.

the ecpsvm command is NOT case sensitive

**********

Determining if the assist is used by VM :

Use the 2 following CLASS A commands :

CP QUERY CPASSIST
CP QUERY SASSIST

Both queries should return 'ON'.

Also use the following CLASS G Command :

CP QUERY SET

2nd line should indicate :

ASSIST ON SVC TMR

***********

Technical information

the CP Assists provides The VM SCP with various microcoded instructions to shorten the supervisor pathlength. All microcoded instructions are priviledged instructions and have an opcode of E6xx. They are native representation of what the SCP would do in a similar case. For all cases where the assist is not able to resolve a situation, the E6XX instructions resolve to a no-op, thus leaving the responsability of the task to the original CP Code.

The VM Assists alters the behaviour of certain priviledged instructions when executed in problem state (controled by the Problem State bit in the PSW) either by completely simulating the instruction (when feasable), Branching directly to the CP support module for that instruction (therefore bypassing Program interruption processing and instruction decoding), or generating a Program interruption otherwise.

The VM Virtual Interval Timer assist allows updating of a Virtual Machine virtual interval timer directly by the microcode.

Both CP And VM Assists are controled by real Control Register 6 which control availability, and behaviour of the assists.

************

Troubleshooting

In the event that a certain CP or VM Assist disrupts normal operations, it is possible to selectivelly disable each discrete component. The best method is to disable ALL VM and CP Assists (Except STEVL and SSM if done prior to IPL) and to enable each feature until the problem occurs. If it is unknown whether the problem lies in the VM or CP Assist, it is also possible to enable/disable the entire group of assists.

See the EVM ENA|DISA Commands.

EVM STA allows to see how often each assist is invoked. The hit and hit ration makes it possible to determine how effective the assists are.

A Low hit ratio may be normal in some situations (for example, the LPSW Hit ration will be very low when running VM under VM, because most PSW switches cannot be resolved by the assist)

A Low invocation count simply shows that in THAT particular situation, the related assist is not used often (For example, there are very few LCTLs when running CMS).

Some assists are just invoked once at IPL (STEVL). This is normal behaviour.

************

Implemented Assists :

CP ASSISTS :
FREEX, FRETX (CP Free Storage management)
DISP0, DISP1, DISP2 (CP Dispatching)
PGLOCK, PGULOCK (Real frame locking/unlocking)
TRANBRNG, TRANLOCK (Virtual frame addressing/locking)
SCNRU, SCNVU (Real/Virtual Device control block scan)
STEVL (Store ECPS:VM support level)

VM ASSISTS :
Virtual Interval Timer
LPSW Simulation
SSM Simulation
SVC Simulation
LCTL Simulation

Non-Implemented assists :

CP ASSISTS :
FREE/FRET : (Original (up to level 19)
            CP Storage Management - replaced by FREEX/FRETX)
CCWGN, DFCCW, DNCCW, UXCCW : CCW/CSW Translation assists (Soon)
LCSPG : Locate Changed Shared Page (Soon)
VIPT, VIST : Virtual Translation Page/Segment Invalidation (Soon)
LINK/RETURN (SVC 8/SVC 12) (Soon)
Prefered Machine Assists (Insufficient information)
.. Maybe others ...

VM ASSISTS :
V=R Shadow Table Bypass assists (Including LRA instruction)
        (note : The V=R Shadow Table Bypass assist is a feature which requires the guest program
        to be aware of the feature (Page 0 Relocation))
SIO (In progress - Partial sim)
DIAG (In progress - Partial sim)
IUCV (In Progress - Partial sim - VM/SP4 or later only)
STxSM (Almost never invoked - ECMODE Only)
ISK/SSK/ISKE/SSKE/IVSK (Extended Key Ops assist)
VM Assists for MVS
.. Maybe others ...

*****************
BUGS & Caveats :

ECPS:VM will NOT work in an AP or MP system. An AP or MP generated system
locks the control blocks being manipulated by the assisted functions
(VMBLOK, RDEVBLOK, VDEVBLOK, etc..). However, the current ECPS:VM
implementation doesn't lock any of those structures. Therefore, CP will
fairly quickly abend because it will find some of the control blocks
to not have been locked when they should (various LOKXXX abends).

Consequently, ECPS:VM must be disabled when a AP or MP system is used.

*****************

Have Fun,

--Ivan

/*
                     Hercules Dynamic Loader

    The dynamic loader is intended to supply a loading and linking
    mechanism, whereby routines, commands, instructions and functions
    can be dynamically added to hercules, without the need to rebuild
    or even restart hercules.

    The loader can be controlled by the following hercules commands:

        ldmod <module list>    - Load modules named in module list
        rmmod <module list>    - Unload modules named in list
        lsmod                  - List all modules and entry points
        lsdep                  - List all dependencies

        The ldmod statement may also appear in the hercules
        configuration file.

        configuration statement:
        modpath <pathname>     - Specifies where modules are loaded from


    The loader has 2 basic functions module load and module unload.

    Module load:

    int hdl_load(char *name, int flags);

        Where name is the module name, this name may include the
        path.  If no path is given then the module is loaded from
        the default library search order.  Note that this is
        different from the standard search order.

        flags may be one of the following:

         HDL_LOAD_DEFAULT or 0  -  Default load
         HDL_LOAD_MAIN          -  Reserved for hercules use
         HDL_LOAD_NOUNLOAD      -  Module cannot be unloaded
         HDL_LOAD_FORCE         -  Override dependency check
         HDL_LOAD_NOMSG         -  Do not issue any error messages

        This function returns a zero value when the load is successful.


    Module unload:

    int hdl_dele(char *name);

        Where name is the name of the module that is to be unloaded.

        This function returns a zero value when the unload is successful.


    Resolving Symbols:

    void * HDL_FINDSYM(char *symbolname);

        This function will return the entry point of symbolname or
        zero when the symbol cannot be resolved.

    void * HDL_FINDNXT(current_entry point);

        This function will return the previous entry point.
        That is, the entry point which was current before the entry point
        as identified by current_entry point was registered.

        This function is intended to allow a module to call the original
        routine.  An example of this is given in the panel_command entry
        as listed below.


    There are some special considerations for systems that do not support
    the concept of back-linking.  Back-linking is the operating system
    support of dynamically resolving unresolved external references in
    a dynamic module, with the main module, or other loaded modules.
    Cygwin does not support back-linking and Cygwin specials are listed
    in this example with #if defined(WIN32).


    Some additional notes:

    Unload will remove all references to a specific module, but currently
    it will not actually remove the loaded module from memory.  This is
    because there is no safe way (yet) to synchronize unloading of code
    and, besides, it may still be in use.  This should however pose no
    practical limitations.

    When a module lists a new dependency, that dependency will be regis-
    tered.  Unloading the module does not remove the dependency, this is
    to be consistent with the previous note about unloading.



    Diagnose F14 - dll interface

    Purpose:

    Allow external routines to be called from OS running under hercules
    external routines must reside in hercules dll's


    Instruction:

      Format:

      83 r1 r3 d2(b2)

      r1: register containing real address of external routine name to be
          called this routine name is defined as CL32, and is subject to
          EBCDIC to ASCII translation under control of hercules codepages.
          This parameter must be 32 byte aligned.

      r3: register containing user parameter.

      d2(b2): 0xF14


    External routine:

      void xxxx_diagf14_routine_name(int r1, int r3, REGS *regs);

      xxxx_diagf14_ prefix to routine_name
      xxxx being either s370, s390 or z900 depending on architecture mode.

      The instruction is subject to machine malfunction checking.
      The external routine may be interrupted when an extended wait or loop
      occurs.


*/

#include "hercules.h"
#include "devtype.h"
#include "opcode.h"


/*   Local definitions   */


static void *gui_cpu_state(REGS *regs)
{
    void *(*prev_cpu_state)(REGS *);

    /* CPU status update processing */

    /* Call higher level routine if one exists */
    if((prev_cpu_state = HDL_FINDNXT(gui_cpu_state)))
        return prev_cpu_state(regs);

    return NULL;
}


void  *ProcessCommand (char *command)
{
void * (*prev_panel_command)(char *);

    if (strncasecmp(command,"ourcmd",6) == 0)
    {
        logmsg ("This is our command\n");
    }
    else
        /* Call higher level command handler */
        if((prev_panel_command = HDL_FINDNXT(ProcessCommand)))
            return prev_panel_command(command);

    return NULL;
}


/*
    The dependency section is - for all intents and purposes - called
    before the module is loaded.  Its function is to check that there
    are no incompatibilities between this module and the version of
    hercules that we are running.  Dependencies are identified by
    name, this name is given on the HDL_DEPENDENCY statement.

    Each dependency then has a version code, and a size code, where
    the version code is a character string, and the size code an
    integer value.  If the version or size codes do not match with
    those in the hercules main module, the module cannot be loaded.
    The version is usually a character string that identifies the
    version of the component, and the size is to be the size of
    the component in the case of structures or unions.

    Version and size should be coded as following:

      #define HDL_VERS_SOMETHING  "1.0"
      #define HDL_SIZE_SOMETHING  sizeof(SOMETHING)

    where SOMETHING can be a structure or other component.

    the associated dependency statement:

      HDL_DEPENDENCY(SOMETHING);

    When a dependency is given that has not yet been registered,
    it will be registered, such that it can be checked in subsequent
    module loads.

    The dependency section is mandatory.

*/

HDL_DEPENDENCY_SECTION;
{
     /* Define version dependencies that this module requires */
     HDL_DEPENDENCY ( HERCULES );
     HDL_DEPENDENCY ( SYSBLK   );
     HDL_DEPENDENCY ( REGS     );
     HDL_DEPENDENCY ( DEVBLK   );
}
END_DEPENDENCY_SECTION;


/*
    The registration exports labels and their associated entry points
    to hercules, such that the symbols and associated entry points may
    be known to hercules and any other module that may have been loaded.
    The registration section is called once during module load.

    If we have registered a function that is also called from this DLL,
    then it must also be listed in the resolver section.  This to ensure
    that the symbol is properly resolved when other modules are loaded.

    The registration section is optional.

*/


HDL_REGISTER_SECTION;
{
    /* These are the entry points we export to Hercules
       All functions and labels used this dll must be static
       and non exportable, this to ensure that no foreign
       names are included by the system loader on systems
       that provide back-link support (mostly *nix systems)
    */

    HDL_REGISTER ( daemon_task, external_gui_interface );
    HDL_REGISTER ( debug_cpu_state, gui_cpu_state );
    HDL_REGISTER ( panel_command, ProcessCommand );
}
END_REGISTER_SECTION;


/*
    The resolver section imports the entry points of symbols that
    have been previously registered.

    When a symbol is requested that has not been previously registered
    then the resolve function will search the loaded modules for
    that symbol, and register it implicitly.  This latter function
    is mainly provided to support systems that do not have back-link
    support (most notably Cygwin).

    Entry points that are resolved should be indirect pointers, for
    example the panel_command routine is defined as:

       void *(*panel_command)(char *)

    The resolver may be called multiple times, the first time it is
    called is during module load, immediately after the registration
    section is called.  It is subsequently called when other modules
    are loaded or unloaded.

    When a symbol cannot be resolved it will be set to NULL.

    The resolver section is optional.

*/


HDL_RESOLVER_SECTION;
{
    /* These are Hercules's entry points that we need access to
       these may be updated by other loadable modules, so we need
       to resolve them here.
    */

    HDL_RESOLVE ( panel_command );
    HDL_RESOLVE ( debug_cpu_state );

    HDL_RESOLVE_PTRVAR ( my_sysblk_ptr, sysblk );
}
END_RESOLVER_SECTION;


/*
    The device section is to register device drivers with hercules.
    It associates device types with device handlers

    If a device handler is not registered for a specific device type
    then and a loadable mode with the name of "hdtxxxx" (where xxxx
    is the device type) exists then that module is loaded

    Search order:
        1) The most recently registered (ie loaded) device of the
           requested device type.
        2) Device driver in external loadable module, where the
           module name is hdtxxxx (where xxxx is the device type
           ie module name hdtlcs for device type LCS or hdt2703
           for device type 2703)
        3) If the device is listed in the alias table (hdteq.c)
           then external module hdtyyyy will be loaded, where
           yyyy is the base name as listed in hdteq.c.
        The device name is always mapped to lower case when searching
        for loadable modules.

    The device section is optional
*/

HDL_DEVICE_SECTION;
{
    HDL_DEVICE(1052,constty_device_hndinfo);
    HDL_DEVICE(3215,constty_device_hndinfo);
}
END_DEVICE_SECTION;

/*  The instruction section registers inserts optional instructions,
    or modifies existing instructions.

    Instructions are generally defined with DEF_INST(instname) which results
    in an external reference of s370_instname, s390_instname and z900_instname.
    If an instruction is not defined for a certain architecture mode then
    UNDEF_INST(instname) must be used for that given architecture mode.

    The instruction section is optional
*/

HDL_INSTRUCTION_SECTION;
{
    HDL_DEFINST(HDL_INSTARCH_370,0xB2FE,new_B2FE_inst_doing_something);
    HDL_DEFINST(HDL_INSTARCH_390|HDL_INSTARCH_900,0xB2FD,new_B2FD_inst_doing_something_else);
}
END_INSTRUCTION_SECTION;


/*
    The final section is called once, when the module is unloaded
    or when hercules terminates.

    A dll can reject being unloaded by returning a non-zero value
    in the final section.

    The final section is intended to be used to perform cleanup or
    indicate cleanup action to be taken.  It may set a shutdown
    flag that is used within this dll that all local functions
    must now terminate.

    The final section is optional
*/

HDL_FINAL_SECTION;
{

}
END_FINAL_SECTION;




Below is Fish's sample code...


/*   Define version dependencies that this module requires...
**
** The following are the various Hercules structures whose layout your
** module depends on. The layout of the following structures (size and
** version) MUST match the layout that was used to build Hercules with.
** If the size/version of any of the following structures changes (and
** a new version of Hercules is built using the new layout), then YOUR
** module must also be built with the new layout as well. The layout of
** the structures as they were when your module is built MUST MATCH the
** layout as it was when the version of Hercules you're using was built.
** Further note that the below HDL_DEPENDENCY_SECTION is actually just
** a function that the hdl logic calls, and thus allows you to insert
** directly into the below section any specialized 'C' code you need.
*/
HDL_DEPENDENCY_SECTION;
{
     HDL_DEPENDENCY(HERCULES);
     HDL_DEPENDENCY(REGS);
     HDL_DEPENDENCY(DEVBLK);
     HDL_DEPENDENCY(SYSBLK);
     HDL_DEPENDENCY(WEBBLK);
}
END_DEPENDENCY_SECTION;


/*  Register re-bindable entry point with resident version, or UNRESOLVED
**
** The following section defines the entry points within Hercules that
** your module is overriding (replacing). Your module's functions will
** be called by Hercules instead of the normal Hercules function (if any).
** The functions defined below thus provide additional/new functionality
** above/beyond the functionality normally provided by Hercules. Be aware
** however that it is entirely possible for other dlls to subsequently
** override the same functions that you've overridden such that they end
** up being called before your override does and your override may thus
** not get called at all (depending on how their override is written).
** Note that the "entry-point name" does not need to correspond to any
** existing variable or function (i.e. the entry-point name is just that:
** a name, and nothing more. There does not need to be a variable defined
** anywhere in your module with that name). Further note that the below
** HDL_REGISTER_SECTION is actually just a function that the hdl logic
** calls, thus allowing you to insert directly into the below section
** any specialized 'C' code that you may need.
*/
HDL_REGISTER_SECTION;
{
    /*            register this       as the address of
                  entry-point name,   this var or func
    */
    HDL_REGISTER( panel_command,      my_panel_command );
    HDL_REGISTER( panel_display,      my_panel_display );
    HDL_REGISTER( some_exitpoint,     UNRESOLVED       );
}
END_REGISTER_SECTION;


/*   Resolve re-bindable entry point on module load or unload...
**
** The following entries "resolve" entry points that your module
** needs. These entries define the names of registered entry points
** that you need "imported" into your dll so that you may call them
** directly yourself. The HDL_RESOLVE_PTRVAR macro is used to auto-
** matically set one of your own pointer variables to the registered
** entry point's currently registered value (usually an address of
** a function or variable). Note that the HDL_RESOLVER_SECTION is
** actually just a function that the hdl logic calls, thus allowing
** you to insert directly into the below section any specialized 'C'
** code that you may need.
*/
HDL_RESOLVER_SECTION;
{
    /*           Herc's registered
                 entry points that
                 you need to call
                 directly yourself
    */
    HDL_RESOLVE( config_command          );
    HDL_RESOLVE( some_exitpoint          );
    HDL_RESOLVE( debug_cpu_state         );
    HDL_RESOLVE( debug_program_interrupt );
    HDL_RESOLVE( debug_diagnose          );

    /* The following illustrates how to use HDL_RESOLVE_PTRVAR
       macro to retrieve the address of one of Herc's registered
       entry points.

                         Your pointer-   Herc's registered
                         variable name   entry-point name
    */
    HDL_RESOLVE_PTRVAR(  my_sysblk_ptr,  sysblk         );
}
END_RESOLVER_SECTION;


/* The following section defines what should be done just before
** your module is unloaded. It is nothing more than a function that
** is called by hdl logic just before your module is unloaded, and
** nothing more. Thus you can place any 'C' code here that you want.
*/
HDL_FINAL_SECTION;
{
    my_cleanup();
}
END_FINAL_SECTION;




/* DYNDIAG.C    (c) Copyright Jan Jaeger, 2003                       */
/*              Hercules Dynamic Loader                              */

/*              Sample diagf14 dll routine                           */

/*                                                                   */
/*   Assembler to call routine:                                      */
/*                                                                   */
/*              LRA  R1,=CL32'test'                                  */
/*              LRA  R2,=X'01020304'  USERPARM                       */
/*              DC   X'83120F14'   DIAG R1,R2,X'F14'                 */
/*                                                                   */


#include "hercules.h"

#include "opcode.h"

#include "inline.h"


void ARCH_DEP(diagf14_test) (int r1, int r3, REGS *regs)
{
U32 r3loc;

    logmsg("diagf14:  r3 = %8.8X\n",regs->GR_L(r3));
    r3loc = ARCH_DEP(vfetch4) (regs->GR_L(r3), USE_REAL_ADDR, regs);
    logmsg("diagf14: *r3 = %8.8X\n",r3loc);
}



#if !defined(_GEN_ARCH)

#if defined(_ARCHMODE2)
 #define  _GEN_ARCH _ARCHMODE2
 #include "dyndiag.c"
#endif

#if defined(_ARCHMODE3)
 #undef   _GEN_ARCH
 #define  _GEN_ARCH _ARCHMODE3
 #include "dyndiag.c"
#endif


HDL_DEPENDENCY_SECTION;
{
     HDL_DEPENDENCY (HERCULES);
     HDL_DEPENDENCY (REGS);
     HDL_DEPENDENCY (DEVBLK);
     HDL_DEPENDENCY (SYSBLK);

} END_DEPENDENCY_SECTION;


HDL_REGISTER_SECTION;
{

    HDL_REGISTER(s370_diagf14_test,s370_diagf14_test);
    HDL_REGISTER(s390_diagf14_test,s390_diagf14_test);
    HDL_REGISTER(z900_diagf14_test,z900_diagf14_test);

} END_REGISTER_SECTION;


HDL_RESOLVER_SECTION;
{

} END_RESOLVER_SECTION;

HDL_FINAL_SECTION;
{

} END_FINAL_SECTION;


#endif /*!defined(_GEN_ARCH)*/

/* END DYNDIAG.C */



/* DYNCGI.C     (c)Copyright Jan Jaeger, 2002-2003                   */
/*              HTTP cgi-bin routines                                */

/* This file contains cgi routines that may be executed on the      */
/* server (ie under control of a hercules thread)                    */
/*                                                                   */
/*                                                                   */
/* Dynamically loaded cgi routines must be registered under the      */
/* pathname that they are accessed with (ie /cgi-bin/test)           */
/* All cgi pathnames must start with /cgi-bin/                       */
/*                                                                   */
/*                                                                   */
/* The cgi-bin routines may call the following HTTP service routines */
/*                                                                   */
/* char *cgi_variable(WEBBLK *webblk, char *name);                   */
/*   This call returns a pointer to the cgi variable requested       */
/*   or a NULL pointer if the variable is not found                  */
/*                                                                   */
/* char *cgi_cookie(WEBBLK *webblk, char *name);                     */
/*   This call returns a pointer to the cookie requested             */
/*   or a NULL pointer if the cookie is not found                    */
/*                                                                   */
/* char *cgi_username(WEBBLK *webblk);                               */
/*   Returns the username for which the user has been authenticated  */
/*   or NULL if not authenticated (refer to auth/noauth parameter    */
/*   on the HTTPPORT configuration statement)                        */
/*                                                                   */
/* char *cgi_baseurl(WEBBLK *webblk);                                */
/*   Returns the url as requested by the user                        */
/*                                                                   */
/* void html_header(WEBBLK *webblk);                                 */
/*   Sets up the standard html header, and includes the              */
/*   html/header.htmlpart file.                                      */
/*                                                                   */
/* void html_footer(WEBBLK *webblk);                                 */
/*   Sets up the standard html footer, and includes the              */
/*   html/footer.htmlpart file.                                      */
/*                                                                   */
/* int html_include(WEBBLK *webblk, char *filename);                 */
/*   Includes an html file                                           */
/*                                                                   */
/*                                                                   */
/*                                           Jan Jaeger - 28/03/2002 */

#include "hstdinc.h"
#include "hercules.h"
#include "devtype.h"
#include "opcode.h"
#include "httpmisc.h"

#if defined(OPTION_HTTP_SERVER)

void cgibin_test(WEBBLK *webblk)
{
    html_header(webblk);
    hprintf(webblk->hsock, "<H2>Sample cgi routine</H2>\n");
    html_footer(webblk);
}


HDL_DEPENDENCY_SECTION;
{
     HDL_DEPENDENCY(HERCULES);
//   HDL_DEPENDENCY(REGS);
//   HDL_DEPENDENCY(DEVBLK);
//   HDL_DEPENDENCY(SYSBLK);
     HDL_DEPENDENCY(WEBBLK);
}
END_DEPENDENCY_SECTION;


HDL_REGISTER_SECTION;
{
    HDL_REGISTER( /cgi-bin/test, cgibin_test );
}
END_REGISTER_SECTION;


HDL_RESOLVER_SECTION;
{
}
END_RESOLVER_SECTION;


HDL_FINAL_SECTION;
{
}
END_FINAL_SECTION;

#endif /*defined(OPTION_HTTP_SERVER)*/



/* TESTINS.C    Test instruction                                     */

#include "hercules.h"

#include "opcode.h"

/*-------------------------------------------------------------------*/
/* 0000 BARF  - Barf                                            [RR] */
/*-------------------------------------------------------------------*/
DEF_INST(barf)
{
int r1, r2;                                     /* register values   */

    RR(inst, regs, r1, r2)

    logmsg("Barf\n");

    ARCH_DEP(program_interrupt)(regs, PGM_OPERATION_EXCEPTION);
}


#if !defined(_GEN_ARCH)

#if defined(_ARCHMODE2)
 #define  _GEN_ARCH _ARCHMODE2
 #include "testins.c"
#endif

#if defined(_ARCHMODE3)
 #undef   _GEN_ARCH
 #define  _GEN_ARCH _ARCHMODE3
 #include "testins.c"
#endif


HDL_DEPENDENCY_SECTION;
{

} END_DEPENDENCY_SECTION;


HDL_INSTRUCTION_SECTION;
{
    HDL_DEFINST(HDL_INSTARCH_ALL,0x00,barf);

} END_INSTRUCTION_SECTION;

#endif /*!defined(_GEN_ARCH)*/

Customizable hercules 3270 Logo

The initial welcome screen presented when a TN 3270 terminal connects
to a hercules 3270 device can now be customized.

The customized logo is stored in a plain text file which contains
positioning orders, attributes and variable substitutions.

hercules also contains a built-in logo should no suitable file be found.

Upon startup, hercules will first look for a file named "herclogo.txt" in
the current directory.

The name of the logo file can also be specified as a startup option by
using the '-b' flag.

Additionally, the file may also be specified by using the 'HERCLOGO'
configuration statement.

(NOTE : The statement was previously LOGOFILE, but LOGOFILE has been
 deprecated).

The file may also be specified by using the 'HERCLOGO' environment
variable.

The file to be used can also be specified at run time using the
'HERCLOGO' panel command.

Each line in the file represent either an order or a plain text line.

The orders are as follows :

@SBA X,Y
Position the current buffer position to Row X col Y (X and Y start at 0)

@SF [H][P]
Set the Highlight and/or Protected attribute

@NL
Forces going to the next line

@ALIGN NONE|LEFT|RIGHT|CENTER
Specified the text alignement (relative to the left and right borders of the
terminal). When ALIGN is other than "NONE", a new line is automatically
inserted after each line of text. If ALIGN is "NONE", then the text will
be written without skipping to the next line.

It is also possible to embbed substitution variables in outgoing text.
Substition is indicated by enclosing the variable name between $( and )

The following variables are defined in that environment :

VERSION : The hercules version
HOSTNAME : The host name on which hercules is running
HOSTOS : The host operating system
HOSTOSREL : The Host operating system release
HOSTOSVER : The host operating system version
HOSTARCH : The host architecture
HOSTNUMCPUS : UP (for 1) or MP=X (for more than 1)
LPARNAME : The LPAR name specified in the configuration file
CCUU,ccuu,CUU,cuu : Various forms of the device number of the terminal
CSS : The Logical Channel Subsystem Set or Channel Set for the terminal
SUBCHAN : The Subchannel number for the terminal

Additionally, it is also possible to specify environment variable names.

The file 'herclogo.txt' is provided in the distribution as a sample template.
It reflects the contents of the built-in logo.

Ivan Warren 3/1/2006

-----------------------------------------------------------------
                    Hercules Networking
-----------------------------------------------------------------

    *** Please read herctcp.html as Roger explains how ***
    *** to set up TCP/IP networking with Hercules.     ***

All of the communications emulation implemented within Hercules
use a CTCA (Channel to Channel Adapter) type device. Depending on
the "flavor", the CTCA device will provide either a
point-to-point or a virtual network adapter interface to the
driving system's TCP/IP stack or in the case of CTCT, a "true"
CTCA connection to another instance of Hercules via a TCP/IP
connection.

All current emulations, with the exception of VMNET, CTCT and CTCE use
the Universal TUN/TAP driver on *nix and TunTap32 (WinPCap) on
the Windows platforms which creates a network interface on the
driving system which allow Hercules to present frames to, and
receive frames from the TCP/IP stack. This network interface is
configured on *nix platforms by the hercifc program which is
invoked by Hercules after the TUN/TAP device is opened. The
hercifc program runs as root. Please read herctcp.html for more
information on the security implications of the hercifc program.

Now for the gory details:

---------------------------------------------------------------

    *** Important information about changes to the ***
    *** Hercules configuration files - PLEASE READ ***

The format of the Hercules configuration file statements for all
of the networking emulations have changed from the previous
releases of Hercules. The older format will still be accepted
to maintain compatibility, however it is the recommendation
of the maintainer that the new format be used. Also note that
there is no distinction between the CTCI and CTCI-W32 modes any
more, in fact CTCI-W32 does not exist in this release (other
than to maintain compatibility with previous configuration files).

---------------------------------------------------------------

    *** Important information about changes to the ***
    *** Hercules configuration files - PLEASE READ ***

In releases prior to Hercules version 3.00, all of the TCP/IP
emulations required two addresses to be defined in the Hercules
configuration file: one address for the read subchannel and the
other for write.

---------------------------------------------------------------

    *** Important information about changes to the ***
    *** Hercules configuration files - PLEASE READ ***

Hercules release version 3.00, however, [temporarily] changed
the rules: With [ONLY!] version 3.00 of Hercules, only the FIRST
address address need be specified in the configuration file.
Hercules version 3.00 automatically creates the second address.
Care must be taken to NOT define the second address [with Hercules
version 3.00 ONLY!] or a configuration error will occur.

---------------------------------------------------------------

    *** Important information about changes to the ***
    *** Hercules configuration files - PLEASE READ ***

Starting with Hercules version 3.01 however, we've gone back to
doing things the way we ORIGINALLY were (and the way most users
are used to (i.e. the way most users EXPECT things to work)):

With Hercules version 3.01 you need to define BOTH addresses!

Both the even numbered read device AS WELL AS the odd numbered
write device must BOTH be defined in your Hercules configuration
file starting with Hercules version 3.01. We apologize for the
mess, but we thought having Herc automatically define the write
device for you (as it does in version 3.00) would be easier for
everyone. Turns out it caused a lot of problems with a lot of
people, so we decided to go back to the original way. Again, we
apologize for whatever headaches this may have caused anyone.

---------------------------------------------------------------

    *** Important information about changes to the ***
    *** Hercules configuration files - PLEASE READ ***

Note that the VMNET and CTCT protocols have ALWAYS required BOTH
addresses to be defined (i.e. ALL versions of Hercules, including
version 3.00 as well, require BOTH even/odd read/write devices to
be defined separately [in your Hercules configuration file]).

---------------------------------------------------------------

The currently supported emulation modes are:

     CTCT     - CTCA Emulation via TCP connection
     CTCE     - Enhanced CTCA Emulation via CTP connection
     CTCI     - Point-to-point connection to the host IP stack.
     LCS      - LAN Channel Station (3172/OSA)
     VMNET    - Point-to-point link via SLIP/VMNET

-----------------------------------------------------------------
CTCT - Channel to Channel Emulation via TCP connection
-----------------------------------------------------------------

This emulation mode provides protocol-independent communication
with another instance of this driver via a TCP connection.

This mode appears to the operating system running in the Hercules
machine as an IBM 3088 Channel to Channel Adapter and can operate
in either Basic or Extended mode.

The configuration statement for CTCT is as follows:

     <devnum> 3088 CTCT <lport> <raddress> <rport> <mtu>

where:

     <devnum>   is the address of the CTCT device.

     <lport>    is the TCP/IP port on the local system.

     <raddress> is the IP address on the remote.

     <rport>    is the TCP/IP port on the remote system.

-----------------------------------------------------------------
CTCI     - Channel to Channel link to Linux TCP/IP stack
-----------------------------------------------------------------

This is a point-to-point link to the driving system's TCP/IP
stack. From the point of view of the operating system running
in the Hercules machine it appears to be a CTC link to a machine
running TCP/IP for MVS or VM.

CTCI uses the Universal TUN/TAP driver on *nix and Politecnico
di Torino's WinPCap packet driver as well as Fish's TunTap32
and FishPack DLLs on Windows[1].

The configuration statement for CTCI is as follows:

     <devnum1-devnum2> CTCI [options] <guestip> <hostip>

where:

     <devnum1-devnum2>   is the address pair of the CTCI device.

     <guestip>  is the IP address of the Hercules (guest OS) side.

     <hostip>   is the IP address on the driving system.

     [options]  can be any of the following:

         -n <devname> or --dev <devname>

             where <devname> is:

             [*nix] the name of the TUN/TAP special character
             device, normally /dev/net/tun.

             [Windows] is either the IP or MAC address of the
             driving systems network card. TunTap32 will
             automatically select the first network card it
             finds if this option is omitted, this may not be
             desirable for some users.

         -t <mtu> or --mtu <mtu>

             [*nix only] where <mtu> is the maximum transmission
             unit size, normally 1500

         -s <netmask> or --netmask <netmask>

             [*nix only] where <netmask> is the netmask to
             be configured on the link. Note: Since this is a
             point-to-point link netmask is meaningless from
             the perspective of the actual network device.

         -m <MAC Address> or --mac <MAC address>

             [Windows only] where <MAC Address> is the optional
             hardware address of the interface in the format of
             either xx:xx:xx:xx:xx:xx or xx-xx-xx-xx-xx-xx.

         -k <kbuff> or --kbuff <kbuff>

             [Windows only] where <kbuff> is the size of the
             WinPCap kernel buffer size, normally 1024.

         -i <ibuff> or --ibuff <ibuff>

             [Windows only] where <ibuff> is the size of the
             WinPCap I/O buffer size, normally 64.

         -d or --debug

             this will turn on the internal debugging routines.
             Warning: This will produce a tremendous amount of
             output to the Hercules console. It is suggested that
             you only enable this at the request of the maintainers.

-----------------------------------------------------------------
LCS - LAN Channel Station
-----------------------------------------------------------------

This emulation mode appears to the operating system running in
the Hercules machine as an IBM 8232 LCS device, an IBM 2216
router, a 3172 running ICP (Interconnect Communications Program),
the LCS3172 driver of a P/390, or an IBM Open Systems Adapter.

Rather than a point-to-point link, this emulation creates a
virtual ethernet adapter through which the guest operating system
running in the Hercules machine can communicate. As such, this
mode is not limited to TCP/IP traffic, but in fact will handle
any ethernet frame.

The configuration statement for LCS is as follows:

     <devnum1-devnum2> LCS [options] [<guestip>]

where:

     <devnum1-devnum2>   is the address pair of the LCS device.
                This pair must be an even-odd address.

     [<guestip>] is an optional IP address of the Hercules
                (guest OS) side. Note: This is only used to
                establish a point-to-point routing table entry
                on driving system. If you use the --oat option,
                do not specify an address here.

There are no required parameters for the LCS emulation, however
there are several options that can be specified on the config
statement:

     -n <devname> or --dev <devname>

         where <devname> is:

         [*nix] the name of the TUN/TAP special character device,
         normally /dev/net/tun.

         [Windows] is either the IP or MAC address of the driving
         systems network card. TunTap32 will automatically select
         the first network card it finds if this option is
         omitted, this may not be desirable for some users.

     -o <filename> or --oat <filename>

         where <filename> specifies the filename of the Address
         Translation file. If this option is specified, the optional
         <guestip> and --mac entries are ignored in preference to
         statements in the OAT. (See below for the format of the OAT)

     -m <MAC Address> or --mac <MAC address>

         where <MAC Address> is the optional hardware address of
         the interface in the format: xx:xx:xx:xx:xx:xx

     -d or --debug

         this will turn on the internal debugging routines.
         Warning: This will produce a tremendous amount of
         output to the Hercules console. It is suggested that
         you only enable this at the request of the maintainers.


If no Address Translation file is specified, the emulation module
will create the following:

     An ethernet adapter (port 0) for TCP/IP traffic only.
     Two device addresses will be defined (devnum and devnum + 1).


The syntax for the Address Translation file is as follows:

*********************************************************
* Dev Mode Port Entry specific information              *
*********************************************************
  0400  IP   00  PRI 172.021.003.032
  0402  IP   00  SEC 172.021.003.033
  0404  IP   00  NO  172.021.003.038
  0406  IP   01  NO  172.021.002.016
  040E  SNA  00

  HWADD 00 02:00:FE:DF:00:42
  HWADD 01 02:00:FE:DF:00:43
  ROUTE 00 172.021.003.032 255.255.255.224

where:

     Dev   is the base device address
     Mode  is the operation mode - IP or SNA
     Port  is the virtual (relative) adapter number.

When the device is specifies the odd address of the pair,
then the read/write functions of the pair will be swapped.

For IP modes, the entry specific information is as follows:

     PRI|SEC|NO  specifies where a packet with an unknown IP
                 address is forwarded to. PRI is the primary
                 default entry, SEC specifies the entry to use
                 when the primary is not available, and NO
                 specifies that this is not a default entry.

     nnn.nnn.nnn.nnn specifies the home IP address

When the operation mode is IP, specify only the even (read)
address. The odd (write) address will be create automatically.

Note: SNA mode does not currently work.

Additionally, two other statements can be included in the
address translation file. The HWADD and ROUTE statements.

Use the HWADD to specify a hardware (MAC) address for a
virtual adapter. The first parameter after HWADD specifies
with relative adapter for which the address is applied.

The ROUTE statement is included for convenience. This allows the
hercifc program to create a network route for this specified
virtual adapter. Please note that it is not necessary to include
point-to-point routes for each IP address in the table. This is
done automatically by the emulation module.

Up to 4 virtual (relative) adapters 00-03 are currently supported.

-----------------------------------------------------------------
SLIP/VMNET  - Channel to Channel link to TCP/IP via SLIP/VMNET
-----------------------------------------------------------------

If the emulation mode is not specified on the configuration
statement, it is assumed to be a point-to-point link to the
driving system's TCP/IP stack using Willem Konynenberg's VMNET
package.  This provides the same function as the CTCI mode of
operation, except that it uses a virtual SLIP interface instead
of the TUN/TAP driver.

Refer to http://www.kiyoinc.com/herc3088.html for more details.

-----------------------------------------------------------------
CTCE - Enhanced Channel to Channel Emulation via TCP connection
-----------------------------------------------------------------

The CTCE device type will emulate a real 3088 Channel to Channnel
Adapter also for non-IP traffic, enhancing the CTCT capabilities.
CTCE connections are also based on TCP/IP between two (or more)
Hercules instances, and requires an even-odd pair of port numbers
per device side. Only the even port numbers are to be configured;
the odd numbers are just derived by adding 1 to the (configured)
even port numbers.  The socket connection pairs cross-connect,
the arrows showing the send->receive direction :

   x-lport-even -> y-rport-odd
   x-lport-odd  <- y-rport-even

The configuration statement for CTCE is as follows :

     <devnum> CTCE <lport> <raddress> <rport> [[<mtu>] <sml>]

where:

     <devnum>   is the address of the CTCT device.

     <lport>    is the even TCP/IP port on the local system.

     <raddress> is the IP address on the remote.

     <rport>    is the even TCP/IP port on the remote system.

     <mtu>      optional mtu buffersize, defaults to 32778

     <sml>      optional small minimum for mtu, defaults to 8

A sample CTCE device configuration is shown below:

   Hercules PC Host A with IP address 192.168.1.100 :

      0E40  CTCE  30880  192.168.1.200  30880
      0E41  CTCE  30882  192.168.1.200  30882

   Hercules PC Host B with IP address 192.168.1.200 :

      0E40  CTCE  30880  192.168.1.100  30880
      0E41  CTCE  30882  192.168.1.100  30882

CTCE connected Hercules instances can be hosted on either Unix
or Windows platforms, both sides do not need to be the same.



=================================================================
[1] The TunTap32.dll and FishPack.dll are part of Fish's CTCI-W32
http://www.softdevlabs.com/Hercules/ctci-w32-index.html
package, but the required WinPCap packet driver must be installed
separately from http://www.winpcap.org  See Fish's web page for
details.

ALSO NOTE that it is HIGHLY RECOMMENDED that you stick with using
only the current RELEASE version of WinPCap and NOT any type of
'alpha' OR 'beta' version! Alpha and Beta versions of WinPCap are
NOT SUPPORTED! Only official *release* version are supported!

When you visit the WinPCap download web page, you need need to
scroll down the page a bit to reach the OFFICIAL RELEASE VERSION
of WinPcap. They usually put their Beta versions at the top of the
page, and BETA versions ARE NOT SUPPORTED. *Please* scroll down
the page and use and official RELEASE version. Thanks.

You may, if you want, use a beta version of WinPCap, but if you do,
then you're on your own if you have any problems with it.

  -- Fish, May 2004.

(The previous contents of this file were removed, as they haven't applied in
years.)

To compile on OS X for another architecture than the one running, or another
OS version, you have to supply several arguments to the configure command.

To force a particular architecture, you need to specify the machine
architecture to the gcc command with the "-arch <architecture>" operand. You
also need to tell configure what environment you're building for, with
--host.

ARCHITECTURE    -arch   --host
32-bit Intel    i386    i686
64-bit Intel    x86_64  x86_64
32-bit PowerPC  ppc     powerpc
64-bit PowerPC  ppc64   powerpc64

The argument for --host is the first part of a build triplet, specified as
<architecture>-<vendor>-<OS>. The vendor is apple for all OS X builds. OS is
"darwin8.8.0" for OS X 10.4 (Tiger), and "darwin9.6.0" for OS X 10.5
(Leopard). This makes, for example, building for 64-bit Intel on Leopard use
"--host x86_64-apple-darwin9.6.0". The -arch argument is specified by
overriding the CC (C compiler) value and adding it to the end, as in CC="gcc
-arch x86_64".

If you're building for an OS that's not the one you're running on, you also
need to tell the build environment that you're doing so. For building for
Tiger on Leopard, you need to add two arguments to the configure
invocation: "CFLAGS='-isysroot /Developer/SDKs/MacOSX10.4u.sdk'
LDFLAGS='-isysroot/Developer/SDKs/MacOSX10.4u.sdk
-Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk'". (All on one line, of
course.) You also need to add an environment variable that's passed to gcc
upon invocation, and this takes adding it to the beginning of the CC value,
as in CC="/usr/bin/env MACOSX_DEPLOYMENT_TARGET=10.4 gcc -arch ix86_64".

This makes a complete invocation for building for 32-bit Intel for Tiger on
Leopard (again, all on one line):

CC="/usr/bin/env MACOSX_DEPLOYMENT_TARGET=10.4 gcc -arch i386"
CFLAGS='-isysroot /Developer/SDKs/MacOSX10.4u.sdk' LDFLAGS='-isysroot
/Developer/SDKs/MacOSX10.4u.sdk
-Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk' ./configure
--enable-setuid-hercifc --host=i686-apple-darwin8.8.0

Building 32-bit Intel for Leopard on Leopard is easier:

CC="gcc -arch i386" ./configure --enable-setuid-hercifc
--host=i686-apple-darwin9.6.0

(Note that building a 64-bit Intel version on a Mac with a 64-bit Intel
processor still requires explicitly setting the architecture. If you don't,
you'll get a 32-bit Intel version.)

Once you have the various architectures built, you can combine them into one
binary with lipo. This is done by saying "lipo <input-files> -output
<output-file> -create". The best approach is to automate this with a shell
script; I've done this for my own use.

HOW TO BUILD HERCULES FROM SVN UNDER SOLARIS

1. DOWNLOAD AND INSTALL THE GNU COMPILER AND TOOLS

  (a) You can obtain all the required tools from
      http://www.sunfreeware.com

      To download the tools you will need wget which is
      installed in /usr/sfw/bin on Solaris 9 and 10.

      First add this directory to your path using the command:
      PATH=${PATH}:/usr/sfw/bin

  (b) Follow instructions on http://www.blastwave.org/pkg-get.php
      to install the pkg-get package.
      Choose /opt/csw as the package base directory.

      Choose a local mirror site from the list at
      http://www.blastwave.org/mirrors.html
      and update /opt/csw/etc/pkg-get.conf to point to the /stable
      directory at the mirror site, for example:
      url=http://blastwave.informatik.uni-erlangen.de/csw/stable

      Add /opt/csw/bin to your path using the command:
      PATH=/opt/csw/bin:${PATH}

  (c) Then install the GNU compiler and tools using these commands:

      pkg-get install textutils
      pkg-get install automake
      pkg-get install autoconf
      pkg-get install subversion
      pkg-get install flex
      pkg-get install gmake
      pkg-get install ggrep
      pkg-get install gcc3

  (d) Check that all the required tools are installed:

      pkg-get compare subversion autoconf automake flex gawk gcc3
      pkg-get compare ggrep libiconv gm4 gmake perl gsed

      which should produce output something like this:

       software                    localrev                   remoterev
     subversion        1.4.5,REV=2007.11.18                        SAME
       autoconf         2.61,REV=2007.07.13                        SAME
       automake                       1.9.6                        SAME
           flex        2.5.4,REV=2005.10.03                        SAME
           gawk                       3.1.5                        SAME
           gcc3                       3.4.5                        SAME
          ggrep          2.5,REV=2004.12.01                        SAME
       libiconv                       1.9.2                        SAME
            gm4        1.4.5,REV=2006.07.27                        SAME
          gmake                        3.81                        SAME
           perl        5.8.8,REV=2007.10.05                        SAME
           gsed                       4.1.4                        SAME

  (e) Finally, add symbolic links to allow certain GNU tools to be
      invoked using standard Unix names:

      cd /opt/csw/bin
      ln -s /opt/csw/gcc3/bin/gcc gcc
      ln -s /opt/csw/bin/ggrep grep
      ln -s /opt/csw/bin/gm4 m4
      ln -s /opt/csw/bin/gmake make
      ln -s /opt/csw/bin/gsed sed

2. DOWNLOAD THE HERCULES SOURCE FROM SVN

      Add the following line to your .profile file:
      PATH=/opt/csw/bin:${PATH}

      From your home directory issue this command:

      svn checkout svn://svn.hercules-390.org/hercules/trunk hercules

      Note: svn will fail if you do not have libuuid installed on your system
      ld.so.1: svn: fatal: libuuid.so.1: open failed: No such file or directory

      If you get this message, you will need to install a patch from Sun:
      1. Go to sunsolve.sun.com and select "Patch Finder"
      2. Scroll down to "Download Product Specific Patches" and select your
         version of Solaris (for example, Solaris 2.9 SPARC)
      3. Look for a patch which contains libuuid (for example, 114129-02)
      4. Download the patch and unzip it into /var/spool/patch
      5. patchadd /var/spool/patch/114129-02

3. CHECK THAT THE REQUIRED LEVELS OF TOOLS ARE INSTALLED

      From your home directory issue these commands:

      cd hercules
      util/bldlvlck

      which should produce output something like this:

       OK      SVN (informational), found x.yy.zz
       OK      autoconf requires 2.5, found 2.61
       OK      automake requires 1.9, found 1.9.6
       OK      flex requires 2.5, found 2.5.4
       OK      gawk requires 3.0, found 3.1.5
       OK      gcc requires 2.95, found 3.4.5
       OK      grep requires 0, found 2.5
       OK      libiconv requires 1.8, found 1.9
       OK      m4 requires 0.0, found 1.4
       OK      make requires 3.79, found 3.81
       OK      perl requires 5.6, found 5.8.8
       OK      sed requires 3.02, found 4.1.4

4. BUILD HERCULES

      In the hercules directory issue these commands:

      sh ./autogen.sh
      ./configure
      make

-------------------------------------------------------------------------------
*        Hercules Tape Support Enhancements SPE/Fixes                         *
*        V1.0 - By Ivan S. Warren                                             *
-------------------------------------------------------------------------------

0 - Version History
    * 08 Mar 2003 : ISW : Initial Release

I - Supported Device Type emulations :

Device Types supported as of yet :
3410/3411, 3420, 3480, 3490, 9347
Upcoming Device type support :
3422, 3424, 3490E, 3590, 3430, 8809

II - Basic ACF support

The ACF (Automatic Cartridge Feeder) is a feature on Cartridge type tape
drives (3480, 3490, etc..) that automatically loads a new tape when a tape
is removed from the drive. There is no real control over this device by the
host, as it just keeps on feeding tapes one after the other.
Although the ACF feature is unique to cartridge type systems, the emulation
accepts to use the same technique for emulated 1/2 inch tapes reel drives
as well.

ACF is supported as follows :

hercules.cnf syntax :
CUU DEVT @filename <options..>
devinit syntax :
devinit CUU @filename <options..>

the 'filename' (without the prefixing @) contains a list of files that will
be loaded one after the other. The filenames contained in the file list cannot
describe another ACF file nor an SCSI tape handle (/dev/stX). However, the
files may be standard AWS, HET or OMA files.

To manually reset the ACF to the top of the stack, the devinit can be used
to 'reload' the ACF feature.

If the filename in the ACF description file contains a '*', any option(s) that
follow(s) the '*' (is)are applied to each file, followed by the option(s)
specified on the devinit or hercules.cnf entry, followed by the option(s)
specified on each individual entry.

Example :

hercules.cnf:
180 3420 @newstack compress=1

newstack:
# Sample file
* maxsizeM=16 eotmargin=131072
tape01.aws compress=0
tape02.het maxsizeM=32 eotmargin=65536
tape03.het maxsize=0

This is equivalent to issuing (one at the start and one after each tape unload
event)

180 3420 tape01.aws maxsizeM=16 eotmargin=131072 compress=1 compress=0
devinit 180 tape02.het maxsizeM=16 eotmargin=131072 compress=1 maxsizeM=32 eotmargin=65536
devinit 180 tape03.het maxsizeM=16 eotmargin=131072 compress=1 maxsize=0

Options are processed in the order in which they appear.
Any conflicting parameter overrides the previous one.
For example, on the 1st entry, the resuling "compress" will be 0.

Care must be taken that '*' line entries are all proecessed at once.
For example :

* compress=0
tape01.aws
* compress=1
tape02.aws

is EQUIVALENT to

* compress=0 compress=1
tape01.aws
tape02.aws

NOTE : This may change in the future though, so ACF description files should not rely on this feature.

III - Multivolume support - End of tape indication, Tape file size limitation

Numerous requests have been made in order to support multi-volume tape
handling, as well as limiting the file size generated by any individual
tape file.

Because multivolume support is not necesserally VOL1-HDR1/EOV/EOF based,
a certain number of new features have to be implemented in order to let
the guest program manage the multivolume on it's own.
(ex: VM/DDR, DOS Tape Spooled output, etc..)

Multivolume support resides in the capacity of a drive to indicate to the
controling program that it is about to reach the end of the physical tape
and that measures have to be taken to close the current volume and
request a new media.

3 new options are introduced :
maxsize[K|M]=nnnn :
        The resulting file size is limited to the amount specified. maxsize
        specifies bytes, maxsizeK specifies a multiple of 10$24 bytes and
        maxsizeM specifies a multiple of 1024*1024 bytes. specifying a size
        of 0 indicates that there is no limit on the size of the file.

        the default is 0 (unlimited file size)

strictsize=0|1 :
        Upon reaching the tape file size limit, depending on strictsize,
        the tape file will or will not be truncated to enforce the maxsize
        limit. The limit is only enforced during a write type operation
        (that is : if the file already exists and the program only reads
        the file, then the file will NOT be truncated, regardless of the
        strictsize setting).
        This affects any write that starts BELOW the limit, but that would
        extend BEYOND the limit.
        This parameter only affects compress HET files. On AWS tapes, the
        limit is always enforced, but the file is not truncated (i.e. the
        write does not occur, because 1) AWS tapes are never truncated, 2)
        the effects of the write are known in advance (no compression)).
        Regardless of strictsize, any write operation (Write, Write TM)
        will return a Unit Check with Equip Check to the program if the file
        size exceeds the predefined limit. If strictsize is 0, the write will
        actually have been performed on the tape file. If strictsize is 1,
        the file will be truncated on the preceeding tape block boundary.
        If an attempt is made to write beyond the maxsize li

        Care must be taken that regardless of the 'strictsize' setting,
        the tape may become unusable for the guest program should such an
        event occur (absence of a Tape Mark for example).

        This option has no effect if maxsize is 0
        This option only affects HET file tapes
        The default is 0 (do not truncate)

eotmargin=nnnn :
        This option specifies, in bytes, the threshold before reaching maxsize
        during which an indication will be returned to the program to indicate
        that an EOT marker has been reached for a write type operation.
        The indication of reaching near-capacity is indicated to the program
        by presenting Unit Exception in the CSW on a Write type operation,
        along with Channel End and Device End.
        For certain device types, sense information may also indicate this
        information independently of a write operation.
        The purpose of this option is to allow the program to determine that
        it is time to change to ask for a new tape. For example :

        maxsizeM=2 eotmargin=131072
        all writes up to 2Mb - 128Kb will occur normally
        All writes between 2Mb-128Kb and 2Mb will receive Unit Exception
        All writes beyond 2Mb will receive Unit Check

        This option has no effect if maxsize is 0
        The default is 131072 (128Kb)

Caveats :

If the emulated tape file resides on a disk media that reaches full capacity
before the tape image exceeds it's size limit, the tape emulation will not
detect that situation and will simulate reaching physical end of tape BEFORE
reaching the EOT marker.
This behaviour may be changed at a later time.

IV - Various other changes / Corrections

IV.1 : Device End Suppression for Tape motion CCWs on a non-ready tape drive

IV.2 : Control Unit End is presented on Rewind Unload status

IV.3 : Sense Pending status support
        When certain conditions arise during an I/O operation, A sense is
        built and Unit Check is presented to the program.
        The program is then responsible for retrieving the sense information.
        However, if the sense is not the result of a previously occuring
        Unit Check, a new sense is built to reflect the current device status.
        Also, this management is a necessary step in order to eventually
        implement multipath operations (Contengency Allegiance status).

IV.4 : readonly=0|1 :
        force an emulated tape device read only.
        (1/2 Inch tape ring or 38k Cartridge Protect tab)
        (support for this feature is incomplete)


--Ivan

8 Mar 2003

-------------------------------------------------------------------------------
*                          AUTOMOUNT support                                  *
-------------------------------------------------------------------------------

Starting with Hercules version 3.06 a new AUTOMOUNT option is available
that allows guest operating systems to directly mount, unmount and query
tape device filenames for themselves, without any intervention on the part
of the Hercules operator.

Automount support is enabled via the AUTOMOUNT configuration file statement.

An example guest automount program for VSE called "TMOUNT" is provided in
the util subdirectory of the Hercules source code distribution.

Briefly, the 0x4B (Set Diagnose) CCW is used to mount (or unmount) a file
onto a tape drive, and the 0xE4 (Sense Id) CCW opcode is used to query the
name of the currently mounted file.

For mounts, the 0x4B CCW specifies the filename of the file to be mounted
onto the drive. The file MUST reside in the specified AUTOMOUNT directory
or the automount request will be rejected. To unmount the currently mounted
file, simply do a mount of the special filename "OFFLINE".

To query the name of the currently mounted file, the 0xE4 CCW is used. Note
however that the 0xE4 (Sense Id) CCW opcode cannot be used by itself since
the drive may also already natively support the Sense Id CCW opcode. Instead,
it must be preceded by (command-chained from) a 0x4B CCW with a data transfer
length of one byte. The following 0xE4 command is the one that then specifies
the i/o buffer and buffer length of where the query function is to place the
device's currently mounted host filename.

In summary:


    MOUNT:      X'4B', <filename>, X'20', <length>

    UNMOUNT:    (same thing but use filename "OFFLINE" instead)

    QUERY:      X'4B', <buffer>, X'60', 1
                X'E4', <buffer>, X'20', <buffersize>


Again, please refer to the provided TMOUNT sample for a simple example.


-- Fish
28 May 2008

HERCULES FOR WIN32 README FILE

HOW TO COMPILE HERCULES FOR WINDOWS 32 BIT MSVC x86

1. Install Visual C++ 2010 Express from the Visual Studio 2010 Express page:
   http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express

2. Install Visual Studio 2010 Service Pack 1 (VS10sp1-KB983509) from:
   http://www.microsoft.com/en-us/download/details.aspx?id=23691

3. Go to the start menu and choose "All Programs"
   - "Microsoft Visual Studio 2010 Express" - "Visual Studio Command Prompt (2010)"

4. Change to the directory where you unpacked the Hercules source

5. If you require gzip or bzip2 for disk or tape compression, or if you
   require PCRE for the Hercules Automatic Operator facility, you should
   install the WIN32 versions of these programs in winbuild\zlib\
   winbuild\bzip2\ and winbuild\pcre\ under the Hercules directory.
   You may override these default directory locations by setting
   environment variables, for example:
   SET ZLIB_DIR=c:\packages\zlib
   SET BZIP2_DIR=c:\packages\bzip2
   SET PCRE_DIR=c:\packages\pcre

6. copy makefile.msvc makefile

7. nmake clean
   nmake

8. The binaries will be installed into subfolder "msvc.dllmod.bin"

9. If you copy the binaries to a machine which does not have Visual
   Studio 2010 (VS10) installed, then you must also install the
   Microsoft Visual C++ 2010 Redistributable Package (x86)
   on the target machine. This package can be downloaded from
   http://www.microsoft.com/en-us/download/details.aspx?id=5555

HERCULES FOR WIN64 README FILE

There are two 64-bit architectures supported by 64-bit Windows:
- x64 also known as x86_64 (for AMD64 and Intel EM64T processors)
- ia64 (for Intel Itanium processors)

This document covers only the x64 architecture.

HOW TO COMPILE HERCULES FOR AMD64

1. Install Visual C++ 2010 Express from the Visual Studio 2010 Express page:
   http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express

2. Install Microsoft Windows SDK 7.1 from:
   http://www.microsoft.com/en-us/download/details.aspx?id=8279
   IMPORTANT: select all components *except* the Visual C++ Compilers

3. Install Visual Studio 2010 Service Pack 1 (VS10sp1-KB983509) from:
   http://www.microsoft.com/en-us/download/details.aspx?id=23691

4. Install Visual C++ 2010 Service Pack 1 Compiler Update
   for the Windows SDK 7.1 (VC-Compiler-KB2519277) from:
   http://www.microsoft.com/en-us/download/details.aspx?id=4422

5. Go to the start menu and choose "All Programs"
   - "Microsoft Windows SDK v7.1" - "Microsoft Windows SDK 7.1 Command Prompt"

6. Change to the directory where you unpacked the Hercules source

7. If you require gzip or bzip2 for disk or tape compression, or if you
   require PCRE for the Hercules Automatic Operator facility, you should
   install the AMD64 versions of these programs in winbuild\zlib\x64
   winbuild\bzip2\x64 and winbuild\pcre\x64 under the Hercules directory.
   You may override these default directory locations by setting
   environment variables, for example:
   SET ZLIB_DIR=c:\packages\zlib
   SET BZIP2_DIR=c:\packages\bzip2
   SET PCRE_DIR=c:\packages\pcre

8. copy makefile.msvc makefile

9. nmake clean
   nmake

10. The binaries will be installed into subfolder "msvc.AMD64.bin"
   If you compiled on a 32-bit Windows system, copy this folder
   to your target 64-bit Windows machine.

11. If you copy the binaries to a machine which does not have Visual
   Studio 2010 (VS10) installed, then you must also install the
   Microsoft Visual C++ 2010 Redistributable Package (x64)
   on the target machine. This package can be downloaded from
   http://www.microsoft.com/en-us/download/details.aspx?id=14632