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
1Thank you for trying this port of UNZIP for VM/CMS and MVS!
2
3 Using under MVS:
4 -------------------------
5
61. To use the Info-ZIP's UNZIP under MVS you need:
7
8 - C/370 ver 2.1 compiler or another compatible compiler supporting
9 long names for function/variable names.
10
112. To compile the program under MVS do :
12
13 - unzip all the files from unz54vm.zip file. They are stored as
14 ASCII format so you have to unzip them first on PC or other
15 system that already have UNZIP, and then upload them to the
16 mainframe with ASCII to EBCDIC conversion.
17
18 - Copy all the .C files in the PDS called USERID.UNZIP.C
19
20 - Copy all the .H files in the PDS called USERID.UNZIP.H
21
22 - adjust the job UNZMVSC.JOB to work on your site. Change USERID
23 to your userid. You might need to change the CEE dataset names
24 to match your OS/390 system.
25
26 - Preallocate PDS datasets named: USERID.UNZIP.OBJ and
27 USERID.UNZIP.LOAD
28
29 - execute the job UNZMVSC to compile and link all the sources.
30
31 - if everything is ok you will get an UNZIP MODULE
32
333. Using UNZIP
34
35 - Just read the UNZIP.TXT
36
37 - A few exceptions concerning MVS
38
39 3.0. There are different ways to invoke UNZIP.
40
41 - allocating UNZIP.LOAD dataset to your ISPLLIB if you
42 want to invoke UNZIP under ISPF.
43 Then just type UNZIP ...parms... to get it work
44
45 - You can also call it directly with :
46 TSO CALL 'userid.UNZIP.LOAD(UNZIP)' '...parms...'
47 (notice to quotes!)
48
49 - You can even call it from a batch job like:
50
51 //MYZIP JOB (account)
52 //STEP1 EXEC PGM=UNZIP,PARM='-l mytestz.zip *.c'
53 //STEPLIB DD DSN=userid.UNZIP.LOAD,DISP=SHR
54 //SYSPRINT DD SYSOUT=*
55
56 This will list all the .c files from the zip file mytestz.zip
57
58 3.1. If the ZIP file has been zipped on an ASCII based system
59 it will be automatically translated to EBCDIC
60 ( I hope I got all those translation tables OK :-).
61 You can force ASCII to EBCDIC conversion with the -a flag.
62
63 3.2. The date/time of the output files is set to the
64 current system date/time - not according the date/time in
65 the zip file.
66
67 3.3. You can even unzip using TSO/E PIPELINES
68 so unzip can be used as pipeline filter:
69
70 'pipe cms unzip -p test.zip george.test | count lines | cons'
71 ( we do also a lot of pipethinking here ;-)
72
73 3.4. If you got also the ZIP program (see ZIP21VM.ZIP) you can
74 do zipping and unzipping without translating to ASCII
75 the ZIP also preserves the file informations (LRECL,BLKSIZE..)
76 So when you UNZIP a file zipped with ZIP under MVS it
77 restores the file info.
78
79 There currently some problems with file with RECFM=V*
80 I don't save the length of each record yet :-)
81
82 3.5. No wildcards are supported in the input zip name you have
83 to give the real name (.zip is not necessary)
84
85 So you CAN'T use things like: unzip -t *.zip
86
87 3.6. But you CAN use wildcards as filename selection like:
88 unzip -t myzip *.c - OK or even
89 unzip -t myzip *.c -x z*.c - to exclude all files matching
90 z*.c
91
92 3.7. You can unzip to a PDS using the -d parameter,
93 for example:
94
95 unzip -dmyzip myzip *.c
96
97 This will unzip all .c files that are in the zip file in a
98 PDS directory called MYZIP.C
99
100 BE AWARE that the extension of every files is being placed as
101 last identifier on the PDS name, so if you have a file in the
102 zipfile called 'testp.doc' and you use '-d mypds' the PDS
103 name will become 'mypds.doc(testp)'
104
105 Depending on which options IBM chose for C this week, unzip
106 may or may not prefix output files with your userid and/or
107 TSO prefix. To prevent this, quote the filename to -d, for
108 example
109
110 //UNZIP EXEC PGM=UNZIP,
111 // PARM='/-a -o ''userid.zip'' -d ''hlq.test'' *'
112 //STEPLIB DD DSN=USERID.UNZIP.LOAD,DISP=SHR
113 //SYSPRINT DD SYSOUT=*
114 //SYSOUT DD SYSOUT=*
115
116 The above JCL converts from ASCII to EBCDIC (-a), always
117 overwrites existing members (-o), extracts from 'userid.zip',
118 writes to files starting with 'hlq.test', all members (*).
119 Note the double quotes because PARM= requires single quotes.
120
121 3.8. The rules for output DCBs are a little messy. If the output
122 file already exists (remember the -d option) then unzip uses
123 the existing DCB and space values.
124
125 If the output file does not exist and the input zip came from
126 MVS then unzip makes its best attempt at preserving the
127 original DCB. However there is not enough information stored
128 in the zip file to do this correctly for all file types, some
129 file types may be corrupted.
130
131 If the output file does not exist and the input zip does not
132 contain MVS DCB information then unzip uses RECFM=U,
133 LRECL=32760 for binary data, RECFM=V, LRECL=133 for text.
134 Text includes ASCII to EBCDIC conversion. As soon as the
135 output file is created, unzip uses the same output DCB for
136 all following members, even if the input is a mixture of text
137 and binary.
138
139 In all cases, unzip has no built in parameters for space.
140 For a preallocated file this is not a problem. If unzip
141 creates an output file you get a default space allocation
142 which is site dependent.
143
144 It is far better to preallocate the output files with the
145 correct space and DCB values then use the -d option to point
146 to those files.
147
148 3.9. All '+','_' or '-' signs are skipped from the filenames
149
150
151Please repport all bugs and problems to :
152 Zip-Bugs@lists.wku.edu
153
154That's all for now.
155
156Have fun!
157
158
159George Petrov
160e-mail: c888090@nlevdpsb.snads.philips.nl
161tel: +31-40-781155
162
163Philips C&P
164Eindhoven
165The Netherlands
166
167Updated by:
168
169Keith Owens <kaos@ocs.com.au>
170