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