1------------------------------------------------------------------------------- 2 3 Version 3.08 RELEASE NOTES 4 5 6* The new minimum supported Microsoft Windows platform is now Windows XP or 7 greater. Windows 98, Windows NT and Windows 2000 are no longer supported. 8 9 10------------------------------------------------------------------------------- 11 12 13 Version 3.06 RELEASE NOTES 14 15 16* Tape "AUTOMOUNT" support 17 18 Starting with Hercules version 3.06 a new AUTOMOUNT option is available 19 that allows guest operating systems to directly mount, unmount and query 20 tape device filenames for themselves, without any intervention on the 21 part of the Hercules operator. 22 23 Automount support is enabled via the AUTOMOUNT configuration file statement. 24 25 An example guest automount program for VSE called "TMOUNT" is provided in 26 the util subdirectory of the Hercules source code distribution. 27 28 Briefly, the 0x4B (Set Diagnose) CCW is used to mount (or unmount) a file 29 onto a tape drive, and the 0xE4 (Sense Id) CCW opcode is used to query the 30 name of the currently mounted file. 31 32 For mounts, the 0x4B CCW specifies the filename of the file to be mounted 33 onto the drive. The file MUST reside in the specified AUTOMOUNT directory 34 or the automount request will be rejected. To unmount the currently mounted 35 file, simply do a mount of the special filename "OFFLINE". 36 37 To query the name of the currently mounted file, the 0xE4 CCW is used. Note 38 however that the 0xE4 (Sense Id) CCW opcode cannot be used by itself since 39 the drive may also already natively support the Sense Id CCW opcode. Instead, 40 it must be preceded by (command-chained from) a 0x4B CCW with a data transfer 41 length of one byte. The following 0xE4 command is the one that then specifies 42 the i/o buffer and buffer length of where the query function is to place the 43 device's currently mounted host filename. 44 45 In summary: 46 47 48 MOUNT: X'4B', <filename>, X'20', <length> 49 50 UNMOUNT: (same thing but use filename "OFFLINE" instead) 51 52 QUERY: X'4B', <buffer>, X'60', 1 53 X'E4', <buffer>, X'20', <buffersize> 54 55 56 Again please refer to the provided TMOUNT program for a simple example 57 of how automount support might be implmented on a guest operating system. 58 59------------------------------------------------------------------------------- 60 61 62 Version 3.05 RELEASE NOTES 63 64 65* The 'conspawn' utility used to process 'sh' commands now recognizes a 66 specially designed keyword "startgui" to accomodate automatic starting 67 of Windows GUI applications via the .RC file or panel command-line. 68 69 If the first word following 'sh' is "startgui", then the "ShellExecute" 70 API is used to start the requested program rather than the 'system()' 71 API as otherwise. This is to address an issue related to running Hercules 72 via the HercGUI graphical front end wherein programs started via the .RC 73 file would cause HercGUI to hang at PowerOff until all programs started 74 by Hercules (via the .RC file or panel command-line) were first closed. 75 76 If the program you wish to invoke via the 'sh' command is a command-line 77 program (that thus uses stdio to read from stdin and write to stdout) 78 then "startgui" should NOT be used. Instead, simply start the program 79 as before (e.g. "sh cmd /c myprog myargs..."). 80 81 If the application you wish to start is a normal Windows GUI application 82 however, then the "startgui" keyword should be used instead. For example, 83 to automatically start the Vista 3270 terminal emulator from your .RC file, 84 use: "sh startgui D:\Vista32\Vista32.exe Hercules.ses". 85 86 Again, this is only for starting Windows GUI programs and thus does not 87 impact non-GUI (command-line) programs nor, obviously, non-MSVC builds 88 of Hercules nor when Hercules is run via the command-line (in non-GUI mode). 89 This is only for the Window MSVC build of Hercules and only when Hercules 90 is started via HercGUI and only when starting a Windows GUI program via 91 the 'sh' command either via the panel command-line or the .RC file. (Note: 92 the panel command-line also includes commands entered via the http server 93 interface as well) 94 95 96* Real SCSI tape drives used with Hercules must provide a certain minimum set 97 is "IBM compatible" support in their SCSI command set/behavior in order to 98 work properly with Hercules. Furthermore, the Hercules device-type used on 99 your device statement in your Hercules configuration file should match the 100 the level of support/behavior that they provide. 101 102 For example, all SCSI tape drives used with Hercules must provide the ability 103 to set variable-length blocks as well as long erase-gaps (long erase-gaps 104 allows new data to be appended to the end of existing data without having to 105 write a tape-mark to separate the new data from the old existing data first). 106 107 Another example would be using a model of SCSI tape drive that happens to 108 report physical block-id values in a format different from the way real IBM 109 mainframe tape drives report them. 3480/3490 tape drives for example report 110 their block-ids (used in Read Block Id and Locate CCWs) in a very specific 111 format wherein bits 1-7 of the high-order byte of the reported 4-byte block- 112 id indicates the tape's physical "segment" location of where the lower 22- 113 bit block number is physically located on the tape. (The block-id segment 114 is used to allow the tape drive to quickly position itself to the approximate 115 location where the desired block acually resides on the tape and thus allows 116 high-speed positioning for the Locate CCW). 117 118 If the model of SCSI tape drive you are actually using with Hercules does not 119 use this same block-id format however, then it cannot be used with Hercules 120 as a 3480 or 3490 model tape drive with specially defined options. 121 122 If the SCSI tape drive you are using reports its block-ids using a 32-bit 123 block-id value (the same way a 3590 model tape drive does), then similarly, 124 it should be defined to Hercules as a model 3590 device-type as well (since 125 that is how it is behaving with respect the format of the returned blockid 126 values). It you wish to define it in Hercules as a model 3480 or 3490, then 127 you will need to use specially defined options before it will work properly 128 as the model drive you wish it to emulate. 129 130 With all that being said, it should be noted that PARTIAL support for 3590 131 device emulation is possible with judicious use the aforementioned special 132 options, but full/complete 3590 support is unlikely due to lack of publicly 133 available documentation. Details regarding 3590 CCW handling is restricted 134 (confidential) IBM proprietary information, and is not normally available 135 outside of IBM. Not long ago IBM was required by US law to publish such 136 information, but unfortunately for Hercules, such is no longer the case. 137 138 For further information regarding use of SCSI attached tape drives with 139 Hercules and their associated specially defined options, please refer to 140 the section on SCSI tape drives in the Hercules's Device Configuration 141 documentation. 142 143 144* In order to ensure proper functioning of the TOD clock with older versions 145 of guest operating systems, the default values of Hercules's internal thread 146 priorities for the Windows version of Hercules were changed to be identical 147 to those used by all other supported platforms. Originally, the default 148 thread priority values for the Windows version of Hercules were: 149 150 *** 3.04 (and prior) Default Priorities *** 151 152 Thread Priority Meaning 153 ------- -------- ------------------------ 154 HERCPRIO 0 Normal Process priority 155 156 DEVPRIO -8 Above Normal Thread priority 157 TODPRIO 0 Normal Thread priority 158 CPUPRIO 0 Normal Thread priority 159 160 which caused acceptable performance/functioning on most, but not all, guest 161 operating systems. Beginning with version 3.05 however, the prioriries now 162 default to: 163 164 *** 3.05 (and later) Default Priorities *** 165 166 Thread Priority Meaning 167 ------- -------- ------------------------ 168 HERCPRIO 0 Normal Process priority 169 170 TODPRIO -20 Time Critical Thread priority 171 DEVPRIO 8 Below Normal Thread priority 172 CPUPRIO 15 Lowest Thread priority 173 174 which may on more modern guest operating systems (which handle the TOD clock 175 differently than do older less sophticated versions) cause a slight decrease 176 in overall performance. If such is the case, the original default priorities 177 (and thus the original behavior) can be obtained via addition of appropriate 178 HERCPRIO, TODPRIO, DEVPRIO and CPUPRIO control file statements with values 179 identical to the original version 3.04 default values. 180 181 182* Additional configuration file usability enhancements have been implemented 183 in the form of a new 'INCLUDE' (and associated 'IGNORE') statement, allowing 184 configuration files to "include" statements from a different named file. 185 186 Additonally, a new "enhanced" symbolic substitution syntax is now also 187 supported. Refer to the Hercules "Configuration File" documentation for 188 further information and details. 189 190 A rather nifty "Automatic Operator" facility has also been implemented in 191 the current release as well. While not exactly a "configuration file 192 usability enhancement", it is nevertheless something we hope might prove 193 to be more useful/helpful to our many users. See the "README.HAO" document 194 for more information. 195 196------------------------------------------------------------------------------- 197 198 199 Version 3.01 RELEASE NOTES 200 201 202- Support for z990 crypto instructions is conditional on the presence of the 203 glibcrypt library. 204 205 If Hercules is BUILT, the development files for glibcrypt should be available. 206 207 When hercules is RUN, the runtime files for glibcrypt should be installed. 208 209 Depending on the level of glibcrypt used to *build* hercules, the associated 210 level of glibcrypt should also be present on the target machine. On systems 211 supporting shared library versioning, multiple levels of the glibcrypt 212 runtime libraries can be installed simultaneously, ensuring availability 213 of the z990 crypto instructions, regardless of the level of glibcrypt with 214 which hercules was initially built. 215 216 217- CTC and LCS devices now ++MUST++ specify ALL addresses on the configuration 218 statement. 219 220 Example: 221 222 0A00.2 LCS ..... 223 0B00.2 CTCI .... 224 225 or 226 227 0A00.4 LCS -oat hercules.oat 228 229 or 230 231 0A00-0A03 LCS -oat hercules.oat 232 233 or 234 235 0A00 LCS -oat hercules.oat 236 0A01 LCS 237 0A02 LCS 238 0A03 LCS 239 240 Previously (i.e. with version 3.00), only the first (even numbered) device 241 needed to be defined and Herc would automatically define the odd numbered 242 device for you. Starting with Hercules version 3.01 however, you now need 243 to define BOTH devices, just like you did with versions prior to 3.00. 244 245 Once again, starting with version 3.01, you **MUST** define BOTH DEVICES. 246 247------------------------------------------------------------------------------- 248 249 250 Version 3.00 RELEASE NOTES 251 252 253- Reminder that CTCI device handling was changed as follows: 254 255 - The CTCI-W32 protocol is deprecated. You should use the CTCI protocol 256 instead. 257 258 - You MUST NOT define both even/odd CTCI device pairs in your configuration 259 file. You should ONLY define the first even numbered device. Hercules will 260 automatically define the odd numbered device for you. If you define the 261 odd numbered device by mistake, an open error will occur on that device. 262 This is by design. See the README.NETWORKING document for further details. 263 264 265- Hercules Dynamic Loader support: starting with version 3.00, Hercules now 266 contains support for the dynamic loading of certain modules upon startup on 267 some platforms (e.g. Linux and Windows for example). As a result of this new 268 feature, "Hercules" itself now no longer consists of just the 'hercules.exe' 269 module by itself, but rather consists of BOTH the 'hercules.exe' program AS 270 WELL AS whatever dynamic modules (DLLs) that accompany it. 271 272 As a result if this change, whenever you install a new version of Hercules, 273 you must ensure that you ALSO install the accompanying new versions of the 274 new dynamic modules as well. Attempting to use a version of Hercules with a 275 dynamic module that was not specifically built for that version will cause 276 loading of that dynamic module to fail. 277 278 You CANNOT mix versions of Hercules with differing versions of dynamically 279 loaded modules. 280 281 Ensure that your library path LD_LIBRARY_PATH is set correctly such that it 282 includes the directory of your Hercules executables. Especially, message 283 HHCCF042E will indicate that system is unable to locate necessary loadable 284 modules. 285 286 287- ECPS:VM: Do not use ECPS:VM (See README.ECPSVM) in an AP or MP environment 288 in VM/370. If AP=YES or MP=YES is coded in DMKSYS and the AP/MP control 289 file is used to build the CP nucleus and NUMCPU is set to more than 1 in 290 the hercules.cnf file, any of LOK001, LOK003 or other abends will occur. 291 This occurs because the Hercules ECPS:VM CP Assist implementation is not 292 MP safe, and particularily, attemps VM dispatching without holding necessary 293 AP or MP locks. 294 295 296- Due to the change in Hercules' "mainstor" memory allocation technique to 297 address a "double memory consumption" bug in Cygwin's malloc implementation, 298 some Windows Hercules users may experience an "out of memory" error whenever 299 Hercules is started with a large MAINSIZE configuration file value: 300 301 "HHCCF031S Cannot obtain nnnMB main storage" 302 303 This error will most likely occur (if it does at all) for those users who 304 have manually adjusted their Cygwin "heap_chunk_in_mb" Windows registry 305 setting value (in order to allow them to specify a large MAINSIZE value 306 when running Hercules). If this problem does occur (i.e. if you DO happen 307 to experience the above mentioned "HHCCF031S Cannot obtain main storage" 308 error with this new release of Hercules), then either REDUCE your "heap_ 309 chunk_in_mb" value (yes, that's correct: REDUCE it; i.e. change it to a 310 SMALLER value) or else remove it altogether (so as to let it default). 311 312 Detailed explanation: 313 314 History/background: Cygwin has a built-in limit to the amount of memory 315 that may be allocated in one chunk. If you try 'malloc'ing more than this 316 limit, you will receive an "out of memory" error. Since many Hercules users 317 specify large MAINSIZE values in their configuration file, they sometimes 318 experience this problem. 319 320 The suggested workaround to this "problem" was to add a "heap_chunk_in_mb" 321 registry value to Cygwin's registry settings with a large enough value such 322 that Cygwin would then be able to satisfy Hercules' 'malloc' request for 323 such a large MAINSIZE value. 324 325 This worked fine until sometime around version 1.3.15 of Cygwin, at which 326 time they began using a different 'malloc' technique that unfortunately 327 causes TWICE as much Windows virtual memory to be allocated for any large 328 memory allocation (the technical reasons of which are explained in comments 329 in source member config.c where mainsize is being allocated). 330 331 In order to address this double memory allocation issue in Cygwin's malloc 332 implementation, Hercules was changed to use mmap to allocate its mainstor 333 rather than malloc (which, unlike malloc, does NOT inadvertently allocate 334 twice as Windows virtual storage than was requested), which did indeed re- 335 solve the "double memory allocation" problem. 336 337 Unfortunately however, because Cygwin's malloc and mmap logic each consume 338 completely different portions of Windows' virtual memory, the more memory 339 that is reserved for malloc usage (via using a larger "heap_chunk_in_mb" 340 value), the LESS becomes available for mmap usage! 341 342 Thus, while increasing your "heap_chunk_in_mb" registry value USED to HELP 343 [to allow you to allocate larger amounts of mainstor (MAINSIZE)], it NOW 344 causes the complete OPPOSITE effect: it ends up PREVENTING you from being 345 able to 'mmap' as much storage as you'd like to have! 346 347 Conclusion: 348 349 Therefore, if you are currently using the "heap_chunk_in_mb" registry value 350 setting to allow you to allocate large MAINSIZE values, then starting with 351 version 3.00 of Hercules you need to DESCREASE your "heap_chunk_in_mb" value 352 (or remove it altogether and let it default) in order to leave enough memory 353 remaining for Hercules (Cygwin actually) to be able to satisfy its 'mmap' 354 request for your desired MAINSIZE amount. 355 356------------------------------------------------------------------------------- 357