forked from mtalexander/hercules-390
/
README.TAPE
288 lines (207 loc) · 11.3 KB
/
README.TAPE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
-------------------------------------------------------------------------------
* 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. Furthermore, the file MUST reside in one of the specified
AUTOMOUNT directories or the request will be rejected. To unmount a 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 already natively support the Sense Id CCW opcode. Instead, it
MUST be preceded by (command-chained from) a 0x4B CCW which specifies a data
transfer length of exactly one byte. The 0xE4 CCW which follows it specifies
the i/o buffer and buffer length of where the query function is to copy the
device's currently mounted host filename into. If the 0x4B Set Diagnose CCW
is not command chained, or if it is, if it does not specify a data-transfer
length of exactly one byte, then it is not recognized as a Automount Query
request and is instead treated as an Automount Mount/Dismount request.
As a result of this restriction, if the automount 0x4B Set Diagnose CCW is
chained, the filename must be at least two bytes or longer. To mount a one
byte filename, the 0x4B Set Diagnose CCW must *NOT* be chained:
--------------- The following works okay ---------------
ONECHAR DC C'Z' (one byte filename)
CCW X'4B',ONECHAR,X'20',L'ONECHAR (automount)
--------------- The following works okay ---------------
MYFILE DC C'MYTAPE.AWS' (normal filename)
CCW X'4B',MYFILE,X'20',L'MYFILE (automount)
--------------- The following works okay ---------------
MYFILE DC C'MYTAPE.AWS' (normal filename)
VOL1LBL DC CL80' '
CCW X'4B',MYFILE,X'60',L'MYFILE (automount)
CCW X'07',*,X'60',1 (rewind)
CCW X'02',VOL1LBL,X'60',L'VOL1LBL (read VOL1)
CCW X'07',*,X'20',1 (rewind)
--------------- The following will FAIL! ---------------
ONECHAR DC C'Z' (one byte filename)
VOL1LBL DC CL80' '
CCW X'4B',ONECHAR,X'60',L'ONECHAR (automount)
CCW X'07',*,X'60',1 (rewind)
CCW X'02',VOL1LBL,X'60',L'VOL1LBL (read VOL1)
CCW X'07',*,X'20',1 (rewind)
To summarize:
MOUNT: X'4B', <filename>, X'nn', <length>
...(other optional CCWS)...
UNMOUNT: (same thing but use filename "OFFLINE" instead)
QUERY: X'4B', <buffer>, X'nn', 1
X'E4', <buffer>, X'nn', <buffersize>
...(other optional CCWS)...
Again, please refer to the provided TMOUNT sample for a simple example.
-- Fish
28 May 2008
10 Jul 2011