-------------------------------------------------------------------------------
*        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