1Using ZIP and UNZIP on VM/CMS 2============================= 3 4 5Installing executables 6---------------------- 7 8The following CMS MODULEs are available: 9 ZIP 10 ZIPNOTE 11 ZIPCLOAK 12 ZIPSPLIT 13 UNZIP 14 15In addition to these, each MODULE file also has an EXEC with the same 16name. These EXECs are front-ends to the MODULES that will attempt to 17set up the required runtime libraries before running the MODULE. 18All the EXECs are identical. Only their names are different. 19They are stored as plain text files. 20 21The CMS MODULE files have been packed using the COPYFILE command to 22allow their file format to be properly restored, since variable length 23binary files will not currently unzip properly (see below for details). 24The MODULEs are shipped with a filetype or extension of CMO (for CMS 25MODULE). Their names may vary on the distribution disk to indicate 26their level, etc. 27 28To restore them to executable MODULEs on CMS, do the following: 29 1. Upload them to CMS with a Fixed record length with LRECL 1024. 30 Example, from a DOS or OS/2 window, type this: 31 SEND unzip.cmo A:unzip module a (RECFM F LRECL 1024 32 33 Example, using FTP from CMS, type this: 34 BINARY FIXED 1024 35 GET unzip.cmo unzip.module.a 36 37 Note: Replace "unzip.cmo" with the actual name. 38 39 2. Use COPYFILE to unpack the file. 40 Example, in CMS type this: 41 COPYFILE UNZIP MODULE A (UNPACK REPLACE OLDDATE 42 43 3. Repeat steps 1-2 for each of the programs. 44 45 4. Build the ZIPINFO module by typing this: 46 COPYFILE UNZIP MODULE A ZIPINFO MODULE A (OLDDATE 47 48 5. Upload the EXECs to CMS as text files (with ASCII-to-EBCDIC 49 translation). 50 Example, from a DOS or OS/2 window, type this: 51 SEND unzip.exc A:unzip exec a (CRLF 52 53 Example, using FTP from CMS, type this: 54 GET unzip.exc unzip.exec.a 55 56 6. Repeat steps 4 for each of the EXECs. 57 58 59Preparing the environment 60------------------------- 61 62The executables provided were compiled with IBM C 3.1.0 and 63require the the Language Environment (LE) runtime libraries. 64 65To provide access to the runtime libraries: 66 1. Link to the disk containing the Language Environment files, 67 if necessary. 68 69 2. Use the command "GLOBAL LOADLIB SCEERUN" 70 71 These commands can be placed in your PROFILE EXEC. 72 73 Note: EXECs have been provided called ZIP, UNZIP, etc. that 74 issue the GLOBAL LOADLIB statement. This was done to alleviate 75 frustration of users that don't have the GLOBAL LOADLIB statement 76 in their PROFILE EXEC. These EXECs may require changing for 77 your system. 78 79 Unfortunately, there is no way, using IBM C, to produce a MODULE 80 that doesn't require a runtime library. 81 82 83Testing 84------- 85 86To test the MODULEs, just type ZIP or UNZIP. They should 87show help information on using the commands. 88 89If you see something like this: 90 DMSLIO201W The following names are undefined: 91 CEEEV003 92 DMSABE155T User abend 4093 called from 00DCD298 reason code 000003EB 93 94Then you don't have access to the proper runtime libraries, as 95described above. 96 97Here is additional information on the ZIP and UNZIP programs that 98may assist support personnel: 99 - Compiled with IBM C V3R1M0 on VM/ESA 2.2.0 with 100 CMS level 13 Service Level 702. 101 102 - Require the SCEERUN LOADLIB runtime library. This is 103 part of the Language Environment (LE). 104 105 - Linked with options RMODE ANY AMODE ANY RLDSAVE. 106 107If you continue to have trouble, report the problem to Zip-Bugs 108(see the bottom of this document). 109 110 111 112Compiling the source on VM/CMS 113------------------------------ 114 115The source has been successfully compiled previously using 116C/370 2.1 and 2.2. The source has been recently compiled using 117IBM C 3.1.0 on VM/ESA 2.2.0 with CMS level 13. I don't have 118access to an MVS system so the code hasn't been tested there 119in a while. 120 121 1. Unzip the source files required for CMS. The root-level files 122 inside the ZIP file and the files in the CMSMVS subdirectory are 123 needed. Example (use both commands): 124 unzip -aj zip23.zip -x */* -dc 125 unzip -aj zip23.zip cmsmvs/* -dc 126 127 This example unzips the files to the C-disk, while translating 128 character data and ignoring paths. 129 130 If you don't already have a working UNZIP MODULE on CMS you will 131 have to unzip the files on another system and transport them 132 to CMS. All the required files are plain text so they can 133 be transferred with ASCII-to-EBCDIC translations. 134 135 2. Repeat step 1 with the zip file containing the UNZIP code. 136 Unzip the files to a different disk than the disk used for the ZIP 137 code. 138 139 3. To compile the ZIP code, run the supplied CCZIP EXEC. 140 To compile the UNZIP code, run the supplied CCUNZIP EXEC. 141 142NOTE: 143Some of the ZIP and UNZIP source files have the same name. It is 144recommended that you keep the source from each on separate disks and 145move the disk you are building from ahead of the other in the search 146order. 147 148For example, you may have a 192 disk with the ZIP source code and 149a 193 disk with the UNZIP source code. To compile ZIP, access 150the 192 disk as B, then run CCZIP. This will create the following 151modules: ZIP, ZIPNOTE, ZIPSPLIT, ZIPCLOAK. 152 153To compile UNZIP, access 193 as B, then run CCUNZIP. This will create 154the following modules: UNZIP, ZIPINFO (a copy of UNZIP). 155 156 157========================================================================= 158 159 160Using ZIP/UNZIP 161--------------- 162 163Documentation for the commands is in MANUAL NONAME (for ZIP) and in 164UNZIP DOC UNZIP. INFOZIP DOC describes the use of the -Z option of 165UNZIP. 166 167The rest of this section explains special notes concerning the VM/CMS 168version of ZIP and UNZIP. 169 170 171Filenames and directories 172------------------------- 173 174 1. Specifying filenames 175 176 a. When specifying CMS files, use filename.filetype.filemode format 177 (separate the three parts of the name with a period and use no 178 spaces). Example: profile.exec.a 179 180 Unfortunately, this prevents you from using ZIP from 181 FILELIST. To unzip a zip file, however, you can type something 182 like this next to it in FILELIST: 183 unzip /n -d c 184 185 This will unzip the contents of the current file to a C-disk. 186 187 b. It is possible to use DD names with ZIP and UNZIP on CMS, though 188 it can be cumbersome. Example: 189 filedef out disk myzip zip a 190 zip dd:out file1.txt file2.txt 191 192 While you can also use a DD name for the input files, ZIP 193 currently does not correctly resolve the filename and will 194 store something like "dd:in" inside the ZIP file. A file stored 195 in this manor cannot easily be unzipped, as "dd:in" is an invalid 196 filename. 197 198 c. In places where a directory name would be used on a PC, such as 199 for the ZIP -b (work path) option or the UNZIP -d (destination 200 path) options, use a filemode letter for CMS. For example, 201 to unzip files onto a C-disk, you might type something like this: 202 unzip myzip.zip -d c 203 204 Currently, ZIP uses the A-disk for work files. When zipping 205 large files, you may want to specify a larger disk for work files. 206 This example will use a C-disk for work files. 207 zip -b C myzip.zip.c test.dat.a 208 209 210 2. Filename conversions 211 212 a. Filemode letters are never stored into the zip file or take from 213 a zip file. Only the filename and filetype are used. 214 ZIP removes the filemode when storing the filename into the 215 zip file. UNZIP assumes "A" for the filemode unless the -d 216 option is used. 217 218 b. When unzipping, any path names are removed from the fileid 219 and the last two period-separated words are used as the 220 filename and filetype. These are truncated to a maximum of 221 eight characters, if necessary. If the filetype (extension) 222 is missing, then UNZIP uses "NONAME" for the filetype. 223 Any '(' or ')' characters are removed from the fileid. 224 225 c. All files are created in upper-case. Files in mixed-case 226 cannot currently be stored into a ZIP file. 227 228 d. Shared File System (SFS) directories are not supported. 229 Files are always accessed by fn.ft.fm. To use an SFS disk, 230 Assign it a filemode, then it can be used. 231 232 233 3. Wildcards in file names 234 235 a. Wildcards are not supported in the zip filename. The full 236 filename of the zip file must be given (but the .zip is not 237 necessary). So, you can't do this: 238 unzip -t *.zip 239 240 b. Wildcards CAN be used with UNZIP to select (or exclude) files 241 inside a zip file. Examples: 242 unzip myzip *.c - Unzip all .c files. 243 unzip myzip *.c -x z*.c - Unzip all .c files but those 244 starting with Z. 245 246 c. Wildcards cannot currently be used to select files with ZIP. 247 So, you can't do this: 248 zip -a myzip *.exec 249 250 I expect to fix this for CMS in the future. 251 252 253 4. File timestamps 254 255 a. The dates and times of files being zipped or unzipped are not 256 currently read or set. When a file is zipped, the timestamp 257 inside the zip file will always be the current system date and 258 time. Likewise, when unzipping, the date and time of files 259 being unzipped will always be the current system date/time. 260 261 b. Existing files are assumed to be newer than files inside a zip 262 file when using the -f freshen option of UNZIP. This will prevent 263 overwriting files that may be newer than the files inside the 264 zip file, but also effectively prevents the -f option from working. 265 266 267 5. ASCII, EBCDIC, and binary data 268 269 Background 270 ---------- 271 Most systems create data files as just a stream of bytes. Record 272 breaks happen when certain characters (new line and/or carriage 273 return characters) are encountered in the data. How to interpret 274 the data in a file is up to the user. The system must be told 275 to either notice new line characters in the data or to assume 276 that the data in the file is binary data and should be read or 277 written as-is. 278 279 CMS and MVS are record-based systems. All files are composed 280 of data records. These can be stored in fixed-length files or 281 in variable length files. With fixed-length files, each record 282 is the same length. The record breaks are implied by the 283 LRECL (logical record length) attribute associated with the file. 284 With variable-length files, each record contains the length of 285 that record. The separation of records are not part of the 286 data, but part of the file structure. 287 288 This means you can store any type of data in either type of file 289 structure without having to worry about the data being interpreted 290 as a record break. Fixed-length files may have padding at the 291 end of the file to make up a full record. Variable-length files 292 have no padding, but require extra record length data be stored 293 with the file data. 294 295 Storing fixed-length files into a zip file is simple, because all 296 the data can just be dumped into the zip file and the record 297 format (RECFM) and logical record length (LRECL) can be stored 298 in the extra data area of the zip file so they can be restored 299 when UNZIP is used. 300 301 Storing variable-length data is harder. There is no place to put 302 the record length data needed for each record of the file. This 303 data could be written to the zip file as the first two bytes of 304 each record and interpreted that way by UNZIP. That would make 305 the data unusable on systems other than CMS and MVS, though. 306 307 Currently, there isn't a solution to this problem. Each record is 308 written to the zip file and the record length information is 309 discarded. Binary data stored in variable-length files can't be put 310 into a zip file then later unzipped back into the proper records. 311 This is fine for binary data that will be read as a stream of bytes 312 but not OK where the records matter, such as with CMS MODULEs. 313 314 If the data is text (character data), there is a solution. 315 This data can be converted into ASCII when it's stored into 316 a zip file. The end of each record is now marked in the file 317 by new line characters. Another advantage of this method is 318 that the data is now accessible to non-EBCDIC systems. When 319 the data is unzipped on CMS or MVS, it is converted back into 320 EBCDIC and the records are recreated into a variable-length file. 321 322 323 So, here's what we have... 324 325 a. To store readable text data into a zip file that can be used 326 on other platforms, use the -a option with ZIP to convert the 327 data to ASCII. These files will unzip into variable-length 328 files on CMS and should not contain binary data or corruption 329 may occur. 330 331 b. Files that were zipped on an ASCII-based system will be 332 automatically translated to EBCDIC when unzipped. To prevent 333 this (to unzip binary data on CMS that was sent from an 334 ASCII-based system), use the -B option with UNZIP to force Binary 335 mode. To zip binary files on CMS, use the -B option with ZIP to 336 force Binary mode. This will prevent any data conversions from 337 taking place. 338 339 c. When using the ZIP program without specifying the "-a" or "-B" 340 option, ZIP defaults to "native" (EBCDIC) mode and tries to 341 preserve the file information (RECFM, LRECL, and BLKSIZE). So 342 when you unzip a file zipped with ZIP under CMS or MVS, UNZIP 343 restores the file info. The output will be fixed-length if the 344 original was fixed and variable-length if the original was 345 variable. 346 347 If UNZIP gives a "write error (disk full?)" message, you may be 348 trying to unzip a binary file that was zipped as a text file 349 (without using the -B option) 350 351 352 Summary 353 ------- 354 Here's how to ZIP the different types of files. 355 356 RECFM F text 357 Use the -a option with ZIP to convert to ASCII for use with other 358 platforms or no options for use on EBCDIC systems only. 359 360 RECFM V text 361 Use the -a option with ZIP to convert to ASCII for use with other 362 platforms or no options for use on EBCDIC systems only. 363 364 365 RECFM F binary 366 Use the -B option with ZIP (upper-case "B"). 367 368 RECFM V binary 369 Use the -B option with ZIP. Can be zipped OK but the record 370 structure is destroyed when unzipped. This is OK for data files 371 read as binary streams but not OK for files such as CMS MODULEs. 372 373 374 6. Character Sets 375 376 If you are used to running UNZIP on systems like UNIX, DOS, OS/2 or 377 Windows, you will may have some problems with differences in the 378 character set. 379 380 There are a number of different EBCDIC code pages, like there are a 381 number of different ASCII code pages. For example, there is a US 382 EBCDIC, a German EBCDIC, and a Swedish EBCDIC. As long as you are 383 working with other people who use the same EBCDIC code page, you 384 will have no trouble. If you work with people who use ASCII, or who 385 use a different EBCDIC code page, you may need to do some 386 translation. 387 388 UNZIP translates ASCII text files to and from Open Systems EBCDIC 389 (IBM-1047), which may not be the EBCDIC that you are using. For 390 example, US EBCDIC (IBM-037) uses different character codes for 391 square brackets. In such cases, you can use the ICONV utility 392 (supplied with IBM C) to translate between your EBCDIC character set 393 and IBM-1047. 394 395 If your installation does not use IBM-1047 EBCDIC, messages from 396 UNZIP may look a little odd. For example, in a US EBCDIC 397 installation, an opening square bracket will become an i-acute and a 398 closing square bracket will become a u-grave. 399 400 The supplied ZIP and UNZIP EXECs attempt to correct this by setting 401 CMS INPUT and OUTPUT translations to adjust the display of left and 402 right brackets. You may need to change this if brackets don't 403 display correctly on your system. 404 405 406 7. You can unzip using VM/CMS PIPELINES so unzip can be used as 407 a pipeline filter. Example: 408 'PIPE COMMAND UNZIP -p test.zip george.test | Count Lines | Cons' 409 410 411 412 413Please report all bugs and problems to: 414 Zip-Bugs@lists.wku.edu 415 416 417----------------------------------------------------------------------- 418Original CMS/MVS port by George Petrov. 419e-mail: c888090@nlevdpsb.snads.philips.nl 420tel: +31-40-781155 421 422Philips C&P 423Eindhoven 424The Netherlands 425 426----------------------------------------------------------------------- 427Additional fixes and README re-write (4/98) by Greg Hartwig. 428e-mail: ghartwig@ix.netcom.com 429 ghartwig@vnet.ibm.com 430 431----------------------------------------------------------------------- 432Additional notes from Ian E. Gorman. 433e-mail: ian@iosphere.net 434 435