1-------------------------------------------------------------------------------
2*        Hercules Tape Support Enhancements SPE/Fixes                         *
3*        V1.0 - By Ivan S. Warren                                             *
4-------------------------------------------------------------------------------
5
60 - Version History
7    * 08 Mar 2003 : ISW : Initial Release
8
9I - Supported Device Type emulations :
10
11Device Types supported as of yet :
123410/3411, 3420, 3480, 3490, 9347
13Upcoming Device type support :
143422, 3424, 3490E, 3590, 3430, 8809
15
16II - Basic ACF support
17
18The ACF (Automatic Cartridge Feeder) is a feature on Cartridge type tape
19drives (3480, 3490, etc..) that automatically loads a new tape when a tape
20is removed from the drive. There is no real control over this device by the
21host, as it just keeps on feeding tapes one after the other.
22Although the ACF feature is unique to cartridge type systems, the emulation
23accepts to use the same technique for emulated 1/2 inch tapes reel drives
24as well.
25
26ACF is supported as follows :
27
28hercules.cnf syntax :
29CUU DEVT @filename <options..>
30devinit syntax :
31devinit CUU @filename <options..>
32
33the 'filename' (without the prefixing @) contains a list of files that will
34be loaded one after the other. The filenames contained in the file list cannot
35describe another ACF file nor an SCSI tape handle (/dev/stX). However, the
36files may be standard AWS, HET or OMA files.
37
38To manually reset the ACF to the top of the stack, the devinit can be used
39to 'reload' the ACF feature.
40
41If the filename in the ACF description file contains a '*', any option(s) that
42follow(s) the '*' (is)are applied to each file, followed by the option(s)
43specified on the devinit or hercules.cnf entry, followed by the option(s)
44specified on each individual entry.
45
46Example :
47
48hercules.cnf:
49180 3420 @newstack compress=1
50
51newstack:
52# Sample file
53* maxsizeM=16 eotmargin=131072
54tape01.aws compress=0
55tape02.het maxsizeM=32 eotmargin=65536
56tape03.het maxsize=0
57
58This is equivalent to issuing (one at the start and one after each tape unload
59event)
60
61180 3420 tape01.aws maxsizeM=16 eotmargin=131072 compress=1 compress=0
62devinit 180 tape02.het maxsizeM=16 eotmargin=131072 compress=1 maxsizeM=32 eotmargin=65536
63devinit 180 tape03.het maxsizeM=16 eotmargin=131072 compress=1 maxsize=0
64
65Options are processed in the order in which they appear.
66Any conflicting parameter overrides the previous one.
67For example, on the 1st entry, the resuling "compress" will be 0.
68
69Care must be taken that '*' line entries are all proecessed at once.
70For example :
71
72* compress=0
73tape01.aws
74* compress=1
75tape02.aws
76
77is EQUIVALENT to
78
79* compress=0 compress=1
80tape01.aws
81tape02.aws
82
83NOTE : This may change in the future though, so ACF description files should not rely on this feature.
84
85III - Multivolume support - End of tape indication, Tape file size limitation
86
87Numerous requests have been made in order to support multi-volume tape
88handling, as well as limiting the file size generated by any individual
89tape file.
90
91Because multivolume support is not necesserally VOL1-HDR1/EOV/EOF based,
92a certain number of new features have to be implemented in order to let
93the guest program manage the multivolume on it's own.
94(ex: VM/DDR, DOS Tape Spooled output, etc..)
95
96Multivolume support resides in the capacity of a drive to indicate to the
97controling program that it is about to reach the end of the physical tape
98and that measures have to be taken to close the current volume and
99request a new media.
100
1013 new options are introduced :
102maxsize[K|M]=nnnn :
103        The resulting file size is limited to the amount specified. maxsize
104        specifies bytes, maxsizeK specifies a multiple of 10$24 bytes and
105        maxsizeM specifies a multiple of 1024*1024 bytes. specifying a size
106        of 0 indicates that there is no limit on the size of the file.
107
108        the default is 0 (unlimited file size)
109
110strictsize=0|1 :
111        Upon reaching the tape file size limit, depending on strictsize,
112        the tape file will or will not be truncated to enforce the maxsize
113        limit. The limit is only enforced during a write type operation
114        (that is : if the file already exists and the program only reads
115        the file, then the file will NOT be truncated, regardless of the
116        strictsize setting).
117        This affects any write that starts BELOW the limit, but that would
118        extend BEYOND the limit.
119        This parameter only affects compress HET files. On AWS tapes, the
120        limit is always enforced, but the file is not truncated (i.e. the
121        write does not occur, because 1) AWS tapes are never truncated, 2)
122        the effects of the write are known in advance (no compression)).
123        Regardless of strictsize, any write operation (Write, Write TM)
124        will return a Unit Check with Equip Check to the program if the file
125        size exceeds the predefined limit. If strictsize is 0, the write will
126        actually have been performed on the tape file. If strictsize is 1,
127        the file will be truncated on the preceeding tape block boundary.
128        If an attempt is made to write beyond the maxsize li
129
130        Care must be taken that regardless of the 'strictsize' setting,
131        the tape may become unusable for the guest program should such an
132        event occur (absence of a Tape Mark for example).
133
134        This option has no effect if maxsize is 0
135        This option only affects HET file tapes
136        The default is 0 (do not truncate)
137
138eotmargin=nnnn :
139        This option specifies, in bytes, the threshold before reaching maxsize
140        during which an indication will be returned to the program to indicate
141        that an EOT marker has been reached for a write type operation.
142        The indication of reaching near-capacity is indicated to the program
143        by presenting Unit Exception in the CSW on a Write type operation,
144        along with Channel End and Device End.
145        For certain device types, sense information may also indicate this
146        information independently of a write operation.
147        The purpose of this option is to allow the program to determine that
148        it is time to change to ask for a new tape. For example :
149
150        maxsizeM=2 eotmargin=131072
151        all writes up to 2Mb - 128Kb will occur normally
152        All writes between 2Mb-128Kb and 2Mb will receive Unit Exception
153        All writes beyond 2Mb will receive Unit Check
154
155        This option has no effect if maxsize is 0
156        The default is 131072 (128Kb)
157
158Caveats :
159
160If the emulated tape file resides on a disk media that reaches full capacity
161before the tape image exceeds it's size limit, the tape emulation will not
162detect that situation and will simulate reaching physical end of tape BEFORE
163reaching the EOT marker.
164This behaviour may be changed at a later time.
165
166IV - Various other changes / Corrections
167
168IV.1 : Device End Suppression for Tape motion CCWs on a non-ready tape drive
169
170IV.2 : Control Unit End is presented on Rewind Unload status
171
172IV.3 : Sense Pending status support
173        When certain conditions arise during an I/O operation, A sense is
174        built and Unit Check is presented to the program.
175        The program is then responsible for retrieving the sense information.
176        However, if the sense is not the result of a previously occuring
177        Unit Check, a new sense is built to reflect the current device status.
178        Also, this management is a necessary step in order to eventually
179        implement multipath operations (Contengency Allegiance status).
180
181IV.4 : readonly=0|1 :
182        force an emulated tape device read only.
183        (1/2 Inch tape ring or 38k Cartridge Protect tab)
184        (support for this feature is incomplete)
185
186
187--Ivan
188
1898 Mar 2003
190
191-------------------------------------------------------------------------------
192*                          AUTOMOUNT support                                  *
193-------------------------------------------------------------------------------
194
195Starting with Hercules version 3.06 a new AUTOMOUNT option is available
196that allows guest operating systems to directly mount, unmount and query
197tape device filenames for themselves, without any intervention on the part
198of the Hercules operator.
199
200Automount support is enabled via the AUTOMOUNT configuration file statement.
201
202An example guest automount program for VSE called "TMOUNT" is provided in
203the util subdirectory of the Hercules source code distribution.
204
205Briefly, the 0x4B (Set Diagnose) CCW is used to mount (or unmount) a file
206onto a tape drive, and the 0xE4 (Sense Id) CCW opcode is used to query the
207name of the currently mounted file.
208
209For mounts, the 0x4B CCW specifies the filename of the file to be mounted
210onto the drive. The file MUST reside in the specified AUTOMOUNT directory
211or the automount request will be rejected. To unmount the currently mounted
212file, simply do a mount of the special filename "OFFLINE".
213
214To query the name of the currently mounted file, the 0xE4 CCW is used. Note
215however that the 0xE4 (Sense Id) CCW opcode cannot be used by itself since
216the drive may also already natively support the Sense Id CCW opcode. Instead,
217it must be preceded by (command-chained from) a 0x4B CCW with a data transfer
218length of one byte. The following 0xE4 command is the one that then specifies
219the i/o buffer and buffer length of where the query function is to place the
220device's currently mounted host filename.
221
222In summary:
223
224
225    MOUNT:      X'4B', <filename>, X'20', <length>
226
227    UNMOUNT:    (same thing but use filename "OFFLINE" instead)
228
229    QUERY:      X'4B', <buffer>, X'60', 1
230                X'E4', <buffer>, X'20', <buffersize>
231
232
233Again, please refer to the provided TMOUNT sample for a simple example.
234
235
236-- Fish
23728 May 2008
238